dspex

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

defmodule Dspy.Utils.BaseCallback do
  @moduledoc """
  A base class for defining callback handlers for DSPy components.

  To use a callback, subclass this class and implement the desired handlers. Each handler
  will be called at the appropriate time before/after the execution of the corresponding component.  For example, if
  you want to print a message before and after an LM is called, implement `the on_llm_start` and `on_lm_end` handler.
  Users can set the callback globally using `dspy.configure` or locally by passing it to the component
  constructor.


  Example 1: Set a global callback using `dspy.configure`.

  ```
  import dspy
  from dspy.utils.callback import BaseCallback

  class LoggingCallback(BaseCallback):

      def on_lm_start(self, call_id, instance, inputs):
          print(f"LM is called with inputs: {inputs}")

      def on_lm_end(self, call_id, outputs, exception):
          print(f"LM is finished with outputs: {outputs}")

  dspy.configure(
      callbacks=[LoggingCallback()]
  )

  cot = dspy.ChainOfThought("question -> answer")
  cot(question="What is the meaning of life?")

  # > LM is called with inputs: {'question': 'What is the meaning of life?'}
  # > LM is finished with outputs: {'answer': '42'}
  ```

  Example 2: Set a local callback by passing it to the component constructor.

  ```
  lm_1 = dspy.LM("gpt-3.5-turbo", callbacks=[LoggingCallback()])
  lm_1(question="What is the meaning of life?")

  # > LM is called with inputs: {'question': 'What is the meaning of life?'}
  # > LM is finished with outputs: {'answer': '42'}

  lm_2 = dspy.LM("gpt-3.5-turbo")
  lm_2(question="What is the meaning of life?")
  # No logging here because only `lm_1` has the callback set.
  ```
  """
  def __snakebridge_python_name__, do: "dspy.utils"
  def __snakebridge_python_class__, do: "BaseCallback"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

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

  ## Parameters

  - `args` (term())
  - `kwargs` (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 """
  A handler triggered after format() method of an adapter (subclass of dspy.Adapter) is called..



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `outputs` - The outputs of the Adapter's format() method. If the method is interrupted by an exception, this will be None.
  - `exception` - If an exception is raised during the execution, it will be stored here.

  ## Returns

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

    SnakeBridge.Runtime.call_method(
      ref,
      :on_adapter_format_end,
      [call_id, outputs] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  A handler triggered when format() method of an adapter (subclass of dspy.Adapter) is called.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `instance` - The Adapter instance.
  - `inputs` - The inputs to the Adapter's format() method. Each arguments is stored as a key-value pair in a dictionary.

  ## Returns

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

  @doc """
  A handler triggered after parse() method of an adapter (subclass of dspy.Adapter) is called.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `outputs` - The outputs of the Adapter's parse() method. If the method is interrupted by an exception, this will be None.
  - `exception` - If an exception is raised during the execution, it will be stored here.

  ## Returns

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

    SnakeBridge.Runtime.call_method(
      ref,
      :on_adapter_parse_end,
      [call_id, outputs] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  A handler triggered when parse() method of an adapter (subclass of dspy.Adapter) is called.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `instance` - The Adapter instance.
  - `inputs` - The inputs to the Adapter's parse() method. Each arguments is stored as a key-value pair in a dictionary.

  ## Returns

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

  @doc """
  A handler triggered after evaluation is executed.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `outputs` - The outputs of the Evaluate's __call__ method. If the method is interrupted by an exception, this will be None.
  - `exception` - If an exception is raised during the execution, it will be stored here.

  ## Returns

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

    SnakeBridge.Runtime.call_method(
      ref,
      :on_evaluate_end,
      [call_id, outputs] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  A handler triggered when evaluation is started.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `instance` - The Evaluate instance.
  - `inputs` - The inputs to the Evaluate's __call__ method. Each arguments is stored as a key-value pair in a dictionary.

  ## Returns

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

  @doc """
  A handler triggered after __call__ method of dspy.LM instance is executed.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `outputs` - The outputs of the LM's __call__ method. If the method is interrupted by an exception, this will be None.
  - `exception` - If an exception is raised during the execution, it will be stored here.

  ## Returns

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

  @doc """
  A handler triggered when __call__ method of dspy.LM instance is called.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `instance` - The LM instance.
  - `inputs` - The inputs to the LM's __call__ method. Each arguments is stored as a key-value pair in a dictionary.

  ## Returns

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

  @doc """
  A handler triggered after forward() method of a module (subclass of dspy.Module) is executed.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `outputs` - The outputs of the module's forward() method. If the method is interrupted by an exception, this will be None.
  - `exception` - If an exception is raised during the execution, it will be stored here.

  ## Returns

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

    SnakeBridge.Runtime.call_method(
      ref,
      :on_module_end,
      [call_id, outputs] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  A handler triggered when forward() method of a module (subclass of dspy.Module) is called.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `instance` - The Module instance.
  - `inputs` - The inputs to the module's forward() method. Each arguments is stored as a key-value pair in a dictionary.

  ## Returns

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

  @doc """
  A handler triggered after a tool is executed.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `outputs` - The outputs of the Tool's __call__ method. If the method is interrupted by an exception, this will be None.
  - `exception` - If an exception is raised during the execution, it will be stored here.

  ## Returns

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

    SnakeBridge.Runtime.call_method(
      ref,
      :on_tool_end,
      [call_id, outputs] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  A handler triggered when a tool is called.



  ## Parameters

  - `call_id` - A unique identifier for the call. Can be used to connect start/end handlers.
  - `instance` - The Tool instance.
  - `inputs` - The inputs to the Tool's __call__ method. Each arguments is stored as a key-value pair in a dictionary.

  ## Returns

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