# `Planck.Agent.Usage`
[🔗](https://github.com/alexdesousa/planck/blob/v0.2.2/lib/planck/agent/usage.ex#L1)

Accumulated token usage and cost for an agent session.

Updated after every LLM turn via `add_turn/4`. Cost is computed from the
model's per-token rates and accumulated alongside token counts — it never
decreases, even when messages are rewound.

# `t`

```elixir
@type t() :: %Planck.Agent.Usage{
  cost: float(),
  input_tokens: non_neg_integer(),
  output_tokens: non_neg_integer()
}
```

- `:input_tokens` — total input tokens consumed this session
- `:output_tokens` — total output tokens consumed this session
- `:cost` — total cost in USD this session

# `add_turn`

```elixir
@spec add_turn(t(), non_neg_integer(), non_neg_integer(), term()) :: t()
```

Add one turn's token counts and compute its cost from `model`.

Returns the updated struct. The per-turn cost is calculated from the model's
`cost.input` and `cost.output` rates (per million tokens). When the model has
no cost information the cost field is left unchanged.

# `from_opts`

```elixir
@spec from_opts(keyword()) :: t()
```

Build a `Usage` struct from agent start-up keyword options.

Reads `:usage` (a map with `:input_tokens` and `:output_tokens`) and `:cost`
to seed the struct when resuming a previous session.

# `new`

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

Return a zeroed usage struct.

---

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