cc-transcript 0.6.0__tar.gz → 0.7.1__tar.gz

{cc_transcript-0.6.0 → cc_transcript-0.7.1}/Cargo.lock

@@ -66,7 +66,7 @@ dependencies = [
 
 [[package]]
 name = "cc_transcript_parser"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "chrono",
  "crossbeam-channel",

{cc_transcript-0.6.0 → cc_transcript-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 0.6.0
+Version: 0.7.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -13,10 +13,12 @@ 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: spacy>=3.8 ; extra == 'lexicon'
-Requires-Dist: afinn>=0.1 ; extra == 'lexicon'
+Requires-Dist: cc-transcript[sentiment] ; extra == 'lexicon'
+Requires-Dist: spacy>=3.8 ; extra == 'sentiment'
+Requires-Dist: afinn>=0.1 ; extra == 'sentiment'
 Provides-Extra: dev
 Provides-Extra: lexicon
+Provides-Extra: sentiment
 License-File: LICENSE
 Summary: Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking.
 Keywords: 

{cc_transcript-0.6.0 → cc_transcript-0.7.1}/cc_transcript/__init__.py

@@ -38,6 +38,13 @@ from cc_transcript.filterspec import (
     keep,
     labels_for,
 )
+from cc_transcript.messages import (
+    AssistantMessage,
+    BaseMessage,
+    ToolCall,
+    TranscriptMessage,
+    UserMessage,
+)
 from cc_transcript.models import (
     AssistantEvent,
     CcVersion,
@@ -56,5 +63,5 @@ from cc_transcript.models import (
     TranscriptEvent,
     UserEvent,
 )
-from cc_transcript.parser import TranscriptParser, parse_events_async, parse_events_from_bytes
+from cc_transcript.parser import TranscriptParser, parse_event, parse_events_async, parse_events_from_bytes
 from cc_transcript.store import FileStateStore

cc_transcript-0.7.1/cc_transcript/domains/__init__.py

@@ -0,0 +1,9 @@
+"""Built-in domains layered on the cc-transcript core.
+
+Each domain builds on the core transcript model and depends only on core — never on
+another domain, and never the reverse. Heavy dependencies sit behind a per-domain
+extra. Today: :mod:`cc_transcript.domains.sentiment` (scoring) and
+:mod:`cc_transcript.domains.mining` (correction/feedback extraction).
+"""
+
+from __future__ import annotations

cc_transcript-0.7.1/cc_transcript/domains/mining/__init__.py

@@ -0,0 +1,79 @@
+# Re-exports establish the domain's public surface; pyright sees them as unused.
+# 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
+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), and persist them through
+:class:`FeedbackStore`.
+"""
+
+from __future__ import annotations
+
+from cc_transcript.domains.mining.candidates import DedupKey, FeedbackCandidate, dedup_key
+from cc_transcript.domains.mining.confidence import (
+    HIGH,
+    LOW,
+    MEDIUM,
+    NOISE_FLOOR,
+    NONE,
+    VERY_HIGH,
+    CandidateSignal,
+    Confidence,
+    effective_confidence,
+    firm,
+    noise,
+    strong,
+    weak,
+)
+from cc_transcript.domains.mining.context import (
+    TOOL_INPUT_LIMIT,
+    ContextSnapshot,
+    ContextTurn,
+    build_snapshot,
+    summarize_tool_input,
+    trigger_for,
+    turn_for,
+)
+from cc_transcript.domains.mining.formats import ReviewComment, ReviewFormat, extract_all
+from cc_transcript.domains.mining.markers import (
+    DENIAL_PREFIX,
+    EDIT_TOOLS,
+    INTERRUPT_MARKER_RE,
+    REENTRY_LOOKBACK,
+    USER_SAID_MARKER,
+    USER_SAID_TRAILER,
+)
+from cc_transcript.domains.mining.nav import (
+    denial_results,
+    denied_tool_payload,
+    embedded_user_text,
+    interrupt_marker,
+    is_bare_interrupt_marker,
+    last_edit_index,
+    marker_in,
+    next_user_message,
+    tool_uses,
+)
+from cc_transcript.domains.mining.signals import (
+    DEFAULT_DETECTORS,
+    MiningSignal,
+    correction_text,
+    iter_interrupt_marker_signals,
+    iter_plan_reentry_signals,
+    iter_plan_rejection_signals,
+    iter_review_comment_signals,
+    iter_tool_denial_signals,
+    iter_user_message_signals,
+    nearest_assistant_index,
+)
+from cc_transcript.domains.mining.sourcekind import (
+    INTERRUPT_REJECTION,
+    PLAN_REVIEW,
+    REVIEW_COMMENT,
+    TRANSCRIPT_MESSAGE,
+    SourceKind,
+)
+from cc_transcript.domains.mining.store import FEEDBACK_DDL, FeedbackStore, Stats, event_row

cc_transcript-0.7.1/cc_transcript/domains/mining/candidates.py

@@ -0,0 +1,70 @@
+"""The feedback candidate model and the dedup key that makes ingestion idempotent."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NewType
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from datetime import datetime
+    from pathlib import Path
+    from typing import Any
+
+    from cc_transcript.models import SessionId
+
+    from cc_transcript.domains.mining.confidence import CandidateSignal
+    from cc_transcript.domains.mining.context import ContextSnapshot
+    from cc_transcript.domains.mining.sourcekind import SourceKind
+
+DedupKey = NewType("DedupKey", str)
+"""A content-derived SHA-256 key that makes feedback ingestion idempotent."""
+
+
+@dataclass(frozen=True, slots=True)
+class FeedbackCandidate:
+    """A single piece of developer pushback extracted from a transcript.
+
+    Attributes:
+        dedup_key: The content-derived key that makes ingestion idempotent.
+        source_kind: Which detector produced the candidate.
+        occurred_at: When the feedback was given.
+        text: The verbatim pushback text.
+        context: The conversational window around the feedback.
+        session_id: The transcript session the feedback came from.
+        origin_path: The file the candidate was extracted from.
+        origin_uuid: The originating transcript entry's uuid.
+        cc_version: The Claude Code version recorded for the origin.
+        payload: Detector-specific metadata preserved verbatim.
+        signal: The de-noising confidence signal, when computed.
+    """
+
+    dedup_key: DedupKey
+    source_kind: SourceKind
+    occurred_at: datetime
+    text: str
+    context: ContextSnapshot
+    session_id: SessionId | None = None
+    origin_path: Path | None = None
+    origin_uuid: str | None = None
+    cc_version: str | None = None
+    payload: Mapping[str, Any] | None = None
+    signal: CandidateSignal | None = None
+
+
+def dedup_key(*parts: str) -> DedupKey:
+    """Returns the stable dedup key for ``parts``.
+
+    Detectors key on session, kind, and the feedback content (plus its code
+    location for review comments) rather than the transcript entry's uuid or the
+    absolute file path, so the same pushback recorded under two transcript entries
+    collapses to one row, and the database stays portable and idempotent across moves.
+
+    Args:
+        parts: The content fragments that uniquely identify a candidate.
+
+    Returns:
+        The SHA-256 hex digest of the parts joined by a null byte.
+    """
+    return DedupKey(hashlib.sha256("\x00".join(parts).encode()).hexdigest())

cc_transcript-0.7.1/cc_transcript/domains/mining/confidence.py

@@ -0,0 +1,74 @@
+"""The de-noising confidence primitive carried alongside mined feedback facts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NewType
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from typing import Any
+
+Confidence = NewType("Confidence", float)
+"""A de-noising score in the closed interval [0, 1]; higher is more trustworthy."""
+
+NONE = Confidence(0.0)
+LOW = Confidence(0.25)
+MEDIUM = Confidence(0.5)
+HIGH = Confidence(0.75)
+VERY_HIGH = Confidence(0.95)
+NOISE_FLOOR = LOW
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateSignal:
+    """A confidence verdict on a mined fact, with the reasons that produced it.
+
+    Attributes:
+        confidence: The de-noising score in [0, 1].
+        reasons: The short reason codes that justify the score.
+        durable: Whether the signal should persist across re-derivation.
+    """
+
+    confidence: Confidence
+    reasons: tuple[str, ...] = ()
+    durable: bool = True
+
+
+def strong(*reasons: str, durable: bool = True) -> CandidateSignal:
+    """Returns a :data:`HIGH`-confidence signal carrying ``reasons``."""
+    return CandidateSignal(HIGH, reasons, durable)
+
+
+def firm(*reasons: str, durable: bool = True) -> CandidateSignal:
+    """Returns a :data:`MEDIUM`-confidence signal carrying ``reasons``."""
+    return CandidateSignal(MEDIUM, reasons, durable)
+
+
+def weak(*reasons: str, durable: bool = True) -> CandidateSignal:
+    """Returns a :data:`LOW`-confidence signal carrying ``reasons``."""
+    return CandidateSignal(LOW, reasons, durable)
+
+
+def noise(*reasons: str, durable: bool = True) -> CandidateSignal:
+    """Returns a :data:`NONE`-confidence signal carrying ``reasons``."""
+    return CandidateSignal(NONE, reasons, durable)
+
+
+def effective_confidence(signal: CandidateSignal | None) -> Confidence:
+    """Returns ``signal``'s confidence, or :data:`MEDIUM` when no signal is set."""
+    return signal.confidence if signal else MEDIUM
+
+
+def to_payload(signal: CandidateSignal) -> dict[str, Any]:
+    return {"confidence": signal.confidence, "reasons": list(signal.reasons), "durable": signal.durable}
+
+
+def from_payload(data: Mapping[str, Any] | None) -> CandidateSignal | None:
+    if data is None:
+        return None
+    return CandidateSignal(
+        confidence=Confidence(data["confidence"]),
+        reasons=tuple(data["reasons"]),
+        durable=data["durable"],
+    )

cc_transcript-0.7.1/cc_transcript/domains/mining/context.py

@@ -0,0 +1,188 @@
+"""The conversational-window primitive captured around each piece of feedback."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from cc_transcript.models import AssistantEvent, ToolUseBlock, UserEvent
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from typing import Any
+
+    from cc_transcript.models import TranscriptEvent
+
+ASSISTANT_TEXT_LIMIT = 2000
+TOOL_INPUT_LIMIT = 1500
+
+
+@dataclass(frozen=True, slots=True)
+class ContextTurn:
+    """One conversational turn surrounding a piece of feedback.
+
+    Attributes:
+        role: Whether the turn came from the user, the assistant, or a tool.
+        text: The turn's text content.
+        tool_calls: The names of the tools the turn invoked, in order.
+        tool_inputs: One input summary per tool call, in the same order.
+    """
+
+    role: Literal["user", "assistant", "tool"]
+    text: str
+    tool_calls: tuple[str, ...] = ()
+    tool_inputs: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ContextSnapshot:
+    """The conversational window around a piece of feedback.
+
+    Attributes:
+        before: The turns leading up to the trigger.
+        trigger: The assistant action the feedback responds to, when known.
+        after: The turns following the trigger.
+    """
+
+    before: tuple[ContextTurn, ...]
+    trigger: ContextTurn | None
+    after: tuple[ContextTurn, ...]
+
+    def to_json(self) -> str:
+        """Serializes the snapshot to the JSON stored in ``context_json``."""
+        return json.dumps(
+            {
+                "before": [turn_to_dict(turn) for turn in self.before],
+                "trigger": turn_to_dict(self.trigger) if self.trigger else None,
+                "after": [turn_to_dict(turn) for turn in self.after],
+            }
+        )
+
+    @classmethod
+    def from_json(cls, raw: str) -> ContextSnapshot:
+        """Deserializes a snapshot from a ``context_json`` string."""
+        data = json.loads(raw)
+        return cls(
+            before=tuple(turn_from_dict(turn) for turn in data["before"]),
+            trigger=turn_from_dict(data["trigger"]) if data["trigger"] else None,
+            after=tuple(turn_from_dict(turn) for turn in data["after"]),
+        )
+
+
+def turn_to_dict(turn: ContextTurn) -> dict[str, Any]:
+    return {
+        "role": turn.role,
+        "text": turn.text,
+        "tool_calls": list(turn.tool_calls),
+        "tool_inputs": list(turn.tool_inputs),
+    }
+
+
+def turn_from_dict(data: Mapping[str, Any]) -> ContextTurn:
+    return ContextTurn(
+        role=data["role"],
+        text=data["text"],
+        tool_calls=tuple(data["tool_calls"]),
+        tool_inputs=tuple(data.get("tool_inputs", ())),
+    )
+
+
+def summarize_tool_input(name: str, input: Mapping[str, Any]) -> str:
+    """Summarizes one tool call's input for context snapshots.
+
+    Extracts the field that captures what the tool actually did — the Bash
+    command, the Edit diff, the plan body — falling back to the raw JSON for
+    unrecognized tools, truncated to :data:`TOOL_INPUT_LIMIT`.
+
+    Args:
+        name: The tool's name as recorded in the transcript.
+        input: The tool call's input mapping, preserved verbatim by the parser.
+
+    Returns:
+        The bounded one-string summary of the call.
+    """
+    match name:
+        case "Bash":
+            summary = str(input.get("command", ""))
+        case "Edit":
+            summary = f"{input.get('file_path', '')}\n- {input.get('old_string', '')}\n+ {input.get('new_string', '')}"
+        case "MultiEdit":
+            first: Mapping[str, Any] = next(iter(input.get("edits") or ()), {})
+            summary = f"{input.get('file_path', '')}\n- {first.get('old_string', '')}\n+ {first.get('new_string', '')}"
+        case "Write":
+            summary = f"{input.get('file_path', '')}\n{input.get('content', '')}"
+        case "ExitPlanMode":
+            summary = str(input.get("plan", ""))
+        case "Task" | "Agent":
+            summary = str(input.get("prompt", ""))
+        case _:
+            summary = json.dumps(dict(input))
+    return summary[:TOOL_INPUT_LIMIT]
+
+
+def turn_for(event: UserEvent | AssistantEvent) -> ContextTurn:
+    match event:
+        case UserEvent():
+            return ContextTurn(role="user", text=event.text)
+        case AssistantEvent():
+            uses = tuple(block for block in event.blocks if isinstance(block, ToolUseBlock))
+            return ContextTurn(
+                role="assistant",
+                text=event.text[:ASSISTANT_TEXT_LIMIT],
+                tool_calls=tuple(use.name for use in uses),
+                tool_inputs=tuple(summarize_tool_input(use.name, use.input) for use in uses),
+            )
+
+
+def trigger_for(events: Sequence[TranscriptEvent], index: int, lower: int) -> ContextTurn | None:
+    return next(
+        (
+            turn_for(event)
+            for i in range(index - 1, lower - 1, -1)
+            if isinstance(event := events[i], AssistantEvent)
+        ),
+        None,
+    )
+
+
+def build_snapshot(
+    events: Sequence[TranscriptEvent],
+    index: int,
+    *,
+    before: int = 6,
+    after: int = 2,
+    lower_bound: int | None = None,
+) -> ContextSnapshot:
+    """Builds the conversational window around the event at ``index``.
+
+    A turn is a :class:`UserEvent` or :class:`AssistantEvent`; system, mode, and
+    other events are skipped. The trigger is the nearest preceding assistant
+    turn — the action the feedback responds to.
+
+    Args:
+        events: The full ordered event stream for one transcript.
+        index: The index of the event the feedback was attached to.
+        before: The maximum number of turns to capture before the trigger.
+        after: The maximum number of turns to capture after the index.
+        lower_bound: When set, an event index the ``before`` window and trigger
+            search may not reach back past — used to anchor plan-review context
+            to the triggering edit cycle.
+
+    Returns:
+        The assembled :class:`ContextSnapshot`.
+    """
+    lower = lower_bound if lower_bound is not None else 0
+    return ContextSnapshot(
+        before=tuple(
+            turn_for(event)
+            for i in range(index - 1, lower - 1, -1)
+            if isinstance(event := events[i], UserEvent | AssistantEvent)
+        )[:before][::-1],
+        trigger=trigger_for(events, index, lower),
+        after=tuple(
+            turn_for(event)
+            for i in range(index + 1, len(events))
+            if isinstance(event := events[i], UserEvent | AssistantEvent)
+        )[:after],
+    )

cc_transcript-0.7.1/cc_transcript/domains/mining/formats.py

@@ -0,0 +1,64 @@
+"""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`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import re
+    from collections.abc import Callable, Iterator, Sequence
+
+
+@dataclass(frozen=True, slots=True)
+class ReviewComment:
+    """A single inline review comment parsed from a code-review message.
+
+    Attributes:
+        file: The file the comment targets, when cited.
+        line_start: The first line the comment targets, when cited.
+        line_end: The last line the comment targets, when a range is cited.
+        comment: The comment's text.
+    """
+
+    file: str | None
+    line_start: int | None
+    line_end: int | None
+    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)
+    )

cc_transcript-0.7.1/cc_transcript/domains/mining/markers.py

@@ -0,0 +1,11 @@
+"""Claude Code transcript marker constants the mining fact-detectors recognize."""
+
+from __future__ import annotations
+
+from cc_transcript import INTERRUPT_MARKER_RE as INTERRUPT_MARKER_RE
+
+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"
+EDIT_TOOLS = frozenset({"Edit", "Write", "MultiEdit", "NotebookEdit"})
+REENTRY_LOOKBACK = 40

cc_transcript-0.7.1/cc_transcript/domains/mining/nav.py

@@ -0,0 +1,100 @@
+"""Pure navigation helpers over a transcript's ordered events."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cc_transcript.models import AssistantEvent, ToolResultBlock, ToolUseBlock, UserEvent
+
+from cc_transcript.domains.mining.markers import (
+    DENIAL_PREFIX,
+    EDIT_TOOLS,
+    INTERRUPT_MARKER_RE,
+    REENTRY_LOOKBACK,
+    USER_SAID_MARKER,
+    USER_SAID_TRAILER,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+    from typing import Any
+
+    from cc_transcript.models import ToolUseId, TranscriptEvent
+
+
+def tool_uses(events: Sequence[TranscriptEvent]) -> dict[ToolUseId, ToolUseBlock]:
+    return {
+        block.id: block
+        for event in events
+        if isinstance(event, AssistantEvent)
+        for block in event.blocks
+        if isinstance(block, ToolUseBlock)
+    }
+
+
+def denial_results(event: UserEvent) -> Iterator[ToolResultBlock]:
+    return (
+        block
+        for block in event.blocks
+        if isinstance(block, ToolResultBlock)
+        if block.is_error
+        if block.content.startswith(DENIAL_PREFIX)
+    )
+
+
+def embedded_user_text(content: str) -> str | None:
+    if (start := content.find(USER_SAID_MARKER)) == -1:
+        return None
+    return content[start + len(USER_SAID_MARKER) :].split(USER_SAID_TRAILER, 1)[0].strip()
+
+
+def last_edit_index(events: Sequence[TranscriptEvent], index: int) -> int | None:
+    return next(
+        (
+            i
+            for i in range(index - 1, max(index - REENTRY_LOOKBACK, 0) - 1, -1)
+            if isinstance(event := events[i], AssistantEvent)
+            if any(isinstance(b, ToolUseBlock) and b.name in EDIT_TOOLS for b in event.blocks)
+        ),
+        None,
+    )
+
+
+def next_user_message(events: Sequence[TranscriptEvent], index: int) -> tuple[int, UserEvent] | None:
+    return next(
+        (
+            (i, event)
+            for i in range(index, len(events))
+            if isinstance(event := events[i], UserEvent)
+            if event.text.strip()
+        ),
+        None,
+    )
+
+
+def denied_tool_payload(use: ToolUseBlock) -> dict[str, Any]:
+    return {"tool": use.name, "file_path": use.input.get("file_path")}
+
+
+def interrupt_marker(content: str) -> str | None:
+    stripped = content.lstrip()
+    if (match := INTERRUPT_MARKER_RE.match(stripped)) is None:
+        return None
+    end = stripped.find("]")
+    return stripped[: end + 1] if end != -1 else match.group(0)
+
+
+def is_bare_interrupt_marker(text: str) -> bool:
+    return (marker := interrupt_marker(text)) is not None and not text.strip()[len(marker.strip()) :].strip()
+
+
+def marker_in(event: UserEvent) -> str | None:
+    return next(
+        (
+            marker
+            for block in event.blocks
+            if isinstance(block, ToolResultBlock)
+            if (marker := interrupt_marker(block.content)) is not None
+        ),
+        None,
+    )