devin-metrics 0.2.0__tar.gz

devin_metrics-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Icaro0310
+
+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.

devin_metrics-0.2.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: devin-metrics
+Version: 0.2.0
+Summary: Activity, context and session observability across Devin sessions — local-only, no telemetry.
+Author: Icaro0310
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: devin-internals-spec<0.4.0,>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+<img src="assets/banner.svg" alt="devin-metrics" width="100%"/>
+
+<a href="https://github.com/Icaro0310/devin-metrics/actions/workflows/ci.yml"><img src="https://github.com/Icaro0310/devin-metrics/actions/workflows/ci.yml/badge.svg" alt="ci"/></a>
+
+
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-metrics"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-metrics/badge" alt="OpenSSF Scorecard"/></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
+<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"/></a>
+<a href="https://github.com/Icaro0310/devin-metrics"><img src="https://img.shields.io/github/stars/Icaro0310/devin-metrics" alt="GitHub stars"/></a>
+<a href="https://github.com/Icaro0310/devin-metrics/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-metrics" alt="Last commit"/></a>
+<a href="https://github.com/Icaro0310/awesome-devin"><img src="https://img.shields.io/badge/part%20of-devin--*-ecosystem-7c3aed" alt="devin-* ecosystem"/></a>
+<a href="https://github.com/Icaro0310/devin-metrics/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
+</div>
+
+# devin-metrics
+
+> **Unofficial community project.** Not affiliated with, endorsed by, or
+> sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
+
+**[Linux](README.linux.md)** · **[Personal Windows](README.windows.md)** · **[Corporate Windows](README.corporate-windows.md)**
+
+Part of the [awesome-devin](https://github.com/Icaro0310/awesome-devin) ecosystem: the curated hub for the devin-* tools.
+
+Local-only metrics for your Devin usage: sessions per day/week, per-project
+and per-model rollups, context-size peaks, longest sessions, tool-call mix —
+zero telemetry, JSON + markdown output.
+
+## The problem
+
+Devin sessions accumulate real activity — context growth, model time, tool
+calls — but there is no way to answer "which project ate my week?" or "how
+big did my sessions get?". The data already exists on disk in `sessions.db`
+and `acp-messages/*.db`; nothing reads it. `devin-metrics` is the missing
+read side.
+
+## Prior art
+
+Agent-usage trackers exist for other tools — e.g. `ccusage` for Claude Code
+reads `~/.claude` transcripts and reports cost/token rollups. This project
+adapts the same idea; it does not reinvent it. What is different here is the
+*source*: Devin's stores are private, schema-versioned (17 migrations), and
+undocumented — so the reading layer is delegated to
+[`devin-internals-spec`](https://github.com/Icaro0310/devin-internals-spec)
+which owns parsing + schema detection.
+
+## What makes it Devin-native
+
+- **Side-by-side:** generic token trackers cannot open Devin's stores at
+  all — the format is unpublished. This tool reads them directly, so
+  metrics come from protocol data (`sessions.db`, `acp-messages`), not
+  scraped text.
+- **No-Devin:** remove Devin and there is nothing to measure — no store, no
+  metrics.
+- **One sentence:** it reads Devin's own databases and tells you what your
+  sessions did — locally, with nothing sent anywhere.
+
+Per-session `working_directory` gives project attribution for free.
+
+## Install
+
+Python ≥ 3.10 and `pipx` are required. **Windows (PowerShell):** install `pipx` with `py -m pip install --user pipx`, run `py -m pipx ensurepath`, then reopen the terminal. **Linux (Debian/Ubuntu):** run `sudo apt install pipx python3-venv` and `pipx ensurepath`; reopen the terminal. Other Linux distributions should install `pipx` using their package manager.
+
+This package is not on PyPI yet; install the public GitHub version:
+
+```bash
+pipx install "devin-metrics @ git+https://github.com/Icaro0310/devin-metrics.git"
+```
+
+## Usage
+
+```bash
+devin-metrics summary                  # headline numbers + top-5 lists
+devin-metrics projects                 # per-project session/activity table
+devin-metrics daily --days 14          # activity over time
+devin-metrics dashboard --out usage.html
+
+devin-dashboard build --out usage.html # dashboard executable alias
+devin-dashboard data --json             # same dashboard source data as JSON
+devin-metrics summary --json           # raw JSON for scripting
+```
+
+`devin-dashboard` is an alias shipped by the same package. Its `build` command
+writes a standalone HTML dashboard; `data` prints the normalized stats payload.
+
+By default, `sessions.db` is read from the platform data root (`%APPDATA%/devin`
+on Windows, `$XDG_DATA_HOME/devin` on Linux, normally `~/.local/share/devin`).
+ACP logs are read from the separate UI config root (`%APPDATA%/Devin/User`
+on Windows, `$XDG_CONFIG_HOME/Devin/User` on Linux). Override with
+`--data-dir`, `--sessions-db` or `--acp-dir`.
+
+```bash
+devin-metrics summary --sessions-db path/to/sessions.db --acp-dir path/to/acp-messages
+```
+
+A missing `acp-messages` dir degrades gracefully: `cost_usd` shows `-`
+(unknown ≠ zero). Note that per-turn cost is **not persisted** even when
+the dir exists (verified — see Limitations); `context_tokens` is the real
+per-session token signal.
+
+## Works with Devin alone (Devin-only mode)
+
+All metrics are computed locally from Devin's own stores and written to a
+local database — zero telemetry, zero network calls. The `devin-dashboard`
+console alias included in this package (it absorbed the old standalone
+dashboard) also renders entirely on your machine.
+
+## Platform support
+
+Tested on **Windows and Linux** (`windows-latest` + `ubuntu-latest` in CI).
+The CLI database is auto-detected from `%APPDATA%/devin/cli/sessions.db` on
+Windows and `$XDG_DATA_HOME/devin/cli/sessions.db` on Linux (default
+`~/.local/share/devin/cli/sessions.db`). ACP logs are read from
+`$XDG_CONFIG_HOME/Devin/User/acp-messages` (default
+`~/.config/Devin/User/acp-messages`). Legacy `~/.config/devin` layouts are
+also checked. Override with `--sessions-db` or `--acp-dir`.
+
+
+The dashboard also charts **peak `num_tokens_preceding` per day** — the only token signal persisted locally (verified: no cost fields are stored). Cost charts show a "no data" note rather than fake zeros.
+
+
+### `devin-metrics churn` (needs `devin-graph build`)
+
+Rework stats from the knowledge graph: files re-touched by multiple tool calls in the same session, per session and per model. Known noise: pseudo-paths like `/dev/null` and shell builtins can rank high — they are real `file_touched` edges, just not meaningful rework.
+
+
+`devin-metrics watch` is an **advisory** context guard (ME-2): lists
+sessions/days whose `context_tokens` exceed thresholds
+(`--session-warn`, `--daily-warn`, `--fail` for CI). It never blocks —
+and it watches *context size*, not cost: local stores have no cost data
+(verified, see SCHEMA.md).
+
+## Limitations
+
+- **Read-only, no network.** Stores are opened `mode=ro`; nothing is
+  written or sent anywhere.
+- **Cost is not persisted locally — verified.** A real install (2026-10)
+  confirms acp payloads and `tool_call_state` carry **no** cost/token
+  fields; per-turn cost lives only in the live ACP session meta and is
+  never written to disk. `cost_usd` therefore shows `-` on real data.
+  The one token signal that *does* persist — `num_tokens_preceding` in
+  `message_nodes.metadata` — is reported per session as `context_tokens`
+  (peak context size). Details: `docs/SCHEMA.md`.
+- **Schema-gated.** `sessions.db` versions outside v15–v17 are refused
+  loudly (via `devin-internals-spec`'s detector) rather than misread.
+- Drift-checked — `devin-inspect contract` (from devin-internals-spec)
+  validates this install against every known contract boundary.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+```
+
+## When to use this
+
+- You want a local view of Devin activity: sessions per project, model,
+  or day, context-size peaks, longest sessions and tool-call mix.
+- You need a scriptable JSON feed of usage stats (`--json` on every command).
+- You want a standalone HTML dashboard of activity (`devin-metrics dashboard`
+  or the `devin-dashboard` alias).
+- Telemetry is a hard no — everything is computed and stored locally.
+
+## When NOT to use this
+
+- You need to search message content — use `devin-search`; or relationship
+  queries across sessions/files/tools — use `devin-graph`.
+- You need live, real-time session monitoring — use `devin-office`.
+- The machine has no Devin CLI/Desktop install — there is nothing to measure.
+
+## FAQ
+
+**What is devin-metrics?** A local CLI that reads Devin's own session
+databases and reports local observability metrics: sessions per day/week,
+activity and context-size peaks per project and model, longest sessions, and
+tool-call mix. It also
+ships a `devin-dashboard` alias that writes a standalone HTML dashboard.
+
+**How does devin-metrics get cost data?** Honest answer: it mostly
+doesn't — verified on a real install, Devin's local stores persist **no**
+cost or token fields (cost exists only in the live ACP session meta and
+is never written to disk). What it does measure: sessions, messages,
+tool calls, durations, per-project/per-model rollups, and `context_tokens`
+(peak `num_tokens_preceding` — the only token signal that persists). The
+`extract_usage()` adapter remains ready if a future schema starts
+persisting cost.
+
+**Does devin-metrics send data anywhere?** No. All metrics are computed
+locally and written to a local database. There are no network calls and no
+telemetry; Devin's own stores are opened `mode=ro` and never written.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

devin_metrics-0.2.0/README.md

@@ -0,0 +1,196 @@
+<div align="center">
+
+<img src="assets/banner.svg" alt="devin-metrics" width="100%"/>
+
+<a href="https://github.com/Icaro0310/devin-metrics/actions/workflows/ci.yml"><img src="https://github.com/Icaro0310/devin-metrics/actions/workflows/ci.yml/badge.svg" alt="ci"/></a>
+
+
+<a href="https://scorecard.dev/viewer/?uri=github.com/Icaro0310/devin-metrics"><img src="https://api.scorecard.dev/projects/github.com/Icaro0310/devin-metrics/badge" alt="OpenSSF Scorecard"/></a>
+<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"/></a>
+<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python 3.10+"/></a>
+<a href="https://github.com/Icaro0310/devin-metrics"><img src="https://img.shields.io/github/stars/Icaro0310/devin-metrics" alt="GitHub stars"/></a>
+<a href="https://github.com/Icaro0310/devin-metrics/commits/main"><img src="https://img.shields.io/github/last-commit/Icaro0310/devin-metrics" alt="Last commit"/></a>
+<a href="https://github.com/Icaro0310/awesome-devin"><img src="https://img.shields.io/badge/part%20of-devin--*-ecosystem-7c3aed" alt="devin-* ecosystem"/></a>
+<a href="https://github.com/Icaro0310/devin-metrics/issues"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen" alt="PRs welcome"/></a>
+</div>
+
+# devin-metrics
+
+> **Unofficial community project.** Not affiliated with, endorsed by, or
+> sponsored by Cognition AI. "Devin" is a trademark of Cognition AI.
+
+**[Linux](README.linux.md)** · **[Personal Windows](README.windows.md)** · **[Corporate Windows](README.corporate-windows.md)**
+
+Part of the [awesome-devin](https://github.com/Icaro0310/awesome-devin) ecosystem: the curated hub for the devin-* tools.
+
+Local-only metrics for your Devin usage: sessions per day/week, per-project
+and per-model rollups, context-size peaks, longest sessions, tool-call mix —
+zero telemetry, JSON + markdown output.
+
+## The problem
+
+Devin sessions accumulate real activity — context growth, model time, tool
+calls — but there is no way to answer "which project ate my week?" or "how
+big did my sessions get?". The data already exists on disk in `sessions.db`
+and `acp-messages/*.db`; nothing reads it. `devin-metrics` is the missing
+read side.
+
+## Prior art
+
+Agent-usage trackers exist for other tools — e.g. `ccusage` for Claude Code
+reads `~/.claude` transcripts and reports cost/token rollups. This project
+adapts the same idea; it does not reinvent it. What is different here is the
+*source*: Devin's stores are private, schema-versioned (17 migrations), and
+undocumented — so the reading layer is delegated to
+[`devin-internals-spec`](https://github.com/Icaro0310/devin-internals-spec)
+which owns parsing + schema detection.
+
+## What makes it Devin-native
+
+- **Side-by-side:** generic token trackers cannot open Devin's stores at
+  all — the format is unpublished. This tool reads them directly, so
+  metrics come from protocol data (`sessions.db`, `acp-messages`), not
+  scraped text.
+- **No-Devin:** remove Devin and there is nothing to measure — no store, no
+  metrics.
+- **One sentence:** it reads Devin's own databases and tells you what your
+  sessions did — locally, with nothing sent anywhere.
+
+Per-session `working_directory` gives project attribution for free.
+
+## Install
+
+Python ≥ 3.10 and `pipx` are required. **Windows (PowerShell):** install `pipx` with `py -m pip install --user pipx`, run `py -m pipx ensurepath`, then reopen the terminal. **Linux (Debian/Ubuntu):** run `sudo apt install pipx python3-venv` and `pipx ensurepath`; reopen the terminal. Other Linux distributions should install `pipx` using their package manager.
+
+This package is not on PyPI yet; install the public GitHub version:
+
+```bash
+pipx install "devin-metrics @ git+https://github.com/Icaro0310/devin-metrics.git"
+```
+
+## Usage
+
+```bash
+devin-metrics summary                  # headline numbers + top-5 lists
+devin-metrics projects                 # per-project session/activity table
+devin-metrics daily --days 14          # activity over time
+devin-metrics dashboard --out usage.html
+
+devin-dashboard build --out usage.html # dashboard executable alias
+devin-dashboard data --json             # same dashboard source data as JSON
+devin-metrics summary --json           # raw JSON for scripting
+```
+
+`devin-dashboard` is an alias shipped by the same package. Its `build` command
+writes a standalone HTML dashboard; `data` prints the normalized stats payload.
+
+By default, `sessions.db` is read from the platform data root (`%APPDATA%/devin`
+on Windows, `$XDG_DATA_HOME/devin` on Linux, normally `~/.local/share/devin`).
+ACP logs are read from the separate UI config root (`%APPDATA%/Devin/User`
+on Windows, `$XDG_CONFIG_HOME/Devin/User` on Linux). Override with
+`--data-dir`, `--sessions-db` or `--acp-dir`.
+
+```bash
+devin-metrics summary --sessions-db path/to/sessions.db --acp-dir path/to/acp-messages
+```
+
+A missing `acp-messages` dir degrades gracefully: `cost_usd` shows `-`
+(unknown ≠ zero). Note that per-turn cost is **not persisted** even when
+the dir exists (verified — see Limitations); `context_tokens` is the real
+per-session token signal.
+
+## Works with Devin alone (Devin-only mode)
+
+All metrics are computed locally from Devin's own stores and written to a
+local database — zero telemetry, zero network calls. The `devin-dashboard`
+console alias included in this package (it absorbed the old standalone
+dashboard) also renders entirely on your machine.
+
+## Platform support
+
+Tested on **Windows and Linux** (`windows-latest` + `ubuntu-latest` in CI).
+The CLI database is auto-detected from `%APPDATA%/devin/cli/sessions.db` on
+Windows and `$XDG_DATA_HOME/devin/cli/sessions.db` on Linux (default
+`~/.local/share/devin/cli/sessions.db`). ACP logs are read from
+`$XDG_CONFIG_HOME/Devin/User/acp-messages` (default
+`~/.config/Devin/User/acp-messages`). Legacy `~/.config/devin` layouts are
+also checked. Override with `--sessions-db` or `--acp-dir`.
+
+
+The dashboard also charts **peak `num_tokens_preceding` per day** — the only token signal persisted locally (verified: no cost fields are stored). Cost charts show a "no data" note rather than fake zeros.
+
+
+### `devin-metrics churn` (needs `devin-graph build`)
+
+Rework stats from the knowledge graph: files re-touched by multiple tool calls in the same session, per session and per model. Known noise: pseudo-paths like `/dev/null` and shell builtins can rank high — they are real `file_touched` edges, just not meaningful rework.
+
+
+`devin-metrics watch` is an **advisory** context guard (ME-2): lists
+sessions/days whose `context_tokens` exceed thresholds
+(`--session-warn`, `--daily-warn`, `--fail` for CI). It never blocks —
+and it watches *context size*, not cost: local stores have no cost data
+(verified, see SCHEMA.md).
+
+## Limitations
+
+- **Read-only, no network.** Stores are opened `mode=ro`; nothing is
+  written or sent anywhere.
+- **Cost is not persisted locally — verified.** A real install (2026-10)
+  confirms acp payloads and `tool_call_state` carry **no** cost/token
+  fields; per-turn cost lives only in the live ACP session meta and is
+  never written to disk. `cost_usd` therefore shows `-` on real data.
+  The one token signal that *does* persist — `num_tokens_preceding` in
+  `message_nodes.metadata` — is reported per session as `context_tokens`
+  (peak context size). Details: `docs/SCHEMA.md`.
+- **Schema-gated.** `sessions.db` versions outside v15–v17 are refused
+  loudly (via `devin-internals-spec`'s detector) rather than misread.
+- Drift-checked — `devin-inspect contract` (from devin-internals-spec)
+  validates this install against every known contract boundary.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+```
+
+## When to use this
+
+- You want a local view of Devin activity: sessions per project, model,
+  or day, context-size peaks, longest sessions and tool-call mix.
+- You need a scriptable JSON feed of usage stats (`--json` on every command).
+- You want a standalone HTML dashboard of activity (`devin-metrics dashboard`
+  or the `devin-dashboard` alias).
+- Telemetry is a hard no — everything is computed and stored locally.
+
+## When NOT to use this
+
+- You need to search message content — use `devin-search`; or relationship
+  queries across sessions/files/tools — use `devin-graph`.
+- You need live, real-time session monitoring — use `devin-office`.
+- The machine has no Devin CLI/Desktop install — there is nothing to measure.
+
+## FAQ
+
+**What is devin-metrics?** A local CLI that reads Devin's own session
+databases and reports local observability metrics: sessions per day/week,
+activity and context-size peaks per project and model, longest sessions, and
+tool-call mix. It also
+ships a `devin-dashboard` alias that writes a standalone HTML dashboard.
+
+**How does devin-metrics get cost data?** Honest answer: it mostly
+doesn't — verified on a real install, Devin's local stores persist **no**
+cost or token fields (cost exists only in the live ACP session meta and
+is never written to disk). What it does measure: sessions, messages,
+tool calls, durations, per-project/per-model rollups, and `context_tokens`
+(peak `num_tokens_preceding` — the only token signal that persists). The
+`extract_usage()` adapter remains ready if a future schema starts
+persisting cost.
+
+**Does devin-metrics send data anywhere?** No. All metrics are computed
+locally and written to a local database. There are no network calls and no
+telemetry; Devin's own stores are opened `mode=ro` and never written.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

devin_metrics-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "devin-metrics"
+version = "0.2.0"
+description = "Activity, context and session observability across Devin sessions — local-only, no telemetry."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Icaro0310" }]
+dependencies = [
+  "devin-internals-spec>=0.3.0,<0.4.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+devin-metrics = "devin_metrics.cli:main"
+devin-dashboard = "devin_metrics.dashboard.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

devin_metrics-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

devin_metrics-0.2.0/src/devin_metrics/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

devin_metrics-0.2.0/src/devin_metrics/aggregate.py

@@ -0,0 +1,199 @@
+"""Rollups over a :class:`MetricsSnapshot` — pure functions, JSON-ready dicts.
+
+Attribution rules:
+
+- Sessions group by ``working_directory`` (the project) — free with Devin's
+  session store.
+- Day buckets use the session's ``created_at`` in UTC.
+- ``cost_usd_total`` counts **all** acp usage rows (including orphan dbs with
+  no session row); ``cost_usd_by_sessions`` counts only matched sessions.
+- ``cost_usd is None`` means *unknown* (no acp data), never zero.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Iterable
+
+from devin_metrics.collect import MetricsSnapshot, SessionMetrics, UsageRecord
+
+
+def _day(ms: int) -> str:
+    return datetime.fromtimestamp(ms / 1000, tz=timezone.utc).date().isoformat()
+
+
+def session_to_dict(s: SessionMetrics) -> dict[str, Any]:
+    return {
+        "id": s.id,
+        "title": s.title,
+        "project": s.working_directory,
+        "model": s.model,
+        "created": _day(s.created_at),
+        "created_at": s.created_at,
+        "duration_ms": s.duration_ms,
+        "messages": s.n_messages,
+        "tool_calls": s.n_tool_calls,
+        "cost_usd": s.cost_usd,
+        "input_tokens": s.input_tokens,
+        "output_tokens": s.output_tokens,
+        "context_tokens": s.context_tokens,
+    }
+
+
+def _sum_or_none(values: Iterable[float | int | None]) -> float | int | None:
+    known = [v for v in values if v is not None]
+    return sum(known) if known else None
+
+
+def _sum(values: Iterable[float | int]) -> float | int:
+    return sum(values)
+
+
+# -- summaries ---------------------------------------------------------------
+
+
+def summarize(snap: MetricsSnapshot) -> dict[str, Any]:
+    sessions = list(snap.sessions)
+    n = len(sessions)
+    with_cost = [s for s in sessions if s.cost_usd is not None]
+    return {
+        "sessions": n,
+        "sessions_with_cost": len(with_cost),
+        "hidden_sessions": sum(1 for s in sessions if s.hidden),
+        "first_seen": _day(min(s.created_at for s in sessions)) if n else None,
+        "last_seen": _day(max(s.last_activity_at for s in sessions)) if n else None,
+        "messages": _sum(s.n_messages for s in sessions),
+        "tool_calls": _sum(s.n_tool_calls for s in sessions),
+        "duration_ms_total": _sum(s.duration_ms for s in sessions),
+        "cost_usd_total": _sum_or_none(u.cost_usd for u in snap.usage),
+        "cost_usd_by_sessions": _sum_or_none(s.cost_usd for s in sessions),
+        "input_tokens_total": _sum_or_none(u.input_tokens for u in snap.usage),
+        "output_tokens_total": _sum_or_none(u.output_tokens for u in snap.usage),
+        "context_tokens_peak": max(
+            (s.context_tokens for s in sessions
+             if s.context_tokens is not None),
+            default=None,
+        ),
+        "sessions_with_context": sum(
+            1 for s in sessions if s.context_tokens is not None
+        ),
+        "avg_duration_ms": (_sum(s.duration_ms for s in sessions) / n) if n else None,
+        "avg_messages": (_sum(s.n_messages for s in sessions) / n) if n else None,
+        "avg_cost_usd": (
+            _sum(s.cost_usd for s in with_cost) / len(with_cost)  # type: ignore[arg-type]
+            if with_cost
+            else None
+        ),
+        "acp_available": snap.acp_available,
+        "acp_db_files": snap.acp_db_files,
+        "acp_db_errors": snap.acp_db_errors,
+        "matched_sessions": snap.matched_sessions,
+        "orphan_dbs": snap.orphan_dbs,
+        "top_longest": top_sessions(snap, n=5, key="duration_ms"),
+        "top_costliest": top_sessions(snap, n=5, key="cost_usd"),
+        "models": by_model(snap),
+    }
+
+
+def by_project(snap: MetricsSnapshot) -> list[dict[str, Any]]:
+    groups: dict[str, list[SessionMetrics]] = {}
+    for s in snap.sessions:
+        groups.setdefault(s.working_directory, []).append(s)
+    rows = [
+        {
+            "project": wd,
+            "sessions": len(members),
+            "messages": _sum(s.n_messages for s in members),
+            "tool_calls": _sum(s.n_tool_calls for s in members),
+            "duration_ms": _sum(s.duration_ms for s in members),
+            "cost_usd": _sum_or_none(s.cost_usd for s in members),
+            "input_tokens": _sum_or_none(s.input_tokens for s in members),
+            "output_tokens": _sum_or_none(s.output_tokens for s in members),
+        }
+        for wd, members in groups.items()
+    ]
+    rows.sort(
+        key=lambda r: (r["cost_usd"] is not None, r["cost_usd"] or 0, r["sessions"]),
+        reverse=True,
+    )
+    return rows
+
+
+def by_model(snap: MetricsSnapshot) -> list[dict[str, Any]]:
+    """Per-model stats merging session-declared models and acp usage rows."""
+    rows: dict[str, dict[str, Any]] = {}
+
+    def _row(model: str | None) -> dict[str, Any]:
+        name = model or "(unknown)"
+        return rows.setdefault(
+            name,
+            {
+                "model": name,
+                "sessions": 0,
+                "usage_records": 0,
+                "cost_usd": None,
+                "input_tokens": None,
+                "output_tokens": None,
+            },
+        )
+
+    for s in snap.sessions:
+        _row(s.model)["sessions"] += 1
+    for u in snap.usage:
+        r = _row(u.model)
+        r["usage_records"] += 1
+        if u.cost_usd is not None:
+            r["cost_usd"] = (r["cost_usd"] or 0.0) + u.cost_usd
+        if u.input_tokens is not None:
+            r["input_tokens"] = (r["input_tokens"] or 0) + u.input_tokens
+        if u.output_tokens is not None:
+            r["output_tokens"] = (r["output_tokens"] or 0) + u.output_tokens
+    out = list(rows.values())
+    out.sort(
+        key=lambda r: (r["cost_usd"] is not None, r["cost_usd"] or 0, r["sessions"]),
+        reverse=True,
+    )
+    return out
+
+
+def by_day(snap: MetricsSnapshot, days: int | None = None) -> list[dict[str, Any]]:
+    """Sessions bucketed by UTC creation date.
+
+    ``days=N`` keeps the N most recent *activity* days (anchored on the latest
+    day in the data, not on wall-clock now — deterministic for fixtures and
+    for inspecting old installs alike).
+    """
+    groups: dict[str, list[SessionMetrics]] = {}
+    for s in snap.sessions:
+        groups.setdefault(_day(s.created_at), []).append(s)
+    dates = sorted(groups)
+    if days is not None:
+        dates = dates[-days:] if days > 0 else []
+    return [
+        {
+            "date": d,
+            "sessions": len(groups[d]),
+            "messages": _sum(s.n_messages for s in groups[d]),
+            "tool_calls": _sum(s.n_tool_calls for s in groups[d]),
+            "duration_ms": _sum(s.duration_ms for s in groups[d]),
+            "cost_usd": _sum_or_none(s.cost_usd for s in groups[d]),
+        }
+        for d in dates
+    ]
+
+
+def top_sessions(
+    snap: MetricsSnapshot, n: int = 5, key: str = "duration_ms"
+) -> list[dict[str, Any]]:
+    """Top-N sessions. ``key``: ``duration_ms`` or ``cost_usd``.
+
+    For ``cost_usd`` sessions with unknown cost are excluded entirely.
+    """
+    if key == "cost_usd":
+        pool = [s for s in snap.sessions if s.cost_usd is not None]
+        ordered = sorted(pool, key=lambda s: s.cost_usd or 0, reverse=True)
+    elif key == "duration_ms":
+        ordered = sorted(snap.sessions, key=lambda s: s.duration_ms, reverse=True)
+    else:
+        raise ValueError(f"top_sessions: unknown key {key!r}")
+    return [session_to_dict(s) for s in ordered[:n]]