dspex

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

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

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

  ## Parameters

  - `callbacks` (term())
  """
  @spec new(list(term()), keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [] ++ List.wrap(args), opts)
  end

  @doc """
  Processes a list of dspy.Example instances in parallel using the Parallel module.



  ## Parameters

  - `examples` - List of dspy.Example instances to process.
  - `batch_size` - Number of threads to use for parallel processing.
  - `max_errors` - Maximum number of errors allowed before stopping execution.
  - `return_failed_examples` - Whether to return failed examples and exceptions.
  - `provide_traceback` - Whether to include traceback information in error logs.

  ## Returns

  - `term()`
  """
  @spec batch(SnakeBridge.Ref.t(), term(), list(term()), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def batch(ref, examples, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_method(ref, :batch, [examples] ++ List.wrap(args), opts)
  end

  @doc """
  Deep copy the module.

  This is a tweak to the default python deepcopy that only deep copies `self.parameters()`, and for other
  attributes, we just do the shallow copy.

  ## Returns

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

  @doc """
  Python method `Program.dump_state`.

  ## Returns

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

  @doc """
  Python method `Program.get_lm`.

  ## Returns

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

  @doc """
  Return repr(self).

  ## Returns

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

  @doc """
  Load the saved module. You may also want to check out dspy.load, if you want to

  load an entire program, not just the state for an existing program.

  ## Parameters

  - `path` - Path to the saved state file, which should be a .json or a .pkl file (type: `String.t()`)

  ## Returns

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

  @doc """
  Python method `Program.load_state`.

  ## Parameters

  - `state` (term())

  ## Returns

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

  @doc """
  Applies a function to all named predictors.

  ## Parameters

  - `func` (term())

  ## Returns

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

  @doc """
  Unlike PyTorch, handles (non-recursive) lists of parameters too.

  ## Returns

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

  @doc """
  Python method `Program.named_predictors`.

  ## Returns

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

  @doc """
  Find all sub-modules in the module, as well as their names.

  Say self.children[4]['key'].sub_module is a sub-module. Then the name will be
  'children[4][key].sub_module'. But if the sub-module is accessible at different
  paths, only one of the paths will be returned.

  ## Parameters

  - `type_` (term())
  - `skip_compiled` (term() default: false)

  ## Returns

  - `term()`
  """
  @spec named_sub_modules(SnakeBridge.Ref.t(), list(term()), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def named_sub_modules(ref, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_method(ref, :named_sub_modules, [] ++ List.wrap(args), opts)
  end

  @doc """
  Python method `Program.parameters`.

  ## Returns

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

  @doc """
  Python method `Program.predictors`.

  ## Returns

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

  @doc """
  Deep copy the module and reset all parameters.

  ## Returns

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

  @doc """
  Save the module.

  Save the module to a directory or a file. There are two modes:
  - `save_program=False`: Save only the state of the module to a json or pickle file, based on the value of
      the file extension.
  - `save_program=True`: Save the whole module to a directory via cloudpickle, which contains both the state and
      architecture of the model.

  We also save the dependency versions, so that the loaded model can check if there is a version mismatch on
  critical dependencies or DSPy version.

  ## Parameters

  - `path` - Path to the saved state file, which should be a .json or .pkl file when `save_program=False`, and a directory when `save_program=True`. (type: `String.t()`)
  - `save_program` - If True, save the whole module to a directory via cloudpickle, otherwise only save the state. (type: `boolean()`)

  ## Returns

  - `term()`
  """
  @spec save(SnakeBridge.Ref.t(), term(), list(term()), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def save(ref, path, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_method(ref, :save, [path] ++ List.wrap(args), opts)
  end

  @doc """
  Python method `Program.set_lm`.

  ## Parameters

  - `lm` (term())

  ## Returns

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