# Generated by SnakeBridge v0.13.0 - DO NOT EDIT MANUALLY
# Regenerate with: mix compile
# Library: dspy 3.1.2
# Python module: dspy.utils.usage_tracker
# Python class: UsageTracker

defmodule Dspy.Utils.UsageTrackerClass3 do
  @moduledoc """
  Tracks LM usage data within a context.
  """
  def __snakebridge_python_name__, do: "dspy.utils.usage_tracker"
  def __snakebridge_python_class__, do: "UsageTracker"
  def __snakebridge_library__, do: "dspy"
  @opaque t :: SnakeBridge.Ref.t()

  @doc """
  Initialize self.  See help(type(self)) for accurate signature.
  """
  @spec new(keyword()) :: {:ok, SnakeBridge.Ref.t()} | {:error, Snakepit.Error.t()}
  def new(opts \\ []) do
    SnakeBridge.Runtime.call_class(__MODULE__, :__init__, [], opts)
  end

  @doc """
  Usage tracking utilities for DSPy.

  ## Parameters

  - `usage_entry` (%{optional(String.t()) => term()})

  ## Returns

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

  @doc """
  Usage tracking utilities for DSPy.

  ## Parameters

  - `usage_entry1` (term())
  - `usage_entry2` (term())

  ## Returns

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

  @doc """
  Add a usage entry to the tracker.

  ## Parameters

  - `lm` (String.t())
  - `usage_entry` (%{optional(String.t()) => term()})

  ## Returns

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

  @doc """
  Calculate total tokens from all tracked usage.

  ## Returns

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