codebase-receipts-cli 1.0.0__py3-none-any.whl

receipts/prep/dossier.py

@@ -0,0 +1,313 @@
+"""Defense dossier — the night-before-the-interview study document.
+
+Assembles everything the pipeline already knows into one file: per bullet,
+the verdict, the exact evidence files that back it, the questions an
+interviewer would most likely ask, a strong grounded model answer, and
+any weak spots from past mock-interview sessions. One LLM call per
+bullet; everything else is assembly.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from receipts.llm.json_utils import parse_json_loose
+from receipts.llm.provider import CompletionResult, LLMProvider
+from receipts.prep.readiness import WeakSpot
+from receipts.verify.verifier import VerificationResult
+
+_VERDICT_WEIGHT = {"unsupported": 3, "plausible": 2, "verified": 1}
+
+_DOSSIER_SYSTEM = """\
+You are an interview coach preparing a candidate to defend a resume
+bullet. Given the bullet, its code-verification results, and the actual
+code evidence, produce:
+
+1. "questions": the 2-3 questions an interviewer is MOST likely to ask
+   about this bullet. Pointed and specific — reference the technologies,
+   numbers, and decisions in the bullet, not generic "tell me about"
+   questions. If a claim was unsupported, at least one question must
+   probe exactly that weak spot, because a good interviewer will.
+2. "model_answers": one strong, honest answer (3-5 sentences) for EACH
+   question, in the SAME ORDER as "questions" — answers[0] answers
+   questions[0], and so on. Ground every answer ONLY in the bullet and the
+   provided evidence. Never invent numbers, files, or capabilities that
+   aren't in the evidence. Where evidence is thin, the answer should show
+   how to respond honestly without overclaiming.
+
+Respond in JSON:
+{"questions": ["q1", "q2", "q3"], "model_answers": ["a1", "a2", "a3"]}
+"""
+
+
+@dataclass(frozen=True)
+class EvidenceRef:
+    rel_path: str
+    name: str
+    start_line: int
+    end_line: int
+
+
+@dataclass(frozen=True)
+class DossierEntry:
+    bullet_text: str
+    section: str
+    heading: str
+    verdict: str  # worst verdict across the bullet's claims
+    claim_notes: list[str]  # "verdict — value: explanation" per claim
+    evidence: list[EvidenceRef]
+    questions: list[str]
+    model_answers: list[str]  # one grounded answer per question, aligned by index
+    weak_note: str = ""  # from past AMA sessions, when it exists
+    completion: CompletionResult | None = None
+
+
+def _group_by_bullet(
+    results: list[VerificationResult],
+) -> list[list[VerificationResult]]:
+    groups: list[list[VerificationResult]] = []
+    index: dict[str, list[VerificationResult]] = {}
+    for r in results:
+        key = r.claim.bullet_text
+        group = index.get(key)
+        if group is None:
+            group = []
+            index[key] = group
+            groups.append(group)
+        group.append(r)
+    return groups
+
+
+def _worst_verdict(group: list[VerificationResult]) -> str:
+    return max(
+        (r.verdict for r in group),
+        key=lambda v: _VERDICT_WEIGHT.get(v, 1),
+    )
+
+
+def _collect_evidence(group: list[VerificationResult]) -> list[EvidenceRef]:
+    seen: set[str] = set()
+    out: list[EvidenceRef] = []
+    for r in group:
+        for e in r.evidence:
+            key = f"{e.rel_path}:{e.name}"
+            if key in seen:
+                continue
+            seen.add(key)
+            out.append(
+                EvidenceRef(
+                    rel_path=e.rel_path,
+                    name=e.name,
+                    start_line=e.start_line,
+                    end_line=e.end_line,
+                )
+            )
+    return out[:6]
+
+
+def _build_prompt(group: list[VerificationResult]) -> str:
+    first = group[0]
+    parts = [
+        f"BULLET: {first.claim.bullet_text}",
+        f"SECTION: {first.claim.section}",
+        "",
+        "VERIFICATION RESULTS:",
+    ]
+    for r in group:
+        parts.append(
+            f'  - {r.claim.claim_type} "{r.claim.value}": {r.verdict}'
+            f" — {r.explanation}"
+        )
+    evidence = _collect_evidence(group)
+    if evidence:
+        parts.append("")
+        parts.append("CODE EVIDENCE:")
+        seen_code: set[str] = set()
+        for r in group:
+            for e in r.evidence:
+                key = f"{e.rel_path}:{e.name}"
+                if key in seen_code:
+                    continue
+                seen_code.add(key)
+                parts.append(f"--- {e.rel_path} :: {e.name} ---")
+                parts.append(e.code[:1500])
+                if len(seen_code) >= 4:
+                    break
+            if len(seen_code) >= 4:
+                break
+    return "\n".join(parts)
+
+
+def build_dossier_entry(
+    group: list[VerificationResult],
+    provider: LLMProvider,
+    *,
+    weak_spots: dict[str, WeakSpot] | None = None,
+) -> DossierEntry:
+    """Build one dossier entry from a bullet's verification results."""
+    first = group[0]
+    completion = provider.complete(
+        _DOSSIER_SYSTEM, _build_prompt(group), json_mode=True
+    )
+
+    questions: list[str] = []
+    model_answers: list[str] = []
+    try:
+        parsed = parse_json_loose(completion.text)
+        raw_questions = parsed.get("questions", [])
+        if isinstance(raw_questions, list):
+            questions = [str(q) for q in raw_questions if str(q).strip()][:3]
+        raw_answers = parsed.get("model_answers", [])
+        if isinstance(raw_answers, list):
+            model_answers = [str(a) for a in raw_answers]
+        elif parsed.get("model_answer"):
+            # Back-compat: a model that still returns a single answer.
+            model_answers = [str(parsed.get("model_answer", ""))]
+    except (ValueError, json.JSONDecodeError, AttributeError):
+        pass
+
+    # Align answers to questions: pad short, trim long.
+    if len(model_answers) < len(questions):
+        model_answers += [""] * (len(questions) - len(model_answers))
+    else:
+        model_answers = model_answers[: len(questions)]
+
+    weak_note = ""
+    if weak_spots:
+        spot = weak_spots.get(first.claim.bullet_text)
+        if spot:
+            weak_note = (
+                f"You previously failed a mock question on this bullet"
+                f' ("{spot.question[:100]}"): {spot.assessment}'
+            )
+
+    claim_notes = [
+        f'{r.verdict} — {r.claim.claim_type} "{r.claim.value}": {r.explanation}'
+        for r in group
+    ]
+
+    return DossierEntry(
+        bullet_text=first.claim.bullet_text,
+        section=first.claim.section,
+        heading=first.claim.entry_heading,
+        verdict=_worst_verdict(group),
+        claim_notes=claim_notes,
+        evidence=_collect_evidence(group),
+        questions=questions,
+        model_answers=model_answers,
+        weak_note=weak_note,
+        completion=completion,
+    )
+
+
+def build_dossier(
+    results: list[VerificationResult],
+    provider: LLMProvider,
+    *,
+    weak_spots: list[WeakSpot] | None = None,
+    on_progress=None,
+) -> list[DossierEntry]:
+    """Build dossier entries for every bullet (one LLM call each)."""
+    spots_by_bullet: dict[str, WeakSpot] = {}
+    for spot in weak_spots or []:
+        # keep the most recent spot per bullet (list arrives newest-first)
+        spots_by_bullet.setdefault(spot.bullet_text, spot)
+
+    groups = _group_by_bullet(results)
+    entries: list[DossierEntry] = []
+    for i, group in enumerate(groups, 1):
+        entries.append(build_dossier_entry(group, provider, weak_spots=spots_by_bullet))
+        if on_progress is not None:
+            on_progress(i, len(groups))
+    return entries
+
+
+_VERDICT_BADGE = {
+    "verified": "VERIFIED",
+    "plausible": "PLAUSIBLE",
+    "unsupported": "UNSUPPORTED",
+}
+
+
+def render_markdown(
+    entries: list[DossierEntry],
+    *,
+    resume_name: str,
+    source_name: str,
+    generated: str,
+) -> str:
+    """Render dossier entries as a study-ready markdown document."""
+    verified = sum(1 for e in entries if e.verdict == "verified")
+    plausible = sum(1 for e in entries if e.verdict == "plausible")
+    unsupported = sum(1 for e in entries if e.verdict == "unsupported")
+
+    lines = [
+        f"# Interview Defense Dossier — {resume_name}",
+        "",
+        f"*Generated {generated} · Codebase: `{source_name}` ·"
+        f" {verified} verified / {plausible} plausible /"
+        f" {unsupported} unsupported bullets*",
+        "",
+        "> Study order: unsupported bullets first — those are the ones a"
+        " good interviewer will find.",
+        "",
+    ]
+
+    by_section: dict[str, list[DossierEntry]] = {}
+    for e in entries:
+        by_section.setdefault(e.section, []).append(e)
+
+    for section, section_entries in by_section.items():
+        lines.append(f"## {section}")
+        lines.append("")
+
+        # Weakest first within each section — that's the study order.
+        section_entries = sorted(
+            section_entries,
+            key=lambda e: -_VERDICT_WEIGHT.get(e.verdict, 1),
+        )
+
+        for e in section_entries:
+            badge = _VERDICT_BADGE.get(e.verdict, e.verdict.upper())
+            lines.append(f"### [{badge}] {e.bullet_text}")
+            lines.append("")
+            if e.heading:
+                lines.append(f"*Entry: {e.heading}*")
+                lines.append("")
+
+            if e.claim_notes:
+                lines.append("**Claim-by-claim:**")
+                for note in e.claim_notes:
+                    lines.append(f"- {note}")
+                lines.append("")
+
+            if e.evidence:
+                lines.append("**Evidence in your code:**")
+                for ev in e.evidence:
+                    loc = (
+                        f" (lines {ev.start_line}–{ev.end_line})" if ev.end_line else ""
+                    )
+                    lines.append(f"- `{ev.rel_path}` :: `{ev.name}`{loc}")
+                lines.append("")
+
+            if e.questions:
+                lines.append("**Questions to expect:**")
+                for i, q in enumerate(e.questions, 1):
+                    lines.append(f"{i}. {q}")
+                    answer = (
+                        e.model_answers[i - 1] if i - 1 < len(e.model_answers) else ""
+                    )
+                    if answer:
+                        lines.append("")
+                        lines.append(f"   > {answer}")
+                    lines.append("")
+
+            if e.weak_note:
+                lines.append(f"**⚠ Drill this:** {e.weak_note}")
+                lines.append("")
+
+            lines.append("---")
+            lines.append("")
+
+    return "\n".join(lines)

receipts/prep/readiness.py

@@ -0,0 +1,227 @@
+"""AMA session persistence and readiness tracking.
+
+Every mock-interview session's rounds are saved to a local SQLite file
+(next to the token ledger, under ``~/.receipts/``). Across sessions this
+answers the questions a student actually has the week before placements:
+am I improving, and which section should I drill next?
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from receipts.ama.interviewer import InterviewRound
+
+_DEFAULT_DB_PATH = Path.home() / ".receipts" / "readiness.db"
+
+_CREATE_SESSIONS = """\
+CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    timestamp REAL NOT NULL,
+    resume_name TEXT NOT NULL,
+    source TEXT NOT NULL DEFAULT ''
+)"""
+
+_CREATE_ROUNDS = """\
+CREATE TABLE IF NOT EXISTS rounds (
+    id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    section TEXT NOT NULL,
+    heading TEXT NOT NULL,
+    bullet_text TEXT NOT NULL,
+    verdict TEXT NOT NULL,
+    question TEXT NOT NULL,
+    answer TEXT NOT NULL,
+    follow_up TEXT NOT NULL,
+    follow_up_answer TEXT NOT NULL,
+    held_up INTEGER NOT NULL,
+    assessment TEXT NOT NULL,
+    model_answer TEXT NOT NULL DEFAULT ''
+)"""
+
+_CREATE_INDEX = """\
+CREATE INDEX IF NOT EXISTS idx_rounds_session ON rounds (session_id)"""
+
+
+@dataclass(frozen=True)
+class SectionStat:
+    section: str
+    held: int
+    total: int
+
+    @property
+    def ratio(self) -> float:
+        return self.held / self.total if self.total else 0.0
+
+
+@dataclass(frozen=True)
+class SessionRecord:
+    session_id: str
+    timestamp: float
+    resume_name: str
+    source: str
+    total_rounds: int
+    held_rounds: int
+    sections: list[SectionStat] = field(default_factory=list)
+
+    @property
+    def ratio(self) -> float:
+        return self.held_rounds / self.total_rounds if self.total_rounds else 0.0
+
+
+@dataclass(frozen=True)
+class WeakSpot:
+    bullet_text: str
+    section: str
+    question: str
+    assessment: str
+    timestamp: float
+    model_answer: str = ""
+
+
+class ReadinessStore:
+    """SQLite-backed store of mock-interview sessions."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self.db_path = db_path or _DEFAULT_DB_PATH
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(self.db_path))
+        self._conn.execute(_CREATE_SESSIONS)
+        self._conn.execute(_CREATE_ROUNDS)
+        self._conn.execute(_CREATE_INDEX)
+        self._migrate()
+        self._conn.commit()
+
+    def _migrate(self) -> None:
+        """Additive migrations for DBs created by an older version.
+
+        New columns are added with a default so existing rows stay valid and
+        older code that never wrote them keeps working.
+        """
+        cols = {row[1] for row in self._conn.execute("PRAGMA table_info(rounds)")}
+        if "model_answer" not in cols:
+            self._conn.execute(
+                "ALTER TABLE rounds ADD COLUMN model_answer TEXT NOT NULL DEFAULT ''"
+            )
+
+    def save_session(
+        self,
+        rounds: list[InterviewRound],
+        *,
+        resume_name: str,
+        source: str = "",
+    ) -> str:
+        """Persist one AMA session. Returns the session id."""
+        session_id = uuid.uuid4().hex[:12]
+        self._conn.execute(
+            "INSERT INTO sessions (id, timestamp, resume_name, source)"
+            " VALUES (?, ?, ?, ?)",
+            (session_id, time.time(), resume_name, source),
+        )
+        for r in rounds:
+            self._conn.execute(
+                "INSERT INTO rounds (id, session_id, section, heading,"
+                " bullet_text, verdict, question, answer, follow_up,"
+                " follow_up_answer, held_up, assessment, model_answer)"
+                " VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    uuid.uuid4().hex[:16],
+                    session_id,
+                    r.section,
+                    r.heading,
+                    r.bullet_text,
+                    r.verdict,
+                    r.question,
+                    r.answer,
+                    r.follow_up,
+                    r.follow_up_answer,
+                    int(r.held_up),
+                    r.assessment,
+                    getattr(r, "model_answer", ""),
+                ),
+            )
+        self._conn.commit()
+        return session_id
+
+    def sessions(self, *, resume_name: str | None = None) -> list[SessionRecord]:
+        """All sessions, oldest first, with per-section held-up stats."""
+        query = "SELECT id, timestamp, resume_name, source FROM sessions"
+        params: tuple = ()
+        if resume_name is not None:
+            query += " WHERE resume_name = ?"
+            params = (resume_name,)
+        query += " ORDER BY timestamp"
+
+        records: list[SessionRecord] = []
+        for sid, ts, rname, source in self._conn.execute(query, params):
+            rows = self._conn.execute(
+                "SELECT section, SUM(held_up), COUNT(*) FROM rounds"
+                " WHERE session_id = ? GROUP BY section",
+                (sid,),
+            ).fetchall()
+            sections = [
+                SectionStat(section=sec, held=int(held or 0), total=int(total))
+                for sec, held, total in rows
+            ]
+            total = sum(s.total for s in sections)
+            held = sum(s.held for s in sections)
+            records.append(
+                SessionRecord(
+                    session_id=sid,
+                    timestamp=ts,
+                    resume_name=rname,
+                    source=source,
+                    total_rounds=total,
+                    held_rounds=held,
+                    sections=sections,
+                )
+            )
+        return records
+
+    def weakest_section(self) -> SectionStat | None:
+        """The section with the lowest held-up ratio in the latest session."""
+        latest = self.sessions()
+        if not latest:
+            return None
+        sections = latest[-1].sections
+        if not sections:
+            return None
+        return min(sections, key=lambda s: s.ratio)
+
+    def weak_spots(self, limit: int = 20) -> list[WeakSpot]:
+        """Recent rounds that did NOT hold up — the drill list."""
+        rows = self._conn.execute(
+            "SELECT r.bullet_text, r.section, r.question, r.assessment,"
+            " s.timestamp, r.model_answer"
+            " FROM rounds r JOIN sessions s ON r.session_id = s.id"
+            " WHERE r.held_up = 0"
+            " ORDER BY s.timestamp DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        return [
+            WeakSpot(
+                bullet_text=b,
+                section=sec,
+                question=q,
+                assessment=a,
+                timestamp=ts,
+                model_answer=ma or "",
+            )
+            for b, sec, q, a, ts, ma in rows
+        ]
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+def readiness_delta(
+    sessions: list[SessionRecord],
+) -> tuple[float, float] | None:
+    """(latest_ratio, previous_ratio) for trend display, or None if <2."""
+    if len(sessions) < 2:
+        return None
+    return sessions[-1].ratio, sessions[-2].ratio