agent-cost-tracker 0.2.1__py3-none-any.whl

agent_cost/__init__.py

@@ -0,0 +1,7 @@
+"""Token, cache and context observability for AI coding agents."""
+
+from .models import SessionStats
+from .pricing import estimate_cost
+
+__all__ = ["SessionStats", "estimate_cost"]
+__version__ = "0.1.0"

agent_cost/analyze.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from agent_cost.models import SessionStats
+
+
+def analyze(stats: SessionStats) -> dict:
+    """Derive actionable signals from session statistics."""
+    signals: dict = {"recommendations": [], "context_growth": None, "largest_sources": []}
+
+    samples = [s["estimated_prompt_tokens"] for s in stats.context_samples]
+    if len(samples) >= 4:
+        half = len(samples) // 2
+        first = sum(samples[:half]) / half
+        second = sum(samples[half:]) / (len(samples) - half)
+        ratio = second / first if first else 0.0
+        signals["context_growth"] = {
+            "first_half_avg": round(first),
+            "second_half_avg": round(second),
+            "growth_ratio": round(ratio, 2),
+        }
+        if ratio >= 2.5:
+            signals["recommendations"].append(
+                "Prompt size is growing steeply; start a fresh session instead of continuing."
+            )
+        elif ratio >= 1.6:
+            signals["recommendations"].append(
+                "Context is growing steadily; budget a /compact or a new session soon."
+            )
+
+    if stats.compaction_events:
+        signals["recommendations"].append(
+            f"Session was already compacted {stats.compaction_events}x; further work belongs in a new session."
+        )
+
+    if stats.turns >= 25 and not stats.context_samples:
+        signals["recommendations"].append("High turn count; review whether a new session would be cheaper.")
+
+    has_cache_data = bool(stats.cache_read_tokens or stats.cache_write_tokens)
+    if has_cache_data and stats.cache_hit_rate < 0.4 and stats.prompt_tokens:
+        signals["recommendations"].append(
+            "Low cache hit rate; same-prefix reuse is low, which usually inflates input cost."
+        )
+
+    total_chars = sum(stats.source_chars.values())
+    if total_chars:
+        ranked = sorted(stats.source_chars.items(), key=lambda kv: kv[1], reverse=True)[:4]
+        signals["largest_sources"] = [
+            {"source": k, "percent": round(v * 100 / total_chars, 1)} for k, v in ranked
+        ]
+        if any(k == "tool_output" for k, _ in ranked[:2]):
+            signals["recommendations"].append(
+                "Tool output dominates context; consider truncating or filtering large command output."
+            )
+
+    return signals

agent_cost/cli.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from pathlib import Path
+
+from agent_cost.analyze import analyze
+from agent_cost.compare import compare_sessions
+from agent_cost.models import SessionStats
+from agent_cost.parsers.detect import load_path
+from agent_cost.pricing import estimate_session_cost
+from agent_cost.report import format_analyze, format_compare, format_inspect, format_stats_table
+
+
+def _pricing_override() -> dict | None:
+    env = __import__("os").environ.get("AGENT_COST_PRICING")
+    return json.loads(env) if env else None
+
+
+def _load_all(paths: list[str]) -> list[SessionStats]:
+    stats: list[SessionStats] = []
+    for path in paths:
+        loaded = load_path(path)
+        stats.extend(loaded)
+    return stats
+
+
+def _fill_cost(
+    stats: SessionStats,
+    custom_pricing: dict | None = None,
+    subscription: bool = False,
+) -> float | None:
+    if stats.cost_status in ("actual", "estimated", "included") and stats.estimated_cost_usd > 0:
+        cost = stats.estimated_cost_usd
+    else:
+        cost, status = estimate_session_cost(stats, custom_pricing)
+        if cost is None:
+            return None
+        stats.estimated_cost_usd = cost
+        stats.cost_status = status
+
+    if subscription and stats.cost_status == "estimated":
+        # The tokens were real, the dollars were not spent: a subscription
+        # already covers them. Keep the figure, change what it claims to be.
+        stats.cost_status = "included"
+    return cost
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-cost",
+        description="Token, cache and context observability for AI coding agents.",
+    )
+    parser.add_argument(
+        "--pricing",
+        help="JSON string with custom pricing override.",
+        default=None,
+    )
+    parser.add_argument(
+        "--subscription",
+        action="store_true",
+        default=False,
+        help="Bill through a Claude Pro/Max (or similar) subscription: report costs "
+             "as API-equivalent value rather than money spent.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_inspect = sub.add_parser("inspect", help="Show a single session's usage and cost.")
+    p_inspect.add_argument("paths", nargs="+", help="Session files or directories.")
+
+    p_analyze = sub.add_parser("analyze", help="Context growth and action recommendations.")
+    p_analyze.add_argument("paths", nargs="+", help="Session files or directories.")
+
+    p_stats = sub.add_parser("stats", help="Aggregate totals across sessions.")
+    p_stats.add_argument("paths", nargs="+", help="Session files or directories.")
+
+    p_compare = sub.add_parser("compare", help="Compare usage, cache efficiency, and cost across multiple agents.")
+    p_compare.add_argument("paths", nargs="+", help="Session files or directories to compare.")
+    p_compare.add_argument("--by-agent", action="store_true", default=False, help="Group comparison strictly by agent.")
+    p_compare.add_argument("--json", action="store_true", default=False, help="Output comparison result as JSON.")
+
+    args = parser.parse_args(argv)
+
+    custom_pricing = _pricing_override()
+    if args.pricing:
+        try:
+            custom_pricing = json.loads(args.pricing)
+        except json.JSONDecodeError:
+            print("Error: Invalid JSON for --pricing", file=sys.stderr)
+            return 2
+
+    stats = _load_all(args.paths)
+    if not stats:
+        print("No sessions found.", file=sys.stderr)
+        return 1
+
+    if args.command == "inspect":
+        for s in stats:
+            _fill_cost(s, custom_pricing, args.subscription)
+            print(format_inspect(s))
+            print()
+    elif args.command == "analyze":
+        for s in stats:
+            _fill_cost(s, custom_pricing, args.subscription)
+            signals = analyze(s)
+            print(format_analyze(s, signals))
+            print()
+    elif args.command == "stats":
+        for s in stats:
+            _fill_cost(s, custom_pricing, args.subscription)
+        print(format_stats_table(stats))
+    elif args.command == "compare":
+        result = compare_sessions(stats, custom_pricing, args.subscription)
+        if args.json:
+            out = {
+                "total_sessions": result.total_sessions,
+                "total_tokens": result.total_tokens,
+                "total_cost_usd": result.total_cost_usd,
+                "total_cache_savings_usd": result.total_cache_savings_usd,
+                # Dollar totals cover only the priced sessions; this says how many
+                # were left out so a consumer never reads them as complete.
+                "unpriced_sessions": result.unpriced_sessions,
+                "insights": result.insights,
+                "agents": {
+                    k: dataclasses.asdict(v) for k, v in result.agent_summaries.items()
+                },
+            }
+            # Convert sets to lists for json serialization
+            for a in out["agents"].values():
+                if isinstance(a.get("models"), set):
+                    a["models"] = list(a["models"])
+            print(json.dumps(out, indent=2, ensure_ascii=False))
+        else:
+            print(format_compare(result, by_agent=args.by_agent))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_cost/compare.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from agent_cost.models import SessionStats
+from agent_cost.pricing import estimate_cost, estimate_session_cost
+
+
+@dataclass
+class AgentSummary:
+    agent: str
+    session_count: int = 0
+    models: set[str] = field(default_factory=set)
+    total_tokens: int = 0
+    input_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    output_tokens: int = 0
+    estimated_cost_usd: float = 0.0
+    turns: int = 0
+    tool_calls: int = 0
+    compaction_events: int = 0
+    unpriced_sessions: int = 0
+
+    @property
+    def prompt_tokens(self) -> int:
+        return self.input_tokens + self.cache_read_tokens + self.cache_write_tokens
+
+    @property
+    def cache_hit_rate(self) -> float:
+        prompt = self.prompt_tokens
+        return self.cache_read_tokens / prompt if prompt else 0.0
+
+    @property
+    def avg_cost_per_session(self) -> float:
+        return self.estimated_cost_usd / self.session_count if self.session_count else 0.0
+
+    @property
+    def avg_tokens_per_turn(self) -> float:
+        return self.total_tokens / self.turns if self.turns else 0.0
+
+
+@dataclass
+class CompareResult:
+    sessions: list[SessionStats]
+    agent_summaries: dict[str, AgentSummary]
+    total_sessions: int
+    total_tokens: int
+    total_cost_usd: float
+    total_cache_savings_usd: float
+    unpriced_sessions: int = 0
+    insights: list[str] = field(default_factory=list)
+
+
+def _dominant_mode(stats: SessionStats) -> tuple[str, str]:
+    """The billing mode most of this session's prompt tokens were billed on.
+
+    Used only for the cache-savings counterfactual, which is a single
+    "what if nothing had been cached" figure and so needs one mode, not a
+    per-bucket split.
+    """
+    buckets = getattr(stats, "billing_buckets", None)
+    if not buckets:
+        return "standard", ""
+    key = max(buckets, key=lambda k: buckets[k].get("cache_read", 0) + buckets[k].get("input", 0))
+    speed, _, geo = key.partition("|")
+    return speed, geo
+
+
+def _dominant_speed(stats: SessionStats) -> str:
+    return _dominant_mode(stats)[0]
+
+
+def _dominant_geo(stats: SessionStats) -> str:
+    return _dominant_mode(stats)[1]
+
+
+def compare_sessions(
+    sessions: list[SessionStats],
+    custom_pricing: dict | None = None,
+    subscription: bool = False,
+) -> CompareResult:
+    """Perform side-by-side comparative analysis of multiple agent sessions."""
+    summaries: dict[str, AgentSummary] = {}
+    total_tokens = 0
+    total_cost = 0.0
+    total_savings = 0.0
+
+    for s in sessions:
+        # Ensure cost is filled
+        if s.cost_status == "unknown" or s.estimated_cost_usd == 0.0:
+            c, st = estimate_session_cost(s, custom_pricing)
+            if c is not None:
+                s.estimated_cost_usd = c
+                s.cost_status = st
+        if subscription and s.cost_status == "estimated":
+            s.cost_status = "included"
+
+        agent = s.agent or "unknown"
+        if agent not in summaries:
+            summaries[agent] = AgentSummary(agent=agent)
+
+        summary = summaries[agent]
+        summary.session_count += 1
+        if s.model:
+            summary.models.add(s.model)
+        summary.total_tokens += s.total_tokens
+        summary.input_tokens += s.input_tokens
+        summary.cache_read_tokens += s.cache_read_tokens
+        summary.cache_write_tokens += s.cache_write_tokens
+        summary.output_tokens += s.output_tokens
+        summary.estimated_cost_usd += s.estimated_cost_usd
+        summary.turns += s.turns
+        summary.tool_calls += s.tool_calls
+        summary.compaction_events += s.compaction_events
+        if s.cost_status == "unknown":
+            summary.unpriced_sessions += 1
+
+        total_tokens += s.total_tokens
+        total_cost += s.estimated_cost_usd
+
+        # Calculate approximate cache savings (cost if cache_read was full price input)
+        if s.cache_read_tokens > 0:
+            # Assume base input price difference
+            full_cost, _ = estimate_cost(
+                s.input_tokens + s.cache_read_tokens,
+                s.output_tokens,
+                0,
+                s.cache_write_tokens,
+                s.model,
+                custom_pricing,
+                speed=_dominant_speed(s),
+                inference_geo=_dominant_geo(s),
+            )
+            if full_cost is not None and full_cost > s.estimated_cost_usd:
+                total_savings += (full_cost - s.estimated_cost_usd)
+
+    # Generate insights
+    insights = []
+    if summaries:
+        # Highest cache efficiency
+        best_cache = max(summaries.values(), key=lambda a: a.cache_hit_rate)
+        if best_cache.cache_hit_rate > 0.1:
+            insights.append(
+                f"Highest cache efficiency: {best_cache.agent} ({best_cache.cache_hit_rate*100:.1f}% hit rate)."
+            )
+
+        # Most tool active
+        most_tools = max(summaries.values(), key=lambda a: a.tool_calls)
+        if most_tools.tool_calls > 0:
+            insights.append(
+                f"Most tool intensive: {most_tools.agent} ({most_tools.tool_calls} total tool calls)."
+            )
+
+        # Cost saving impact
+        if total_savings > 0:
+            insights.append(f"Prompt caching saved approx. ${total_savings:.2f} across analyzed sessions.")
+
+    unpriced = sum(1 for s in sessions if s.cost_status == "unknown")
+    if unpriced:
+        insights.append(
+            f"{unpriced} of {len(sessions)} sessions have no rate card and are excluded from "
+            f"every dollar figure above. Supply rates with --pricing to include them."
+        )
+
+    return CompareResult(
+        sessions=sessions,
+        agent_summaries=summaries,
+        total_sessions=len(sessions),
+        total_tokens=total_tokens,
+        total_cost_usd=total_cost,
+        total_cache_savings_usd=total_savings,
+        unpriced_sessions=unpriced,
+        insights=insights,
+    )

agent_cost/models.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SessionStats:
+    """Aggregated usage statistics for one agent session."""
+
+    agent: str
+    session_key: str
+    model: str = ""
+    platform: str = ""
+    cli_version: str = ""
+    cwd: str = ""
+    created_at: str = ""
+    updated_at: str = ""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    estimated_cost_usd: float = 0.0
+    cost_status: str = "unknown"
+    turns: int = 0
+    tool_calls: int = 0
+    compaction_events: int = 0
+    context_samples: list[dict] = field(default_factory=list)
+    source_chars: dict[str, int] = field(default_factory=dict)
+    # Tokens split by billing mode, keyed "<speed>|<inference_geo>". Fast mode and
+    # US-pinned inference are priced differently and can change mid-session, so
+    # the totals above are not enough to price a session correctly. Parsers that
+    # cannot observe these modes leave this empty and are priced off the totals.
+    billing_buckets: dict[str, dict[str, int]] = field(default_factory=dict)
+
+    def add_usage(
+        self,
+        input_tokens: int,
+        output_tokens: int,
+        cache_read: int,
+        cache_write: int,
+        speed: str = "standard",
+        inference_geo: str = "",
+    ) -> None:
+        """Add one turn's usage to both the flat totals and its billing bucket."""
+        self.input_tokens += input_tokens
+        self.output_tokens += output_tokens
+        self.cache_read_tokens += cache_read
+        self.cache_write_tokens += cache_write
+
+        bucket = self.billing_buckets.setdefault(
+            f"{speed or 'standard'}|{inference_geo or ''}",
+            {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0},
+        )
+        bucket["input"] += input_tokens
+        bucket["output"] += output_tokens
+        bucket["cache_read"] += cache_read
+        bucket["cache_write"] += cache_write
+
+    @property
+    def prompt_tokens(self) -> int:
+        return self.input_tokens + self.cache_read_tokens + self.cache_write_tokens
+
+    @property
+    def total_tokens(self) -> int:
+        return self.prompt_tokens + self.output_tokens
+
+    @property
+    def cache_hit_rate(self) -> float:
+        prompt = self.prompt_tokens
+        return self.cache_read_tokens / prompt if prompt else 0.0

agent_cost/parsers/__init__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from agent_cost.parsers.claude import parse_claude_session
+from agent_cost.parsers.codex import parse_codex_rollout
+from agent_cost.parsers.detect import load_path, parse_file
+from agent_cost.parsers.hermes import parse_hermes_sessions
+from agent_cost.parsers.opencode import parse_opencode_session
+
+__all__ = [
+    "load_path",
+    "parse_file",
+    "parse_claude_session",
+    "parse_codex_rollout",
+    "parse_hermes_sessions",
+    "parse_opencode_session",
+]

agent_cost/parsers/claude.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agent_cost.models import SessionStats
+
+
+def _chars(text: object) -> int:
+    return len(str(text or ""))
+
+
+def parse_claude_session(path: str | Path) -> SessionStats:
+    """Parse a Claude Code session log (JSON or JSONL) into SessionStats.
+
+    Claude Code logs interactions and Anthropic API usage objects:
+    - input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens
+    - tool_use content blocks (Bash, FileEdit, GlobTool, etc.)
+    """
+    p = Path(path)
+    stats = SessionStats(agent="claude-code", session_key=p.stem)
+
+    if p.suffix == ".json":
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                return _parse_claude_dict(data, stats)
+            elif isinstance(data, list):
+                return _parse_claude_records(data, stats)
+        except json.JSONDecodeError:
+            pass
+
+    # Process JSONL format (standard Claude Code transcript)
+    turns = 0
+    cumulative_chars = 0
+    with p.open(encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            _process_claude_event(event, stats)
+
+    if stats.turns == 0 and turns > 0:
+        stats.turns = turns
+    return stats
+
+
+def _process_claude_event(event: dict, stats: SessionStats) -> None:
+    # Session metadata if present
+    if "session_id" in event or "sessionId" in event:
+        stats.session_key = str(event.get("session_id") or event.get("sessionId") or stats.session_key)
+    if "cwd" in event:
+        stats.cwd = str(event.get("cwd") or stats.cwd)
+    if "platform" in event or "origin" in event:
+        stats.platform = str(event.get("platform") or event.get("origin") or stats.platform)
+    if "created_at" in event or "timestamp" in event:
+        ts = str(event.get("created_at") or event.get("timestamp") or "")
+        if not stats.created_at:
+            stats.created_at = ts
+        stats.updated_at = ts
+
+    # Check for model
+    model = event.get("model") or (event.get("message", {}) if isinstance(event.get("message"), dict) else {}).get("model")
+    if model and not stats.model:
+        stats.model = str(model)
+
+    # Check for compaction or context prune events
+    etype = event.get("type") or ""
+    if etype in ("compacted", "context_pruned", "summary"):
+        stats.compaction_events += 1
+
+    # Extract usage
+    usage = event.get("usage")
+    if not usage and isinstance(event.get("message"), dict):
+        usage = event.get("message", {}).get("usage")
+
+    if isinstance(usage, dict):
+        inp = int(usage.get("input_tokens") or 0)
+        out = int(usage.get("output_tokens") or 0)
+        cache_read = int(usage.get("cache_read_input_tokens") or usage.get("cache_read_tokens") or 0)
+        cache_write = int(usage.get("cache_creation_input_tokens") or usage.get("cache_write_tokens") or 0)
+
+        # `speed` and `inference_geo` decide which rate card this turn is billed
+        # on, and both can change between turns, so they are recorded per turn.
+        stats.add_usage(
+            inp,
+            out,
+            cache_read,
+            cache_write,
+            speed=str(usage.get("speed") or "standard"),
+            inference_geo=str(usage.get("inference_geo") or ""),
+        )
+
+        stats.turns += 1
+        prompt_tokens_this_turn = inp + cache_read + cache_write
+        stats.context_samples.append({
+            "turn": stats.turns,
+            "estimated_prompt_tokens": prompt_tokens_this_turn,
+        })
+
+    # Count tool uses & source chars
+    content = event.get("content")
+    if not content and isinstance(event.get("message"), dict):
+        content = event.get("message", {}).get("content")
+
+    if isinstance(content, list):
+        for block in content:
+            if isinstance(block, dict):
+                btype = block.get("type")
+                if btype == "tool_use":
+                    stats.tool_calls += 1
+                    tool_name = block.get("name") or "tool"
+                    stats.source_chars["tool_calls"] = stats.source_chars.get("tool_calls", 0) + _chars(tool_name)
+                elif btype == "tool_result":
+                    res_text = block.get("content") or block.get("text") or ""
+                    stats.source_chars["tool_output"] = stats.source_chars.get("tool_output", 0) + _chars(res_text)
+                elif btype == "text":
+                    text = block.get("text") or ""
+                    stats.source_chars["assistant"] = stats.source_chars.get("assistant", 0) + _chars(text)
+    elif isinstance(content, str):
+        role = event.get("role") or event.get("type") or "user"
+        stats.source_chars[role] = stats.source_chars.get(role, 0) + _chars(content)
+
+
+def _parse_claude_dict(data: dict, stats: SessionStats) -> SessionStats:
+    stats.session_key = str(data.get("session_id") or data.get("id") or stats.session_key)
+    stats.model = str(data.get("model") or stats.model)
+    stats.created_at = str(data.get("created_at") or "")
+    stats.updated_at = str(data.get("updated_at") or "")
+
+    messages = data.get("messages") or data.get("transcript") or []
+    if isinstance(messages, list):
+        for item in messages:
+            if isinstance(item, dict):
+                _process_claude_event(item, stats)
+    return stats
+
+
+def _parse_claude_records(records: list[dict], stats: SessionStats) -> SessionStats:
+    for rec in records:
+        if isinstance(rec, dict):
+            _process_claude_event(rec, stats)
+    return stats