adjudicate 0.3.0__tar.gz

adjudicate-0.3.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/

adjudicate-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Brož
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adjudicate-0.3.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: adjudicate
+Version: 0.3.0
+Summary: Bounded, auditable text edits chosen by a language model: detector proposes, model picks, applier splices.
+Project-URL: Homepage, https://github.com/AndrewBroz/adjudicate
+Project-URL: Issues, https://github.com/AndrewBroz/adjudicate/issues
+Author: Andrew Brož
+License-Expression: MIT AND LGPL-2.0-or-later AND LicenseRef-SCOWL
+License-File: LICENSE
+License-File: adjudicate/dict/LICENSE-en_GB.txt
+License-File: adjudicate/dict/LICENSE-en_US.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: spylls>=0.1.7
+Description-Content-Type: text/markdown
+
+# adjudicate
+
+A small library for one pattern: a detector proposes a span in a document
+and a short list of candidate replacements; a local language model picks
+one of them, or KEEP, from the surrounding sentence and a rule of thumb;
+the applier splices the choice in with case preserved. Every change is a
+bounded, logged, reasoned edit. The model never rewrites prose.
+
+It is the toolkit behind [stylefix](https://github.com/AndrewBroz/stylefix)
+(US/UK spelling and style) and [proofix](https://github.com/AndrewBroz/proofix)
+(typos, punctuation, commas). It is published because they depend on it; the
+API may change between 0.x releases.
+
+```
+pip install adjudicate
+```
+
+Modules: `llm` (OpenAI-compatible client and endpoint resolution), `core`
+(Item, Decision, Cache, `adjudicate`), `apply` (Edit, `apply_edits`),
+`context` (sentence context, Markdown prose regions), `dictionary`
+(Hunspell lookups over the bundled en_US and en_GB dictionaries), `setup`
+(`run_setup` and `check_endpoint`, behind the tools' `--setup` and
+`--check-endpoint`).
+
+## Choosing the model endpoint
+
+`resolve_endpoint(app, preset="auto", url=None, model=None, key=None,
+think=False, timeout=None)` merges settings from, highest first:
+
+1. its arguments (the calling tool's `--url`, `--model`, `--timeout`)
+2. `<APP>_LLM_URL`, `<APP>_LLM_MODEL`, `<APP>_LLM_KEY`, e.g. `STYLEFIX_LLM_URL`
+3. `~/.config/<app>/config.toml`
+4. `ADJUDICATE_LLM_URL`, `ADJUDICATE_LLM_MODEL`, `ADJUDICATE_LLM_KEY`
+5. `~/.config/adjudicate/config.toml`, shared by every tool
+
+(`$XDG_CONFIG_HOME` replaces `~/.config` when set.) Layers merge field by
+field, except that a layer naming a `url` drops the `model`, key and
+`thinking_switch` of the layers below it, since those described another
+server. With no `url` anywhere, a local Ollama is used if it is running with
+a model pulled; otherwise there is no model and callers fall back to
+listing items for review.
+
+```toml
+[llm]
+url = "https://api.example.com/v1"   # any OpenAI-compatible base URL
+model = "some-model"                  # optional: the server's first listed model
+api_key_env = "EXAMPLE_API_KEY"       # or api_key = "..."; not both
+timeout = 120                         # seconds per request
+thinking_switch = false               # true for vLLM/LiteLLM serving a reasoning model
+```
+
+`thinking_switch = true` sends `chat_template_kwargs: {enable_thinking:
+false}`, which vLLM honours and strict APIs reject; if a server answers 400
+or 422 to it, it is dropped for the rest of the run. Unknown keys, wrong
+types, empty strings, a `timeout` that is not positive, and an
+`api_key_env` naming an unset variable are errors (`ConfigError`), so a typo
+is never silently ignored. An `api_key_env` is read only if it survives the
+merge: a higher layer's `url` or key discards it first.
+
+## License
+
+The code is MIT (see `LICENSE`). The dictionaries in `adjudicate/dict/`
+keep their own licenses: en_US under the SCOWL notice in
+`LICENSE-en_US.txt`, en_GB under the LGPL as stated in `LICENSE-en_GB.txt`.

adjudicate-0.3.0/README.md

@@ -0,0 +1,64 @@
+# adjudicate
+
+A small library for one pattern: a detector proposes a span in a document
+and a short list of candidate replacements; a local language model picks
+one of them, or KEEP, from the surrounding sentence and a rule of thumb;
+the applier splices the choice in with case preserved. Every change is a
+bounded, logged, reasoned edit. The model never rewrites prose.
+
+It is the toolkit behind [stylefix](https://github.com/AndrewBroz/stylefix)
+(US/UK spelling and style) and [proofix](https://github.com/AndrewBroz/proofix)
+(typos, punctuation, commas). It is published because they depend on it; the
+API may change between 0.x releases.
+
+```
+pip install adjudicate
+```
+
+Modules: `llm` (OpenAI-compatible client and endpoint resolution), `core`
+(Item, Decision, Cache, `adjudicate`), `apply` (Edit, `apply_edits`),
+`context` (sentence context, Markdown prose regions), `dictionary`
+(Hunspell lookups over the bundled en_US and en_GB dictionaries), `setup`
+(`run_setup` and `check_endpoint`, behind the tools' `--setup` and
+`--check-endpoint`).
+
+## Choosing the model endpoint
+
+`resolve_endpoint(app, preset="auto", url=None, model=None, key=None,
+think=False, timeout=None)` merges settings from, highest first:
+
+1. its arguments (the calling tool's `--url`, `--model`, `--timeout`)
+2. `<APP>_LLM_URL`, `<APP>_LLM_MODEL`, `<APP>_LLM_KEY`, e.g. `STYLEFIX_LLM_URL`
+3. `~/.config/<app>/config.toml`
+4. `ADJUDICATE_LLM_URL`, `ADJUDICATE_LLM_MODEL`, `ADJUDICATE_LLM_KEY`
+5. `~/.config/adjudicate/config.toml`, shared by every tool
+
+(`$XDG_CONFIG_HOME` replaces `~/.config` when set.) Layers merge field by
+field, except that a layer naming a `url` drops the `model`, key and
+`thinking_switch` of the layers below it, since those described another
+server. With no `url` anywhere, a local Ollama is used if it is running with
+a model pulled; otherwise there is no model and callers fall back to
+listing items for review.
+
+```toml
+[llm]
+url = "https://api.example.com/v1"   # any OpenAI-compatible base URL
+model = "some-model"                  # optional: the server's first listed model
+api_key_env = "EXAMPLE_API_KEY"       # or api_key = "..."; not both
+timeout = 120                         # seconds per request
+thinking_switch = false               # true for vLLM/LiteLLM serving a reasoning model
+```
+
+`thinking_switch = true` sends `chat_template_kwargs: {enable_thinking:
+false}`, which vLLM honours and strict APIs reject; if a server answers 400
+or 422 to it, it is dropped for the rest of the run. Unknown keys, wrong
+types, empty strings, a `timeout` that is not positive, and an
+`api_key_env` naming an unset variable are errors (`ConfigError`), so a typo
+is never silently ignored. An `api_key_env` is read only if it survives the
+merge: a higher layer's `url` or key discards it first.
+
+## License
+
+The code is MIT (see `LICENSE`). The dictionaries in `adjudicate/dict/`
+keep their own licenses: en_US under the SCOWL notice in
+`LICENSE-en_US.txt`, en_GB under the LGPL as stated in `LICENSE-en_GB.txt`.

adjudicate-0.3.0/adjudicate/__init__.py

@@ -0,0 +1,18 @@
+"""adjudicate: bounded, auditable text edits chosen by a language model.
+
+A detector proposes a span and a short list of candidate replacements; the
+model picks one (or KEEP) from the sentence and a rule of thumb; the applier
+splices the choice in. The toolkit behind stylefix and proofix.
+"""
+
+from .apply import Edit, apply_edits, line_offsets, match_case, to_offsets  # noqa: F401
+from .context import (FENCE, FRONT_MATTER, HTML_ENTITY, at_sentence_start,  # noqa: F401
+                      inside_quotes, map_prose, paragraph_bounds,
+                      prose_regions, protected_spans, sentence_context)
+from .core import (Cache, Decision, Item, adjudicate, decide_batch, parse_response,  # noqa: F401
+                   render_batch, system_prompt, DEFAULT_KEEP_RULE, match_choice)
+from .llm import ConfigError, Endpoint, LLMError, resolve_endpoint, strip_thinking  # noqa: F401
+from .setup import check_endpoint, run_setup  # noqa: F401
+from .dictionary import known, known_anywhere  # noqa: F401
+
+__version__ = "0.3.0"

adjudicate-0.3.0/adjudicate/apply.py

@@ -0,0 +1,71 @@
+"""Splice replacements into text at Vale's (line, span) positions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Edit:
+    line: int      # 1-indexed
+    start: int     # 1-indexed inclusive column
+    end: int       # 1-indexed inclusive column
+    original: str
+    replacement: str
+    source: str    # check name or "adjudicated"
+
+
+def match_case(original: str, replacement: str) -> str:
+    """Give `replacement` the casing pattern of `original`, unless the
+    replacement is already deliberately cased (it contains a capital), as
+    with abbreviations and names: "US" -> "United States", not "UNITED
+    STATES"; "us" -> "U.S." stays "U.S."."""
+    if any(ch.isupper() for ch in replacement):
+        return replacement
+    if original.isupper() and len(original) > 1:
+        return replacement.upper()
+    if original[:1].isupper():
+        return replacement[:1].upper() + replacement[1:]
+    return replacement
+
+
+def line_offsets(text: str) -> list[int]:
+    """Absolute offset of the start of each line (index 0 = line 1)."""
+    offsets = [0]
+    for i, ch in enumerate(text):
+        if ch == "\n":
+            offsets.append(i + 1)
+    return offsets
+
+
+def to_offsets(text: str, edit: Edit) -> tuple[int, int]:
+    starts = line_offsets(text)
+    base = starts[edit.line - 1]
+    return base + edit.start - 1, base + edit.end
+
+
+def apply_edits(text: str, edits: list[Edit]) -> tuple[str, list[Edit]]:
+    """Apply edits whose span still contains the expected original text.
+
+    Returns the new text and the edits that were skipped because the text
+    at their position no longer matched.
+    """
+    skipped: list[Edit] = []
+    spans = []
+    for e in edits:
+        s, t = to_offsets(text, e)
+        if text[s:t] != e.original:
+            skipped.append(e)
+            continue
+        spans.append((s, t, e))
+    # Apply from the end so earlier offsets stay valid; drop overlaps.
+    spans.sort(key=lambda x: (x[0], x[1]), reverse=True)
+    out = text
+    last_start = len(text) + 1
+    for s, t, e in spans:
+        if t > last_start:
+            skipped.append(e)
+            continue
+        out = out[:s] + match_case(e.original, e.replacement) + out[t:]
+        last_start = s
+    return out, skipped

adjudicate-0.3.0/adjudicate/context.py

@@ -0,0 +1,139 @@
+"""Sentence context, position heuristics, and Markdown prose regions."""
+
+from __future__ import annotations
+
+import re
+
+from dataclasses import dataclass  # noqa: F401
+
+FENCE = re.compile(r"^(```|~~~)[^\n]*\n.*?^\1[ \t]*$", re.M | re.S)
+_INLINE_CODE = re.compile(r"(`+)[^`\n]*?\1")
+_LINK_DEST = re.compile(r"\]\([^)\s]*(?:\s+\"[^\"]*\")?\)")
+_URL = re.compile(r"<?(?:https?|ftp|mailto):[^\s>)]+>?")
+FRONT_MATTER = re.compile(r"\A---\n.*?\n---\n", re.S)
+_HTML_COMMENT = re.compile(r"<!--.*?-->", re.S)
+_HTML_TAG = re.compile(r"</?[A-Za-z][^<>\n]*>")
+HTML_ENTITY = re.compile(r"&(?:#\d+|#x[0-9A-Fa-f]+|[A-Za-z][A-Za-z0-9]*);")
+
+# Pre-0.3 names, kept so an old consumer does not break mid-upgrade; removed in 0.4.
+_FENCE, _FRONT, _HTML_ENTITY = FENCE, FRONT_MATTER, HTML_ENTITY
+
+
+@dataclass
+class _Unused:
+    quotes: int = 0
+    apostrophes: int = 0
+    dashes: int = 0
+    ranges: int = 0
+    dates: int = 0
+    punctuation_moved: int = 0
+
+    def as_dict(self) -> dict[str, int]:
+        return {k: v for k, v in self.__dict__.items() if v}
+
+
+def protected_spans(text: str, entities: bool = True) -> list[tuple[int, int]]:
+    """Spans no tool should edit: front matter, fenced and inline code, link
+    targets, URLs, HTML comments and tags, and (unless entities=False) HTML
+    entities."""
+    spans = []
+    m = FRONT_MATTER.match(text)
+    if m:
+        spans.append((0, m.end()))
+    rxs = [FENCE, _INLINE_CODE, _LINK_DEST, _URL, _HTML_COMMENT, _HTML_TAG]
+    if entities:
+        rxs.append(HTML_ENTITY)
+    for rx in rxs:
+        spans.extend(m.span() for m in rx.finditer(text))
+    spans.sort()
+    merged: list[tuple[int, int]] = []
+    for s, e in spans:
+        if merged and s <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], e))
+        else:
+            merged.append((s, e))
+    return merged
+
+
+def prose_regions(text: str) -> list[tuple[int, int]]:
+    regions, cursor = [], 0
+    for s, e in protected_spans(text):
+        if s > cursor:
+            regions.append((cursor, s))
+        cursor = e
+    if cursor < len(text):
+        regions.append((cursor, len(text)))
+    return regions
+
+
+def map_prose(text: str, fn) -> str:
+    out, cursor = [], 0
+    for s, e in prose_regions(text):
+        out.append(text[cursor:s])
+        out.append(fn(text[s:e]))
+        cursor = e
+    out.append(text[cursor:])
+    return "".join(out)
+
+
+
+_SENT_END = re.compile(r"(?<=[.!?])\s+")
+
+
+def paragraph_bounds(text: str, pos: int) -> tuple[int, int]:
+    start = text.rfind("\n\n", 0, pos)
+    start = 0 if start < 0 else start + 2
+    end = text.find("\n\n", pos)
+    end = len(text) if end < 0 else end
+    return start, end
+
+
+def sentence_context(text: str, start: int, end: int, radius: int = 1,
+                     max_chars: int = 400) -> str:
+    """The sentence containing [start, end) plus `radius` neighbours, with
+    the target span marked as [[...]]."""
+    ps, pe = paragraph_bounds(text, start)
+    para = text[ps:pe]
+    rel_s, rel_e = start - ps, end - ps
+    pieces, cursor = [], 0
+    for m in _SENT_END.finditer(para):
+        pieces.append((cursor, m.start()))
+        cursor = m.end()
+    pieces.append((cursor, len(para)))
+    idx = next((i for i, (a, b) in enumerate(pieces) if a <= rel_s < b), len(pieces) - 1)
+    lo = pieces[max(0, idx - radius)][0]
+    hi = pieces[min(len(pieces) - 1, idx + radius)][1]
+    snippet = para[lo:rel_s] + "[[" + para[rel_s:rel_e] + "]]" + para[rel_e:hi]
+    snippet = re.sub(r"\s+", " ", snippet).strip()
+    if len(snippet) > max_chars:
+        mark = snippet.find("[[")
+        a = max(0, mark - max_chars // 2)
+        snippet = ("…" if a else "") + snippet[a:a + max_chars] + "…"
+    return snippet
+
+
+# Brackets are not sentence starts: "[Center for X](url)" and "(Centre for Y)"
+# keep their capital because of the name, so the word is adjudicated.
+_SENTENCE_START_PUNCT = set('.!?:"“‘\'')
+
+
+def at_sentence_start(text: str, pos: int) -> bool:
+    """True when a capital at `pos` is explained by position, not by being a name."""
+    line_start = text.rfind("\n", 0, pos) + 1
+    before = text[line_start:pos].rstrip()
+    if not before:
+        return True
+    # Markdown markers: headings, list bullets, numbered items, blockquotes.
+    if re.fullmatch(r"(#{1,6}|[-*+]|\d+[.)]|>|\|)", before):
+        return True
+    return before[-1] in _SENTENCE_START_PUNCT
+
+
+def inside_quotes(text: str, pos: int) -> bool:
+    """Cheap check: an odd number of opening quotes precede `pos` in the paragraph."""
+    ps, _ = paragraph_bounds(text, pos)
+    seg = text[ps:pos]
+    opens = seg.count("“") + seg.count("‘") + len(re.findall(r'(?:^|\s)["\']', seg))
+    # `seg` ends where the word starts, so a quote at its very end is an opener.
+    closes = seg.count("”") + seg.count("’") + len(re.findall(r'["\'](?=[\s.,;:!?)])', seg))
+    return opens > closes

adjudicate-0.3.0/adjudicate/core.py

@@ -0,0 +1,206 @@
+"""Ask a model to choose between supplied candidates for marked spans.
+
+The contract: each item carries a short list of options (the last usually
+KEEP), a rule of thumb, and the sentence with the span marked [[...]].
+The model picks one option per item. Anything else is rejected."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+from .llm import Endpoint, LLMError
+
+SYSTEM_TEMPLATE = """{task}
+For each item, choose exactly one option from its numbered list. {keep_rule}
+Answer with the option's number (or the word KEEP); never retype or paraphrase the option text.
+Respond with JSON only, in this shape:
+{{"decisions": [{{"id": 1, "choice": "<option number, or KEEP>", "confidence": 0.0, "reason": "<under 12 words>"}}]}}"""
+
+DEFAULT_KEEP_RULE = ("Choose KEEP when the marked text is already correct in context, is part of a "
+                     "proper name, a title, a quotation, a URL or code, or when no option fits.")
+
+
+def system_prompt(task: str, keep_rule: str = DEFAULT_KEEP_RULE) -> str:
+    return SYSTEM_TEMPLATE.format(task=task, keep_rule=keep_rule)
+
+
+@dataclass
+class Item:
+    id: int
+    word: str
+    options: tuple[str, ...]
+    rule: str
+    context: str
+    line: int
+    start: int
+    end: int
+    source: str = "ambiguous"     # caller-defined tag for reporting
+
+
+@dataclass
+class Decision:
+    item: Item
+    choice: str | None            # None = could not decide
+    confidence: float
+    reason: str
+    cached: bool = False
+
+    @property
+    def replacement(self) -> str | None:
+        """The text to substitute, or None to leave the word alone."""
+        if self.choice is None or self.choice == "KEEP":
+            return None
+        if self.choice.lower() == self.item.word.lower():
+            return None
+        return self.choice
+
+
+class Cache:
+    def __init__(self, path: Path | None):
+        self.path = path
+        self.data: dict[str, dict] = {}
+        if path and path.exists():
+            try:
+                self.data = json.loads(path.read_text())
+            except json.JSONDecodeError:
+                self.data = {}
+
+    @staticmethod
+    def key(scope: str, item: Item) -> str:
+        """scope: anything that changes the right answer (target variety, task)."""
+        norm = re.sub(r"\s+", " ", item.context).strip().lower()
+        h = hashlib.sha256(f"{scope}|{item.word.lower()}|{'|'.join(item.options)}|{norm}".encode()).hexdigest()
+        return h[:24]
+
+    def get(self, k: str) -> dict | None:
+        return self.data.get(k)
+
+    def put(self, k: str, d: Decision) -> None:
+        self.data[k] = {"word": d.item.word, "choice": d.choice,
+                        "confidence": d.confidence, "reason": d.reason,
+                        "context": d.item.context}
+
+    def save(self) -> None:
+        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 render_batch(items: list[Item]) -> str:
+    parts = []
+    for it in items:
+        opts = " | ".join(o if o == "KEEP" else f"[{n}] {o}" for n, o in enumerate(it.options, 1))
+        parts.append(
+            f"Item {it.id} — word: \"{it.word}\" — options: {opts}\n"
+            f"Rule: {it.rule}\n"
+            f"Context: {it.context}")
+    return "\n\n".join(parts)
+
+
+def match_choice(choice: str, options: tuple[str, ...]) -> str | None:
+    """Resolve the model's answer to one option: by number ("2", "[2]"),
+    by the word KEEP, or by the option text (trimmed, case-insensitive)."""
+    c = str(choice).strip()
+    m = re.fullmatch(r"\[?(\d+)\]?", c)
+    if m:
+        n = int(m.group(1))
+        return options[n - 1] if 1 <= n <= len(options) else None
+    if c.upper() == "KEEP" and "KEEP" in options:
+        return "KEEP"
+    c = re.sub(r"^\[\d+\]\s*", "", c)
+    return next((o for o in options if o.strip().lower() == c.lower()), None)
+
+
+def parse_response(text: str) -> dict[int, dict]:
+    """Return {id: {choice, confidence, reason}} from the model's reply."""
+    text = text.strip()
+    text = re.sub(r"^```(?:json)?\s*|\s*```$", "", text, flags=re.S)
+    m = re.search(r"[\[{]", text)
+    if not m:
+        return {}
+    try:
+        data = json.loads(text[m.start():])
+    except json.JSONDecodeError:
+        # Try to salvage the largest balanced object.
+        end = max(text.rfind("}"), text.rfind("]"))
+        try:
+            data = json.loads(text[m.start():end + 1])
+        except json.JSONDecodeError:
+            return {}
+    if isinstance(data, dict):
+        data = data.get("decisions", data.get("items", []))
+    out = {}
+    for d in data if isinstance(data, list) else []:
+        if isinstance(d, dict) and "id" in d:
+            try:
+                out[int(d["id"])] = d
+            except (TypeError, ValueError):
+                continue
+    return out
+
+
+def decide_batch(ep: Endpoint, system: str, items: list[Item]) -> list[Decision]:
+    try:
+        reply = ep.chat(system, render_batch(items))
+    except LLMError as e:
+        return [Decision(it, None, 0.0, f"model error: {e}") for it in items]
+    answers = parse_response(reply)
+    out = []
+    for it in items:
+        a = answers.get(it.id)
+        if not a:
+            out.append(Decision(it, None, 0.0, "no answer from model"))
+            continue
+        choice = str(a.get("choice", "")).strip()
+        matched = match_choice(choice, it.options)
+        try:
+            conf = float(a.get("confidence", 0))
+        except (TypeError, ValueError):
+            conf = 0.0
+        reason = str(a.get("reason", ""))[:200]
+        if matched is None:
+            out.append(Decision(it, None, 0.0, f"invalid choice {choice!r}"))
+        else:
+            out.append(Decision(it, matched, conf, reason))
+    return out
+
+
+def adjudicate(ep: Endpoint | None, scope: str, items: list[Item], cache: Cache,
+               batch_size: int = 20, parallel: int = 4, verbose: bool = False,
+               system: str | None = None, log_name: str = "adjudicate") -> list[Decision]:
+    """Decide every item: from cache where possible, otherwise from the model
+    in parallel batches. `scope` keys the cache; `system` is the task prompt
+    (see system_prompt)."""
+    system = system or system_prompt("You are a meticulous copy editor.")
+    decisions: dict[int, Decision] = {}
+    todo: list[Item] = []
+    for it in items:
+        k = Cache.key(scope, it)
+        hit = cache.get(k)
+        if hit and hit.get("choice") in it.options:
+            decisions[it.id] = Decision(it, hit["choice"], float(hit.get("confidence", 1.0)),
+                                        hit.get("reason", ""), cached=True)
+        else:
+            todo.append(it)
+    if todo and ep is None:
+        for it in todo:
+            decisions[it.id] = Decision(it, None, 0.0, "no model configured")
+    elif todo:
+        batches = [todo[i:i + batch_size] for i in range(0, len(todo), batch_size)]
+        if verbose:
+            print(f"{log_name}: asking {ep.name} ({ep.model}) about {len(todo)} items "
+                  f"in {len(batches)} batch(es), {parallel} in parallel", file=sys.stderr)
+        with ThreadPoolExecutor(max_workers=max(1, parallel)) as pool:
+            for result in pool.map(lambda b: decide_batch(ep, system, b), batches):
+                for d in result:
+                    decisions[d.item.id] = d
+                    if d.choice is not None:
+                        cache.put(Cache.key(scope, d.item), d)
+        cache.save()
+    return [decisions[it.id] for it in items]