docs(readme): give install its own heading and match the forge description

The repo-standard gate (v0.1.1, class `standalone`) flagged two ERRORs on the
first screen. Both are about a reader who arrives from outside:

- The opening line now repeats the forge description verbatim. That is the
  only place where description, catalog and README can be machine-checked to
  agree; a paraphrase reads fine and is unverifiable.
- `## Install` exists as a heading, on the first screen, with the commands
  under it. They were previously buried in `## Requirements` two screens
  down, which is where a human eventually finds them and an agent does not.
  `## Requirements` keeps the dependency policy and the direct-reference
  rationale, and points at `## Install` for the commands.

The Install block also states which tag a stranger should pin: `v0.4.0` is
stable, `v0.5.0a2` is the OKF v0.2 pilot pre-release and is not for general
use. Nothing else moved; the body below the first screen is unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TJUFZhHzf9AqLucMsJy6u1
This commit is contained in:
Kjell Tore Guttormsen 2026-08-03 21:54:03 +02:00
commit b9ba42da6f

View file

@ -1,6 +1,6 @@
# llm-ingestion-okf
Shared ingestion library for OKF (Open Knowledge Format) bundles.
Shared OKF (Open Knowledge Format) ingestion library: spec-based connectors, bundle inbox, and external-bundle import. Security delegated to llm-ingestion-guard.
Status: phases 1 and 2 are implemented. Phase 1 (spec-based ingestion) covers
manifest validation, the `file`/`sql`/`http` connectors, deterministic
@ -13,6 +13,26 @@ extraction (`pdf`/`docx`/`xlsx` behind the `[extract]` extra) is unimplemented,
so those types are rejected fail-fast. Phases 34 are planned (see
`docs/plan/`).
## Install
Python 3.10+. Neither this package nor the guard it depends on is on a package
index yet, so **with pip, install the guard first** — otherwise installing this
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-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.
`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
[Upstream OKF versions](#upstream-okf-versions)).
## Planned scope (v1)
The library provides three entry points for getting content into an OKF
@ -192,21 +212,8 @@ structure from either.
## Requirements
Python 3.10+, and exactly one runtime dependency — the security boundary,
`llm-ingestion-guard>=0.3,<0.4`. Everything else is stdlib.
That guard is not on a package index yet, so **with pip, install it first**
otherwise installing this 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-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.
`llm-ingestion-guard>=0.3,<0.4`. Everything else is stdlib. The commands are
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