dspex

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

defmodule Dspy.Primitives.Example do
  @moduledoc """
  A flexible data container for DSPy examples and training data with named fields.

  An `Example` is roughly one row from a HuggingFace dataset or pandas
  `DataFrame`. It behaves a lot like a dictionary or dot-access record: you
  can read fields with `example["question"]` or `example.question`.

  In DSPy, lists of `Example` objects are your trainset, devset, and testset.
  Most examples are built from keyword arguments or an existing record, then
  tagged with `with_inputs(...)` to say which fields should be fed into a
  module. The remaining fields are labels or metadata.

  When you write evaluation code, custom optimizers, or training loops, use
  `example.inputs()` for the fields you want to pass to a module, and use
  `example.labels()` for the fields you want to compare against the module's
  output.

  ## Examples

      Build one from keyword arguments:

      iex> import dspy
      iex> example = dspy.Example(
      ...> question="What is the capital of France?",
      ...> answer="Paris",
      ...> ).with_inputs("question")
      iex> example.question
      'What is the capital of France?'
      iex> example.answer
      'Paris'
      iex> example.inputs().toDict()
      {'question': 'What is the capital of France?'}

      Build one from an existing record:

      iex> record = {"question": "What is 2+2?", "answer": "4"}
      iex> example = dspy.Example(**record).with_inputs("question")
      iex> example["question"]
      'What is 2+2?'
      iex> example.labels().answer
      '4'

      Mark which fields are inputs:

      iex> example = dspy.Example(
      ...> question="What is the weather?",
      ...> answer="It's sunny",
      ...> ).with_inputs("question")
      iex> example.inputs().question
      'What is the weather?'
      iex> example.labels().answer
      "It's sunny"

      Use examples in a trainset:

      iex> trainset = [
      ...> dspy.Example(question="What is 2+2?", answer="4").with_inputs("question"),
      ...> dspy.Example(question="What is 3+3?", answer="6").with_inputs("question"),
      ...> ]
      iex> trainset[0].inputs().toDict()
      {'question': 'What is 2+2?'}

      Use an example in a metric:

      iex> def exact_match_metric(example, pred, trace=None):
      ...> return example.answer.lower() == pred.answer.lower()
      iex> gold = dspy.Example(question="What is 1+1?", answer="2").with_inputs("question")
      iex> pred = dspy.Prediction(answer="2")
      iex> exact_match_metric(gold, pred)
      True

      Use it like a dictionary:

      iex> example = dspy.Example(name="Alice", age=30).with_inputs("name")
      iex> "name" in example
      True
      iex> example.get("city", "Unknown")
      'Unknown'
  """
  def __snakebridge_python_name__, do: "dspy.primitives"
  def __snakebridge_python_class__, do: "Example"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Create an `Example` from fields or from an existing record.

  In the common case, pass fields as keyword arguments, like
  `dspy.Example(question="...", answer="...")`. Use `base` when you
  already have a dictionary or another `Example` and want to copy its
  fields before adding or overriding a few values.

  ## Parameters

  - `base` - A dictionary or `Example` to copy fields from before applying `**kwargs`. When `None`, starts with no fields. **kwargs: Field names and values to store on the example. If a field appears in both `base` and `**kwargs`, the value from `**kwargs` wins.
  """
  @spec new(list(term()), keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(args, opts \\ []) do
    {args, opts} = SnakeBridge.Runtime.normalize_args_opts(args, opts)
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [] ++ List.wrap(args), opts)
  end

  @doc """
  Return a shallow copy, optionally overriding fields.



  ## Examples

      iex> import dspy
      iex> ex = dspy.Example(question="Why?", answer="Because.")
      iex> ex.copy(answer="No reason.")
      Example({'question': 'Why?', 'answer': 'No reason.'}) (input_keys=None)

  ## 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 """
  Return the value for `key`, or `default` if the field doesn't exist.



  ## Parameters

  - `key` - Field name to look up.
  - `default` - Value to return when `key` is missing.

  ## Examples

      iex> import dspy
      iex> ex = dspy.Example(name="Alice")
      iex> ex.get("name")
      'Alice'
      iex> ex.get("city", "Unknown")
      'Unknown'

  ## Returns

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

  @doc """
  Return a new `Example` containing only the input fields.

  Requires `with_inputs` to have been called first.

  ## Raises

  - `ArgumentError` - If `with_inputs` was not called on this example.

  ## Examples

      iex> import dspy
      iex> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
      iex> ex.inputs()
      Example({'question': 'Why?'}) (input_keys={'question'})

  ## Returns

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

  @doc """
  Return `(field_name, value)` pairs, like `dict.items()`.



  ## Parameters

  - `include_dspy` - If `True`, include internal fields prefixed with `dspy_`.

  ## Examples

      iex> import dspy
      iex> dspy.Example(question="Why?", answer="Because.").items()
      [('question', 'Why?'), ('answer', 'Because.')]

  ## Returns

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

  @doc """
  Return field names, like `dict.keys()`.



  ## Parameters

  - `include_dspy` - If `True`, include internal fields prefixed with `dspy_`. Normally you can ignore these.

  ## Examples

      iex> import dspy
      iex> dspy.Example(question="Why?", answer="Because.").keys()
      ['question', 'answer']

  ## Returns

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

  @doc """
  Return a new `Example` containing only the label (non-input) fields.

  Requires `with_inputs` to have been called first, since labels are
  everything that is *not* an input.

  ## Examples

      iex> import dspy
      iex> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
      iex> ex.labels()
      Example({'answer': 'Because.'}) (input_keys=None)

  ## Returns

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

  @doc """
  Convert to a plain dictionary, recursively serializing nested objects.

  Nested `Example` objects, Pydantic models, lists, and dicts are
  converted so the result is JSON-friendly.

  ## Examples

      iex> import dspy
      iex> dspy.Example(question="Why?", answer="Because.").toDict()
      {'question': 'Why?', 'answer': 'Because.'}

  ## Returns

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

  @doc """
  Return field values, like `dict.values()`.



  ## Parameters

  - `include_dspy` - If `True`, include internal fields prefixed with `dspy_`.

  ## Examples

      iex> import dspy
      iex> dspy.Example(question="Why?", answer="Because.").values()
      ['Why?', 'Because.']

  ## Returns

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

  @doc """
  Mark which fields are inputs and return a new `Example`.

  Fields not listed here are treated as labels (expected outputs).
  DSPy optimizers and evaluators use this split: they pass
  `example.inputs()` to your program and compare the output against
  `example.labels()`.

  ## Examples

      iex> import dspy
      iex> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
      iex> ex.inputs().keys()
      ['question']
      iex> ex.labels().keys()
      ['answer']

  ## Parameters

  - `keys` (term())

  ## Returns

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

  @doc """
  Return a copy with the specified fields removed.



  ## Examples

      iex> import dspy
      iex> ex = dspy.Example(question="Why?", answer="Because.", source="web")
      iex> ex.without("source")
      Example({'question': 'Why?', 'answer': 'Because.'}) (input_keys=None)

  ## Parameters

  - `keys` (term())

  ## Returns

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