dspex

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

defmodule Dspy.Predict.CodeAct do
  @moduledoc """
  CodeAct is a module that utilizes the Code Interpreter and predefined tools to solve the problem.
  """
  def __snakebridge_python_name__, do: "dspy.predict"
  def __snakebridge_python_class__, do: "CodeAct"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Initializes the CodeAct class with the specified model, temperature, and max tokens.



  ## Parameters

  - `signature` - The signature of the module. (type: `String.t() | Type[Signature]`)
  - `tools` - The tool callables to be used. CodeAct only accepts functions and not callable objects. (type: `list(Callable)`)
  - `max_iters` - The maximum number of iterations to generate the answer. (type: `integer()`)
  - `interpreter` - PythonInterpreter instance to use. If None, a new one is instantiated.

  ## Examples

      ```python
      from dspy.predict import CodeAct
      def factorial(n):
      if n == 1:
      return 1
      return n * factorial(n-1)

      act = CodeAct("n->factorial", tools=[factorial])
      act(n=5) # 120
      ```
  """
  @spec new(term(), list(term()), list(term()), keyword()) ::
          {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(signature, tools, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)

    SnakeBridge.Runtime.call_class(
      __MODULE__,
      :__init__,
      [signature, tools] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  Python method `CodeAct._async_call_with_potential_trajectory_truncation`.

  ## Parameters

  - `module` (term())
  - `trajectory` (term())
  - `input_args` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct._base_init`.

  ## Returns

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

  @doc """
  Python method `CodeAct._build_instructions`.

  ## Parameters

  - `signature` (term())
  - `tools` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct._call_with_potential_trajectory_truncation`.

  ## Parameters

  - `module` (term())
  - `trajectory` (term())
  - `input_args` (term())

  ## Returns

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

  @doc """
  Execute the code using PythonInterpreter and return the output or error.

  ## Parameters

  - `code` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct._format_trajectory`.

  ## Parameters

  - `trajectory` (%{optional(String.t()) => term()})

  ## Returns

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

  @doc """
  Python method `CodeAct._generate_instruction`.

  ## Parameters

  - `mode` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct._generate_signature`.

  ## Parameters

  - `mode` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct._parse_code`.

  ## Parameters

  - `code_data` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct._set_lm_usage`.

  ## Parameters

  - `tokens` (%{optional(String.t()) => term()})
  - `output` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct.acall`.

  ## Parameters

  - `args` (term())
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct.aforward`.

  ## Parameters

  - `input_args` (term())

  ## Returns

  - `term()`
  """
  @spec aforward(SnakeBridge.Ref.t(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def aforward(ref, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :aforward, [], 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.
  - `num_threads` - Number of threads to use for parallel processing.
  - `max_errors` - Maximum number of errors allowed before stopping execution. If ``None``, inherits from ``dspy.settings.max_errors``.
  - `return_failed_examples` - Whether to return failed examples and exceptions.
  - `provide_traceback` - Whether to include traceback information in error logs.
  - `disable_progress_bar` - Whether to display the progress bar.
  - `timeout` - Seconds before a straggler task is resubmitted. Set to 0 to disable.
  - `straggler_limit` - Only check for stragglers when this many or fewer tasks remain.

  ## Returns

  - `term()`
  """
  @spec batch(SnakeBridge.Ref.t(), list(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 `CodeAct.dump_state`.

  ## Parameters

  - `json_mode` (term() default: True)

  ## Returns

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

  @doc """
  Python method `CodeAct.forward`.

  ## Parameters

  - `kwargs` (term())

  ## Returns

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

  @doc """
  Python method `CodeAct.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 """
  Python method `CodeAct.inspect_history`.

  ## Parameters

  - `n` (integer() default: 1)

  ## Returns

  - `term()`
  """
  @spec inspect_history(SnakeBridge.Ref.t(), list(term()), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def inspect_history(ref, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_method(ref, :inspect_history, [] ++ List.wrap(args), 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()`)
  - `allow_pickle` - If True, allow loading .pkl files, which can run arbitrary code. This is dangerous and should only be used if you are sure about the source of the file and in a trusted environment. (type: `boolean()`)

  ## Returns

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

  @doc """
  Python method `CodeAct.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 `CodeAct.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() default: None)
  - `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 `CodeAct.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 `CodeAct.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.

  If `save_program=True` and `modules_to_serialize` are provided, it will register those modules for serialization
  with cloudpickle's `register_pickle_by_value`. This causes cloudpickle to serialize the module by value rather
  than by reference, ensuring the module is fully preserved along with the saved program. This is useful
  when you have custom modules that need to be serialized alongside your program. If None, then no modules
  will be registered for serialization.

  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()`)
  - `modules_to_serialize` - A list of modules to serialize with cloudpickle's `register_pickle_by_value`. If None, then no modules will be registered for serialization. (type: `list()`)

  ## 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 `CodeAct.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

  @doc """
  Truncates the trajectory so that it fits in the context window.

  Users can override this method to implement their own truncation logic.

  ## Parameters

  - `trajectory` (term())

  ## Returns

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