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

defmodule Dspy.BaseLM do
  @moduledoc """
  Base class for handling LLM calls.

  Most users can directly use the `dspy.LM` class, which is a subclass of `BaseLM`. Users can also implement their
  own subclasses of `BaseLM` to support custom LLM providers and inject custom logic. To do so, simply override the
  `forward` method and make sure the return format is identical to the
  [OpenAI response format](https://platform.openai.com/docs/api-reference/responses/object).
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "BaseLM"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

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

  ## Parameters

  - `model` (term())
  - `model_type` (term() default: 'chat')
  - `temperature` (term() default: 0.0)
  - `max_tokens` (term() default: 1000)
  - `cache` (term() default: True)
  - `kwargs` (term())
  """
  @spec new(term(), list(term()), keyword()) ::
          {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(model, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [model] ++ List.wrap(args), opts)
  end

  @doc """
  Extract citations from LiteLLM response if available.

  Reference: https://docs.litellm.ai/docs/providers/anthropic#beta-citations-api

  ## Parameters

  - `choice` - The choice object from response.choices

  ## Returns

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

  @doc """
  Process the response of OpenAI chat completion API and extract outputs.



  ## Parameters

  - `response` - The OpenAI chat completion response
  - `https` - //platform.openai.com/docs/api-reference/chat/object
  - `merged_kwargs` - Merged kwargs from self.kwargs and method kwargs

  ## Returns

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

  @doc """
  Python method `BaseLM._process_lm_response`.

  ## Parameters

  - `response` (term())
  - `prompt` (term())
  - `messages` (term())
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Process the response of OpenAI Response API and extract outputs.



  ## Parameters

  - `response` - OpenAI Response API response
  - `https` - //platform.openai.com/docs/api-reference/responses/object

  ## Returns

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

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

  ## Parameters

  - `prompt` (term() default: None)
  - `messages` (term() default: None)
  - `kwargs` (term())

  ## Returns

  - `list(term())`
  """
  @spec acall(SnakeBridge.Ref.t(), list(term()), keyword()) ::
          {:ok, list(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 """
  Async forward pass for the language model.

  Subclasses must implement this method, and the response should be identical to either of the following formats:
  - [OpenAI response format](https://platform.openai.com/docs/api-reference/responses/object)
  - [OpenAI chat completion format](https://platform.openai.com/docs/api-reference/chat/object)
  - [OpenAI text completion format](https://platform.openai.com/docs/api-reference/completions/object)

  ## Parameters

  - `prompt` (term() default: None)
  - `messages` (term() default: None)
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Returns a copy of the language model with possibly updated parameters.

  Any provided keyword arguments update the corresponding attributes or LM kwargs of
  the copy. For example, ``lm.copy(rollout_id=1, temperature=1.0)`` returns an LM whose
  requests use a different rollout ID at non-zero temperature to bypass cache collisions.

  ## Parameters

  - `kwargs` (term())

  ## Returns

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

  @doc """
  Forward pass for the language model.

  Subclasses must implement this method, and the response should be identical to either of the following formats:
  - [OpenAI response format](https://platform.openai.com/docs/api-reference/responses/object)
  - [OpenAI chat completion format](https://platform.openai.com/docs/api-reference/chat/object)
  - [OpenAI text completion format](https://platform.openai.com/docs/api-reference/completions/object)

  ## Parameters

  - `prompt` (term() default: None)
  - `messages` (term() default: None)
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Python method `BaseLM.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 """
  Python method `BaseLM.update_history`.

  ## Parameters

  - `entry` (term())

  ## Returns

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