cc-transcript 5.0.0__tar.gz → 7.0.0__tar.gz

cc_transcript-7.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: cc-transcript
+Version: 7.0.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Rust
+Classifier: Typing :: Typed
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: anyio>=4.4
+Requires-Dist: click>=8.1
+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.5.0 ; extra == 'llm'
+Requires-Dist: spacy>=3.8 ; extra == 'sentiment'
+Requires-Dist: afinn>=0.1 ; extra == 'sentiment'
+Provides-Extra: dev
+Provides-Extra: llm
+Provides-Extra: sentiment
+License-File: LICENSE
+Summary: 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.
+Keywords: claude-code,claude,anthropic,transcripts,jsonl,parser,cli,agents,sentiment,feedback-mining
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/yasyf/cc-transcript/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://yasyf.github.io/cc-transcript/
+Project-URL: Homepage, https://github.com/yasyf/cc-transcript
+Project-URL: Issues, https://github.com/yasyf/cc-transcript/issues
+Project-URL: Repository, https://github.com/yasyf/cc-transcript
+
+# cc-transcript
+
+![cc-transcript banner](https://github.com/yasyf/cc-transcript/raw/main/docs/assets/readme-banner.webp)
+
+[![PyPI](https://img.shields.io/pypi/v/cc-transcript.svg)](https://pypi.org/project/cc-transcript/)
+[![Python](https://img.shields.io/pypi/pyversions/cc-transcript.svg)](https://pypi.org/project/cc-transcript/)
+[![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/cc-transcript/docs.yml?branch=main&label=docs)](https://yasyf.github.io/cc-transcript/)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm--Noncommercial--1.0.0-blue.svg)](https://github.com/yasyf/cc-transcript/blob/main/LICENSE)
+
+A non-lossy parser for Claude Code's on-disk JSONL transcripts, plus a CLI to investigate sessions.
+
+`cc-transcript` parses Claude Code's JSONL transcripts into a typed superset event model — every entry type preserved, nothing dropped. The parser never silently discards sidechains, synthetic turns, tool results, or unrecognized entries; filtering is opt-in and lives in your code, not buried in the parser. It ships as a Python library, a `uvx`-runnable CLI, and a Claude Code plugin.
+
+## Install
+
+```bash
+uvx cc-transcript --help    # run the CLI
+```
+
+## Quickstart
+
+Discover the transcripts on disk, parse one, and walk the events:
+
+```python
+import anyio
+
+from cc_transcript import AssistantEvent, TranscriptDiscovery, UserEvent, parse_events_from_bytes
+
+path = anyio.run(TranscriptDiscovery.find_transcripts)[0]
+events = parse_events_from_bytes(path.read_bytes())
+
+for event in events:
+    match event:
+        case UserEvent(text=text):
+            print("user:", text[:80])
+        case AssistantEvent(model=model, text=text):
+            print(f"assistant ({model}):", text[:80])
+```
+
+Filtering is opt-in. Compose a spec from small builders and apply it — `build_spec` assembles clauses, `apply_spec` yields the survivors. `NOISE_SPEC` is a ready-made spec for universal structural noise (system reminders, local-command output, skill banners):
+
+```python
+from cc_transcript import apply_spec, build_spec, keep_only, drop_junk, drop_short
+
+spec = build_spec(keep_only("user", "assistant"), drop_junk("structural"), drop_short(2))
+clean = list(apply_spec(events, spec))
+```
+
+## CLI
+
+Every command runs as `uvx cc-transcript <command> ...`; see `--help` on any command for its flags.
+
+| Command  | What it does |
+| -------- | ------------ |
+| `list`   | Find transcripts on disk, newest first |
+| `stats`  | Summarize a session — counts, kinds, models, tools, token sizes, span |
+| `show`   | Render one compact line per event (`--signal` keeps the conversational spine) |
+| `grep`   | Search event content; hit indexes feed back into `show --range` |
+| `slice`  | Emit per-tool-call JSONL for a session UUID and time window (the bridge cc-review consumes) |
+| `digest` | Generate and check the cross-language fixture corpus for the tool-digest contract |
+
+The output is compact by design — one line per event, hard truncation — so an agent triages a session in a few hundred tokens instead of paging through megabytes of JSONL:
+
+```console
+$ uvx cc-transcript stats ~/.claude/projects/-Users-yasyf-Code-cc-transcript/4c77d556-8694-4613-8f50-253d905da68e.jsonl
+files        1
+events       181
+kinds        other 68 · assistant 53 · user 33 · mode 22 · system 5
+models       claude-fable-5 53
+tools        TaskCreate 10 · Agent 5 · Read 5 · TaskUpdate 5 · Bash 2 · ToolSearch 2 · AskUserQuestion 1 · ExitPlanMode 1
+text         14.8KB
+thinking     8.7KB
+tool io      89.0KB
+sessions     1
+span         2026-06-12 01:07:55 → 2026-06-12 02:28:03
+interrupts   0
+tool errors  0
+sidechain    0
+```
+
+## Claude Code plugin
+
+Install the bundled plugin from inside Claude Code:
+
+```
+/plugin marketplace add yasyf/cc-transcript
+/plugin install cc-transcript@cc-transcript
+```
+
+The plugin's skill teaches Claude to answer questions about its own history — "what did I ask yesterday", "find the session where we fixed the parser" — by funneling through the CLI's `list`, `stats`, `grep`, and `show` commands instead of reading raw JSONL.
+
+## How it works
+
+The event model is a superset: sidechains, `<synthetic>` turns, thinking blocks, and unrecognized entry types all survive parsing, so you decide what to drop via composable filter specs. Two engines sit behind one `Backend` protocol — `RustBackend` (PyO3 + rayon) is the default fast path, `PythonBackend` is the readable reference, parity-asserted against each other. On top of the spine, `SessionActivity` lifts events into turns and typed tool calls, `FileStateStore` tracks per-file mtimes in SQLite for incremental re-parses, and `cc_transcript.mining`/`judge`/`sentiment` extract feedback, run LLM verdict passes, and score conversational sentiment. The [docs site](https://yasyf.github.io/cc-transcript/) covers each of these in depth.
+
+## Docs
+
+Each section of [the docs site](https://yasyf.github.io/cc-transcript/) is a focused guide:
+
+- [Getting Started](https://yasyf.github.io/cc-transcript/docs/getting-started/index.html) — install, parse, filter, persist.
+- [Filtering events](https://yasyf.github.io/cc-transcript/docs/guide/filtering-events.html) — clauses, specs, and `NOISE_SPEC`.
+- [Scoring sentiment](https://yasyf.github.io/cc-transcript/docs/guide/scoring-sentiment.html) — the lexicon engine and score specs.
+- [Rust/Python backends & parity](https://yasyf.github.io/cc-transcript/docs/guide/backends-and-parity.html) — the `Backend` protocol and parity testing.
+- [Compose your own policy](https://yasyf.github.io/cc-transcript/docs/guide/compose-your-own-policy.html) — building a bespoke filtering policy.
+- [Mining feedback](https://yasyf.github.io/cc-transcript/docs/guide/mining-feedback.html) — detectors, confidence, candidates, and verdicts.
+- [The transcript CLI](https://yasyf.github.io/cc-transcript/docs/guide/transcript-cli.html) — `list`/`show`/`grep`/`stats` end to end.
+- [API reference](https://yasyf.github.io/cc-transcript/reference/index.html) — the complete typed surface.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE).
+

cc_transcript-7.0.0/README.md

@@ -0,0 +1,111 @@
+# cc-transcript
+
+![cc-transcript banner](https://github.com/yasyf/cc-transcript/raw/main/docs/assets/readme-banner.webp)
+
+[![PyPI](https://img.shields.io/pypi/v/cc-transcript.svg)](https://pypi.org/project/cc-transcript/)
+[![Python](https://img.shields.io/pypi/pyversions/cc-transcript.svg)](https://pypi.org/project/cc-transcript/)
+[![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/cc-transcript/docs.yml?branch=main&label=docs)](https://yasyf.github.io/cc-transcript/)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm--Noncommercial--1.0.0-blue.svg)](https://github.com/yasyf/cc-transcript/blob/main/LICENSE)
+
+A non-lossy parser for Claude Code's on-disk JSONL transcripts, plus a CLI to investigate sessions.
+
+`cc-transcript` parses Claude Code's JSONL transcripts into a typed superset event model — every entry type preserved, nothing dropped. The parser never silently discards sidechains, synthetic turns, tool results, or unrecognized entries; filtering is opt-in and lives in your code, not buried in the parser. It ships as a Python library, a `uvx`-runnable CLI, and a Claude Code plugin.
+
+## Install
+
+```bash
+uvx cc-transcript --help    # run the CLI
+```
+
+## Quickstart
+
+Discover the transcripts on disk, parse one, and walk the events:
+
+```python
+import anyio
+
+from cc_transcript import AssistantEvent, TranscriptDiscovery, UserEvent, parse_events_from_bytes
+
+path = anyio.run(TranscriptDiscovery.find_transcripts)[0]
+events = parse_events_from_bytes(path.read_bytes())
+
+for event in events:
+    match event:
+        case UserEvent(text=text):
+            print("user:", text[:80])
+        case AssistantEvent(model=model, text=text):
+            print(f"assistant ({model}):", text[:80])
+```
+
+Filtering is opt-in. Compose a spec from small builders and apply it — `build_spec` assembles clauses, `apply_spec` yields the survivors. `NOISE_SPEC` is a ready-made spec for universal structural noise (system reminders, local-command output, skill banners):
+
+```python
+from cc_transcript import apply_spec, build_spec, keep_only, drop_junk, drop_short
+
+spec = build_spec(keep_only("user", "assistant"), drop_junk("structural"), drop_short(2))
+clean = list(apply_spec(events, spec))
+```
+
+## CLI
+
+Every command runs as `uvx cc-transcript <command> ...`; see `--help` on any command for its flags.
+
+| Command  | What it does |
+| -------- | ------------ |
+| `list`   | Find transcripts on disk, newest first |
+| `stats`  | Summarize a session — counts, kinds, models, tools, token sizes, span |
+| `show`   | Render one compact line per event (`--signal` keeps the conversational spine) |
+| `grep`   | Search event content; hit indexes feed back into `show --range` |
+| `slice`  | Emit per-tool-call JSONL for a session UUID and time window (the bridge cc-review consumes) |
+| `digest` | Generate and check the cross-language fixture corpus for the tool-digest contract |
+
+The output is compact by design — one line per event, hard truncation — so an agent triages a session in a few hundred tokens instead of paging through megabytes of JSONL:
+
+```console
+$ uvx cc-transcript stats ~/.claude/projects/-Users-yasyf-Code-cc-transcript/4c77d556-8694-4613-8f50-253d905da68e.jsonl
+files        1
+events       181
+kinds        other 68 · assistant 53 · user 33 · mode 22 · system 5
+models       claude-fable-5 53
+tools        TaskCreate 10 · Agent 5 · Read 5 · TaskUpdate 5 · Bash 2 · ToolSearch 2 · AskUserQuestion 1 · ExitPlanMode 1
+text         14.8KB
+thinking     8.7KB
+tool io      89.0KB
+sessions     1
+span         2026-06-12 01:07:55 → 2026-06-12 02:28:03
+interrupts   0
+tool errors  0
+sidechain    0
+```
+
+## Claude Code plugin
+
+Install the bundled plugin from inside Claude Code:
+
+```
+/plugin marketplace add yasyf/cc-transcript
+/plugin install cc-transcript@cc-transcript
+```
+
+The plugin's skill teaches Claude to answer questions about its own history — "what did I ask yesterday", "find the session where we fixed the parser" — by funneling through the CLI's `list`, `stats`, `grep`, and `show` commands instead of reading raw JSONL.
+
+## How it works
+
+The event model is a superset: sidechains, `<synthetic>` turns, thinking blocks, and unrecognized entry types all survive parsing, so you decide what to drop via composable filter specs. Two engines sit behind one `Backend` protocol — `RustBackend` (PyO3 + rayon) is the default fast path, `PythonBackend` is the readable reference, parity-asserted against each other. On top of the spine, `SessionActivity` lifts events into turns and typed tool calls, `FileStateStore` tracks per-file mtimes in SQLite for incremental re-parses, and `cc_transcript.mining`/`judge`/`sentiment` extract feedback, run LLM verdict passes, and score conversational sentiment. The [docs site](https://yasyf.github.io/cc-transcript/) covers each of these in depth.
+
+## Docs
+
+Each section of [the docs site](https://yasyf.github.io/cc-transcript/) is a focused guide:
+
+- [Getting Started](https://yasyf.github.io/cc-transcript/docs/getting-started/index.html) — install, parse, filter, persist.
+- [Filtering events](https://yasyf.github.io/cc-transcript/docs/guide/filtering-events.html) — clauses, specs, and `NOISE_SPEC`.
+- [Scoring sentiment](https://yasyf.github.io/cc-transcript/docs/guide/scoring-sentiment.html) — the lexicon engine and score specs.
+- [Rust/Python backends & parity](https://yasyf.github.io/cc-transcript/docs/guide/backends-and-parity.html) — the `Backend` protocol and parity testing.
+- [Compose your own policy](https://yasyf.github.io/cc-transcript/docs/guide/compose-your-own-policy.html) — building a bespoke filtering policy.
+- [Mining feedback](https://yasyf.github.io/cc-transcript/docs/guide/mining-feedback.html) — detectors, confidence, candidates, and verdicts.
+- [The transcript CLI](https://yasyf.github.io/cc-transcript/docs/guide/transcript-cli.html) — `list`/`show`/`grep`/`stats` end to end.
+- [API reference](https://yasyf.github.io/cc-transcript/reference/index.html) — the complete typed surface.
+
+## License
+
+[PolyForm Noncommercial 1.0.0](LICENSE).

{cc_transcript-5.0.0 → cc_transcript-7.0.0}/cc_transcript/extract/correct.py

@@ -25,7 +25,6 @@ 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:
@@ -138,10 +137,12 @@ def usable_backend() -> LlmBackend | None:
 async def choose_pair(
     pairs: Sequence[CandidatePair], *, feedback: str, anchor_turn: int, tier: TModel, backend: LlmBackend | None
 ) -> CandidatePair | None:
+    from spawnllm import extract
+
     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
+    pick = await extract(
+        build_pick_prompt(feedback, pairs, anchor_turn=anchor_turn), CorrectionPick, backend=backend, model=tier
     )
     return pairs[pick.candidate - 1] if pick.candidate is not None and 1 <= pick.candidate <= len(pairs) else None
 

{cc_transcript-5.0.0 → cc_transcript-7.0.0}/cc_transcript/filterspec.py

@@ -69,6 +69,12 @@ AGENT_INJECTION_GROUPS: tuple[tuple[str, str], ...] = (
 INTERRUPT_MARKER_GROUPS: tuple[tuple[str, str], ...] = (("interrupt", r"\[Request interrupted by user"),)
 STOP_HOOK_GROUPS: tuple[tuple[str, str], ...] = (("stop_hook", r"Stop hook feedback:"),)
 
+# Raw CC-injected protocol strings carried in tool-result content: the denial banner
+# and the markers that wrap the user's verbatim instruction in a rejected tool use.
+DENIAL_PREFIX = "The user doesn't want to proceed with this tool use. The tool use was rejected"
+USER_SAID_MARKER = "To tell you how to proceed, the user said:\n"
+USER_SAID_TRAILER = "Note: The user's next message"
+
 # Approve-and-advance directives: a user telling the agent to proceed/commit/push or
 # to resume killed work. They follow an assistant turn but advance it rather than
 # correcting it — the opposite of pushback — so a pushback consumer drops them. The
@@ -142,6 +148,11 @@ MILD_IMPATIENCE_GROUPS: tuple[tuple[str, str], ...] = (
     ),
 )
 
+# Hedging cues that soften a correction; a mining demote stage drops confidence on a hit.
+HEDGE_GROUPS: tuple[tuple[str, str], ...] = (
+    ("hedged", r"\b(?:maybe|perhaps|possibly|might|not sure|i think|i guess|if you (?:want|prefer)|up to you)\b"),
+)
+
 PORTABLE_GROUP_NAMES: frozenset[str] = frozenset(
     name
     for name, _ in (
@@ -152,6 +163,7 @@ PORTABLE_GROUP_NAMES: frozenset[str] = frozenset(
         *COMMAND_ECHO_GROUPS,
         *FRUSTRATION_GROUPS,
         *MILD_IMPATIENCE_GROUPS,
+        *HEDGE_GROUPS,
     )
 )
 

{cc_transcript-5.0.0 → cc_transcript-7.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, run_structured_on, structured_judge
+from cc_transcript.judge.llm import default_backend, resolved_model, structured_judge
 from cc_transcript.judge.verdicts import (
     AuditEstimate,
     AuditSample,

cc_transcript-7.0.0/cc_transcript/judge/llm.py

@@ -0,0 +1,62 @@
+"""Headless structured completions via spawnllm's first ready CLI backend.
+
+The structured call comes from the shared ``spawnllm`` library;
+:func:`spawnllm.extract` resolves a backend, runs the spawn, and validates the
+response into the model. 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
+
+from functools import cache
+from typing import TYPE_CHECKING
+
+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]
+
+
+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`.
+
+    Each call runs one structured completion on the cached default backend via
+    :func:`spawnllm.extract`, which validates the response into ``response_model``.
+
+    Example:
+        >>> judge = structured_judge(Verdict, tier="medium")
+        >>> await run_verdicts(rows, prompt_for, judge, persist, concurrency=8)
+    """
+    from spawnllm import extract
+
+    return lambda prompt: extract(prompt, response_model, backend=default_backend(), model=tier, timeout=timeout)

{cc_transcript-5.0.0 → cc_transcript-7.0.0}/cc_transcript/mining/__init__.py

@@ -2,8 +2,9 @@
 # pyright: reportUnusedImport=false
 """The correction/feedback mining mechanism.
 
-Neutral fact-detectors over Claude Code transcripts: each iterator recognizes a
-transcript shape and yields a :class:`MiningSignal` — a neutral fact carrying a
+Neutral fact-detectors over Claude Code transcripts, driven by a declarative
+:class:`MiningSpec`: :func:`mine` interprets the spec and yields a
+:class:`MiningSignal` per recognized transcript shape — a neutral fact carrying a
 candidate trigger, confidence, and evidence, but no policy. Apps map signals to
 their own candidate records with policy injected (their filter spec, their
 disqualification rules, their review formats), capture each candidate's durable
@@ -11,6 +12,11 @@ disqualification rules, their review formats), capture each candidate's durable
 :func:`~cc_transcript.context.capture_window`, and persist them through
 :class:`FeedbackStore`. LLM verdict passes over the stored corpus live in
 :mod:`cc_transcript.judge`.
+
+The :class:`MiningSpec` is the mining analogue of :class:`~cc_transcript.FilterSpec`
+and :class:`~cc_transcript.sentiment.ScoreSpec`: a frozen-dataclass tree with a JSON
+contract (:func:`mining_spec_to_json`) that the Python reference executor here and,
+when :func:`mining_spec_is_portable` holds, the Rust backend both interpret.
 """
 
 from __future__ import annotations
@@ -30,6 +36,7 @@ from cc_transcript.mining.confidence import (
     strong,
     weak,
 )
+from cc_transcript.mining.engine import mine_signals, rehydrate_signal, rust_mine_backend
 from cc_transcript.mining.filterspec import (
     CandidateClause,
     CandidateFilterSpec,
@@ -46,40 +53,15 @@ from cc_transcript.mining.filterspec import (
 )
 from cc_transcript.mining.formats import (
     ReviewComment,
-    ReviewFormat,
     StructuredFormat,
-    extract_all,
     extract_structured,
 )
 from cc_transcript.mining.signals import (
-    DEFAULT_DETECTORS,
     DENIAL_PREFIX,
-    EDIT_TOOLS,
-    REENTRY_LOOKBACK,
-    SUBAGENT_TOOLS,
     USER_SAID_MARKER,
     USER_SAID_TRAILER,
     MiningSignal,
-    Provenance,
-    ScanText,
-    classify_provenance,
-    correction_text,
-    denial_results,
-    denied_tool_payload,
-    embedded_user_text,
-    interrupt_marker,
-    is_bare_interrupt_marker,
-    iter_interrupt_marker_signals,
-    iter_plan_reentry_signals,
-    iter_plan_rejection_signals,
-    iter_review_comment_signals,
-    iter_tool_denial_signals,
-    iter_user_message_signals,
-    last_edit_index,
-    marker_in,
-    nearest_assistant_index,
-    next_user_message,
-    review_scan_texts,
+    mine,
 )
 from cc_transcript.mining.sourcekind import (
     INTERRUPT_REJECTION,
@@ -88,4 +70,28 @@ from cc_transcript.mining.sourcekind import (
     TRANSCRIPT_MESSAGE,
     SourceKind,
 )
+from cc_transcript.mining.spec import (
+    CALIBRATED_SPEC,
+    HEDGE_GROUPS,
+    USER_MESSAGE_SPEC,
+    Base,
+    BumpIfProximate,
+    BumpIfSubstantive,
+    CallableReviewFormat,
+    ConfidenceSpec,
+    ConfStage,
+    DemoteIfHedged,
+    DemoteIfShort,
+    DetectorName,
+    MiningSpec,
+    NoiseIfStructural,
+    Provenance,
+    ProvenanceSpec,
+    RegexReviewFormat,
+    ReviewFormat,
+    ReviewSpec,
+    mining_spec_is_portable,
+    mining_spec_to_json,
+    signal_to_dict,
+)
 from cc_transcript.mining.store import FEEDBACK_DDL, FeedbackStore, Stats, event_row

cc_transcript-7.0.0/cc_transcript/mining/engine.py

@@ -0,0 +1,91 @@
+"""Dual-backend mining entry — the mining analogue of
+:func:`~cc_transcript.sentiment.engine.rust_score_backend`.
+
+:func:`rust_mine_backend` resolves the Rust executor when the extension is built and
+the :class:`~cc_transcript.mining.spec.MiningSpec` is portable, else None to fall
+back to the Python reference. :func:`mine_signals` is the public dual-backend entry:
+it takes RAW transcript bytes plus a spec and returns
+:class:`~cc_transcript.mining.signals.MiningSignal` objects, routing to the Rust
+parse+detect fast path or the Python :func:`~cc_transcript.mining.signals.mine` over
+parsed events. The Rust path rehydrates the returned dicts into ``MiningSignal``
+objects byte-identical to the Python path.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from cc_transcript.mining.confidence import CandidateSignal, Confidence
+from cc_transcript.mining.signals import MiningSignal, mine
+from cc_transcript.mining.sourcekind import SourceKind
+from cc_transcript.mining.spec import mining_spec_is_portable, mining_spec_to_json
+from cc_transcript.models import CcVersion, EventUuid, SessionId
+from cc_transcript.parser import parse_events_from_bytes
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Mapping
+    from types import ModuleType
+
+    from cc_transcript.mining.spec import MiningSpec
+
+
+def rust_mine_backend(spec: MiningSpec) -> ModuleType | None:
+    """The Rust mining executor when built and the spec is portable; else None → Python."""
+    if os.environ.get("CC_TRANSCRIPT_DISABLE_RUST"):
+        return None
+    try:
+        from cc_transcript import _parser_rs
+    except ImportError:
+        return None
+    if not hasattr(_parser_rs, "mine_signals") or not mining_spec_is_portable(spec):
+        return None
+    return _parser_rs
+
+
+def mine_signals(raw: bytes, spec: MiningSpec) -> Iterator[MiningSignal]:
+    """Mines every :class:`MiningSignal` from raw transcript bytes via the active backend.
+
+    The Rust backend parses and detects over ``raw`` in one pass when the extension is
+    built and ``spec`` is portable; otherwise the bytes are parsed to events in Python
+    and the reference :func:`~cc_transcript.mining.signals.mine` runs. Both paths yield
+    byte-identical ``MiningSignal`` objects.
+
+    Args:
+        raw: The raw bytes of a ``.jsonl`` transcript.
+        spec: The mining policy: which detectors run, with which scoring, provenance,
+            and review-format policy.
+
+    Yields:
+        Neutral mined facts, one per recognized transcript shape, in detector order.
+    """
+    rust = rust_mine_backend(spec)
+    if rust is None:
+        yield from mine(parse_events_from_bytes(raw), spec)
+        return
+    yield from (rehydrate_signal(payload) for payload in rust.mine_signals(raw, mining_spec_to_json(spec)))
+
+
+def rehydrate_signal(payload: Mapping[str, Any]) -> MiningSignal:
+    """Rebuilds a :class:`MiningSignal` from a Rust ``mine_signals`` dict.
+
+    ``occurred_at`` is parsed back from its RFC3339 string and the branded primitives
+    are re-wrapped, producing an object byte-identical to the Python reference path.
+    """
+    return MiningSignal(
+        kind=SourceKind(payload["kind"]),
+        detector=payload["detector"],
+        session_id=SessionId(payload["session_id"]),
+        event_index=payload["event_index"],
+        event_uuid=EventUuid(payload["event_uuid"]),
+        occurred_at=datetime.fromisoformat(payload["occurred_at"]),
+        text=payload["text"],
+        cc_version=None if (version := payload["cc_version"]) is None else CcVersion(version),
+        trigger_index=payload["trigger_index"],
+        signal=CandidateSignal(
+            Confidence((signal := payload["signal"])["confidence"]), tuple(signal["reasons"]), signal["durable"]
+        ),
+        lower_bound=payload["lower_bound"],
+        evidence=payload["evidence"],
+    )

{cc_transcript-5.0.0 → cc_transcript-7.0.0}/cc_transcript/mining/formats.py

@@ -1,18 +1,21 @@
 """Generic infrastructure for parsing structured code-review messages.
 
-The concrete review formats are app policy; an app injects its own
-:class:`ReviewFormat` sequence into :func:`extract_all`.
+The concrete review formats are app policy; an app declares its formats as
+:class:`~cc_transcript.mining.spec.RegexReviewFormat`,
+:class:`~cc_transcript.mining.spec.CallableReviewFormat`, and
+:class:`StructuredFormat` on a :class:`~cc_transcript.mining.spec.ReviewSpec`, which
+:func:`~cc_transcript.mining.mine` interprets.
 """
 
 from __future__ import annotations
 
-import json
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
+import orjson
+
 if TYPE_CHECKING:
-    import re
-    from collections.abc import Callable, Iterator, Mapping, Sequence
+    from collections.abc import Iterator, Mapping, Sequence
     from typing import Any
 
 FINDING_KEYS: tuple[str, ...] = ("findings", "bugs", "improvements", "issues", "items", "verdicts")
@@ -35,39 +38,6 @@ class ReviewComment:
     comment: str
 
 
-@dataclass(frozen=True, slots=True)
-class ReviewFormat:
-    """A named code-review text format with a detector and extractor.
-
-    Attributes:
-        name: The format's identifier.
-        pattern: A pattern that matches when the format is present in a text.
-        extract: Parses a matching text into its review comments.
-    """
-
-    name: str
-    pattern: re.Pattern[str]
-    extract: Callable[[str], tuple[ReviewComment, ...]]
-
-
-def extract_all(text: str, formats: Sequence[ReviewFormat]) -> Iterator[tuple[ReviewFormat, ReviewComment]]:
-    """Yields every ``(format, comment)`` extracted by any matching format.
-
-    Args:
-        text: The raw review message text.
-        formats: The review formats to try, in order.
-
-    Yields:
-        One pair per extracted comment, across all formats whose pattern matches.
-    """
-    return (
-        (fmt, comment)
-        for fmt in formats
-        if fmt.pattern.search(text)
-        for comment in fmt.extract(text)
-    )
-
-
 @dataclass(frozen=True, slots=True)
 class StructuredFormat:
     """A named JSON code-review format keyed by caller-supplied field aliases.
@@ -166,7 +136,7 @@ def extract_structured(
         One pair per finding, across all formats. Non-JSON text yields nothing.
     """
     try:
-        payload = json.loads(text)
+        payload = orjson.loads(text)
     except (ValueError, TypeError):
         return
     yield from ((fmt, comment) for fmt in structured_formats for comment in fmt.extract(payload))