<!-- Sema documentation — std.usage
     Sema is a new AI-native, neurosymbolic programming language most models
     have not been trained on. Full corpus: https://sema.49.12.246.95.sslip.io/llms-full.txt
     Install language support: https://sema.49.12.246.95.sslip.io/install-skill/ -->

# std.usage

> Reflected API reference for the Sema standard-library module std.usage.

> Generated by `sema doc` from `stdlib/sema/usage.sema`. Import with `from std.usage import …`. For a narrative introduction see [std.usage](/stdlib/usage/).

# `usage`

std.usage — model usage accounting (design ①).

Accumulate token usage across calls and price it. Replaces eai-search's
`(result, usage)` tuple threading and SymbolicAI's ~470-line MetadataTracker.
`Pricing` is passed in by the caller — rates are never hardcoded. (For ambient,
automatic accounting see the `with meter as u:` scope, §3.6.)

# `struct Usage`

**Fields**

| field | type | descriptor |
|---|---|---|
| `prompt_tokens` | `int` |  |
| `completion_tokens` | `int` |  |
| `reasoning_tokens` | `int` |  |
| `cached_tokens` | `int` |  |
| `total_calls` | `int` |  |
| `total_tokens` | `int` |  |
| `cost_estimate` | `f64` |  |

# `struct Pricing`

**Fields**

| field | type | descriptor |
|---|---|---|
| `input` | `f64` |  |
| `cached_input` | `f64` |  |
| `output` | `f64` |  |
| `calls` | `f64` |  |

# `zero`

```sema
def zero() -> Usage !{}
```

**Returns** `Usage`

**Effects** `!{}`

# `estimate_cost`

```sema
def estimate_cost(u: Usage, p: Pricing) -> f64 !{}
```

**Parameters**

| name | type |
|---|---|
| `u` | `Usage` |
| `p` | `Pricing` |

**Returns** `f64`

**Effects** `!{}`