tokenhub 0.1.0__tar.gz

tokenhub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aldrin Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenhub-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: tokenhub
+Version: 0.1.0
+Summary: Local-first TokenHub
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Requires-Dist: pydantic
+Requires-Dist: sqlalchemy
+Requires-Dist: alembic
+Requires-Dist: filelock<4,>=3.12
+Requires-Dist: psutil<8,>=5.9
+Dynamic: license-file
+
+# TokenHub
+
+A local-first usage observatory. TokenHub detects the coding agents installed on
+this machine, imports usage from sources you explicitly approve, and
+shows agent, model, and session usage in a local explorer. Nothing leaves the machine: no provider
+API is called, no provider executable is launched, and only usage metadata is retained. Credentials and provider accounts are never
+read; transcript content is never stored or shown. Approved session files can contain chat text, which the parsers discard.
+
+Supported sources: **OpenAI Codex** session usage, **Claude Code** project and
+subagent session logs, **Hermes Agent** session counters in its local state
+database, **VS Code Copilot Chat** saved sessions, and **Antigravity** conversation
+databases.
+
+## Install and run
+
+Requires Python 3.12 or newer. After the public package is released:
+
+```bash
+pip install tokenhub
+tokenhub                     # starts in the background and opens the local dashboard
+tokenhub status              # prints its local URL
+tokenhub open                # opens an already running dashboard
+tokenhub stop                # stops this TokenHub instance
+```
+
+`tokenhub start --no-open` starts without opening a browser. Use
+`tokenhub start --port 9000` to choose another loopback port. A second start
+reuses the running instance, including its chosen port. The server continues
+after the terminal closes; run `tokenhub` again after a reboot or login. Logs
+and local data are stored in `~/.tokenhub/`, with startup details in
+`~/.tokenhub/runtime.log`.
+
+For development from this checkout, run `uv sync --all-groups` and
+`uv run tokenhub --no-open`.
+
+TokenHub binds to `127.0.0.1:7432` by default and prints that URL when it
+starts. It is loopback-only by design:
+
+- the bind host is validated at startup — `0.0.0.0`, `::`, or any non-loopback
+  value raises rather than serving;
+- every request must carry a loopback `Host` header (`localhost`, `127.0.0.1`,
+  `[::1]`, with the configured port), so a DNS-rebinding page cannot reach the
+  API even from the local browser;
+- state-changing requests (`approve`, `rescan`, `rebuild`) must also carry the
+  request's own origin; otherwise they are refused with `403`;
+- no CORS headers are ever added, and `X-Forwarded-*` headers are ignored.
+
+The UI is bundled with the Python package. To refresh it while developing:
+
+```bash
+npm --prefix frontend ci
+npm --prefix frontend run build              # writes backend/tokenhub/web
+```
+
+The packaged UI is mounted at `/`; the API also works if the built UI is absent.
+
+## Automatic collection
+
+While TokenHub is running, it scans approved sources from all five providers at startup and every
+30 seconds. The explorer refreshes itself every 10 seconds. Approving a provider
+in the UI also starts its first import immediately. Unchanged session files are skipped. Hermes and Antigravity databases are checked on each scan
+because active usage can live in their SQLite journal. Repeated scans do not
+increase totals. Automatic scans of unchanged data do not create extra
+import-history rows, including after restarting TokenHub.
+
+Choose **Approve and import** on a provider card to approve its discovered
+usage folder once and include both existing and future sessions automatically.
+This consent survives restarts and is pinned to the folder's device and inode;
+replacing the folder or redirecting it through a symlink cannot authorize another
+location. **Stop including new sessions** removes that folder consent; previously
+approved files keep updating. Without folder consent, new files require approval.
+
+`GET /api/v1/collection` reports the scan interval, folder-consent state, last
+completed scan, and failed-source count. Same-origin `POST` requests to
+`/api/v1/collection/{provider}/enable` and `/disable` change consent (`codex`,
+`claude_code`, `hermes`, `vscode_copilot`, or `antigravity`). Responses contain
+no private paths. Failed sources are retried without preventing other sources
+from updating, and collection runs even when the dashboard is closed.
+
+For Codex, only per-response `token_usage_record.payload.usage` values contribute
+to totals.
+Known session messages are skipped. Cumulative token snapshots, malformed records,
+and unknown usage structures remain visible as unsupported records; cumulative
+snapshots are excluded from totals to avoid double counting. Workload is
+input plus output, with cached input and reasoning already included in those
+counts. Token counts are not billing amounts. The UI uses K/M/B abbreviations
+and shows the exact count on hover.
+
+Claude Code reads `message.usage` from assistant records under its `projects`
+folder. Repeated streaming chunks are consolidated by message ID, copied history in
+resumed/forked session files is counted once, and later usage updates replace
+the session's previous normalized records. Hermes reads
+only allowlisted session identifiers, timestamps, and token counters from a
+no-follow snapshot of `state.db` and its journal; no provider database is written.
+Each Hermes session contributes once, with running totals replaced atomically as
+they change. Cache reads and writes are included in the input total for Claude
+and Hermes because both store them in separate buckets. Hermes session
+contributions are marked `high` quality; Claude message usage is marked `exact`.
+
+VS Code Copilot Chat imports saved `chatSessions/*.jsonl` requests from VS Code's
+workspace storage. It records each Copilot request's model, session, input tokens,
+and output tokens when VS Code saved those counters. Later session patches replace
+earlier counters; unchanged files do not add usage again. Requests without token
+counters remain unsupported rather than receiving estimated values. Cache and
+reasoning counters are not available in these saved requests. Inline suggestions,
+Copilot CLI, and Copilot activity in other editors are outside this source's scope.
+`VSCODE_USER_DATA_DIR` can point to a different VS Code user-data directory,
+such as an Insiders installation.
+
+Antigravity imports per-generation model, timestamp, input, cache-read, output,
+and reasoning counters from approved `~/.gemini/antigravity/conversations/*.db`
+files. It reads a snapshot of the database and its active journal without writing
+to the provider database. Antigravity's local metadata format is private, so
+unrecognized or inconsistent generations are excluded and reported as partial
+instead of estimated. `ANTIGRAVITY_HOME` can point to another Antigravity root.
+
+## Discovery and approval
+
+`GET /api/v1/discovery` reports each provider's display name, connection state,
+a confidence level derived from its evidence (`high` when two or more
+independent signals were found, `medium` for one, `low` for none), the evidence
+codes it found (`executable_on_path`, `known_root_exists`, `configuration_found`,
+`session_source_found`, `state_database_found`), and a stable path fingerprint.
+Discovery reads **presence only** — it stats candidate roots and directories and
+never opens a provider file.
+
+The provider card combines approval and first import in one click. It also
+enables future session imports for that provider. The lower-level API remains
+available for one-source troubleshooting:
+
+1. `POST /api/v1/sources/{source_id}/approve` persists the canonical path for
+   that one source. Before approval, responses contain no absolute path at all.
+2. `POST /api/v1/sources/{source_id}/rescan` imports new records through the
+   connector's parser. Repeating a rescan over unchanged bytes inserts nothing;
+   `POST /api/v1/rebuild` re-derives all normalized events from scratch and
+   leaves totals unchanged.
+
+`GET /api/v1/dashboard` and `GET /api/v1/data-quality` report observed usage.
+Workload is input total plus output total; cache and reasoning are breakdowns,
+never extra usage. A metric the data cannot support is returned as `null` and
+rendered as an em dash — TokenHub never substitutes `0` for "unknown".
+
+The default **Usage explorer** combines the consolidated token summary with
+agent, model, and session breakdowns for Codex, Claude Code, Hermes Agent,
+VS Code Copilot, and Antigravity. Filter by all time, today, yesterday, the last
+7 or 30 days, or a selected local calendar date.
+Choose an agent to rank its models by total, input, output, cache-read, or
+reasoning tokens. Search for a model, select it to see its sessions, and expand
+a session to compare the models used inside it. Exact counts are available on
+hover. Source health and import quality appear together under **Local sources**.
+
+`GET /api/v1/usage` returns canonical totals plus agent, model, and session
+breakdowns. Session identifiers are opaque, stable hashes; original session IDs
+and source paths are not exposed. The same Claude message deduplication is used
+throughout the explorer. Optional timezone-aware `from` and `to` query bounds
+filter usage by recorded event time; the upper bound is exclusive. Known older
+parsers re-read approved sources on startup to add
+model/session metadata without changing previously imported Codex counters.
+
+## Data boundaries
+
+- Only usage metadata is normalized. Prompts, messages, tool output, transcript
+  bodies, and raw provider records are never retained or returned by the API.
+- Provider credentials, API keys, `auth.json`, keychain, and cookie stores are
+  never read. Approved session JSONL can contain chat text; only allowlisted
+  usage fields are normalized, and raw content is never stored or returned.
+- Anything outside an approved source's own approved root: canonical-path
+  validation rejects symlink escapes, and the approved root is re-validated by
+  device/inode at every scan.
+
+## Tests
+
+```bash
+uv run pytest -q                              # unit + API
+uv run pytest tests/integration -m integration -q   # real app stack, synthetic homes
+uv run ruff check backend tests
+uv run mypy backend
+cd frontend && npm run test -- --run && npm run build
+uv build
+python scripts/verify_distribution.py dist/*  # tests installed wheel and source archive
+```
+
+Every test is offline and deterministic: synthetic fixtures in a temp directory,
+no real home directory, no network, no provider subprocess. A test that points
+at a real provider path or opens a real credential store is a bug.
+
+## Layout
+
+| Path | Responsibility |
+|---|---|
+| `backend/tokenhub/domain/` | provider-neutral enums and data models |
+| `backend/tokenhub/security/` | path containment, redaction, Host/Origin policy |
+| `backend/tokenhub/connectors/` | one module per provider behind a shared contract |
+| `backend/tokenhub/discovery/` | presence discovery and the pre-approval handoff |
+| `backend/tokenhub/ingestion/` | approval gate, incremental scan, rebuild |
+| `backend/tokenhub/database/` | SQLAlchemy models, repositories, Alembic migrations |
+| `backend/tokenhub/analytics/` | dashboard aggregates over observed deltas |
+| `backend/tokenhub/api/` | versioned `/api/v1` routes and the app container |
+| `frontend/` | React + TypeScript + Vite client (Vitest, MSW) |
+
+## Current limitations
+
+- **Local schemas only.** Unknown usage structures and malformed records are
+  reported as partial or unavailable. Hermes needs a `sessions` table containing
+  session IDs, start timestamps, and input/output counters. An unsupported or
+  unreadable database leaves previously imported usage intact.
+- **No cost or pricing.** TokenHub reports token counts only — no currency, no
+  provider plan data.
+- **Model attribution depends on recorded metadata.** Missing model names appear
+  in “Model not recorded”. Hermes exposes session totals with a reported model;
+  model switches within that session cannot be split by its current counters.
+- **No trend chart.** Date filters use observed usage timestamps. TokenHub does
+  not guess daily allocations for counters that lack event dates.

tokenhub-0.1.0/README.md

@@ -0,0 +1,213 @@
+# TokenHub
+
+A local-first usage observatory. TokenHub detects the coding agents installed on
+this machine, imports usage from sources you explicitly approve, and
+shows agent, model, and session usage in a local explorer. Nothing leaves the machine: no provider
+API is called, no provider executable is launched, and only usage metadata is retained. Credentials and provider accounts are never
+read; transcript content is never stored or shown. Approved session files can contain chat text, which the parsers discard.
+
+Supported sources: **OpenAI Codex** session usage, **Claude Code** project and
+subagent session logs, **Hermes Agent** session counters in its local state
+database, **VS Code Copilot Chat** saved sessions, and **Antigravity** conversation
+databases.
+
+## Install and run
+
+Requires Python 3.12 or newer. After the public package is released:
+
+```bash
+pip install tokenhub
+tokenhub                     # starts in the background and opens the local dashboard
+tokenhub status              # prints its local URL
+tokenhub open                # opens an already running dashboard
+tokenhub stop                # stops this TokenHub instance
+```
+
+`tokenhub start --no-open` starts without opening a browser. Use
+`tokenhub start --port 9000` to choose another loopback port. A second start
+reuses the running instance, including its chosen port. The server continues
+after the terminal closes; run `tokenhub` again after a reboot or login. Logs
+and local data are stored in `~/.tokenhub/`, with startup details in
+`~/.tokenhub/runtime.log`.
+
+For development from this checkout, run `uv sync --all-groups` and
+`uv run tokenhub --no-open`.
+
+TokenHub binds to `127.0.0.1:7432` by default and prints that URL when it
+starts. It is loopback-only by design:
+
+- the bind host is validated at startup — `0.0.0.0`, `::`, or any non-loopback
+  value raises rather than serving;
+- every request must carry a loopback `Host` header (`localhost`, `127.0.0.1`,
+  `[::1]`, with the configured port), so a DNS-rebinding page cannot reach the
+  API even from the local browser;
+- state-changing requests (`approve`, `rescan`, `rebuild`) must also carry the
+  request's own origin; otherwise they are refused with `403`;
+- no CORS headers are ever added, and `X-Forwarded-*` headers are ignored.
+
+The UI is bundled with the Python package. To refresh it while developing:
+
+```bash
+npm --prefix frontend ci
+npm --prefix frontend run build              # writes backend/tokenhub/web
+```
+
+The packaged UI is mounted at `/`; the API also works if the built UI is absent.
+
+## Automatic collection
+
+While TokenHub is running, it scans approved sources from all five providers at startup and every
+30 seconds. The explorer refreshes itself every 10 seconds. Approving a provider
+in the UI also starts its first import immediately. Unchanged session files are skipped. Hermes and Antigravity databases are checked on each scan
+because active usage can live in their SQLite journal. Repeated scans do not
+increase totals. Automatic scans of unchanged data do not create extra
+import-history rows, including after restarting TokenHub.
+
+Choose **Approve and import** on a provider card to approve its discovered
+usage folder once and include both existing and future sessions automatically.
+This consent survives restarts and is pinned to the folder's device and inode;
+replacing the folder or redirecting it through a symlink cannot authorize another
+location. **Stop including new sessions** removes that folder consent; previously
+approved files keep updating. Without folder consent, new files require approval.
+
+`GET /api/v1/collection` reports the scan interval, folder-consent state, last
+completed scan, and failed-source count. Same-origin `POST` requests to
+`/api/v1/collection/{provider}/enable` and `/disable` change consent (`codex`,
+`claude_code`, `hermes`, `vscode_copilot`, or `antigravity`). Responses contain
+no private paths. Failed sources are retried without preventing other sources
+from updating, and collection runs even when the dashboard is closed.
+
+For Codex, only per-response `token_usage_record.payload.usage` values contribute
+to totals.
+Known session messages are skipped. Cumulative token snapshots, malformed records,
+and unknown usage structures remain visible as unsupported records; cumulative
+snapshots are excluded from totals to avoid double counting. Workload is
+input plus output, with cached input and reasoning already included in those
+counts. Token counts are not billing amounts. The UI uses K/M/B abbreviations
+and shows the exact count on hover.
+
+Claude Code reads `message.usage` from assistant records under its `projects`
+folder. Repeated streaming chunks are consolidated by message ID, copied history in
+resumed/forked session files is counted once, and later usage updates replace
+the session's previous normalized records. Hermes reads
+only allowlisted session identifiers, timestamps, and token counters from a
+no-follow snapshot of `state.db` and its journal; no provider database is written.
+Each Hermes session contributes once, with running totals replaced atomically as
+they change. Cache reads and writes are included in the input total for Claude
+and Hermes because both store them in separate buckets. Hermes session
+contributions are marked `high` quality; Claude message usage is marked `exact`.
+
+VS Code Copilot Chat imports saved `chatSessions/*.jsonl` requests from VS Code's
+workspace storage. It records each Copilot request's model, session, input tokens,
+and output tokens when VS Code saved those counters. Later session patches replace
+earlier counters; unchanged files do not add usage again. Requests without token
+counters remain unsupported rather than receiving estimated values. Cache and
+reasoning counters are not available in these saved requests. Inline suggestions,
+Copilot CLI, and Copilot activity in other editors are outside this source's scope.
+`VSCODE_USER_DATA_DIR` can point to a different VS Code user-data directory,
+such as an Insiders installation.
+
+Antigravity imports per-generation model, timestamp, input, cache-read, output,
+and reasoning counters from approved `~/.gemini/antigravity/conversations/*.db`
+files. It reads a snapshot of the database and its active journal without writing
+to the provider database. Antigravity's local metadata format is private, so
+unrecognized or inconsistent generations are excluded and reported as partial
+instead of estimated. `ANTIGRAVITY_HOME` can point to another Antigravity root.
+
+## Discovery and approval
+
+`GET /api/v1/discovery` reports each provider's display name, connection state,
+a confidence level derived from its evidence (`high` when two or more
+independent signals were found, `medium` for one, `low` for none), the evidence
+codes it found (`executable_on_path`, `known_root_exists`, `configuration_found`,
+`session_source_found`, `state_database_found`), and a stable path fingerprint.
+Discovery reads **presence only** — it stats candidate roots and directories and
+never opens a provider file.
+
+The provider card combines approval and first import in one click. It also
+enables future session imports for that provider. The lower-level API remains
+available for one-source troubleshooting:
+
+1. `POST /api/v1/sources/{source_id}/approve` persists the canonical path for
+   that one source. Before approval, responses contain no absolute path at all.
+2. `POST /api/v1/sources/{source_id}/rescan` imports new records through the
+   connector's parser. Repeating a rescan over unchanged bytes inserts nothing;
+   `POST /api/v1/rebuild` re-derives all normalized events from scratch and
+   leaves totals unchanged.
+
+`GET /api/v1/dashboard` and `GET /api/v1/data-quality` report observed usage.
+Workload is input total plus output total; cache and reasoning are breakdowns,
+never extra usage. A metric the data cannot support is returned as `null` and
+rendered as an em dash — TokenHub never substitutes `0` for "unknown".
+
+The default **Usage explorer** combines the consolidated token summary with
+agent, model, and session breakdowns for Codex, Claude Code, Hermes Agent,
+VS Code Copilot, and Antigravity. Filter by all time, today, yesterday, the last
+7 or 30 days, or a selected local calendar date.
+Choose an agent to rank its models by total, input, output, cache-read, or
+reasoning tokens. Search for a model, select it to see its sessions, and expand
+a session to compare the models used inside it. Exact counts are available on
+hover. Source health and import quality appear together under **Local sources**.
+
+`GET /api/v1/usage` returns canonical totals plus agent, model, and session
+breakdowns. Session identifiers are opaque, stable hashes; original session IDs
+and source paths are not exposed. The same Claude message deduplication is used
+throughout the explorer. Optional timezone-aware `from` and `to` query bounds
+filter usage by recorded event time; the upper bound is exclusive. Known older
+parsers re-read approved sources on startup to add
+model/session metadata without changing previously imported Codex counters.
+
+## Data boundaries
+
+- Only usage metadata is normalized. Prompts, messages, tool output, transcript
+  bodies, and raw provider records are never retained or returned by the API.
+- Provider credentials, API keys, `auth.json`, keychain, and cookie stores are
+  never read. Approved session JSONL can contain chat text; only allowlisted
+  usage fields are normalized, and raw content is never stored or returned.
+- Anything outside an approved source's own approved root: canonical-path
+  validation rejects symlink escapes, and the approved root is re-validated by
+  device/inode at every scan.
+
+## Tests
+
+```bash
+uv run pytest -q                              # unit + API
+uv run pytest tests/integration -m integration -q   # real app stack, synthetic homes
+uv run ruff check backend tests
+uv run mypy backend
+cd frontend && npm run test -- --run && npm run build
+uv build
+python scripts/verify_distribution.py dist/*  # tests installed wheel and source archive
+```
+
+Every test is offline and deterministic: synthetic fixtures in a temp directory,
+no real home directory, no network, no provider subprocess. A test that points
+at a real provider path or opens a real credential store is a bug.
+
+## Layout
+
+| Path | Responsibility |
+|---|---|
+| `backend/tokenhub/domain/` | provider-neutral enums and data models |
+| `backend/tokenhub/security/` | path containment, redaction, Host/Origin policy |
+| `backend/tokenhub/connectors/` | one module per provider behind a shared contract |
+| `backend/tokenhub/discovery/` | presence discovery and the pre-approval handoff |
+| `backend/tokenhub/ingestion/` | approval gate, incremental scan, rebuild |
+| `backend/tokenhub/database/` | SQLAlchemy models, repositories, Alembic migrations |
+| `backend/tokenhub/analytics/` | dashboard aggregates over observed deltas |
+| `backend/tokenhub/api/` | versioned `/api/v1` routes and the app container |
+| `frontend/` | React + TypeScript + Vite client (Vitest, MSW) |
+
+## Current limitations
+
+- **Local schemas only.** Unknown usage structures and malformed records are
+  reported as partial or unavailable. Hermes needs a `sessions` table containing
+  session IDs, start timestamps, and input/output counters. An unsupported or
+  unreadable database leaves previously imported usage intact.
+- **No cost or pricing.** TokenHub reports token counts only — no currency, no
+  provider plan data.
+- **Model attribution depends on recorded metadata.** Missing model names appear
+  in “Model not recorded”. Hermes exposes session totals with a reported model;
+  model switches within that session cannot be split by its current counters.
+- **No trend chart.** Date filters use observed usage timestamps. TokenHub does
+  not guess daily allocations for counters that lack event dates.

tokenhub-0.1.0/backend/tokenhub/__init__.py

@@ -0,0 +1 @@
+"""TokenHub package."""

tokenhub-0.1.0/backend/tokenhub/__main__.py

@@ -0,0 +1,8 @@
+"""Module entrypoint for the detached child and interactive command."""
+
+from __future__ import annotations
+
+from tokenhub.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tokenhub-0.1.0/backend/tokenhub/analytics/__init__.py

@@ -0,0 +1 @@
+"""Provider-neutral analytics over normalized local events."""

tokenhub-0.1.0/backend/tokenhub/analytics/breakdown.py

@@ -0,0 +1,78 @@
+"""Agent, model, and session views of the canonical observed workload."""
+
+import hashlib
+from collections import defaultdict
+from datetime import UTC
+from typing import Any
+
+from tokenhub.database.models import UsageEventRecord
+
+_COUNTERS = (
+    "input_total_tokens", "output_total_tokens", "cache_read_tokens",
+    "cache_write_tokens", "reasoning_tokens",
+)
+
+
+def _session_key(event: UsageEventRecord) -> str:
+    # Stable across refreshes, with no original session id or filesystem path.
+    identity = f"{event.connector_id}\0{event.session_id or event.source_id}"
+    return hashlib.sha256(identity.encode()).hexdigest()[:24]
+
+
+def _summary(events: list[UsageEventRecord]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for field in _COUNTERS:
+        values = [getattr(event, field) for event in events if getattr(event, field) is not None]
+        result[field] = sum(values) if values else None
+    workloads = [
+        event.input_total_tokens + event.output_total_tokens
+        for event in events
+        if event.input_total_tokens is not None and event.output_total_tokens is not None
+    ]
+    result.update(
+        workload_tokens=sum(workloads) if workloads else None,
+        event_count=len(events),
+        session_count=len({_session_key(event) for event in events}),
+        model_count=len({event.model_name for event in events if event.model_name is not None}),
+        incomplete_event_count=sum(
+            event.input_total_tokens is None or event.output_total_tokens is None for event in events
+        ),
+        first_seen=min((event.timestamp for event in events), default=None),
+        last_seen=max((event.timestamp for event in events), default=None),
+    )
+    for field in ("first_seen", "last_seen"):
+        result[field] = result[field].replace(tzinfo=UTC).isoformat() if result[field] else None
+    return result
+
+
+def usage_breakdown(events: list[UsageEventRecord]) -> dict[str, Any]:
+    providers: dict[str, list[UsageEventRecord]] = defaultdict(list)
+    models: dict[tuple[str, str | None], list[UsageEventRecord]] = defaultdict(list)
+    sessions: dict[tuple[str, str], list[UsageEventRecord]] = defaultdict(list)
+    for event in events:
+        providers[event.provider].append(event)
+        models[event.provider, event.model_name].append(event)
+        sessions[event.provider, _session_key(event)].append(event)
+    model_rows = []
+    for (provider, model), group in models.items():
+        attributions = {event.model_attribution for event in group}
+        model_rows.append(dict(
+            _summary(group), provider=provider, model_name=model,
+            attribution=next(iter(attributions)) if len(attributions) == 1 else "mixed",
+        ))
+    session_rows = []
+    for (provider, key), group in sessions.items():
+        session_models: dict[str | None, list[UsageEventRecord]] = defaultdict(list)
+        for event in group:
+            session_models[event.model_name].append(event)
+        session_rows.append(dict(
+            _summary(group), provider=provider, session_key=key,
+            models=[dict(_summary(rows), model_name=model) for model, rows in session_models.items()],
+        ))
+    sort_key = lambda row: (-(row["workload_tokens"] or 0), row["provider"], row.get("model_name") or "")
+    return {
+        "totals": _summary(events),
+        "providers": sorted([dict(_summary(group), provider=provider) for provider, group in providers.items()], key=sort_key),
+        "models": sorted(model_rows, key=sort_key),
+        "sessions": sorted(session_rows, key=sort_key),
+    }

tokenhub-0.1.0/backend/tokenhub/analytics/service.py

@@ -0,0 +1,21 @@
+"""Dashboard queries over observed, normalized usage only."""
+
+from datetime import datetime
+from typing import Any
+
+from tokenhub.analytics.breakdown import usage_breakdown
+from tokenhub.database.repositories import UsageRepository
+from tokenhub.domain.models import DashboardSummary
+
+
+class AnalyticsService:
+    def __init__(self, usage_repository: UsageRepository) -> None:
+        self.usage_repository = usage_repository
+
+    def dashboard(self) -> DashboardSummary:
+        return self.usage_repository.dashboard_totals()
+
+    def usage_breakdown(
+        self, start: datetime | None = None, end: datetime | None = None
+    ) -> dict[str, Any]:
+        return usage_breakdown(self.usage_repository.observed_events(start, end))

tokenhub-0.1.0/backend/tokenhub/api/__init__.py

@@ -0,0 +1,7 @@
+"""HTTP surface for the local TokenHub server.
+
+* :mod:`tokenhub.api.container` — startup/shutdown and shared services
+* :mod:`tokenhub.api.routes` — the versioned `/api/v1` routes
+
+The application factory lives in :mod:`tokenhub.app`.
+"""