Nous.Usage (nous v0.13.3)

Tracks resource usage for agent runs.

Usage tracking helps monitor costs and performance across agent executions. You can aggregate usage from multiple agent runs to track total consumption.

Example

usage = Usage.new()
usage = Usage.inc_requests(usage)
usage = Usage.add_tokens(usage, input: 100, output: 50)
IO.inspect(usage.total_tokens) # 150

Summary

Types

t()

Functions

add(u1, u2)

Add two usage trackers together.

add_tokens(usage, opts)

Add token counts from options.

from_openai(openai_usage)

Create usage from OpenAI API usage format.

inc_requests(usage)

Increment request count by 1.

inc_tool_calls(usage, count \\ 1)

Increment tool call count.

new()

Create a new empty usage tracker.

Types

t()

@type t() :: %Nous.Usage{
  input_tokens: non_neg_integer(),
  output_tokens: non_neg_integer(),
  requests: non_neg_integer(),
  tool_calls: non_neg_integer(),
  total_tokens: non_neg_integer()
}

Functions

add(u1, u2)

@spec add(t(), t()) :: t()

Add two usage trackers together.

Useful for aggregating usage across multiple agent runs.

Example

usage1 = %Usage{requests: 1, total_tokens: 100}
usage2 = %Usage{requests: 2, total_tokens: 200}
total = Usage.add(usage1, usage2)
# %Usage{requests: 3, total_tokens: 300}

add_tokens(usage, opts)

@spec add_tokens(
  t(),
  keyword()
) :: t()

Add token counts from options.

Options

:input - Number of input tokens (default: 0)
:output - Number of output tokens (default: 0)

Example

usage = Usage.new()
usage = Usage.add_tokens(usage, input: 50, output: 30)
# %Usage{input_tokens: 50, output_tokens: 30, total_tokens: 80}

from_openai(openai_usage)

@spec from_openai(map()) :: t()

Create usage from OpenAI API usage format.

Converts the usage object from OpenAI responses to our format.

Example

openai_usage = %{
  prompt_tokens: 100,
  completion_tokens: 50,
  total_tokens: 150
}
usage = Usage.from_openai(openai_usage)
# %Usage{input_tokens: 100, output_tokens: 50, total_tokens: 150}

inc_requests(usage)

@spec inc_requests(t()) :: t()

Increment request count by 1.

Example

usage = Usage.new() |> Usage.inc_requests()
# %Usage{requests: 1, ...}

inc_tool_calls(usage, count \\ 1)

@spec inc_tool_calls(t(), non_neg_integer()) :: t()

Increment tool call count.

Example

usage = Usage.new() |> Usage.inc_tool_calls(3)
# %Usage{tool_calls: 3, ...}

new()

@spec new() :: t()

Create a new empty usage tracker.

Example

usage = Usage.new()
# %Usage{requests: 0, total_tokens: 0, ...}