@spec comprehensive_validation_report(
  validation_target(),
  validation_input(),
  enhanced_options()
) :: %{
  validation_result: validation_result(),
  enhanced_schema: map(),
  schema_analysis: %{
    computed_field_count: non_neg_integer(),
    field_count: non_neg_integer(),
    has_config: boolean(),
    model_validator_count: non_neg_integer(),
    struct_support: boolean()
  },
  provider_compatibility: map(),
  performance_metrics:
    %{
      validation_duration_microseconds: integer(),
      validation_duration_milliseconds: float(),
      memory_usage: non_neg_integer(),
      complexity_analysis: map()
    }
    | nil,
  dspy_analysis:
    %{signature_compatible: boolean(), recommendations: [binary()]} | nil,
  recommendations: [binary()],
  generated_at: DateTime.t()
}

Comprehensive validation report with enhanced schema analysis.

Phase 6 Enhancement: Complete integration testing and analysis.

Parameters

• target - What to validate against
• input - Data to validate
• opts - Enhanced validation options

Returns

• Comprehensive validation and schema analysis report

Examples

iex> report = Exdantic.EnhancedValidator.comprehensive_validation_report(
...>   MySchema,
...>   sample_data,
...>   test_providers: [:openai, :anthropic],
...>   include_performance_analysis: true
...> )
%{
  validation_result: {:ok, validated_data},
  enhanced_schema: %{...},
  provider_compatibility: %{...},
  performance_metrics: %{...},
  recommendations: [...]
}

@spec pipeline([term()], term(), enhanced_options()) ::
  {:ok, term()} | {:error, {integer(), [Exdantic.Error.t()]}}

Creates a basic validation pipeline for simple sequential validation.

Parameters

• steps - List of validation steps to execute in order
• input - The data to validate through the pipeline
• opts - Enhanced validation options

Returns

• {:ok, final_validated_data} if all steps succeed
• {:error, {step_index, errors}} if any step fails

Examples

iex> steps = [:string, fn s -> {:ok, String.upcase(s)} end, :string]
iex> Exdantic.EnhancedValidator.pipeline(steps, "hello", [])
{:ok, "HELLO"}

@spec validate(validation_target(), validation_input(), enhanced_options()) ::
  validation_result()

Universal validation function that handles all types of validation targets.

Parameters

• target - What to validate against (schema, type spec, etc.)
• input - The data to validate
• opts - Enhanced validation options

Options

• :config - Exdantic.Config for validation behavior
• :wrapper_field - Field name if using wrapper validation
• :json_schema_opts - Options for JSON schema operations
• :type_adapter_opts - Options for TypeAdapter operations

Returns

• {:ok, validated_data} on success
• {:error, errors} on validation failure

Examples

# Validate against a compiled schema
iex> Exdantic.EnhancedValidator.validate(MySchema, %{name: "John"})
{:ok, %{name: "John"}}

# Validate against a runtime schema
iex> schema = Exdantic.Runtime.create_schema([{:name, :string}])
iex> Exdantic.EnhancedValidator.validate(schema, %{name: "John"})
{:ok, %{name: "John"}}

# Validate against a type specification
iex> Exdantic.EnhancedValidator.validate({:array, :string}, ["a", "b"])
{:ok, ["a", "b"]}

# Validate with custom configuration
iex> config = Exdantic.Config.create(strict: true, coercion: :safe)
iex> Exdantic.EnhancedValidator.validate(:integer, "123", config: config)
{:ok, 123}

@spec validate_for_llm(
  validation_target(),
  validation_input(),
  atom(),
  enhanced_options()
) ::
  {:ok, term(), map()} | {:error, [Exdantic.Error.t()]}

Validates data for a specific LLM provider's structured output requirements.

Parameters

• target - What to validate against
• input - Data to validate
• provider - LLM provider (:openai, :anthropic, :generic)
• opts - Enhanced validation options

Returns

• {:ok, validated_data, provider_schema} on success
• {:error, errors} on validation failure

Examples

iex> Exdantic.EnhancedValidator.validate_for_llm(schema, data, :openai)
{:ok, validated_data, %{"type" => "object", "additionalProperties" => false}}

@spec validate_many(validation_target(), [validation_input()], enhanced_options()) ::
  {:ok, [term()]} | {:error, %{required(integer()) => [Exdantic.Error.t()]}}

Validates multiple values efficiently against the same target.

Parameters

• target - What to validate against
• inputs - List of data to validate
• opts - Enhanced validation options

Returns

• {:ok, validated_list} if all validations succeed
• {:error, errors_by_index} if any validation fails

Examples

iex> Exdantic.EnhancedValidator.validate_many(:string, ["a", "b", "c"])
{:ok, ["a", "b", "c"]}

iex> Exdantic.EnhancedValidator.validate_many(:integer, [1, "bad", 3])
{:error, %{1 => [%Exdantic.Error{...}]}}

@spec validate_with_enhanced_schema(
  validation_target(),
  validation_input(),
  enhanced_options()
) ::
  {:ok, term()} | {:ok, term(), map()} | {:error, [Exdantic.Error.t()]}

Validates data with enhanced JSON schema generation.

Phase 6 Enhancement: Integrates with EnhancedResolver for complete pipeline.

Parameters

• target - What to validate against
• input - Data to validate
• opts - Enhanced validation options

Phase 6 Options

• :generate_enhanced_schema - Include enhanced JSON schema in result (default: false)
• :optimize_for_provider - LLM provider optimization (default: :generic)
• :include_metadata - Include validation metadata in result (default: false)

Returns

• {:ok, validated_data} or {:ok, validated_data, enhanced_schema} on success
• {:error, errors} on validation failure

Examples

iex> Exdantic.EnhancedValidator.validate_with_enhanced_schema(
...>   MySchema,
...>   data,
...>   generate_enhanced_schema: true,
...>   optimize_for_provider: :openai
...> )
{:ok, validated_data, %{
  "type" => "object",
  "x-exdantic-enhanced" => true,
  "x-openai-optimized" => true,
  ...
}}

@spec validate_with_resolved_schema(
  validation_target(),
  validation_input(),
  enhanced_options()
) ::
  {:ok, term(), map()} | {:error, [Exdantic.Error.t()]}

Validates data and resolves all JSON schema references.

Parameters

• target - What to validate against
• input - Data to validate
• opts - Enhanced validation options

Returns

• {:ok, validated_data, resolved_schema} on success
• {:error, errors} on validation failure

Examples

iex> Exdantic.EnhancedValidator.validate_with_resolved_schema(MySchema, data)
{:ok, validated_data, %{"type" => "object", ...}}

@spec validate_with_schema(
  validation_target(),
  validation_input(),
  enhanced_options()
) ::
  {:ok, term(), map()} | {:error, [Exdantic.Error.t()]}

Validates data and generates a JSON schema for the validation target.

Parameters

• target - What to validate against
• input - Data to validate
• opts - Enhanced validation options

Returns

• {:ok, validated_data, json_schema} on success
• {:error, errors} on validation failure

Examples

iex> schema = Exdantic.Runtime.create_schema([{:name, :string}])
iex> Exdantic.EnhancedValidator.validate_with_schema(schema, %{name: "John"})
{:ok, %{name: "John"}, %{"type" => "object", ...}}

@spec validate_wrapped(
  atom(),
  Exdantic.TypeAdapter.type_spec(),
  term(),
  enhanced_options()
) ::
  {:error, [Exdantic.Error.t()]}

Validates data and wraps it in a temporary schema if needed.

Parameters

• field_name - Name for the wrapper field
• type_spec - Type specification for the field
• input - Data to validate
• opts - Enhanced validation options

Returns

• {:ok, extracted_value} on success
• {:error, errors} on validation failure

Examples

iex> Exdantic.EnhancedValidator.validate_wrapped(:result, :integer, "123",
...>   config: Exdantic.Config.create(coercion: :safe))
{:ok, 123}

iex> Exdantic.EnhancedValidator.validate_wrapped(:items, {:array, :string}, ["a", "b"])
{:ok, ["a", "b"]}

@spec validation_report(validation_target(), validation_input(), enhanced_options()) ::
  map()

Creates a comprehensive validation report for debugging purposes.

Parameters

• target - What to validate against
• input - Data to validate
• opts - Enhanced validation options

Returns

• Map with detailed validation information

Examples

iex> report = Exdantic.EnhancedValidator.validation_report(schema, data)
%{
  validation_result: {:ok, validated_data},
  json_schema: %{...},
  target_info: %{...},
  input_analysis: %{...},
  performance_metrics: %{...}
}