clustergrep 0.8.0__tar.gz

clustergrep-0.8.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: publish
+
+# Fires only when you publish a GitHub Release, so nothing reaches PyPI
+# without a deliberate act. A PyPI version can be yanked but never replaced,
+# so the tests run again here rather than trusting that the push-time run of
+# the same commit is still representative.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # No `environment:` here, deliberately: the trusted publisher on PyPI was
+    # registered without one, and PyPI checks the environment claim only when
+    # the publisher names an environment to check it against. Declaring one
+    # here that PyPI does not know about buys nothing. To add the extra gate
+    # later, set the environment on both sides at once -- a mismatch fails the
+    # upload at the last step, after the build has already succeeded.
+    permissions:
+      # Required for trusted publishing: GitHub mints a short-lived OIDC token
+      # that PyPI verifies against the publisher you configured. No long-lived
+      # API token is stored in this repository.
+      id-token: write
+
+    steps:
+      # Install and test with exactly the steps test.yml already proves green
+      # on every push. This workflow runs once, at the only moment it matters,
+      # and cannot be rehearsed without publishing something -- so it reuses a
+      # known-good path rather than a tidier untested one. uv appears only for
+      # the two steps that need it.
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e '.[dev]'
+
+      - name: Download the WordNet corpus
+        run: python -m clustergrep --install-data
+
+      - name: Test
+        run: python -m pytest -q
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

clustergrep-0.8.0/.github/workflows/test.yml

@@ -0,0 +1,41 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # The full interpreter range on one platform, plus one job each on
+        # macOS and Windows -- the per-platform data directories are real
+        # branching logic and deserve to be exercised where they apply.
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: macos-latest
+            python-version: "3.13"
+          - os: windows-latest
+            python-version: "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: python -m pip install --upgrade pip && python -m pip install -e '.[dev]'
+
+      - name: Download the WordNet corpus
+        run: python -m clustergrep --install-data
+
+      - name: Show resolved paths
+        run: python -m clustergrep --paths
+
+      - name: Test
+        run: python -m pytest -q

clustergrep-0.8.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+*.egg-info/
+build/
+dist/

clustergrep-0.8.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.8.0
+
+First public release.
+
+- `clustergrep WORD FILE` matches a word and the words that mean roughly the
+  same thing, reporting the distance and the term that fired on every line.
+- `--threshold 0 --no-inflect -s` is exactly `grep -w -F`, verified against
+  real grep in the test suite.
+- Three backends behind one distance contract: `wordnet` (default; weighted
+  shortest path over the lexical graph, every distance an explainable path),
+  `vectors` (cosine distance over GloVe/word2vec), `thesaurus` (a TSV you pin,
+  edit and commit).
+- `--explain` prints the cluster before you trust it; `--tsv` writes it out as
+  a thesaurus file; `--stats` reports which terms actually fired.
+- Options may appear anywhere among the file names, as they may in grep.
+- The WordNet corpus is downloaded on request with `--install-data`, never
+  bundled. It lands in a per-user data directory — `%LOCALAPPDATA%` on Windows,
+  `~/Library/Application Support` on macOS, `~/.local/share` elsewhere — and an
+  existing copy is reused. `--paths` shows where everything is.

clustergrep-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niall Richard Murphy
+
+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.

clustergrep-0.8.0/PKG-INFO

@@ -0,0 +1,285 @@
+Metadata-Version: 2.5
+Name: clustergrep
+Version: 0.8.0
+Summary: grep for a concept rather than a string, with the distance reported
+Project-URL: Homepage, https://github.com/niallrmurphy/clustergrep
+Project-URL: Repository, https://github.com/niallrmurphy/clustergrep
+Project-URL: Issues, https://github.com/niallrmurphy/clustergrep/issues
+Author: Niall Richard Murphy
+License: MIT
+License-File: LICENSE
+Keywords: cli,grep,logs,nlp,search,semantic,wordnet
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: nltk>=3.8
+Provides-Extra: dev
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: vectors
+Requires-Dist: numpy>=1.24; extra == 'vectors'
+Description-Content-Type: text/markdown
+
+# clustergrep
+
+grep for a concept rather than a string, and tell you how far each match is
+from what you asked for.
+
+`grep` is mostly used for fixed or moderately varying text that you can determine
+in advance: a fixed log line string (e.g. "reboot"), a well-formed timestamp,
+a string which is known to occur around another particular string ("login for niallm
+failed"). It is a poor fit for the other common search, the one where you
+know the *idea* and not the words — for example the concept "escape".
+Today we use something like `grep -E 'escape|flee|jailbreak|breakout'`, which
+is inelegant, incomplete, and stale after we invent a new word for something,
+which we seem to be doing a lot these days. Handing the whole job to a language model
+trades those problems for different, potentially worse ones: hallucination,
+skipping lines or an entire file, or answering differently this Tuesday as
+opposed to last one.
+
+clustergrep splits the difference. A lexical model decides *what to
+look for*, once, up front, where you can read it and argue with it. After that,
+finding it is ordinary deterministic matching with nothing in the loop.
+
+```console
+$ clustergrep -t 0.25 escape incidents.log
+1:0.00:escape:2024-01-02 The prisoner escaped through the laundry chute.
+2:0.25:breakout:2024-01-03 Guards reported a breakout on B wing at 0300.
+4:0.20:flee:2024-01-05 Two inmates fled across the yard before dawn.
+5:0.25:jailbreak:2024-01-06 A jailbreak attempt was foiled by the perimeter fence.
+6:0.25:fly the coop:2024-01-07 He flew the coop while the van was being loaded.
+8:0.15:elude:2024-01-09 The suspect eluded officers for six hours.
+9:0.15:escapism:2024-01-10 Staff described a general air of escapism among the population.
+10:0.20:getaway:2024-01-11 Getaway vehicle recovered near the motorway.
+12:0.15:break loose:2024-01-13 The detainee broke loose during transfer.
+```
+
+Of course, this matching surrenders the previous boolean does/doesn't match
+approach, in favour of a notion of the _conceptual distance_ between the term
+you searched for and what was found. This means that we report lines that matched,
+and also the extent to which they matched. In the above, `0.25:jailbreak` says
+*this line matched because "jailbreak" is 0.25 away from "escape"*. You can tune
+`-t`, the flag that sets the conceptual/lexical distance until you're satisfied
+with the results.
+
+Note "fled" and "broke loose": clustergrep matches irregular inflections, so
+the cluster does not have to enumerate them.
+
+At the moment clustergrep does not handle non-English, but this is very definitely
+an ambition. (Technically, the thesaurus is multi-language, but the inflection
+rules are not.)
+
+## Install
+
+```bash
+pip install clustergrep
+clustergrep --install-data      # once: fetches the WordNet corpus
+```
+
+**The corpus is not bundled.** WordNet is about 10MB and is licensed separately
+by Princeton, so clustergrep downloads it on request into a per-user directory
+rather than shipping a copy. If you already have it — from a previous `nltk`
+install, a system package, or `NLTK_DATA` — that copy is found first and
+nothing is downloaded.
+
+|            | data                                   | cache                                |
+|------------|----------------------------------------|--------------------------------------|
+| Linux      | `~/.local/share/clustergrep`           | `~/.cache/clustergrep`               |
+| macOS      | `~/Library/Application Support/clustergrep` | `~/Library/Caches/clustergrep`  |
+| Windows    | `%LOCALAPPDATA%\clustergrep\Data`       | `%LOCALAPPDATA%\clustergrep\Cache`   |
+
+`XDG_DATA_HOME` and `XDG_CACHE_HOME` are honoured wherever they are set, and
+`CLUSTERGREP_DATA` / `CLUSTERGREP_CACHE` override everything — necessary for
+containers, CI, and read-only home directories.
+
+```console
+$ clustergrep --paths
+data     /home/you/.local/share/clustergrep
+cache    /home/you/.cache/clustergrep
+wordnet  /home/you/.local/share/clustergrep/corpora/wordnet.zip
+```
+
+Uninstalling is `pip uninstall clustergrep` and deleting those two
+directories. Nothing else is written. The cache holds only files clustergrep
+can rebuild, so deleting it alone is always safe.
+
+### From source
+
+```bash
+git clone https://github.com/niallrmurphy/clustergrep
+cd clustergrep
+uv pip install -e '.[dev]'
+uv run pytest -q
+```
+
+## Distance
+
+Distance runs from 0.0 to 1.0.
+
+| | |
+|---|---|
+| `0.0` | the word you typed, and nothing else |
+| `~0.15` | another word for the same thing |
+| `~0.25` | a narrower or related kind of the same thing |
+| `~0.4` | recognisably connected, plausibly a different concept |
+| `1.0` | unrelated |
+
+`--threshold 0` admits only the literal word, so clustergrep becomes plain grep.
+That is exact, not approximate:
+
+```console
+$ clustergrep -t 0 --no-inflect -s --no-distance Guards incidents.log
+$ grep -n -w -F Guards incidents.log            # identical output
+```
+
+*Notable distinction from grep*: cluster matching is always word-oriented,
+like `grep -w`, because concepts are words, and root/syllabic tokenisation would
+result in undue implementation complexity right now.
+
+### Where the numbers come from
+
+The default backend walks WordNet as a weighted graph with costed edges,
+and a penalty per "sense".  Every distance is therefore a summed path,
+which `--explain` will show:
+
+```console
+$ clustergrep --explain -t 0.2 escape
+'escape' via wordnet, threshold 0.2: 15 term(s)
+  0.00  escape
+  0.15  break loose  escape.v.01
+  0.15  dodging      evasion.n.03
+  0.15  elude        elude.v.02
+  0.15  escapism     escape.n.02
+  0.15  evasion      evasion.n.03
+  0.15  flight       escape.n.01
+  0.15  get away     escape.v.01
+  0.15  get by       get_off.v.05
+  0.15  get off      get_off.v.05
+  0.15  get out      get_off.v.05
+  0.15  miss         miss.v.09
+  0.20  escapee      escape.v.01 -derivation-> escapee
+  0.20  flee         escape.n.01 -derivation-> flee
+  0.20  getaway      escape.v.01 -derivation-> getaway
+```
+
+| relation | cost | |
+|---|---|---|
+| synonym | 0.15 | another lemma of the same sense |
+| similar / derivation / verb group | 0.20 | escape → escapee |
+| hyponym | 0.25 | escape → jailbreak (narrower) |
+| also-see | 0.35 | |
+| hypernym | 0.40 | escape → movement (broader) |
+| meronym | 0.45 | part, member, substance |
+| antonym | 0.60 | `--antonyms`, off by default |
+
+Narrowing costs less than broadening, because a narrower term keeps you inside
+the concept while a broader one leaves it. Each successive dictionary sense of
+the word adds 0.05, so the dominant reading dominates the cluster. There is little
+that is truly objective about this scoring, but is pragmatically enough to work
+with right now, and we are open to other suggestions.
+
+## Backends
+
+```
+--backend wordnet      (default)  offline, explainable, English
+--backend vectors      --model glove.6B.100d.txt
+--backend thesaurus    --thesaurus terms.tsv
+```
+
+**wordnet** just knows lexicographic relations: relatively precise, but only
+lexically bound, so "escape" and "jail" have no plausible path.
+
+**vectors** is the opposite. Cosine distance over any GloVe or word2vec
+text export "knows" that `escape → jail` immediately but isn't comparably
+enumerable as a path from an accessible graph search.
+
+**thesaurus** is a patch file you can use to add your own terms (but
+_replaces_ WordNet rather than augments it, so you need to seed from the
+original):
+
+```
+# concept   term          distance   note
+escape      jailbreak     0.25
+escape      exfil         0.30       our term
+```
+
+```bash
+clustergrep --explain -t 0.3 escape --tsv > escape.tsv
+clustergrep -b thesaurus --thesaurus escape.tsv escape incidents.log
+```
+
+From then on the search is fully reproducible and a new term is a one-line diff.
+
+## Options
+
+Familiar from grep: `-i` `-v` `-c` `-l` `-L` `-o` `-n` `-r` `-m` `-H`
+`--include` `--exclude` `--color`. Exit codes match too — 0 matched, 1 nothing
+matched, 2 error.
+
+Particular to this tool:
+
+| | |
+|---|---|
+| `-t, --threshold` | how far to reach (default 0.4) |
+| `--explain`, `--tsv` | print the cluster and stop |
+| `--senses` | list the word's WordNet senses, for `--sense` |
+| `--pos n\|v\|a\|r` | one part of speech only |
+| `--sense N` | pin one reading of the word |
+| `--stats` | which cluster terms actually fired |
+| `--sort` | nearest matches first |
+| `--json` | one object per match |
+| `--no-inflect` | exact surface forms only |
+| `--no-distance` | grep-shaped output |
+
+`--stats` is for tuning: 
+
+```console
+$ clustergrep -t 0.4 escape incidents.log --stats -c
+10 match(es) from 10 of 62 cluster term(s)
+  0.00  escape                   1
+  0.25  breakout                 1
+  0.20  flee                     1
+  0.25  jailbreak                1
+  0.25  fly the coop             1
+  0.30  leakage                  1
+  0.15  elude                    1
+  0.15  escapism                 1
+  0.20  getaway                  1
+  0.15  break loose              1
+```
+
+## Known limits
+
+**Polysemy.** A cluster covers every sense of the word. At `-t 0.4`, "escape"
+reaches `leakage` and `outflow` via the concept of fluid-discharge, so a line about
+reactor coolant will match.
+
+**Distances are not probabilities** and are not comparable between backends.
+They only order matches within one search.
+
+**English only**, and only as current as WordNet 3.0.
+
+**Irregular inflections** (`fled`, `broke`) come from WordNet's exception lists,
+so they are available under the default backend. The vectors and thesaurus
+backends get regular suffix rules only: if you have a specific requirement,
+put them in the TSV.
+
+**Speed.** Roughly 8µs per line — about 5s for a 24MB, 300k-line file, against
+0.02s for `grep -E`. This is Python's regex engine over a large alternation
+and the extra columns. For now, if you need fast loops over lots of data, use 
+`--explain` to generate the alternation and hand it to real grep.
+
+## Licence
+
+clustergrep is MIT licensed. The WordNet corpus it downloads is **not** part of
+this distribution and is covered by [Princeton's WordNet
+licence](https://wordnet.princeton.edu/license-and-commercial-use). Any vector
+model you point `--model` at carries whatever licence its publisher gave it.

clustergrep-0.8.0/README.md

@@ -0,0 +1,255 @@
+# clustergrep
+
+grep for a concept rather than a string, and tell you how far each match is
+from what you asked for.
+
+`grep` is mostly used for fixed or moderately varying text that you can determine
+in advance: a fixed log line string (e.g. "reboot"), a well-formed timestamp,
+a string which is known to occur around another particular string ("login for niallm
+failed"). It is a poor fit for the other common search, the one where you
+know the *idea* and not the words — for example the concept "escape".
+Today we use something like `grep -E 'escape|flee|jailbreak|breakout'`, which
+is inelegant, incomplete, and stale after we invent a new word for something,
+which we seem to be doing a lot these days. Handing the whole job to a language model
+trades those problems for different, potentially worse ones: hallucination,
+skipping lines or an entire file, or answering differently this Tuesday as
+opposed to last one.
+
+clustergrep splits the difference. A lexical model decides *what to
+look for*, once, up front, where you can read it and argue with it. After that,
+finding it is ordinary deterministic matching with nothing in the loop.
+
+```console
+$ clustergrep -t 0.25 escape incidents.log
+1:0.00:escape:2024-01-02 The prisoner escaped through the laundry chute.
+2:0.25:breakout:2024-01-03 Guards reported a breakout on B wing at 0300.
+4:0.20:flee:2024-01-05 Two inmates fled across the yard before dawn.
+5:0.25:jailbreak:2024-01-06 A jailbreak attempt was foiled by the perimeter fence.
+6:0.25:fly the coop:2024-01-07 He flew the coop while the van was being loaded.
+8:0.15:elude:2024-01-09 The suspect eluded officers for six hours.
+9:0.15:escapism:2024-01-10 Staff described a general air of escapism among the population.
+10:0.20:getaway:2024-01-11 Getaway vehicle recovered near the motorway.
+12:0.15:break loose:2024-01-13 The detainee broke loose during transfer.
+```
+
+Of course, this matching surrenders the previous boolean does/doesn't match
+approach, in favour of a notion of the _conceptual distance_ between the term
+you searched for and what was found. This means that we report lines that matched,
+and also the extent to which they matched. In the above, `0.25:jailbreak` says
+*this line matched because "jailbreak" is 0.25 away from "escape"*. You can tune
+`-t`, the flag that sets the conceptual/lexical distance until you're satisfied
+with the results.
+
+Note "fled" and "broke loose": clustergrep matches irregular inflections, so
+the cluster does not have to enumerate them.
+
+At the moment clustergrep does not handle non-English, but this is very definitely
+an ambition. (Technically, the thesaurus is multi-language, but the inflection
+rules are not.)
+
+## Install
+
+```bash
+pip install clustergrep
+clustergrep --install-data      # once: fetches the WordNet corpus
+```
+
+**The corpus is not bundled.** WordNet is about 10MB and is licensed separately
+by Princeton, so clustergrep downloads it on request into a per-user directory
+rather than shipping a copy. If you already have it — from a previous `nltk`
+install, a system package, or `NLTK_DATA` — that copy is found first and
+nothing is downloaded.
+
+|            | data                                   | cache                                |
+|------------|----------------------------------------|--------------------------------------|
+| Linux      | `~/.local/share/clustergrep`           | `~/.cache/clustergrep`               |
+| macOS      | `~/Library/Application Support/clustergrep` | `~/Library/Caches/clustergrep`  |
+| Windows    | `%LOCALAPPDATA%\clustergrep\Data`       | `%LOCALAPPDATA%\clustergrep\Cache`   |
+
+`XDG_DATA_HOME` and `XDG_CACHE_HOME` are honoured wherever they are set, and
+`CLUSTERGREP_DATA` / `CLUSTERGREP_CACHE` override everything — necessary for
+containers, CI, and read-only home directories.
+
+```console
+$ clustergrep --paths
+data     /home/you/.local/share/clustergrep
+cache    /home/you/.cache/clustergrep
+wordnet  /home/you/.local/share/clustergrep/corpora/wordnet.zip
+```
+
+Uninstalling is `pip uninstall clustergrep` and deleting those two
+directories. Nothing else is written. The cache holds only files clustergrep
+can rebuild, so deleting it alone is always safe.
+
+### From source
+
+```bash
+git clone https://github.com/niallrmurphy/clustergrep
+cd clustergrep
+uv pip install -e '.[dev]'
+uv run pytest -q
+```
+
+## Distance
+
+Distance runs from 0.0 to 1.0.
+
+| | |
+|---|---|
+| `0.0` | the word you typed, and nothing else |
+| `~0.15` | another word for the same thing |
+| `~0.25` | a narrower or related kind of the same thing |
+| `~0.4` | recognisably connected, plausibly a different concept |
+| `1.0` | unrelated |
+
+`--threshold 0` admits only the literal word, so clustergrep becomes plain grep.
+That is exact, not approximate:
+
+```console
+$ clustergrep -t 0 --no-inflect -s --no-distance Guards incidents.log
+$ grep -n -w -F Guards incidents.log            # identical output
+```
+
+*Notable distinction from grep*: cluster matching is always word-oriented,
+like `grep -w`, because concepts are words, and root/syllabic tokenisation would
+result in undue implementation complexity right now.
+
+### Where the numbers come from
+
+The default backend walks WordNet as a weighted graph with costed edges,
+and a penalty per "sense".  Every distance is therefore a summed path,
+which `--explain` will show:
+
+```console
+$ clustergrep --explain -t 0.2 escape
+'escape' via wordnet, threshold 0.2: 15 term(s)
+  0.00  escape
+  0.15  break loose  escape.v.01
+  0.15  dodging      evasion.n.03
+  0.15  elude        elude.v.02
+  0.15  escapism     escape.n.02
+  0.15  evasion      evasion.n.03
+  0.15  flight       escape.n.01
+  0.15  get away     escape.v.01
+  0.15  get by       get_off.v.05
+  0.15  get off      get_off.v.05
+  0.15  get out      get_off.v.05
+  0.15  miss         miss.v.09
+  0.20  escapee      escape.v.01 -derivation-> escapee
+  0.20  flee         escape.n.01 -derivation-> flee
+  0.20  getaway      escape.v.01 -derivation-> getaway
+```
+
+| relation | cost | |
+|---|---|---|
+| synonym | 0.15 | another lemma of the same sense |
+| similar / derivation / verb group | 0.20 | escape → escapee |
+| hyponym | 0.25 | escape → jailbreak (narrower) |
+| also-see | 0.35 | |
+| hypernym | 0.40 | escape → movement (broader) |
+| meronym | 0.45 | part, member, substance |
+| antonym | 0.60 | `--antonyms`, off by default |
+
+Narrowing costs less than broadening, because a narrower term keeps you inside
+the concept while a broader one leaves it. Each successive dictionary sense of
+the word adds 0.05, so the dominant reading dominates the cluster. There is little
+that is truly objective about this scoring, but is pragmatically enough to work
+with right now, and we are open to other suggestions.
+
+## Backends
+
+```
+--backend wordnet      (default)  offline, explainable, English
+--backend vectors      --model glove.6B.100d.txt
+--backend thesaurus    --thesaurus terms.tsv
+```
+
+**wordnet** just knows lexicographic relations: relatively precise, but only
+lexically bound, so "escape" and "jail" have no plausible path.
+
+**vectors** is the opposite. Cosine distance over any GloVe or word2vec
+text export "knows" that `escape → jail` immediately but isn't comparably
+enumerable as a path from an accessible graph search.
+
+**thesaurus** is a patch file you can use to add your own terms (but
+_replaces_ WordNet rather than augments it, so you need to seed from the
+original):
+
+```
+# concept   term          distance   note
+escape      jailbreak     0.25
+escape      exfil         0.30       our term
+```
+
+```bash
+clustergrep --explain -t 0.3 escape --tsv > escape.tsv
+clustergrep -b thesaurus --thesaurus escape.tsv escape incidents.log
+```
+
+From then on the search is fully reproducible and a new term is a one-line diff.
+
+## Options
+
+Familiar from grep: `-i` `-v` `-c` `-l` `-L` `-o` `-n` `-r` `-m` `-H`
+`--include` `--exclude` `--color`. Exit codes match too — 0 matched, 1 nothing
+matched, 2 error.
+
+Particular to this tool:
+
+| | |
+|---|---|
+| `-t, --threshold` | how far to reach (default 0.4) |
+| `--explain`, `--tsv` | print the cluster and stop |
+| `--senses` | list the word's WordNet senses, for `--sense` |
+| `--pos n\|v\|a\|r` | one part of speech only |
+| `--sense N` | pin one reading of the word |
+| `--stats` | which cluster terms actually fired |
+| `--sort` | nearest matches first |
+| `--json` | one object per match |
+| `--no-inflect` | exact surface forms only |
+| `--no-distance` | grep-shaped output |
+
+`--stats` is for tuning: 
+
+```console
+$ clustergrep -t 0.4 escape incidents.log --stats -c
+10 match(es) from 10 of 62 cluster term(s)
+  0.00  escape                   1
+  0.25  breakout                 1
+  0.20  flee                     1
+  0.25  jailbreak                1
+  0.25  fly the coop             1
+  0.30  leakage                  1
+  0.15  elude                    1
+  0.15  escapism                 1
+  0.20  getaway                  1
+  0.15  break loose              1
+```
+
+## Known limits
+
+**Polysemy.** A cluster covers every sense of the word. At `-t 0.4`, "escape"
+reaches `leakage` and `outflow` via the concept of fluid-discharge, so a line about
+reactor coolant will match.
+
+**Distances are not probabilities** and are not comparable between backends.
+They only order matches within one search.
+
+**English only**, and only as current as WordNet 3.0.
+
+**Irregular inflections** (`fled`, `broke`) come from WordNet's exception lists,
+so they are available under the default backend. The vectors and thesaurus
+backends get regular suffix rules only: if you have a specific requirement,
+put them in the TSV.
+
+**Speed.** Roughly 8µs per line — about 5s for a 24MB, 300k-line file, against
+0.02s for `grep -E`. This is Python's regex engine over a large alternation
+and the extra columns. For now, if you need fast loops over lots of data, use 
+`--explain` to generate the alternation and hand it to real grep.
+
+## Licence
+
+clustergrep is MIT licensed. The WordNet corpus it downloads is **not** part of
+this distribution and is covered by [Princeton's WordNet
+licence](https://wordnet.princeton.edu/license-and-commercial-use). Any vector
+model you point `--model` at carries whatever licence its publisher gave it.