dspex

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

defmodule Dspy.Clients.LmLocal do
  @moduledoc """
  Submodule bindings for `dspy.clients.lm_local`.

  ## Version

  - Requested: 3.1.2
  - Observed at generation: 3.1.2

  ## Runtime Options

  All functions accept a `__runtime__` option for controlling execution behavior:

      Dspy.Clients.LmLocal.some_function(args, __runtime__: [timeout: 120_000])

  ### Supported runtime options

  - `:timeout` - Call timeout in milliseconds (default: 120,000ms / 2 minutes)
  - `:timeout_profile` - Use a named profile (`:default`, `:ml_inference`, `:batch_job`, `:streaming`)
  - `:stream_timeout` - Timeout for streaming operations (default: 1,800,000ms / 30 minutes)
  - `:session_id` - Override the session ID for this call
  - `:pool_name` - Target a specific Snakepit pool (multi-pool setups)
  - `:affinity` - Override session affinity (`:hint`, `:strict_queue`, `:strict_fail_fast`)

  ### Timeout Profiles

  - `:default` - 2 minute timeout for regular calls
  - `:ml_inference` - 10 minute timeout for ML/LLM workloads
  - `:batch_job` - Unlimited timeout for long-running jobs
  - `:streaming` - 2 minute timeout, 30 minute stream_timeout

  ### Example with timeout override

      # For a long-running ML inference call
      Dspy.Clients.LmLocal.predict(data, __runtime__: [timeout_profile: :ml_inference])

      # Or explicit timeout
      Dspy.Clients.LmLocal.predict(data, __runtime__: [timeout: 600_000])

      # Route to a pool and enforce strict affinity
      Dspy.Clients.LmLocal.predict(data, __runtime__: [pool_name: :strict_pool, affinity: :strict_queue])

  See `SnakeBridge.Defaults` for global timeout configuration.

  """

  @doc false
  def __snakebridge_python_name__, do: "dspy.clients.lm_local"
  @doc false
  def __snakebridge_library__, do: "dspy"

  @doc """
  Python binding for `dspy.clients.lm_local.create_output_dir`.

  ## Parameters

  - `model_name` (term())
  - `data_path` (term())

  ## Returns

  - `term()`
  """
  @spec create_output_dir(term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def create_output_dir(model_name, data_path, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :create_output_dir, [model_name, data_path], opts)
  end

  @doc """
  This function encodes a single example into a format that can be used for sft training.

  Here, we assume each example has a 'messages' field. Each message in it is a dict with 'role' and 'content' fields.
  We use the `apply_chat_template` function from the tokenizer to tokenize the messages and prepare the input and label tensors.

  Code obtained from the allenai/open-instruct repository: https://github.com/allenai/open-instruct/blob/4365dea3d1a6111e8b2712af06b22a4512a0df88/open_instruct/finetune.py

  ## Parameters

  - `example` (term())
  - `tokenizer` (term())
  - `max_seq_length` (term())

  ## Returns

  - `term()`
  """
  @spec encode_sft_example(term(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def encode_sft_example(example, tokenizer, max_seq_length, opts \\ []) do
    SnakeBridge.Runtime.call(
      __MODULE__,
      :encode_sft_example,
      [example, tokenizer, max_seq_length],
      opts
    )
  end

  @doc """
  Return a free TCP port on localhost.

  ## Returns

  - `integer()`
  """
  @spec get_free_port(keyword()) :: {:ok, integer()} | {:error, Snakepit.Error.t()}
  def get_free_port(opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :get_free_port, [], opts)
  end

  @doc """
  Python binding for `dspy.clients.lm_local.train_sft_locally`.

  ## Parameters

  - `model_name` (term())
  - `train_data` (term())
  - `train_kwargs` (term())

  ## Returns

  - `term()`
  """
  @spec train_sft_locally(term(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def train_sft_locally(model_name, train_data, train_kwargs, opts \\ []) do
    SnakeBridge.Runtime.call(
      __MODULE__,
      :train_sft_locally,
      [model_name, train_data, train_kwargs],
      opts
    )
  end

  @doc """
  Wait for the server to be ready by polling the /v1/models endpoint.



  ## Parameters

  - `base_url` - The base URL of the server (e.g. http://localhost:1234)
  - `timeout` - Maximum time to wait in seconds. None means wait forever.

  ## Returns

  - `nil`
  """
  @spec wait_for_server(String.t()) :: {:ok, nil} | {:error, Snakepit.Error.t()}
  @spec wait_for_server(String.t(), keyword()) :: {:ok, nil} | {:error, Snakepit.Error.t()}
  @spec wait_for_server(String.t(), term()) :: {:ok, nil} | {:error, Snakepit.Error.t()}
  @spec wait_for_server(String.t(), term(), keyword()) ::
          {:ok, nil} | {:error, Snakepit.Error.t()}
  def wait_for_server(base_url) do
    SnakeBridge.Runtime.call(__MODULE__, :wait_for_server, [base_url], [])
  end

  def wait_for_server(base_url, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :wait_for_server, [base_url], opts)
  end

  def wait_for_server(base_url, timeout) do
    SnakeBridge.Runtime.call(__MODULE__, :wait_for_server, [base_url, timeout], [])
  end

  def wait_for_server(base_url, timeout, opts)
      when is_list(opts) and
             (opts == [] or
                (is_tuple(hd(opts)) and tuple_size(hd(opts)) == 2 and is_atom(elem(hd(opts), 0)))) do
    SnakeBridge.Runtime.call(__MODULE__, :wait_for_server, [base_url, timeout], opts)
  end
end