ReqManagedAgents.Usage (ReqManagedAgents v0.14.0)

Observed token counts and their measurement coverage.

Input counts retain their provider's meaning, recorded in input_token_basis. Missing cache measurements are nil; measured zero remains zero. When complete? is false, numeric counts are observed subtotals. Completeness covers represented contributions, not additional unfinished provider work.

Summary

Types

input_token_basis()

raw()

Provider-verbatim usage objects; their keys and values are not interpreted here.

t()

Functions

add(acc, usage)

Adds contributions once; missing measurements make their total incomplete.

new(usage)

Validates a closed atom-keyed projection or an existing usage struct.

zero()

The known empty accumulation identity, distinct from an absent usage report.

Types

input_token_basis()

@type input_token_basis() :: :uncached | :inclusive | :unknown | :none

raw()

@type raw() :: [map()]

Provider-verbatim usage objects; their keys and values are not interpreted here.

t()

@type t() :: %ReqManagedAgents.Usage{
  cache_creation_input_tokens: non_neg_integer() | nil,
  cache_read_input_tokens: non_neg_integer() | nil,
  complete?: boolean(),
  input_token_basis: input_token_basis(),
  input_tokens: non_neg_integer(),
  output_tokens: non_neg_integer(),
  raw: raw()
}

Functions

add(acc, usage)

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

Adds contributions once; missing measurements make their total incomplete.

new(usage)

@spec new(map() | t()) :: {:ok, t()} | {:error, {:invalid_usage, atom()}}

Validates a closed atom-keyed projection or an existing usage struct.

Missing or nil input/output becomes zero with incomplete coverage; other invalid input/output returns a tagged error. Invalid optional cache counts become nil. An explicit false coverage flag cannot be upgraded.

zero()

@spec zero() :: t()

The known empty accumulation identity, distinct from an absent usage report.