# Required API in lib/dspex/program.ex
@spec forward(t(), map()) :: {:ok, map()} | {:error, term()}
@spec forward(t(), map(), keyword()) :: {:ok, map()} | {:error, term()}

# Contract Requirements:
# 1. MUST return consistent format: {:ok, outputs} | {:error, reason}
# 2. MUST handle concurrent calls safely (no shared mutable state)
# 3. MUST preserve correlation_id through telemetry
# 4. MUST timeout predictably when given timeout option
# 5. outputs MUST be a map with atom keys matching signature output fields

# Required API additions to lib/dspex/program.ex

@spec program_type(t()) :: :predict | :optimized | :custom | :unknown
def program_type(program)

@spec safe_program_info(t()) :: %{
  type: atom(),
  name: atom(), 
  has_demos: boolean(),
  signature: atom() | nil
}
def safe_program_info(program)

@spec has_demos?(t()) :: boolean()  
def has_demos?(program)

def program_type(program) when is_struct(program) do
  case program.__struct__ |> Module.split() |> List.last() do
    "Predict" -> :predict
    "OptimizedProgram" -> :optimized  
    _ -> :custom
  end
end
def program_type(_), do: :unknown

def safe_program_info(program) when is_struct(program) do
  %{
    type: program_type(program),
    name: program_name(program),
    has_demos: has_demos?(program),
    signature: get_signature_module(program)
  }
end

def has_demos?(program) when is_struct(program) do
  cond do
    Map.has_key?(program, :demos) and is_list(program.demos) ->
      length(program.demos) > 0
    true -> false
  end
end

# Required API in lib/dspex/client.ex
@spec request([message()], map()) :: {:ok, response()} | {:error, error_reason()}

# Contract Requirements:
# 1. messages MUST be list of %{role: string, content: string}
# 2. options MUST support: %{provider: atom, correlation_id: string, timeout: integer}
# 3. response MUST have format: %{choices: [%{message: %{content: string}}]}
# 4. MUST preserve correlation_id in telemetry events
# 5. MUST handle provider switching gracefully

# Required error types in lib/dspex/client.ex
@type error_reason :: 
  :timeout | :network_error | :api_error | :rate_limited | 
  :invalid_messages | :provider_not_configured

# Contract Requirements:
# 1. MUST categorize errors consistently
# 2. MUST provide fallback mechanisms for instruction generation
# 3. MUST preserve correlation context through error paths

# Required API in lib/dspex/example.ex (ALREADY IMPLEMENTED ✅)
@spec new(map()) :: t()
@spec new(map(), [atom()]) :: t()  
@spec inputs(t()) :: map()
@spec outputs(t()) :: map()
@spec with_inputs(t(), [atom()]) :: t()

# Contract Requirements:
# 1. MUST maintain immutable data structure
# 2. inputs/1 and outputs/1 MUST return consistent field separation
# 3. new/2 MUST properly set input_keys for field separation
# 4. MUST handle serialization/deserialization for demo storage

# Required API in lib/dspex/optimized_program.ex

@spec new(struct(), [Example.t()], map()) :: t()
def new(program, demos, metadata \\ %{})

# Contract Requirements:  
# 1. MUST accept any program struct as first argument
# 2. MUST store demos and metadata without restrictions
# 3. MUST implement Program behavior correctly
# 4. metadata MUST support arbitrary SIMBA optimization data
# 5. MUST preserve original program functionality

# Required detection logic for SIMBA optimization strategy
def supports_native_demos?(program) when is_struct(program) do
  Map.has_key?(program, :demos)
end

def supports_native_instruction?(program) when is_struct(program) do  
  Map.has_key?(program, :instruction)
end

# SIMBA Usage Pattern:
case student do
  %{demos: _, instruction: _} ->
    # Native support - direct field assignment
    %{student | demos: best_demos, instruction: best_instruction}
  %{demos: _} ->  
    # Partial support - demos only
    %{student | demos: best_demos}
  _ ->
    # No native support - wrap with OptimizedProgram
    OptimizedProgram.new(student, best_demos, %{instruction: best_instruction})
end

# Required API in lib/dspex/services/config_manager.ex

@spec get_with_default([atom()], term()) :: term()
def get_with_default(path, default)

# Critical SIMBA Usage:
default_provider = ConfigManager.get_with_default([:prediction, :default_provider], :gemini)

# Contract Requirements:
# 1. MUST return valid provider atoms (:gemini, :openai, etc.)
# 2. MUST handle graceful fallback when Foundation config unavailable  
# 3. MUST support nested path access like [:prediction, :default_provider]
# 4. MUST work during SIMBA initialization without blocking

# Required telemetry events that SIMBA depends on
[:dspex, :program, :forward, :start]
[:dspex, :program, :forward, :stop]  
[:dspex, :client, :request, :start]
[:dspex, :client, :request, :stop]
[:dspex, :teleprompter, :bootstrap, :start]
[:dspex, :teleprompter, :bootstrap, :stop]

# Contract Requirements:
# 1. MUST include correlation_id in all event metadata
# 2. MUST include consistent measurement structure (duration, success)
# 3. MUST handle Foundation integration without crashes
# 4. MUST work during SIMBA optimization loops

# Required API in lib/dspex/teleprompter/bootstrap_fewshot.ex
@behaviour DSPEx.Teleprompter

@spec compile(t(), struct(), [Example.t()], function(), keyword()) :: 
  {:ok, struct()} | {:error, term()}

# Contract Requirements:
# 1. MUST handle empty demonstration results gracefully
# 2. MUST support custom metric functions safely  
# 3. MUST provide meaningful progress callbacks
# 4. MUST work with concurrent teacher program execution
# 5. MUST return OptimizedProgram with proper metadata

# SIMBA needs this interface for instruction candidates
case DSPEx.Client.request(messages, %{provider: model, correlation_id: correlation_id}) do
  {:ok, response} ->
    instruction = response.choices
                  |> List.first()  
                  |> get_in([Access.key(:message), Access.key(:content)])
                  |> String.trim()
    {:ok, instruction}
  {:error, reason} -> {:error, reason}
end

# SIMBA creates trial programs and evaluates them
trial_program = create_trial_program(student, instruction_candidate, demo_candidates)

# Must work reliably:
case Program.forward(trial_program, inputs) do
  {:ok, prediction} -> metric_fn.(example, prediction)
  {:error, _} -> 0.0  # Graceful degradation
end

defmodule DSPEx.SIMBAContractTest do
  # Test that validates the exact APIs SIMBA depends on
  
  test "Program.forward/3 contract compliance" do
    program = create_test_program()
    inputs = %{question: "test"}
    
    # Test basic contract
    assert {:ok, outputs} = Program.forward(program, inputs)
    assert is_map(outputs)
    assert Map.has_key?(outputs, :answer)
    
    # Test options contract  
    opts = [correlation_id: "test-123", timeout: 5000]
    assert {:ok, outputs} = Program.forward(program, inputs, opts)
    
    # Test error contract
    assert {:error, reason} = Program.forward(nil, inputs)
    assert is_atom(reason)
  end
  
  test "SIMBA instruction generation contract" do
    messages = [%{role: "user", content: "Generate instruction"}]
    opts = %{provider: :gemini, correlation_id: "test-456"}
    
    case Client.request(messages, opts) do
      {:ok, response} ->
        # Validate response structure SIMBA expects
        assert %{choices: choices} = response
        assert is_list(choices)
        assert [%{message: %{content: content}} | _] = choices
        assert is_binary(content)
        
      {:error, reason} ->
        # Validate error handling SIMBA expects
        assert reason in [:timeout, :network_error, :api_error, :rate_limited]
    end
  end
end

defmodule DSPEx.SIMBAIntegrationSmokeTest do
  test "minimal SIMBA workflow compatibility" do
    # This test validates the essential SIMBA workflow
    student = create_simple_student()
    teacher = create_simple_teacher()  
    trainset = create_minimal_trainset()
    metric_fn = &simple_metric/2
    
    # Test bootstrap generation (simplified)
    assert {:ok, demos} = generate_bootstrap_demos(teacher, trainset)
    assert length(demos) > 0
    
    # Test instruction generation  
    assert {:ok, instruction} = generate_test_instruction(student, trainset)
    assert is_binary(instruction)
    
    # Test program enhancement
    enhanced = enhance_program(student, demos, instruction)
    assert is_struct(enhanced)
    
    # Test enhanced program execution
    assert {:ok, result} = Program.forward(enhanced, %{question: "test"})
    assert Map.has_key?(result, :answer)
  end
end