# `Sycophant.Usage`

Token usage statistics from an LLM response.

Reports input and output token counts, plus optional cache hit/miss
information for providers that support prompt caching.

## Examples

    iex> %Sycophant.Usage{input_tokens: 10, output_tokens: 25}
    #Sycophant.Usage<%{in: 10, out: 25}>

# `t`

```elixir
@type t() :: %Sycophant.Usage{
  cache_creation_input_tokens: non_neg_integer() | nil,
  cache_read_cost: float() | nil,
  cache_read_input_tokens: non_neg_integer() | nil,
  cache_write_cost: float() | nil,
  input_cost: float() | nil,
  input_tokens: non_neg_integer() | nil,
  output_cost: float() | nil,
  output_tokens: non_neg_integer() | nil,
  pricing: Sycophant.Pricing.t() | nil,
  reasoning_cost: float() | nil,
  reasoning_tokens: non_neg_integer() | nil,
  total_cost: float() | nil
}
```

# `calculate_cost`

```elixir
@spec calculate_cost(t() | nil, Sycophant.Pricing.t() | nil) :: t() | nil
```

Calculates cost fields from token counts and a `Pricing` struct.

Looks up each token component by ID (e.g. `"token.input"`, `"token.output"`)
and computes cost as `tokens * rate / per`. Missing components yield nil costs.

# `from_map`

```elixir
@spec from_map(map()) :: t()
```

Reconstructs a Usage struct from a serialized map.

---

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