dspex

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

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

  The `Example` class is the standard data format used in DSPy evaluation and optimization.

  Key features:
      - Dictionary-like access patterns (item access, iteration, etc.)
      - Flexible initialization from dictionaries, other `Example` instances, or keyword arguments
      - Input/output field separation for training data
      - Serialization support for saving/loading `Example` instances
      - Immutable operations that return new `Example` instances

  ## Examples

      Basic usage with keyword arguments:

      ```python
      import dspy

      # Create an example with input and output fields
      example = dspy.Example(
      question="What is the capital of France?",
      answer="Paris",
      )
      print(example.question)  # "What is the capital of France?"
      print(example.answer)   # "Paris"
      ```

      Initialize from a dictionary:

      ```python
      data = {"question": "What is 2+2?", "answer": "4"}
      example = dspy.Example(data)
      print(example["question"])  # "What is 2+2?"
      ```

      Copy from another Example:

      ```python
      original = dspy.Example(question="Hello", answer="World")
      copy = dspy.Example(original)
      print(copy.question)  # "Hello"
      ```

      Working with input/output separation:

      ```python
      # Mark which fields are inputs for training
      example = dspy.Example(
      question="What is the weather?",
      answer="It's sunny",
      ).with_inputs("question")

      # Get only input fields
      inputs = example.inputs()
      print(inputs.question)  # "What is the weather?"

      # Get only output fields (labels)
      labels = example.labels()
      print(labels.answer)  # "It's sunny"
      ```

      Dictionary-like operations:

      ```python
      example = dspy.Example(name="Alice", age=30)

      # Check if key exists
      if "name" in example:
      print("Name field exists")

      # Get with default value
      city = example.get("city", "Unknown")
      print(city)  # "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 """
  Initialize an Example instance.



  ## Parameters

  - `base` - Optional base data source. Can be: - Another Example instance (copies its data) - A dictionary (copies its key-value pairs) - None (creates empty Example) **kwargs: Additional key-value pairs to store in the Example.
  """
  @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 """
  Python method `Example.copy`.

  ## 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 """
  Python method `Example.get`.

  ## Parameters

  - `key` (term())
  - `default` (term() default: None)

  ## 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 """
  Python method `Example.inputs`.

  ## 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 """
  Python method `Example.items`.

  ## Parameters

  - `include_dspy` (term() default: False)

  ## 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 """
  Python method `Example.keys`.

  ## Parameters

  - `include_dspy` (term() default: False)

  ## 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 """
  Python method `Example.labels`.

  ## 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 """
  Python method `Example.toDict`.

  ## 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 """
  Python method `Example.values`.

  ## Parameters

  - `include_dspy` (term() default: False)

  ## 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 """
  Python method `Example.with_inputs`.

  ## 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 """
  Python method `Example.without`.

  ## 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