cc-transcript 3.3.0__tar.gz → 4.0.0__tar.gz

{cc_transcript-3.3.0 → cc_transcript-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 3.3.0
+Version: 4.0.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -16,7 +16,7 @@ Requires-Dist: orjson>=3.10
 Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: ty>=0.0.44 ; extra == 'dev'
 Requires-Dist: ruff>=0.8 ; extra == 'dev'
-Requires-Dist: spawnllm>=0.1.3 ; extra == 'llm'
+Requires-Dist: spawnllm>=0.2.0 ; extra == 'llm'
 Requires-Dist: spacy>=3.8 ; extra == 'sentiment'
 Requires-Dist: afinn>=0.1 ; extra == 'sentiment'
 Provides-Extra: dev

{cc_transcript-3.3.0 → cc_transcript-4.0.0}/cc_transcript/__init__.py

@@ -97,7 +97,6 @@ EXPORTS: dict[str, str] = {
             "native_user_classifier",
         ),
         "cc_transcript.evidence": (
-            "EXTRACTOR_VERSION",
             "CandidatePair",
             "GitFix",
             "git_corrections",
@@ -320,9 +319,6 @@ if TYPE_CHECKING:
     from cc_transcript.disktruth import (
         load_export as load_export,
     )
-    from cc_transcript.evidence import (
-        EXTRACTOR_VERSION as EXTRACTOR_VERSION,
-    )
     from cc_transcript.evidence import (
         CandidatePair as CandidatePair,
     )

{cc_transcript-3.3.0 → cc_transcript-4.0.0}/cc_transcript/cli.py

@@ -24,6 +24,7 @@ from cc_transcript.builders import (
     drop_synthetic,
     keep_only,
 )
+from cc_transcript.corrections_cli import corrections
 from cc_transcript.discovery import CLAUDE_PROJECTS_DIR, TranscriptDiscovery, find_transcript_sync
 from cc_transcript.filterspec import ASSISTANTS, USERS, EventKind, event_kind, keep
 from cc_transcript.ids import SessionId, tool_digest
@@ -255,6 +256,9 @@ def cli() -> None:
     """Investigate Claude Code transcripts: list, show, grep, and stats."""
 
 
+cli.add_command(corrections)
+
+
 @cli.command("list")
 @discovery_options
 @click.option("--json", "as_json", is_flag=True, help="Emit one JSON object per transcript.")
@@ -424,7 +428,9 @@ def grep(
                 for i in range(lo, hi)
             )
     if not as_json:
-        out.append(f"{files_matched} files, {matched} matches" + (f" · {note}" if (note := scope_note(targets)) else ""))
+        out.append(
+            f"{files_matched} files, {matched} matches" + (f" · {note}" if (note := scope_note(targets)) else "")
+        )
     emit(out)
     if matched == 0:
         raise SystemExit(1)
@@ -449,9 +455,7 @@ def stats(
     targets = resolve_targets(paths, root=root, project=project, contains=contains, limit=None if all_ else limit)
     transcripts = parse_transcripts(targets.paths)
     if per_file and as_json:
-        emit(
-            orjson.dumps({"path": str(parsed.path)} | stats_dict(collect_stats([parsed]))) for parsed in transcripts
-        )
+        emit(orjson.dumps({"path": str(parsed.path)} | stats_dict(collect_stats([parsed]))) for parsed in transcripts)
     elif per_file:
         emit(
             chain(

{cc_transcript-3.3.0 → cc_transcript-4.0.0}/cc_transcript/corrections.py

@@ -1,16 +1,16 @@
 """The shared code-correction ledger every consumer reads and writes.
 
-One SQLite table (``corrections_v1``) records each incorrect edit a developer
-pushed back on paired with the correction that later overwrote it — from the
-same session or from git history. cc-pushback writes it from its enrich pass;
-captain-hook and cc-review join it to their own records by ``incorrect_digest``,
-the same cross-language tool digest the decision ledger keys on. The DDL below
-is vendored byte-identical into the Go repo and byte-compared in CI.
+One SQLite table (``corrections``) records each incorrect edit a developer
+pushed back on paired with the correction that overwrote it — a later edit, a
+git commit, or a reviewer's natural-language note. cc-pushback and captain-hook
+write it from their harvest passes; cc-review writes human review corrections
+through the ``cc-transcript corrections`` CLI; all join it by ``incorrect_digest``,
+the same cross-language tool digest the decision ledger keys on.
 
 Import-light by contract, like :mod:`cc_transcript.ids` and
 :mod:`cc_transcript.decisions`: the standard library plus identity primitives
 only, so a hook reading corrections pays nothing for the parser. The harvest
-that produces rows lives in :func:`cc_transcript.evidence.record_harvest`,
+that produces mined rows lives in :func:`cc_transcript.evidence.record_harvest`,
 which is allowed the heavier activity imports.
 """
 
@@ -29,93 +29,94 @@ if TYPE_CHECKING:
     from cc_transcript.ids import EventUuid, SessionId, ToolDigest
 
 CORRECTIONS_DDL = """\
-CREATE TABLE IF NOT EXISTS corrections_v1 (
+CREATE TABLE IF NOT EXISTS corrections (
     id INTEGER PRIMARY KEY,
     ts_ms INTEGER NOT NULL,
     session_id TEXT NOT NULL,
     source TEXT NOT NULL,
     anchor_uuid TEXT NOT NULL,
-    incorrect_digest TEXT NOT NULL,
+    incorrect_digest TEXT,
     incorrect_file TEXT NOT NULL,
     incorrect_old TEXT NOT NULL,
     incorrect_new TEXT NOT NULL,
-    correction_origin TEXT CHECK (correction_origin IN ('session', 'git')),
+    correction_origin TEXT CHECK (correction_origin IN ('session', 'git', 'review')),
     correction_file TEXT,
     correction_old TEXT,
     correction_new TEXT,
     correction_commit TEXT,
+    correction_text TEXT,
     overlap REAL NOT NULL DEFAULT 0,
-    extractor_version INTEGER NOT NULL,
     detail_json TEXT NOT NULL DEFAULT '{}',
-    UNIQUE (session_id, anchor_uuid, incorrect_digest, extractor_version)
+    UNIQUE (session_id, anchor_uuid, incorrect_digest)
 );
 
-CREATE INDEX IF NOT EXISTS idx_corrections_v1_session_ts ON corrections_v1 (session_id, ts_ms);
+CREATE INDEX IF NOT EXISTS idx_corrections_session_ts ON corrections (session_id, ts_ms);
 
-CREATE INDEX IF NOT EXISTS idx_corrections_v1_incorrect_digest ON corrections_v1 (incorrect_digest);
+CREATE INDEX IF NOT EXISTS idx_corrections_incorrect_digest ON corrections (incorrect_digest);
 """
 
-Origin = Literal["session", "git"]
+Origin = Literal["session", "git", "review"]
 
 CORRECTION_COLUMNS = (
     "ts_ms, session_id, source, anchor_uuid, incorrect_digest, incorrect_file, incorrect_old, "
     "incorrect_new, correction_origin, correction_file, correction_old, correction_new, "
-    "correction_commit, overlap, extractor_version, detail_json"
+    "correction_commit, correction_text, overlap, detail_json"
 )
 
 
 @dataclass(frozen=True, slots=True)
 class Correction:
-    """One incorrect edit and the correction that later overwrote it.
+    """One incorrect edit and the correction that overwrote it.
 
     Attributes:
         ts_ms: Integer-millisecond timestamp of the incorrect edit.
         session_id: The Claude session UUID the edit fired in.
-        source: The writing system, e.g. ``cc-pushback``.
-        anchor_uuid: The transcript uuid of the feedback the harvest anchored on.
+        source: The writing system, e.g. ``cc-pushback``, ``captain-hook``, ``cc-review``.
+        anchor_uuid: The transcript uuid of the feedback the harvest anchored on,
+            or ``review:<reviewID>:<commentID>`` for a human review correction.
         incorrect_digest: The cross-language content digest of the incorrect
-            edit's tool call — the join key shared with ``decisions_v1``.
+            edit's tool call — the join key shared with the ``decisions`` ledger.
+            None for human review corrections, which join by ``anchor_uuid``.
         incorrect_file: The file the incorrect edit targeted.
         incorrect_old: The content the incorrect edit replaced (hunks joined).
         incorrect_new: The content the incorrect edit wrote (hunks joined).
-        extractor_version: The deterministic-extraction version that derived the
-            pair; part of the UNIQUE key.
-        correction_origin: ``'session'`` or ``'git'``, or None when no
-            correction was found.
+        correction_origin: ``'session'``/``'git'`` for a mined code fix,
+            ``'review'`` for a human note, or None when no correction was found.
         correction_file: The file the correction touched, when one exists.
         correction_old: The content the correction replaced, when one exists.
         correction_new: The content the correction wrote, when one exists.
         correction_commit: The full commit hash, when the correction is a git fix.
+        correction_text: The reviewer's verbatim natural-language correction, for
+            ``'review'`` rows; None for mined code corrections.
         overlap: The hunk-overlap score linking incorrect and correction; 0.0
             when there is no correction.
-        detail: Structured extras, serialized to ``detail_json``.
+        detail: Structured extras (e.g. ``repo``), serialized to ``detail_json``.
     """
 
     ts_ms: int
     session_id: SessionId
     source: str
     anchor_uuid: EventUuid
-    incorrect_digest: ToolDigest
+    incorrect_digest: ToolDigest | None
     incorrect_file: str
     incorrect_old: str
     incorrect_new: str
-    extractor_version: int
     correction_origin: Origin | None = None
     correction_file: str | None = None
     correction_old: str | None = None
     correction_new: str | None = None
     correction_commit: str | None = None
+    correction_text: str | None = None
     overlap: float = 0.0
     detail: Mapping[str, Any] = field(default_factory=dict)
 
 
 class CorrectionLog:
-    """The ``corrections_v1`` ledger at ``~/.cc-transcript/corrections.db``.
+    """The ``corrections`` ledger at ``~/.cc-transcript/corrections.db``.
 
     Opened in WAL mode with a busy timeout because writers across the family
-    (and cc-review's Go port) touch the same file concurrently. Durable by
-    convention: rows are never auto-dropped. Requires a local disk — WAL does
-    not work over NFS.
+    touch the same file concurrently. Durable by convention: rows are never
+    auto-dropped. Requires a local disk — WAL does not work over NFS.
 
     Example:
         >>> log = CorrectionLog.open()
@@ -150,11 +151,11 @@ class CorrectionLog:
         """Appends ``correction`` as a single ``INSERT OR IGNORE``.
 
         Idempotent on the UNIQUE key ``(session_id, anchor_uuid,
-        incorrect_digest, extractor_version)`` — re-harvesting the same edit,
-        across reruns or across the pairs of one event, writes one row.
+        incorrect_digest)`` — re-harvesting the same edit, across reruns or
+        across the pairs of one event, writes one row.
         """
         self.conn.execute(
-            f"INSERT OR IGNORE INTO corrections_v1 ({CORRECTION_COLUMNS}) "
+            f"INSERT OR IGNORE INTO corrections ({CORRECTION_COLUMNS}) "
             "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
             (
                 correction.ts_ms,
@@ -170,8 +171,8 @@ class CorrectionLog:
                 correction.correction_old,
                 correction.correction_new,
                 correction.correction_commit,
+                correction.correction_text,
                 correction.overlap,
-                correction.extractor_version,
                 json.dumps(dict(correction.detail)),
             ),
         )
@@ -181,16 +182,44 @@ class CorrectionLog:
         return tuple(
             correction_of(row)
             for row in self.conn.execute(
-                "SELECT * FROM corrections_v1 WHERE session_id = ? ORDER BY ts_ms, id", (session_id,)
+                "SELECT * FROM corrections WHERE session_id = ? ORDER BY ts_ms, id", (session_id,)
             )
         )
 
+    def for_repo(self, repo: str) -> tuple[Correction, ...]:
+        """All corrections whose ``detail.repo`` is ``repo``, ordered by timestamp.
+
+        The repo key producers stamp into ``detail`` so a per-repo consumer (the
+        captain-hook reviewer) can pull every correction for its repo at once.
+        """
+        return tuple(
+            correction_of(row)
+            for row in self.conn.execute(
+                "SELECT * FROM corrections WHERE json_extract(detail_json, '$.repo') = ? ORDER BY ts_ms, id",
+                (repo,),
+            )
+        )
+
+    def since(self, ts_ms: int, *, source: str | None = None) -> tuple[Correction, ...]:
+        """Corrections with ``ts_ms`` strictly greater than ``ts_ms``, oldest first.
+
+        A cursor read for incremental consumers; pass ``source`` to scope to one
+        producer.
+        """
+        if source is None:
+            rows = self.conn.execute("SELECT * FROM corrections WHERE ts_ms > ? ORDER BY ts_ms, id", (ts_ms,))
+        else:
+            rows = self.conn.execute(
+                "SELECT * FROM corrections WHERE ts_ms > ? AND source = ? ORDER BY ts_ms, id", (ts_ms, source)
+            )
+        return tuple(correction_of(row) for row in rows)
+
     def for_anchor(self, session_id: SessionId, anchor_uuid: EventUuid) -> tuple[Correction, ...]:
         """The corrections harvested around one feedback ``anchor_uuid``."""
         return tuple(
             correction_of(row)
             for row in self.conn.execute(
-                "SELECT * FROM corrections_v1 WHERE session_id = ? AND anchor_uuid = ? ORDER BY ts_ms, id",
+                "SELECT * FROM corrections WHERE session_id = ? AND anchor_uuid = ? ORDER BY ts_ms, id",
                 (session_id, anchor_uuid),
             )
         )
@@ -199,12 +228,13 @@ class CorrectionLog:
         """Corrections of the tool call with ``incorrect_digest`` in ``session_id``.
 
         The cross-consumer join: pass the ``tool_digest`` a hook recorded in
-        ``decisions_v1`` to learn whether that exact edit was later corrected.
+        the ``decisions`` ledger to learn whether that exact edit was later
+        corrected.
         """
         return tuple(
             correction_of(row)
             for row in self.conn.execute(
-                "SELECT * FROM corrections_v1 WHERE session_id = ? AND incorrect_digest = ? ORDER BY ts_ms, id",
+                "SELECT * FROM corrections WHERE session_id = ? AND incorrect_digest = ? ORDER BY ts_ms, id",
                 (session_id, incorrect_digest),
             )
         )
@@ -220,12 +250,12 @@ def correction_of(row: sqlite3.Row) -> Correction:
         incorrect_file=row["incorrect_file"],
         incorrect_old=row["incorrect_old"],
         incorrect_new=row["incorrect_new"],
-        extractor_version=row["extractor_version"],
         correction_origin=row["correction_origin"],
         correction_file=row["correction_file"],
         correction_old=row["correction_old"],
         correction_new=row["correction_new"],
         correction_commit=row["correction_commit"],
+        correction_text=row["correction_text"],
         overlap=row["overlap"],
         detail=json.loads(row["detail_json"]),
     )

cc_transcript-4.0.0/cc_transcript/corrections_cli.py

@@ -0,0 +1,122 @@
+"""The ``cc-transcript corrections`` CLI: the ledger's write/read surface for
+non-Python consumers (cc-review's Go) and humans.
+
+The ledger's location is owned here — callers never name the database file. Most
+work goes through the structured ``add``/``query`` commands; ``sql`` is the
+escape hatch for the rare ad-hoc statement.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict
+from typing import cast
+
+import click
+import orjson
+
+from cc_transcript.corrections import Correction, CorrectionLog, Origin
+from cc_transcript.ids import EventUuid, SessionId, ToolDigest
+
+
+def emit_rows(rows: tuple[Correction, ...]) -> None:
+    for row in rows:
+        click.echo(orjson.dumps(asdict(row)))
+
+
+@click.group()
+def corrections() -> None:
+    """Read and write the shared code-correction ledger."""
+
+
+@corrections.command("add")
+@click.option("--session", required=True, help="The Claude session UUID the edit fired in.")
+@click.option("--source", required=True, help="The writing system, e.g. cc-review.")
+@click.option("--anchor", required=True, help="The feedback anchor uuid, or review:<reviewID>:<commentID>.")
+@click.option("--incorrect-file", required=True, help="The file the incorrect edit targeted.")
+@click.option("--ts-ms", type=int, default=None, help="Edit timestamp in ms [default: now].")
+@click.option("--origin", type=click.Choice(["session", "git", "review"]), default=None)
+@click.option("--incorrect-old", default="", help="Content the incorrect edit replaced.")
+@click.option("--incorrect-new", default="", help="Content the incorrect edit wrote.")
+@click.option("--incorrect-digest", default=None, help="Cross-language tool digest; omit for review rows.")
+@click.option("--correction-file", default=None)
+@click.option("--correction-old", default=None)
+@click.option("--correction-new", default=None)
+@click.option("--correction-commit", default=None)
+@click.option("--correction-text", default=None, help="The reviewer's verbatim note, for review rows.")
+@click.option("--overlap", type=float, default=0.0)
+@click.option("--repo", default=None, help="Repo key, stamped into detail.repo.")
+@click.option("--detail", "detail_json", default=None, help="Extra JSON object merged into detail.")
+def add(
+    session: str,
+    source: str,
+    anchor: str,
+    incorrect_file: str,
+    ts_ms: int | None,
+    origin: str | None,
+    incorrect_old: str,
+    incorrect_new: str,
+    incorrect_digest: str | None,
+    correction_file: str | None,
+    correction_old: str | None,
+    correction_new: str | None,
+    correction_commit: str | None,
+    correction_text: str | None,
+    overlap: float,
+    repo: str | None,
+    detail_json: str | None,
+) -> None:
+    """Append one correction to the ledger (idempotent)."""
+    detail = (json.loads(detail_json) if detail_json else {}) | ({"repo": repo} if repo else {})
+    CorrectionLog.open().append(
+        Correction(
+            ts_ms=ts_ms if ts_ms is not None else int(time.time() * 1000),
+            session_id=SessionId(session),
+            source=source,
+            anchor_uuid=EventUuid(anchor),
+            incorrect_digest=ToolDigest(incorrect_digest) if incorrect_digest else None,
+            incorrect_file=incorrect_file,
+            incorrect_old=incorrect_old,
+            incorrect_new=incorrect_new,
+            correction_origin=cast("Origin | None", origin),
+            correction_file=correction_file,
+            correction_old=correction_old,
+            correction_new=correction_new,
+            correction_commit=correction_commit,
+            correction_text=correction_text,
+            overlap=overlap,
+            detail=detail,
+        )
+    )
+
+
+@corrections.command("query")
+@click.option("--session", default=None)
+@click.option("--repo", default=None)
+@click.option("--digest", default=None, help="Requires --session.")
+@click.option("--since", type=int, default=None, help="Corrections with ts_ms greater than this.")
+@click.option("--source", default=None, help="Scopes --since to one producer.")
+def query(session: str | None, repo: str | None, digest: str | None, since: int | None, source: str | None) -> None:
+    """Query corrections as one JSON object per line."""
+    log = CorrectionLog.open()
+    match (session, digest, repo, since):
+        case (str(s), str(d), _, _):
+            emit_rows(log.by_digest(SessionId(s), incorrect_digest=ToolDigest(d)))
+        case (str(s), None, _, _):
+            emit_rows(log.for_session(SessionId(s)))
+        case (None, _, str(r), _):
+            emit_rows(log.for_repo(r))
+        case (None, _, None, int(ts)):
+            emit_rows(log.since(ts, source=source))
+        case _:
+            raise click.UsageError("pass one of --session, --repo, or --since (and --digest only with --session)")
+
+
+@corrections.command("sql")
+@click.argument("statement")
+def sql(statement: str) -> None:
+    """Run a raw SQL statement against the ledger — the escape hatch."""
+    rows = CorrectionLog.open().conn.execute(statement).fetchall()
+    for row in rows:
+        click.echo(orjson.dumps(dict(row)))

{cc_transcript-3.3.0 → cc_transcript-4.0.0}/cc_transcript/evidence.py

@@ -28,9 +28,6 @@ if TYPE_CHECKING:
     from cc_transcript.corrections import CorrectionLog, Origin
     from cc_transcript.ids import EventRef
 
-EXTRACTOR_VERSION = 1
-"""The deterministic-extraction version; part of every derived artifact's UNIQUE key."""
-
 GIT_TIMEOUT_S = 15
 
 
@@ -208,7 +205,6 @@ def record_harvest(
     pairs: Sequence[CandidatePair],
     *,
     source: str,
-    extractor_version: int = EXTRACTOR_VERSION,
 ) -> int:
     """Records ``pairs`` harvested around ``anchor`` into the shared ledger.
 
@@ -220,19 +216,13 @@ def record_harvest(
     Returns:
         The number of corrections appended this call.
     """
-    rows = [
-        correction
-        for pair in pairs
-        if (correction := lower_pair(activity, anchor, pair, source=source, extractor_version=extractor_version))
-    ]
+    rows = [correction for pair in pairs if (correction := lower_pair(activity, anchor, pair, source=source))]
     for row in rows:
         log.append(row)
     return len(rows)
 
 
-def lower_pair(
-    activity: SessionActivity, anchor: EventRef, pair: CandidatePair, *, source: str, extractor_version: int
-) -> Correction | None:
+def lower_pair(activity: SessionActivity, anchor: EventRef, pair: CandidatePair, *, source: str) -> Correction | None:
     if (block := incorrect_block(activity, pair.incorrect)) is None:
         return None
     incorrect_old, incorrect_new = joined_hunks(pair.incorrect.hunks)
@@ -246,7 +236,6 @@ def lower_pair(
         incorrect_file=pair.incorrect.file_path,
         incorrect_old=incorrect_old,
         incorrect_new=incorrect_new,
-        extractor_version=extractor_version,
         correction_origin=origin,
         correction_file=correction_file,
         correction_old=correction_old,

cc_transcript-4.0.0/cc_transcript/extract/__init__.py

@@ -0,0 +1,23 @@
+"""The LLM-grounded correction extractor domain.
+
+Layers on :mod:`cc_transcript.evidence` (the deterministic harvest) and
+:mod:`cc_transcript.judge` (the LLM runner) to pick the one edit a piece of
+feedback faults and append it to the shared ledger. Re-exports lazily so
+``import cc_transcript.extract`` stays free of the ``[llm]`` extra; the symbols
+pull in pydantic only when first accessed.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from cc_transcript.extract.correct import CorrectionPick, extract_correction, usable_backend
+
+    __all__ = ["CorrectionPick", "extract_correction", "usable_backend"]
+
+
+def __getattr__(name: str) -> Any:
+    import importlib
+
+    return getattr(importlib.import_module(f"{__name__}.correct"), name)

cc_transcript-4.0.0/cc_transcript/extract/correct.py

@@ -0,0 +1,181 @@
+"""The canonical, LLM-grounded correction extractor.
+
+:func:`extract_correction` harvests the candidate incorrect edits around a
+feedback anchor (deterministically, via :mod:`cc_transcript.evidence`), then picks
+the single edit the feedback faults and appends that one row to the shared
+ledger. The pick is an LLM call by default — lifted from cc-pushback's enrich
+prompt — and degrades to the best-overlap candidate when no LLM backend is ready
+(:func:`usable_backend` returns None). The pick keys to the candidate's index, so
+the row carries the real cross-language ``incorrect_digest`` from the harvested
+tool call, never reconstructed content.
+
+Behind the ``[llm]`` extra: this module imports pydantic at definition time and
+``spawnllm`` lazily, so only LLM-capable consumers import it. A hook that merely
+reads :mod:`cc_transcript.corrections` pays nothing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from functools import partial
+from typing import TYPE_CHECKING
+
+import anyio
+import anyio.to_thread
+from pydantic import BaseModel
+
+from cc_transcript.evidence import GitFix, harvest_pairs, lower_pair
+from cc_transcript.judge.llm import run_structured_on
+from cc_transcript.render import Budget, hunk_lines
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from spawnllm import LlmBackend, TModel
+
+    from cc_transcript.activity import SessionActivity
+    from cc_transcript.corrections import Correction, CorrectionLog
+    from cc_transcript.evidence import CandidatePair
+    from cc_transcript.ids import EventRef
+    from cc_transcript.tools import Hunk
+
+HUNK_BUDGET = Budget(tool_chars=600)
+
+PICK_PROMPT = """\
+You are grounding one piece of developer FEEDBACK on an AI coding assistant's work
+in the concrete code change it faults.
+
+Below are candidate edits the assistant made shortly before the feedback, newest
+first. Each shows the edit's before (-) and after (+) content and, when one was
+found, the correction that later overwrote it — from the same session, or from git
+history (marked "git <sha>"). The correction ranked most likely by content overlap
+is tagged [likely fix].
+
+Decide which single candidate edit THIS feedback faults, if any:
+- candidate: the NUMBER of the candidate the feedback is about, or null when the
+  feedback is not about any of these edits (it may fault the approach, a command,
+  or work outside this window).
+- note: one short clause explaining the call.
+
+=== CANDIDATE EDITS ===
+{candidates}
+=== FEEDBACK (verbatim) ===
+{feedback}"""
+
+
+class CorrectionPick(BaseModel):
+    """The candidate a piece of feedback faults.
+
+    Attributes:
+        candidate: The 1-based number of the faulted candidate, or None when the
+            feedback is not about any harvested edit.
+        note: One short clause explaining the call.
+    """
+
+    candidate: int | None
+    note: str
+
+
+def hunk_block(hunks: Sequence[Hunk]) -> str:
+    return "\n".join(line for hunk in hunks for line in hunk_lines(hunk.old, hunk.new, budget=HUNK_BUDGET))
+
+
+def likely_fix(pairs: Sequence[CandidatePair]) -> CandidatePair | None:
+    best = max(pairs, key=lambda pair: pair.overlap)
+    return best if best.correction is not None and best.overlap > 0 else None
+
+
+def correction_header(pair: CandidatePair, *, likely: bool) -> str:
+    match pair.correction:
+        case None:
+            return "no correction found"
+        case GitFix(commit=commit):
+            head = f"correction (git {commit}, overlap {pair.overlap:.2f})"
+        case correction:
+            turns = correction.turn_index - pair.incorrect.turn_index
+            head = f"correction (same session, {turns} turn(s) later, overlap {pair.overlap:.2f})"
+    return f"{head} [likely fix]:" if likely else f"{head}:"
+
+
+def candidate_block(index: int, pair: CandidatePair, *, anchor_turn: int, likely: bool) -> str:
+    return "\n".join(
+        (
+            f"--- candidate {index}: {pair.incorrect.file_path} "
+            f"({pair.incorrect.tool}, {anchor_turn - pair.incorrect.turn_index} turn(s) before the feedback) ---",
+            hunk_block(pair.incorrect.hunks),
+            correction_header(pair, likely=likely),
+            *(() if pair.correction is None else (hunk_block(pair.correction.hunks),)),
+        )
+    )
+
+
+def build_pick_prompt(feedback: str, pairs: Sequence[CandidatePair], *, anchor_turn: int) -> str:
+    likely = likely_fix(pairs)
+    return PICK_PROMPT.format(
+        candidates="\n\n".join(
+            candidate_block(index, pair, anchor_turn=anchor_turn, likely=pair is likely)
+            for index, pair in enumerate(pairs, 1)
+        ),
+        feedback=feedback,
+    )
+
+
+def usable_backend() -> LlmBackend | None:
+    """The first ready spawnllm backend for the ``review`` specialty, or None when none is ready.
+
+    Probe once per pass and pass the result to :func:`extract_correction`; the
+    status check spawns a subprocess per call.
+    """
+    from spawnllm import BackendUnavailable, select_backend
+
+    try:
+        return select_backend(specialty="review")
+    except BackendUnavailable:
+        return None
+
+
+async def choose_pair(
+    pairs: Sequence[CandidatePair], *, feedback: str, anchor_turn: int, tier: TModel, backend: LlmBackend | None
+) -> CandidatePair | None:
+    if backend is None:
+        return max(pairs, key=lambda pair: pair.overlap)
+    pick = await run_structured_on(
+        backend, build_pick_prompt(feedback, pairs, anchor_turn=anchor_turn), response_model=CorrectionPick, tier=tier
+    )
+    return pairs[pick.candidate - 1] if pick.candidate is not None and 1 <= pick.candidate <= len(pairs) else None
+
+
+async def extract_correction(
+    log: CorrectionLog,
+    activity: SessionActivity,
+    anchor: EventRef,
+    *,
+    source: str,
+    feedback: str,
+    repo: Path | None = None,
+    tier: TModel = "medium",
+    backend: LlmBackend | None = None,
+) -> Correction | None:
+    """Harvests around ``anchor`` and appends the one correction ``feedback`` faults.
+
+    The faulted candidate is the LLM's pick when ``backend`` is given, else the
+    best-overlap candidate. Idempotent per anchor: a no-op when this anchor
+    already has a row, so re-runs and overlapping producers never duplicate.
+    Returns the appended correction, or None when nothing is harvested or picked.
+    """
+    if log.for_anchor(anchor.session_id, anchor.event_uuid):
+        return None
+    pairs = await anyio.to_thread.run_sync(partial(harvest_pairs, activity, anchor, repo=repo))
+    if not pairs:
+        return None
+    turn = activity.turn_of(anchor)
+    pick = await choose_pair(
+        pairs, feedback=feedback, anchor_turn=turn.index if turn else 0, tier=tier, backend=backend
+    )
+    if pick is None or (row := lower_pair(activity, anchor, pick, source=source)) is None:
+        return None
+    if repo is not None:
+        row = replace(row, detail={"repo": str(repo)})
+    log.append(row)
+    return row

{cc_transcript-3.3.0 → cc_transcript-4.0.0}/cc_transcript/judge/__init__.py

@@ -12,7 +12,7 @@ prompts, the verdict model, and any SQL views over the verdict table.
 
 from __future__ import annotations
 
-from cc_transcript.judge.llm import resolved_model, run_structured, structured_judge
+from cc_transcript.judge.llm import resolved_model, run_structured, run_structured_on, structured_judge
 from cc_transcript.judge.verdicts import (
     AuditEstimate,
     AuditSample,

cc_transcript-4.0.0/cc_transcript/judge/llm.py

@@ -0,0 +1,106 @@
+"""Headless structured completions via spawnllm's first ready CLI backend.
+
+Argv construction and envelope parsing come from the shared ``spawnllm`` library;
+the spawn stays local (``anyio.run_process``). The backend is whichever of
+spawnllm's CLIs is installed and authenticated (:func:`spawnllm.select_backend`),
+using the caller's existing CLI auth — no API key, no pinned provider.
+``spawnllm`` and ``pydantic`` load lazily inside each function, so importing the
+judge package needs no extra installed.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from functools import cache
+from typing import TYPE_CHECKING, cast
+
+import anyio
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from pydantic import BaseModel
+    from spawnllm import LlmBackend, TModel
+
+LLM_TIMEOUT = 180
+
+
+@cache
+def default_backend() -> LlmBackend:
+    """The first installed, authenticated spawnllm backend, cached per process.
+
+    Raises:
+        spawnllm.BackendUnavailable: When no backend is installed and authenticated.
+    """
+    from spawnllm import select_backend
+
+    return select_backend()
+
+
+def resolved_model(tier: TModel) -> str:
+    """The concrete model name the active backend runs for an abstract tier.
+
+    The verdict store keys on this string; it reflects whichever backend
+    :func:`spawnllm.select_backend` resolves, so a judged corpus stays coherent
+    within one backend environment.
+    """
+    return default_backend().models[tier]
+
+
+async def run_structured_on[M: BaseModel](
+    backend: LlmBackend, prompt: str, *, response_model: type[M], tier: TModel, timeout: int = LLM_TIMEOUT
+) -> M:
+    """Runs one structured completion on an explicit ``backend``.
+
+    A caller that resolves a backend once per pass passes it here, so a large pass
+    probes auth once; :func:`run_structured` is the select-and-run convenience.
+
+    Raises:
+        subprocess.SubprocessError: If the backend CLI exits non-zero or times out.
+        pydantic.ValidationError: If the response does not match the schema.
+    """
+    from spawnllm import resolve_schema_path, schema_for
+
+    argv, stdin = backend.invocation(
+        prompt,
+        model=backend.models[tier],
+        schema_path=resolve_schema_path(backend, schema_for(response_model)),
+        agent=False,
+    )
+    try:
+        with anyio.fail_after(timeout):
+            result = await anyio.run_process(
+                argv, input=stdin.encode() if stdin is not None else None, check=True, env=os.environ | backend.env()
+            )
+    except TimeoutError as exc:
+        raise subprocess.TimeoutExpired(argv, timeout) from exc
+    return cast(response_model, backend.parse_response(result.stdout.decode(), response_model))
+
+
+async def run_structured[M: BaseModel](
+    prompt: str, *, response_model: type[M], tier: TModel, timeout: int = LLM_TIMEOUT
+) -> M:
+    """Runs one structured completion on the first ready backend.
+
+    The prompt is delivered to the CLI and the response forced into
+    ``response_model``'s JSON schema. Backend selection is cached per process.
+
+    Raises:
+        spawnllm.BackendUnavailable: If no backend is installed and authenticated.
+        subprocess.SubprocessError: If the backend CLI exits non-zero or times out.
+        pydantic.ValidationError: If the response does not match the schema.
+    """
+    return await run_structured_on(default_backend(), prompt, response_model=response_model, tier=tier, timeout=timeout)
+
+
+def structured_judge[M: BaseModel](
+    response_model: type[M], *, tier: TModel, timeout: int = LLM_TIMEOUT
+) -> Callable[[str], Awaitable[M]]:
+    """Returns a prompt-to-verdict callable that plugs into :func:`run_verdicts`.
+
+    Example:
+        >>> judge = structured_judge(Verdict, tier="medium")
+        >>> await run_verdicts(rows, prompt_for, judge, persist, concurrency=8)
+    """
+    return lambda prompt: run_structured(prompt, response_model=response_model, tier=tier, timeout=timeout)

{cc_transcript-3.3.0 → cc_transcript-4.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cc-transcript"
-version = "3.3.0"
+version = "4.0.0"
 description = "The Claude Code session-activity platform: a superset JSONL parser (Rust fast path, Python reference), typed tool calls with a cross-language content digest, turns/edits/evidence over one spine, context windows with labeled fidelity, unified decision and correction ledgers, LLM judging, and a transcript-investigation CLI."
 readme = "README.md"
 license = "PolyForm-Noncommercial-1.0.0"
@@ -46,7 +46,7 @@ sentiment = [
     "spacy>=3.8",
     "afinn>=0.1",
 ]
-llm = ["spawnllm>=0.1.3"]
+llm = ["spawnllm>=0.2.0"]
 
 [project.scripts]
 cc-transcript = "cc_transcript.cli:cli"

cc_transcript-3.3.0/cc_transcript/judge/llm.py

@@ -1,91 +0,0 @@
-"""Headless structured completions via the ``claude`` CLI, behind the ``[llm]`` extra.
-
-Argv construction and envelope parsing come from the shared ``spawnllm`` library;
-the spawn stays local (``anyio.run_process``). It uses the user's existing Claude
-Code auth (no API key). ``spawnllm`` and ``pydantic`` load lazily inside each
-function, so importing the judge package needs no extra installed.
-"""
-
-from __future__ import annotations
-
-import os
-import subprocess
-from typing import TYPE_CHECKING
-
-import anyio
-
-if TYPE_CHECKING:
-    from collections.abc import Awaitable, Callable
-
-    from pydantic import BaseModel
-    from spawnllm import TModel
-
-CLAUDE_TIMEOUT = 180
-
-
-def resolved_model(tier: TModel) -> str:
-    """Returns the concrete Claude model name for an abstract tier.
-
-    A verdict store's unique key includes the model string, so the resolution
-    must stay byte-identical across releases for a judged corpus to stay valid.
-    """
-    from spawnllm import ClaudeCliBackend
-
-    return ClaudeCliBackend.models[tier]
-
-
-async def run_structured[M: BaseModel](
-    prompt: str, *, response_model: type[M], tier: TModel, timeout: int = CLAUDE_TIMEOUT
-) -> M:
-    """Runs one headless ``claude`` turn and parses its structured output.
-
-    The prompt is delivered over stdin and the response is forced into
-    ``response_model``'s JSON schema via the CLI's ``--json-schema`` flag. The
-    structured path runs with an empty system prompt, so all instructions must
-    live in ``prompt``.
-
-    Args:
-        prompt: The full prompt, instructions included.
-        response_model: The pydantic model the response must validate against.
-        tier: The abstract model tier to run, resolved by the Claude backend.
-        timeout: The per-call wall-clock budget in seconds.
-
-    Returns:
-        The validated ``response_model`` instance.
-
-    Raises:
-        subprocess.SubprocessError: If ``claude`` exits non-zero or times out.
-        pydantic.ValidationError: If the response does not match the schema.
-    """
-    from spawnllm import ClaudeCliBackend, parse_structured_output, resolve_schema_path, schema_for
-
-    backend = ClaudeCliBackend()
-    argv = backend.build_command(
-        backend.models[tier], resolve_schema_path(backend, schema_for(response_model)), agent=False
-    )
-    try:
-        with anyio.fail_after(timeout):
-            result = await anyio.run_process(argv, input=prompt.encode(), check=True, env=os.environ | backend.env())
-    except TimeoutError as exc:
-        raise subprocess.TimeoutExpired(argv, timeout) from exc
-    return parse_structured_output(result.stdout.decode(), response_model)
-
-
-def structured_judge[M: BaseModel](
-    response_model: type[M], *, tier: TModel, timeout: int = CLAUDE_TIMEOUT
-) -> Callable[[str], Awaitable[M]]:
-    """Returns a prompt-to-verdict callable that plugs into :func:`run_verdicts`.
-
-    Args:
-        response_model: The pydantic model each response must validate against.
-        tier: The abstract model tier to run.
-        timeout: The per-call wall-clock budget in seconds.
-
-    Returns:
-        A callable awaiting one structured completion per prompt.
-
-    Example:
-        >>> judge = structured_judge(Verdict, tier="medium")
-        >>> await run_verdicts(rows, prompt_for, judge, persist, concurrency=8)
-    """
-    return lambda prompt: run_structured(prompt, response_model=response_model, tier=tier, timeout=timeout)