agentburn 0.2.0__py3-none-any.whl

agentburn/__init__.py

@@ -0,0 +1,8 @@
+"""agentburn — where does your AI agent burn money?
+
+Local, zero-dependency token/cost profiler for always-on AI agents.
+Adapter #1: Hermes Agent (~/.hermes/state.db). Honest methodology:
+numbers come from the agent's own accounting; gaps are surfaced, not hidden.
+"""
+
+__version__ = "0.2.0"

agentburn/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Adapter registry. v0.1 ships Hermes; OpenClaw and Claude Code are next."""
+
+from __future__ import annotations
+
+from . import hermes
+
+ADAPTERS = {
+    "hermes": hermes,
+}
+
+
+def detect() -> list[str]:
+    """Return adapter names whose data is present on this machine."""
+    return [name for name, mod in ADAPTERS.items() if mod.available()]

agentburn/adapters/hermes.py

@@ -0,0 +1,239 @@
+"""Hermes Agent adapter: reads ~/.hermes/state.db (SQLite) read-only.
+
+Schema observed in NousResearch/hermes-agent `hermes_state.py` (June 2026):
+  sessions(id, source, model, parent_session_id, started_at, ended_at,
+           message_count, tool_call_count, api_call_count,
+           input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
+           reasoning_tokens, estimated_cost_usd, actual_cost_usd, cost_status,
+           title, archived, ...)
+  messages(session_id, role, tool_name, tool_calls, timestamp, token_count, ...)
+
+Known upstream accounting gaps (hermes-agent #12023, #6775, #8337): some
+providers/streams record zero tokens. We DETECT and REPORT those gaps instead
+of silently presenting totals as truth.
+
+Optional precision layer: request_dump_*.json files (written when request
+dumping is enabled) contain the full API body; we sample them to estimate the
+input composition (system prompt vs tool definitions vs history).
+"""
+
+from __future__ import annotations
+
+import glob
+import json
+import os
+import sqlite3
+import time
+from typing import Optional
+
+from ..model import DumpComposition, SessionRec, Snapshot, ToolStat
+
+GATEWAY_SOURCES = {
+    "telegram",
+    "whatsapp",
+    "discord",
+    "slack",
+    "signal",
+    "imessage",
+    "email",
+    "api",
+    "api_server",
+    "web",
+}
+
+
+def default_db_path() -> str:
+    return os.path.join(os.path.expanduser("~"), ".hermes", "state.db")
+
+
+def available() -> bool:
+    return os.path.exists(default_db_path())
+
+
+def normalize_source(raw: Optional[str]) -> str:
+    s = (raw or "unknown").strip().lower()
+    if s in ("cli", "cron", "subagent"):
+        return s
+    if s in GATEWAY_SOURCES:
+        return f"gateway:{s}"
+    if s.startswith(("gateway:", "other:")):
+        return s
+    return f"other:{s}"
+
+
+def _columns(con: sqlite3.Connection, table: str) -> set:
+    try:
+        return {r[1] for r in con.execute(f"PRAGMA table_info({table})")}
+    except sqlite3.Error:
+        return set()
+
+
+def _col(cols: set, name: str, default_sql: str = "NULL") -> str:
+    return name if name in cols else f"{default_sql} AS {name}"
+
+
+def load(
+    db_path: Optional[str] = None,
+    days: Optional[int] = 30,
+    dumps_dir: Optional[str] = None,
+    now: Optional[float] = None,
+) -> Snapshot:
+    path = db_path or default_db_path()
+    if not os.path.exists(path):
+        raise FileNotFoundError(
+            f"Hermes state not found at {path}. Pass --db /path/to/state.db "
+            "or run on the machine where Hermes Agent lives."
+        )
+    now = now or time.time()
+    since = now - days * 86400 if days else 0
+
+    snap = Snapshot(
+        agent="hermes",
+        source_path=path,
+        generated_at=now,
+        days=days,
+    )
+
+    con = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    try:
+        con.row_factory = sqlite3.Row
+        scols = _columns(con, "sessions")
+        if "id" not in scols:
+            raise RuntimeError(
+                "sessions table not found — is this really a Hermes state.db? "
+                "(schema may have changed; please open an issue with `PRAGMA table_info(sessions)` output)"
+            )
+
+        fields = ", ".join(
+            [
+                "id",
+                _col(scols, "source", "'unknown'"),
+                _col(scols, "model"),
+                _col(scols, "parent_session_id"),
+                _col(scols, "started_at"),
+                _col(scols, "ended_at"),
+                _col(scols, "title"),
+                _col(scols, "message_count", "0"),
+                _col(scols, "api_call_count", "0"),
+                _col(scols, "input_tokens", "0"),
+                _col(scols, "output_tokens", "0"),
+                _col(scols, "cache_read_tokens", "0"),
+                _col(scols, "cache_write_tokens", "0"),
+                _col(scols, "reasoning_tokens", "0"),
+                _col(scols, "estimated_cost_usd"),
+                _col(scols, "actual_cost_usd"),
+                _col(scols, "billing_provider"),
+            ]
+        )
+        where = "WHERE COALESCE(started_at, 0) >= ?" if days else ""
+        rows = con.execute(
+            f"SELECT {fields} FROM sessions {where}", (since,) if days else ()
+        ).fetchall()
+
+        for r in rows:
+            actual = r["actual_cost_usd"]
+            est = r["estimated_cost_usd"]
+            cost, basis = (
+                (actual, "actual")
+                if actual is not None
+                else (est, "estimated")
+                if est is not None
+                else (None, "unknown")
+            )
+            snap.sessions.append(
+                SessionRec(
+                    id=str(r["id"]),
+                    source=normalize_source(r["source"]),
+                    model=r["model"],
+                    started_at=r["started_at"],
+                    ended_at=r["ended_at"],
+                    parent_id=r["parent_session_id"],
+                    title=r["title"],
+                    api_calls=int(r["api_call_count"] or 0),
+                    input_tokens=int(r["input_tokens"] or 0),
+                    output_tokens=int(r["output_tokens"] or 0),
+                    cache_read_tokens=int(r["cache_read_tokens"] or 0),
+                    cache_write_tokens=int(r["cache_write_tokens"] or 0),
+                    reasoning_tokens=int(r["reasoning_tokens"] or 0),
+                    cost_usd=float(cost) if cost is not None else None,
+                    cost_basis=basis,
+                    message_count=int(r["message_count"] or 0),
+                    provider=r["billing_provider"],
+                )
+            )
+
+        mcols = _columns(con, "messages")
+        if {"tool_name", "timestamp"} <= mcols:
+            tok = "COALESCE(token_count, 0)" if "token_count" in mcols else "0"
+            mwhere = "AND timestamp >= ?" if days else ""
+            for r in con.execute(
+                f"""SELECT tool_name, COUNT(*) AS calls, SUM({tok}) AS toks
+                    FROM messages
+                    WHERE tool_name IS NOT NULL AND tool_name != '' {mwhere}
+                    GROUP BY tool_name ORDER BY toks DESC""",
+                (since,) if days else (),
+            ):
+                snap.tools.append(
+                    ToolStat(name=r["tool_name"], calls=int(r["calls"]), result_tokens=int(r["toks"] or 0))
+                )
+    finally:
+        con.close()
+
+    comp = _sample_dumps(dumps_dir or os.path.join(os.path.dirname(path), "sessions"))
+    if comp:
+        snap.composition = comp
+    return snap
+
+
+def _sample_dumps(dumps_dir: str, limit: int = 20) -> Optional[DumpComposition]:
+    """Estimate input composition from request dumps (newest `limit` files).
+
+    Char-proportional split of the request body: system prompt vs tool
+    definitions vs message history. Proportions, not exact tokens — labeled
+    as sampled estimate in the report.
+    """
+    try:
+        files = sorted(glob.glob(os.path.join(dumps_dir, "request_dump_*.json")))[-limit:]
+    except OSError:
+        return None
+    if not files:
+        return None
+    sys_c = tools_c = hist_c = 0
+    samples = 0
+    for f in files:
+        try:
+            with open(f, "r", encoding="utf-8", errors="replace") as fh:
+                payload = json.load(fh)
+        except (OSError, json.JSONDecodeError):
+            continue
+        body = payload.get("body") or payload.get("request") or payload
+        if not isinstance(body, dict):
+            continue
+        msgs = body.get("messages") or []
+        tools = body.get("tools") or []
+        s = t = h = 0
+        if isinstance(body.get("system"), str):
+            s += len(body["system"])
+        for m in msgs if isinstance(msgs, list) else []:
+            chunk = len(json.dumps(m, ensure_ascii=False, default=str))
+            if isinstance(m, dict) and m.get("role") == "system":
+                s += chunk
+            else:
+                h += chunk
+        t = len(json.dumps(tools, ensure_ascii=False, default=str)) if tools else 0
+        total = s + t + h
+        if total <= 0:
+            continue
+        sys_c += s
+        tools_c += t
+        hist_c += h
+        samples += 1
+    total = sys_c + tools_c + hist_c
+    if samples == 0 or total == 0:
+        return None
+    return DumpComposition(
+        samples=samples,
+        system_share=sys_c / total,
+        tools_share=tools_c / total,
+        history_share=hist_c / total,
+    )

agentburn/analyze.py

@@ -0,0 +1,180 @@
+"""Aggregations over the normalized snapshot. Pure functions, no I/O."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .model import SessionRec, Snapshot
+
+
+@dataclass
+class Bucket:
+    sessions: int = 0
+    api_calls: int = 0
+    tokens: int = 0
+    input_tokens: int = 0
+    cost: float = 0.0
+    cost_known: bool = False
+
+    def add(self, s: SessionRec) -> None:
+        self.sessions += 1
+        self.api_calls += s.api_calls
+        self.tokens += s.total_tokens
+        self.input_tokens += s.input_tokens
+        if s.cost_usd is not None:
+            self.cost += s.cost_usd
+            self.cost_known = True
+
+
+@dataclass
+class ParentRollup:
+    id: str
+    title: str
+    model: Optional[str]
+    own_cost: float
+    sub_cost: float
+    sub_sessions: int
+
+
+@dataclass
+class Analysis:
+    agent: str
+    source_path: str
+    days: Optional[int]
+    period_start: Optional[float]
+    period_end: float
+    total: Bucket
+    by_source: dict
+    by_model: dict
+    tools: list
+    night: Bucket
+    night_by_source: dict
+    night_window: tuple
+    rollups: list
+    overhead_per_call: dict  # source -> avg input tokens per api call
+    composition: object
+    cost_basis: str  # actual | estimated | mixed | unknown
+    zero_token_sessions: int
+    daily_cost: Optional[float]
+    monthly_projection: Optional[float]
+    warnings: list = field(default_factory=list)
+
+
+def _is_night(ts: float, window: tuple) -> bool:
+    h = time.localtime(ts).tm_hour
+    start, end = window
+    if start <= end:
+        return start <= h < end
+    return h >= start or h < end  # wraps midnight, e.g. 23-7
+
+
+def analyze(snap: Snapshot, night_window: tuple = (0, 8)) -> Analysis:
+    total = Bucket()
+    by_source: dict = {}
+    by_model: dict = {}
+    night = Bucket()
+    night_by_source: dict = {}
+    zero_token = 0
+    bases = set()
+
+    for s in snap.sessions:
+        total.add(s)
+        by_source.setdefault(s.source, Bucket()).add(s)
+        by_model.setdefault(s.model or "unknown", Bucket()).add(s)
+        if s.started_at and _is_night(s.started_at, night_window):
+            night.add(s)
+            night_by_source.setdefault(s.source, Bucket()).add(s)
+        if s.total_tokens == 0 and s.message_count > 0:
+            zero_token += 1
+        bases.add(s.cost_basis)
+
+    bases.discard("unknown")
+    cost_basis = (
+        "unknown" if not bases else bases.pop() if len(bases) == 1 else "mixed"
+    )
+
+    # subagent costs rolled up to their root parents
+    by_id = {s.id: s for s in snap.sessions}
+    sub_cost: dict = {}
+    sub_count: dict = {}
+    for s in snap.sessions:
+        if s.source != "subagent":
+            continue
+        root = s
+        seen = set()
+        while root.parent_id and root.parent_id in by_id and root.id not in seen:
+            seen.add(root.id)
+            root = by_id[root.parent_id]
+        if root.id != s.id:
+            sub_cost[root.id] = sub_cost.get(root.id, 0.0) + (s.cost_usd or 0.0)
+            sub_count[root.id] = sub_count.get(root.id, 0) + 1
+    rollups = sorted(
+        (
+            ParentRollup(
+                id=pid,
+                title=(by_id[pid].title or pid)[:60],
+                model=by_id[pid].model,
+                own_cost=by_id[pid].cost_usd or 0.0,
+                sub_cost=c,
+                sub_sessions=sub_count[pid],
+            )
+            for pid, c in sub_cost.items()
+            if pid in by_id
+        ),
+        key=lambda r: r.sub_cost,
+        reverse=True,
+    )[:5]
+
+    overhead = {
+        src: round(b.input_tokens / b.api_calls)
+        for src, b in by_source.items()
+        if b.api_calls > 0
+    }
+
+    starts = [s.started_at for s in snap.sessions if s.started_at]
+    period_start = min(starts) if starts else None
+    span_days = (
+        max(1.0, (snap.generated_at - period_start) / 86400) if period_start else None
+    )
+    daily = (total.cost / span_days) if (span_days and total.cost_known) else None
+
+    warnings = list(snap.warnings)
+    if zero_token > 0:
+        warnings.append(
+            f"{zero_token} session(s) have messages but zero recorded tokens — known Hermes "
+            "accounting gaps (e.g. streaming without usage, hermes-agent #12023). "
+            "All totals are a LOWER BOUND."
+        )
+    if cost_basis == "estimated":
+        warnings.append("Costs are Hermes' own estimates, not provider-billed actuals.")
+    if cost_basis == "mixed":
+        warnings.append("Costs mix provider-billed actuals and Hermes estimates.")
+    if cost_basis == "unknown" and total.tokens > 0:
+        warnings.append("No cost data recorded by Hermes — token counts only.")
+
+    return Analysis(
+        agent=snap.agent,
+        source_path=snap.source_path,
+        days=snap.days,
+        period_start=period_start,
+        period_end=snap.generated_at,
+        total=total,
+        by_source=dict(sorted(by_source.items(), key=lambda kv: kv[1].cost, reverse=True)),
+        by_model=dict(sorted(by_model.items(), key=lambda kv: kv[1].cost, reverse=True)),
+        tools=snap.tools[:10],
+        night=night,
+        night_by_source=dict(
+            sorted(night_by_source.items(), key=lambda kv: kv[1].cost, reverse=True)
+        ),
+        night_window=night_window,
+        rollups=rollups,
+        overhead_per_call=overhead,
+        composition=snap.composition,
+        cost_basis=cost_basis,
+        zero_token_sessions=zero_token,
+        daily_cost=daily,
+        monthly_projection=daily * 30 if daily is not None else None,
+        warnings=warnings,
+    )

agentburn/baseline.py

@@ -0,0 +1,92 @@
+"""Optimize → prove it: save a baseline, change your config, compare.
+
+Comparisons are pace-normalized (per-month figures), so a 7-day baseline can
+be compared against a 30-day current window honestly.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+
+from .analyze import Analysis
+from .report import fmt_money
+
+DEFAULT_PATH = os.path.join(os.path.expanduser("~"), ".agentburn", "baseline.json")
+
+
+def _monthly_by_source(a: Analysis) -> dict:
+    total = a.total.cost or 0.0
+    proj = a.monthly_projection or 0.0
+    if total <= 0 or proj <= 0:
+        return {}
+    return {src: proj * (b.cost / total) for src, b in a.by_source.items() if b.cost > 0}
+
+
+def snapshot_for_baseline(a: Analysis) -> dict:
+    return {
+        "saved_at": time.time(),
+        "agent": a.agent,
+        "days": a.days,
+        "cost_basis": a.cost_basis,
+        "monthly_projection": a.monthly_projection,
+        "monthly_by_source": _monthly_by_source(a),
+        "overhead_per_call": a.overhead_per_call,
+        "night_monthly": (a.monthly_projection or 0.0)
+        * ((a.night.cost / a.total.cost) if (a.total.cost or 0) > 0 else 0.0),
+    }
+
+
+def save(a: Analysis, path: str = DEFAULT_PATH) -> str:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(snapshot_for_baseline(a), f, indent=1)
+    return path
+
+
+def load(path: str = DEFAULT_PATH) -> dict:
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _delta(old: float, new: float, basis: str) -> str:
+    d = new - old
+    pct = f" ({d / old:+.0%})" if old else ""
+    return f"{fmt_money(old, basis)} → {fmt_money(new, basis)}  ({'+' if d >= 0 else '−'}{fmt_money(abs(d), '').lstrip('~')}{pct})"
+
+
+def render_compare(a: Analysis, base: dict) -> str:
+    basis = a.cost_basis
+    cur = snapshot_for_baseline(a)
+    age_days = max(0, (time.time() - base.get("saved_at", time.time())) / 86400)
+    out = ["", f"📐 Δ vs baseline saved {age_days:.0f} day(s) ago", ""]
+
+    bo, co = base.get("monthly_projection"), cur.get("monthly_projection")
+    if bo is not None and co is not None:
+        eps = max(0.01, abs(bo) * 0.002)  # ignore float drift / sub-cent noise
+        verdict = "✅ cheaper" if co < bo - eps else "⚠ more expensive" if co > bo + eps else "≈ flat"
+        out.append(f"   monthly pace : {_delta(bo, co, basis)}  {verdict}")
+
+    bsrc, csrc = base.get("monthly_by_source", {}), cur.get("monthly_by_source", {})
+    for src in sorted(set(bsrc) | set(csrc), key=lambda s: bsrc.get(s, 0), reverse=True)[:6]:
+        out.append(f"   {src:<13}: {_delta(bsrc.get(src, 0.0), csrc.get(src, 0.0), basis)}")
+
+    bov, cov = base.get("overhead_per_call", {}), cur.get("overhead_per_call", {})
+    common = [s for s in cov if s in bov and bov[s] > 0]
+    if common:
+        out.append("")
+        out.append("   overhead, input tokens per call:")
+        for s in sorted(common, key=lambda s: bov[s], reverse=True)[:4]:
+            d = cov[s] - bov[s]
+            out.append(f"   {s:<13}: {bov[s]:,} → {cov[s]:,} ({d:+,})")
+
+    bn, cn = base.get("night_monthly"), cur.get("night_monthly")
+    if bn is not None and cn is not None and (bn or cn):
+        out.append("")
+        out.append(f"   🌙 night/mo   : {_delta(bn, cn, basis)}")
+
+    out.append("")
+    out.append("   (pace-normalized: monthly figures, so different windows compare honestly)")
+    out.append("")
+    return "\n".join(out)

agentburn/benchmarks.py

@@ -0,0 +1,41 @@
+"""Community-measured reference points, embedded as dated constants.
+
+These are NOT our measurements. Each constant carries its public source and
+date; the report cites them verbatim so users can calibrate "is my number
+normal?" without agentburn ever touching the network.
+"""
+
+from __future__ import annotations
+
+# Phala / Clawdi token benchmark of an always-on agent (OpenClaw-class),
+# published 2026-03-10: https://phala.com/posts/understanding-openclaws-token-usage
+PHALA_2026_03 = {
+    "source": "Phala token benchmark, 2026-03",
+    "url": "https://phala.com/posts/understanding-openclaws-token-usage",
+    "baseline_tokens_per_call": 8_000,  # instruction/bootstrap baseline resent per request
+    "multi_turn_5x_cost_factor": 13.3,  # 5-turn dialog vs single turn
+    "output_share_typical": 0.06,  # output is 1–6% of tokens
+}
+
+# Hermes Agent community measurement (user-reported, issue #4379, 2026):
+# https://github.com/NousResearch/hermes-agent/issues/4379
+HERMES_4379 = {
+    "source": "hermes-agent #4379 (user-measured)",
+    "url": "https://github.com/NousResearch/hermes-agent/issues/4379",
+    "fixed_overhead_tokens": 13_935,
+    "overhead_share": 0.73,
+}
+
+REFERENCE_BASELINE = PHALA_2026_03["baseline_tokens_per_call"]
+
+
+def overhead_vs_reference(avg_input_per_call: int) -> str:
+    """One-line calibration against the community baseline."""
+    if avg_input_per_call <= 0:
+        return ""
+    delta = avg_input_per_call / REFERENCE_BASELINE - 1
+    sign = "+" if delta >= 0 else "−"
+    return (
+        f"community baseline ≈{REFERENCE_BASELINE // 1000}k/call "
+        f"({PHALA_2026_03['source']}): {sign}{abs(delta):.0%}"
+    )