docs(readme): pair the guard tag to the okf tag, not to this branch

The public install block did not work. It paired guard `@v0.3.4` with okf
`@v0.4.0`, and `v0.4.0` declares `llm-ingestion-guard>=0.2,<0.3` — which
v0.3.4 does not satisfy. With the guard absent from any package index, pip
then fails with `No matching distribution found for llm-ingestion-guard`:
exactly the error the two-step block exists to prevent. Anyone following the
front page hit it.

Three instances of one conflation, all measured, all introduced by writing
this branch's pin into a sentence about a tag:

  1. l.23 guard tag — repaired to `@v0.2.0`, which is what `v0.4.0` needs and
     what `v0.4.0`'s own README already says.
  2. The uv sentence claimed uv reads `[tool.uv.sources]` in "this project's"
     pyproject; installing `@v0.4.0` makes uv read the *tag's* file. Measured:
     that entry in `v0.4.0` points at guard tag `v0.2.0`, so the uv path was
     correct and only described wrong.
  3. Requirements cited `Requires-Dist: llm-ingestion-guard<0.3,>=0.2` as
     verified against the wheel, under a stated range of `>=0.3,<0.4`. A wheel
     built from this branch today carries `<0.4,>=0.3`; the quoted evidence was
     a true measurement of the old pin left standing under the new one.

The 2026-07-25 measurement stamp is kept rather than dropped: `v0.5.0a2`'s
frozen README shows that measurement was of the guard `v0.2.0` + okf `v0.4.0`
pair, which is the pair restored here. `b9ba42d` moved the numbers away from
what had been measured while keeping the date that vouched for them.

Docs only, by operator decision. Making the block's numbers true by releasing a
stable tag that carries this branch's pin is the other repair, and it is a
release: it belongs to the open release decision, and not inside the pilot
freeze.

The trap was already written down ("the install channel depends on the tag, not
`main`") and the public README carried the defect anyway. Recording a trap is
not applying it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PoZ2ZCWdkkZ3QYMHJFRX4z
This commit is contained in:
Kjell Tore Guttormsen 2026-08-10 21:15:41 +02:00
commit 200ed61701

View file

@ -20,14 +20,22 @@ index yet, so **with pip, install the guard first** — otherwise installing thi
package fails with `No matching distribution found for llm-ingestion-guard`:
```
pip install "llm-ingestion-guard @ git+https://git.fromaitochitta.com/open/llm-ingestion-pipeline-security.git@v0.3.4"
pip install "llm-ingestion-guard @ git+https://git.fromaitochitta.com/open/llm-ingestion-pipeline-security.git@v0.2.0"
pip install "llm-ingestion-okf @ git+https://git.fromaitochitta.com/open/llm-ingestion-okf.git@v0.4.0"
```
With uv, one command is enough — `uv pip install "llm-ingestion-okf @ git+…@v0.4.0"`
resolves the guard from the tag on its own, because uv reads the
`[tool.uv.sources]` entry in this project's `pyproject.toml` when it builds
from the source tree. Both paths were measured on 2026-07-25.
resolves the guard on its own, because uv reads the `[tool.uv.sources]` entry
in the `pyproject.toml` **of the tag it is installing**, and `v0.4.0` points
that entry at the guard tag above. Both paths were measured on 2026-07-25,
against this exact pair of tags.
The guard tag is paired to the okf tag, not to this branch: `v0.4.0` declares
`llm-ingestion-guard>=0.2,<0.3`, which `v0.2.0` satisfies and later guard tags
do not. `main` has since moved its own pin to `>=0.3,<0.4` (see
[Requirements](#requirements)); that pin reaches you in the next stable tag,
not in the commands above. Reading a pin off this branch and installing it
against `v0.4.0` is the one combination that fails.
`v0.4.0` is the current stable tag. `v0.5.0a2` is a pre-release for the named
OKF v0.2 pilot set only; pin it only if you are one of them (see
@ -226,9 +234,10 @@ under [Install](#install); what follows is why they look the way they do.
A git URL is a PEP 508 direct reference and pins one exact tag, so it is an
install-time *channel*, not the pin: the range above stays the declared
dependency — the built wheel carries `Requires-Dist:
llm-ingestion-guard<0.3,>=0.2` — and resolves normally once the package index
exists. The optional `[extract]` extra (pdf/docx/xlsx parsers) is not
dependency — a wheel built from this branch carries `Requires-Dist:
llm-ingestion-guard<0.4,>=0.3`, measured 2026-08-10 — and resolves normally
once the package index exists. A wheel built from a *tag* carries that tag's
range instead, which is why the install commands pair tag with tag. The optional `[extract]` extra (pdf/docx/xlsx parsers) is not
populated yet. The planned Node half targets Node/ESM with zero npm
dependencies.