coulomb/llm-connect
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
llm-connect/contracts/functional/usage-ledger.md
tegwick 09aa1f3604
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / container-smoke (push) Has been cancelled
Details
Implement LLM-WP-0007: Kimi K3 default and EUR spend reporting 
Add moonshotai/kimi-k3 as OpenRouter basemodel default after live smoke,
USD→EUR cost conversion, append-only usage ledger, and CLI run/cost/spend
week commands with token and euro reporting.
2026-08-03 22:00:34 +02:00

1.1 KiB
Raw Blame History

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).