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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-transcript
-Version: 0.7.1
+Version: 0.8.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -14,10 +14,12 @@ Requires-Dist: pytest>=8.0 ; extra == 'dev'
 Requires-Dist: ty>=0.0.44 ; extra == 'dev'
 Requires-Dist: ruff>=0.8 ; extra == 'dev'
 Requires-Dist: cc-transcript[sentiment] ; extra == 'lexicon'
+Requires-Dist: spawnllm>=0.1.3 ; extra == 'llm'
 Requires-Dist: spacy>=3.8 ; extra == 'sentiment'
 Requires-Dist: afinn>=0.1 ; extra == 'sentiment'
 Provides-Extra: dev
 Provides-Extra: lexicon
+Provides-Extra: llm
 Provides-Extra: sentiment
 License-File: LICENSE
 Summary: Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking.
@@ -34,6 +36,8 @@ 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.png)
+
 [![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/)

{cc_transcript-0.7.1 → cc_transcript-0.8.0}/README.md

@@ -1,5 +1,7 @@
 # cc-transcript
 
+![cc-transcript banner](https://github.com/yasyf/cc-transcript/raw/main/docs/assets/readme-banner.png)
+
 [![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/)

{cc_transcript-0.7.1 → cc_transcript-0.8.0}/cc_transcript/domains/mining/__init__.py

@@ -30,14 +30,33 @@ from cc_transcript.domains.mining.confidence import (
 )
 from cc_transcript.domains.mining.context import (
     TOOL_INPUT_LIMIT,
+    TURN_TEXT_LIMIT,
     ContextSnapshot,
     ContextTurn,
     build_snapshot,
+    clip,
+    render_turn,
+    render_turns,
     summarize_tool_input,
     trigger_for,
     turn_for,
 )
+from cc_transcript.domains.mining.filterspec import (
+    CandidateClause,
+    CandidateFilterSpec,
+    CandidatePredicate,
+    ConfidenceAtLeast,
+    HasReason,
+    IsDurable,
+    SourceKindIn,
+    apply_candidate_filter,
+    at_least,
+    build_candidate_filter,
+    keep_candidate,
+    only_kinds,
+)
 from cc_transcript.domains.mining.formats import ReviewComment, ReviewFormat, extract_all
+from cc_transcript.domains.mining.llm import resolved_model, run_structured, structured_judge
 from cc_transcript.domains.mining.markers import (
     DENIAL_PREFIX,
     EDIT_TOOLS,
@@ -77,3 +96,21 @@ from cc_transcript.domains.mining.sourcekind import (
     SourceKind,
 )
 from cc_transcript.domains.mining.store import FEEDBACK_DDL, FeedbackStore, Stats, event_row
+from cc_transcript.domains.mining.verdicts import (
+    AuditEstimate,
+    AuditSample,
+    Disagreement,
+    Flip,
+    FlipReport,
+    GoldenFailure,
+    GoldenResult,
+    GoldenRow,
+    Metrics,
+    VerdictLike,
+    VerdictStoreMixin,
+    exact_upper_bound,
+    flip_pairs,
+    golden_result,
+    run_verdicts,
+    sample_audit,
+)

{cc_transcript-0.7.1 → cc_transcript-0.8.0}/cc_transcript/domains/mining/context.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass
+from itertools import zip_longest
 from typing import TYPE_CHECKING, Literal
 
 from cc_transcript.models import AssistantEvent, ToolUseBlock, UserEvent
@@ -16,6 +17,7 @@ if TYPE_CHECKING:
 
 ASSISTANT_TEXT_LIMIT = 2000
 TOOL_INPUT_LIMIT = 1500
+TURN_TEXT_LIMIT = 700
 
 
 @dataclass(frozen=True, slots=True)
@@ -121,6 +123,33 @@ def summarize_tool_input(name: str, input: Mapping[str, Any]) -> str:
     return summary[:TOOL_INPUT_LIMIT]
 
 
+def clip(text: str, limit: int) -> str:
+    """Truncates ``text`` to ``limit`` characters, marking any cut with an ellipsis."""
+    return text if len(text) <= limit else text[:limit].rstrip() + "…"
+
+
+def render_turn(turn: ContextTurn, limit: int = TURN_TEXT_LIMIT) -> str:
+    """Renders one turn as ``role: text`` plus one indented line per tool call.
+
+    Args:
+        turn: The turn to render.
+        limit: The character budget for the turn text and each tool input.
+
+    Returns:
+        The prompt-ready rendering, tool inputs included.
+    """
+    tools = "".join(
+        f"\n  {name}({clip(input, limit)})" if input else f"\n  {name}()"
+        for name, input in zip_longest(turn.tool_calls, turn.tool_inputs, fillvalue="")
+    )
+    return f"{turn.role}: {clip(turn.text, limit)}{tools}"
+
+
+def render_turns(turns: Sequence[ContextTurn]) -> str:
+    """Renders a window of turns, one per line, or ``(none)`` when empty."""
+    return "\n".join(render_turn(turn) for turn in turns) or "(none)"
+
+
 def turn_for(event: UserEvent | AssistantEvent) -> ContextTurn:
     match event:
         case UserEvent():

cc_transcript-0.8.0/cc_transcript/domains/mining/filterspec.py

@@ -0,0 +1,128 @@
+"""Declarative filtering of mined feedback candidates.
+
+A :class:`CandidateFilterSpec` is an ordered tuple of :class:`CandidateClause`
+rules — the candidate-level companion to the event-level
+:class:`cc_transcript.filterspec.FilterSpec`. A candidate survives when every
+clause matches, after per-clause negation. The core ships no concrete spec and
+no thresholds; the consumer owns policy and composes its own spec from the
+builders here.
+
+Example:
+    >>> from cc_transcript.domains.mining import NOISE_FLOOR, REVIEW_COMMENT
+    >>> spec = build_candidate_filter(at_least(NOISE_FLOOR), only_kinds(REVIEW_COMMENT))
+    >>> kept = list(apply_candidate_filter(candidates, spec))
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from cc_transcript.domains.mining.confidence import effective_confidence
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+    from cc_transcript.domains.mining.candidates import FeedbackCandidate
+    from cc_transcript.domains.mining.confidence import Confidence
+    from cc_transcript.domains.mining.sourcekind import SourceKind
+
+
+@dataclass(frozen=True, slots=True)
+class ConfidenceAtLeast:
+    """Matches candidates whose effective confidence is at least ``floor``.
+
+    A candidate without a stored signal scores
+    :data:`~cc_transcript.domains.mining.confidence.MEDIUM` via
+    :func:`~cc_transcript.domains.mining.confidence.effective_confidence`, so
+    legacy rows pass any floor at or below it.
+    """
+
+    floor: Confidence
+
+
+@dataclass(frozen=True, slots=True)
+class SourceKindIn:
+    """Matches candidates whose ``source_kind`` is in ``kinds``."""
+
+    kinds: frozenset[SourceKind]
+
+
+@dataclass(frozen=True, slots=True)
+class HasReason:
+    """Matches candidates whose signal carries the reason code ``reason``."""
+
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class IsDurable:
+    """Matches candidates whose signal durability equals ``want``.
+
+    A candidate without a stored signal counts as durable, mirroring
+    :class:`~cc_transcript.domains.mining.confidence.CandidateSignal`'s default.
+    """
+
+    want: bool
+
+
+CandidatePredicate = ConfidenceAtLeast | SourceKindIn | HasReason | IsDurable
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateClause:
+    """One filter rule: the candidate must satisfy ``predicate``.
+
+    Attributes:
+        predicate: The condition tested against a candidate.
+        negate: Invert the predicate match.
+    """
+
+    predicate: CandidatePredicate
+    negate: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class CandidateFilterSpec:
+    """An ordered tuple of :class:`CandidateClause` rules, all of which must hold."""
+
+    clauses: tuple[CandidateClause, ...]
+
+
+def predicate_matches(predicate: CandidatePredicate, candidate: FeedbackCandidate) -> bool:
+    match predicate:
+        case ConfidenceAtLeast(floor):
+            return effective_confidence(candidate.signal) >= floor
+        case SourceKindIn(kinds):
+            return candidate.source_kind in kinds
+        case HasReason(reason):
+            return candidate.signal is not None and reason in candidate.signal.reasons
+        case IsDurable(want):
+            return (candidate.signal is None or candidate.signal.durable) is want
+
+
+def keep_candidate(candidate: FeedbackCandidate, spec: CandidateFilterSpec) -> bool:
+    """Returns whether ``candidate`` satisfies every clause of ``spec``."""
+    return all(predicate_matches(clause.predicate, candidate) is not clause.negate for clause in spec.clauses)
+
+
+def apply_candidate_filter(
+    candidates: Iterable[FeedbackCandidate], spec: CandidateFilterSpec
+) -> Iterator[FeedbackCandidate]:
+    """Yields the candidates that satisfy every clause of ``spec``."""
+    return (candidate for candidate in candidates if keep_candidate(candidate, spec))
+
+
+def at_least(floor: Confidence) -> CandidateClause:
+    """Returns a clause keeping candidates at or above ``floor`` confidence."""
+    return CandidateClause(ConfidenceAtLeast(floor))
+
+
+def only_kinds(*kinds: SourceKind) -> CandidateClause:
+    """Returns a clause keeping candidates whose ``source_kind`` is one of ``kinds``."""
+    return CandidateClause(SourceKindIn(frozenset(kinds)))
+
+
+def build_candidate_filter(*clauses: CandidateClause) -> CandidateFilterSpec:
+    """Composes ``clauses`` into a :class:`CandidateFilterSpec`."""
+    return CandidateFilterSpec(clauses=clauses)

cc_transcript-0.8.0/cc_transcript/domains/mining/llm.py

@@ -0,0 +1,91 @@
+"""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 mining domain 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)

{cc_transcript-0.7.1 → cc_transcript-0.8.0}/cc_transcript/domains/mining/signals.py

@@ -4,17 +4,25 @@ Each iterator recognizes one transcript shape and yields a :class:`MiningSignal`
 describing it. A signal is a neutral fact: it carries a candidate ``trigger_index``
 but never disqualifies on its absence, never applies a ``FilterSpec``, and never
 builds an app candidate. The app maps signals to its own records with policy injected.
+
+Every signal carries a calibrated :class:`CandidateSignal` spanning the full
+confidence band: arithmetic bumps and demotions over the anchors, with named
+reason codes (``trigger_proximate``, ``short_followup``, ``substantive``,
+``hedged``, ``embedded_text``, ``bare_marker``, ``structural_only``) so apps can
+filter on :func:`~cc_transcript.domains.mining.confidence.effective_confidence`
+and reasons instead of re-deriving them.
 """
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NamedTuple
 
 from cc_transcript import STRUCTURAL_NOISE_RE
 from cc_transcript.models import AssistantEvent, ModeEvent, UserEvent
 
-from cc_transcript.domains.mining.confidence import firm, weak
+from cc_transcript.domains.mining.confidence import CandidateSignal, Confidence, firm, noise, weak
 from cc_transcript.domains.mining.formats import extract_all
 from cc_transcript.domains.mining.nav import (
     denial_results,
@@ -40,10 +48,17 @@ if TYPE_CHECKING:
 
     from cc_transcript.models import CcVersion, EntryUuid, SessionId, TranscriptEvent
 
-    from cc_transcript.domains.mining.confidence import CandidateSignal
     from cc_transcript.domains.mining.formats import ReviewFormat
     from cc_transcript.domains.mining.sourcekind import SourceKind
 
+CONFIDENCE_STEP = 0.25
+SHORT_FOLLOWUP_MAX_WORDS = 2
+TIGHT_PROXIMITY = 2
+HEDGE_RE = re.compile(
+    r"\b(?:maybe|perhaps|possibly|might|not sure|i think|i guess|if you (?:want|prefer)|up to you)\b",
+    re.IGNORECASE,
+)
+
 
 @dataclass(frozen=True, slots=True)
 class MiningSignal:
@@ -79,6 +94,11 @@ class MiningSignal:
     signal: CandidateSignal | None = None
 
 
+class ScoredText(NamedTuple):
+    text: str
+    signal: CandidateSignal
+
+
 def nearest_assistant_index(events: Sequence[TranscriptEvent], index: int) -> int | None:
     return next((i for i in range(index - 1, -1, -1) if isinstance(events[i], AssistantEvent)), None)
 
@@ -92,6 +112,57 @@ def correction_text(events: Sequence[TranscriptEvent], index: int) -> str | None
     return None
 
 
+def first_followup(events: Sequence[TranscriptEvent], index: int) -> str | None:
+    while (found := next_user_message(events, index + 1)) is not None:
+        index, event = found
+        if not is_bare_interrupt_marker(event.text):
+            return event.text
+    return None
+
+
+def adjust(signal: CandidateSignal, delta: float, reason: str) -> CandidateSignal:
+    return CandidateSignal(
+        Confidence(min(1.0, max(0.0, signal.confidence + delta))), (*signal.reasons, reason), signal.durable
+    )
+
+
+def is_substantive(text: str) -> bool:
+    return len(text.split()) > SHORT_FOLLOWUP_MAX_WORDS and not STRUCTURAL_NOISE_RE.search(text)
+
+
+def is_proximate(index: int, trigger: int | None) -> bool:
+    return trigger is not None and index - trigger <= TIGHT_PROXIMITY
+
+
+def calibrated(text: str, *reasons: str) -> CandidateSignal:
+    base = firm(*reasons)
+    promoted = adjust(base, CONFIDENCE_STEP, "substantive") if is_substantive(text) else base
+    return adjust(promoted, -CONFIDENCE_STEP, "hedged") if HEDGE_RE.search(text) else promoted
+
+
+def score_user_message(text: str, index: int, trigger: int | None) -> CandidateSignal:
+    if STRUCTURAL_NOISE_RE.search(text):
+        return noise("structural_only")
+    base = firm("user_message")
+    short = len(text.split()) <= SHORT_FOLLOWUP_MAX_WORDS
+    demoted = adjust(base, -CONFIDENCE_STEP, "short_followup") if short else base
+    return adjust(demoted, CONFIDENCE_STEP, "trigger_proximate") if is_proximate(index, trigger) else demoted
+
+
+def marker_correction(events: Sequence[TranscriptEvent], index: int) -> ScoredText | None:
+    if (correction := correction_text(events, index)) is not None:
+        return ScoredText(correction, weak("bare_marker"))
+    if (followup := first_followup(events, index)) is not None:
+        return ScoredText(followup, noise("structural_only"))
+    return None
+
+
+def denial_correction(events: Sequence[TranscriptEvent], index: int, embedded: str | None) -> ScoredText | None:
+    if embedded:
+        return ScoredText(embedded, calibrated(embedded, "embedded_text"))
+    return marker_correction(events, index)
+
+
 def iter_user_message_signals(events: Sequence[TranscriptEvent]) -> Iterator[MiningSignal]:
     return (
         MiningSignal(
@@ -103,8 +174,8 @@ def iter_user_message_signals(events: Sequence[TranscriptEvent]) -> Iterator[Min
             occurred_at=event.meta.timestamp,
             text=event.text,
             cc_version=event.meta.cc_version,
-            trigger_index=nearest_assistant_index(events, index),
-            signal=firm("transcript_message"),
+            trigger_index=(trigger := nearest_assistant_index(events, index)),
+            signal=score_user_message(event.text, index, trigger),
         )
         for index, event in enumerate(events)
         if isinstance(event, UserEvent)
@@ -126,7 +197,7 @@ def iter_plan_rejection_signals(events: Sequence[TranscriptEvent]) -> Iterator[M
             text=text,
             cc_version=event.meta.cc_version,
             trigger_index=nearest_assistant_index(events, index),
-            signal=firm("exit_plan_rejection"),
+            signal=calibrated(text, "embedded_text"),
         )
         for index, event in enumerate(events)
         if isinstance(event, UserEvent)
@@ -161,7 +232,7 @@ def iter_plan_reentry_signals(events: Sequence[TranscriptEvent]) -> Iterator[Min
             cc_version=user_event.meta.cc_version,
             trigger_index=nearest_assistant_index(events, user_index),
             lower_bound=edit,
-            signal=firm("plan_reentry"),
+            signal=calibrated(user_event.text, "reentry_after_edit"),
         )
 
 
@@ -175,17 +246,17 @@ def iter_tool_denial_signals(events: Sequence[TranscriptEvent]) -> Iterator[Mini
             event_index=index,
             event_uuid=event.meta.uuid,
             occurred_at=event.meta.timestamp,
-            text=text,
+            text=scored.text,
             cc_version=event.meta.cc_version,
             trigger_index=nearest_assistant_index(events, index),
             evidence=denied_tool_payload(paired) if paired else {},
-            signal=firm("denial") if embedded else weak("bare_marker"),
+            signal=scored.signal,
         )
         for index, event in enumerate(events)
         if isinstance(event, UserEvent)
         for block in denial_results(event)
         if (paired := uses.get(block.tool_use_id)) is None or paired.name not in {"ExitPlanMode", "AskUserQuestion"}
-        if (text := (embedded := embedded_user_text(block.content)) or correction_text(events, index))
+        if (scored := denial_correction(events, index, embedded_user_text(block.content))) is not None
     )
 
 
@@ -198,15 +269,15 @@ def iter_interrupt_marker_signals(events: Sequence[TranscriptEvent]) -> Iterator
             event_index=index,
             event_uuid=event.meta.uuid,
             occurred_at=event.meta.timestamp,
-            text=correction,
+            text=scored.text,
             cc_version=event.meta.cc_version,
             trigger_index=nearest_assistant_index(events, index),
-            signal=weak("bare_marker"),
+            signal=scored.signal,
         )
         for index, event in enumerate(events)
         if isinstance(event, UserEvent)
         if marker_in(event) is not None
-        if (correction := correction_text(events, index)) is not None
+        if (scored := marker_correction(events, index)) is not None
     )
 
 
@@ -230,7 +301,7 @@ def iter_review_comment_signals(
                 "line_start": comment.line_start,
                 "line_end": comment.line_end,
             },
-            signal=firm("review_comment"),
+            signal=calibrated(comment.comment, "format_match"),
         )
         for index, event in enumerate(events)
         if isinstance(event, UserEvent)