v1.0.0 — page images in, one accessible document out

What Iris is

Equalify Iris converts a sequential set of page images — the rendered pages of a PDF, typically — into one content-only, WCAG 2.2 AA accessible HTML document.

One vision call per page turns each page into an accessible HTML fragment. The fragments are assembled in page order into a minimal document and checked with axe-core. Then a review loop runs: a Reader reads the assembled document and flags reading-order and semantic problems, attributing each to the pages it appears on; a Copy Editor proposes fixes against just those pages' images; the document is re-linted. Up to three rounds by default, or until a round changes nothing.

Three constraints shape all of it:

• Content only. No CSS, no visual fidelity. A two-column scan becomes linear semantic HTML. WCAG 2.2 AA is the fixed target, not a per-run option.
• One machine, no vendor lock-in. A laptop, a Mac Mini or a self-hosted box are all first-class. Defaults are SQLite and the local filesystem; nothing hosted is required, and every external dependency is replaceable by configuration.
• One GitHub identity, held by the server. There is no sign-in. You set one GitHub token and Iris files every session's contributions under it. That costs per-user attribution and session isolation, and README § One GitHub identity, and no sign-in says exactly what that means.

Start it

git clone https://github.com/EqualifyEverything/equalify-iris.git
cd equalify-iris
cp .env.example .env          # fill in values
docker compose up

Two values in .env are not optional: IRIS_GITHUB_TOKEN (Iris refuses to start without it — it is the one identity the server files contributions under) and a credential for whichever model provider your config names. .env.example documents every variable and says which are optional and what leaving them blank means.

Then open http://localhost:8080/ for the browser app — upload page images, convert, read the accessible HTML, no API and no token needed. Or check the service directly:

curl http://localhost:8080/v1/health
# {"status":"ok","service":"equalify-iris","version":"1.0.0"}

On Linux, if your user is not uid 1000, run sudo chown -R 1000:1000 ./data first — the container runs as uid 1000 and ./data keeps its ownership from the host. If you skip it, the startup log tells you the command to run.

What a first version promises about /v1

The endpoints and response shapes in docs/API.md are the contract from here on. Within 1.x they gain fields but do not lose them or change what an existing one means; anything that would break a caller waits for 2.0. GET /v1/health reports the running build, so a deployment can be identified from outside.

Rate limits are enforced, not just documented, and every rate-limited response carries RateLimit and RateLimit-Policy headers a client can read its remaining budget from. GET /v1/health sits above the limiter on purpose, so a probe cannot report a deployment as down for asking too often. The quality tally at GET /v1/quality is off unless you set a secret for it.

What it costs

$0 to about 10.7¢ a page, and which one you get is a config choice. Iris ships no model — every model is named in your config, and an unconfigured provider throws rather than falling back to a default.

Point it at your own vLLM, ollama or llama.cpp server and there is no token bill at all. On the models this repo suggests, 100 scanned pages cost $10.70, measured end to end. docs/cost.md breaks that down per step, and docs/models.md says what each suggestion was measured on.

The two things this release does not measure

Stated plainly, because both are easy to assume from the numbers above:

1. The self-hosted open-weight path is unmeasured for quality. $0 in tokens is a real option and the code supports it, but nobody has benchmarked what an open-weight model does to the output. The agents that read page images need a model that accepts images.
2. One corpus. Every quality and cost figure comes from the same 100 scanned pages. It is a real document with real tables and real multi-column layout, and it is one document. Nothing here says how Iris behaves on born-digital PDFs, handwriting, non-English text, or anything else it has not been run against.

For anyone working on Iris, including agents

CONTRIBUTING.md and README § "Working on Iris" say which document to update for which change, and the four rules this repo has already paid for. Documentation here is concise plain language by requirement, not by preference.