# `Foresight.Usage`
[🔗](https://github.com/fosferon/foresight/blob/v0.3.2/lib/foresight/usage.ex#L1)

Ledger of the chargeable calls made while serving one operation.

Retain and recall open a ledger in the calling process, the LLM adapter and the
remote embedder record every call they make into it, and the operation closes it
and reports the entries on its result under `"usage"`. Each entry names the kind
of call, the provider and model, the token counts the provider reported, the
request id when one was returned, and whether the call succeeded, so a consumer
can attribute cost deterministically and audit it against the provider's own
records.

`"usage"` is `nil` when no chargeable call happened: local embedders and the Noop
LLM record nothing, so the default configuration is unchanged.

# `entry`

```elixir
@type entry() :: %{required(String.t()) => term()}
```

# `drain`

```elixir
@spec drain() :: [entry()]
```

Close the ledger and return its entries in call order.

# `llm_entry`

```elixir
@spec llm_entry(map(), atom() | String.t() | nil) :: entry()
```

Build an LLM entry from an `LlmCore.LLM.Response`-shaped struct or map.

# `llm_error_entry`

```elixir
@spec llm_error_entry(term(), atom() | String.t() | nil) :: entry()
```

Build an LLM entry for a call that failed before any usage was reported.

# `record`

```elixir
@spec record(map()) :: :ok
```

Record one call. A no-op when no ledger is open, so adapters can always call it.
Missing token counts default to zero; `"status"` defaults to `"ok"`.

# `report`

```elixir
@spec report([entry()]) :: map() | nil
```

Summarise entries for a result: token totals over successful calls plus the
calls themselves. `nil` for an empty ledger.

# `start`

```elixir
@spec start() :: :ok
```

Open a fresh ledger in the current process.

---

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