dspex

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

defmodule Dspy.Signatures do
  @moduledoc """
  Submodule bindings for `dspy.signatures`.

  ## Version

  - Requested: 3.2.0
  - Observed at generation: 3.2.0

  ## Runtime Options

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

      Dspy.Signatures.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.Signatures.predict(data, __runtime__: [timeout_profile: :ml_inference])

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

      # Route to a pool and enforce strict affinity
      Dspy.Signatures.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.signatures"
  @doc false
  def __snakebridge_library__, do: "dspy"

  @doc """
  Python binding for `dspy.signatures.ensure_signature`.

  ## Parameters

  - `signature` (term())
  - `instructions` (term() default: None)

  ## Returns

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

  def ensure_signature(signature, 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__, :ensure_signature, [signature], opts)
  end

  def ensure_signature(signature, instructions) do
    SnakeBridge.Runtime.call(__MODULE__, :ensure_signature, [signature, instructions], [])
  end

  def ensure_signature(signature, instructions, 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__, :ensure_signature, [signature, instructions], opts)
  end

  @doc """
  Infer a prefix from an attribute name by converting it to a human-readable format.



  ## Examples

    "camelCaseText" -> "Camel Case Text"
    "snake_case_text" -> "Snake Case Text"
    "text2number" -> "Text 2 Number"
    "HTMLParser" -> "HTML Parser"

  ## Parameters

  - `attribute_name` (String.t())

  ## Returns

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

  @doc """
  Python binding for `dspy.signatures.InputField`.

  ## Parameters

  - `kwargs` (term())

  ## Returns

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

  @doc """
  Create a new Signature subclass with the specified fields and instructions.



  ## Parameters

  - `signature` - Either a string in the format "input1, input2 -> output1, output2" or a dictionary mapping field names to tuples of (type, FieldInfo).
  - `instructions` - Optional string containing instructions/prompt for the signature. If not provided, defaults to a basic description of inputs and outputs.
  - `signature_name` - Optional string to name the generated Signature subclass. Defaults to "StringSignature".
  - `custom_types` - Optional dictionary mapping type names to their actual type objects. Useful for resolving custom types that aren't built-ins or in the typing module.

  ## Returns

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

  def make_signature(signature, 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__, :make_signature, [signature], opts)
  end

  def make_signature(signature, instructions) do
    SnakeBridge.Runtime.call(__MODULE__, :make_signature, [signature, instructions], [])
  end

  def make_signature(signature, instructions, 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__, :make_signature, [signature, instructions], opts)
  end

  def make_signature(signature, instructions, signature_name) do
    SnakeBridge.Runtime.call(
      __MODULE__,
      :make_signature,
      [signature, instructions, signature_name],
      []
    )
  end

  def make_signature(signature, instructions, signature_name, 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__,
      :make_signature,
      [signature, instructions, signature_name],
      opts
    )
  end

  def make_signature(signature, instructions, signature_name, custom_types) do
    SnakeBridge.Runtime.call(
      __MODULE__,
      :make_signature,
      [signature, instructions, signature_name, custom_types],
      []
    )
  end

  def make_signature(signature, instructions, signature_name, custom_types, 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__,
      :make_signature,
      [signature, instructions, signature_name, custom_types],
      opts
    )
  end

  @doc """
  Python binding for `dspy.signatures.OutputField`.

  ## Parameters

  - `kwargs` (term())

  ## Returns

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