# Private OCR API

Run the separate `ocr.api:app` ASGI application through an existing trusted ingress
or an explicitly approved loopback/Unix socket. It is not mounted into or started
by the existing Augmentoolkit application. Runtime settings are read from process
environment (Space secrets or Debian secret injection), never bundled in code.

All routes except `/health` require `Authorization: Bearer $OCR_DISPATCHER_TOKEN`.
`GET /ready` returns 200 only when CPU is warmed, otherwise 503. `/docs` and
`/openapi.json` provide the generated versioned schema. `/metrics` is authenticated
and returns content-free lane counters, queue depth, cold/warm latency percentiles.

| Method/path | Contract |
|---|---|
| POST `/v1/ocr/jobs` | Multipart `file`, `options` JSON; 202 with job/status/result URLs |
| GET `/v1/ocr/jobs/{id}` | queued/running/completed/partial/failed/cancelled, counts, timestamps, safe errors |
| GET `/v1/ocr/jobs/{id}/result` | `ocr-result/v1` JSON, only when a result is retained; 409 otherwise |
| DELETE `/v1/ocr/jobs/{id}` | Cancel pending work and purge retained result; no promise of undoing remote work |
| POST `/v1/ocr/page` | One image or one-page PDF, normalized `ocr-page/v1` result |
| POST `/v1/chat/completions` | Restricted single-image façade described below |

Use `Idempotency-Key` (max 128 characters) on job creation. Keys are scoped to the
authenticated service credential, not globally. Reuse with different effective
options/bytes returns 409. Multiple users sharing a token share that scope; this
is not a multi-tenant identity provider. 404 does not disclose another credential's
job. TTL eviction removes result/idempotency records. Errors include 401 auth,
403 unauthorized destination, 413 size, 422 input/backend errors, 429 capacity/rate,
409 result/idempotency state, 503 unavailable readiness.

```sh
# Existing private endpoint supplied by the operator; never use a guessed port.
curl --fail-with-body -H "Authorization: Bearer $OCR_DISPATCHER_TOKEN" \
  -F 'file=@public-example.pdf' \
  -F 'options={"mode":"cpu_only","sensitivity":"D0","output":"both"}' \
  "$OCR_DISPATCHER_URL/v1/ocr/jobs"
```

Options: `mode` (auto/cpu_only/gpu_only/quality/throughput), `sensitivity`, `output`
(text/markdown/structured/both), `language_hints`, `layout`, `preserve_boxes`,
`extract_pdf_text_layer`, `force_ocr`, `prefer_cpu`, `allow_external_cpu`,
`allow_gpu_overflow`, `max_pages`. Unknown fields are rejected. `output` selects
assembled text/Markdown fields; per-page source evidence remains in the envelope.
Language hints do not replace the pinned multilingual recognition model. CPU
preference is a hint subject to explicit mode, quality and capability requirements.

Results contain stable zero-based page indexes and SHA256-derived page identities,
engine/backend versions, sensitivity, normalized blocks, flags, route reasons,
attempt counts/timing/destinations and alternative evidence. Markdown delimiters
are one-based `<!-- page:1 -->`. Geometry is finite 0..1000 in source-raster
orientation. Missing geometry/confidence stays null; alias destination stays null
when not verifiable. No invented token usage or LightOn confidence.

The optional façade accepts `model: ocr-auto | ocr-cpu | ocr-gpu`, `stream:false`,
and exactly one user message containing exactly one image_url with
`data:image/png;base64,...` (JPEG/TIFF also supported). An `ocr_options` extension
can increase sensitivity or restrict routing. It returns standard non-streaming
chat choices plus an `ocr` provenance extension, without invented `usage`.
Arbitrary text messages, remote URLs, tools/functions, extra parameters, streaming
and PDFs are rejected. This is not full OpenAI API compatibility and does not
modify FreeLLMAPI. The raw JSON body cap makes effective inline-image capacity
slightly smaller than the 25 MiB binary multipart limit.

Worker API: separate token `OCR_CPU_AUTH_TOKEN`, `POST /internal/ocr/page` multipart
one raster image (`file`, optional bounded `request_id`, empty `{}` `options`).
`GET /internal/capabilities` returns conservative model capabilities. It admits one
inference at a time and rejects excess work, rather than accumulating an unbounded
queue. It does not receive FreeLLMAPI credentials or document classification policy.