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

defmodule Dspy.Evaluate do
  @moduledoc """
  DSPy Evaluate class.

  This class is used to evaluate the performance of a DSPy program. Users need to provide a evaluation dataset and
  a metric function in order to use this class. This class supports parallel evaluation on the provided dataset.
  """
  def __snakebridge_python_name__, do: "dspy"
  def __snakebridge_python_class__, do: "Evaluate"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Args:

  devset (list[dspy.Example]): the evaluation dataset.
      metric (Callable): The metric function to use for evaluation.
      num_threads (Optional[int]): The number of threads to use for parallel evaluation.
      display_progress (bool): Whether to display progress during evaluation.
      display_table (Union[bool, int]): Whether to display the evaluation results in a table.
          If a number is passed, the evaluation results will be truncated to that number before displayed.
      max_errors (Optional[int]): The maximum number of errors to allow before
          stopping evaluation. If ``None``, inherits from ``dspy.settings.max_errors``.
      provide_traceback (Optional[bool]): Whether to provide traceback information during evaluation.
      failure_score (float): The default score to use if evaluation fails due to an exception.
      save_as_csv (Optional[str]): The file name where the csv will be saved.
      save_as_json (Optional[str]): The file name where the json will be saved.

  ## Parameters

  - `devset` (list(term()) keyword-only, required)
  - `metric` (term() | nil keyword-only default: None)
  - `num_threads` (term() keyword-only default: None)
  - `display_progress` (boolean() keyword-only default: False)
  - `display_table` (term() keyword-only default: False)
  - `max_errors` (term() keyword-only default: None)
  - `provide_traceback` (term() keyword-only default: None)
  - `failure_score` (float() keyword-only default: 0.0)
  - `save_as_csv` (term() keyword-only default: None)
  - `save_as_json` (term() keyword-only default: None)
  - `kwargs` (term())
  """
  @spec new(keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(opts \\ []) do
    kw_keys = opts |> Keyword.keys() |> Enum.map(&to_string/1)
    missing_kw = ["devset"] |> Enum.reject(&(&1 in kw_keys))

    if missing_kw != [] do
      raise ArgumentError,
            "Missing required keyword-only arguments: " <> Enum.join(missing_kw, ", ")
    end

    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [], opts)
  end

  @doc """
  Construct a pandas DataFrame from the specified result list.

  Let's not try to change the name of this method as it may be patched by external tracing tools.

  ## Parameters

  - `results` - The list of results to construct the result DataFrame from.
  - `metric_name` - The name of the metric used for evaluation.

  ## Returns

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

  @doc """
  Display the specified result DataFrame in a table format.



  ## Parameters

  - `result_df` - The result DataFrame to display.
  - `display_table` - Whether to display the evaluation results in a table. If a number is passed, the evaluation results will be truncated to that number before displayed.
  - `metric_name` - The name of the metric used for evaluation.

  ## Returns

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

  @doc """
  Python method `Evaluate._prepare_results_output`.

  ## Parameters

  - `results` (list({term(), term(), term()}))
  - `metric_name` (String.t())

  ## Returns

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