driftcast 1.0.0__tar.gz

driftcast-1.0.0/LICENSE

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

driftcast-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: driftcast
+Version: 1.0.0
+Summary: Local-first cost and trace telemetry for AI agents — see exactly what each agent spends, per run.
+Author-email: Akash RK <akashrk@avtaarlabs.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AkashRK1216/driftcast
+Project-URL: Repository, https://github.com/AkashRK1216/driftcast
+Project-URL: Issues, https://github.com/AkashRK1216/driftcast/issues
+Keywords: llm,agents,cost,telemetry,observability,tokens,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dashboard
+Requires-Dist: gradio>=4.0.0; extra == "dashboard"
+Dynamic: license-file
+
+# driftcast
+
+Cost and trace telemetry for agent frameworks. Captures actual tokens, cost,
+latency, and errors as your agent runs, persisted to a local SQLite file.
+
+**You own your data.** DriftCast is content-agnostic by default: it records the
+*shape and economics* of execution (token counts, cost, latency, status,
+structure) — never your prompts, completions, or documents. Everything is
+written to a local file you control; there is no DriftCast server in the data
+path. Unlike cloud-coupled tracers (which go dark under Zero Data Retention
+policies), there is nothing to switch off. See [Data ownership](#data-ownership).
+
+One decorator, one explicit call. `@lens.track` turns any function into a
+tracked run or span automatically — nesting into a call-tree on its own. The
+only thing you pass by hand is token usage (`driftcast.record(...)`), because
+provider response shapes differ across providers and call types (embeddings vs.
+chat completions). Everything else — cost lookup, latency, structure,
+persistence — is automatic.
+
+## Install
+
+```bash
+pip install driftcast
+```
+
+Optional local dashboard (Gradio):
+
+```bash
+pip install "driftcast[dashboard]"
+```
+
+The core SDK is stdlib-only. `driftcast[dashboard]` adds the local Gradio
+viewer (`driftcast dashboard`). Claude Code capture via the OTLP receiver
+(`driftcast-otel`) is included in the core install.
+
+**Build from source:**
+
+```bash
+git clone https://github.com/AkashRK1216/driftcast
+cd driftcast
+pip install -e ".[dashboard]"
+```
+
+## Usage
+
+Decorate your functions with `@lens.track`. The **outermost** decorated call
+becomes a *run* (one full pipeline execution); **nested** decorated calls become
+*spans* (individual provider calls), auto-parented into a tree. Inside a span,
+call `driftcast.record(...)` once to report token usage.
+
+```python
+import driftcast
+
+lens = driftcast.init(project="rag-agent", db_path="./driftcast.db")
+
+@lens.track(model="text-embedding-3-small")
+def embed_query(query):
+    result = openai_client.embeddings.create(model=EMBED_MODEL, input=query)
+    driftcast.record(input_tokens=result.usage.prompt_tokens, output_tokens=0)
+    return result
+
+@lens.track(model="gpt-4o-mini")
+def generate_answer(query):
+    response = openai_client.chat.completions.create(...)
+    driftcast.record(
+        input_tokens=response.usage.prompt_tokens,
+        output_tokens=response.usage.completion_tokens,
+    )
+    return response.choices[0].message.content
+
+@lens.track                              # the top-level call is the run
+def ask(query):
+    driftcast.annotate(customer_id="acme")   # business labels onto the run
+    embed_query(query)
+    return generate_answer(query)
+
+ask("what is the refund policy?")
+```
+
+- `@lens.track(model=None, name=None)` — the whole API. The outermost decorated call opens a run; nested decorated calls become spans, auto-nested by call depth. On exit each records `cost`, `latency_ms`, and status; an exception is recorded as `status="error"` and re-raised — tracing never masks a real failure. Works on sync and `async` functions.
+- `driftcast.record(input_tokens, output_tokens, content=None)` — call once inside a `@lens.track(model=...)` function to report what the provider call consumed. This is the one number you pass by hand (provider usage shapes differ). Pass `content=` to persist prompt/response **only** when `capture_content=True` (see Data ownership).
+- `driftcast.annotate(**labels)` — attach business labels (`route`, `customer_id`, judge verdicts…) to the current run's metadata. Always stored, never treated as content.
+- `driftcast.outcome(accepted, wasted=[...])` — at the end of a run, record your own ground-truth label (what you accepted / what was wasted). Content-free; persisted into the run's metadata.
+
+## Data ownership
+
+`driftcast.init(..., capture_content=False)` is the default. In that mode:
+
+- **Content passed via `content=` is dropped before persistence.** Token counts, cost, latency, and structure are still recorded — enough for cost attribution and tracing, with zero prompt/response data at rest.
+- **Error messages are reduced to the exception type** (e.g. `RateLimitError`), since provider errors can echo input content. The full message is kept only when content capture is on.
+- **Metadata is stored separately from content**, so per-customer attribution (`customer_id=...`) never requires storing a prompt.
+
+Set `capture_content=True` to also persist `content=` payloads for debugging — written only to your local `db_path`, never transmitted anywhere. This is the design that lets DriftCast run under Zero Data Retention policies where cloud-coupled tracers cannot.
+
+## CLI
+
+```bash
+driftcast summary --db ./driftcast.db [--project rag-agent]
+```
+
+Prints an aggregate report grouped by run and by model — total cost, total
+tokens, run count, average latency.
+
+## Live dashboard
+
+A web dashboard renders the same data as a live, auto-refreshing view (headline
+totals, runs, per-model cost/tokens/latency). Gradio is an **optional** extra —
+the core SDK stays stdlib-only.
+
+```bash
+pip install -e ".[dashboard]"           # installs gradio
+driftcast dashboard --db ./driftcast.db --project rag-agent --port 7861
+```
+
+To pop it automatically alongside an agent's own UI, launch it non-blocking:
+
+```python
+import driftcast.dashboard as dashboard
+
+# returns immediately; server runs in a background thread on its own port
+dashboard.launch(db_path="./driftcast.db", project="rag-agent", port=7861, block=False)
+```
+
+The RAG test agent does exactly this — running `python main.py` opens the chat
+UI and the stats dashboard side by side (dashboard on port 7861, override with
+`DRIFTCAST_DASHBOARD_PORT`).
+
+## Pricing
+
+`src/driftcast/pricing.py` is a plain editable `$ per 1M tokens` dict. Unknown
+models cost `$0.0` and log a warning, so untracked spend is a visible signal
+to add the model rather than a silent miscalculation.
+
+## Storage
+
+SQLite via stdlib `sqlite3` — file-based, no extra dependency, matches the
+"under $100, personal dogfood" scale this targets. Two tables: `runs` (one row
+per pipeline execution) and `spans` (one row per provider call).

driftcast-1.0.0/README.md

@@ -0,0 +1,138 @@
+# driftcast
+
+Cost and trace telemetry for agent frameworks. Captures actual tokens, cost,
+latency, and errors as your agent runs, persisted to a local SQLite file.
+
+**You own your data.** DriftCast is content-agnostic by default: it records the
+*shape and economics* of execution (token counts, cost, latency, status,
+structure) — never your prompts, completions, or documents. Everything is
+written to a local file you control; there is no DriftCast server in the data
+path. Unlike cloud-coupled tracers (which go dark under Zero Data Retention
+policies), there is nothing to switch off. See [Data ownership](#data-ownership).
+
+One decorator, one explicit call. `@lens.track` turns any function into a
+tracked run or span automatically — nesting into a call-tree on its own. The
+only thing you pass by hand is token usage (`driftcast.record(...)`), because
+provider response shapes differ across providers and call types (embeddings vs.
+chat completions). Everything else — cost lookup, latency, structure,
+persistence — is automatic.
+
+## Install
+
+```bash
+pip install driftcast
+```
+
+Optional local dashboard (Gradio):
+
+```bash
+pip install "driftcast[dashboard]"
+```
+
+The core SDK is stdlib-only. `driftcast[dashboard]` adds the local Gradio
+viewer (`driftcast dashboard`). Claude Code capture via the OTLP receiver
+(`driftcast-otel`) is included in the core install.
+
+**Build from source:**
+
+```bash
+git clone https://github.com/AkashRK1216/driftcast
+cd driftcast
+pip install -e ".[dashboard]"
+```
+
+## Usage
+
+Decorate your functions with `@lens.track`. The **outermost** decorated call
+becomes a *run* (one full pipeline execution); **nested** decorated calls become
+*spans* (individual provider calls), auto-parented into a tree. Inside a span,
+call `driftcast.record(...)` once to report token usage.
+
+```python
+import driftcast
+
+lens = driftcast.init(project="rag-agent", db_path="./driftcast.db")
+
+@lens.track(model="text-embedding-3-small")
+def embed_query(query):
+    result = openai_client.embeddings.create(model=EMBED_MODEL, input=query)
+    driftcast.record(input_tokens=result.usage.prompt_tokens, output_tokens=0)
+    return result
+
+@lens.track(model="gpt-4o-mini")
+def generate_answer(query):
+    response = openai_client.chat.completions.create(...)
+    driftcast.record(
+        input_tokens=response.usage.prompt_tokens,
+        output_tokens=response.usage.completion_tokens,
+    )
+    return response.choices[0].message.content
+
+@lens.track                              # the top-level call is the run
+def ask(query):
+    driftcast.annotate(customer_id="acme")   # business labels onto the run
+    embed_query(query)
+    return generate_answer(query)
+
+ask("what is the refund policy?")
+```
+
+- `@lens.track(model=None, name=None)` — the whole API. The outermost decorated call opens a run; nested decorated calls become spans, auto-nested by call depth. On exit each records `cost`, `latency_ms`, and status; an exception is recorded as `status="error"` and re-raised — tracing never masks a real failure. Works on sync and `async` functions.
+- `driftcast.record(input_tokens, output_tokens, content=None)` — call once inside a `@lens.track(model=...)` function to report what the provider call consumed. This is the one number you pass by hand (provider usage shapes differ). Pass `content=` to persist prompt/response **only** when `capture_content=True` (see Data ownership).
+- `driftcast.annotate(**labels)` — attach business labels (`route`, `customer_id`, judge verdicts…) to the current run's metadata. Always stored, never treated as content.
+- `driftcast.outcome(accepted, wasted=[...])` — at the end of a run, record your own ground-truth label (what you accepted / what was wasted). Content-free; persisted into the run's metadata.
+
+## Data ownership
+
+`driftcast.init(..., capture_content=False)` is the default. In that mode:
+
+- **Content passed via `content=` is dropped before persistence.** Token counts, cost, latency, and structure are still recorded — enough for cost attribution and tracing, with zero prompt/response data at rest.
+- **Error messages are reduced to the exception type** (e.g. `RateLimitError`), since provider errors can echo input content. The full message is kept only when content capture is on.
+- **Metadata is stored separately from content**, so per-customer attribution (`customer_id=...`) never requires storing a prompt.
+
+Set `capture_content=True` to also persist `content=` payloads for debugging — written only to your local `db_path`, never transmitted anywhere. This is the design that lets DriftCast run under Zero Data Retention policies where cloud-coupled tracers cannot.
+
+## CLI
+
+```bash
+driftcast summary --db ./driftcast.db [--project rag-agent]
+```
+
+Prints an aggregate report grouped by run and by model — total cost, total
+tokens, run count, average latency.
+
+## Live dashboard
+
+A web dashboard renders the same data as a live, auto-refreshing view (headline
+totals, runs, per-model cost/tokens/latency). Gradio is an **optional** extra —
+the core SDK stays stdlib-only.
+
+```bash
+pip install -e ".[dashboard]"           # installs gradio
+driftcast dashboard --db ./driftcast.db --project rag-agent --port 7861
+```
+
+To pop it automatically alongside an agent's own UI, launch it non-blocking:
+
+```python
+import driftcast.dashboard as dashboard
+
+# returns immediately; server runs in a background thread on its own port
+dashboard.launch(db_path="./driftcast.db", project="rag-agent", port=7861, block=False)
+```
+
+The RAG test agent does exactly this — running `python main.py` opens the chat
+UI and the stats dashboard side by side (dashboard on port 7861, override with
+`DRIFTCAST_DASHBOARD_PORT`).
+
+## Pricing
+
+`src/driftcast/pricing.py` is a plain editable `$ per 1M tokens` dict. Unknown
+models cost `$0.0` and log a warning, so untracked spend is a visible signal
+to add the model rather than a silent miscalculation.
+
+## Storage
+
+SQLite via stdlib `sqlite3` — file-based, no extra dependency, matches the
+"under $100, personal dogfood" scale this targets. Two tables: `runs` (one row
+per pipeline execution) and `spans` (one row per provider call).

driftcast-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "driftcast"
+version = "1.0.0"
+description = "Local-first cost and trace telemetry for AI agents — see exactly what each agent spends, per run."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Akash RK", email = "akashrk@avtaarlabs.com" }]
+keywords = ["llm", "agents", "cost", "telemetry", "observability", "tokens", "local-first"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dashboard = ["gradio>=4.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/AkashRK1216/driftcast"
+Repository = "https://github.com/AkashRK1216/driftcast"
+Issues = "https://github.com/AkashRK1216/driftcast/issues"
+
+[project.scripts]
+driftcast = "driftcast.cli:main"
+driftcast-otel = "driftcast.otel.claude_code_tel:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"driftcast" = ["py.typed"]

driftcast-1.0.0/setup.cfg

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

driftcast-1.0.0/src/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-1.0.0/src/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()