stylefix 0.7.0__tar.gz

stylefix-0.7.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.stylefix/
+__pycache__/
+*.egg-info/
+dist/
+*.us.md
+*.uk.md
+*.report.md

stylefix-0.7.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.

stylefix-0.7.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: stylefix
+Version: 0.7.0
+Summary: Regularize a Markdown file to US or UK English and a style guide, using Vale plus a language model for the ambiguous cases.
+Project-URL: Homepage, https://github.com/AndrewBroz/stylefix
+Project-URL: Issues, https://github.com/AndrewBroz/stylefix/issues
+Author: Andrew Brož
+License-Expression: MIT AND LicenseRef-VarCon
+License-File: LICENSE
+License-File: stylefix/dict/README-varcon.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: adjudicate<0.4,>=0.3
+Requires-Dist: spylls>=0.1.7
+Description-Content-Type: text/markdown
+
+# stylefix
+
+Regularize a Markdown file to **US or UK English** and a **style guide**
+(Chicago, Oxford, AP, GPO, APA or Guardian), fully automatically, and locally unless you point it at a hosted model.
+
+```
+stylefix draft.md --target us              # -> draft.us.md + draft.us.md.report.md
+stylefix draft.md --target uk --oxford-ize # UK with Oxford -ize spellings
+stylefix draft.md --target us --dry-run    # print a diff, write nothing
+stylefix draft.md --target us --changes    # list every change as it is made
+```
+
+[Vale](https://vale.sh) decides what to change; a small Python wrapper applies
+the changes. The few words that need judgement (UK *licence*/*license*,
+*programme*/*program*, *cheque*/*check*, ...) are put to a language model as a
+multiple-choice question with the surrounding sentence. The model never
+rewrites prose: it picks one of the options you supply, or KEEP.
+
+## Install
+
+```
+uv tool install stylefix      # or: pipx install stylefix
+```
+
+stylefix also needs [Vale](https://vale.sh/docs/install) on your PATH:
+`brew install vale` on macOS, `choco install vale` on Windows, or a release
+binary from GitHub on Linux. Python 3.11+.
+
+`stylefix --help` gives the full option reference with examples. The man
+page is in the repository at `man/stylefix.1` (`man ./man/stylefix.1`).
+
+## How it works
+
+Every candidate word lands in one of three tiers:
+
+| tier | mechanism | what happens |
+|---|---|---|
+| deterministic | **suffix patterns** confirmed against dictionaries, plus a curated table for the irregular families | applied, case preserved |
+| adjudicated | words with a sense split (licence/license, programme/program), pattern hits whose rewrite is in no dictionary (coinages, names), any hit that is capitalised mid-sentence or inside a quotation, and the style guide's serial-comma and numeral rules | a language model chooses between the candidates and KEEP |
+| review | spellings that look like the other variety but could not be converted; serial-comma and numeral hits when no model is configured | listed in the report and the `--changes` log |
+
+**Two data sources, both from the SCOWL project: VarCon, shipped in
+`stylefix/dict/`, and the Hunspell dictionaries that come with adjudicate.**
+
+- **VarCon** (Variant Conversion Info) is the curated table: about 15,000
+  spellings mapped to their preferred American, British and Oxford forms,
+  with sense annotations. It is the source of the Vale substitution rules,
+  regenerated by `python -m stylefix.wordlist`. Where VarCon says a spelling
+  is *also* a word of its own in the target ("check | verify" alongside
+  "check / cheque | bank"; licence as noun, license as verb), the word is
+  not converted but adjudicated, and VarCon's glosses become the rule of
+  thumb the model reads: "British: 'check' for verify; 'cheque' for bank."
+- **Hunspell dictionaries** (en_US, en_GB, read with the pure-Python
+  `spylls`) confirm the pattern tier. English keeps coining -ize verbs, so
+  the -ise/-ize, -yse/-yze, -our/-or, -re/-er and -ll-/-l- endings are
+  handled as patterns: a hit is rewritten and looked up. A rewrite that is
+  a real word is applied ("securitise" becomes "securitize" without anyone
+  listing it); one in no dictionary goes to the model ("platformise"); a
+  word already valid in the target is left alone ("advertise", "glamour").
+
+Patterns take what they can prove; the table carries everything else
+(closed families like -ogue and ae/oe, vocabulary like aluminium/aluminum,
+and inflections the patterns don't cover). On the same word the table
+wins.
+
+**UK variants.** The default UK target writes -ise. `--oxford-ize` uses
+VarCon's Oxford column and flips the -ise/-ize pattern, keeping -yse and
+every other British form.
+
+## Style guides
+
+`--style` chooses the mechanical conventions; spelling always follows
+`--target`. `stylefix --list-styles` prints this table.
+
+| guide | for | dash | serial comma | numerals from | toward | punctuation in quotes | abbreviations |
+|---|---|---|---|---|---|---|---|
+| `chicago` (US default) | Chicago Manual of Style | unspaced em | required | 101 | toward | inside | US, UK; PhD; 10 a.m.; vs.; e.g. |
+| `gpo` | US Government Publishing Office Style Manual, the federal standard | unspaced em | required | 10 | toward | inside | U.S., U.K.; Ph.D.; 10 a.m.; vs.; e.g. |
+| `ap` | Associated Press, journalism | spaced em | omitted in a simple series | 10 | toward | inside | U.S., U.K.; Ph.D.; 10 a.m.; vs.; e.g. |
+| `apa` | APA 7th, academic and policy research | unspaced em | required | 10 | no rule | inside | U.S.; PhD; 10 a.m.; vs.; e.g. |
+| `oxford` (UK default) | New Hart's Rules | spaced en | required | 101 | towards | logical (unchanged) | US, UK; PhD; 10 a.m.; vs; e.g. |
+| `guardian` | Guardian/Observer, UK journalism | spaced en | omitted unless needed | 10 | towards | logical (unchanged) | US, UK; PhD; 10am; v; eg, ie, etc |
+| `none` | no guide | unchanged | no rule | no rule | no rule | unchanged | unchanged |
+
+**Abbreviations** follow the guides' general rules, not a word list.
+Chicago's rule (10.4), shared by Oxford and the Guardian, is that an
+abbreviation in full capitals takes no periods, two letters or more: US,
+UK, EU, NATO, PhD, DC. It is applied to every period-group of capitals.
+The hazard is personal initials ("J.K. Rowling" keeps its periods), which
+look identical; so a group followed by a capitalised word is adjudicated,
+with the readings shown as they would print, and the sentence-end case
+("in the U.S. The ...") is handled the same way. AP's rule is the reverse
+for "most two-letter abbreviations" (U.S., U.N., U.K., B.A., B.C.), with
+named exceptions (EU, GI, ID) and none in longer ones (FBI, NATO); since AP
+writes AI, IT and TV without periods, the rule is applied by category:
+countries, places, degrees and eras. GPO follows AP's forms; APA keeps
+"U.S." but writes degrees without periods (PhD, MA). Clock times, vs., and
+e.g., i.e., etc. take each guide's form.
+
+**The noun rule.** GPO and APA use "U.S." only as an adjective ("U.S.
+policy") and write the noun out ("the United States"). Because that is a
+part-of-speech question, it is a warning by default under those guides
+(each likely noun use is listed for review) and an enforcement on request:
+`--abbreviation-nouns enforce` puts every "the U.S." to the model, which
+chooses "United States", the adjective form, or KEEP. `off` silences it.
+
+Dashes, toward/towards and punctuation placement are applied outright.
+Serial commas and numerals need judgement (is "attacks, intentional and
+unintentional" a list of three? is "10" a count or a percentage?), so each
+hit becomes an adjudication item: the model sees the sentence and the
+guide's rule of thumb and chooses between one concrete edit ("ten",
+"a, b, and c") and KEEP. With no model configured they are listed for
+review instead. A guide from the other variety (`--target uk --style
+chicago`) is allowed and noted on stderr.
+
+Guides are a few parameters each in `stylefix/styleguides.py`; the Vale
+rules are generated from them.
+
+After the word-level edits, a punctuation pass handles what a regex rule
+cannot: curly quotes, primary double (US) or single (UK) quotes with correct
+nesting, apostrophes, parenthetical dashes (Chicago em dash / Oxford spaced en
+dash), en dashes in number ranges, and date order (September 4, 2026 /
+4 September 2026). Chicago also moves commas and periods inside closing
+quotes. Front matter, fenced code, inline code, link targets and URLs are
+never touched.
+
+The report next to the output lists every deterministic swap, every model
+decision with its confidence and reason, and every alert left for a human.
+
+## The model
+
+The quickest way to set one up is
+
+```
+stylefix --setup
+```
+
+which asks where your model is (local Ollama, a hosted API, or your own
+server), tests it, and saves the answer where both stylefix and proofix
+find it. `stylefix --check-endpoint` shows what stylefix will use, where
+each setting came from, and whether the endpoint answers.
+
+Any OpenAI-compatible `/v1/chat/completions` endpoint works: Ollama, vLLM,
+LiteLLM, llama.cpp's server, or a hosted API. stylefix takes its settings
+from, highest first: `--url`/`--model`/`--timeout`; `STYLEFIX_LLM_URL`,
+`STYLEFIX_LLM_MODEL`, `STYLEFIX_LLM_KEY`; `~/.config/stylefix/config.toml`;
+`ADJUDICATE_LLM_*`; and `~/.config/adjudicate/config.toml`, which proofix
+reads too. A `--url` or `STYLEFIX_LLM_URL` drops keys set in lower layers;
+set `STYLEFIX_LLM_KEY` (or `api_key_env` in the same config file) alongside
+it. With nothing configured, `--llm auto` (the default) uses a local
+Ollama if one is running with a model pulled, and otherwise runs as
+`--llm none`: ambiguous words are left alone and listed in the report,
+while capitalised deterministic swaps are applied anyway.
+
+**Ollama**: nothing to configure; the first installed model is used.
+`--model` picks another.
+
+**A hosted API**:
+
+```toml
+# ~/.config/adjudicate/config.toml
+[llm]
+url = "https://api.openai.com/v1"
+model = "gpt-4.1-mini"
+api_key_env = "OPENAI_API_KEY"   # the key stays in your environment
+```
+
+**Self-hosted vLLM or LiteLLM with a reasoning model**:
+
+```toml
+[llm]
+url = "http://gpu-box:8000/v1"
+model = "qwen3"
+thinking_switch = true   # send enable_thinking: false, which vLLM honours
+```
+
+Leave `model` out and the server's first listed model is used. A key the
+file or environment names but that is unset, an unknown key, or a wrong
+type stops the run with the file and key named. The full table is
+documented in [adjudicate](https://github.com/AndrewBroz/adjudicate#choosing-the-model-endpoint).
+
+Requests go out in batches of `--batch-size` items (20), `--parallel` (4) at a
+time, so a serving stack with continuous batching (vLLM) answers a document's
+worth of questions in a couple of round-trips. Decisions are cached in
+`.stylefix/cache.json` keyed on target, word and sentence; re-runs are
+instant and reproducible, and you can edit a cached choice to override it.
+Answers below `--min-confidence` (0.7), invalid answers, and transport errors
+all fall through to the report rather than being applied.
+
+### Choosing a model
+
+The question the model answers is narrow (pick one of two or three options,
+given a sentence), so any current instruct model handles it; what differs is
+speed. `scripts/eval_adjudicator.py` scores an endpoint on 48 gold cases
+(noun/verb splits, sense splits, proper nouns, quotations) and reports latency:
+
+```
+uv run python scripts/eval_adjudicator.py [--url URL --model NAME] [--think] [--parallel 8] [--repeat 4]
+```
+
+One measurement, on a DGX Spark serving Qwen3.8-27B (NVFP4) through vLLM:
+
+| mode | accuracy | per item |
+|---|---|---|
+| thinking off, `--parallel 1` | 47/48 | ~1.0 s |
+| thinking off, `--parallel 8` | 47/48 | ~0.33 s |
+| `--think`, batch 8, `--parallel 4` | 48/48 | ~3.2 s |
+
+The one miss without thinking is a capitalised common noun ("Colour theory")
+kept as if it were a title, which is the conservative failure. Thinking buys
+the last case at four to ten times the latency; use `--think` with
+`--batch-size 8 --timeout 600` for a final pass on an important document,
+and the default for everyday runs. Throughput scales with `--parallel`
+because vLLM batches concurrent requests, so a mixture-of-experts model with
+few active parameters (e.g. Gemma-4-26B-A4B) will be faster still on large
+batches without changing accuracy noticeably.
+
+## Exceptions
+
+Words to leave alone come from four places, all optional and all combined:
+
+1. A built-in list (`stylefix/accept.txt`) of technical and policy terms
+   and acronyms (cybersecurity, sandboxing, LLM, NIST). A test ensures
+   nothing on it is a word the conversion tables know.
+2. `~/.config/stylefix/accept.txt`, your personal list.
+3. `.stylefix/accept.txt` in the working directory, the project's list.
+4. `--accept FILE` for a one-off.
+
+One term per line, `#` comments allowed, case-insensitive. They become a
+Vale vocabulary and are skipped by every rule. `--no-default-accept` uses
+only the `--accept` file.
+
+## Extending
+
+- **Suffix families** live in `stylefix/patterns.py`: the regexes, the
+  never-lists, and the decision logic. The conversion table comes from
+  `stylefix/dict/varcon.txt.gz` through `stylefix/varcon.py`; local fixes
+  go in the override dicts in `stylefix/wordlist.py`. After editing any of
+  these, run `python -m stylefix.wordlist` to regenerate the Vale rules (a
+  test fails if they drift). Tests check that the patterns never contradict
+  VarCon and that the old hand tables are still fully covered.
+- **Ambiguous words** live in `stylefix/candidates.py` and the matching
+  `Ambiguous.yml` token regex.
+- **Style rules** are plain Vale YAML under `stylefix/styles/<Guide>`, generated
+  from `stylefix/styleguides.py`; any substitution rule with `action: replace` is
+  applied automatically, anything else goes to the report.
+
+## Limitations
+
+- The UK direction does not move punctuation outside quotation marks: whether
+  a comma belongs to the quote is not knowable mechanically.
+- Numeral and serial-comma detection is heuristic, so no hit is applied
+  mechanically: each goes to the model, which chooses the edit or KEEP, or to
+  the report when no model is available (`--llm none`, or no endpoint reachable).
+- `.docx` files: convert with pandoc first
+  (`pandoc in.docx -t gfm -o in.md`), fix, convert back.
+
+## License
+
+MIT (see `LICENSE`). `stylefix/dict/varcon.txt.gz` is VarCon, under the
+notice in `stylefix/dict/README-varcon.txt`. The spelling dictionaries come
+with [adjudicate](https://github.com/AndrewBroz/adjudicate).
+
+## Development
+
+```
+uv sync
+uv run pytest
+```

stylefix-0.7.0/README.md

@@ -0,0 +1,269 @@
+# stylefix
+
+Regularize a Markdown file to **US or UK English** and a **style guide**
+(Chicago, Oxford, AP, GPO, APA or Guardian), fully automatically, and locally unless you point it at a hosted model.
+
+```
+stylefix draft.md --target us              # -> draft.us.md + draft.us.md.report.md
+stylefix draft.md --target uk --oxford-ize # UK with Oxford -ize spellings
+stylefix draft.md --target us --dry-run    # print a diff, write nothing
+stylefix draft.md --target us --changes    # list every change as it is made
+```
+
+[Vale](https://vale.sh) decides what to change; a small Python wrapper applies
+the changes. The few words that need judgement (UK *licence*/*license*,
+*programme*/*program*, *cheque*/*check*, ...) are put to a language model as a
+multiple-choice question with the surrounding sentence. The model never
+rewrites prose: it picks one of the options you supply, or KEEP.
+
+## Install
+
+```
+uv tool install stylefix      # or: pipx install stylefix
+```
+
+stylefix also needs [Vale](https://vale.sh/docs/install) on your PATH:
+`brew install vale` on macOS, `choco install vale` on Windows, or a release
+binary from GitHub on Linux. Python 3.11+.
+
+`stylefix --help` gives the full option reference with examples. The man
+page is in the repository at `man/stylefix.1` (`man ./man/stylefix.1`).
+
+## How it works
+
+Every candidate word lands in one of three tiers:
+
+| tier | mechanism | what happens |
+|---|---|---|
+| deterministic | **suffix patterns** confirmed against dictionaries, plus a curated table for the irregular families | applied, case preserved |
+| adjudicated | words with a sense split (licence/license, programme/program), pattern hits whose rewrite is in no dictionary (coinages, names), any hit that is capitalised mid-sentence or inside a quotation, and the style guide's serial-comma and numeral rules | a language model chooses between the candidates and KEEP |
+| review | spellings that look like the other variety but could not be converted; serial-comma and numeral hits when no model is configured | listed in the report and the `--changes` log |
+
+**Two data sources, both from the SCOWL project: VarCon, shipped in
+`stylefix/dict/`, and the Hunspell dictionaries that come with adjudicate.**
+
+- **VarCon** (Variant Conversion Info) is the curated table: about 15,000
+  spellings mapped to their preferred American, British and Oxford forms,
+  with sense annotations. It is the source of the Vale substitution rules,
+  regenerated by `python -m stylefix.wordlist`. Where VarCon says a spelling
+  is *also* a word of its own in the target ("check | verify" alongside
+  "check / cheque | bank"; licence as noun, license as verb), the word is
+  not converted but adjudicated, and VarCon's glosses become the rule of
+  thumb the model reads: "British: 'check' for verify; 'cheque' for bank."
+- **Hunspell dictionaries** (en_US, en_GB, read with the pure-Python
+  `spylls`) confirm the pattern tier. English keeps coining -ize verbs, so
+  the -ise/-ize, -yse/-yze, -our/-or, -re/-er and -ll-/-l- endings are
+  handled as patterns: a hit is rewritten and looked up. A rewrite that is
+  a real word is applied ("securitise" becomes "securitize" without anyone
+  listing it); one in no dictionary goes to the model ("platformise"); a
+  word already valid in the target is left alone ("advertise", "glamour").
+
+Patterns take what they can prove; the table carries everything else
+(closed families like -ogue and ae/oe, vocabulary like aluminium/aluminum,
+and inflections the patterns don't cover). On the same word the table
+wins.
+
+**UK variants.** The default UK target writes -ise. `--oxford-ize` uses
+VarCon's Oxford column and flips the -ise/-ize pattern, keeping -yse and
+every other British form.
+
+## Style guides
+
+`--style` chooses the mechanical conventions; spelling always follows
+`--target`. `stylefix --list-styles` prints this table.
+
+| guide | for | dash | serial comma | numerals from | toward | punctuation in quotes | abbreviations |
+|---|---|---|---|---|---|---|---|
+| `chicago` (US default) | Chicago Manual of Style | unspaced em | required | 101 | toward | inside | US, UK; PhD; 10 a.m.; vs.; e.g. |
+| `gpo` | US Government Publishing Office Style Manual, the federal standard | unspaced em | required | 10 | toward | inside | U.S., U.K.; Ph.D.; 10 a.m.; vs.; e.g. |
+| `ap` | Associated Press, journalism | spaced em | omitted in a simple series | 10 | toward | inside | U.S., U.K.; Ph.D.; 10 a.m.; vs.; e.g. |
+| `apa` | APA 7th, academic and policy research | unspaced em | required | 10 | no rule | inside | U.S.; PhD; 10 a.m.; vs.; e.g. |
+| `oxford` (UK default) | New Hart's Rules | spaced en | required | 101 | towards | logical (unchanged) | US, UK; PhD; 10 a.m.; vs; e.g. |
+| `guardian` | Guardian/Observer, UK journalism | spaced en | omitted unless needed | 10 | towards | logical (unchanged) | US, UK; PhD; 10am; v; eg, ie, etc |
+| `none` | no guide | unchanged | no rule | no rule | no rule | unchanged | unchanged |
+
+**Abbreviations** follow the guides' general rules, not a word list.
+Chicago's rule (10.4), shared by Oxford and the Guardian, is that an
+abbreviation in full capitals takes no periods, two letters or more: US,
+UK, EU, NATO, PhD, DC. It is applied to every period-group of capitals.
+The hazard is personal initials ("J.K. Rowling" keeps its periods), which
+look identical; so a group followed by a capitalised word is adjudicated,
+with the readings shown as they would print, and the sentence-end case
+("in the U.S. The ...") is handled the same way. AP's rule is the reverse
+for "most two-letter abbreviations" (U.S., U.N., U.K., B.A., B.C.), with
+named exceptions (EU, GI, ID) and none in longer ones (FBI, NATO); since AP
+writes AI, IT and TV without periods, the rule is applied by category:
+countries, places, degrees and eras. GPO follows AP's forms; APA keeps
+"U.S." but writes degrees without periods (PhD, MA). Clock times, vs., and
+e.g., i.e., etc. take each guide's form.
+
+**The noun rule.** GPO and APA use "U.S." only as an adjective ("U.S.
+policy") and write the noun out ("the United States"). Because that is a
+part-of-speech question, it is a warning by default under those guides
+(each likely noun use is listed for review) and an enforcement on request:
+`--abbreviation-nouns enforce` puts every "the U.S." to the model, which
+chooses "United States", the adjective form, or KEEP. `off` silences it.
+
+Dashes, toward/towards and punctuation placement are applied outright.
+Serial commas and numerals need judgement (is "attacks, intentional and
+unintentional" a list of three? is "10" a count or a percentage?), so each
+hit becomes an adjudication item: the model sees the sentence and the
+guide's rule of thumb and chooses between one concrete edit ("ten",
+"a, b, and c") and KEEP. With no model configured they are listed for
+review instead. A guide from the other variety (`--target uk --style
+chicago`) is allowed and noted on stderr.
+
+Guides are a few parameters each in `stylefix/styleguides.py`; the Vale
+rules are generated from them.
+
+After the word-level edits, a punctuation pass handles what a regex rule
+cannot: curly quotes, primary double (US) or single (UK) quotes with correct
+nesting, apostrophes, parenthetical dashes (Chicago em dash / Oxford spaced en
+dash), en dashes in number ranges, and date order (September 4, 2026 /
+4 September 2026). Chicago also moves commas and periods inside closing
+quotes. Front matter, fenced code, inline code, link targets and URLs are
+never touched.
+
+The report next to the output lists every deterministic swap, every model
+decision with its confidence and reason, and every alert left for a human.
+
+## The model
+
+The quickest way to set one up is
+
+```
+stylefix --setup
+```
+
+which asks where your model is (local Ollama, a hosted API, or your own
+server), tests it, and saves the answer where both stylefix and proofix
+find it. `stylefix --check-endpoint` shows what stylefix will use, where
+each setting came from, and whether the endpoint answers.
+
+Any OpenAI-compatible `/v1/chat/completions` endpoint works: Ollama, vLLM,
+LiteLLM, llama.cpp's server, or a hosted API. stylefix takes its settings
+from, highest first: `--url`/`--model`/`--timeout`; `STYLEFIX_LLM_URL`,
+`STYLEFIX_LLM_MODEL`, `STYLEFIX_LLM_KEY`; `~/.config/stylefix/config.toml`;
+`ADJUDICATE_LLM_*`; and `~/.config/adjudicate/config.toml`, which proofix
+reads too. A `--url` or `STYLEFIX_LLM_URL` drops keys set in lower layers;
+set `STYLEFIX_LLM_KEY` (or `api_key_env` in the same config file) alongside
+it. With nothing configured, `--llm auto` (the default) uses a local
+Ollama if one is running with a model pulled, and otherwise runs as
+`--llm none`: ambiguous words are left alone and listed in the report,
+while capitalised deterministic swaps are applied anyway.
+
+**Ollama**: nothing to configure; the first installed model is used.
+`--model` picks another.
+
+**A hosted API**:
+
+```toml
+# ~/.config/adjudicate/config.toml
+[llm]
+url = "https://api.openai.com/v1"
+model = "gpt-4.1-mini"
+api_key_env = "OPENAI_API_KEY"   # the key stays in your environment
+```
+
+**Self-hosted vLLM or LiteLLM with a reasoning model**:
+
+```toml
+[llm]
+url = "http://gpu-box:8000/v1"
+model = "qwen3"
+thinking_switch = true   # send enable_thinking: false, which vLLM honours
+```
+
+Leave `model` out and the server's first listed model is used. A key the
+file or environment names but that is unset, an unknown key, or a wrong
+type stops the run with the file and key named. The full table is
+documented in [adjudicate](https://github.com/AndrewBroz/adjudicate#choosing-the-model-endpoint).
+
+Requests go out in batches of `--batch-size` items (20), `--parallel` (4) at a
+time, so a serving stack with continuous batching (vLLM) answers a document's
+worth of questions in a couple of round-trips. Decisions are cached in
+`.stylefix/cache.json` keyed on target, word and sentence; re-runs are
+instant and reproducible, and you can edit a cached choice to override it.
+Answers below `--min-confidence` (0.7), invalid answers, and transport errors
+all fall through to the report rather than being applied.
+
+### Choosing a model
+
+The question the model answers is narrow (pick one of two or three options,
+given a sentence), so any current instruct model handles it; what differs is
+speed. `scripts/eval_adjudicator.py` scores an endpoint on 48 gold cases
+(noun/verb splits, sense splits, proper nouns, quotations) and reports latency:
+
+```
+uv run python scripts/eval_adjudicator.py [--url URL --model NAME] [--think] [--parallel 8] [--repeat 4]
+```
+
+One measurement, on a DGX Spark serving Qwen3.8-27B (NVFP4) through vLLM:
+
+| mode | accuracy | per item |
+|---|---|---|
+| thinking off, `--parallel 1` | 47/48 | ~1.0 s |
+| thinking off, `--parallel 8` | 47/48 | ~0.33 s |
+| `--think`, batch 8, `--parallel 4` | 48/48 | ~3.2 s |
+
+The one miss without thinking is a capitalised common noun ("Colour theory")
+kept as if it were a title, which is the conservative failure. Thinking buys
+the last case at four to ten times the latency; use `--think` with
+`--batch-size 8 --timeout 600` for a final pass on an important document,
+and the default for everyday runs. Throughput scales with `--parallel`
+because vLLM batches concurrent requests, so a mixture-of-experts model with
+few active parameters (e.g. Gemma-4-26B-A4B) will be faster still on large
+batches without changing accuracy noticeably.
+
+## Exceptions
+
+Words to leave alone come from four places, all optional and all combined:
+
+1. A built-in list (`stylefix/accept.txt`) of technical and policy terms
+   and acronyms (cybersecurity, sandboxing, LLM, NIST). A test ensures
+   nothing on it is a word the conversion tables know.
+2. `~/.config/stylefix/accept.txt`, your personal list.
+3. `.stylefix/accept.txt` in the working directory, the project's list.
+4. `--accept FILE` for a one-off.
+
+One term per line, `#` comments allowed, case-insensitive. They become a
+Vale vocabulary and are skipped by every rule. `--no-default-accept` uses
+only the `--accept` file.
+
+## Extending
+
+- **Suffix families** live in `stylefix/patterns.py`: the regexes, the
+  never-lists, and the decision logic. The conversion table comes from
+  `stylefix/dict/varcon.txt.gz` through `stylefix/varcon.py`; local fixes
+  go in the override dicts in `stylefix/wordlist.py`. After editing any of
+  these, run `python -m stylefix.wordlist` to regenerate the Vale rules (a
+  test fails if they drift). Tests check that the patterns never contradict
+  VarCon and that the old hand tables are still fully covered.
+- **Ambiguous words** live in `stylefix/candidates.py` and the matching
+  `Ambiguous.yml` token regex.
+- **Style rules** are plain Vale YAML under `stylefix/styles/<Guide>`, generated
+  from `stylefix/styleguides.py`; any substitution rule with `action: replace` is
+  applied automatically, anything else goes to the report.
+
+## Limitations
+
+- The UK direction does not move punctuation outside quotation marks: whether
+  a comma belongs to the quote is not knowable mechanically.
+- Numeral and serial-comma detection is heuristic, so no hit is applied
+  mechanically: each goes to the model, which chooses the edit or KEEP, or to
+  the report when no model is available (`--llm none`, or no endpoint reachable).
+- `.docx` files: convert with pandoc first
+  (`pandoc in.docx -t gfm -o in.md`), fix, convert back.
+
+## License
+
+MIT (see `LICENSE`). `stylefix/dict/varcon.txt.gz` is VarCon, under the
+notice in `stylefix/dict/README-varcon.txt`. The spelling dictionaries come
+with [adjudicate](https://github.com/AndrewBroz/adjudicate).
+
+## Development
+
+```
+uv sync
+uv run pytest
+```

stylefix-0.7.0/examples/sample.md

@@ -0,0 +1,29 @@
+---
+title: Colour Management Programme
+author: The Centre for Analysis
+---
+
+# Colour management programme
+
+The Centre for Digital Behaviour organises its work around a simple licence
+model. Members practise what they preach: every programme is analysed, every
+storey of the building is catalogued, and "colour" is spelt the British way --
+whilst our American colleagues favour 'color'.
+
+## Practical details
+
+- The licence fee is 10 pounds and the practice runs 3-5 sessions a week.
+- Please send your cheque to the Labour Party office by 4 September 2026.
+- The theatre programme lists the metre readings, the tyre pressures, and the
+  disc brakes we've organised for the aluminium trailer.
+- As the Defence Ministry's report put it, "the colour scheme was unauthorised".
+
+The program crashed after the check cleared, and the story about the storey
+made us tire of the whole thing. It's the Joneses' problem now, towards the end
+of the '90s.
+
+```python
+colour = "unchanged in code"  # organise nothing here
+```
+
+See `colour_utils.organise()` and [the colour guide](https://example.org/colour).