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

receipts/resume/claim_extractor.py

@@ -0,0 +1,338 @@
+"""Extract verifiable claims from parsed resume bullets.
+
+Three kinds of claims are pulled:
+
+* **numeric** — percentages, counts, latency, durations, ratios
+  (``"~40%"``, ``"12 microservices"``, ``"sub-2s"``).
+* **technology** — specific tools, frameworks, languages, platforms
+  (``"FastAPI"``, ``"ChromaDB"``, ``"React"``).
+* **contextual** — whole-bullet claims from sections where code evidence
+  is unlikely (education, work experience, certifications, etc.). These
+  exist so the AMA interviewer can still quiz on them.
+
+Each claim carries surrounding context so the verifier (Phase 4) can
+search the knowledge base for supporting evidence.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from receipts.resume.tex_parser import ParsedResume
+
+# ---------------------------------------------------------------------------
+# Section classification
+# ---------------------------------------------------------------------------
+
+_CODE_SECTION_KEYWORDS = ["project"]
+_EXPERIENCE_SECTION_KEYWORDS = ["experience", "work", "internship", "employment"]
+_EDUCATION_SECTION_KEYWORDS = ["education"]
+_SKILLS_SECTION_KEYWORDS = ["skill", "technical"]
+_NOPROBE_SECTION_KEYWORDS = [
+    "certification",
+    "publication",
+    "award",
+    "honor",
+    "extracurricular",
+    "leadership",
+    "volunteer",
+    "achievement",
+    "activity",
+]
+
+
+def classify_section(section_name: str) -> str:
+    """Classify a resume section into a category for verification/AMA behavior.
+
+    Returns one of: ``"project"``, ``"experience"``, ``"education"``,
+    ``"skills"``, ``"other"``.
+    """
+    lower = section_name.lower()
+    for kw in _CODE_SECTION_KEYWORDS:
+        if kw in lower:
+            return "project"
+    for kw in _EXPERIENCE_SECTION_KEYWORDS:
+        if kw in lower:
+            return "experience"
+    for kw in _EDUCATION_SECTION_KEYWORDS:
+        if kw in lower:
+            return "education"
+    for kw in _SKILLS_SECTION_KEYWORDS:
+        if kw in lower:
+            return "skills"
+    for kw in _NOPROBE_SECTION_KEYWORDS:
+        if kw in lower:
+            return "other"
+    return "other"
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Claim:
+    section: str
+    entry_heading: str
+    bullet_text: str
+    claim_type: str  # "numeric" | "technology" | "contextual"
+    value: str  # the extracted token: "~40%", "FastAPI", or bullet text
+    snippet: str  # surrounding context
+    section_type: str = "project"  # classify_section() result
+    bullet_raw: str = ""  # raw TeX of the source bullet, for exact replacement
+
+
+# ---------------------------------------------------------------------------
+# Numeric extraction
+# ---------------------------------------------------------------------------
+
+_NUMERIC_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"~?\s?\d[\d,]*(?:\.\d+)?\s*%"), "percentage"),
+    (re.compile(r"sub-\d[\d,]*(?:\.\d+)?\s*(?:s|ms)\b"), "latency"),
+    (re.compile(r"\d[\d,]*(?:\.\d+)?\s*(?:s|ms)\s+\w+"), "latency"),
+    (re.compile(r"\d[\d,]*/\d[\d,]*"), "ratio"),
+    (
+        re.compile(r"\d[\d,]*\s+(?:year|month|week|day|hour|minute|second)s?\b"),
+        "duration",
+    ),
+    (re.compile(r"\d[\d,]*\+?\s+[\w./-]+(?:\s+[\w./-]+)?"), "count"),
+]
+
+_SKIP_COUNT = re.compile(r"^\d+\s*(?:pt|cm|mm|em|ex|px|rem)\b", re.IGNORECASE)
+
+
+def _context(text: str, start: int, end: int) -> str:
+    lo = max(0, start - 40)
+    hi = min(len(text), end + 40)
+    snippet = text[lo:hi]
+    if lo > 0:
+        sp = snippet.find(" ")
+        if sp != -1 and sp < 15:
+            snippet = snippet[sp + 1 :]
+    if hi < len(text):
+        sp = snippet.rfind(" ")
+        if sp != -1 and len(snippet) - sp < 15:
+            snippet = snippet[:sp]
+    return snippet.strip()
+
+
+def _overlaps(span: tuple[int, int], seen: list[tuple[int, int]]) -> bool:
+    for s, e in seen:
+        if span[0] < e and s < span[1]:
+            return True
+    return False
+
+
+def _extract_numeric(bullet: str) -> list[tuple[str, str, str]]:
+    """Return (value, snippet, category) triples."""
+    found: list[tuple[str, str, str]] = []
+    seen_spans: list[tuple[int, int]] = []
+
+    for pattern, category in _NUMERIC_PATTERNS:
+        for m in pattern.finditer(bullet):
+            span = m.span()
+            if _overlaps(span, seen_spans):
+                continue
+            value = m.group().strip()
+            if category == "count" and _SKIP_COUNT.match(value):
+                continue
+            if category == "count" and re.match(r"^\d+$", value):
+                continue
+            seen_spans.append(span)
+            found.append((value, _context(bullet, *span), category))
+
+    return found
+
+
+# ---------------------------------------------------------------------------
+# Technology extraction
+# ---------------------------------------------------------------------------
+
+_KNOWN_TECH: list[str] = [
+    # multi-word (longest first so they match before substrings)
+    "Azure OpenAI",
+    "Azure SQL",
+    "Docker Compose",
+    "Framer Motion",
+    "Google Advanced Data Analytics",
+    "Radix UI",
+    "Server-Sent Events",
+    "Tailwind CSS",
+    "tree-sitter",
+    # versioned / compound
+    "Express.js",
+    "GPT-4o",
+    "Node.js",
+    "React 18",
+    # single-word frameworks / libs
+    "Alembic",
+    "ChromaDB",
+    "Clerk",
+    "Databricks",
+    "Detekt",
+    "Django",
+    "Express",
+    "FastAPI",
+    "Flask",
+    "Geekbench",
+    "HTTPX",
+    "Nginx",
+    "OpenCL",
+    "Pandas",
+    "PostgreSQL",
+    "Pydantic",
+    "Pytest",
+    "React",
+    "Recharts",
+    "Redis",
+    "SQLAlchemy",
+    "Sentry",
+    "Snowflake",
+    "Uvicorn",
+    "Vite",
+    "Vulkan",
+    "pgvector",
+    # languages
+    "Java",
+    "JavaScript",
+    "Kotlin",
+    "Python",
+    "SQL",
+    "TypeScript",
+    # infra / concepts
+    "CI/CD",
+    "Docker",
+    "Git",
+    "HNSW",
+    "JWT",
+    "RAG",
+    "REST",
+    "SPCS",
+    "SSE",
+    "WebSocket",
+]
+
+# Public alias — the ATS scorer boosts these terms during keyword ranking.
+KNOWN_TECH = _KNOWN_TECH
+
+_TECH_PATTERNS: list[re.Pattern[str]] = []
+
+
+def _build_tech_patterns() -> None:
+    if _TECH_PATTERNS:
+        return
+    for tech in sorted(_KNOWN_TECH, key=len, reverse=True):
+        escaped = re.escape(tech)
+        _TECH_PATTERNS.append(re.compile(r"(?<![A-Za-z])" + escaped + r"(?![A-Za-z])"))
+
+
+def _extract_tech(bullet: str) -> list[tuple[str, str]]:
+    """Return (tech_name, snippet) pairs."""
+    _build_tech_patterns()
+    found: list[tuple[str, str]] = []
+    seen_names: set[str] = set()
+    for i, pattern in enumerate(_TECH_PATTERNS):
+        tech = sorted(_KNOWN_TECH, key=len, reverse=True)[i]
+        m = pattern.search(bullet)
+        if m and tech not in seen_names:
+            shorter = tech.split()[0] if " " in tech else None
+            if shorter:
+                seen_names.add(shorter)
+            seen_names.add(tech)
+            found.append((tech, _context(bullet, m.start(), m.end())))
+    return found
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def extract_claims(
+    resume: ParsedResume,
+    sections: list[str] | None = None,
+    entries: list[str] | None = None,
+    include_skills_with_entries: bool = True,
+) -> list[Claim]:
+    """Pull numeric, technology, and contextual claims from every bullet.
+
+    If *sections* is given, only bullets from matching section names are
+    processed (case-insensitive substring match, so ``"project"`` matches
+    ``"Projects"`` and ``"Personal Projects"``).
+
+    If *entries* is given, only bullets whose entry heading matches one of
+    the filters are processed (case-insensitive substring match, so
+    ``"one more light"`` matches the "One More Light" project entry).
+    Skills-type sections are still included by default so JD keyword
+    matching always has the skills list to work with — pass
+    ``include_skills_with_entries=False`` to disable that.
+
+    For non-project sections (education, experience, skills, etc.), a
+    ``contextual`` claim is generated per bullet so the AMA interviewer
+    can still quiz on them even without code evidence.
+    """
+    claims: list[Claim] = []
+    _filters = [s.lower() for s in sections] if sections else None
+    _entry_filters = [e.lower() for e in entries] if entries else None
+
+    for sec_name, heading, bullet in resume.all_items:
+        if _filters and not any(f in sec_name.lower() for f in _filters):
+            continue
+        if _entry_filters:
+            entry_match = any(f in heading.lower() for f in _entry_filters)
+            skills_pass = (
+                include_skills_with_entries and classify_section(sec_name) == "skills"
+            )
+            if not entry_match and not skills_pass:
+                continue
+
+        sec_type = classify_section(sec_name)
+        has_specific_claims = False
+
+        for value, snippet, _cat in _extract_numeric(bullet.text):
+            claims.append(
+                Claim(
+                    section=sec_name,
+                    entry_heading=heading,
+                    bullet_text=bullet.text,
+                    claim_type="numeric",
+                    value=value,
+                    snippet=snippet,
+                    section_type=sec_type,
+                    bullet_raw=bullet.raw_tex,
+                )
+            )
+            has_specific_claims = True
+
+        for tech, snippet in _extract_tech(bullet.text):
+            claims.append(
+                Claim(
+                    section=sec_name,
+                    entry_heading=heading,
+                    bullet_text=bullet.text,
+                    claim_type="technology",
+                    value=tech,
+                    snippet=snippet,
+                    section_type=sec_type,
+                    bullet_raw=bullet.raw_tex,
+                )
+            )
+            has_specific_claims = True
+
+        if not has_specific_claims and sec_type != "project":
+            claims.append(
+                Claim(
+                    section=sec_name,
+                    entry_heading=heading,
+                    bullet_text=bullet.text,
+                    claim_type="contextual",
+                    value=bullet.text[:120],
+                    snippet=bullet.text,
+                    section_type=sec_type,
+                    bullet_raw=bullet.raw_tex,
+                )
+            )
+
+    return claims

receipts/resume/loader.py

@@ -0,0 +1,35 @@
+"""One entry point for loading a resume, whatever the format.
+
+``.tex`` gets the macro-aware parser (exact structure, enables surgical
+rewriting); ``.pdf`` and ``.txt`` get the layout-heuristic parser. Both
+return the same ``ParsedResume``, so every downstream consumer is
+format-agnostic. Rewriting the .tex file itself is the one flow that
+genuinely requires the .tex source — its command guards for that.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from receipts.errors import ReceiptsError
+from receipts.resume.tex_parser import ParsedResume
+
+
+def load_resume(path: Path) -> ParsedResume:
+    suffix = path.suffix.lower()
+    if suffix == ".tex":
+        from receipts.resume.tex_parser import parse_file
+
+        return parse_file(path)
+    if suffix == ".pdf":
+        from receipts.resume.pdf_parser import parse_pdf
+
+        return parse_pdf(path)
+    if suffix in (".txt", ".md"):
+        from receipts.resume.pdf_parser import parse_text
+
+        return parse_text(path.read_text(encoding="utf-8", errors="replace"))
+    raise ReceiptsError(
+        f"Unsupported resume format '{suffix or path.name}'."
+        " Use a .tex source, a text-based .pdf, or a plain .txt export."
+    )

receipts/resume/pdf_parser.py

@@ -0,0 +1,259 @@
+"""Parse a PDF (or plain-text) resume into the tex_parser structures.
+
+Friction killer: most people's resume is a PDF, not a LaTeX source. A PDF
+is flat text with no macros to anchor on, so this parser rebuilds the
+structure with layout heuristics — section keywords, bullet glyphs, wrap
+continuation, heading/date shapes. It emits the exact same ``ParsedResume``
+shapes as ``tex_parser``, so everything downstream (claim extraction,
+verification, AMA, dossier) is untouched.
+
+Costs ZERO LLM calls — text extraction is pypdf, structure is regex and
+rules. Honest limits: text-layer PDFs parse well; unusual layouts may
+mis-group a line or two; scanned/image PDFs have no text at all and are
+rejected with a clear message instead of guessed at.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from receipts.errors import ReceiptsError
+from receipts.resume.tex_parser import (
+    ParsedResume,
+    ResumeBullet,
+    ResumeEntry,
+    ResumeSection,
+)
+
+#: Canonical section keywords (lowercase). A short line that normalizes to
+#: one of these — or is ALL CAPS and contains one — starts a new section.
+_SECTION_KEYWORDS = {
+    "education",
+    "experience",
+    "work experience",
+    "professional experience",
+    "employment",
+    "internships",
+    "projects",
+    "personal projects",
+    "academic projects",
+    "skills",
+    "technical skills",
+    "skills & certifications",
+    "certifications",
+    "certificates",
+    "publications",
+    "research",
+    "achievements",
+    "awards",
+    "honors",
+    "leadership",
+    "extracurricular",
+    "extracurriculars",
+    "activities",
+    "volunteering",
+    "volunteer experience",
+    "coursework",
+    "summary",
+    "objective",
+    "profile",
+    "interests",
+    "languages",
+}
+
+#: Sections where every non-bullet line is its own heading-only entry
+#: (a "Languages: Python, SQL" line is a claim in itself).
+_LINE_PER_ENTRY_SECTIONS = {
+    "skills",
+    "technical skills",
+    "certifications",
+    "certificates",
+    "education",
+    "publications",
+    "coursework",
+    "languages",
+    "interests",
+}
+
+_BULLET_GLYPHS = "•◦▪‣·∙●○–—*"
+
+_YEAR_RE = re.compile(r"(?:19|20)\d{2}")
+_DATE_TAIL_RE = re.compile(
+    r"((?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+)?"
+    r"(?:19|20)\d{2}\s*[–—-]?\s*"
+    r"(?:(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+)?"
+    r"(?:(?:19|20)\d{2}|[Pp]resent|[Cc]urrent)?\s*$"
+)
+
+_CONTACT_RE = re.compile(
+    r"@|linkedin\.com|github\.com|(?:\+?\d[\d ()\-]{7,})|https?://|www\."
+)
+
+#: A line that is NOTHING BUT a date range ("May 2024 - Aug 2024",
+#: "2021 – Present") — belongs to the heading above it, never a new entry.
+_DATE_ONLY_RE = re.compile(
+    r"^(?:(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s*)?"
+    r"(?:19|20)\d{2}\s*[–—-]+\s*"
+    r"(?:(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s*)?"
+    r"(?:(?:19|20)\d{2}|[Pp]resent|[Cc]urrent|[Oo]ngoing)$"
+)
+
+
+def _normalize(line: str) -> str:
+    return re.sub(r"[^a-z& ]", "", line.strip().lower()).strip()
+
+
+def _section_name(line: str) -> str | None:
+    """The section this line starts, or None."""
+    stripped = line.strip().strip(":").strip()
+    if not stripped or len(stripped) > 40:
+        return None
+    norm = _normalize(stripped)
+    # Singular/plural tolerant: "Publication" matches "publications".
+    variants = {norm, norm + "s"}
+    if norm.endswith("s"):
+        variants.add(norm[:-1])
+    if variants & _SECTION_KEYWORDS:
+        return stripped
+    # ALL-CAPS-ish short lines containing a keyword ("TECHNICAL SKILLS  ")
+    letters = [c for c in stripped if c.isalpha()]
+    if letters and all(c.isupper() for c in letters):
+        for kw in _SECTION_KEYWORDS:
+            if kw in norm or kw in norm + "s":
+                return stripped
+    return None
+
+
+def _is_bullet_line(line: str) -> bool:
+    s = line.strip()
+    if len(s) < 3:
+        return False
+    first = s[0]
+    if first in _BULLET_GLYPHS:
+        return True
+    # PDF extractors map list markers to arbitrary glyphs (seen: \x7f).
+    # Any non-alphanumeric single marker followed by a space counts.
+    return not first.isalnum() and first not in "([<{\"'#$%&/@\\" and s[1] == " "
+
+
+def _strip_bullet(line: str) -> str:
+    return line.strip().lstrip(_BULLET_GLYPHS + "\x7f\x95").strip()
+
+
+def _looks_like_new_entry(line: str) -> bool:
+    """In experience/projects, does a non-bullet line start a NEW entry
+    (vs. continuing the previous wrapped bullet)?"""
+    s = line.strip()
+    if not s or not s[0].isupper():
+        return False
+    return bool("|" in s or _DATE_TAIL_RE.search(s) or len(s) <= 60)
+
+
+def _entry_date(heading: str) -> str:
+    m = _YEAR_RE.search(heading)
+    return m.group(0) if m else ""
+
+
+def parse_text(text: str) -> ParsedResume:
+    """Rebuild resume structure from flat text (PDF-extracted or .txt)."""
+    raw_lines = [ln.rstrip() for ln in text.splitlines()]
+    lines = [ln for ln in raw_lines if ln.strip()]
+    if not lines:
+        raise ReceiptsError("The resume is empty after text extraction.")
+
+    # Name: first line that isn't contact info.
+    name = ""
+    for ln in lines[:5]:
+        if not _CONTACT_RE.search(ln) and _section_name(ln) is None:
+            name = ln.strip()
+            break
+
+    sections: list[ResumeSection] = []
+    current_section: str | None = None
+    entries: list[ResumeEntry] = []
+    heading = ""
+    bullets: list[ResumeBullet] = []
+
+    def flush_entry() -> None:
+        nonlocal heading, bullets
+        if heading or bullets:
+            entries.append(
+                ResumeEntry(
+                    heading=heading,
+                    date=_entry_date(heading),
+                    bullets=bullets,
+                    heading_raw=heading,
+                )
+            )
+        heading = ""
+        bullets = []
+
+    def flush_section() -> None:
+        nonlocal entries
+        flush_entry()
+        if current_section is not None and entries:
+            sections.append(ResumeSection(name=current_section, entries=entries))
+        entries = []
+
+    for line in lines:
+        sec = _section_name(line)
+        if sec is not None:
+            flush_section()
+            current_section = sec
+            continue
+        if current_section is None:
+            continue  # contact header before the first section
+
+        line_per_entry = _normalize(current_section) in _LINE_PER_ENTRY_SECTIONS
+
+        if _is_bullet_line(line):
+            bullets.append(ResumeBullet(text=_strip_bullet(line), raw_tex=line))
+        elif line_per_entry:
+            # Skills/certs/education: every line is a claim of its own.
+            flush_entry()
+            heading = line.strip()
+            flush_entry()
+        elif heading and not bullets and _DATE_ONLY_RE.match(line.strip()):
+            heading = f"{heading} | {line.strip()}"  # the heading's date line
+        elif not bullets and heading and not _looks_like_new_entry(line):
+            heading = f"{heading} | {line.strip()}"  # wrapped heading line
+        elif bullets and not _looks_like_new_entry(line):
+            # Wrapped continuation of the previous bullet.
+            last = bullets[-1]
+            bullets[-1] = ResumeBullet(
+                text=f"{last.text} {line.strip()}",
+                raw_tex=f"{last.raw_tex} {line.strip()}",
+            )
+        else:
+            flush_entry()
+            heading = line.strip()
+
+    flush_section()
+
+    if not sections:
+        raise ReceiptsError(
+            "Could not find any resume sections (Education, Experience,"
+            " Projects, Skills...) in the text. If this is a scanned/image"
+            " PDF, export a text-based PDF or use the .tex source."
+        )
+    return ParsedResume(name=name, sections=sections)
+
+
+def parse_pdf(path: Path) -> ParsedResume:
+    """Extract text from a PDF resume and parse its structure."""
+    from pypdf import PdfReader  # verified against installed pypdf 6.x
+
+    try:
+        reader = PdfReader(str(path))
+        text = "\n".join(page.extract_text() or "" for page in reader.pages)
+    except Exception as exc:
+        raise ReceiptsError(f"Could not read '{path.name}' as a PDF: {exc}") from None
+
+    if len(text.strip()) < 100:
+        raise ReceiptsError(
+            f"'{path.name}' has (almost) no extractable text — it is likely a"
+            " scanned/image PDF. Export a text-based PDF from your editor,"
+            " or use the .tex source."
+        )
+    return parse_text(text)