dspex

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

defmodule Dspy.LM do
  @moduledoc """
  A language model supporting chat or text completion requests for use with DSPy modules.
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "LM"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Create a new language model instance for use with DSPy modules and programs.



  ## Parameters

  - `model` - The model to use. This should be a string of the form ``"llm_provider/llm_name"`` supported by LiteLLM. For example, ``"openai/gpt-4o"``.
  - `model_type` - The type of the model, either ``"chat"`` or ``"text"``.
  - `temperature` - The sampling temperature to use when generating responses.
  - `max_tokens` - The maximum number of tokens to generate per response.
  - `cache` - Whether to cache the model responses for reuse to improve performance and reduce costs.
  - `callbacks` - A list of callback functions to run before and after each request.
  - `num_retries` - The number of times to retry a request if it fails transiently due to network error, rate limiting, etc. Requests are retried with exponential backoff.
  - `provider` - The provider to use. If not specified, the provider will be inferred from the model.
  - `finetuning_model` - The model to finetune. In some providers, the models available for finetuning is different from the models available for inference.
  - `rollout_id` - Optional integer used to differentiate cache entries for otherwise identical requests. Different values bypass DSPy's caches while still caching future calls with the same inputs and rollout ID. Note that `rollout_id` only affects generation when `temperature` is non-zero. This argument is stripped before sending requests to the provider.
  """
  @spec new(String.t(), 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 """
  Python method `LM._check_truncation`.

  ## Parameters

  - `results` (term())

  ## Returns

  - `term()`
  """
  @spec _check_truncation(SnakeBridge.Ref.t(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def _check_truncation(ref, results, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :_check_truncation, [results], 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 """
  Python method `LM._get_cached_completion_fn`.

  ## Parameters

  - `completion_fn` (term())
  - `cache` (term())

  ## Returns

  - `term()`
  """
  @spec _get_cached_completion_fn(SnakeBridge.Ref.t(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def _get_cached_completion_fn(ref, completion_fn, cache, opts \\ []) do
    SnakeBridge.Runtime.call_method(ref, :_get_cached_completion_fn, [completion_fn, cache], 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 `LM._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 `LM._run_finetune_job`.

  ## Parameters

  - `job` (Dspy.Clients.Provider.TrainingJob.t())

  ## Returns

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

  @doc """
  Python method `LM._warn_zero_temp_rollout`.

  ## Parameters

  - `temperature` (term())
  - `rollout_id` (term())

  ## Returns

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

  @doc """
  Python method `LM.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 """
  Python method `LM.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 `LM.finetune`.

  ## Parameters

  - `train_data` (list(%{optional(String.t()) => term()}))
  - `train_data_format` (term())
  - `train_kwargs` (term() default: None)

  ## Returns

  - `Dspy.Clients.Provider.TrainingJob.t()`
  """
  @spec finetune(
          SnakeBridge.Ref.t(),
          list(%{optional(String.t()) => term()}),
          term(),
          list(term()),
          keyword()
        ) :: {:ok, Dspy.Clients.Provider.TrainingJob.t()} | {:error, Snakepit.Error.t()}
  def finetune(ref, train_data, train_data_format, args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)

    SnakeBridge.Runtime.call_method(
      ref,
      :finetune,
      [train_data, train_data_format] ++ List.wrap(args),
      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 `LM.infer_provider`.

  ## Returns

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

  @doc """
  Python method `LM.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 `LM.kill`.

  ## Parameters

  - `launch_kwargs` (term() default: None)

  ## Returns

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

  @doc """
  Python method `LM.launch`.

  ## Parameters

  - `launch_kwargs` (term() default: None)

  ## Returns

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

  @doc """
  Python method `LM.reinforce`.

  ## Parameters

  - `train_kwargs` (term())

  ## Returns

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

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