agent-decoder 0.3.2__py3-none-any.whl

clau_decode/analytics/pricing.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import json
+import time as _time
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+import httpx
+
+from .models import TokenBreakdown
+
+_LITELLM_URL = (
+    "https://raw.githubusercontent.com/BerriAI/litellm/main/"
+    "model_prices_and_context_window.json"
+)
+
+# API pricing as of May 2026 (USD per million tokens).
+# Keys are model name prefixes for flexible matching.
+_HARDCODED_RATES: dict[str, "ModelPricing"] = {}
+
+
+@dataclass
+class ModelPricing:
+    """Per-model pricing in USD per million tokens."""
+
+    input_per_mtok: Decimal = field(default_factory=lambda: Decimal("0"))
+    output_per_mtok: Decimal = field(default_factory=lambda: Decimal("0"))
+    cache_write_per_mtok: Decimal = field(default_factory=lambda: Decimal("0"))
+    cache_read_per_mtok: Decimal = field(default_factory=lambda: Decimal("0"))
+
+    def compute_cost(self, breakdown: TokenBreakdown) -> Decimal:
+        M = Decimal("1000000")
+        return (
+            self.input_per_mtok * breakdown.input_tokens / M
+            + self.output_per_mtok * breakdown.output_tokens / M
+            + self.cache_write_per_mtok * breakdown.cache_creation_tokens / M
+            + self.cache_read_per_mtok * breakdown.cache_read_tokens / M
+        )
+
+
+_HARDCODED_RATES = {
+    "claude-opus-4-7": ModelPricing(
+        input_per_mtok=Decimal("15.00"),
+        output_per_mtok=Decimal("75.00"),
+        cache_write_per_mtok=Decimal("18.75"),
+        cache_read_per_mtok=Decimal("1.50"),
+    ),
+    "claude-sonnet-4-6": ModelPricing(
+        input_per_mtok=Decimal("3.00"),
+        output_per_mtok=Decimal("15.00"),
+        cache_write_per_mtok=Decimal("3.75"),
+        cache_read_per_mtok=Decimal("0.30"),
+    ),
+    "claude-haiku-4-5": ModelPricing(
+        input_per_mtok=Decimal("0.80"),
+        output_per_mtok=Decimal("4.00"),
+        cache_write_per_mtok=Decimal("1.00"),
+        cache_read_per_mtok=Decimal("0.08"),
+    ),
+    "claude-3-5-sonnet": ModelPricing(
+        input_per_mtok=Decimal("3.00"),
+        output_per_mtok=Decimal("15.00"),
+        cache_write_per_mtok=Decimal("3.75"),
+        cache_read_per_mtok=Decimal("0.30"),
+    ),
+    "claude-3-5-haiku": ModelPricing(
+        input_per_mtok=Decimal("0.80"),
+        output_per_mtok=Decimal("4.00"),
+        cache_write_per_mtok=Decimal("1.00"),
+        cache_read_per_mtok=Decimal("0.08"),
+    ),
+    "claude-3-opus": ModelPricing(
+        input_per_mtok=Decimal("15.00"),
+        output_per_mtok=Decimal("75.00"),
+        cache_write_per_mtok=Decimal("18.75"),
+        cache_read_per_mtok=Decimal("1.50"),
+    ),
+}
+
+
+class HardcodedPricingStrategy:
+    """Static pricing table — exact match first, then prefix match."""
+
+    def get_pricing(self, model: str) -> ModelPricing | None:
+        if model in _HARDCODED_RATES:
+            return _HARDCODED_RATES[model]
+        for prefix, pricing in _HARDCODED_RATES.items():
+            if model.startswith(prefix):
+                return pricing
+        return None
+
+
+class LiteLLMPricingFetcher:
+    """Fetch per-model pricing from LiteLLM's published JSON registry."""
+
+    def __init__(self, url: str = _LITELLM_URL, timeout: float = 10.0) -> None:
+        self._url = url
+        self._timeout = timeout
+
+    async def fetch(self) -> dict[str, ModelPricing]:
+        """Return a dict mapping model name → ModelPricing."""
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.get(self._url)
+                response.raise_for_status()
+                raw: dict = json.loads(response.text)
+        except Exception:
+            return {}
+
+        result: dict[str, ModelPricing] = {}
+        for model, entry in raw.items():
+            if not isinstance(entry, dict):
+                continue
+            if not model.startswith("claude"):
+                continue
+            inp = entry.get("input_cost_per_token") or 0.0
+            out = entry.get("output_cost_per_token") or 0.0
+            cw = entry.get("cache_creation_input_token_cost") or 0.0
+            cr = entry.get("cache_read_input_token_cost") or 0.0
+            result[model] = ModelPricing(
+                input_per_mtok=Decimal(str(round(inp * 1_000_000, 6))),
+                output_per_mtok=Decimal(str(round(out * 1_000_000, 6))),
+                cache_write_per_mtok=Decimal(str(round(cw * 1_000_000, 6))),
+                cache_read_per_mtok=Decimal(str(round(cr * 1_000_000, 6))),
+            )
+        return result
+
+
+class CachedPricingStrategy:
+    """Live pricing from LiteLLM with TTL cache; falls back to hardcoded rates."""
+
+    def __init__(
+        self,
+        fetcher: LiteLLMPricingFetcher | None = None,
+        fallback: HardcodedPricingStrategy | None = None,
+        ttl_seconds: float = 3600.0,
+    ) -> None:
+        self._fetcher = fetcher or LiteLLMPricingFetcher()
+        self._fallback = fallback or HardcodedPricingStrategy()
+        self._ttl = ttl_seconds
+        self._cached_data: dict[str, ModelPricing] = {}
+        self._cache_fetched_at: float = 0.0
+
+    def _is_cache_stale(self) -> bool:
+        return (_time.monotonic() - self._cache_fetched_at) >= self._ttl
+
+    async def refresh(self) -> None:
+        """Fetch fresh pricing from LiteLLM and update the in-memory cache."""
+        data = await self._fetcher.fetch()
+        if data:
+            self._cached_data = data
+            self._cache_fetched_at = _time.monotonic()
+
+    def get_pricing(self, model: str) -> ModelPricing | None:
+        # Try live cache first (exact then prefix)
+        if model in self._cached_data:
+            return self._cached_data[model]
+        for key, pricing in self._cached_data.items():
+            if model.startswith(key):
+                return pricing
+        # Fall back to hardcoded
+        return self._fallback.get_pricing(model)

clau_decode/analytics/prompt.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+from typing import Iterator
+from clau_decode.models import Message
+from .extractor import TokenExtractor
+from .models import PromptCost
+
+
+class PromptIterator:
+    """Yield PromptCost for each non-meta user→assistant pair in a message list."""
+
+    def __init__(
+        self, messages: list[Message], extractor: TokenExtractor | None = None
+    ) -> None:
+        self._messages = messages
+        self._extractor = extractor or TokenExtractor()
+
+    def __iter__(self) -> Iterator[PromptCost]:
+        by_id: dict[str, Message] = {m.id: m for m in self._messages}
+        for msg in self._messages:
+            if msg.role != "assistant":
+                continue
+            if msg.is_sidechain:
+                continue
+            if msg.parent_id is None or msg.parent_id not in by_id:
+                continue
+            parent = by_id[msg.parent_id]
+            if parent.role != "user" or parent.is_meta:
+                continue
+            yield PromptCost(
+                user_message_id=parent.id,
+                assistant_message_id=msg.id,
+                model=msg.model or "unknown",
+                breakdown=self._extractor.extract(msg),
+            )

clau_decode/analytics/service.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from clau_decode.models import Message
+from .aggregator import DailyAggregator, SessionAggregator
+from .extractor import TokenExtractor
+from .models import DailyBucket, PromptCost, TokenBreakdown
+from .prompt import PromptIterator
+
+
+class TokenAnalyticsService:
+    """Facade: answers analytics questions about a list of messages."""
+
+    def __init__(self) -> None:
+        self._extractor = TokenExtractor()
+
+    def session_totals(self, messages: list[Message]) -> TokenBreakdown:
+        return SessionAggregator(self._extractor).aggregate(messages)
+
+    def prompt_breakdown(self, messages: list[Message]) -> list[PromptCost]:
+        prompts = list(PromptIterator(messages, self._extractor))
+        return sorted(prompts, key=lambda p: p.breakdown.total, reverse=True)
+
+    def daily_buckets(self, messages: list[Message]) -> list[DailyBucket]:
+        return DailyAggregator(self._extractor).aggregate(messages)

clau_decode/analytics/stats.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+import statistics
+from collections import Counter, defaultdict
+from typing import Any
+
+from clau_decode.models import Message, ToolUseBlock
+from .extractor import TokenExtractor
+from .prompt import PromptIterator
+
+
+def compute_stats(values: list[int | float]) -> dict[str, Any] | None:
+    """Return mean/median/p95/min/max/count for a non-empty list, else None."""
+    if not values:
+        return None
+    sorted_vals = sorted(values)
+    n = len(sorted_vals)
+    p95_idx = max(0, int(round(0.95 * n)) - 1)
+    return {
+        "count": n,
+        "mean": round(statistics.mean(sorted_vals), 2),
+        "median": statistics.median(sorted_vals),
+        "p95": sorted_vals[p95_idx],
+        "min": sorted_vals[0],
+        "max": sorted_vals[-1],
+    }
+
+
+class PromptStatsScanner:
+    """Compute per-assistant-response token distribution stats across a message list.
+
+    prompt_count is the number of assistant API responses (each tool-use
+    cycle counted separately), not the number of user messages.
+    """
+
+    def __init__(self) -> None:
+        self._extractor = TokenExtractor()
+
+    def scan(self, messages: list[Message]) -> dict[str, Any]:
+        inputs, outputs, totals = [], [], []
+        for prompt in PromptIterator(messages, self._extractor):
+            bd = prompt.breakdown
+            inputs.append(bd.input_tokens)
+            outputs.append(bd.output_tokens)
+            totals.append(bd.total)
+        return {
+            "prompt_count": len(inputs),
+            "input_tokens": compute_stats(inputs),
+            "output_tokens": compute_stats(outputs),
+            "total_tokens": compute_stats(totals),
+        }
+
+
+class ModelUsageScanner:
+    """Aggregate token usage broken down by model name."""
+
+    def scan(self, messages: list[Message]) -> list[dict[str, Any]]:
+        buckets: dict[str, dict[str, int]] = defaultdict(
+            lambda: {
+                "message_count": 0,
+                "input_tokens": 0,
+                "output_tokens": 0,
+                "total_tokens": 0,
+            }
+        )
+        for msg in messages:
+            if msg.role != "assistant" or not msg.model or not msg.usage:
+                continue
+            b = buckets[msg.model]
+            b["message_count"] += 1
+            b["input_tokens"] += msg.usage.input_tokens
+            b["output_tokens"] += msg.usage.output_tokens
+            b["total_tokens"] += (
+                msg.usage.input_tokens
+                + msg.usage.output_tokens
+                + msg.usage.cache_creation_input_tokens
+                + msg.usage.cache_read_input_tokens
+            )
+        result = [{"model": model, **counts} for model, counts in buckets.items()]
+        return sorted(result, key=lambda r: r["total_tokens"], reverse=True)
+
+
+class ToolUsageScanner:
+    """Count tool_use calls by tool name across all messages."""
+
+    def scan(self, messages: list[Message]) -> list[dict[str, Any]]:
+        counts: Counter[str] = Counter()
+        for msg in messages:
+            for block in msg.content_blocks:
+                if isinstance(block, ToolUseBlock):
+                    counts[block.name] += 1
+        return [{"tool": name, "count": count} for name, count in counts.most_common()]
+
+
+class FileTouchScanner:
+    """Count tool invocations by full file path (file_path or path input key).
+
+    Stores the full path so same-named files in different directories are
+    not silently merged. The frontend trims for display.
+    """
+
+    def __init__(self, top_n: int = 20) -> None:
+        self._top_n = top_n
+
+    def scan(self, messages: list[Message]) -> list[dict[str, Any]]:
+        counts: Counter[str] = Counter()
+        for msg in messages:
+            for block in msg.content_blocks:
+                if not isinstance(block, ToolUseBlock):
+                    continue
+                path = block.input.get("file_path") or block.input.get("path") or ""
+                if not path or not isinstance(path, str):
+                    continue
+                counts[path] += 1
+        return [
+            {"file": path, "count": count}
+            for path, count in counts.most_common(self._top_n)
+        ]

clau_decode/analytics/tips.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Literal, Protocol
+
+from clau_decode.models import Message, ToolResultBlock, ToolUseBlock
+
+
+_SEVERITY_ORDER = {"error": 0, "warning": 1, "info": 2}
+_WRITE_TOOLS = frozenset({"Edit", "MultiEdit", "Write", "NotebookEdit"})
+
+
+@dataclass
+class Tip:
+    rule_id: str
+    severity: Literal["info", "warning", "error"]
+    title: str
+    detail: str
+    evidence: list[str] = field(default_factory=list)
+
+
+class TipRule(Protocol):
+    def check(self, messages: list[Message]) -> list[Tip]: ...
+
+
+class TipRegistry:
+    """Run all registered rules and return tips sorted by severity."""
+
+    def __init__(self) -> None:
+        self._rules: list[TipRule] = []
+
+    def register(self, rule: TipRule) -> None:
+        self._rules.append(rule)
+
+    def run(self, messages: list[Message]) -> list[Tip]:
+        tips: list[Tip] = []
+        for rule in self._rules:
+            tips.extend(rule.check(messages))
+        return sorted(tips, key=lambda t: _SEVERITY_ORDER.get(t.severity, 99))
+
+
+class RepeatedFileReadRule:
+    """Flag files that are Read >= threshold times without an intervening write."""
+
+    def __init__(self, threshold: int = 3) -> None:
+        self._threshold = threshold
+
+    def check(self, messages: list[Message]) -> list[Tip]:
+        read_counts: dict[str, int] = defaultdict(int)
+        flagged: dict[str, int] = {}
+
+        for msg in messages:
+            for block in msg.content_blocks:
+                if not isinstance(block, ToolUseBlock):
+                    continue
+                path = block.input.get("file_path") or block.input.get("path") or ""
+                if not path or not isinstance(path, str):
+                    continue
+                if block.name == "Read":
+                    read_counts[path] += 1
+                    if read_counts[path] >= self._threshold:
+                        flagged[path] = read_counts[path]
+                elif block.name in _WRITE_TOOLS:
+                    read_counts[path] = 0
+                    flagged.pop(path, None)
+
+        tips = []
+        for path, count in sorted(flagged.items(), key=lambda x: -x[1]):
+            tips.append(
+                Tip(
+                    rule_id="repeated_file_read",
+                    severity="warning",
+                    title=f"File read {count}× without edit: {path.split('/')[-1]}",
+                    detail=(
+                        "Reading the same file repeatedly re-sends its full content on every "
+                        "prompt turn. Consider reading it once and referencing it from context, "
+                        "or check whether the assistant has already loaded this file."
+                    ),
+                    evidence=[f"{path} — read {count} times"],
+                )
+            )
+        return tips
+
+
+def _result_char_count(block: ToolResultBlock) -> int:
+    if block.content is None:
+        return 0
+    if isinstance(block.content, str):
+        return len(block.content)
+    return sum(
+        len(item.get("text", "")) for item in block.content if isinstance(item, dict)
+    )
+
+
+class OversizedToolResultRule:
+    """Flag tool results larger than threshold_chars characters."""
+
+    def __init__(self, threshold_chars: int = 50_000) -> None:
+        self._threshold = threshold_chars
+
+    def check(self, messages: list[Message]) -> list[Tip]:
+        tips = []
+        for msg in messages:
+            for block in msg.content_blocks:
+                if not isinstance(block, ToolResultBlock):
+                    continue
+                size = _result_char_count(block)
+                if size < self._threshold:
+                    continue
+                size_k = round(size / 1_000)
+                tips.append(
+                    Tip(
+                        rule_id="oversized_tool_result",
+                        severity="warning",
+                        title=f"Oversized tool result (~{size_k}k chars)",
+                        detail=(
+                            "This result was included verbatim in the context window. "
+                            "Large results consume expensive input tokens on every subsequent "
+                            "turn. Consider truncating output, using grep/head, or asking "
+                            "the assistant to request only the relevant section."
+                        ),
+                        evidence=[
+                            f"~{size_k}k chars (tool_use_id: {block.tool_use_id})"
+                        ],
+                    )
+                )
+        return tips
+
+
+class LowCacheHitRule:
+    """Flag corpora where cache-read tokens are < ratio_threshold of all input-type tokens."""
+
+    def __init__(
+        self, ratio_threshold: float = 0.10, min_input_tokens: int = 5_000
+    ) -> None:
+        self._ratio = ratio_threshold
+        self._min_input = min_input_tokens
+
+    def check(self, messages: list[Message]) -> list[Tip]:
+        total_input = 0
+        total_cache_read = 0
+        for msg in messages:
+            if msg.role != "assistant" or not msg.usage:
+                continue
+            total_input += (
+                msg.usage.input_tokens
+                + msg.usage.cache_read_input_tokens
+                + msg.usage.cache_creation_input_tokens
+            )
+            total_cache_read += msg.usage.cache_read_input_tokens
+
+        if total_input < self._min_input:
+            return []
+
+        ratio = total_cache_read / total_input
+        if ratio >= self._ratio:
+            return []
+
+        pct = round(ratio * 100, 1)
+        threshold_pct = round(self._ratio * 100, 1)
+        return [
+            Tip(
+                rule_id="low_cache_hit",
+                severity="info",
+                title=f"Low cache hit ratio ({pct}%)",
+                detail=(
+                    f"Less than {threshold_pct:g}% of input tokens came from cache reads. "
+                    "Pinning large, stable content (system prompts, file context) with "
+                    "cache_control can substantially reduce cost and latency on long sessions."
+                ),
+                evidence=[
+                    f"Cache hit ratio: {pct}% "
+                    f"({total_cache_read:,} cache-read tokens vs {total_input:,} total input tokens)"
+                ],
+            )
+        ]