Usage-based billing from AI agent tool-call logs

Who it is for

API and MCP providers who sell metered access to autonomous agents, and platform teams who bill agent tool calls per unit. If your meter and your payment authorizations disagree, you either under-bill or charge for usage you cannot defend. This pack finds the disagreement first.

Quick start

sudo bash install.sh --no-service
cp examples/usage_ledger.json my_ledger.json
./venv/bin/python agent.py --ledger my_ledger.json meter
./venv/bin/python agent.py --ledger my_ledger.json report --out usage_report.md

Each usage event needs event_id, customer_id, sku, a numeric quantity, an ISO timestamp, and the authorization_id that covers it. Anything missing or unreadable becomes an exception, never a silent charge.

local usage_ledger.json
        |
        v
deduplicate --> check authorization --> price and meter --> reconcile quota + authorized amount
                                                                    |
                                              billable evidence -----+--> Markdown / JSON report
                                                                    |
                                                                    +--> optional BYO-LLM brief

What lands in each bucket

Honest operating modes

No API key or network call is required. The optional CLI uses the subscription already connected on the machine. This agent produces evidence: it never charges a card, captures a payment, issues an invoice, or changes a customer account.

Commands

python agent.py --ledger my_ledger.json meter
python agent.py --ledger my_ledger.json --period-start 2026-07-01 --period-end 2026-07-31 meter
python agent.py --ledger my_ledger.json report --out usage_report.md
python agent.py --ledger my_ledger.json brief
python agent.py status
python test_agent.py

See CUSTOMIZE.md to connect your own event stream and CHECKLIST.md before you bill from the output.

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.