proofix 0.5.0__py3-none-any.whl

proofix/__init__.py

@@ -0,0 +1,3 @@
+"""proofix: typos and punctuation, fixed under audit."""
+
+__version__ = "0.5.0"

proofix/cli.py

@@ -0,0 +1,328 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import difflib
+import math
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from adjudicate import Cache, ConfigError, Edit, adjudicate, apply_edits, check_endpoint, resolve_endpoint, run_setup, system_prompt
+
+from . import __version__, report
+from .commas import CommaCache, correct_commas
+from .lt import LTError, find_languagetool, run_languagetool
+from . import consistency, hygiene
+from .tiers import partition, typos_edits
+
+DESCRIPTION = """\
+Fix typos and punctuation in a Markdown file, under audit.
+
+Five tiers, each bounded so every change is one logged, reasoned edit:
+
+0. Hygiene: HTML entities Markdown can carry plainly, zero-width spaces,
+   byte-order marks, soft hyphens, control characters, Windows line endings
+   and decomposed accents are fixed deterministically.
+1. Mechanical faults with one right answer are fixed outright: a space before a
+   comma or period, a missing space after one, doubled punctuation, doubled
+   words. Detected by LanguageTool (and, if installed, the `typos` tool for
+   known misspellings).
+2. Adjudicated: LanguageTool proposes spellings or grammar fixes, and a
+   language model picks one or KEEP from the sentence and the rule's message.
+3. Compounds and consistency: the model chooses closed, hyphenated or open
+   for compounds the dictionaries question ("cyber attack", "non-profit"),
+   and one form for terms the document capitalises two ways.
+4. Commas: comma placement, which no rule engine detects, is corrected
+   sentence by sentence by the model under a diff guard: only insertions and
+   deletions of commas are accepted; anything else the model returns is
+   rejected and reported.
+
+Without a model, tiers 0 and 1 still apply; tier 2's fixes are listed for
+review, tier 3 is skipped and sentences are not checked for commas.
+
+Code spans, fenced code, link targets, URLs, HTML and front matter are never
+touched. Run it after stylefix so LanguageTool sees the target variety.
+"""
+
+EPILOG = """\
+examples:
+  proofix --setup                        # choose, test and save a model endpoint
+  proofix draft.md                       # -> draft.proofed.md, US English
+  proofix draft.md --target uk -o out.md
+  proofix draft.md --changes             # list every change as it is made
+  proofix draft.md --no-commas --llm none
+      LanguageTool's mechanical fixes only; nothing needs a model
+
+Requires languagetool on PATH for tier 1's LanguageTool fixes and for tier 2
+(brew install languagetool); tiers 3 and 4 need only a model. Accept lists:
+--accept, ~/.config/proofix/accept.txt, ~/.config/stylefix/accept.txt,
+./.stylefix/accept.txt and ./.proofix/accept.txt are all honoured.
+
+environment:
+  PROOFIX_LLM_URL, PROOFIX_LLM_MODEL, PROOFIX_LLM_KEY
+      the model endpoint for proofix (same as --url, --model, and the API key)
+  ADJUDICATE_LLM_URL, ADJUDICATE_LLM_MODEL, ADJUDICATE_LLM_KEY
+      the same, shared with stylefix; below the proofix variables and config
+  OLLAMA_HOST   Ollama base URL (default http://localhost:11434)
+
+files:
+  ~/.config/proofix/config.toml      [llm] url, model, api_key or api_key_env,
+                                     timeout, thinking_switch (proofix only)
+  ~/.config/adjudicate/config.toml   the same table, shared with stylefix
+
+Full documentation: https://github.com/AndrewBroz/proofix (man page:
+man/proofix.1 in the source)
+"""
+
+TASK = "You are a meticulous copy editor fixing typos and punctuation in a document written in {variety}."
+VARIETY = {"us": "American English", "uk": "British English"}
+
+
+def positive_seconds(text: str) -> float:
+    """argparse type for --timeout: a positive, finite number of seconds."""
+    try:
+        value = float(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"not a number: {text!r}") from None
+    if not (math.isfinite(value) and value > 0):
+        raise argparse.ArgumentTypeError(f"must be a positive number of seconds, not {text}")
+    return value
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="proofix", description=DESCRIPTION, epilog=EPILOG,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("input", type=Path, nargs="?", help="Markdown file to proofread")
+    p.add_argument("-o", "--output", type=Path, metavar="FILE",
+                   help="default: <input>.proofed.md")
+    p.add_argument("-i", "--in-place", action="store_true", help="overwrite the input file")
+    p.add_argument("--target", choices=["us", "uk"], default="us",
+                   help="English variety the document is written in (default: %(default)s)")
+    p.add_argument("--accept", type=Path, metavar="FILE",
+                   help="extra words to never flag as misspelled, one per line")
+    p.add_argument("--no-lt", action="store_true",
+                   help="skip LanguageTool: its tier 1 fixes (typos still runs) and all of tier 2")
+    p.add_argument("--lt-level", choices=["default", "picky"], default="default",
+                   help="LanguageTool rule level (default: %(default)s)")
+    p.add_argument("--no-typos", action="store_true",
+                   help="skip the `typos` pre-pass even if installed")
+    p.add_argument("--no-hygiene", action="store_true",
+                   help="skip text hygiene (HTML entities, invisible characters, line endings, "
+                        "decomposed accents)")
+    p.add_argument("--no-consistency", action="store_true",
+                   help="skip the compounds and consistency tier (closed, hyphenated or open "
+                        "compounds; terms capitalised two ways)")
+    p.add_argument("--style", default="none", metavar="GUIDE",
+                   help="style guide, only for its hyphenation habit (ap hyphenates less); "
+                        "chicago, gpo, ap, apa, oxford, guardian or none")
+    p.add_argument("--commas", choices=["gated", "all", "none"], default="gated",
+                   help="comma tier: gated sends only sentences with a comma, an introductory "
+                        "opener, a clause trigger or a conjunction joining clauses; all sends every "
+                        "sentence; none skips it (default: %(default)s)")
+    p.add_argument("--no-commas", action="store_true", help="same as --commas none")
+    p.add_argument("--max-sentences", type=int, metavar="N",
+                   help="cap on sentences sent to the comma tier (the rest are reported as unchecked)")
+    p.add_argument("--optional-commas", choices=["leave", "add"], default="leave",
+                   help="what the comma tier does with commas that are optional by convention "
+                        "(default: %(default)s)")
+    p.add_argument("--llm", choices=["auto", "ollama", "none"], default="auto", help="auto: the endpoint from --url, PROOFIX_LLM_*, ~/.config/proofix/config.toml, ADJUDICATE_LLM_* or ~/.config/adjudicate/config.toml, else local Ollama; ollama: local Ollama only; none: no model, so tier 2's fixes are listed for review, tier 3 is skipped and commas are not checked (default: %(default)s)")
+    p.add_argument("--url", metavar="URL",
+                   help="OpenAI-compatible base URL ending in /v1; overrides every configured "
+                        "url. A --url or PROOFIX_LLM_URL drops keys set in lower layers; set "
+                        "PROOFIX_LLM_KEY (or api_key_env in the same config file) alongside it")
+    p.add_argument("--model", metavar="NAME")
+    p.add_argument("--min-confidence", type=float, default=0.8, metavar="X")
+    p.add_argument("--parallel", type=int, default=4, metavar="N")
+    p.add_argument("--timeout", type=positive_seconds, default=None, metavar="SEC", help="seconds per model request (default: 120, or timeout in config.toml)")
+    c = p.add_argument_group("configuration", "set up or check the model endpoint, then exit")
+    c.add_argument("--setup", action="store_true",
+                   help="choose a model endpoint interactively, test it, and save it to "
+                        "~/.config/adjudicate/config.toml or ~/.config/proofix/config.toml")
+    c.add_argument("--check-endpoint", action="store_true",
+                   help="show the endpoint proofix would use and where each setting comes "
+                        "from, then test it; exit 0 if it answers, 1 if not, 2 on a config error")
+    p.add_argument("--cache", type=Path, default=Path(".proofix/cache.json"), metavar="FILE")
+    p.add_argument("--no-cache", action="store_true")
+    p.add_argument("--report", type=Path, metavar="FILE", help="default: <output>.report.md")
+    p.add_argument("--no-report", action="store_true")
+    p.add_argument("--dry-run", action="store_true", help="print a diff, write nothing")
+    p.add_argument("--changes", action="store_true", help="print every change to stderr")
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.add_argument("--version", action="version", version=f"proofix {__version__}")
+    return p
+
+
+def load_accept(explicit: Path | None) -> set[str]:
+    cfg = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+    paths = [cfg / "proofix" / "accept.txt", cfg / "stylefix" / "accept.txt",
+             Path(".stylefix") / "accept.txt", Path(".proofix") / "accept.txt"]
+    if explicit:
+        paths.append(explicit)
+    words: set[str] = set()
+    for path in paths:
+        if path.exists():
+            for line in path.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    words.add(line.lower())
+    return words
+
+
+def run_typos(text: str) -> list[Edit]:
+    """Known-misspelling fixes from the `typos` tool, as edits, if installed."""
+    exe = shutil.which("typos")
+    if not exe:
+        return []
+    proc = subprocess.run([exe, "--format", "json", "-"], input=text, capture_output=True, text=True)
+    return typos_edits(text, proc.stdout)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.setup:
+        return run_setup("proofix")
+    if args.check_endpoint:
+        return check_endpoint("proofix", preset=args.llm, url=args.url, model=args.model,
+                              timeout=args.timeout)
+    if args.input is None:
+        parser.error("the following arguments are required: input")
+    if not args.input.exists():
+        print(f"proofix: no such file: {args.input}", file=sys.stderr)
+        return 2
+    output = args.input if args.in_place else (
+        args.output or args.input.with_name(args.input.stem + ".proofed" + (args.input.suffix or ".md")))
+    report_path = args.report or output.with_suffix(output.suffix + ".report.md")
+    text = args.input.read_text(encoding="utf-8")
+    accept = load_accept(args.accept)
+    try:
+        ep = resolve_endpoint("proofix", args.llm, url=args.url, model=args.model,
+                              timeout=args.timeout)
+    except ConfigError as e:
+        print(f"proofix: {e}", file=sys.stderr)
+        return 2
+    if ep is None and args.llm == "auto":
+        print("proofix: no model endpoint found; adjudicated fixes (tier 2) will be listed for "
+              "review, not applied, compounds (tier 3) skipped and commas (tier 4) not checked. "
+              "Run `proofix --setup` to configure one.", file=sys.stderr)
+
+    original = text
+    hygiene_notes: list[str] = []
+    edits: list[Edit] = []
+    if not args.no_hygiene:
+        text, hygiene_notes = hygiene.normalize_text(text)
+        h_edits, h_notes = hygiene.plan(text)
+        edits += h_edits
+        hygiene_notes += [f"L{n.line} {n.message}" for n in h_notes]
+    edits += [] if args.no_typos else run_typos(text)
+    typos_fixed = sum(1 for e in edits if e.source == "typos")
+    decisions = []
+    review = []
+    lt = find_languagetool() if not args.no_lt else None
+    if not args.no_lt and not lt:
+        print("proofix: languagetool not found; skipping its tier 1 fixes and tier 2 "
+              "(brew install languagetool)", file=sys.stderr)
+    # Pass 1: mechanical faults (typos, whitespace, doubled punctuation), applied.
+    if lt:
+        try:
+            matches = run_languagetool(text, args.target, args.lt_level)
+        except LTError as e:
+            print(f"proofix: {e}", file=sys.stderr)
+            return 2
+        edits += partition(text, matches, accept, adjudicate_available=False).edits
+    text, skipped = apply_edits(text, edits)
+    applied = [e for e in edits if e not in skipped]
+    # Pass 2: judgement calls on the cleaned text, so spans no longer collide.
+    if lt:
+        try:
+            matches = run_languagetool(text, args.target, args.lt_level)
+        except LTError as e:
+            print(f"proofix: {e}", file=sys.stderr)
+            return 2
+        part = partition(text, matches, accept, adjudicate_available=ep is not None)
+        edits = [e for e in part.edits if e.source == "MISSING_SPACE"]   # anything pass 1 exposed
+        review = part.review
+    else:
+        from .tiers import Partition
+        part = Partition([], [], [])
+        edits = []
+    if True:
+        if True:
+            if part.items:
+                cache = Cache(None if args.no_cache else args.cache)
+                decisions = adjudicate(ep, f"proofix|{args.target}", part.items, cache,
+                                       parallel=args.parallel, verbose=args.verbose,
+                                       system=system_prompt(TASK.format(variety=VARIETY[args.target])),
+                                       log_name="proofix")
+                for d in decisions:
+                    if d.choice is not None and d.confidence < args.min_confidence:
+                        d.reason, d.choice = f"low confidence ({d.confidence:.2f}): {d.reason}", None
+                    if d.replacement:
+                        edits.append(Edit(d.item.line, d.item.start, d.item.end, d.item.word,
+                                          d.replacement, "adjudicated"))
+        new_text, skipped = apply_edits(text, edits)
+        applied += [e for e in edits if e not in skipped]
+        text = new_text
+    # Pass 3: compounds and consistency, on the text as it now stands.
+    if not args.no_consistency and ep is not None:
+        c_items, groups = consistency.items(text, args.target, args.style)
+        if c_items:
+            cache = Cache(None if args.no_cache else args.cache)
+            c_decisions = adjudicate(ep, f"proofix|{args.target}", c_items, cache,
+                                     parallel=args.parallel, verbose=args.verbose,
+                                     system=system_prompt(TASK.format(variety=VARIETY[args.target])),
+                                     log_name="proofix")
+            c_edits = []
+            for d in c_decisions:
+                if d.choice is not None and d.confidence < args.min_confidence:
+                    d.reason, d.choice = f"low confidence ({d.confidence:.2f}): {d.reason}", None
+                if not d.replacement:
+                    continue
+                for o in groups[d.item.id]:
+                    line = text.count("\n", 0, o.start) + 1
+                    col = o.start - (text.rfind("\n", 0, o.start) + 1) + 1
+                    c_edits.append(Edit(line, col, col + (o.end - o.start) - 1, o.form,
+                                        consistency._recase(o.form, d.replacement.lower()), "adjudicated"))
+            decisions += c_decisions
+            new_text, skipped = apply_edits(text, c_edits)
+            applied += [e for e in c_edits if e not in skipped]
+            text = new_text
+    new_text = text
+
+    comma_results = []
+    if not args.no_commas and args.commas != "none":
+        ccache = CommaCache(None if args.no_cache else args.cache.with_name("commas.json"))
+        cedits, comma_results = correct_commas(new_text, args.target, ep, ccache,
+                                               args.optional_commas, args.min_confidence,
+                                               parallel=args.parallel, verbose=args.verbose,
+                                               gate=args.commas == "gated",
+                                               max_sentences=args.max_sentences)
+        final, cskipped = apply_edits(new_text, cedits)
+        applied += [e for e in cedits if e not in cskipped]
+        new_text = final
+
+    if args.dry_run:
+        sys.stdout.writelines(difflib.unified_diff(
+            original.splitlines(keepends=True), new_text.splitlines(keepends=True),
+            str(args.input), str(output)))
+    else:
+        output.write_text(new_text, encoding="utf-8")
+    log = report.changelog(original, applied, decisions, comma_results, review, typos_fixed,
+                           hygiene_notes)
+    if args.changes or args.verbose:
+        sys.stderr.write(log)
+    if not args.no_report and not args.dry_run:
+        report_path.write_text("# proofix report\n\n```\n" + log + "```\n", encoding="utf-8")
+    n_commas = sum(1 for r in comma_results if r.status == "edit")
+    print(f"proofix: {len(applied)} edit(s) ({n_commas} comma sentence(s)), "
+          f"{sum(1 for d in decisions if d.choice is None)} undecided, {len(review)} for review"
+          + ("" if args.dry_run else f" -> {output}"), file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

proofix/commas.py

@@ -0,0 +1,325 @@
+"""Constrained rewrite tier: the model corrects comma placement sentence by
+sentence, and a diff guard admits only insertions and deletions of commas.
+Anything else the model returns is rejected and reported."""
+
+from __future__ import annotations
+
+import difflib
+import hashlib
+import json
+import re
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from adjudicate import FENCE, FRONT_MATTER, Edit, Endpoint, LLMError, protected_spans, strip_thinking
+
+VARIETY = {"us": "American English", "uk": "British English"}
+
+SYSTEM = """You are a copy editor checking comma placement only, in {variety}.
+For each numbered sentence, decide whether a comma is missing or misplaced. You may ONLY insert or delete commas.
+Never change, add, or remove any other character, including other punctuation and spacing.
+{optional}
+Never add or remove a serial (Oxford) comma before the last item of a list; that is a style choice made elsewhere.
+Do not "fix" a comma splice by changing punctuation; instead list it under "notes".
+Return ONLY the sentences you changed. Respond with JSON only:
+{{"changed": [{{"id": 1, "text": "<corrected sentence>", "confidence": 0.0, "reason": "<under 12 words>"}}],
+ "notes": [{{"id": 2, "reason": "<e.g. comma splice; needs a semicolon or period>"}}]}}"""
+
+OPTIONAL = {
+    "leave": "Where a comma is optional by convention (after a short introductory phrase, before "
+             "a short final clause), leave the sentence unchanged.",
+    "add": "Where a comma is optional by convention, add it: this style guide prefers commas "
+           "after introductory phrases and before coordinating conjunctions joining clauses.",
+}
+
+_SENT_END = re.compile(r"(?<=[.!?])[\"”’)]*\s+(?=[A-Z“\"(])")
+_MD_LINE = re.compile(r"^(\s*(?:#{1,6}\s|[-*+]\s|\d+[.)]\s|>\s?|\|))")
+
+# The gate: a sentence goes to the model only if a comma question can arise.
+_OPENER = re.compile(r"^(?:After|Although|As|Because|Before|By|Despite|During|For|From|If|In|On|Once|"
+                     r"Since|Though|Through|Unless|Until|When|Whenever|Where|Whereas|While|With|Without|"
+                     r"Given|Having|Following|Under|Over|To|At|Like|Unlike|Beyond|Within|Throughout|"
+                     r"According|Instead|Rather|First|Second|Third|Finally|Meanwhile|Today|Yesterday|"
+                     r"Tomorrow|Now|Then|Thus|Hence|So|Yet|But|And|Or|Nor|However|Therefore|Moreover|"
+                     r"Furthermore|Nevertheless|Nonetheless|Consequently|Otherwise|Indeed|Still|Also|"
+                     r"Additionally|Importantly|Notably|Ultimately|Overall)\b")
+_TRIGGER = re.compile(r"\b(?:which|however|therefore|moreover|for example|for instance|such as|including|"
+                      r"e\.g\.|i\.e\.|said|says|asked|replied|added|noted|argued|wrote)\b|[\"“”]", re.I)
+_CLAUSE_JOIN = re.compile(r"\b(?:and|but|so|yet|or|nor)\b", re.I)
+
+
+def needs_check(sentence: str) -> bool:
+    """True if the sentence contains a comma, an introductory opener, a
+    clause-level trigger, or two clauses joined by a conjunction."""
+    if "," in sentence:
+        return True
+    if _OPENER.match(sentence):
+        return True
+    if _TRIGGER.search(sentence):
+        return True
+    words = len(sentence.split())
+    return words >= 12 and bool(_CLAUSE_JOIN.search(sentence))
+
+
+PLACEHOLDER = "⟨…⟩"
+
+
+@dataclass
+class Sentence:
+    start: int                       # absolute offset of the first character
+    end: int
+    text: str                        # what the model sees: protected spans as PLACEHOLDER
+    segments: list[tuple[int, int, int]] = field(default_factory=list)
+    # (display_start, display_end, absolute_start) for each real-text run
+
+    def to_absolute(self, display_pos: int) -> int | None:
+        """Absolute offset for a position in `text`; None inside a placeholder."""
+        for ds, de, a in self.segments:
+            if ds <= display_pos <= de:
+                return a + (display_pos - ds)
+        return None
+
+
+@dataclass
+class CommaResult:
+    sentence: Sentence
+    new_text: str | None        # None = unchanged / no answer
+    confidence: float
+    reason: str
+    status: str                 # unchanged | edit | rejected | low | note | error
+
+
+def _paragraphs(text: str):
+    """(start, end) of paragraphs outside front matter and fenced code."""
+    blocked = []
+    m = FRONT_MATTER.match(text)
+    if m:
+        blocked.append((0, m.end()))
+    blocked += [m.span() for m in FENCE.finditer(text)]
+    cursor = 0
+    for bs, be in sorted(blocked):
+        if bs > cursor:
+            yield from _split_paras(text, cursor, bs)
+        cursor = be
+    if cursor < len(text):
+        yield from _split_paras(text, cursor, len(text))
+
+
+def _split_paras(text: str, lo: int, hi: int):
+    for pm in re.finditer(r"[^\n]+(?:\n[^\n]+)*", text[lo:hi]):
+        yield lo + pm.start(), lo + pm.end()
+
+
+def _display(text: str, a: int, b: int, spans: list[tuple[int, int]]) -> tuple[str, list[tuple[int, int, int]]]:
+    """Text of [a, b) with protected spans replaced by PLACEHOLDER, plus the
+    segment map back to absolute offsets."""
+    out, segs, cursor = [], [], a
+    dpos = 0
+    for s_, e_ in spans:
+        if e_ <= a or s_ >= b:
+            continue
+        s_, e_ = max(s_, a), min(e_, b)
+        if s_ > cursor:
+            piece = text[cursor:s_]
+            segs.append((dpos, dpos + len(piece), cursor))
+            out.append(piece); dpos += len(piece)
+        out.append(PLACEHOLDER); dpos += len(PLACEHOLDER)
+        cursor = e_
+    if cursor < b:
+        piece = text[cursor:b]
+        segs.append((dpos, dpos + len(piece), cursor))
+        out.append(piece)
+    return "".join(out), segs
+
+
+def sentences(text: str, min_words: int = 4, gate: bool = True) -> list[Sentence]:
+    """Sentences in prose, excluding table rows and headings, with protected
+    spans (code, link targets, URLs, HTML) shown as a placeholder so a link
+    does not split its sentence. With gate, only sentences where a comma
+    question can arise."""
+    spans = protected_spans(text)
+    out: list[Sentence] = []
+    for ps, pe in _paragraphs(text):
+        first = text[ps:pe].split("\n", 1)[0]
+        if first.lstrip().startswith(("#", "|")):
+            continue
+        display, segs = _display(text, ps, pe, spans)
+        cursor = 0
+        pieces = []
+        for m in _SENT_END.finditer(display):
+            pieces.append((cursor, m.start() + len(m.group(0).rstrip())))
+            cursor = m.end()
+        pieces.append((cursor, len(display)))
+        for a, b in pieces:
+            raw = display[a:b]
+            lead = len(raw) - len(raw.lstrip())
+            body = raw.strip()
+            if not body:
+                continue
+            words = len(body.replace(PLACEHOLDER, "").split())
+            if words < min_words or (gate and not needs_check(body)):
+                continue
+            da, db = a + lead, a + lead + len(body)
+            # segments clipped to this sentence, re-based to its display text
+            fixed = []
+            for ds, de, ab in [(ds - da, de - da, ab) for ds, de, ab in segs if de > da and ds < db]:
+                clip = max(ds, 0)
+                fixed.append((clip, min(de, len(body)), ab + (clip - ds)))
+            abs_start = fixed[0][2] if fixed else ps
+            abs_end = fixed[-1][2] + (fixed[-1][1] - fixed[-1][0]) if fixed else ps
+            out.append(Sentence(abs_start, abs_end, body, fixed))
+    return out
+
+
+def only_commas(a: str, b: str) -> bool:
+    for op, i1, i2, j1, j2 in difflib.SequenceMatcher(None, a, b, autojunk=False).get_opcodes():
+        if op == "equal":
+            continue
+        if set(a[i1:i2] + b[j1:j2]) - {","}:
+            return False
+    return True
+
+
+def comma_edits(text: str, s: Sentence, new: str) -> list[Edit]:
+    """Edits (line, col based) turning s.text into new; only comma changes.
+    Returns [] if any change falls inside a placeholder."""
+    edits = []
+    for op, i1, i2, j1, j2 in difflib.SequenceMatcher(None, s.text, new, autojunk=False).get_opcodes():
+        if op == "equal":
+            continue
+        pos = s.to_absolute(i1)
+        if pos is None or (i2 > i1 and s.to_absolute(i2) is None):
+            return []
+        original, repl = s.text[i1:i2], new[j1:j2]
+        if original and text[pos:pos + len(original)] != original:
+            return []
+        line = text.count("\n", 0, pos) + 1
+        col = pos - (text.rfind("\n", 0, pos) + 1) + 1
+        edits.append(Edit(line, col, col + len(original) - 1, original, repl, "commas"))
+    return edits
+
+
+class CommaCache:
+    def __init__(self, path: Path | None):
+        self.path, self.data = path, {}
+        if path and path.exists():
+            try:
+                self.data = json.loads(path.read_text())
+            except json.JSONDecodeError:
+                self.data = {}
+
+    @staticmethod
+    def key(scope: str, sentence: str) -> str:
+        return hashlib.sha256(f"commas|{scope}|{sentence.strip()}".encode()).hexdigest()[:24]
+
+    def save(self):
+        if self.path:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(json.dumps(self.data, indent=1, ensure_ascii=False))
+
+
+def _ask(ep: Endpoint, system: str, batch: list[Sentence]) -> dict[int, dict] | None:
+    """{id: {"text", "confidence", "reason"} or {"note": reason}}; None on a bad reply."""
+    user = "\n".join(f"{i + 1}. {s.text}" for i, s in enumerate(batch))
+    reply = strip_thinking(ep.chat(system, user))
+    m = re.search(r"\{.*\}", reply, re.S)
+    if not m:
+        return None
+    try:
+        data = json.loads(m.group(0))
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    out: dict[int, dict] = {}
+    for d in data.get("changed") or data.get("sentences") or []:
+        try:
+            out[int(d["id"])] = d
+        except (KeyError, TypeError, ValueError):
+            continue
+    for d in data.get("notes") or []:
+        try:
+            out.setdefault(int(d["id"]), {"note": str(d.get("reason", ""))})
+        except (KeyError, TypeError, ValueError):
+            continue
+    return out
+
+
+def correct_commas(text: str, target: str, ep: Endpoint | None, cache: CommaCache,
+                   optional: str = "leave", min_confidence: float = 0.8, batch_size: int = 15,
+                   parallel: int = 4, verbose: bool = False, gate: bool = True,
+                   max_sentences: int | None = None) -> tuple[list[Edit], list[CommaResult]]:
+    sents = sentences(text, gate=gate)
+    if max_sentences is not None:
+        sents = sents[:max_sentences]
+    scope = f"{target}|{optional}"
+    results: dict[int, CommaResult] = {}
+    todo: list[tuple[int, Sentence]] = []
+    for i, s in enumerate(sents):
+        hit = cache.data.get(CommaCache.key(scope, s.text))
+        if hit is not None:
+            new = hit.get("text")
+            results[i] = CommaResult(s, new if new and new != s.text else None,
+                                     float(hit.get("confidence", 1.0)), hit.get("reason", "") + " (cached)",
+                                     "edit" if new and new != s.text else "unchanged")
+        else:
+            todo.append((i, s))
+    if todo and ep is not None:
+        system = SYSTEM.format(variety=VARIETY[target], optional=OPTIONAL[optional])
+        batches = [todo[k:k + batch_size] for k in range(0, len(todo), batch_size)]
+        if verbose:
+            print(f"proofix: checking commas in {len(todo)} sentence(s), {len(batches)} batch(es)",
+                  file=sys.stderr)
+
+        def run(batch):
+            try:
+                return batch, _ask(ep, system, [s for _, s in batch])
+            except LLMError as e:
+                return batch, {"error": str(e)}
+
+        with ThreadPoolExecutor(max_workers=max(1, parallel)) as pool:
+            for batch, answers in pool.map(run, batches):
+                for n, (i, s) in enumerate(batch, 1):
+                    if answers is None or "error" in answers:
+                        why = answers["error"] if answers else "unparseable reply"
+                        results[i] = CommaResult(s, None, 0.0, f"model error: {why}", "error")
+                        continue
+                    a = answers.get(n)
+                    if a is None:                      # not listed: unchanged
+                        results[i] = CommaResult(s, None, 1.0, "", "unchanged")
+                        cache.data[CommaCache.key(scope, s.text)] = {"text": s.text, "confidence": 1.0, "reason": ""}
+                        continue
+                    if "note" in a:
+                        results[i] = CommaResult(s, None, 0.0, a["note"], "note")
+                        continue
+                    if not isinstance(a.get("text"), str):
+                        results[i] = CommaResult(s, None, 0.0, "malformed answer", "error")
+                        continue
+                    new = a["text"].strip()
+                    try:
+                        conf = float(a.get("confidence", 0))
+                    except (TypeError, ValueError):
+                        conf = 0.0
+                    reason = str(a.get("reason", ""))[:160]
+                    if new == s.text:
+                        results[i] = CommaResult(s, None, conf, reason, "unchanged")
+                        cache.data[CommaCache.key(scope, s.text)] = {"text": s.text, "confidence": conf, "reason": reason}
+                    elif not only_commas(s.text, new):
+                        results[i] = CommaResult(s, new, conf, reason, "rejected")
+                    elif conf < min_confidence:
+                        results[i] = CommaResult(s, new, conf, reason, "low")
+                    else:
+                        results[i] = CommaResult(s, new, conf, reason, "edit")
+                        cache.data[CommaCache.key(scope, s.text)] = {"text": new, "confidence": conf, "reason": reason}
+        cache.save()
+    elif todo:
+        for i, s in todo:
+            results[i] = CommaResult(s, None, 0.0, "no model configured", "error")
+    ordered = [results[i] for i in range(len(sents)) if i in results]
+    edits = []
+    for r in ordered:
+        if r.status == "edit" and r.new_text:
+            edits.extend(comma_edits(text, r.sentence, r.new_text))
+    return edits, ordered