driftcast 1.0.0__py3-none-any.whl

driftcast/__init__.py

@@ -0,0 +1,17 @@
+"""driftcast — cost and trace telemetry for agent frameworks."""
+
+from .storage import default_db_path
+from .tracer import Lens, annotate, outcome, record
+
+__all__ = ["init", "Lens", "record", "annotate", "outcome", "default_db_path"]
+
+
+def init(
+    project: str,
+    db_path: str | None = None,
+    capture_content: bool = False,
+) -> Lens:
+    """Single entry point so every caller gets the universal db path and the capture_content privacy default (False = shape and economics only, never content)."""
+    if db_path is None:
+        db_path = default_db_path()
+    return Lens(project=project, db_path=db_path, capture_content=capture_content)

driftcast/cli.py

@@ -0,0 +1,128 @@
+"""
+cli.py — `driftcast summary`: aggregate cost/token report.
+
+Plain-table output, mirroring the visual style of rag-agent's
+`ingest.py:preview_ingest` for consistency across the DriftCast tooling.
+"""
+
+import argparse
+import sqlite3
+
+from .storage import default_db_path
+
+
+def _fetch_rows(db_path: str, project: str | None):
+    """Isolates the read-only SQL so the printers work on plain rows."""
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    try:
+        if project:
+            runs = conn.execute(
+                "SELECT * FROM runs WHERE project = ? ORDER BY started_at", (project,)
+            ).fetchall()
+        else:
+            runs = conn.execute("SELECT * FROM runs ORDER BY started_at").fetchall()
+
+        run_ids = [r["run_id"] for r in runs]
+        spans = []
+        if run_ids:
+            placeholders = ",".join("?" * len(run_ids))
+            spans = conn.execute(
+                f"SELECT * FROM spans WHERE run_id IN ({placeholders})", run_ids
+            ).fetchall()
+        return runs, spans
+    finally:
+        conn.close()
+
+
+def _print_by_run(runs):
+    """Answers "what did each pipeline execution cost" at a glance in the terminal."""
+    if not runs:
+        print("No runs recorded.")
+        return
+
+    col = 28
+    print(f"\n  {'Run':<{col}} {'Status':>8} {'Cost ($)':>10} {'Started':>26}")
+    print("  " + "─" * (col + 48))
+    total_cost = 0.0
+    for r in runs:
+        print(f"  {r['name']:<{col}} {r['status']:>8} {r['total_cost']:>10.4f} {r['started_at']:>26}")
+        total_cost += r["total_cost"]
+    print("  " + "─" * (col + 48))
+    print(f"  {'TOTAL':<{col}} {'':>8} {total_cost:>10.4f}")
+    print()
+
+
+def _print_by_model(spans):
+    """Answers "which model is the money going to" without opening the dashboard."""
+    if not spans:
+        return
+
+    stats: dict[str, dict] = {}
+    for s in spans:
+        model = s["model"] or "(no model)"
+        st = stats.setdefault(model, {"calls": 0, "input_tokens": 0, "output_tokens": 0, "cost": 0.0, "latency_ms": 0.0})
+        st["calls"] += 1
+        st["input_tokens"] += s["input_tokens"]
+        st["output_tokens"] += s["output_tokens"]
+        st["cost"] += s["cost"]
+        st["latency_ms"] += s["latency_ms"]
+
+    col = 28
+    print(f"  {'Model':<{col}} {'Calls':>6} {'In tok':>10} {'Out tok':>10} {'Cost ($)':>10} {'Avg ms':>8}")
+    print("  " + "─" * (col + 48))
+    total_cost = total_calls = 0
+    for model, st in stats.items():
+        avg_latency = st["latency_ms"] / st["calls"]
+        print(f"  {model:<{col}} {st['calls']:>6,} {st['input_tokens']:>10,} {st['output_tokens']:>10,} {st['cost']:>10.4f} {avg_latency:>8.0f}")
+        total_cost += st["cost"]
+        total_calls += st["calls"]
+    print("  " + "─" * (col + 48))
+    print(f"  {'TOTAL':<{col}} {total_calls:>6,}")
+    print()
+
+
+def summary(db_path: str, project: str | None = None) -> None:
+    """Gives scripts and the CLI one callable for the full cost/token report."""
+    runs, spans = _fetch_rows(db_path, project)
+    label = f" for project '{project}'" if project else ""
+    print(f"\nDriftCast summary{label} — {db_path}")
+    _print_by_run(runs)
+    _print_by_model(spans)
+
+
+def main() -> None:
+    """Console-script entry point: routes `driftcast <command>` to the right tool with lazy optional-extra imports."""
+    parser = argparse.ArgumentParser(prog="driftcast")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    summary_parser = sub.add_parser("summary", help="Aggregate cost/token report")
+    summary_parser.add_argument("--db", default=None,
+                                help="Path to the SQLite db (default: the universal db via default_db_path())")
+    summary_parser.add_argument("--project", default=None, help="Filter by project name")
+
+    dash_parser = sub.add_parser("dashboard", help="Live web dashboard (needs the 'dashboard' extra)")
+    dash_parser.add_argument("--db", default=None,
+                             help="Path to the SQLite db (default: the universal db via default_db_path())")
+    dash_parser.add_argument("--project", default=None, help="Filter by project name")
+    dash_parser.add_argument("--port", type=int, default=7861, help="Port to serve on")
+    dash_parser.add_argument("--refresh", type=float, default=2.0, help="Auto-refresh interval (seconds)")
+
+    args = parser.parse_args()
+    if args.command == "summary":
+        summary(args.db or default_db_path(), args.project)
+    elif args.command == "dashboard":
+        try:
+            from . import dashboard
+        except ImportError:
+            raise SystemExit(
+                "The dashboard needs Gradio. Install it with: pip install \"driftcast[dashboard]\""
+            )
+        dashboard.launch(
+            db_path=args.db or default_db_path(), project=args.project, port=args.port,
+            refresh_seconds=args.refresh, block=True,
+        )
+
+
+if __name__ == "__main__":
+    main()

driftcast/dashboard.py

@@ -0,0 +1,329 @@
+"""
+dashboard.py — live Gradio dashboard for DriftCast stats.
+
+Reads the same SQLite db the tracer writes to and renders a live-refreshing
+view of runs, per-model cost/token aggregates, and headline totals. Reusable
+by any agent that uses the SDK — point it at the project's db and launch.
+
+The "Coordination" tab renders each run as a tree from parent_span_id, so a
+multi-agent run (orchestrator → chosen subagent → provider calls) reads as a
+diagram of what the system did and what each step cost — the routing LLM calls
+(route_classify / judge_answer / synthesize) included, since those spend tokens
+too. When a run records routing fields via driftcast.annotate() (route / source /
+reason / refined), a one-line badge explains WHY that run went where it did.
+
+Gradio is an *optional* dependency, imported lazily inside the launch path so
+the core SDK (tracer/storage/pricing) stays stdlib-only. Install with:
+
+    pip install "driftcast[dashboard]"
+"""
+
+import json
+import sqlite3
+
+# Absolute (not `from .storage`) so this module works both as `python -m
+# driftcast.dashboard` AND run directly as a file (`python dashboard.py`), where
+# there is no parent package for a relative import to resolve against. driftcast
+# is pip-installed, so the absolute form resolves in either case.
+from driftcast.storage import default_db_path
+
+# ── Read layer (read-only; never writes) ──────────────────────────────────────
+
+
+def _fetch(db_path: str, project: str | None):
+    """Return (runs, spans) as lists of sqlite3.Row. Empty lists if no data yet."""
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    try:
+        if project:
+            runs = conn.execute(
+                "SELECT * FROM runs WHERE project = ? ORDER BY started_at DESC", (project,)
+            ).fetchall()
+        else:
+            runs = conn.execute("SELECT * FROM runs ORDER BY started_at DESC").fetchall()
+
+        run_ids = [r["run_id"] for r in runs]
+        spans = []
+        if run_ids:
+            placeholders = ",".join("?" * len(run_ids))
+            spans = conn.execute(
+                f"SELECT * FROM spans WHERE run_id IN ({placeholders}) ORDER BY started_at",
+                run_ids,
+            ).fetchall()
+        return runs, spans
+    except sqlite3.OperationalError:
+        # Tables not created yet (agent hasn't run a single trace) — show empty.
+        return [], []
+    finally:
+        conn.close()
+
+
+def _col(row: sqlite3.Row, key: str, default=None):
+    """Read a column that may be absent on a db written by an older SDK build."""
+    return row[key] if key in row.keys() else default
+
+
+# ── Coordination tree (per-run, built from parent_span_id) ────────────────────
+
+# Routing reason codes (set by the orchestrator via annotate) → human text. Kept
+# here so the badge reads cleanly; an unknown code falls back to itself with
+# underscores turned into spaces, so new codes still render.
+_REASON_TEXT = {
+    "intent_public_web": "classifier judged the query needs current public web info",
+    "no_corpus": "no local corpus to ground an answer — fell back to web",
+    "rag_sufficient": "RAG answer judged sufficient on its own",
+    "rag_insufficient_refined": "RAG answer judged weak — refined with web evidence",
+}
+
+
+def _routing_badge(metadata_json: str | None) -> str | None:
+    """Build a one-line 'why' badge from a run's annotated routing metadata."""
+    if not metadata_json:
+        return None
+    try:
+        meta = json.loads(metadata_json)
+    except (ValueError, TypeError):
+        return None
+    source = meta.get("source") or meta.get("route")
+    if not source:
+        return None  # not a routed run — nothing to explain
+
+    parts = [f"**routed to {str(source).upper()}**"]
+    reason = meta.get("reason")
+    if reason:
+        parts.append(_REASON_TEXT.get(reason, str(reason).replace("_", " ")))
+    if meta.get("refined"):
+        parts.append("RAG base + web evidence synthesized")
+    return "  ·  ".join(parts)
+
+
+def _fmt_span_line(s: sqlite3.Row, depth: int) -> str:
+    """One monospaced tree row for a span: name · model · tokens · cost [· error]."""
+    connector = ("    " * (depth - 1) + "└─ ") if depth else ""
+    model = s["model"] or "—"
+    toks = f"{s['input_tokens']} in / {s['output_tokens']} out"
+    line = f"{connector}{s['name']}  ·  {model}  ·  {toks}  ·  ${s['cost']:.4f}"
+    if s["status"] != "ok":
+        line += f"  ·  [{s['status']}: {s['error']}]"
+    return line
+
+
+def _render_run(run: sqlite3.Row, run_spans: list[sqlite3.Row]) -> str:
+    """Render one run as a header + routing badge + indented span tree."""
+    mark = "ok" if run["status"] == "ok" else "ERROR"
+    header = (
+        f"#### {run['name']}  ·  {mark}  ·  ${run['total_cost']:.4f}  "
+        f"·  {run['started_at']}"
+    )
+
+    blocks = [header]
+    badge = _routing_badge(_col(run, "metadata_json"))
+    if badge:
+        blocks.append(badge)
+
+    # Group children by parent, then walk depth-first from the roots (parent None).
+    children: dict[str | None, list[sqlite3.Row]] = {}
+    for s in run_spans:
+        children.setdefault(_col(s, "parent_span_id"), []).append(s)
+
+    lines: list[str] = []
+
+    def walk(parent_id: str | None, depth: int) -> None:
+        """Emits span rows depth-first so the tree indents match parent_span_id nesting."""
+        for s in children.get(parent_id, []):
+            lines.append(_fmt_span_line(s, depth))
+            walk(s["span_id"], depth + 1)
+
+    walk(None, 0)
+    blocks.append("```\n" + "\n".join(lines) + "\n```" if lines else "_(no provider calls recorded)_")
+    return "\n\n".join(blocks)
+
+
+def _coordination_md(runs, spans) -> str:
+    """Renders the whole Coordination tab as one tree per agent, newest-first, so activity reads top-to-bottom without a sort step."""
+    if not runs:
+        return "_No runs recorded yet._"
+    by_run: dict[str, list] = {}
+    for s in spans:
+        by_run.setdefault(s["run_id"], []).append(s)
+
+    by_project: dict[str, list] = {}
+    for r in runs:
+        by_project.setdefault(_col(r, "project") or "(no project)", []).append(r)
+
+    sections = []
+    for project, project_runs in by_project.items():
+        n = len(project_runs)
+        header = f"## {project}  ·  {n} run{'s' if n != 1 else ''}"
+        run_blocks = [_render_run(r, by_run.get(r["run_id"], [])) for r in project_runs]
+        sections.append(header + "\n\n" + "\n\n---\n\n".join(run_blocks))
+    return "\n\n<br>\n\n".join(sections)
+
+
+# ── Snapshot (the view payloads) ──────────────────────────────────────────────
+
+
+def _snapshot(db_path: str, project: str | None):
+    """Build the view payloads: headline markdown, coordination markdown, model rows."""
+    runs, spans = _fetch(db_path, project)
+
+    total_cost = sum(r["total_cost"] for r in runs)
+    total_runs = len(runs)
+    errored = sum(1 for r in runs if r["status"] == "error")
+    total_in = sum(s["input_tokens"] for s in spans)
+    total_out = sum(s["output_tokens"] for s in spans)
+
+    label = f"`{project}`" if project else "all projects"
+    headline = (
+        f"### DriftCast — {label}\n"
+        f"**${total_cost:.4f}** total  ·  "
+        f"**{total_runs}** runs ({errored} errored)  ·  "
+        f"**{total_in:,}** in / **{total_out:,}** out tokens\n\n"
+        f"<sub>live, refreshes automatically</sub>"
+    )
+
+    coordination_md = _coordination_md(runs, spans)
+
+    stats: dict[str, dict] = {}
+    for s in spans:
+        model = s["model"] or "(no model)"
+        st = stats.setdefault(
+            model, {"calls": 0, "in": 0, "out": 0, "cost": 0.0, "latency_ms": 0.0}
+        )
+        st["calls"] += 1
+        st["in"] += s["input_tokens"]
+        st["out"] += s["output_tokens"]
+        st["cost"] += s["cost"]
+        st["latency_ms"] += s["latency_ms"]
+
+    model_rows = [
+        [
+            model,
+            st["calls"],
+            f"{st['in']:,}",
+            f"{st['out']:,}",
+            f"{st['cost']:.4f}",
+            f"{st['latency_ms'] / st['calls']:.0f}",
+        ]
+        for model, st in sorted(stats.items(), key=lambda kv: kv[1]["cost"], reverse=True)
+    ]
+
+    return headline, coordination_md, model_rows
+
+
+# ── Gradio app ────────────────────────────────────────────────────────────────
+
+
+def build_app(db_path: str, project: str | None = None, refresh_seconds: float = 2.0):
+    """Build (don't launch) the Gradio dashboard app."""
+    import gradio as gr
+
+    def refresh():
+        """Rebuilds the view payloads on each Gradio tick so the dashboard stays live."""
+        return _snapshot(db_path, project)
+
+    with gr.Blocks(title="DriftCast Stats") as demo:
+        # Tier-1 conversion surface: a single static line pointing at the paid layer
+        # (waste attribution, outcome labels, collapse prediction run server-side).
+        gr.Markdown("advanced analysis available at driftcast.dev")
+        headline = gr.Markdown()
+
+        with gr.Tab("Coordination"):
+            gr.Markdown(
+                "<sub>One top-level tree per agent (project), each accumulating its "
+                "runs newest-first. Within a run: orchestrator → chosen subagent → "
+                "provider calls. The badge explains why each run routed where it did; "
+                "the routing LLM calls (route_classify / judge_answer / synthesize) "
+                "show the tokens and cost of the coordination itself.</sub>"
+            )
+            coordination = gr.Markdown()
+
+        with gr.Tab("By model"):
+            model_df = gr.Dataframe(
+                headers=["Model", "Calls", "In tok", "Out tok", "Cost ($)", "Avg ms"],
+                datatype=["str", "number", "str", "str", "str", "str"],
+                interactive=False,
+                wrap=True,
+            )
+
+        outputs = [headline, coordination, model_df]
+        demo.load(refresh, outputs=outputs)              # initial paint
+        gr.Timer(refresh_seconds).tick(refresh, outputs=outputs)  # live refresh
+
+    return demo
+
+
+def launch(
+    db_path: str = "./driftcast.db",
+    project: str | None = None,
+    port: int = 7861,
+    refresh_seconds: float = 2.0,
+    block: bool = True,
+    **launch_kwargs,
+):
+    """Single launch entry point offering both a blocking CLI mode and a non-blocking mode so the dashboard can pop up beside an agent's own UI."""
+    demo = build_app(db_path, project, refresh_seconds)
+    demo.launch(
+        server_port=port,
+        prevent_thread_lock=not block,
+        inbrowser=not block,
+        show_error=True,
+        quiet=True,
+        **launch_kwargs,
+    )
+    return demo
+
+
+# ── Unified launcher (run this file directly) ─────────────────────────────────
+#
+# Everything above is the generic, reusable SDK dashboard. The block below is
+# this repo's single entry point: `python dashboard.py` opens the unified
+# dashboard (every agent's tree) AND starts the Claude Code OTLP listener in the
+# same process, both pointed at one shared db at the project root. It is the only
+# part of this file tied to the repo layout, so it stays out of the import path
+# and runs only when this file is executed directly.
+
+
+def _start_claude_code_listener(db_path: str):
+    """Best-effort in-process receiver start (lazy import, returns None on failure) so a busy port can never take the dashboard down with it."""
+    try:
+        from driftcast.otel import claude_code_tel
+
+        shutdown, _ = claude_code_tel.start_receiver(db_path=db_path)
+        print(
+            "[dashboard] Claude Code listener -> http://127.0.0.1:4318 "
+            "(set OTEL_EXPORTER_OTLP_ENDPOINT to this in the shell running Claude Code)",
+            flush=True,
+        )
+        return shutdown
+    except Exception as exc:  # a missing receiver or busy port must not kill the dashboard
+        print(f"[dashboard] Claude Code listener not started: {exc!r}", flush=True)
+        return None
+
+
+def main():
+    """This repo's single entry point: opens the unified dashboard and the Claude Code listener in one process against one shared db."""
+    import atexit
+    import os
+    import threading
+
+    db_path = default_db_path()
+    port = int(os.getenv("DRIFTCAST_DASHBOARD_PORT", "7861"))
+
+    shutdown = _start_claude_code_listener(db_path)
+    if shutdown is not None:
+        atexit.register(shutdown)
+
+    print(f"[dashboard] unified dashboard -> http://127.0.0.1:{port}  (db: {db_path})", flush=True)
+    # project=None -> all projects: one tree per agent. block=False opens the browser
+    # and serves on a background thread; we then hold the main thread so the daemon
+    # receiver keeps running and Ctrl+C still flushes buffered sessions via atexit.
+    launch(db_path=db_path, project=None, port=port, block=False)
+    try:
+        threading.Event().wait()
+    except KeyboardInterrupt:
+        print("\n[dashboard] shutting down...", flush=True)
+
+
+if __name__ == "__main__":
+    main()

driftcast/otel/__init__.py

@@ -0,0 +1,6 @@
+"""driftcast.otel — OpenTelemetry-based ingestion into DriftCast.
+
+Home for telemetry experiments that replay an external system's OTel stream into
+the same `runs`/`spans` tables the tracer writes. First resident:
+`claude_code_tel`, a local OTLP/HTTP receiver for Claude Code's telemetry.
+"""