# Usage Ledger and Spend Windows

`llm_connect.usage` stores append-only spend events for operator cost reporting.
It is separate from `QualityLedger` (adaptive routing quality signals).

## UsageEvent

Each event records provider, model, token counts, estimated `cost_usd` /
`cost_eur`, cost/FX sources, call `source` (`cli` | `server` | `library`),
and `recorded_at` (UTC).

## Paths

1. Explicit `--ledger` / constructor path
2. Env `LLM_CONNECT_USAGE_LEDGER`
3. `$XDG_DATA_HOME/llm-connect/usage.jsonl`
4. `~/.local/share/llm-connect/usage.jsonl`

Library and server auto-recording only runs when `LLM_CONNECT_USAGE_LEDGER` is
set (opt-in). CLI `run` records by default to the resolved path unless
`--no-ledger`.

## Week windows

`week_window("current"|"last", tz=...)` returns Monday-based half-open ranges
in local time (default `Europe/Berlin`, override with `LLM_CONNECT_TZ` or
`--tz`):

- **current**: Monday 00:00 → now
- **last**: previous Monday 00:00 → this Monday 00:00 (full Mon–Sun week)

`UsageLedger.sum_range(start, end)` aggregates tokens and costs for
`[start, end)`.