tokenbill 0.1.0__tar.gz

tokenbill-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Something is wrong, or a number in the report looks off
+labels: ["bug"]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: Token Bill version
+      description: Output of `tokenbill --version`.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Python version and OS
+      placeholder: "Python 3.12.4, macOS 15"
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Exact command
+      description: The full command line you ran, including flags and seed.
+      render: shell
+      placeholder: tokenbill analyze trace.jsonl -o report.html
+    validations:
+      required: true
+  - type: dropdown
+    id: trace-source
+    attributes:
+      label: Trace source
+      options:
+        - Bundled demo scenario (synthetic)
+        - Recorded with tokenbill.instrument
+        - Converted or hand-written JSONL
+    validations:
+      required: true
+  - type: textarea
+    id: trace-line
+    attributes:
+      label: One redacted trace line (if not the bundled demo)
+      description: >
+        One representative line of your trace JSONL. IMPORTANT — trace lines
+        contain your prompts, tool definitions, and conversation history:
+        redact all text content before pasting. Field names, shapes, and the
+        `usage` numbers are what matter for debugging; keep those intact.
+      render: json
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened vs. what you expected
+      description: >
+        Include the full traceback or the wrong output verbatim. If a dollar
+        or token number looks wrong, say which number and what you expected
+        it to be (and why).
+    validations:
+      required: true

tokenbill-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/sedai77/tokenbill-llm-agent-cost-profiler/security/advisories/new
+    about: Please report security issues privately — see SECURITY.md.

tokenbill-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,40 @@
+name: Feature request
+description: Propose a new breaker kind, scenario, adapter, or capability
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What waste are you trying to find, or what workflow are you unblocking?
+      description: >
+        The underlying need, not the mechanism — e.g. "my agent alternates
+        between two models and I can't see which one burns the cache", not
+        just "add flag X".
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: >
+        Sketch the interface (CLI flag, function signature, report section).
+        For a new breaker kind: give the detection rule precisely enough to
+        unit-test, plus the one-sentence fix it would attach. For a new
+        simulator scenario: state its assumptions the way DESIGN.md's
+        assumption table does. Say how a planted-waste demo scenario could
+        validate it end to end.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+  - type: checkboxes
+    id: constraints
+    attributes:
+      label: Project constraints
+      options:
+        - label: This can be built with the Python standard library only (no new runtime dependencies; the recorder keeps duck-typing provider SDKs, never importing them).
+          required: true
+        - label: Every dollar figure this produces is either derived from real billed usage (exact) or clearly labeled approximate — never an approximation presented as billed.
+          required: true

tokenbill-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## What & why
+
+<!-- One or two sentences. Link the issue if there is one. -->
+
+## Checklist
+
+- [ ] `uv run --python 3.12 --extra dev pytest -q` passes locally (includes the
+      flagship planted-waste recovery test).
+- [ ] `uv run --python 3.12 --extra dev ruff check .` is clean.
+- [ ] No new runtime dependencies (stdlib only; `instrument.py` duck-types the
+      SDK client and never imports `anthropic`).
+- [ ] Tests added/updated for the change; nothing here hits the network or
+      needs an API key — CI has no secrets and never will.
+- [ ] Every new number surfaced to users is either derived from billed `usage`
+      (exact) or labeled approximate; no approximation is presented as billed.
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` for user-visible changes.
+- [ ] If a metric definition, cache-rule constant, or pricing entry changed:
+      `DESIGN.md`, the report's methodology footnotes, and the flagship test's
+      derived expectations are updated together — and pricing changes cite the
+      published pricing doc in the source comment.
+
+## Anything reviewers should focus on?
+
+<!-- Subtle spots, e.g. canonical-rendering byte stability, approx-vs-billed
+     labeling, TTL edge cases in the simulator, seed scoping. -->

tokenbill-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+# CI: lint + unit tests + the offline demo as pipeline proof.
+#
+# Deliberately NO live-API job: Token Bill needs no API keys at all. The
+# `demo` job runs the entire real pipeline (synthetic planted-waste traces ->
+# analyzer -> cache simulator -> breaker detection -> HTML report) offline,
+# and the unit matrix includes tests/test_demo_recovers_planted_waste.py,
+# which asserts the analyzer recovers the exact waste the demo traces plant.
+# That is the correctness proof, and it needs zero keys and zero network.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    name: lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: ruff check
+        run: uv run --extra dev ruff check .
+
+  unit:
+    name: unit (py ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: pytest
+        run: uv run --python ${{ matrix.python }} --extra dev pytest -q
+
+  demo:
+    name: offline demo (no keys, no network)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Run the full pipeline offline
+        run: uv run tokenbill demo -o /tmp/report.html
+      - name: Report must exist and be non-empty
+        run: test -s /tmp/report.html

tokenbill-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+# Release pipeline, triggered by pushing a v* tag (e.g. v0.1.0).
+#
+# No API tokens anywhere: PyPI uses Trusted Publishing (OIDC).
+# One-time setup by the repo owner:
+#   1. pypi.org -> account -> Publishing -> add a (pending) trusted publisher:
+#      project "tokenbill", owner "sedai77",
+#      repository "tokenbill-llm-agent-cost-profiler",
+#      workflow "release.yml", environment "pypi".
+#   2. GitHub repo Settings -> Environments -> create "pypi".
+# Then: bump __version__ in tokenbill/__init__.py, move the CHANGELOG.md
+# Unreleased entries into a dated section, and push the matching tag.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: build (wheel + sdist)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - name: Tag must match the package version
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          if [ ! -f "dist/tokenbill-${version}.tar.gz" ]; then
+            echo "tag ${GITHUB_REF_NAME} does not match the built version:" >&2
+            ls dist/ >&2
+            echo "bump __version__ in tokenbill/__init__.py before tagging" >&2
+            exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    name: publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC is the whole credential — no token, no secret
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub release
+    needs: [build, pypi]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract this version's notes from CHANGELOG.md
+        run: |
+          awk -v heading="## [${GITHUB_REF_NAME#v}]" '
+            index($0, heading) == 1 { found = 1; next }
+            found && (/^## / || /^\[.*\]: /) { exit }
+            found { print }
+          ' CHANGELOG.md > notes.md
+          if [ ! -s notes.md ]; then
+            echo "no CHANGELOG.md section for ${GITHUB_REF_NAME#v}" >&2
+            echo "See CHANGELOG.md." > notes.md
+          fi
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "Token Bill ${GITHUB_REF_NAME#v}" \
+            --notes-file notes.md

tokenbill-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Token Bill artifacts (root-anchored — never swallow tests/data/)
+/report.html
+/trace*.jsonl
+/data/
+
+# Environment / OS / editor
+.env
+.DS_Store
+.idea/
+.vscode/

tokenbill-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to Token Bill are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-26
+
+### Added
+
+- Trace schema `tokenbill/trace@1`: JSONL, one API call per line (full request
+  payload + real billed usage), with strict validation and precise
+  `TraceError` messages, plus canonical rendering (tools → system → messages)
+  as the byte-level substrate for prefix comparison.
+- Per-call and per-run **token waterfalls** computed from real billed `usage`:
+  cache reads / cache writes / uncached input / output, in tokens and dollars.
+- **Redundancy analysis**: the share of cumulative billed input spend that was
+  re-sending byte-identical prefix the model had already seen and that was
+  *not* served from cache — labeled approximate, since it splits exact billed
+  totals by character fractions.
+- **Cache simulator** replaying each run under the provider's documented
+  prompt-caching rules in four priced scenarios: as-billed, no-cache,
+  optimal-cache, and fixed-cache (after repairing detected breakers), with a
+  validation hook comparing predicted vs. billed cache reads whenever the
+  trace shows real cache activity.
+- **Cache-breaker detection** with classified causes — volatile system prompt,
+  tool churn, history rewrite, model switch, missing breakpoint — each with
+  the evidence span, a one-sentence concrete fix, and the estimated dollars
+  recovered.
+- `tokenbill demo`: four deterministic synthetic coding-agent scenarios with
+  *planted* waste patterns — zero keys, zero network. The flagship test
+  (`tests/test_demo_recovers_planted_waste.py`) asserts the analyzer recovers
+  exactly the waste the traces plant, so the demo doubles as the correctness
+  certificate.
+- `tokenbill analyze`: aligned terminal summary plus a single self-contained
+  HTML report (inline CSS, inline SVG waterfalls and scenario bars,
+  dark/light via `prefers-color-scheme`, zero external resources);
+  `--model-price MODEL=IN,OUT` for pricing unknown or self-hosted models.
+- `tokenbill.instrument.Recorder`: records real traces by duck-type-wrapping
+  an Anthropic-SDK-shaped client (`messages.create` and `messages.stream`,
+  streaming via `get_final_message()`), appending one crash-safe JSONL line
+  per completed call — without ever importing the SDK.
+- Versioned pricing and cache-rule tables with per-entry source comments
+  (verified 2026-07 against the published pricing doc).
+- Zero runtime dependencies (pure standard library); Python 3.10+; typed
+  (PEP 561 `py.typed`).
+
+[Unreleased]: https://github.com/sedai77/tokenbill-llm-agent-cost-profiler/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sedai77/tokenbill-llm-agent-cost-profiler/releases/tag/v0.1.0

tokenbill-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Code of Conduct
+
+This project adopts the spirit and structure of the
+[Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+The short version follows; the linked document governs anything this summary
+leaves ambiguous.
+
+## Our pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+Token Bill a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, religion, or sexual identity
+and orientation.
+
+## Our standards
+
+Behavior that keeps this a good place to work:
+
+- Being kind and welcoming to newcomers and disagreeing with ideas, not people.
+- Giving and gracefully accepting constructive review feedback.
+- Owning mistakes, apologizing to those affected, and learning from them.
+- Focusing on what is best for the project and its users.
+
+Behavior that is not acceptable:
+
+- Sexualized language or imagery, and sexual attention of any kind.
+- Trolling, insults, personal or political attacks, and sustained disruption.
+- Public or private harassment.
+- Publishing others' private information (physical or email address, etc.)
+  without their explicit permission.
+- Any other conduct that would reasonably be considered inappropriate in a
+  professional setting.
+
+## Scope and enforcement
+
+This code applies in all project spaces (issues, pull requests, discussions)
+and whenever someone is representing the project in public.
+
+Report violations privately to the maintainers via
+[GitHub's report-abuse flow](https://github.com/contact/report-abuse) or by
+opening a [private security advisory](https://github.com/sedai77/tokenbill-llm-agent-cost-profiler/security/advisories/new)
+marked "conduct". Maintainers will review every report, keep reporters'
+identities confidential, and respond with actions proportionate to the
+violation — from a warning, to temporary interaction limits, to a permanent
+ban — following the Contributor Covenant's enforcement guidelines.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available under CC BY 4.0.

tokenbill-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to Token Bill
+
+Thanks for helping make agent bills explainable. This document covers the
+mechanics; [docs/SPEC.md](docs/SPEC.md) is the authoritative contract for the
+internals — when this file and the spec disagree, the spec wins.
+
+## Ground rules
+
+- **Zero runtime dependencies is a feature, not an accident.** The package
+  must import and run on a bare Python 3.10+ install — no exceptions, not
+  even optional extras. The recorder (`tokenbill/instrument.py`) duck-types
+  the Anthropic SDK client and must never import `anthropic`. PRs that add a
+  runtime dependency will be declined.
+- **The honesty rules are product law.** Every dollar total comes from real
+  billed `usage` fields — exact. Character-based tokenization
+  (`approx_tokens`, chars ÷ 3.7) is used *only* for proportional attribution
+  and divergence localization, is always rescaled so segments sum to the
+  billed total, and is labeled "approx" everywhere it surfaces. A PR that
+  presents an approximate number as billed will be declined regardless of how
+  useful the number is.
+- **Determinism is load-bearing.** Every stochastic step takes an explicit
+  `seed` and derives its stream via `common.rng(seed, *scope)`. Never call
+  `random` module-level functions or `hash()` for anything reproducible.
+- **The flagship test is the contract.**
+  `tests/test_demo_recovers_planted_waste.py` asserts the analyzer, simulator,
+  and breaker detector recover the demo traces' planted waste, with
+  expectations derived from the documented usage construction. If your change
+  breaks it, either the instruments are wrong or the traces changed — either
+  way, that is a design conversation, not a tolerance bump.
+
+## Development setup
+
+We use [uv](https://docs.astral.sh/uv/). No install step is needed beyond
+cloning:
+
+```bash
+git clone https://github.com/sedai77/tokenbill-llm-agent-cost-profiler
+cd tokenbill-llm-agent-cost-profiler
+
+# Run the full offline pipeline
+uv run tokenbill demo -o report.html
+
+# Tests (any supported interpreter; CI runs 3.10 and 3.13)
+uv run --python 3.12 --extra dev pytest -q
+
+# Lint
+uv run --python 3.12 --extra dev ruff check .
+```
+
+Or via the Makefile: `make demo`, `make test`, `make lint`.
+
+## Tests
+
+Everything passes offline — no network, no API keys, ever. CI has no secrets
+and never will. Tests for the recorder use a tiny fake client double (a few
+lines), never the real SDK. Tests that need trace input generate it from
+`tokenbill/demo_traces.py` or build `Call` objects inline — do not add tests
+that download anything or check in large trace fixtures containing real
+prompts.
+
+## Style
+
+- `from __future__ import annotations`, full type hints, frozen dataclasses
+  for value types.
+- Loggers are named `logging.getLogger("tokenbill.<module>")`.
+- Docstrings on public functions; comments only for invariants the code
+  cannot express.
+- `ruff check .` must pass (config in `pyproject.toml`; line length 100).
+
+## Submitting changes
+
+1. Fork, branch, and keep the change focused.
+2. Add or update tests next to the code you touched.
+3. Update `CHANGELOG.md` under `[Unreleased]` for user-visible changes.
+4. Confirm `pytest -q` and `ruff check .` are clean.
+5. Open the PR — the template walks through the checklist.
+
+Metric definitions, cache-rule constants, and pricing entries are public API:
+changing one changes what a dollar figure means. Such changes need a matching
+update to [DESIGN.md](DESIGN.md), the report's methodology footnotes, and the
+flagship test's derived expectations — together, in the same PR. Pricing and
+cache-rule edits must cite the published pricing doc in the entry's source
+comment; the values are re-verified before each release.
+
+## Releasing (maintainers)
+
+1. Re-verify the pricing table against the published pricing doc (see the
+   comment in `tokenbill/pricing.py`).
+2. Move `[Unreleased]` entries into a new dated section in `CHANGELOG.md`.
+3. Bump `__version__` in `tokenbill/__init__.py`.
+4. Tag `v<version>` and push the tag. `release.yml` builds, verifies the tag
+   matches the package version, publishes to PyPI via Trusted Publishing (no
+   tokens), and creates a GitHub release with the changelog section as notes.