dspex

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

defmodule Dspy.TwoStepAdapter do
  @moduledoc """
  A two-stage adapter that:

  1. Uses a simpler, more natural prompt for the main LM
      2. Uses a smaller LM with chat adapter to extract structured data from the response of main LM
  This adapter uses a common __call__ logic defined in base Adapter class.
  This class is particularly useful when interacting with reasoning models as the main LM since reasoning models
  are known to struggle with structured outputs.
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "TwoStepAdapter"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Args:

  callbacks: List of callback functions to execute during `format()` and `parse()` methods. Callbacks can be
          used for logging, monitoring, or custom processing. Defaults to None (empty list).
      use_native_function_calling: Whether to enable native function calling capabilities when the LM supports it.
          If True, the adapter will automatically configure function calling when input fields contain `dspy.Tool`
          or `list[dspy.Tool]` types. Defaults to False.
      native_response_types: List of output field types that should be handled by native LM features rather than
          adapter parsing. For example, `dspy.Citations` can be populated directly by citation APIs
          (e.g., Anthropic's citation feature). Defaults to `[Citations]`.

  ## Parameters

  - `extraction_model` (term())
  - `kwargs` (term())
  """
  @spec new(term(), keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(extraction_model, opts \\ []) do
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [extraction_model], opts)
  end

  @doc """
  Python method `TwoStepAdapter._call_postprocess`.

  ## Parameters

  - `processed_signature` (term())
  - `original_signature` (term())
  - `outputs` (list(term()))
  - `lm` (term())
  - `lm_kwargs` (%{optional(String.t()) => term()})

  ## Returns

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

  @doc """
  Python method `TwoStepAdapter._call_preprocess`.

  ## Parameters

  - `lm` (term())
  - `lm_kwargs` (%{optional(String.t()) => term()})
  - `signature` (term())
  - `inputs` (%{optional(String.t()) => term()})

  ## Returns

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

  @doc """
  Create a new signature containing a new 'text' input field and all output fields.



  ## Parameters

  - `original_signature` - The original signature to extract output fields from

  ## Returns

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

  @doc """
  Python method `TwoStepAdapter._get_history_field_name`.

  ## Parameters

  - `signature` (term())

  ## Returns

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

  @doc """
  Python method `TwoStepAdapter._get_tool_call_input_field_name`.

  ## Parameters

  - `signature` (term())

  ## Returns

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

  @doc """
  Python method `TwoStepAdapter._get_tool_call_output_field_name`.

  ## Parameters

  - `signature` (term())

  ## Returns

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

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

  ## Parameters

  - `lm` (term())
  - `lm_kwargs` (%{optional(String.t()) => term()})
  - `signature` (term())
  - `demos` (list(%{optional(String.t()) => term()}))
  - `inputs` (%{optional(String.t()) => term()})

  ## Returns

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

  @doc """
  Format a prompt for the first stage with the main LM.

  This no specific structure is required for the main LM, we customize the format method
  instead of format_field_description or format_field_structure.

  ## Parameters

  - `signature` - The signature of the original task
  - `demos` - A list of demo examples
  - `inputs` - The current input

  ## Returns

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

  @doc """
  Format the assistant message content.

  This method formats the assistant message content, which can be used in formatting few-shot examples,
  conversation history.

  ## Parameters

  - `signature` - The DSPy signature for which to format the assistant message content.
  - `outputs` - The output fields to be formatted.
  - `missing_field_message` - A message to be used when a field is missing.

  ## Returns

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

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

  @doc """
  Format the conversation history.

  This method formats the conversation history and the current input as multiturn messages.

  ## Parameters

  - `signature` - The DSPy signature for which to format the conversation history.
  - `history_field_name` - The name of the history field in the signature.
  - `inputs` - The input arguments to the DSPy module.

  ## Returns

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

  @doc """
  Format the few-shot examples.

  This method formats the few-shot examples as multiturn messages.

  ## Parameters

  - `signature` - The DSPy signature for which to format the few-shot examples.
  - `demos` - A list of few-shot examples, each element is a dictionary with keys of the input and output fields of the signature.

  ## Returns

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

  @doc """
  Format the field description for the system message.

  This method formats the field description for the system message. It should return a string that contains
  the field description for the input fields and the output fields.

  ## Parameters

  - `signature` - The DSPy signature for which to format the field description.

  ## Returns

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

  @doc """
  Format the field structure for the system message.

  This method formats the field structure for the system message. It should return a string that dictates the
  format the input fields should be provided to the LM, and the format the output fields will be in the response.
  Refer to the ChatAdapter and JsonAdapter for an example.

  ## Parameters

  - `signature` - The DSPy signature for which to format the field structure.

  ## Returns

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

  @doc """
  Format the system message for the LM call.



  ## Parameters

  - `signature` - The DSPy signature for which to format the system message.

  ## Returns

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

  @doc """
  Create a description of the task based on the signature

  ## Parameters

  - `signature` (term())

  ## Returns

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

  @doc """
  Format the user message content.

  This method formats the user message content, which can be used in formatting few-shot examples, conversation
  history, and the current input.

  ## Parameters

  - `signature` - The DSPy signature for which to format the user message content.
  - `inputs` - The input arguments to the DSPy module.
  - `prefix` - A prefix to the user message content.
  - `suffix` - A suffix to the user message content.

  ## Returns

  - `String.t()`
  """
  @spec format_user_message_content(
          SnakeBridge.Ref.t(),
          term(),
          %{optional(String.t()) => term()},
          list(term()),
          keyword()
        ) :: {:ok, String.t()} | {:error, Snakepit.Error.t()}
  def format_user_message_content(ref, signature, inputs, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)

    SnakeBridge.Runtime.call_method(
      ref,
      :format_user_message_content,
      [signature, inputs] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  Use a smaller LM (extraction_model) with chat adapter to extract structured data

  from the raw completion text of the main LM.

  ## Parameters

  - `signature` - The signature of the original task
  - `completion` - The completion from the main LM

  ## Returns

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