contextrot 0.1.0__py3-none-any.whl

contextrot/__init__.py

@@ -0,0 +1,3 @@
+"""contextrot — personal context-rot analytics for coding agents."""
+
+__version__ = "0.1.0"

contextrot/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""Adapter registry."""
+
+from __future__ import annotations
+
+from contextrot.adapters.base import SessionAdapter
+from contextrot.adapters.claude_code import ClaudeCodeAdapter
+
+ADAPTERS: dict[str, SessionAdapter] = {
+    ClaudeCodeAdapter.name: ClaudeCodeAdapter(),
+}
+
+__all__ = ["ADAPTERS", "SessionAdapter", "ClaudeCodeAdapter"]

contextrot/adapters/base.py

@@ -0,0 +1,28 @@
+"""Adapter interface.
+
+To add support for a new agent CLI, subclass SessionAdapter, implement
+discover() and parse(), and register it in adapters/__init__.py. Adapters
+must be tolerant: unknown fields are ignored, malformed lines are skipped,
+and a partially parsed session is better than a crash.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from contextrot.models import Session
+
+
+class SessionAdapter(ABC):
+    """Parses one agent CLI's native transcripts into normalized Sessions."""
+
+    name: str = "base"
+
+    @abstractmethod
+    def discover(self, data_dir: Path | None = None) -> list[Path]:
+        """Return transcript files available on this machine."""
+
+    @abstractmethod
+    def parse(self, path: Path) -> Session | None:
+        """Parse one transcript file. Return None if it holds no usable steps."""

contextrot/adapters/claude_code.py

@@ -0,0 +1,197 @@
+"""Claude Code transcript adapter.
+
+Claude Code stores each session as a JSONL file under
+``~/.claude/projects/<project-slug>/<session-uuid>.jsonl``. Relevant entry
+types:
+
+- ``assistant``: one model API call. ``message.usage`` carries token
+  accounting (``input_tokens``, ``cache_creation_input_tokens``,
+  ``cache_read_input_tokens``, ``output_tokens``); ``message.content`` is a
+  list of blocks (``text``, ``thinking``, ``tool_use``).
+- ``user``: either a human prompt (string content) or tool results
+  (``tool_result`` blocks with ``tool_use_id`` and ``is_error``).
+- ``isSidechain: true`` marks sub-agent traffic; it is counted but excluded
+  from the main step list so fill percentages reflect the primary context
+  window.
+
+Format observed on Claude Code 2.x. Parsing is tolerant by design: fields
+we don't recognize are ignored, lines that fail to decode are skipped.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from contextrot.adapters.base import SessionAdapter
+from contextrot.models import Session, Step, ToolCall
+
+# Tool input keys used as the retry/re-read "target", in priority order.
+_TARGET_KEYS = ("file_path", "path", "url", "pattern", "command", "query")
+
+
+def _parse_ts(raw: object) -> datetime | None:
+    if not isinstance(raw, str):
+        return None
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _target_of(name: str, tool_input: dict) -> str | None:
+    for key in _TARGET_KEYS:
+        val = tool_input.get(key)
+        if isinstance(val, str) and val:
+            # For shell commands, the first line is enough to identify a retry.
+            return val.split("\n", 1)[0][:300]
+    return None
+
+
+def _result_text(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict) and isinstance(block.get("text"), str):
+                parts.append(block["text"])
+        return "\n".join(parts)
+    return ""
+
+
+class ClaudeCodeAdapter(SessionAdapter):
+    name = "claude-code"
+
+    def discover(self, data_dir: Path | None = None) -> list[Path]:
+        root = data_dir or Path.home() / ".claude" / "projects"
+        if not root.is_dir():
+            return []
+        return sorted(root.glob("*/*.jsonl"))
+
+    def parse(self, path: Path) -> Session | None:
+        session = Session(
+            session_id=path.stem,
+            source=self.name,
+            project=path.parent.name,
+        )
+        # tool_use_id -> ToolCall, so results (which arrive in later user
+        # entries) can be attached to the step that made the call.
+        open_calls: dict[str, ToolCall] = {}
+
+        try:
+            with path.open(encoding="utf-8", errors="replace") as fh:
+                for line in fh:
+                    try:
+                        entry = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    if not isinstance(entry, dict):
+                        continue
+                    self._consume(entry, session, open_calls)
+        except OSError:
+            return None
+
+        if not session.steps:
+            return None
+
+        # Use the real working directory as the project name when present.
+        return session
+
+    def _consume(self, entry: dict, session: Session, open_calls: dict[str, ToolCall]) -> None:
+        etype = entry.get("type")
+        if etype == "assistant":
+            if entry.get("isSidechain"):
+                session.sidechain_steps += 1
+                return
+            self._consume_assistant(entry, session, open_calls)
+        elif etype == "user" and not entry.get("isSidechain"):
+            self._consume_user(entry, session, open_calls)
+
+        cwd = entry.get("cwd")
+        if isinstance(cwd, str) and cwd:
+            session.project = cwd
+
+    def _consume_assistant(
+        self, entry: dict, session: Session, open_calls: dict[str, ToolCall]
+    ) -> None:
+        message = entry.get("message")
+        if not isinstance(message, dict):
+            return
+        usage = message.get("usage")
+        ts = _parse_ts(entry.get("timestamp"))
+
+        content = message.get("content")
+        texts: list[str] = []
+        calls: list[ToolCall] = []
+        if isinstance(content, list):
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                btype = block.get("type")
+                if btype == "text" and isinstance(block.get("text"), str):
+                    texts.append(block["text"])
+                elif btype == "tool_use":
+                    name = block.get("name") or "unknown"
+                    raw_input = block.get("input")
+                    tool_input: dict = raw_input if isinstance(raw_input, dict) else {}
+                    call = ToolCall(
+                        name=str(name),
+                        tool_use_id=str(block.get("id") or ""),
+                        target=_target_of(str(name), tool_input),
+                    )
+                    calls.append(call)
+                    if call.tool_use_id:
+                        open_calls[call.tool_use_id] = call
+
+        # Claude Code streams one API call across several assistant entries
+        # that share a requestId; usage rides on each. Merge by requestId so
+        # a single call isn't double counted: only the entry that carries
+        # usage starts a new step, subsequent content is folded in.
+        if isinstance(usage, dict):
+            step = Step(
+                timestamp=ts,
+                model=str(message.get("model") or "unknown"),
+                input_tokens=int(usage.get("input_tokens") or 0),
+                cache_creation_tokens=int(usage.get("cache_creation_input_tokens") or 0),
+                cache_read_tokens=int(usage.get("cache_read_input_tokens") or 0),
+                output_tokens=int(usage.get("output_tokens") or 0),
+                tool_calls=calls,
+                assistant_text="\n".join(texts),
+            )
+            session.steps.append(step)
+            if session.started_at is None:
+                session.started_at = ts
+            if ts is not None:
+                session.ended_at = ts
+        elif session.steps:
+            last = session.steps[-1]
+            last.tool_calls.extend(calls)
+            if texts:
+                last.assistant_text = (last.assistant_text + "\n" + "\n".join(texts)).strip()
+
+    def _consume_user(self, entry: dict, session: Session, open_calls: dict[str, ToolCall]) -> None:
+        message = entry.get("message")
+        if not isinstance(message, dict):
+            return
+        content = message.get("content")
+        if isinstance(content, str):
+            session.user_message_chars += len(content)
+            return
+        if not isinstance(content, list):
+            return
+        for block in content:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "tool_result":
+                call = open_calls.pop(str(block.get("tool_use_id") or ""), None)
+                if call is None:
+                    continue
+                text = _result_text(block.get("content"))
+                call.result_chars = len(text)
+                if block.get("is_error"):
+                    call.is_error = True
+                    call.error_text = text[:500]
+            elif block.get("type") == "text" and isinstance(block.get("text"), str):
+                session.user_message_chars += len(block["text"])

contextrot/analysis/__init__.py

@@ -0,0 +1,106 @@
+"""Analysis orchestrator: transcripts in, AnalysisResult out."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from contextrot.adapters import ADAPTERS
+from contextrot.analysis.composition import Composition, estimate_composition
+from contextrot.analysis.prescriptions import Prescription, prescribe
+from contextrot.analysis.rot import RotCurve, build_rot_curve
+from contextrot.models import Session
+from contextrot.pricing import DEFAULT_CONTEXT_WINDOW, context_window_for
+from contextrot.signals import StepSignals, extract_signals
+
+
+@dataclass
+class AnalysisResult:
+    sessions: list[Session]
+    steps: list[StepSignals]
+    curve: RotCurve
+    composition: Composition
+    prescriptions: list[Prescription]
+    context_window: int
+    total_cost_usd: float
+    rework_cost_usd: float  # cost of degraded steps + their outputs
+    steps_past_knee: int
+    days: int | None
+    skipped_sessions: int = 0
+    signal_rates: dict[str, float] = field(default_factory=dict)
+
+
+def load_sessions(
+    data_dir: Path | None = None,
+    project_filter: str | None = None,
+    days: int | None = None,
+    min_steps: int = 3,
+) -> tuple[list[Session], int]:
+    """Discover and parse sessions across all adapters. Returns (sessions, skipped)."""
+    sessions: list[Session] = []
+    skipped = 0
+    cutoff = datetime.now(UTC) - timedelta(days=days) if days else None
+
+    for adapter in ADAPTERS.values():
+        for path in adapter.discover(data_dir):
+            if cutoff is not None:
+                try:
+                    mtime = datetime.fromtimestamp(path.stat().st_mtime, tz=UTC)
+                    if mtime < cutoff:
+                        continue
+                except OSError:
+                    continue
+            session = adapter.parse(path)
+            if session is None or len(session.steps) < min_steps:
+                skipped += 1
+                continue
+            if project_filter and project_filter.lower() not in session.project.lower():
+                continue
+            sessions.append(session)
+
+    sessions.sort(key=lambda s: (s.started_at or datetime.min.replace(tzinfo=UTC)))
+    return sessions, skipped
+
+
+def analyze(
+    data_dir: Path | None = None,
+    project_filter: str | None = None,
+    days: int | None = 30,
+    window_override: int | None = None,
+) -> AnalysisResult:
+    sessions, skipped = load_sessions(data_dir, project_filter, days)
+
+    all_steps: list[StepSignals] = []
+    window = window_override or DEFAULT_CONTEXT_WINDOW
+    for s in sessions:
+        model = s.steps[0].model if s.steps else ""
+        session_window = context_window_for(model, window_override)
+        window = max(window, session_window)
+        all_steps.extend(extract_signals(s, session_window).steps)
+
+    curve = build_rot_curve(all_steps)
+    comp = estimate_composition(sessions, window)
+
+    total_cost = sum(st.cost_usd for st in all_steps)
+    rework_cost = sum(st.cost_usd for st in all_steps if st.degraded)
+    knee = curve.knee_pct
+    past_knee = sum(1 for st in all_steps if knee is not None and st.fill_pct >= knee)
+
+    n = max(len(all_steps), 1)
+    signal_rates = {name: count / n for name, count in curve.signal_totals.items()}
+
+    return AnalysisResult(
+        sessions=sessions,
+        steps=all_steps,
+        curve=curve,
+        composition=comp,
+        prescriptions=prescribe(curve, comp, rework_cost, past_knee),
+        context_window=window,
+        total_cost_usd=total_cost,
+        rework_cost_usd=rework_cost,
+        steps_past_knee=past_knee,
+        days=days,
+        skipped_sessions=skipped,
+        signal_rates=signal_rates,
+    )

contextrot/analysis/composition.py

@@ -0,0 +1,72 @@
+"""Context-composition estimation.
+
+Transcripts don't record the literal context content, but token accounting
+lets us attribute where the window goes with useful accuracy:
+
+- session overhead: prompt tokens of the *first* API call — system prompt,
+  tool schemas, MCP schemas, CLAUDE.md — everything loaded before the user
+  typed a word
+- tool outputs: estimated from result characters (chars/4 heuristic)
+- conversation: user + assistant text, same heuristic
+- other growth: whatever remains of peak prompt size (thinking, file
+  snapshots, framework bookkeeping)
+
+Figures are labeled as estimates in every report.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from contextrot.models import Session
+
+CHARS_PER_TOKEN = 4
+
+
+@dataclass
+class Composition:
+    overhead_tokens: int  # loaded before the first user word
+    tool_output_tokens: int
+    conversation_tokens: int
+    other_growth_tokens: int
+    peak_prompt_tokens: int
+    context_window: int
+
+    @property
+    def overhead_pct_of_window(self) -> float:
+        return 100.0 * self.overhead_tokens / max(self.context_window, 1)
+
+
+def estimate_composition(sessions: list[Session], context_window: int) -> Composition:
+    """Per-session average composition, so all figures share one scale.
+
+    Tool-output and conversation figures are tokens that *flowed through*
+    the session; with compaction they can exceed the window itself, which
+    is exactly the point — that flow is what fills it.
+    """
+    n = max(len(sessions), 1)
+    overhead_sum = tool_out = convo = 0
+    peak_sum = 0
+    for s in sessions:
+        if s.steps:
+            overhead_sum += s.steps[0].prompt_tokens
+        peak_sum += s.peak_prompt_tokens
+        for st in s.steps:
+            convo += len(st.assistant_text) // CHARS_PER_TOKEN
+            for c in st.tool_calls:
+                tool_out += c.result_chars // CHARS_PER_TOKEN
+        convo += s.user_message_chars // CHARS_PER_TOKEN
+
+    overhead = overhead_sum // n
+    avg_peak = peak_sum // n
+    avg_tool = tool_out // n
+    avg_convo = convo // n
+    other = max(0, avg_peak - overhead - avg_tool - avg_convo)
+    return Composition(
+        overhead_tokens=overhead,
+        tool_output_tokens=avg_tool,
+        conversation_tokens=avg_convo,
+        other_growth_tokens=other,
+        peak_prompt_tokens=avg_peak,
+        context_window=context_window,
+    )

contextrot/analysis/prescriptions.py

@@ -0,0 +1,101 @@
+"""Prescription engine v1.
+
+Rule-based recommendations, each quantified from the user's own data.
+A prescription is only emitted when its evidence threshold is met — an
+empty list is a valid, honest output.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from contextrot.analysis.composition import Composition
+from contextrot.analysis.rot import RotCurve
+
+
+@dataclass
+class Prescription:
+    title: str
+    detail: str
+    impact: str  # quantified expected benefit
+    priority: int  # lower = more important
+
+
+def prescribe(
+    curve: RotCurve,
+    comp: Composition,
+    rework_cost_usd: float,
+    steps_past_knee: int,
+) -> list[Prescription]:
+    out: list[Prescription] = []
+
+    if curve.knee_pct is not None and curve.high_fill_rate and curve.low_fill_rate:
+        out.append(
+            Prescription(
+                title=f"Compact or restart sessions before ~{curve.knee_pct}% context fill",
+                detail=(
+                    f"Your failure-signal rate rises from "
+                    f"{curve.low_fill_rate:.1%} below {int(curve.knee_pct)}% fill to "
+                    f"{curve.high_fill_rate:.1%} in deep context. "
+                    f"{steps_past_knee} of your recent steps ran past that threshold."
+                ),
+                impact=(
+                    f"Estimated ${rework_cost_usd:.2f} of recent spend went to degraded "
+                    "steps and their retries; most of it is concentrated past the knee."
+                ),
+                priority=1,
+            )
+        )
+
+    if comp.overhead_pct_of_window >= 15:
+        out.append(
+            Prescription(
+                title="Audit your session startup overhead",
+                detail=(
+                    f"On average, ~{comp.overhead_tokens:,} tokens "
+                    f"({comp.overhead_pct_of_window:.0f}% of the context window) are "
+                    "loaded before your first word — system prompt, MCP tool schemas, "
+                    "CLAUDE.md. Disable MCP servers you don't use in this project and "
+                    "trim stale CLAUDE.md sections."
+                ),
+                impact=(
+                    "Every point of startup overhead is a point of working context "
+                    "you never get back, in every session."
+                ),
+                priority=2,
+            )
+        )
+
+    total_growth = comp.tool_output_tokens + comp.conversation_tokens + comp.other_growth_tokens
+    if total_growth > 0 and comp.tool_output_tokens / total_growth >= 0.5:
+        out.append(
+            Prescription(
+                title="Tool outputs dominate your context growth",
+                detail=(
+                    f"~{comp.tool_output_tokens:,} tokens (est.) of context growth come "
+                    "from tool results. Prefer targeted reads (offsets, limits), "
+                    "narrower searches, and quieter commands over dumping whole files "
+                    "and logs into the window."
+                ),
+                impact="Slower fill means more steps before the degradation zone.",
+                priority=3,
+            )
+        )
+
+    reread_total = curve.signal_totals.get("reread", 0)
+    if curve.total_steps and reread_total / curve.total_steps >= 0.08:
+        out.append(
+            Prescription(
+                title="Your agent frequently re-reads files it already read",
+                detail=(
+                    f"Re-reads fired on {reread_total} steps "
+                    f"({reread_total / curve.total_steps:.0%}). That usually means the "
+                    "original content scrolled out of effective attention. Splitting "
+                    "large tasks into shorter sessions keeps files 'fresh'."
+                ),
+                impact="Fewer re-reads is both cheaper and a direct rot symptom removed.",
+                priority=4,
+            )
+        )
+
+    return sorted(out, key=lambda p: p.priority)

contextrot/analysis/rot.py

@@ -0,0 +1,132 @@
+"""Rot-curve statistics.
+
+Buckets steps by context-fill percentage and measures how often failure
+signals fire in each bucket. All statistics are observational: this is a
+diagnostic on your own sessions, not a controlled experiment, and the
+report says so. Wilson score intervals are used because bucket counts are
+often small and rates are near the boundary.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+from contextrot.signals import SIGNAL_NAMES, StepSignals
+
+BUCKET_WIDTH = 10  # percent
+LOW_FILL_MAX = 40.0  # "fresh context" zone
+HIGH_FILL_MIN = 60.0  # "deep context" zone
+MIN_BUCKET_N = 15  # buckets below this are shown but marked low-confidence
+KNEE_RATIO = 1.5  # bucket rate vs baseline that marks the degradation knee
+
+
+def wilson_interval(successes: int, n: int, z: float = 1.96) -> tuple[float, float]:
+    if n == 0:
+        return (0.0, 1.0)
+    p = successes / n
+    denom = 1 + z * z / n
+    center = (p + z * z / (2 * n)) / denom
+    margin = (z / denom) * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n))
+    return (max(0.0, center - margin), min(1.0, center + margin))
+
+
+@dataclass
+class Bucket:
+    lo: int  # inclusive fill %
+    hi: int  # exclusive fill %
+    n: int = 0
+    degraded: int = 0
+    by_signal: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def rate(self) -> float:
+        return self.degraded / self.n if self.n else 0.0
+
+    @property
+    def ci(self) -> tuple[float, float]:
+        return wilson_interval(self.degraded, self.n)
+
+    @property
+    def low_confidence(self) -> bool:
+        return self.n < MIN_BUCKET_N
+
+
+@dataclass
+class RotCurve:
+    buckets: list[Bucket]
+    total_steps: int
+    total_degraded: int
+    low_fill_rate: float | None  # rate below LOW_FILL_MAX
+    high_fill_rate: float | None  # rate at/above HIGH_FILL_MIN
+    low_fill_n: int
+    high_fill_n: int
+    degradation_ratio: float | None  # high / low
+    ratio_significant: bool  # Wilson CIs of the two zones don't overlap
+    knee_pct: int | None  # start of first bucket where rate >= KNEE_RATIO * baseline
+    signal_totals: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def overall_rate(self) -> float:
+        return self.total_degraded / self.total_steps if self.total_steps else 0.0
+
+
+def build_rot_curve(steps: list[StepSignals]) -> RotCurve:
+    buckets = [Bucket(lo, lo + BUCKET_WIDTH) for lo in range(0, 100, BUCKET_WIDTH)]
+    signal_totals = dict.fromkeys(SIGNAL_NAMES, 0)
+
+    low_n = low_d = high_n = high_d = 0
+    total_degraded = 0
+
+    for s in steps:
+        idx = min(int(s.fill_pct // BUCKET_WIDTH), len(buckets) - 1)
+        b = buckets[idx]
+        b.n += 1
+        if s.degraded:
+            b.degraded += 1
+            total_degraded += 1
+        for name in SIGNAL_NAMES:
+            if getattr(s, name):
+                b.by_signal[name] = b.by_signal.get(name, 0) + 1
+                signal_totals[name] += 1
+
+        if s.fill_pct < LOW_FILL_MAX:
+            low_n += 1
+            low_d += 1 if s.degraded else 0
+        elif s.fill_pct >= HIGH_FILL_MIN:
+            high_n += 1
+            high_d += 1 if s.degraded else 0
+
+    low_rate = low_d / low_n if low_n else None
+    high_rate = high_d / high_n if high_n else None
+
+    ratio = None
+    significant = False
+    if low_rate is not None and high_rate is not None and low_n and high_n:
+        ratio = high_rate / low_rate if low_rate > 0 else (float("inf") if high_rate > 0 else 1.0)
+        lo_ci = wilson_interval(low_d, low_n)
+        hi_ci = wilson_interval(high_d, high_n)
+        significant = hi_ci[0] > lo_ci[1]  # high zone's floor above low zone's ceiling
+
+    knee = None
+    if low_rate is not None and low_rate > 0:
+        for b in buckets:
+            if b.lo < LOW_FILL_MAX or b.low_confidence:
+                continue
+            if b.rate >= KNEE_RATIO * low_rate:
+                knee = b.lo
+                break
+
+    return RotCurve(
+        buckets=buckets,
+        total_steps=len(steps),
+        total_degraded=total_degraded,
+        low_fill_rate=low_rate,
+        high_fill_rate=high_rate,
+        low_fill_n=low_n,
+        high_fill_n=high_n,
+        degradation_ratio=ratio,
+        ratio_significant=significant,
+        knee_pct=knee,
+        signal_totals=signal_totals,
+    )