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

receipts/rewrite/optimizer.py

@@ -0,0 +1,140 @@
+"""Score-aware rewrite optimization — never trade honesty for score.
+
+After the honest rewriter runs, each rewrite is checked for ATS-dimension
+regressions the rewrite itself introduced: losing every concrete number
+the original had (quantification) or losing a strong opening verb
+(action verbs). Offending bullets get ONE constrained re-prompt that pins
+the regression and supplies the provable numbers the model may use. If
+the retry still regresses — or weakens honesty in any way — the first
+honest rewrite is kept. Max one retry per bullet, and the loop reports
+what happened instead of hiding it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from receipts.ats.scorer import _NUMBER_RE, _STRONG_VERBS
+from receipts.llm.provider import LLMProvider
+from receipts.verify.rewriter import RewriteResult, rewrite_bullet
+from receipts.verify.verifier import VerificationResult
+
+
+@dataclass(frozen=True)
+class OptimizedRewrite:
+    result: RewriteResult
+    regressions_found: list[str] = field(default_factory=list)
+    retried: bool = False
+    retry_fixed: bool = False
+
+
+def _has_number(text: str) -> bool:
+    return bool(_NUMBER_RE.search(text))
+
+
+def _starts_with_strong_verb(text: str) -> bool:
+    words = text.strip().split()
+    if not words:
+        return False
+    return words[0].lower().rstrip(",.:;") in _STRONG_VERBS
+
+
+def check_regressions(rewrite: RewriteResult) -> list[str]:
+    """ATS dimensions where the rewrite is measurably weaker than the original."""
+    if rewrite.original == rewrite.rewritten:
+        return []
+
+    regressions: list[str] = []
+    if _has_number(rewrite.original) and not _has_number(rewrite.rewritten):
+        regressions.append("quantification")
+    if _starts_with_strong_verb(rewrite.original) and not _starts_with_strong_verb(
+        rewrite.rewritten
+    ):
+        regressions.append("action_verbs")
+    return regressions
+
+
+def _retry_constraint(regressions: list[str], grounded_facts: str | None) -> str:
+    parts = ["Your previous rewrite regressed on ATS dimensions:"]
+    if "quantification" in regressions:
+        if grounded_facts:
+            parts.append(
+                "- It lost all concrete numbers. Include at least one number,"
+                " but ONLY from the provable facts list or verified claims."
+            )
+        else:
+            parts.append(
+                "- It lost all concrete numbers. Keep any number that was"
+                " part of a verified claim; do not invent new ones."
+            )
+    if "action_verbs" in regressions:
+        parts.append(
+            "- It no longer starts with a strong action verb"
+            " (architected, built, engineered, optimized, ...). Fix that."
+        )
+    parts.append("Honesty rules still apply and always win over score.")
+    return "\n".join(parts)
+
+
+def optimize_rewrites(
+    rewrites: list[RewriteResult],
+    results_by_bullet: dict[str, list[VerificationResult]],
+    provider: LLMProvider,
+    *,
+    grounded_facts: str | None = None,
+    addable_keywords: list[str] | None = None,
+) -> list[OptimizedRewrite]:
+    """Check each rewrite for ATS regressions; one constrained retry each.
+
+    The retry is accepted only if it clears the regressions it was asked to
+    fix — otherwise the original honest rewrite stands.
+    """
+    optimized: list[OptimizedRewrite] = []
+
+    for rw in rewrites:
+        regressions = check_regressions(rw)
+        if not regressions:
+            optimized.append(OptimizedRewrite(result=rw))
+            continue
+
+        bullet_results = results_by_bullet.get(rw.original, [])
+        retry = rewrite_bullet(
+            rw.original,
+            bullet_results,
+            provider,
+            grounded_facts=grounded_facts,
+            addable_keywords=addable_keywords,
+            extra_constraint=_retry_constraint(regressions, grounded_facts),
+            original_raw=getattr(rw, "original_raw", ""),
+        )
+
+        still_regressed = set(check_regressions(retry)) & set(regressions)
+        if retry.rewritten != rw.original and not still_regressed:
+            optimized.append(
+                OptimizedRewrite(
+                    result=retry,
+                    regressions_found=regressions,
+                    retried=True,
+                    retry_fixed=True,
+                )
+            )
+        else:
+            optimized.append(
+                OptimizedRewrite(
+                    result=rw,
+                    regressions_found=regressions,
+                    retried=True,
+                    retry_fixed=False,
+                )
+            )
+
+    return optimized
+
+
+def group_results_by_bullet(
+    results: list[VerificationResult],
+) -> dict[str, list[VerificationResult]]:
+    by_bullet: dict[str, list[VerificationResult]] = {}
+    for r in results:
+        by_bullet.setdefault(r.claim.bullet_text, []).append(r)
+    return by_bullet

receipts/rewrite/tex_rewriter.py

@@ -0,0 +1,227 @@
+"""Surgical TeX bullet replacement.
+
+Copies the original .tex file verbatim and replaces only the bullet
+points that have rewrites — everything else (formatting, macros,
+headers, education, skills) is preserved exactly.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from receipts.resume.tex_parser import clean_tex
+from receipts.verify.rewriter import RewriteResult
+
+
+@dataclass(frozen=True)
+class TexRewriteReport:
+    original_path: Path
+    output_path: Path
+    replacements: int
+    skipped: int
+
+
+def _normalize(text: str) -> str:
+    """Collapse whitespace for fuzzy matching."""
+    return re.sub(r"\s+", " ", text).strip().lower()
+
+
+def _find_item_spans(tex: str) -> list[tuple[int, int, str]]:
+    r"""Find all \item blocks in the TeX source.
+
+    Returns (start, end, cleaned_text) for each \item.
+    The span covers from ``\item`` to just before the next ``\item``,
+    ``\end{highlights}``, or ``\end{``.
+    """
+    pattern = re.compile(r"\\item\s+", re.DOTALL)
+    matches = list(pattern.finditer(tex))
+    spans: list[tuple[int, int, str]] = []
+
+    for i, m in enumerate(matches):
+        start = m.start()
+        if i + 1 < len(matches):
+            end = matches[i + 1].start()
+        else:
+            end_hl = tex.find(r"\end{highlights}", m.end())
+            end_env = tex.find(r"\end{", m.end())
+            if end_hl != -1:
+                end = end_hl
+            elif end_env != -1:
+                end = end_env
+            else:
+                end = len(tex)
+
+        raw = tex[m.end() : end].strip()
+        cleaned = clean_tex(raw)
+        spans.append((start, end, cleaned))
+
+    return spans
+
+
+def _match_rewrite(
+    cleaned_item: str, rewrites: list[RewriteResult]
+) -> RewriteResult | None:
+    """Find the rewrite whose original matches this item's cleaned text."""
+    norm_item = _normalize(cleaned_item)
+    for rw in rewrites:
+        if rw.original == rw.rewritten:
+            continue
+        norm_orig = _normalize(rw.original)
+        if norm_orig == norm_item:
+            return rw
+        if len(norm_orig) > 20 and norm_orig in norm_item:
+            return rw
+        if len(norm_item) > 20 and norm_item in norm_orig:
+            return rw
+    return None
+
+
+def _plain_to_tex_bullet(text: str) -> str:
+    """Convert a plain-text rewritten bullet into minimal LaTeX.
+
+    Wraps technology names and numbers in \\textbf{} to match typical
+    resume styling. Escapes LaTeX-special characters.
+    """
+    s = text
+    s = s.replace("&", "\\&")
+    s = s.replace("%", "\\%")
+    s = s.replace("#", "\\#")
+    s = s.replace("~", "\\textasciitilde{}")
+    return s
+
+
+def rewrite_tex(
+    original_path: Path,
+    rewrites: list[RewriteResult],
+    output_path: Path | None = None,
+    *,
+    section_filter: str | None = None,
+) -> TexRewriteReport:
+    """Copy the .tex file and surgically replace rewritten bullets.
+
+    Parameters
+    ----------
+    original_path:
+        Path to the original .tex resume file.
+    rewrites:
+        List of RewriteResult from the verification pipeline.
+    output_path:
+        Where to write the modified .tex. Defaults to
+        ``<original_stem>_optimized.tex`` next to the original.
+    section_filter:
+        If given, only replace bullets inside \\section{} blocks whose
+        name contains this substring (case-insensitive). Useful for
+        limiting changes to just the Projects section.
+    """
+    if output_path is None:
+        output_path = original_path.with_stem(original_path.stem + "_optimized")
+
+    tex = original_path.read_text(encoding="utf-8")
+    actionable = [rw for rw in rewrites if rw.original != rw.rewritten]
+
+    if not actionable:
+        output_path.write_text(tex, encoding="utf-8")
+        return TexRewriteReport(
+            original_path=original_path,
+            output_path=output_path,
+            replacements=0,
+            skipped=0,
+        )
+
+    if section_filter:
+        section_ranges = _section_ranges(tex, section_filter)
+    else:
+        section_ranges = None
+
+    replacements: list[tuple[int, int, str]] = []
+    matched_rewrites: set[int] = set()
+
+    def _in_section(pos: int) -> bool:
+        if section_ranges is None:
+            return True
+        return any(s <= pos < e for s, e in section_ranges)
+
+    def _overlaps_claimed(start: int, end: int) -> bool:
+        return any(start < e and s < end for s, e, _ in replacements)
+
+    # Pass 1 — replace by identity: the bullet's raw TeX (carried through
+    # the claim → verification → rewrite pipeline) is a verbatim substring
+    # of this file, so an exact find pinpoints it. This also covers bullets
+    # that aren't \item lines at all (e.g. onecolentry skills rows).
+    for rw in actionable:
+        raw = getattr(rw, "original_raw", "")
+        if not raw or len(raw.strip()) < 10:
+            continue
+        idx = tex.find(raw)
+        if idx == -1 or tex.find(raw, idx + 1) != -1:
+            continue  # absent or ambiguous — leave it to the fuzzy pass
+        if not _in_section(idx) or _overlaps_claimed(idx, idx + len(raw)):
+            continue
+        matched_rewrites.add(id(rw))
+        replacements.append((idx, idx + len(raw), _plain_to_tex_bullet(rw.rewritten)))
+
+    # Pass 2 — legacy fuzzy match over \item spans for anything left
+    # (externally supplied rewrites, or raw text that didn't resolve).
+    spans = _find_item_spans(tex)
+    remaining = [rw for rw in actionable if id(rw) not in matched_rewrites]
+
+    for start, end, cleaned in spans:
+        if not _in_section(start) or _overlaps_claimed(start, end):
+            continue
+
+        rw = _match_rewrite(cleaned, remaining)
+        if rw is not None:
+            rw_idx = id(rw)
+            if rw_idx not in matched_rewrites:
+                matched_rewrites.add(rw_idx)
+                new_item = f"\\item {_plain_to_tex_bullet(rw.rewritten)}"
+                ws_after = ""
+                raw_after = tex[end - 1 : end]
+                if raw_after == "\n":
+                    ws_after = "\n"
+                replacements.append((start, end, new_item + ws_after))
+
+    result_tex = tex
+    for start, end, replacement in sorted(replacements, reverse=True):
+        result_tex = result_tex[:start] + replacement + result_tex[end:]
+
+    output_path.write_text(result_tex, encoding="utf-8")
+
+    return TexRewriteReport(
+        original_path=original_path,
+        output_path=output_path,
+        replacements=len(replacements),
+        skipped=len(actionable) - len(replacements),
+    )
+
+
+def _section_ranges(tex: str, filter_str: str) -> list[tuple[int, int]]:
+    r"""Find byte ranges of \section{} blocks matching the filter."""
+    section_re = re.compile(r"\\section\{", re.DOTALL)
+    hits = list(section_re.finditer(tex))
+    ranges: list[tuple[int, int]] = []
+
+    lower_filter = filter_str.lower()
+
+    for idx, m in enumerate(hits):
+        brace_start = m.start() + len("\\section")
+        depth = 0
+        i = brace_start
+        while i < len(tex):
+            if tex[i] == "{":
+                depth += 1
+            elif tex[i] == "}":
+                depth -= 1
+                if depth == 0:
+                    break
+            i += 1
+        section_name = clean_tex(tex[brace_start + 1 : i])
+
+        if lower_filter in section_name.lower():
+            sec_start = m.start()
+            sec_end = hits[idx + 1].start() if idx + 1 < len(hits) else len(tex)
+            ranges.append((sec_start, sec_end))
+
+    return ranges