dspex

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

defmodule Dspy.Evaluate.Module do
  @moduledoc """
  Submodule bindings for `dspy.evaluate`.

  ## Version

  - Requested: 3.1.2
  - Observed at generation: 3.1.2

  ## Runtime Options

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

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

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

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

  @doc """
  Evaluate exact match or F1-thresholded match for an example/prediction pair.

  If `example.answer` is a string, compare `pred.answer` against it. If it's a list,
  compare against any of the references. When `frac >= 1.0` (default), use EM;
  otherwise require that the maximum F1 across references is at least `frac`.

  ## Parameters

  - `example` - `dspy.Example` object with field `answer` (str or list[str]).
  - `pred` - `dspy.Prediction` object with field `answer` (str).
  - `trace` - Unused; reserved for compatibility.
  - `frac` - Threshold in [0.0, 1.0]. `1.0` means EM. (type: `float()`)

  ## Returns

  Returns `boolean()`. True if the match condition holds; otherwise False.

  ## Examples

    ```python
    import dspy

    example = dspy.Example(answer=["Eiffel Tower", "Louvre"])
    pred = dspy.Prediction(answer="The Eiffel Tower")

    answer_exact_match(example, pred, frac=1.0)  # equivalent to EM, True
    answer_exact_match(example, pred, frac=0.5)  # True
    ```
  """
  @spec answer_exact_match(term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_exact_match(term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_exact_match(term(), term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_exact_match(term(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_exact_match(term(), term(), term(), term()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_exact_match(term(), term(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def answer_exact_match(example, pred) do
    SnakeBridge.Runtime.call(__MODULE__, :answer_exact_match, [example, pred], [])
  end

  def answer_exact_match(example, pred, 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__, :answer_exact_match, [example, pred], opts)
  end

  def answer_exact_match(example, pred, trace) do
    SnakeBridge.Runtime.call(__MODULE__, :answer_exact_match, [example, pred, trace], [])
  end

  def answer_exact_match(example, pred, trace, 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__, :answer_exact_match, [example, pred, trace], opts)
  end

  def answer_exact_match(example, pred, trace, frac) do
    SnakeBridge.Runtime.call(__MODULE__, :answer_exact_match, [example, pred, trace, frac], [])
  end

  def answer_exact_match(example, pred, trace, frac, 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__, :answer_exact_match, [example, pred, trace, frac], opts)
  end

  @doc """
  Return True if any passage in `pred.context` contains the answer(s).

  Strings are normalized (and passages also use DPR normalization internally).

  ## Parameters

  - `example` - `dspy.Example` object with field `answer` (str or list[str]).
  - `pred` - `dspy.Prediction` object with field `context` (list[str]) containing passages.
  - `trace` - Unused; reserved for compatibility.

  ## Returns

  Returns `boolean()`. True if any passage contains any reference answer; otherwise False.

  ## Examples

    ```python
    import dspy

    example = dspy.Example(answer="Eiffel Tower")
    pred = dspy.Prediction(context=["The Eiffel Tower is in Paris.", "..."])

    answer_passage_match(example, pred)  # True
    ```
  """
  @spec answer_passage_match(term(), term()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_passage_match(term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_passage_match(term(), term(), term()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  @spec answer_passage_match(term(), term(), term(), keyword()) ::
          {:ok, term()} | {:error, Snakepit.Error.t()}
  def answer_passage_match(example, pred) do
    SnakeBridge.Runtime.call(__MODULE__, :answer_passage_match, [example, pred], [])
  end

  def answer_passage_match(example, pred, 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__, :answer_passage_match, [example, pred], opts)
  end

  def answer_passage_match(example, pred, trace) do
    SnakeBridge.Runtime.call(__MODULE__, :answer_passage_match, [example, pred, trace], [])
  end

  def answer_passage_match(example, pred, trace, 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__, :answer_passage_match, [example, pred, trace], opts)
  end

  @doc """
  Compute the Exact Match (EM) metric between a prediction and reference answers.

  Returns True if any reference exactly matches the prediction after normalization;
  otherwise False. Normalization applies Unicode NFD, lowercasing, punctuation
  removal, English article removal ("a", "an", "the"), and whitespace collapse.

  ## Parameters

  - `prediction` - Predicted answer string. (type: `String.t()`)
  - `answers_list` - List of reference answers. (type: `list(String.t())`)

  ## Returns

  Returns `boolean()`. Whether any reference exactly equals the prediction after normalization.

  ## Examples

    ```python
    EM("The Eiffel Tower", ["Eiffel Tower", "Louvre"])  # True

    EM("paris", ["Paris"])  # True
    EM("paris", ["Paris, France"])  # False
    ```
  """
  @spec em(term(), term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def em(prediction, answers_list, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, "EM", [prediction, answers_list], opts)
  end

  @doc """
  Normalize text for string and token comparisons.

  Steps:
    1) Unicode NFD normalization
    2) lowercasing
    3) punctuation removal
    4) English article removal ("a", "an", "the")
    5) whitespace collapse

  ## Parameters

  - `s` - Input string. (type: `String.t()`)

  ## Returns

  Returns `String.t()`. Normalized string.

  ## Examples

    ```python
    normalize_text("The,  Eiffel  Tower!")  # "eiffel tower"
    ```
  """
  @spec normalize_text(term(), keyword()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def normalize_text(s, opts \\ []) do
    SnakeBridge.Runtime.call(__MODULE__, :normalize_text, [s], opts)
  end
end