# `ReqManagedAgents.Usage`
[🔗](https://github.com/cash-mckeeman/req_managed_agents/blob/v0.14.0/req_managed_agents/lib/req_managed_agents/usage.ex#L1)

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.

# `input_token_basis`

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

# `raw`

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

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

# `t`

```elixir
@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()
}
```

# `add`

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

Adds contributions once; missing measurements make their total incomplete.

# `new`

```elixir
@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`

```elixir
@spec zero() :: t()
```

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*