34 lines
1.1 KiB
Markdown
34 lines
1.1 KiB
Markdown
|
# 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)`.
|