zeno-cli 0.3.4__py3-none-any.whl

zeno_session_intel/analytics.py

@@ -0,0 +1,588 @@
+"""Session-intelligence analytics: ccusage-class rollups over the transcript_* tables.
+
+Read-only aggregation the dashboard export scripts and the ``zeno-usage`` CLI both call.
+Ported from agentsview (MIT, see THIRD_PARTY_LICENSES.md): cache-aware cost
+(``usage.go``), session stats + version-locked histogram edges + archetypes
+(``session_stats.go``/``session_stats_buckets.go``/``analytics.go``), tool-mix taxonomy,
+and outcomes. zeno additions: peak-context-pct as a first-class metric, and cache
+economics for any agent with nonzero cache rates (not agentsview's claude-only gate).
+
+Stdlib-only and **py3.9-safe** (the dashboard runs the system python3). Percentiles use
+nearest-rank (NOT interpolated - matches agentsview ``analytics.go:455-465``); histograms
+use ``bisect`` over half-open ``[lo, hi)`` edges with a ``+Inf`` last bucket.
+"""
+
+from __future__ import annotations
+
+import argparse
+import bisect
+import json
+import os
+import sqlite3
+import sys
+
+from . import compression, schema
+from .taxonomy import CATEGORIES
+
+# version-locked histogram edges (session_stats_buckets.go). Half-open [lo, hi), last +Inf.
+DURATION_EDGES = [0, 1, 5, 20, 60, 120]
+PEAK_CONTEXT_EDGES = [0, 10_000, 50_000, 100_000, 150_000, 200_000]
+TOOLS_PER_TURN_EDGES = [0, 1, 2, 4, 7, 11]
+
+_ARCHETYPE_ORDER = ("automation", "marathon", "deep", "standard", "quick")
+
+
+def _has_tables(con: sqlite3.Connection) -> bool:
+    rows = con.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='transcript_sessions'"
+    ).fetchall()
+    return bool(rows)
+
+
+def percentile(values: list[float], pct: float) -> float | None:
+    """Nearest-rank, zero-indexed, NOT interpolated: sorted[min(int(n*pct), n-1)]."""
+    vals = sorted(v for v in values if v is not None)
+    n = len(vals)
+    if n == 0:
+        return None
+    return vals[min(int(n * pct), n - 1)]
+
+
+def histogram(values: list[float], edges: list[float]) -> list[dict]:
+    """Half-open [lo, hi) buckets with a final +Inf bucket. Returns labeled counts."""
+    counts = [0] * (len(edges))  # one extra bucket for >= last edge (the +Inf bucket)
+    for v in values:
+        if v is None:
+            continue
+        idx = bisect.bisect_right(edges, v) - 1
+        if idx < 0:
+            idx = 0
+        if idx >= len(counts):
+            idx = len(counts) - 1
+        counts[idx] += 1
+    out = []
+    for i, lo in enumerate(edges):
+        hi = edges[i + 1] if i + 1 < len(edges) else None
+        out.append({"lo": lo, "hi": hi, "count": counts[i]})
+    return out
+
+
+def archetype(user_message_count: int, is_automated: bool) -> str:
+    if is_automated:
+        return "automation"
+    if user_message_count <= 5:
+        return "quick"
+    if user_message_count <= 15:
+        return "standard"
+    if user_message_count <= 50:
+        return "deep"
+    return "marathon"
+
+
+def _duration_min(started: str | None, ended: str | None) -> float | None:
+    if not started or not ended:
+        return None
+    try:
+        from datetime import datetime
+
+        s = datetime.fromisoformat(started.replace("Z", "+00:00"))
+        e = datetime.fromisoformat(ended.replace("Z", "+00:00"))
+        mins = round((e - s).total_seconds() / 60.0, 2)
+        # reject negatives from out-of-order / clock-skewed timestamps so they do not
+        # skew percentiles or land in the [0,1) bucket
+        return mins if mins >= 0 else None
+    except Exception:
+        return None
+
+
+def _q(con: sqlite3.Connection, sql: str, params: tuple = ()) -> list:
+    try:
+        return con.execute(sql, params).fetchall()
+    except Exception:
+        return []
+
+
+def cost_totals(con: sqlite3.Connection) -> dict:
+    """Cache-aware token/cost totals + cache hit ratio + cache savings (ccusage-class).
+
+    Cache savings joins the usage ledger to model_pricing and is NOT clamped (negative on
+    write-heavy sessions is itself the finding). Computed for any agent with nonzero cache
+    rates - not gated to claude.
+    """
+    row = _q(
+        con,
+        "SELECT COALESCE(SUM(input_tokens),0), COALESCE(SUM(output_tokens),0), "
+        "COALESCE(SUM(cache_creation_input_tokens),0), COALESCE(SUM(cache_read_input_tokens),0), "
+        "COALESCE(SUM(cost_usd),0), COUNT(*), SUM(CASE WHEN cost_status='' THEN 1 ELSE 0 END) "
+        "FROM token_usage_events",
+    )
+    if not row:
+        return {}
+    inp, out, cc, cr, cost, n, unpriced = row[0]
+    cache_in = cr + cc
+    total_in = inp + cache_in
+    cache_hit_ratio = round(cr / total_in, 4) if total_in else 0.0
+    savings_row = _q(
+        con,
+        "SELECT COALESCE(SUM("
+        "  e.cache_read_input_tokens * (p.input_per_mtok - p.cache_read_per_mtok) "
+        "+ e.cache_creation_input_tokens * (p.input_per_mtok - p.cache_creation_per_mtok)"
+        ") / 1000000.0, 0) "
+        "FROM token_usage_events e JOIN model_pricing p ON p.model_pattern = e.model",
+    )
+    savings = round(savings_row[0][0], 4) if savings_row else 0.0
+    return {
+        "events": int(n or 0),
+        "unpriced_events": int(unpriced or 0),
+        "input_tokens": int(inp),
+        "output_tokens": int(out),
+        "cache_creation_tokens": int(cc),
+        "cache_read_tokens": int(cr),
+        "total_tokens": int(total_in + out),
+        "cost_usd": round(cost, 4),
+        "cache_hit_ratio": cache_hit_ratio,
+        "cache_savings_usd": savings,
+    }
+
+
+def by_model(con: sqlite3.Connection) -> list[dict]:
+    rows = _q(
+        con,
+        "SELECT COALESCE(NULLIF(model,''),'(unpriced)'), COUNT(DISTINCT session_id), "
+        "COALESCE(SUM(cost_usd),0), "
+        "COALESCE(SUM(input_tokens+output_tokens+cache_read_input_tokens+"
+        "cache_creation_input_tokens),0) "
+        "FROM token_usage_events GROUP BY 1 ORDER BY SUM(cost_usd) DESC",
+    )
+    return [
+        {"model": m, "sessions": s, "cost_usd": round(c, 4), "total_tokens": int(t)}
+        for m, s, c, t in rows
+    ]
+
+
+def by_day(con: sqlite3.Connection) -> list[dict]:
+    rows = _q(
+        con,
+        "SELECT substr(occurred_at,1,10) d, COUNT(DISTINCT session_id), COALESCE(SUM(cost_usd),0) "
+        "FROM token_usage_events WHERE occurred_at IS NOT NULL GROUP BY d ORDER BY d",
+    )
+    return [{"date": d, "sessions": s, "cost_usd": round(c, 4)} for d, s, c in rows if d]
+
+
+def tool_mix(con: sqlite3.Connection) -> list[dict]:
+    rows = _q(
+        con,
+        "SELECT category, COUNT(*), COALESCE(SUM(is_error),0) "
+        "FROM transcript_tool_calls GROUP BY category",
+    )
+    by_cat = {c: (n, e) for c, n, e in rows}
+    total = sum(n for n, _ in by_cat.values()) or 1
+    out = []
+    for cat in CATEGORIES:
+        n, e = by_cat.get(cat, (0, 0))
+        if n == 0:
+            continue
+        out.append({"category": cat, "count": n, "errors": e, "pct": round(n / total * 1000) / 10})
+    out.sort(key=lambda r: r["count"], reverse=True)
+    return out
+
+
+def _session_rows(con: sqlite3.Connection) -> list[dict]:
+    cols = [
+        "id",
+        "agent",
+        "project",
+        "started_at",
+        "ended_at",
+        "message_count",
+        "user_message_count",
+        "is_automated",
+        "outcome",
+        "outcome_confidence",
+        "health_score",
+        "health_grade",
+        "peak_context_tokens",
+        "context_pressure_max",
+        "total_output_tokens",
+    ]
+    rows = _q(con, f"SELECT {','.join(cols)} FROM transcript_sessions")
+    return [{c: r[i] for i, c in enumerate(cols)} for r in rows]
+
+
+def session_analytics(con: sqlite3.Connection) -> dict:
+    sessions = _session_rows(con)
+    n = len(sessions)
+    arche: dict[str, int] = {}
+    outcomes: dict[str, int] = {}
+    grades: dict[str, int] = {"A": 0, "B": 0, "C": 0, "D": 0, "F": 0}
+    durations: list[float] = []
+    peaks: list[float] = []
+    pressures: list[float] = []
+    scored = 0
+    score_sum = 0
+    # tool calls per session for the tools-per-turn histogram
+    tc_rows = _q(con, "SELECT session_id, COUNT(*) FROM transcript_tool_calls GROUP BY session_id")
+    tc_by_session = {sid: c for sid, c in tc_rows}
+
+    for s in sessions:
+        a = archetype(int(s["user_message_count"] or 0), bool(s["is_automated"]))
+        arche[a] = arche.get(a, 0) + 1
+        oc = s["outcome"] or "unknown"
+        outcomes[oc] = outcomes.get(oc, 0) + 1
+        if s["health_score"] is not None:
+            scored += 1
+            score_sum += int(s["health_score"])
+            g = s["health_grade"] or ""
+            if g in grades:
+                grades[g] += 1
+        d = _duration_min(s["started_at"], s["ended_at"])
+        if d is not None:
+            durations.append(d)
+        if s["peak_context_tokens"]:
+            peaks.append(float(s["peak_context_tokens"]))
+        if s["context_pressure_max"] is not None:
+            pressures.append(float(s["context_pressure_max"]))
+
+    primary = ""
+    if arche:
+        primary = sorted(
+            arche,
+            key=lambda k: (-arche[k], _ARCHETYPE_ORDER.index(k) if k in _ARCHETYPE_ORDER else 99),
+        )[0]
+    return {
+        "session_count": n,
+        "archetypes": [
+            {"archetype": k, "count": v} for k, v in sorted(arche.items(), key=lambda kv: -kv[1])
+        ],
+        "primary_archetype": primary,
+        "outcomes": [
+            {"outcome": k, "count": v} for k, v in sorted(outcomes.items(), key=lambda kv: -kv[1])
+        ],
+        "health": {
+            "scored": scored,
+            "mean": round(score_sum / scored, 1) if scored else None,
+            "grades": grades,
+        },
+        "duration_distribution": histogram(durations, DURATION_EDGES),
+        "duration_p50_min": percentile(durations, 0.5),
+        "peak_context_distribution": histogram(peaks, PEAK_CONTEXT_EDGES),
+        "peak_context_p90": percentile(peaks, 0.9),
+        "context_pressure_p90": percentile(pressures, 0.9),
+        "tools_per_session_distribution": histogram(
+            [float(v) for v in tc_by_session.values()], TOOLS_PER_TURN_EDGES
+        ),
+    }
+
+
+def recent_sessions(con: sqlite3.Connection, limit: int = 12) -> list[dict]:
+    cols = [
+        "id",
+        "agent",
+        "project",
+        "started_at",
+        "ended_at",
+        "message_count",
+        "user_message_count",
+        "is_automated",
+        "outcome",
+        "health_score",
+        "health_grade",
+        "peak_context_tokens",
+        "context_pressure_max",
+    ]
+    rows = _q(
+        con,
+        f"SELECT {','.join(cols)} FROM transcript_sessions ORDER BY ended_at DESC, id LIMIT ?",
+        (limit,),
+    )
+    cost_rows = _q(
+        con,
+        "SELECT session_id, COALESCE(SUM(cost_usd),0) FROM token_usage_events GROUP BY session_id",
+    )
+    cost_by = {sid: c for sid, c in cost_rows}
+    tc_rows = _q(con, "SELECT session_id, COUNT(*) FROM transcript_tool_calls GROUP BY session_id")
+    tc_by = {sid: c for sid, c in tc_rows}
+    out = []
+    for r in rows:
+        s = {c: r[i] for i, c in enumerate(cols)}
+        out.append(
+            {
+                "id": s["id"],
+                "agent": s["agent"],
+                "project": s["project"],
+                "started_at": s["started_at"],
+                "duration_min": _duration_min(s["started_at"], s["ended_at"]),
+                "message_count": s["message_count"],
+                "tool_calls": tc_by.get(s["id"], 0),
+                "cost_usd": round(cost_by.get(s["id"], 0.0), 4),
+                "health_score": s["health_score"],
+                "health_grade": s["health_grade"],
+                "outcome": s["outcome"],
+                "archetype": archetype(int(s["user_message_count"] or 0), bool(s["is_automated"])),
+                "peak_context_tokens": s["peak_context_tokens"],
+                "peak_context_pct": (
+                    round(s["context_pressure_max"] * 100, 1)
+                    if s["context_pressure_max"] is not None
+                    else None
+                ),
+            }
+        )
+    return out
+
+
+def search(con: sqlite3.Connection, query: str, limit: int = 20) -> list[dict]:
+    """Full-text search transcript messages via the FTS5 index, bm25-ranked.
+
+    Returns rows of {id, session_id, ordinal, role, timestamp, snippet, rank}
+    with the matched terms wrapped in [..] by snippet(). Ordered most-relevant
+    first: SQLite bm25() returns NEGATIVE scores (best match most negative), so
+    plain ascending ORDER BY is correct (no DESC, no negation).
+
+    Never raises (mirrors ``_q``): returns [] when the query is empty, the
+    SQLite build lacks fts5, or the FTS5 query syntax is invalid. The user term
+    is wrapped as a quoted phrase so raw input containing FTS5 operators
+    (AND / OR / NEAR / unbalanced quotes) is matched literally instead of
+    raising. py3.9-safe.
+    """
+    query = (query or "").strip()
+    if not query or not schema.fts5_available(con):
+        return []
+    fts = schema.FTS_TABLE
+    phrase = '"' + query.replace('"', '""') + '"'
+    rows = _q(
+        con,
+        f"SELECT m.id, m.session_id, m.ordinal, m.role, m.timestamp, "
+        f"snippet({fts}, 0, '[', ']', '...', 10) AS snippet, bm25({fts}) AS rank "
+        f"FROM {fts} JOIN transcript_messages m ON m.id = {fts}.rowid "
+        f"WHERE {fts} MATCH ? ORDER BY bm25({fts}) LIMIT ?",
+        (phrase, limit),
+    )
+    return [
+        {
+            "id": r[0],
+            "session_id": r[1],
+            "ordinal": r[2],
+            "role": r[3],
+            "timestamp": r[4],
+            "snippet": r[5],
+            "rank": r[6],
+        }
+        for r in rows
+    ]
+
+
+def _empty_payload() -> dict:
+    """Full-shaped empty payload so the dashboard's TS type + spread-merge stay safe even
+    when there is no capture yet (mirrors the exporter's always-emit-full-shape pattern)."""
+    return {
+        "present": False,
+        "totals": {
+            "sessions": 0,
+            "messages": 0,
+            "tool_calls": 0,
+            "agents": [],
+            "events": 0,
+            "unpriced_events": 0,
+            "input_tokens": 0,
+            "output_tokens": 0,
+            "cache_creation_tokens": 0,
+            "cache_read_tokens": 0,
+            "total_tokens": 0,
+            "cost_usd": 0.0,
+            "cache_hit_ratio": 0.0,
+            "cache_savings_usd": 0.0,
+        },
+        "by_model": [],
+        "by_day": [],
+        "tool_mix": [],
+        "sessions": {
+            "session_count": 0,
+            "archetypes": [],
+            "primary_archetype": "",
+            "outcomes": [],
+            "health": {
+                "scored": 0,
+                "mean": None,
+                "grades": {"A": 0, "B": 0, "C": 0, "D": 0, "F": 0},
+            },
+            "duration_distribution": [],
+            "duration_p50_min": None,
+            "peak_context_distribution": [],
+            "peak_context_p90": None,
+            "context_pressure_p90": None,
+            "tools_per_session_distribution": [],
+        },
+        "recent_sessions": [],
+        "compression": {
+            "present": False,
+            "analyzed_chunks": 0,
+            "total_tokens": 0,
+            "savable_tokens": 0,
+            "savable_pct": 0.0,
+            "by_type": [],
+        },
+    }
+
+
+COMPRESSION_MIN_CONTENT_LEN = 500  # only sizable chunks are worth (theoretically) compressing
+COMPRESSION_MAX_CHUNKS = 20_000  # bound the offline scan; the largest chunks dominate savings
+
+
+def compression_savings(con: sqlite3.Connection) -> dict:
+    """Directional 'tokens you could have saved' estimate across captured content,
+    segmented by type. Read-only; this NEVER compresses anything (the agent request
+    path is untouched - see compression.py / the zeno-compression-decision memo).
+
+    Excludes assistant-authored text: the metric is about tool outputs + pasted data,
+    not the model's own prose. Code, tracebacks, and diffs always score 0 savable
+    (lossy compression corrupts exact tokens). Scans the largest non-assistant chunks;
+    fetches only a bounded head + interior + tail SAMPLE of each (classification is
+    sample-based) and derives the token count from the stored content_length - so a
+    large DB never materializes megabytes of content into memory.
+    """
+    rows = _q(
+        con,
+        "SELECT substr(content, 1, 2000) || x'0a' || "
+        "substr(content, max(1, content_length / 2 - 500), 1000) || x'0a' || "
+        "substr(content, -2000), content_length "
+        "FROM transcript_messages "
+        "WHERE role != 'assistant' AND content_length >= ? "
+        "ORDER BY content_length DESC LIMIT ?",
+        (COMPRESSION_MIN_CONTENT_LEN, COMPRESSION_MAX_CHUNKS),
+    )
+    agg: dict[str, dict[str, int]] = {}
+    total_tokens = 0
+    savable = 0
+    for sample, content_length in rows:
+        ctype = compression.classify(sample or "")
+        tokens = int((content_length or 0) / compression.CHARS_PER_TOKEN)
+        savable_tokens = int(tokens * compression.COMPRESSIBLE_FRACTION[ctype])
+        bucket = agg.setdefault(ctype, {"tokens": 0, "savable_tokens": 0, "chunks": 0})
+        bucket["tokens"] += tokens
+        bucket["savable_tokens"] += savable_tokens
+        bucket["chunks"] += 1
+        total_tokens += tokens
+        savable += savable_tokens
+    by_type = [
+        {"type": t, **vals}
+        for t, vals in sorted(agg.items(), key=lambda kv: kv[1]["savable_tokens"], reverse=True)
+    ]
+    return {
+        "present": bool(rows),
+        "analyzed_chunks": len(rows),
+        "total_tokens": total_tokens,
+        "savable_tokens": savable,
+        "savable_pct": round(100.0 * savable / total_tokens, 1) if total_tokens else 0.0,
+        "by_type": by_type,
+    }
+
+
+def _fmt_tok(n: int) -> str:
+    """Compact token count: 1.2M / 34k / 512."""
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 1_000:
+        return f"{n / 1_000:.0f}k"
+    return str(int(n))
+
+
+def render_compression_text(comp: dict) -> str:
+    """Human-readable compression-savings summary for ``zeno usage --compression``."""
+    if not comp.get("present"):
+        return "Compression savings: no sizable tool/data content captured yet."
+    lines = [
+        "Compression savings (directional - this measures only, never compresses):",
+        f"  {comp['savable_pct']}% of {_fmt_tok(comp['total_tokens'])} captured non-assistant "
+        f"tokens are safely compressible (~{_fmt_tok(comp['savable_tokens'])}).",
+        f"  scanned {comp['analyzed_chunks']} chunks, by type:",
+    ]
+    for b in comp["by_type"]:
+        tag = "" if b["savable_tokens"] > 0 else "  (never compressed - code/traceback)"
+        lines.append(
+            f"    {b['type']:<10}{_fmt_tok(b['savable_tokens']):>8} savable  "
+            f"of {_fmt_tok(b['tokens'])}  ({b['chunks']} chunks){tag}"
+        )
+    return "\n".join(lines)
+
+
+def build(con: sqlite3.Connection) -> dict:
+    """Assemble the full session-intelligence payload the dashboard embeds. Never raises;
+    returns a full-shaped ``present: False`` payload if the tables are absent or empty."""
+    out = _empty_payload()
+    if not _has_tables(con):
+        return out
+    totals_sessions = _q(con, "SELECT COUNT(*) FROM transcript_sessions")
+    if not totals_sessions or not totals_sessions[0][0]:
+        return out
+    out["present"] = True
+    out["totals"] = {
+        "sessions": totals_sessions[0][0],
+        "messages": _q(con, "SELECT COUNT(*) FROM transcript_messages")[0][0],
+        "tool_calls": _q(con, "SELECT COUNT(*) FROM transcript_tool_calls")[0][0],
+        "agents": [
+            {"agent": a, "sessions": c}
+            for a, c in _q(
+                con,
+                "SELECT agent, COUNT(*) FROM transcript_sessions "
+                "GROUP BY agent ORDER BY COUNT(*) DESC",
+            )
+        ],
+        **cost_totals(con),
+    }
+    out["by_model"] = by_model(con)
+    out["by_day"] = by_day(con)
+    out["tool_mix"] = tool_mix(con)
+    out["sessions"] = session_analytics(con)
+    out["recent_sessions"] = recent_sessions(con)
+    out["compression"] = compression_savings(con)
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="zeno-usage", description="Session-intelligence rollups")
+    base = os.environ.get("ZENO_HOME") or os.path.join(os.path.expanduser("~"), ".zeno")
+    default_db = os.environ.get("ZENO_DB_PATH") or os.path.join(base, "zeno.db")
+    ap.add_argument("--db", default=default_db)
+    ap.add_argument(
+        "--search",
+        default=None,
+        metavar="QUERY",
+        help="Full-text search transcript messages (bm25-ranked snippets) instead of rollups.",
+    )
+    ap.add_argument(
+        "--limit",
+        type=int,
+        default=20,
+        help="Max rows for --search (default 20).",
+    )
+    ap.add_argument(
+        "--compression",
+        action="store_true",
+        help="Print the compression-savings metric (human-readable) instead of the JSON rollup.",
+    )
+    args = ap.parse_args(argv)
+    try:
+        con = sqlite3.connect(f"file:{args.db}?mode=ro", uri=True)
+    except Exception:
+        json.dump({"present": False}, sys.stdout)
+        return 0
+    try:
+        if args.compression:
+            sys.stdout.write(render_compression_text(compression_savings(con)) + "\n")
+        else:
+            if args.search is not None:
+                payload = {
+                    "query": args.search,
+                    "results": search(con, args.search, limit=args.limit),
+                }
+                json.dump(payload, sys.stdout, indent=2)
+            else:
+                json.dump(build(con), sys.stdout, indent=2)
+            sys.stdout.write("\n")
+    finally:
+        con.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())