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

defmodule Dspy.SIMBA do
  @moduledoc """
  SIMBA (Stochastic Introspective Mini-Batch Ascent) optimizer for DSPy.

  SIMBA is a DSPy optimizer that uses the LLM to analyze its own performance and 
  generate improvement rules. It samples mini-batches, identifies challenging examples 
  with high output variability, then either creates self-reflective rules or adds 
  successful examples as demonstrations.

  For more details, see: https://dspy.ai/api/optimizers/SIMBA/
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "SIMBA"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Initializes SIMBA.



  ## Parameters

  - `metric` - A function that takes an Example and a prediction_dict as input and returns a float.
  - `bsize` - Mini-batch size. Defaults to 32.
  - `num_candidates` - Number of new candidate programs to produce per iteration. Defaults to 6.
  - `max_steps` - Number of optimization steps to run. Defaults to 8.
  - `max_demos` - Maximum number of demos a predictor can hold before dropping some. Defaults to 4.
  - `prompt_model` - The model to use to evolve the program. When `prompt_model is None`, the globally configured lm is used.
  - `teacher_settings` - Settings for the teacher model. Defaults to None.
  - `demo_input_field_maxlen` - Maximum number of characters to keep in an input field when building a new demo. Defaults to 100,000.
  - `num_threads` - Number of threads for parallel execution. Defaults to None.
  - `temperature_for_sampling` - Temperature used for picking programs during the trajectory-sampling step. Defaults to 0.2.
  - `temperature_for_candidates` - Temperature used for picking the source program for building new candidates. Defaults to 0.2.
  """
  @spec new(keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(opts \\ []) do
    kw_keys = opts |> Keyword.keys() |> Enum.map(&to_string/1)
    missing_kw = ["metric"] |> 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_class(__MODULE__, :__init__, [], opts)
  end

  @doc """
  Compile and optimize the student module using SIMBA.



  ## Parameters

  - `student` - The module to optimize
  - `trainset` - Training examples for optimization
  - `seed` - Random seed for reproducibility

  ## 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
end