dspex

# Generated by SnakeBridge v0.16.0 - DO NOT EDIT MANUALLY
# Regenerate with: mix compile
# Library: dspy 3.2.0
# Python module: dspy
# Python class: MIPROv2

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

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

  ## Parameters

  - `metric` (term())
  - `prompt_model` (term() default: None)
  - `task_model` (term() default: None)
  - `teacher_settings` (term() default: None)
  - `max_bootstrapped_demos` (integer() default: 4)
  - `max_labeled_demos` (integer() default: 4)
  - `auto` (term() | nil default: 'light')
  - `num_candidates` (term() default: None)
  - `num_threads` (term() default: None)
  - `max_errors` (term() default: None)
  - `seed` (integer() default: 9)
  - `init_temperature` (float() default: 1.0)
  - `verbose` (boolean() default: False)
  - `track_stats` (boolean() default: True)
  - `log_dir` (term() default: None)
  - `metric_threshold` (term() default: None)
  """
  @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 `MIPROv2._bootstrap_fewshot_examples`.

  ## Parameters

  - `program` (term())
  - `trainset` (list(term()))
  - `seed` (integer())
  - `teacher` (term())
  - `num_fewshot_candidates` (integer() keyword-only, required)
  - `max_bootstrapped_demos` (integer() keyword-only, required)
  - `max_labeled_demos` (integer() keyword-only, required)
  - `max_errors` (term() keyword-only, required)
  - `metric_threshold` (term() keyword-only, required)

  ## Returns

  - `term()`
  """
  @spec _bootstrap_fewshot_examples(
          SnakeBridge.Ref.t(),
          term(),
          list(term()),
          integer(),
          term(),
          keyword()
        ) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _bootstrap_fewshot_examples(ref, program, trainset, seed, teacher, opts \\ []) do
    kw_keys = opts |> Keyword.keys() |> Enum.map(&to_string/1)

    missing_kw =
      [
        "num_fewshot_candidates",
        "max_bootstrapped_demos",
        "max_labeled_demos",
        "max_errors",
        "metric_threshold"
      ]
      |> 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,
      :_bootstrap_fewshot_examples,
      [program, trainset, seed, teacher],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._estimate_lm_calls`.

  ## Parameters

  - `program` (term())
  - `num_trials` (integer())
  - `minibatch` (boolean())
  - `minibatch_size` (integer())
  - `minibatch_full_eval_steps` (integer())
  - `valset` (list(term()))
  - `program_aware_proposer` (boolean())
  - `num_instruct_candidates` (integer())

  ## Returns

  - `{String.t(), String.t()}`
  """
  @spec _estimate_lm_calls(
          SnakeBridge.Ref.t(),
          term(),
          integer(),
          boolean(),
          integer(),
          integer(),
          list(term()),
          boolean(),
          integer(),
          keyword()
        ) :: {:ok, {String.t(), String.t()}} | {:error, Snakepit.Error.t()}
  def _estimate_lm_calls(
        ref,
        program,
        num_trials,
        minibatch,
        minibatch_size,
        minibatch_full_eval_steps,
        valset,
        program_aware_proposer,
        num_instruct_candidates,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_estimate_lm_calls,
      [
        program,
        num_trials,
        minibatch,
        minibatch_size,
        minibatch_full_eval_steps,
        valset,
        program_aware_proposer,
        num_instruct_candidates
      ],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._get_param_distributions`.

  ## Parameters

  - `program` (term())
  - `instruction_candidates` (term())
  - `demo_candidates` (term())

  ## Returns

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

  @doc """
  Python method `MIPROv2._log_minibatch_eval`.

  ## Parameters

  - `score` (term())
  - `best_score` (term())
  - `batch_size` (term())
  - `chosen_params` (term())
  - `score_data` (term())
  - `trial` (term())
  - `adjusted_num_trials` (term())
  - `trial_logs` (term())
  - `trial_num` (term())
  - `candidate_program` (term())
  - `total_eval_calls` (term())

  ## Returns

  - `term()`
  """
  @spec _log_minibatch_eval(
          SnakeBridge.Ref.t(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          keyword()
        ) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _log_minibatch_eval(
        ref,
        score,
        best_score,
        batch_size,
        chosen_params,
        score_data,
        trial,
        adjusted_num_trials,
        trial_logs,
        trial_num,
        candidate_program,
        total_eval_calls,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_log_minibatch_eval,
      [
        score,
        best_score,
        batch_size,
        chosen_params,
        score_data,
        trial,
        adjusted_num_trials,
        trial_logs,
        trial_num,
        candidate_program,
        total_eval_calls
      ],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._log_normal_eval`.

  ## Parameters

  - `score` (term())
  - `best_score` (term())
  - `chosen_params` (term())
  - `score_data` (term())
  - `trial` (term())
  - `num_trials` (term())
  - `trial_logs` (term())
  - `trial_num` (term())
  - `valset` (term())
  - `batch_size` (term())
  - `candidate_program` (term())
  - `total_eval_calls` (term())

  ## Returns

  - `term()`
  """
  @spec _log_normal_eval(
          SnakeBridge.Ref.t(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          term(),
          keyword()
        ) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _log_normal_eval(
        ref,
        score,
        best_score,
        chosen_params,
        score_data,
        trial,
        num_trials,
        trial_logs,
        trial_num,
        valset,
        batch_size,
        candidate_program,
        total_eval_calls,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_log_normal_eval,
      [
        score,
        best_score,
        chosen_params,
        score_data,
        trial,
        num_trials,
        trial_logs,
        trial_num,
        valset,
        batch_size,
        candidate_program,
        total_eval_calls
      ],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._optimize_prompt_parameters`.

  ## Parameters

  - `program` (term())
  - `instruction_candidates` (%{optional(integer()) => list(String.t())})
  - `demo_candidates` (term())
  - `evaluate` (term())
  - `valset` (list(term()))
  - `num_trials` (integer())
  - `minibatch` (boolean())
  - `minibatch_size` (integer())
  - `minibatch_full_eval_steps` (integer())
  - `seed` (integer())

  ## Returns

  - `term()`
  """
  @spec _optimize_prompt_parameters(
          SnakeBridge.Ref.t(),
          term(),
          %{optional(integer()) => list(String.t())},
          term(),
          term(),
          list(term()),
          integer(),
          boolean(),
          integer(),
          integer(),
          integer(),
          keyword()
        ) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _optimize_prompt_parameters(
        ref,
        program,
        instruction_candidates,
        demo_candidates,
        evaluate,
        valset,
        num_trials,
        minibatch,
        minibatch_size,
        minibatch_full_eval_steps,
        seed,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_optimize_prompt_parameters,
      [
        program,
        instruction_candidates,
        demo_candidates,
        evaluate,
        valset,
        num_trials,
        minibatch,
        minibatch_size,
        minibatch_full_eval_steps,
        seed
      ],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._perform_full_evaluation`.

  ## Parameters

  - `trial_num` (integer())
  - `adjusted_num_trials` (integer())
  - `param_score_dict` (%{optional(term()) => term()})
  - `fully_evaled_param_combos` (%{optional(term()) => term()})
  - `evaluate` (term())
  - `valset` (list(term()))
  - `trial_logs` (%{optional(term()) => term()})
  - `total_eval_calls` (integer())
  - `score_data` (term())
  - `best_score` (float())
  - `best_program` (term())
  - `study` (term())
  - `instruction_candidates` (list(term()))
  - `demo_candidates` (list(term()))

  ## Returns

  - `term()`
  """
  @spec _perform_full_evaluation(
          SnakeBridge.Ref.t(),
          integer(),
          integer(),
          %{optional(term()) => term()},
          %{optional(term()) => term()},
          term(),
          list(term()),
          %{optional(term()) => term()},
          integer(),
          term(),
          float(),
          term(),
          term(),
          list(term()),
          list(term()),
          keyword()
        ) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _perform_full_evaluation(
        ref,
        trial_num,
        adjusted_num_trials,
        param_score_dict,
        fully_evaled_param_combos,
        evaluate,
        valset,
        trial_logs,
        total_eval_calls,
        score_data,
        best_score,
        best_program,
        study,
        instruction_candidates,
        demo_candidates,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_perform_full_evaluation,
      [
        trial_num,
        adjusted_num_trials,
        param_score_dict,
        fully_evaled_param_combos,
        evaluate,
        valset,
        trial_logs,
        total_eval_calls,
        score_data,
        best_score,
        best_program,
        study,
        instruction_candidates,
        demo_candidates
      ],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._print_auto_run_settings`.

  ## Parameters

  - `num_trials` (integer())
  - `minibatch` (boolean())
  - `valset` (list(term()))
  - `num_fewshot_candidates` (integer())
  - `num_instruct_candidates` (integer())

  ## Returns

  - `term()`
  """
  @spec _print_auto_run_settings(
          SnakeBridge.Ref.t(),
          integer(),
          boolean(),
          list(term()),
          integer(),
          integer(),
          keyword()
        ) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _print_auto_run_settings(
        ref,
        num_trials,
        minibatch,
        valset,
        num_fewshot_candidates,
        num_instruct_candidates,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_print_auto_run_settings,
      [num_trials, minibatch, valset, num_fewshot_candidates, num_instruct_candidates],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._propose_instructions`.

  ## Parameters

  - `program` (term())
  - `trainset` (list(term()))
  - `demo_candidates` (term())
  - `view_data_batch_size` (integer())
  - `program_aware_proposer` (boolean())
  - `data_aware_proposer` (boolean())
  - `tip_aware_proposer` (boolean())
  - `fewshot_aware_proposer` (boolean())
  - `num_instruct_candidates` (integer())

  ## Returns

  - `%{optional(integer()) => list(String.t())}`
  """
  @spec _propose_instructions(
          SnakeBridge.Ref.t(),
          term(),
          list(term()),
          term(),
          integer(),
          boolean(),
          boolean(),
          boolean(),
          boolean(),
          integer(),
          keyword()
        ) :: {:ok, %{optional(integer()) => list(String.t())}} | {:error, Snakepit.Error.t()}
  def _propose_instructions(
        ref,
        program,
        trainset,
        demo_candidates,
        view_data_batch_size,
        program_aware_proposer,
        data_aware_proposer,
        tip_aware_proposer,
        fewshot_aware_proposer,
        num_instruct_candidates,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_propose_instructions,
      [
        program,
        trainset,
        demo_candidates,
        view_data_batch_size,
        program_aware_proposer,
        data_aware_proposer,
        tip_aware_proposer,
        fewshot_aware_proposer,
        num_instruct_candidates
      ],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._select_and_insert_instructions_and_demos`.

  ## Parameters

  - `candidate_program` (term())
  - `instruction_candidates` (%{optional(integer()) => list(String.t())})
  - `demo_candidates` (term())
  - `trial` (term())
  - `trial_logs` (%{optional(term()) => term()})
  - `trial_num` (integer())

  ## Returns

  - `list(String.t())`
  """
  @spec _select_and_insert_instructions_and_demos(
          SnakeBridge.Ref.t(),
          term(),
          %{optional(integer()) => list(String.t())},
          term(),
          term(),
          %{optional(term()) => term()},
          integer(),
          keyword()
        ) :: {:ok, list(String.t())} | {:error, Snakepit.Error.t()}
  def _select_and_insert_instructions_and_demos(
        ref,
        candidate_program,
        instruction_candidates,
        demo_candidates,
        trial,
        trial_logs,
        trial_num,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_select_and_insert_instructions_and_demos,
      [candidate_program, instruction_candidates, demo_candidates, trial, trial_logs, trial_num],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._set_and_validate_datasets`.

  ## Parameters

  - `trainset` (list(term()))
  - `valset` (term())

  ## Returns

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

  @doc """
  Python method `MIPROv2._set_hyperparams_from_run_mode`.

  ## Parameters

  - `program` (term())
  - `num_trials` (term())
  - `minibatch` (boolean())
  - `zeroshot_opt` (boolean())
  - `valset` (list(term()))
  - `num_instruct_candidates` (term())
  - `num_fewshot_candidates` (term())

  ## Returns

  - `{integer(), list(term()), boolean(), integer(), integer()}`
  """
  @spec _set_hyperparams_from_run_mode(
          SnakeBridge.Ref.t(),
          term(),
          term(),
          boolean(),
          boolean(),
          list(term()),
          term(),
          term(),
          keyword()
        ) ::
          {:ok, {integer(), list(term()), boolean(), integer(), integer()}}
          | {:error, Snakepit.Error.t()}
  def _set_hyperparams_from_run_mode(
        ref,
        program,
        num_trials,
        minibatch,
        zeroshot_opt,
        valset,
        num_instruct_candidates,
        num_fewshot_candidates,
        opts \\ []
      ) do
    SnakeBridge.Runtime.call_method(
      ref,
      :_set_hyperparams_from_run_mode,
      [
        program,
        num_trials,
        minibatch,
        zeroshot_opt,
        valset,
        num_instruct_candidates,
        num_fewshot_candidates
      ],
      opts
    )
  end

  @doc """
  Python method `MIPROv2._set_num_trials_from_num_candidates`.

  ## Parameters

  - `program` (term())
  - `zeroshot_opt` (term())
  - `num_candidates` (term())

  ## Returns

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

  @doc """
  Python method `MIPROv2._set_random_seeds`.

  ## Parameters

  - `seed` (term())

  ## Returns

  - `term()`
  """
  @spec _set_random_seeds(SnakeBridge.Ref.t(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def _set_random_seeds(ref, seed, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :_set_random_seeds, [seed], 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
end