# Generated by SnakeBridge v0.14.0 - DO NOT EDIT MANUALLY
# Regenerate with: mix compile
# Library: dspy 3.1.2
# Python module: dspy
# Python class: AvatarOptimizer

defmodule Dspy.AvatarOptimizer do
  @moduledoc """
  Wrapper for Python class AvatarOptimizer.
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "AvatarOptimizer"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Initialize self.  See help(type(self)) for accurate signature.

  ## Parameters

  - `metric` (term())
  - `max_iters` (integer() default: 10)
  - `lower_bound` (integer() default: 0)
  - `upper_bound` (integer() default: 1)
  - `max_positive_inputs` (term() default: None)
  - `max_negative_inputs` (term() default: None)
  - `optimize_for` (String.t() default: 'max')
  """
  @spec new(term(), list(term()), keyword()) ::
          {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(metric, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [metric] ++ List.wrap(args), opts)
  end

  @doc """
  Python method `AvatarOptimizer._get_pos_neg_results`.

  ## Parameters

  - `actor` (Dspy.Primitives.ModuleClass3.t())
  - `trainset` (list(Dspy.Primitives.ExampleClass.t()))

  ## Returns

  - `{float(), list(Dspy.Teleprompt.AvatarOptimizer.EvalResult.t()),
   list(Dspy.Teleprompt.AvatarOptimizer.EvalResult.t())}`
  """
  @spec _get_pos_neg_results(
          SnakeBridge.Ref.t(),
          Dspy.Primitives.ModuleClass3.t(),
          list(Dspy.Primitives.ExampleClass.t()),
          keyword()
        ) ::
          {:ok,
           {float(), list(Dspy.Teleprompt.AvatarOptimizer.EvalResult.t()),
            list(Dspy.Teleprompt.AvatarOptimizer.EvalResult.t())}}
          | {:error, Snakepit.Error.t()}
  def _get_pos_neg_results(ref, actor, trainset, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :_get_pos_neg_results, [actor, trainset], opts)
  end

  @doc """
  Optimize the student program.



  ## Parameters

  - `student` - The student program to optimize.
  - `trainset` - The training set to use for optimization.
  - `teacher` - The teacher program to use for optimization.
  - `valset` - The validation set to use for optimization.

  ## Returns

  - `term()`
  """
  @spec compile(SnakeBridge.Ref.t(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def compile(ref, student, opts \\ []) do
    kw_keys = opts |> Keyword.keys() |> Enum.map(&to_string/1)
    missing_kw = ["trainset"] |> Enum.reject(&(&1 in kw_keys))

    if missing_kw != [] do
      raise ArgumentError,
            "Missing required keyword-only arguments: " <> Enum.join(missing_kw, ", ")
    end

    SnakeBridge.Runtime.call_method(ref, :compile, [student], opts)
  end

  @doc """
  Get the parameters of the teleprompter.

  ## Returns

  - `%{optional(String.t()) => term()}`
  """
  @spec get_params(SnakeBridge.Ref.t(), keyword()) ::
          {:ok, %{optional(String.t()) => term()}} | {:error, Snakepit.Error.t()}
  def get_params(ref, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :get_params, [], opts)
  end

  @doc """
  Python method `AvatarOptimizer.process_example`.

  ## Parameters

  - `actor` (term())
  - `example` (term())
  - `return_outputs` (term())

  ## Returns

  - `term()`
  """
  @spec process_example(SnakeBridge.Ref.t(), term(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def process_example(ref, actor, example, return_outputs, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :process_example, [actor, example, return_outputs], opts)
  end

  @doc """
  Python method `AvatarOptimizer.thread_safe_evaluator`.

  ## Parameters

  - `devset` (term())
  - `actor` (term())
  - `return_outputs` (term() default: False)
  - `num_threads` (term() default: None)

  ## Returns

  - `term()`
  """
  @spec thread_safe_evaluator(SnakeBridge.Ref.t(), term(), term(), list(term()), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def thread_safe_evaluator(ref, devset, actor, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)

    SnakeBridge.Runtime.call_method(
      ref,
      :thread_safe_evaluator,
      [devset, actor] ++ List.wrap(args),
      opts
    )
  end
end