dspex

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

defmodule Dspy.Evaluate.AutoEvaluation.AnswerCompleteness do
  @moduledoc """
  Estimate the completeness of a system's responses, against the ground truth.

  You will first enumerate key ideas in each response, discuss their overlap, and then report completeness.
  """
  def __snakebridge_python_name__, do: "dspy.evaluate.auto_evaluation"
  def __snakebridge_python_class__, do: "AnswerCompleteness"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Create a new model by parsing and validating input data from keyword arguments.

  Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
  validated to form a valid model.

  `self` is explicitly positional-only to allow `self` as a field name.

  ## Parameters

  - `data` (term())
  """
  @spec new(keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(opts \\ []) do
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [], opts)
  end

  @doc """
  !!! abstract "Usage Documentation"

  [JSON Parsing](https://docs.pydantic.dev/latest/concepts/json/#json-parsing)

  Validate the given JSON data against the Pydantic model.

  ## Parameters

  - `json_data` - The JSON data to validate.
  - `strict` - Whether to enforce types strictly.
  - `extra` - Whether to ignore, allow, or forbid extra data during model validation. See the [`extra` configuration value][pydantic.ConfigDict.extra] for details.
  - `context` - Extra variables to pass to the validator.
  - `by_alias` - Whether to use the field's alias when validating against the provided input data.
  - `by_name` - Whether to use the field's name when validating against the provided input data.

  ## Raises

  - `ValidationError` - If `json_data` is not a JSON string or the object could not be validated.

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.parse_raw`.

  ## Parameters

  - `b` (term())
  - `content_type` (term())
  - `encoding` (term())
  - `proto` (term())
  - `allow_pickle` (term())

  ## Returns

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

  @doc """
  !!! abstract "Usage Documentation"

  [`model_dump`](https://docs.pydantic.dev/latest/concepts/serialization/#python-mode)

  Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

  ## Parameters

  - `mode` - The mode in which `to_python` should run. If mode is 'json', the output will only contain JSON serializable types. If mode is 'python', the output may contain non-JSON-serializable Python objects.
  - `include` - A set of fields to include in the output.
  - `exclude` - A set of fields to exclude from the output.
  - `context` - Additional context to pass to the serializer.
  - `by_alias` - Whether to use the field's alias in the dictionary key if defined.
  - `exclude_unset` - Whether to exclude fields that have not been explicitly set.
  - `exclude_defaults` - Whether to exclude fields that are set to their default value.
  - `exclude_none` - Whether to exclude fields that have a value of `None`.
  - `exclude_computed_fields` - Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated `round_trip` parameter instead.
  - `round_trip` - If True, dumped values should be valid as input for non-idempotent types such as Json[T].
  - `warnings` - How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors, "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
  - `fallback` - A function to call when an unknown value is encountered. If not provided, a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.
  - `serialize_as_any` - Whether to serialize fields with duck-typing serialization behavior.

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.parse_obj`.

  ## Parameters

  - `obj` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness._get_value`.

  ## Parameters

  - `args` (term())
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.dict`.

  ## Parameters

  - `include` ((((MapSet.t(integer()) | MapSet.t(String.t())) | term()) | term()) | nil keyword-only default: None)
  - `exclude` ((((MapSet.t(integer()) | MapSet.t(String.t())) | term()) | term()) | nil keyword-only default: None)
  - `by_alias` (boolean() keyword-only default: False)
  - `exclude_unset` (boolean() keyword-only default: False)
  - `exclude_defaults` (boolean() keyword-only default: False)
  - `exclude_none` (boolean() keyword-only default: False)

  ## Returns

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

  @doc """
  Creates a new instance of the `Model` class with validated data.

  Creates a new model setting `__dict__` and `__pydantic_fields_set__` from trusted or pre-validated data.
  Default values are respected, but no other validation is performed.

  !!! note
      `model_construct()` generally respects the `model_config.extra` setting on the provided model.
      That is, if `model_config.extra == 'allow'`, then all extra passed values are added to the model instance's `__dict__`
      and `__pydantic_extra__` fields. If `model_config.extra == 'ignore'` (the default), then all extra passed values are ignored.
      Because no validation is performed with a call to `model_construct()`, having `model_config.extra == 'forbid'` does not result in
      an error if extra values are passed, but they will be ignored.

  ## Parameters

  - `_fields_set` - A set of field names that were originally explicitly set during instantiation. If provided, this is directly used for the [`model_fields_set`][pydantic.BaseModel.model_fields_set] attribute. Otherwise, the field names from the `values` argument will be used.
  - `values` - Trusted or pre-validated data dictionary.

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness._calculate_keys`.

  ## Parameters

  - `args` (term())
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.dump_state`.

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.schema_json`.

  ## Parameters

  - `by_alias` (boolean() keyword-only default: True)
  - `ref_template` (String.t() keyword-only default: '#/$defs/{model}')
  - `dumps_kwargs` (term())

  ## Returns

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

  @doc """
  Returns a copy of the model.

  !!! warning "Deprecated"
      This method is now deprecated; use `model_copy` instead.

  If you need `include` or `exclude`, use:

  ```python {test="skip" lint="skip"}
  data = self.model_dump(include=include, exclude=exclude, round_trip=True)
  data = {**data, **(update or {})}
  copied = self.model_validate(data)
  ```

  ## Parameters

  - `include` - Optional set or mapping specifying which fields to include in the copied model.
  - `exclude` - Optional set or mapping specifying which fields to exclude in the copied model.
  - `update` - Optional dictionary of field-value pairs to override field values in the copied model.
  - `deep` - If True, the values of fields that are Pydantic models will be deep-copied.

  ## Returns

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

  @doc """
  Validate the given object with string data against the Pydantic model.



  ## Parameters

  - `obj` - The object containing string data to validate.
  - `strict` - Whether to enforce types strictly.
  - `extra` - Whether to ignore, allow, or forbid extra data during model validation. See the [`extra` configuration value][pydantic.ConfigDict.extra] for details.
  - `context` - Extra variables to pass to the validator.
  - `by_alias` - Whether to use the field's alias when validating against the provided input data.
  - `by_name` - Whether to use the field's name when validating against the provided input data.

  ## Returns

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

  @doc """
  Try to rebuild the pydantic-core schema for the model.

  This may be necessary when one of the annotations is a ForwardRef which could not be resolved during
  the initial attempt to build the schema, and automatic rebuilding fails.

  ## Parameters

  - `force` - Whether to force the rebuilding of the model schema, defaults to `False`.
  - `raise_errors` - Whether to raise errors, defaults to `True`.
  - `_parent_namespace_depth` - The depth level of the parent namespace, defaults to 2.
  - `_types_namespace` - The types namespace, defaults to `None`.

  ## Returns

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

  @doc """
  Return a new Signature class with identical fields and new instructions.

  This method does not mutate `cls`. It constructs a fresh Signature
  class using the current fields and the provided `instructions`.

  ## Parameters

  - `instructions` - Instruction text to attach to the new signature. (type: `String.t()`)

  ## Examples

      ```python
      import dspy

      class MySig(dspy.Signature):
      input_text: str = dspy.InputField(desc="Input text")
      output_text: str = dspy.OutputField(desc="Output text")

      NewSig = MySig.with_instructions("Translate to French.")
      assert NewSig is not MySig
      assert NewSig.instructions == "Translate to French."
      ```

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness._iter`.

  ## Parameters

  - `args` (term())
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Return a new Signature class without the given field.

  If `name` is not present, the fields are unchanged (no error raised).

  ## Parameters

  - `name` - Field name to remove. (type: `String.t()`)

  ## Examples

      ```python
      import dspy

      class MySig(dspy.Signature):
      input_text: str = dspy.InputField(desc="Input sentence")
      temp_field: str = dspy.InputField(desc="Temporary debug field")
      output_text: str = dspy.OutputField(desc="Translated sentence")

      NewSig = MySig.delete("temp_field")
      print(list(NewSig.fields.keys()))

      # No error is raised if the field is not present
      Unchanged = NewSig.delete("nonexistent")
      print(list(Unchanged.fields.keys()))
      ```

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.load_state`.

  ## Parameters

  - `state` (term())

  ## Returns

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

  @doc """
  Insert a field at index 0 of the `inputs` or `outputs` section.



  ## Parameters

  - `name` - Field name to add. (type: `String.t()`)
  - `field` - `InputField` or `OutputField` instance to insert.
  - `type_` - Optional explicit type annotation. If `type_` is `None`, the effective type is resolved by `insert`. (type: `type | None`)

  ## Examples

      ```python
      import dspy

      class MySig(dspy.Signature):
      input_text: str = dspy.InputField(desc="Input sentence")
      output_text: str = dspy.OutputField(desc="Translated sentence")

      NewSig = MySig.prepend("context", dspy.InputField(desc="Context for translation"))
      print(list(NewSig.fields.keys()))
      ```

  ## Returns

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

  @doc """
  Validate a pydantic model instance.



  ## Parameters

  - `obj` - The object to validate.
  - `strict` - Whether to enforce types strictly.
  - `extra` - Whether to ignore, allow, or forbid extra data during model validation. See the [`extra` configuration value][pydantic.ConfigDict.extra] for details.
  - `from_attributes` - Whether to extract data from object attributes.
  - `context` - Additional context to pass to the validator.
  - `by_alias` - Whether to use the field's alias when validating against the provided input data.
  - `by_name` - Whether to use the field's name when validating against the provided input data.

  ## Raises

  - `ValidationError` - If the object could not be validated.

  ## Returns

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

  @doc """
  !!! abstract "Usage Documentation"

  [`model_dump_json`](https://docs.pydantic.dev/latest/concepts/serialization/#json-mode)

  Generates a JSON representation of the model using Pydantic's `to_json` method.

  ## Parameters

  - `indent` - Indentation to use in the JSON output. If None is passed, the output will be compact.
  - `ensure_ascii` - If `True`, the output is guaranteed to have all incoming non-ASCII characters escaped. If `False` (the default), these characters will be output as-is.
  - `include` - Field(s) to include in the JSON output.
  - `exclude` - Field(s) to exclude from the JSON output.
  - `context` - Additional context to pass to the serializer.
  - `by_alias` - Whether to serialize using field aliases.
  - `exclude_unset` - Whether to exclude fields that have not been explicitly set.
  - `exclude_defaults` - Whether to exclude fields that are set to their default value.
  - `exclude_none` - Whether to exclude fields that have a value of `None`.
  - `exclude_computed_fields` - Whether to exclude computed fields. While this can be useful for round-tripping, it is usually recommended to use the dedicated `round_trip` parameter instead.
  - `round_trip` - If True, dumped values should be valid as input for non-idempotent types such as Json[T].
  - `warnings` - How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors, "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
  - `fallback` - A function to call when an unknown value is encountered. If not provided, a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError] error is raised.
  - `serialize_as_any` - Whether to serialize fields with duck-typing serialization behavior.

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.construct`.

  ## Parameters

  - `fields_set` (term() default: None)
  - `values` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.from_orm`.

  ## Parameters

  - `obj` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness._copy_and_set_values`.

  ## Parameters

  - `args` (term())
  - `kwargs` (term())

  ## Returns

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

  @doc """
  Create a new Signature class with the updated field information.

  Returns a new Signature class with the field, name, updated
  with fields[name].json_schema_extra[key] = value.

  ## Parameters

  - `name` - The name of the field to update.
  - `type_` - The new type of the field.
  - `kwargs` - The new values for the field.

  ## Returns

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

  @doc """
  Override this method to perform additional initialization after `__init__` and `model_construct`.

  This is useful if you want to do some validation that requires the entire model to be initialized.

  ## Parameters

  - `context` (term())

  ## Returns

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

  @doc """
  Insert a field at the end of the `inputs` or `outputs` section.



  ## Parameters

  - `name` - Field name to add. (type: `String.t()`)
  - `field` - `InputField` or `OutputField` instance to insert.
  - `type_` - Optional explicit type annotation. If `type_` is `None`, the effective type is resolved by `insert`. (type: `type | None`)

  ## Examples

      ```python
      import dspy

      class MySig(dspy.Signature):
      input_text: str = dspy.InputField(desc="Input sentence")
      output_text: str = dspy.OutputField(desc="Translated sentence")

      NewSig = MySig.append("confidence", dspy.OutputField(desc="Translation confidence"))
      print(list(NewSig.fields.keys()))
      ```

  ## Returns

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

  @doc """
  Compute the class name for parametrizations of generic classes.

  This method can be overridden to achieve a custom naming scheme for generic BaseModels.

  ## Parameters

  - `params` - Tuple of types of the class. Given a generic class `Model` with 2 type variables and a concrete model `Model[str, int]`, the value `(str, int)` would be passed to `params`.

  ## Raises

  - `ArgumentError` - Raised when trying to generate concrete names for non-generic models.

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.json`.

  ## Parameters

  - `include` ((((MapSet.t(integer()) | MapSet.t(String.t())) | term()) | term()) | nil keyword-only default: None)
  - `exclude` ((((MapSet.t(integer()) | MapSet.t(String.t())) | term()) | term()) | nil keyword-only default: None)
  - `by_alias` (boolean() keyword-only default: False)
  - `exclude_unset` (boolean() keyword-only default: False)
  - `exclude_defaults` (boolean() keyword-only default: False)
  - `exclude_none` (boolean() keyword-only default: False)
  - `encoder` (term() | nil keyword-only default: PydanticUndefined)
  - `models_as_dict` (boolean() keyword-only default: PydanticUndefined)
  - `dumps_kwargs` (term())

  ## Returns

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

  @doc """
  Generates a JSON schema for a model class.



  ## Parameters

  - `by_alias` - Whether to use attribute aliases or not.
  - `ref_template` - The reference template.
  - `union_format` - The format to use when combining schemas from unions together. Can be one of:
  - `schema_generator` - To override the logic used to generate the JSON schema, as a subclass of `GenerateJsonSchema` with your desired modifications
  - `mode` - The mode in which to generate the schema.

  ## Returns

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

  @doc """
  !!! abstract "Usage Documentation"

  [`model_copy`](https://docs.pydantic.dev/latest/concepts/models/#model-copy)

  Returns a copy of the model.

  !!! note
      The underlying instance's [`__dict__`][object.__dict__] attribute is copied. This
      might have unexpected side effects if you store anything in it, on top of the model
      fields (e.g. the value of [cached properties][functools.cached_property]).

  ## Parameters

  - `update` - Values to change/add in the new model. Note: the data is not validated before creating the new model. You should trust this data.
  - `deep` - Set to `True` to make a deep copy of the model.

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.validate`.

  ## Parameters

  - `value` (term())

  ## Returns

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

  @doc """
  Compare the JSON schema of two Signature classes.

  ## Parameters

  - `other` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.schema`.

  ## Parameters

  - `by_alias` (boolean() default: True)
  - `ref_template` (String.t() default: '#/$defs/{model}')

  ## Returns

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

  @doc """
  Insert a field at a specific position among inputs or outputs.

  Negative indices are supported (e.g., `-1` appends). If `type_` is omitted, the field's
  existing `annotation` is used; if that is missing, `str` is used.

  ## Parameters

  - `index` - Insertion position within the chosen section; negatives append. (type: `integer()`)
  - `name` - Field name to add. (type: `String.t()`)
  - `field` - InputField or OutputField instance to insert.
  - `type_` - Optional explicit type annotation. (type: `type | None`)

  ## Raises

  - `ArgumentError` - If `index` falls outside the valid range for the chosen section.

  ## Examples

      ```python
      import dspy

      class MySig(dspy.Signature):
      input_text: str = dspy.InputField(desc="Input sentence")
      output_text: str = dspy.OutputField(desc="Translated sentence")

      NewSig = MySig.insert(0, "context", dspy.InputField(desc="Context for translation"))
      print(list(NewSig.fields.keys()))

      NewSig2 = NewSig.insert(-1, "confidence", dspy.OutputField(desc="Translation confidence"))
      print(list(NewSig2.fields.keys()))
      ```

  ## Returns

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

  @doc """
  Get a handler for setting an attribute on the model instance.

  ## Parameters

  - `name` (String.t())
  - `value` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.update_forward_refs`.

  ## Parameters

  - `localns` (term())

  ## Returns

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

  @doc """
  Python method `AnswerCompleteness.parse_file`.

  ## Parameters

  - `path` (term())
  - `content_type` (term())
  - `encoding` (term())
  - `proto` (term())
  - `allow_pickle` (term())

  ## Returns

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

  @spec _abc_impl(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def _abc_impl(ref) do
    SnakeBridge.Runtime.get_attr(ref, :_abc_impl)
  end

  @spec model_computed_fields(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def model_computed_fields(ref) do
    SnakeBridge.Runtime.get_attr(ref, :model_computed_fields)
  end

  @spec model_config(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def model_config(ref) do
    SnakeBridge.Runtime.get_attr(ref, :model_config)
  end

  @spec model_extra(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def model_extra(ref) do
    SnakeBridge.Runtime.get_attr(ref, :model_extra)
  end

  @spec model_fields(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def model_fields(ref) do
    SnakeBridge.Runtime.get_attr(ref, :model_fields)
  end

  @spec model_fields_set(SnakeBridge.Ref.t()) :: {:ok, term()} | {:error, Snakepit.Error.t()}
  def model_fields_set(ref) do
    SnakeBridge.Runtime.get_attr(ref, :model_fields_set)
  end
end