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

receipts/ama/interviewer.py

@@ -0,0 +1,415 @@
+"""Mock-interview loop weighted toward weak resume bullets.
+
+The interviewer picks bullets to quiz on — Unsupported and Plausible
+bullets get asked about more often than Verified ones. For each bullet
+it generates a technical question, listens to the user's answer, asks a
+natural follow-up, then moves on. At the end it prints a summary of
+what held up and what didn't.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+from dataclasses import dataclass, field
+
+from receipts.llm.json_utils import parse_json_loose
+from receipts.llm.provider import CompletionResult, LLMProvider
+from receipts.verify.verifier import VerificationResult
+
+_VERDICT_WEIGHT = {
+    "unsupported": 3,
+    "plausible": 2,
+    "verified": 1,
+}
+
+_QUESTION_SYSTEM = """\
+You are a technical interviewer. Given a resume bullet and its \
+verification status, ask ONE pointed technical question that tests \
+whether the candidate truly did what the bullet claims.
+
+Rules:
+- For "unsupported" or "plausible" bullets, probe the specific claim \
+  that lacks evidence — ask for concrete details, numbers, or \
+  implementation choices.
+- For "verified" bullets, ask a deeper follow-up that tests real \
+  understanding (architecture decisions, trade-offs, failure modes).
+- Be direct and specific. No generic "tell me about" questions.
+- The question should be answerable in 2-3 sentences.
+
+Respond in JSON: {"question": "your question here"}
+"""
+
+_EXPERIENCE_QUESTION_SYSTEM = """\
+You are a behavioral interviewer. Given a resume bullet from the \
+candidate's work experience, ask ONE pointed behavioral question \
+using the STAR format (Situation, Task, Action, Result).
+
+Rules:
+- Ask about a specific aspect of the bullet — a challenge faced, a \
+  decision made, a result achieved, or a collaboration required.
+- Probe for concrete details: team size, timeline, measurable impact.
+- Do NOT ask generic questions. Reference the specific technologies, \
+  metrics, or responsibilities mentioned in the bullet.
+- The question should be answerable in 3-4 sentences.
+
+Respond in JSON: {"question": "your question here"}
+"""
+
+_EDUCATION_QUESTION_SYSTEM = """\
+You are an interviewer testing a candidate's academic knowledge. Given \
+a bullet from the Education section of their resume, ask ONE pointed \
+knowledge question.
+
+Rules:
+- If the bullet mentions a GPA, coursework, or degree, ask about a \
+  concept they should know from that program.
+- If the bullet mentions a specific course or project, ask about the \
+  key concepts or techniques involved.
+- Test understanding, not memorization — ask "how does X work" or \
+  "what's the trade-off between X and Y", not "define X".
+- The question should be answerable in 2-3 sentences.
+
+Respond in JSON: {"question": "your question here"}
+"""
+
+_SKILLS_QUESTION_SYSTEM = """\
+You are a technical interviewer. Given a skill claim from the \
+candidate's resume, ask ONE practical question that tests whether \
+they actually use this technology.
+
+Rules:
+- Ask about real usage: "how would you do X with this tool" or "when \
+  would you choose X over Y".
+- Probe for hands-on experience, not textbook knowledge.
+- If the skill is a language or framework, ask about a specific feature, \
+  pattern, or common pitfall.
+- The question should be answerable in 2-3 sentences.
+
+Respond in JSON: {"question": "your question here"}
+"""
+
+_SECTION_QUESTION_SYSTEMS = {
+    "experience": _EXPERIENCE_QUESTION_SYSTEM,
+    "education": _EDUCATION_QUESTION_SYSTEM,
+    "skills": _SKILLS_QUESTION_SYSTEM,
+}
+
+# Interview round presets — match the questioning style to the kind of
+# company round the candidate is preparing for.
+_STYLE_MODIFIERS = {
+    "service": """\
+
+ROUND STYLE — service company (TCS/Infosys/Wipro-type):
+- Favor fundamentals and clarity over depth: "explain your project simply",
+  core language/OOP/DBMS concepts behind what they built.
+- Expect the candidate to explain their project to a non-expert panel in
+  2-3 sentences before drilling one level down.
+- Keep the question answerable without whiteboarding.""",
+    "product": """\
+
+ROUND STYLE — product company (design-depth round):
+- Favor architecture decisions, trade-offs, scalability, and failure modes.
+- Ask "why this over the alternative" and "what breaks at 10x load".
+- Reference the specific technologies in the bullet — generic system
+  design questions are not allowed.""",
+    "startup": """\
+
+ROUND STYLE — startup (ownership round):
+- Favor shipping speed, scrappiness, and end-to-end ownership.
+- Ask what the candidate cut, deferred, or hacked to ship — and how they'd
+  fix it with more time.
+- Probe whether they understand the WHOLE stack of what they built, not
+  just their corner.""",
+}
+
+INTERVIEW_STYLES = tuple(_STYLE_MODIFIERS)
+
+_FOLLOWUP_SYSTEM = """\
+You are a technical interviewer conducting a follow-up. Given the \
+original question and the candidate's answer, ask ONE natural \
+follow-up question that digs deeper.
+
+Rules:
+- If the answer was vague, ask for specifics.
+- If the answer was detailed, probe a related edge case or trade-off.
+- Keep it conversational — this should feel like a real interview.
+- One question only, answerable in 2-3 sentences.
+
+Respond in JSON: {"follow_up": "your follow-up question here"}
+"""
+
+_ASSESS_SYSTEM = """\
+You are evaluating a candidate's interview answer. Given the resume \
+bullet, the question asked, and the candidate's answer, assess how \
+well they demonstrated real knowledge.
+
+Respond in JSON:
+{"held_up": true/false, "assessment": "one sentence summary"}
+
+Set held_up to true if the answer shows genuine understanding, even \
+if imperfect. Set it to false if the answer is vague, evasive, or \
+contradicts the claim.
+"""
+
+_MODEL_ANSWER_SYSTEM = """\
+You are an interview coach. Given a resume bullet, an interview question \
+just asked about it, and the actual code evidence from the candidate's \
+codebase, write the answer the candidate SHOULD give.
+
+Rules:
+- 3-5 sentences, first person, spoken the way a candidate would in a real \
+  interview — not a written essay.
+- Ground every claim ONLY in the provided evidence. Reference the specific \
+  files, functions, or patterns shown. Never invent numbers, files, or \
+  capabilities that aren't in the evidence.
+- If the evidence only partially supports the bullet, answer honestly about \
+  what the code actually shows rather than overclaiming.
+
+Respond in JSON: {"model_answer": "the answer here"}
+"""
+
+_MODEL_ANSWER_NO_EVIDENCE_SYSTEM = """\
+You are an interview coach. A resume bullet was just asked about in an \
+interview, but there is NO code evidence in the candidate's ingested \
+codebase to back it up — the claim may be about a private repo, a \
+non-code achievement, or something that simply cannot be proven from code.
+
+Write the answer the candidate should give: honest, specific where they \
+legitimately can be, framed so they show real understanding WITHOUT \
+fabricating evidence or numbers they cannot support.
+
+Rules:
+- 3-5 sentences, first person, conversational.
+- Do NOT invent metrics, file names, or specifics that weren't in the bullet.
+- Show how to speak to the claim credibly and honestly, acknowledging the \
+  limits of what can be demonstrated.
+
+Respond in JSON: {"model_answer": "the answer here"}
+"""
+
+_SUMMARY_SYSTEM = """\
+You are wrapping up a mock interview. Given the rounds of Q&A and \
+assessments, write a brief summary.
+
+Respond in JSON:
+{"strong": ["point 1", "point 2"], \
+"weak": ["point 1", "point 2"], \
+"overall": "one paragraph overall assessment"}
+"""
+
+
+@dataclass(frozen=True)
+class InterviewRound:
+    bullet_text: str
+    section: str
+    heading: str
+    verdict: str
+    question: str
+    answer: str
+    follow_up: str
+    follow_up_answer: str
+    held_up: bool
+    assessment: str
+    model_answer: str = ""
+    completions: list[CompletionResult] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class InterviewSummary:
+    rounds: list[InterviewRound]
+    strong: list[str]
+    weak: list[str]
+    overall: str
+    completion: CompletionResult | None = None
+
+
+def select_bullets(
+    results: list[VerificationResult],
+    n: int,
+    *,
+    rng: random.Random | None = None,
+) -> list[VerificationResult]:
+    """Pick *n* bullets to quiz on, weighted toward weak verdicts."""
+    by_bullet: dict[str, VerificationResult] = {}
+    for r in results:
+        key = r.claim.bullet_text
+        if key not in by_bullet:
+            by_bullet[key] = r
+        elif _VERDICT_WEIGHT.get(r.verdict, 1) > _VERDICT_WEIGHT.get(
+            by_bullet[key].verdict, 1
+        ):
+            by_bullet[key] = r
+
+    unique = list(by_bullet.values())
+    if not unique:
+        return []
+
+    weights = [_VERDICT_WEIGHT.get(r.verdict, 1) for r in unique]
+    rng = rng or random.Random()
+    n = min(n, len(unique))
+
+    selected: list[VerificationResult] = []
+    remaining = list(zip(unique, weights, strict=True))
+
+    for _ in range(n):
+        if not remaining:
+            break
+        items, ws = zip(*remaining, strict=True)
+        choice = rng.choices(list(items), weights=list(ws), k=1)[0]
+        selected.append(choice)
+        remaining = [(r, w) for r, w in remaining if r is not choice]
+
+    return selected
+
+
+def generate_question(
+    result: VerificationResult,
+    provider: LLMProvider,
+    *,
+    style: str | None = None,
+) -> tuple[str, CompletionResult]:
+    """Ask the LLM to generate an interview question for this bullet.
+
+    Uses section-aware system prompts: behavioral/STAR for work experience,
+    knowledge-check for education, skill-application for skills, and
+    technical deep-dive for projects. ``style`` optionally tunes the
+    questioning to a company round type ("service" | "product" | "startup").
+    """
+    sec_type = getattr(result.claim, "section_type", "project")
+    system = _SECTION_QUESTION_SYSTEMS.get(sec_type, _QUESTION_SYSTEM)
+    modifier = _STYLE_MODIFIERS.get((style or "").strip().lower())
+    if modifier:
+        system += modifier
+
+    user = (
+        f"BULLET: {result.claim.bullet_text}\n"
+        f"SECTION: {result.claim.section}\n"
+        f"VERDICT: {result.verdict}\n"
+        f"EXPLANATION: {result.explanation}"
+    )
+    completion = provider.complete(system, user, json_mode=True)
+    try:
+        parsed = parse_json_loose(completion.text)
+        question = parsed.get("question", completion.text)
+    except (ValueError, json.JSONDecodeError, AttributeError):
+        question = completion.text
+    return question, completion
+
+
+def generate_follow_up(
+    question: str,
+    answer: str,
+    provider: LLMProvider,
+) -> tuple[str, CompletionResult]:
+    """Generate a follow-up question based on the candidate's answer."""
+    user = f"QUESTION: {question}\nANSWER: {answer}"
+    completion = provider.complete(_FOLLOWUP_SYSTEM, user, json_mode=True)
+    try:
+        parsed = parse_json_loose(completion.text)
+        follow_up = parsed.get("follow_up", completion.text)
+    except (ValueError, json.JSONDecodeError, AttributeError):
+        follow_up = completion.text
+    return follow_up, completion
+
+
+def assess_answer(
+    bullet_text: str,
+    question: str,
+    answer: str,
+    provider: LLMProvider,
+) -> tuple[bool, str, CompletionResult]:
+    """Assess whether the candidate's answer held up."""
+    user = f"BULLET: {bullet_text}\n" f"QUESTION: {question}\n" f"ANSWER: {answer}"
+    completion = provider.complete(_ASSESS_SYSTEM, user, json_mode=True)
+    try:
+        parsed = parse_json_loose(completion.text)
+        held_up = bool(parsed.get("held_up", False))
+        assessment = parsed.get("assessment", "")
+    except (ValueError, json.JSONDecodeError, AttributeError):
+        held_up = False
+        assessment = completion.text[:200]
+    return held_up, assessment, completion
+
+
+def generate_model_answer(
+    result: VerificationResult,
+    question: str,
+    provider: LLMProvider,
+) -> tuple[str, CompletionResult]:
+    """Generate the strong, honest answer the candidate SHOULD have given.
+
+    Grounded ONLY in the round's retrieved code evidence. When the bullet has
+    no evidence behind it (unsupported claims, non-code sections), the prompt
+    switches to honest-reframe guidance instead of inventing support — the
+    same honesty constraint the verifier enforces. Evidence chunks are
+    truncated so a large ``SearchResult.code`` block never blows the context
+    of a small local model.
+    """
+    evidence = getattr(result, "evidence", None) or []
+    if evidence:
+        parts = [
+            f"BULLET: {result.claim.bullet_text}",
+            f"QUESTION: {question}",
+            "",
+            "CODE EVIDENCE:",
+        ]
+        for e in evidence[:3]:
+            parts.append(f"--- {e.rel_path} :: {e.name} ---")
+            parts.append(e.code[:1200])
+        user = "\n".join(parts)
+        system = _MODEL_ANSWER_SYSTEM
+    else:
+        user = (
+            f"BULLET: {result.claim.bullet_text}\n"
+            f"QUESTION: {question}\n"
+            f"VERDICT: {result.verdict}\n"
+            f"EXPLANATION: {result.explanation}"
+        )
+        system = _MODEL_ANSWER_NO_EVIDENCE_SYSTEM
+
+    completion = provider.complete(system, user, json_mode=True)
+    try:
+        parsed = parse_json_loose(completion.text)
+        answer = parsed.get("model_answer", completion.text)
+    except (ValueError, json.JSONDecodeError, AttributeError):
+        answer = completion.text
+    return answer, completion
+
+
+def generate_summary(
+    rounds: list[InterviewRound],
+    provider: LLMProvider,
+) -> InterviewSummary:
+    """Generate a summary of the entire interview."""
+    parts = []
+    for i, r in enumerate(rounds, 1):
+        parts.append(
+            f"Round {i}:\n"
+            f"  Bullet: {r.bullet_text[:80]}\n"
+            f"  Verdict: {r.verdict}\n"
+            f"  Q: {r.question}\n"
+            f"  A: {r.answer[:100]}\n"
+            f"  Held up: {r.held_up}\n"
+            f"  Assessment: {r.assessment}"
+        )
+
+    completion = provider.complete(_SUMMARY_SYSTEM, "\n\n".join(parts), json_mode=True)
+
+    try:
+        parsed = parse_json_loose(completion.text)
+        strong = parsed.get("strong", [])
+        weak = parsed.get("weak", [])
+        overall = parsed.get("overall", "")
+    except (ValueError, json.JSONDecodeError, AttributeError):
+        strong = []
+        weak = []
+        overall = completion.text[:300]
+
+    return InterviewSummary(
+        rounds=rounds,
+        strong=strong,
+        weak=weak,
+        overall=overall,
+        completion=completion,
+    )

receipts/ats/__init__.py

@@ -0,0 +1 @@
+"""ATS scoring & comparison engine."""

receipts/ats/comparator.py

@@ -0,0 +1,98 @@
+"""Before/after ATS comparison — score original vs rewritten, report deltas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from receipts.ats.scorer import (
+    ATSScore,
+    score_tex_file,
+    score_tex_string,
+)
+
+
+@dataclass(frozen=True)
+class DimensionDelta:
+    name: str
+    before: int
+    after: int
+    delta: int
+    detail_before: str
+    detail_after: str
+
+
+@dataclass(frozen=True)
+class ComparisonReport:
+    before: ATSScore
+    after: ATSScore
+    deltas: list[DimensionDelta]
+    composite_delta: float
+    improved: bool
+
+    @property
+    def summary(self) -> str:
+        direction = "+" if self.composite_delta >= 0 else ""
+        lines = [
+            f"Composite: {self.before.composite:.1f} → {self.after.composite:.1f} "
+            f"({direction}{self.composite_delta:.1f})",
+            "",
+        ]
+        for d in self.deltas:
+            arrow = "+" if d.delta >= 0 else ""
+            lines.append(
+                f"  {d.name:<22} {d.before:>3} → {d.after:>3}  ({arrow}{d.delta})"
+            )
+        return "\n".join(lines)
+
+
+def compare_scores(before: ATSScore, after: ATSScore) -> ComparisonReport:
+    """Compare two ATSScore objects and produce a delta report."""
+    deltas: list[DimensionDelta] = []
+
+    for dim_before in before.dimensions:
+        dim_after = after.dimension(dim_before.name)
+        if dim_after is None:
+            continue
+        deltas.append(
+            DimensionDelta(
+                name=dim_before.name,
+                before=dim_before.score,
+                after=dim_after.score,
+                delta=dim_after.score - dim_before.score,
+                detail_before=dim_before.detail,
+                detail_after=dim_after.detail,
+            )
+        )
+
+    composite_delta = round(after.composite - before.composite, 1)
+
+    return ComparisonReport(
+        before=before,
+        after=after,
+        deltas=deltas,
+        composite_delta=composite_delta,
+        improved=composite_delta > 0,
+    )
+
+
+def compare_tex_files(
+    before_path: Path,
+    after_path: Path,
+    jd_text: str,
+) -> ComparisonReport:
+    """Score two .tex files against the same JD and compare."""
+    before_score = score_tex_file(before_path, jd_text)
+    after_score = score_tex_file(after_path, jd_text)
+    return compare_scores(before_score, after_score)
+
+
+def compare_tex_strings(
+    before_tex: str,
+    after_tex: str,
+    jd_text: str,
+) -> ComparisonReport:
+    """Score two TeX strings against the same JD and compare."""
+    before_score = score_tex_string(before_tex, jd_text)
+    after_score = score_tex_string(after_tex, jd_text)
+    return compare_scores(before_score, after_score)