tokenjam 0.4.2__tar.gz → 0.5.1__tar.gz

{tokenjam-0.4.2 → tokenjam-0.5.1}/CLAUDE.md

@@ -376,7 +376,7 @@ Key runtime dependency: `pytz` is required by DuckDB for `TIMESTAMPTZ` column ha
 - `tokenjam[bloat]` — `llmlingua>=0.2`, used by the Trim analyzer. Pulls PyTorch + transformers (~2GB). Kept out of base install. The analyzer self-registers without the extra installed; the deferred `import llmlingua` inside the analysis function body raises a typed message pointing the user at the install command.
 - Framework extras `[langchain]`, `[crewai]`, `[autogen]`, `[litellm]` for SDK patches.
 - `[dev]` for local development (`pytest`, `ruff`, `mypy`, `httpx`).
-- `[mcp]` for the FastMCP stdio server.
+- `[mcp]` — empty no-op alias. `fastmcp` moved into the base install in v0.3.5 (#101), so the FastMCP stdio server (`tj mcp`) works on a plain `pipx install tokenjam`. The extra is kept so old `tokenjam[mcp]` install commands still succeed; it pulls nothing extra.
 
 ## Further Reading
 
@@ -392,3 +392,4 @@ Key runtime dependency: `pytz` is required by DuckDB for `TIMESTAMPTZ` column ha
 - **Backfill adapters** — `docs/backfill/overview.md` lists the four sources (`claude-code` / `langfuse` / `helicone` / `otlp`) with the partnership-posture framing; per-adapter pages document modes (URL / file), field mapping, idempotency, and v1 limitations.
 - **[docs/policy/overview.md](docs/policy/overview.md)** — read-only preview of the unified policy surface (`tj policy list`). Notes that the `add` / `edit` / `apply` subcommands and the underlying `[policy]` config migration land next sprint.
 - **Internal specs** — `docs/internal/specs/` is reserved for canonical specs that production code references at long-term. Currently empty (sprint specs have been cleaned up after merge); add new ones here when a feature needs a stable, code-referenced source of truth.
+- **[docs/internal/release-smoke-checklist.md](docs/internal/release-smoke-checklist.md)** — fresh-install pre-release gate (clean env → `pipx install` → `tj onboard --claude-code` → verify Lens plan badge + `tj optimize` agree → sane session count). Catches plan-tier / framing regressions a real first-run hits that synthetic-factory tests don't. Its automated counterpart is `tests/integration/test_first_run_roundtrip_239.py`.

{tokenjam-0.4.2 → tokenjam-0.5.1}/CONTRIBUTING.md

@@ -1,14 +1,24 @@
 # Contributing to TokenJam
 
-TokenJam is MIT licensed and welcomes contributions. The codebase was built using parallel Claude Code agents — the `.claude/` task files are intentionally committed so contributors can use the same workflow.
+TokenJam is MIT licensed and welcomes contributions. It's built by AI coding agents, and contributing with one is first-class — see [Using coding agents](#using-coding-agents) below.
+
+## Good first contributions
+
+New here? These are the lowest-friction ways to land your first PR:
+
+- 🟢 **[Good first issues](https://github.com/Metabuilder-Labs/tokenjam/labels/good%20first%20issue)** — scoped tasks tagged ready for newcomers.
+- 💸 **Model pricing** — add a missing model or correct a rate in [`tokenjam/pricing/models.toml`](tokenjam/pricing/models.toml). One file, no issue needed (details below).
+- 🔌 **A framework/provider integration** — they follow one clear pattern; `tokenjam/sdk/integrations/anthropic.py` is the reference. Open an issue first to align on approach.
+
+Questions on any of these? Open an issue — we're happy to point you at a good starting spot.
 
 ## Getting started
 
 ```bash
 git clone https://github.com/Metabuilder-Labs/tokenjam
 cd tokenjam
-pip install -e ".[dev,mcp]"   # editable install with dev tools + MCP support
-pip install anthropic          # for running the toy agent
+pip install -e ".[dev]"   # editable install with dev tools (the MCP server ships in the base install)
+pip install anthropic     # for running the toy agent
 ```
 
 ## Running tests
@@ -48,12 +58,12 @@ tests/factories.py     Span factory — use this in all synthetic tests, never
                        construct NormalizedSpan directly
 ```
 
-## Using Claude Code
+## Using coding agents
 
-This project was built using parallel Claude Code agents. The `.claude/` directory contains the original task files. If you're using Claude Code to contribute:
+TokenJam is built by AI coding agents, and contributing with one is first-class:
 
-- Read `AGENTS.md` at the repo root before starting — it contains the critical rules (DuckDB not SQLite, TOML not YAML, no CLI imports in `tokenjam/core/`, etc.)
-- The task files in `.claude/` show how the codebase was structured and are useful context for larger contributions
+- **Claude Code** — it reads [`CLAUDE.md`](CLAUDE.md) automatically; run `/init` to bring your agent up to speed on the architecture and conventions.
+- **Codex / Gemini / other agents** — read [`AGENTS.md`](AGENTS.md): the critical rules (DuckDB not SQLite, TOML not YAML, no CLI imports in `tokenjam/core/`, etc.) plus a pointer to CLAUDE.md for the full guide.
 
 ## Pricing table contributions
 

{tokenjam-0.4.2 → tokenjam-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tokenjam
-Version: 0.4.2
+Version: 0.5.1
 Summary: TokenJam — local-first OTel-native observability for Autonomous AI agents
 Project-URL: Homepage, https://opencla.watch
 Project-URL: Repository, https://github.com/Metabuilder-Labs/openclawwatch
@@ -68,6 +68,7 @@ TokenJam reads your agent's telemetry and tells you when to downsize, when to tr
 
 [![CI](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml/badge.svg)](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/tokenjam?color=3d8eff&labelColor=0d1117)](https://pypi.org/project/tokenjam/)
+[![Downloads](https://img.shields.io/pypi/dm/tokenjam?color=3d8eff&labelColor=0d1117&label=downloads)](https://pypi.org/project/tokenjam/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3d8eff?labelColor=0d1117)](https://pypi.org/project/tokenjam/)
 [![npm](https://img.shields.io/npm/v/@tokenjam/sdk?color=3d8eff&labelColor=0d1117)](https://www.npmjs.com/package/@tokenjam/sdk)
 [![License: MIT](https://img.shields.io/badge/license-MIT-3d8eff?labelColor=0d1117)](LICENSE)
@@ -81,6 +82,8 @@ pipx install tokenjam
 
 **No cloud · No signup · No vendor lock-in**
 
+<sub>⭐ If TokenJam saves you tokens, **star it** · 👁 **Watch for releases** — we ship often</sub>
+
 </div>
 
 ---
@@ -280,7 +283,13 @@ tj serve               # start Lens + REST API
 - [x] **Daemon DB concurrency** — per-thread DuckDB cursors so the Overview's fan-out doesn't block on a single shared connection (v0.4.1)
 - [x] **Cache cost transparency** — `cache_read` + `cache_write` token columns surfaced in CLI + UI + API (the previously-hidden ~91% cost driver on cache-heavy workloads)
 
-**Up next:**
+**Shipped in 0.5.x:**
+- [x] **Lens Visualizations** — an Analytics pivot explorer (metric × dimension × chart, presets, CSV), stacked cost-by-model, a cache-savings chart, KPI sparklines, a cost-annotated trace waterfall, and consistent series coloring
+- [x] **Merged Dashboard** — the explorer and the triage front-door unified into one default screen, with in-place drill-through from recoverable-waste tiles
+- [x] **First-run polish** — backfill fidelity (session-level traces, cache read/write split, honest session counts), plan-tier-aware framing throughout (subscription users see token-share, never raw spend), an onboarding welcome banner + next-steps guidance, and a contribution funnel
+
+**Up next** (roughly):
+- [ ] Continued Lens polish + per-product visual branding
 - [ ] `tj policy add | edit | apply` — unified rule surface
 - [ ] `tj replay` — replay captured sessions against new model versions
 - [ ] TypeScript framework patches (LangChain JS, OpenAI Agents SDK)
@@ -290,6 +299,21 @@ tj serve               # start Lens + REST API
 
 ---
 
+## Contributing
+
+TokenJam is MIT, and contributions are welcome — from a one-line pricing fix to a whole new framework integration. A few easy on-ramps:
+
+- 🟢 **[Good first issues →](https://github.com/Metabuilder-Labs/tokenjam/labels/good%20first%20issue)** — scoped, newcomer-friendly tasks, ready to pick up.
+- 💸 **Model pricing** — `tokenjam/pricing/models.toml` is community-maintained. Fix a rate or add a model in a single PR — no issue needed.
+- 🔌 **Framework integrations** — provider/framework patches follow one clear pattern (`tokenjam/sdk/integrations/anthropic.py` is the reference). Open an issue first to align on approach.
+- 🤖 **Built with coding agents** — TokenJam is built by AI coding agents, and contributing with one is first-class. **Claude Code:** read [CLAUDE.md](CLAUDE.md) and run `/init` to bring your agent up to speed. **Codex / other agents:** [AGENTS.md](AGENTS.md) has the critical rules.
+
+Setup and the full dev workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+If TokenJam saves you tokens, **⭐ star it** and **👁 watch for releases** — we ship often.
+
+---
+
 <div align="center">
 
 **[tokenjam.dev](https://tokenjam.dev)** · [PyPI](https://pypi.org/project/tokenjam/) · [npm](https://www.npmjs.com/package/@tokenjam/sdk) · [Issues](https://github.com/Metabuilder-Labs/tokenjam/issues)

{tokenjam-0.4.2 → tokenjam-0.5.1}/README.md

@@ -10,6 +10,7 @@ TokenJam reads your agent's telemetry and tells you when to downsize, when to tr
 
 [![CI](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml/badge.svg)](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/tokenjam?color=3d8eff&labelColor=0d1117)](https://pypi.org/project/tokenjam/)
+[![Downloads](https://img.shields.io/pypi/dm/tokenjam?color=3d8eff&labelColor=0d1117&label=downloads)](https://pypi.org/project/tokenjam/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-3d8eff?labelColor=0d1117)](https://pypi.org/project/tokenjam/)
 [![npm](https://img.shields.io/npm/v/@tokenjam/sdk?color=3d8eff&labelColor=0d1117)](https://www.npmjs.com/package/@tokenjam/sdk)
 [![License: MIT](https://img.shields.io/badge/license-MIT-3d8eff?labelColor=0d1117)](LICENSE)
@@ -23,6 +24,8 @@ pipx install tokenjam
 
 **No cloud · No signup · No vendor lock-in**
 
+<sub>⭐ If TokenJam saves you tokens, **star it** · 👁 **Watch for releases** — we ship often</sub>
+
 </div>
 
 ---
@@ -222,7 +225,13 @@ tj serve               # start Lens + REST API
 - [x] **Daemon DB concurrency** — per-thread DuckDB cursors so the Overview's fan-out doesn't block on a single shared connection (v0.4.1)
 - [x] **Cache cost transparency** — `cache_read` + `cache_write` token columns surfaced in CLI + UI + API (the previously-hidden ~91% cost driver on cache-heavy workloads)
 
-**Up next:**
+**Shipped in 0.5.x:**
+- [x] **Lens Visualizations** — an Analytics pivot explorer (metric × dimension × chart, presets, CSV), stacked cost-by-model, a cache-savings chart, KPI sparklines, a cost-annotated trace waterfall, and consistent series coloring
+- [x] **Merged Dashboard** — the explorer and the triage front-door unified into one default screen, with in-place drill-through from recoverable-waste tiles
+- [x] **First-run polish** — backfill fidelity (session-level traces, cache read/write split, honest session counts), plan-tier-aware framing throughout (subscription users see token-share, never raw spend), an onboarding welcome banner + next-steps guidance, and a contribution funnel
+
+**Up next** (roughly):
+- [ ] Continued Lens polish + per-product visual branding
 - [ ] `tj policy add | edit | apply` — unified rule surface
 - [ ] `tj replay` — replay captured sessions against new model versions
 - [ ] TypeScript framework patches (LangChain JS, OpenAI Agents SDK)
@@ -232,6 +241,21 @@ tj serve               # start Lens + REST API
 
 ---
 
+## Contributing
+
+TokenJam is MIT, and contributions are welcome — from a one-line pricing fix to a whole new framework integration. A few easy on-ramps:
+
+- 🟢 **[Good first issues →](https://github.com/Metabuilder-Labs/tokenjam/labels/good%20first%20issue)** — scoped, newcomer-friendly tasks, ready to pick up.
+- 💸 **Model pricing** — `tokenjam/pricing/models.toml` is community-maintained. Fix a rate or add a model in a single PR — no issue needed.
+- 🔌 **Framework integrations** — provider/framework patches follow one clear pattern (`tokenjam/sdk/integrations/anthropic.py` is the reference). Open an issue first to align on approach.
+- 🤖 **Built with coding agents** — TokenJam is built by AI coding agents, and contributing with one is first-class. **Claude Code:** read [CLAUDE.md](CLAUDE.md) and run `/init` to bring your agent up to speed. **Codex / other agents:** [AGENTS.md](AGENTS.md) has the critical rules.
+
+Setup and the full dev workflow are in **[CONTRIBUTING.md](CONTRIBUTING.md)**.
+
+If TokenJam saves you tokens, **⭐ star it** and **👁 watch for releases** — we ship often.
+
+---
+
 <div align="center">
 
 **[tokenjam.dev](https://tokenjam.dev)** · [PyPI](https://pypi.org/project/tokenjam/) · [npm](https://www.npmjs.com/package/@tokenjam/sdk) · [Issues](https://github.com/Metabuilder-Labs/tokenjam/issues)

{tokenjam-0.4.2 → tokenjam-0.5.1}/docs/claude-code-integration.md

@@ -3,7 +3,7 @@
 Monitor every Claude Code session — costs, tool calls, API requests, errors — with two commands:
 
 ```bash
-pipx install 'tokenjam[mcp]'
+pipx install tokenjam
 tj onboard --claude-code
 # Restart Claude Code, then:
 tj status --agent claude-code-<project>
@@ -35,7 +35,7 @@ Claude Code emits OTLP log events which `tj serve` converts into spans — every
 
 ## MCP server
 
-The MCP server is included in the `[mcp]` extra and registered automatically by `tj onboard --claude-code`. It gives Claude Code direct access to your observability data inside the session itself. After restarting Claude Code you have 13 tools available in every session:
+The MCP server ships in the base install (`pipx install tokenjam` — no extra needed) and is registered automatically by `tj onboard --claude-code`. It gives Claude Code direct access to your observability data inside the session itself. After restarting Claude Code you have 13 tools available in every session:
 
 | Tool | What it does |
 |---|---|

{tokenjam-0.4.2 → tokenjam-0.5.1}/docs/installation.md

@@ -52,8 +52,8 @@ TokenJam keeps heavyweight ML dependencies, framework adapters, and the MCP serv
 
 | Extra | What it pulls in | Why it's optional |
 |---|---|---|
-| `tokenjam[mcp]` | `fastmcp` | Only needed for the Claude Code / Codex MCP server (`tj mcp`). Pulled by `tj onboard --claude-code` automatically when invoked through the documented one-liner. |
-| `tokenjam[bloat]` | `llmlingua>=0.2`, transitively PyTorch + transformers (~2GB) | The Trim analyzer (`tj optimize trim`) scores token significance with LLMLingua-2. Most users don't run it; keeping torch out of the base install means `pip install tokenjam` stays small and fast on machines that don't have a GPU/CPU build of torch already. |
+| `tokenjam[mcp]` | nothing (no-op alias) | **No longer needed.** `fastmcp` moved into the base install in v0.3.5, so the Claude Code / Codex MCP server (`tj mcp`) works on a plain `pipx install tokenjam`. The extra is kept as an empty no-op so old `pipx install 'tokenjam[mcp]'` commands still succeed; it pulls nothing extra. |
+| `tokenjam[bloat]` | `llmlingua>=0.2`, transitively PyTorch + transformers (~2GB) | The Trim analyzer (`tj optimize trim`) scores token significance with LLMLingua-2. Most users don't run it; keeping torch out of the base install keeps it small and fast on machines that don't have a GPU/CPU build of torch already. |
 | `tokenjam[langchain]` | `langchain>=0.2` | Convenience pin for `patch_langchain()`; you can also install langchain yourself. |
 | `tokenjam[crewai]` | `crewai>=0.28` | Convenience pin for `patch_crewai()`. |
 | `tokenjam[autogen]` | `pyautogen>=0.2` | Convenience pin for `patch_autogen()`. |
@@ -63,7 +63,7 @@ TokenJam keeps heavyweight ML dependencies, framework adapters, and the MCP serv
 Combine multiple extras:
 
 ```bash
-pipx install 'tokenjam[mcp,bloat]'
+pipx install 'tokenjam[bloat,litellm]'
 ```
 
 ### Bloat extra details

tokenjam-0.5.1/docs/internal/release-smoke-checklist.md

@@ -0,0 +1,126 @@
+# Fresh-install release smoke checklist
+
+A lightweight pre-release gate so **plan-tier / framing regressions can't ship
+silently**. The 0.5.0 first-run review burned real time chasing a "Max 20x"
+framing that turned out to be stale data, not a code bug — there was no
+automated *or* manual signal either way. Run this once against a clean machine
+(or a throwaway VM / container) after publishing a release candidate and before
+announcing the release.
+
+This is distinct from [`tests/manual-pre-release-testing.md`](../../tests/manual-pre-release-testing.md),
+which tests a **branch** via an editable install. This checklist tests the
+**published wheel** the way a brand-new user installs it: `pipx install tokenjam`.
+
+The automated counterpart to this checklist is
+`tests/integration/test_first_run_roundtrip_239.py`, which pins the
+config → backfill → framing contract in CI. This checklist covers the parts CI
+can't: a real `pipx` install, a real `tj onboard --claude-code`, and the
+rendered Lens badge.
+
+## 0. Clean environment
+
+Start from a machine (or container / VM) with **no prior TokenJam state**. On a
+machine you've used before, wipe it first:
+
+```bash
+tj stop 2>/dev/null            # halt any daemon holding the DB / port 7391
+tj uninstall --yes 2>/dev/null # remove launchd / systemd unit files
+pipx uninstall tokenjam 2>/dev/null
+pip3 uninstall -y tokenjam 2>/dev/null
+rm -rf ~/.tj ~/.config/tj .tj  # default DB (~/.tj/telemetry.duckdb), global + project config
+```
+
+Verify nothing lingers:
+
+```bash
+launchctl list | grep tokenjam      # macOS — expect no output
+systemctl --user is-active tokenjam # Linux — expect "inactive"/"unknown"
+which tj                            # expect "not found"
+```
+
+## 1. Fresh install
+
+```bash
+pipx install tokenjam
+tj --version          # matches the release tag (vX.Y.Z)
+```
+
+`pipx`, not `pip` — that's the recommended path (sidesteps PEP 668 on Homebrew
+Python and Debian 12+/Ubuntu 24+).
+
+## 2. Onboard with a known plan
+
+```bash
+tj onboard --claude-code --plan max_5x
+```
+
+Use `--plan max_5x` (non-interactive) so the expected framing is unambiguous.
+This writes `[budget.anthropic] plan = "max_5x"` to the **global** config
+(`~/.config/tj/config.toml`) and auto-runs the Claude Code backfill at the end.
+
+Confirm the config landed:
+
+```bash
+grep -A2 'budget.anthropic' ~/.config/tj/config.toml   # plan = "max_5x"
+```
+
+> If this machine has no `~/.claude/projects/*.jsonl` history, seed a little by
+> running Claude Code a few times first — otherwise the backfill finds nothing
+> and the framing falls back to the config-declared plan (still `max_5x`, but
+> you won't exercise the data path).
+
+## 3. Verify the backfill session count is sane
+
+The onboard backfill prints a summary. Sanity-check it against the table — the
+two must reconcile (the #238 contract):
+
+```bash
+tj status                      # session count, span count, window
+# Compare against the printed "N new / M existing · T total" summary.
+```
+
+Red flags: a "1 session" summary on a machine with months of history (new-only
+reporting — #238), or a session count wildly off from the spans/cost shown.
+
+## 4. Verify the Lens plan badge matches the config
+
+```bash
+tj serve &                     # or rely on the daemon installed by onboard
+open http://localhost:7391/    # macOS; otherwise browse to it
+```
+
+On the **Overview** screen:
+
+- The plan badge / framing reads **Max 5x plan** (subscription), **not** Max 20x
+  or an API-dollar framing.
+- Cost figures render as token-share / "% of cycle", **not** raw API dollars
+  (subscription users never see "spend").
+
+Optionally confirm the raw framing block:
+
+```bash
+curl -s 'http://localhost:7391/api/v1/cost?since=90d' | python3 -m json.tool | grep -A12 '"framing"'
+# expect: "pricing_mode": "subscription", "plan_tier": "max_5x", "plan_monthly_usd": 100.0
+```
+
+## 5. Verify `tj optimize` agrees with Lens
+
+```bash
+tj optimize --since 90d
+```
+
+- The framing must match the Lens badge: subscription / Max 5x, **implied API
+  value** language, token-share savings — never dollar "spend" or a different
+  plan than step 4 showed.
+- Savings lines say "estimated recoverable", never "saves you" (Critical Rule 14).
+
+If Lens and `tj optimize` disagree on the plan, **stop** — that's the exact
+class of regression this gate exists to catch. File a blocker before releasing.
+
+## Pass criteria
+
+- [ ] Clean machine → `pipx install tokenjam` succeeds; `tj --version` == release tag
+- [ ] `tj onboard --claude-code --plan max_5x` writes `plan = "max_5x"` to global config
+- [ ] Backfill summary reconciles with `tj status` (new/existing/total is sane, not new-only)
+- [ ] Lens Overview badge reads **Max 5x** (subscription framing, no API dollars)
+- [ ] `tj optimize` framing agrees with Lens (same plan, implied-value language)

{tokenjam-0.4.2 → tokenjam-0.5.1}/docs/optimize/trim.md

@@ -25,7 +25,7 @@ base install:
 pipx install 'tokenjam[bloat]'
 ```
 
-The base `pip install tokenjam` does NOT pull torch. Trim shows up in
+The base install (`pipx install tokenjam`) does NOT pull torch. Trim shows up in
 `tj optimize` analyzer choices regardless, but running it without the
 extra prints a clear install hint and exits.
 

{tokenjam-0.4.2 → tokenjam-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tokenjam"
-version = "0.4.2"
+version = "0.5.1"
 description = "TokenJam — local-first OTel-native observability for Autonomous AI agents"
 readme = "README.md"
 requires-python = ">=3.10"

{tokenjam-0.4.2 → tokenjam-0.5.1}/sdk-ts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenjam/sdk",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "TypeScript SDK for TokenJam — local-first observability for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

tokenjam-0.5.1/tests/integration/test_analytics.py

@@ -0,0 +1,191 @@
+"""Endpoint tests for the Analytics pivot explorer (#210).
+
+Covers the generalized group-by: metric × group_by × stack_by × filters → a
+grouped series + KPI totals + the plan-tier framing block. The explorer's
+line / bar / hbar views are all client-side pivots of this one `rows` shape.
+"""
+from __future__ import annotations
+
+from datetime import timedelta
+
+import httpx
+import pytest
+
+from tokenjam.api.app import create_app
+from tokenjam.core.config import ProviderBudget, TjConfig
+from tokenjam.core.db import InMemoryBackend
+from tokenjam.core.ingest import IngestPipeline
+from tokenjam.utils.time_parse import utcnow
+from tests.factories import make_llm_span, make_session, make_tool_span
+
+
+def _app(db, config):
+    return create_app(config=config, db=db, ingest_pipeline=IngestPipeline(db=db, config=config))
+
+
+def _seed(db, plan="api"):
+    now = utcnow()
+    for d in range(4):
+        for model, provider, cost in [("claude-opus-4-7", "anthropic", 0.06),
+                                       ("gpt-4o", "openai", 0.03)]:
+            sid = f"s{d}-{model}"
+            db.upsert_session(make_session(session_id=sid, plan_tier=plan, agent_id="cc"))
+            llm = make_llm_span(
+                session_id=sid, agent_id="cc", model=model, provider=provider,
+                input_tokens=2000, output_tokens=300, cost_usd=cost,
+                start_time=now - timedelta(days=d),
+            )
+            db.insert_span(llm)
+            for tool in ["Read", "Bash", "Grep"]:
+                t = make_tool_span(agent_id="cc", tool_name=tool, trace_id=llm.trace_id)
+                t.session_id = sid
+                t.start_time = now - timedelta(days=d)
+                db.insert_span(t)
+
+
+async def _get(db, cfg, qs):
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        return (await c.get("/api/v1/analytics?" + qs)).json()
+
+
+@pytest.mark.asyncio
+async def test_spend_by_model_grouped_series_and_kpis():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=30d")
+    assert d["metric"] == "spend" and d["value_unit"] == "usd"
+    # groups sorted by total desc; opus (0.06×4) > gpt (0.03×4)
+    assert d["groups"] == ["claude-opus-4-7", "gpt-4o"]
+    assert d["rows"], "expected grouped rows"
+    for r in d["rows"]:
+        assert {"bucket", "group", "stack", "value", "tokens"} <= set(r)
+    # KPIs are window totals, independent of group_by
+    assert d["kpis"]["spend"] == pytest.approx(0.36)
+    assert d["kpis"]["sessions"] == 8
+    assert d["framing"]["pricing_mode"] == "api"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("metric,unit", [
+    ("tokens", "tokens"), ("sessions", "count"), ("events", "count"),
+])
+async def test_metric_dimension_matrix(metric, unit):
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, f"metric={metric}&group_by=agent&since=30d")
+    assert d["value_unit"] == unit
+    assert d["groups"] == ["cc"]
+    assert d["rows"]
+
+
+@pytest.mark.asyncio
+async def test_tool_category_dimension_includes_tool_spans():
+    """tool / tool_category breakdowns must see tool spans (NULL model), which
+    the LLM-cost `model IS NOT NULL` gate would otherwise hide."""
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=events&group_by=tool_category&since=30d")
+    assert set(d["groups"]) == {"file", "shell", "search"}  # Read/Edit, Bash, Grep
+    assert "(none)" not in d["groups"]
+    # KPI totals reflect the FULL window (LLM spend included), not the tool-only
+    # subtype gate the breakdown applies — so "events by tool" never zeroes Spend.
+    assert d["kpis"]["spend"] > 0
+    assert d["kpis"]["tokens"] > 0
+
+
+@pytest.mark.asyncio
+async def test_stack_by_returns_second_dimension():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=provider&stack_by=model&since=30d")
+    assert d["stack_by"] == "model"
+    assert set(d["groups"]) == {"anthropic", "openai"}
+    assert set(d["stacks"]) == {"claude-opus-4-7", "gpt-4o"}
+    assert any(r["stack"] for r in d["rows"])
+
+
+@pytest.mark.asyncio
+async def test_filters_scope_the_window():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=model&provider=anthropic&since=30d")
+    assert d["groups"] == ["claude-opus-4-7"]
+    assert "gpt-4o" not in d["groups"]
+
+
+@pytest.mark.asyncio
+async def test_subscription_framing_suppresses_dollars():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1", budgets={"anthropic": ProviderBudget(plan="max_20x")})
+    _seed(db, plan="max_20x")
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=30d")
+    assert d["framing"]["pricing_mode"] == "subscription"
+    # token volume is present per row so the UI renders token-share, not $
+    assert all("tokens" in r for r in d["rows"])
+
+
+@pytest.mark.asyncio
+async def test_unknown_metric_and_dimension_rejected():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    transport = httpx.ASGITransport(app=_app(db, cfg))
+    async with httpx.AsyncClient(transport=transport, base_url="http://t") as c:
+        assert (await c.get("/api/v1/analytics?metric=bogus")).status_code == 400
+        assert (await c.get("/api/v1/analytics?group_by=bogus")).status_code == 400
+
+
+@pytest.mark.asyncio
+async def test_empty_window_is_safe():
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=7d")
+    assert d["rows"] == [] and d["groups"] == []
+    assert d["kpis"]["spend"] == 0
+    assert "framing" in d
+    # #217: the sparkline/delta fields are always present. With a window set,
+    # the delta keys exist but are null (no prior data → no divide-by-zero).
+    assert d["kpi_series"] == []
+    assert set(d["kpi_deltas"]) == {"spend", "tokens", "events", "sessions"}
+    assert all(v is None for v in d["kpi_deltas"].values())
+
+
+@pytest.mark.asyncio
+async def test_kpi_series_and_deltas_for_sparklines():
+    """#217: the explorer returns a per-bucket `kpi_series` (all four metrics)
+    and a period-over-period `kpi_deltas` vs the prior equal-length window —
+    both computed server-side so the UI never aggregates per-bucket in JS."""
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)  # 4 days of data, two models/day
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=30d")
+    # Per-bucket series carries every KPI metric for each bucket.
+    assert d["kpi_series"], "expected a non-empty kpi_series"
+    for b in d["kpi_series"]:
+        assert {"bucket", "spend", "tokens", "events", "sessions"} <= set(b)
+    # Series spend reconciles with the window KPI total.
+    assert sum(b["spend"] for b in d["kpi_series"]) == pytest.approx(d["kpis"]["spend"])
+    # Prior window had no data (seed is the most recent 4 days) → prev=0 → null
+    # delta, never a divide-by-zero.
+    assert set(d["kpi_deltas"]) == {"spend", "tokens", "events", "sessions"}
+    assert d["kpi_deltas"]["spend"] is None
+    assert d["kpi_prev"]["spend"] == 0
+
+
+@pytest.mark.asyncio
+async def test_kpi_delta_non_null_when_prior_window_has_data():
+    """#217: a real period-over-period % when both the current and prior
+    equal-length windows carry data (the seed spans 4 consecutive days, so a
+    2-day window's prior 2 days are non-empty)."""
+    db = InMemoryBackend()
+    cfg = TjConfig(version="1")
+    _seed(db)
+    d = await _get(db, cfg, "metric=spend&group_by=model&since=2d")
+    assert d["kpi_prev"]["spend"] > 0, "prior window should have seeded data"
+    assert d["kpi_deltas"]["spend"] is not None
+    assert isinstance(d["kpi_deltas"]["spend"], float)