dspex

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

defmodule Dspy.Provider do
  @moduledoc """
  Base class for language model providers.

  A provider is responsible for managing language model instances, including
  launching, killing, and fine-tuning models. Subclasses should implement
  provider-specific logic for these operations.

  Attributes:
      finetunable: Whether this provider supports fine-tuning.
      reinforceable: Whether this provider supports reinforcement learning.
      TrainingJob: The class to use for training jobs (subclass of `TrainingJob`).
      ReinforceJob: The class to use for reinforcement learning jobs (subclass of `ReinforceJob`).

  ## Examples

      ```python
      from dspy.clients.provider import Provider

      class MyProvider(Provider):
      def __init__(self):
      super().__init__()
      self.finetunable = True

      @staticmethod
      def is_provider_model(model: str) -> bool:
      return model.startswith("myprovider/")

      @staticmethod
      def finetune(job, model, train_data, train_data_format, train_kwargs=None):
      # Implement fine-tuning logic
      return "fine_tuned_model_id"
      ```
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "Provider"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Initialize self.  See help(type(self)) for accurate signature.
  """
  @spec new(keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(opts \\ []) do
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [], opts)
  end

  @doc """
  Fine-tune a language model with the provided training data.

  This method should be implemented by subclasses to perform fine-tuning
  of a language model using the provided training data.

  ## Parameters

  - `job` - The training job instance to use for tracking the fine-tuning process.
  - `model` - The model identifier to fine-tune.
  - `train_data` - A list of training examples, each represented as a dictionary.
  - `train_data_format` - The format of the training data. Can be a `TrainDataFormat` enum value or a string identifier.
  - `train_kwargs` - Additional keyword arguments for fine-tuning configuration.

  ## Returns

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

    SnakeBridge.Runtime.call_method(
      ref,
      :finetune,
      [job, model, train_data, train_data_format] ++ List.wrap(args),
      opts
    )
  end

  @doc """
  Check if a model identifier is supported by this provider.

  Subclasses should override this method to check whether a model is
  supported if they want to have the model provider auto-discovered.

  ## Parameters

  - `model` - The model identifier to check (e.g., "openai/gpt-4").

  ## Returns

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

  @doc """
  Kill a running language model instance.

  This method should be implemented by subclasses to stop a running language
  model instance. Note that this method might be called even if there is no
  launched LM to kill, so implementations should be resilient to such cases.

  ## Parameters

  - `lm` - The language model instance to kill.
  - `launch_kwargs` - Additional keyword arguments for killing the model. The `lm.launch_kwargs` dictionary will contain the necessary information for the provider to kill the LM. This argument is named `launch_kwargs` (not `kill_kwargs`) because it contains the same information used for launching.

  ## Returns

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

  @doc """
  Launch a language model instance.

  This method should be implemented by subclasses to start a language model
  instance. Note that this method might be called even if there is already
  a launched LM, so implementations should be resilient to such cases.

  ## Parameters

  - `lm` - The language model instance to launch.
  - `launch_kwargs` - Additional keyword arguments for launching the model. The `lm.launch_kwargs` dictionary will contain the necessary information for the provider to launch the LM.

  ## Returns

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