Operations

Running locally

pip install -e .
mkdocs build --strict
PORT=8000 python -m nirog_ocr_ops.main

The application serves the generated Material for MkDocs site at / and the operational API at /api/v1.

Deployment

The production container builds the documentation with the Python MkDocs package and starts the Python composition root. It accepts the hosting-provided PORT environment variable. No browser-facing worker secret is used.

Core-authorized live workflow

When NIROG_LIVE_EVIDENCE_ENABLED=true and all server-only Core, dispatcher, and Gemini settings are present, Core's outbox dispatcher delivers evidence.ocr.requested.v1 to the private POST /internal/ocr/events endpoint. The event contains only Core profile, evidence, OCR-job, and correlation identifiers and is authenticated with the dispatcher secret.

OCR Ops creates an idempotent operational job, leases the Core job, exchanges the lease for a short-lived evidence URL, processes the evidence in memory through the schema-constrained Gemini adapter, and reports the bounded extraction result back to Core. Evidence bytes are not saved in the OCR Ops database, logs, or documentation site. The resulting packet remains provisional until an explicit human actor confirms or rejects it.

Only a human-confirmed packet may be sent to Core's correlation-bound receipt endpoint. That receipt contains identifiers, provenance, reviewer reference, hashed reason, and versions only. It never contains evidence bytes, document text, candidate lists, or diagnostic context.

Medication index and lab flows

The medication index lives in a dedicated Postgres database (Neon) configured by MEDICATION_INDEX_DATABASE_URL (pooled endpoint for runtime reads) and is loaded fully into memory at startup — roughly 12 seconds for the full 21.6K-variant catalog, longer after Neon autosuspend; size health-check grace periods accordingly. Bulk seeding uses the unpooled endpoint:

python scripts/seed_medication_index.py path/to/medicine_bd.csv --version 2026-08

Incremental entries arrive through POST /api/v1/index/import or the /lab page and are matchable immediately. The nightly alias promotion job must be scheduled by the platform (idempotent, advisory-locked):

python scripts/run_alias_promotion.py

The evaluation harness (scripts/run_eval.py) runs the extraction and matching pipeline against annotated prescription images in eval/ and gates on certain-line recall; see the repository README for the answer-key format.

Required server settings

Setting	Purpose
GEMINI_API_KEY	Paid Gemini credential, available only to the OCR Ops server.
GEMINI_MODEL	Optional model override; defaults to the verified gemini-3.6-flash.
GEMINI_DISAMBIGUATION_MODEL	Constrained multiple-choice model for ambiguous names; defaults to gemini-3.1-flash-lite.
GEMINI_THINKING_BUDGET	Optional positive integer; unset keeps full model thinking (~7s/image), 128–512 effectively disables it (~2s/image). Validated at startup.
MEDICATION_INDEX_DATABASE_URL	Neon Postgres medication index (pooled endpoint). Takes precedence over MEDICATION_INDEX_CSV.
LOG_LEVEL	Application log level; extracted prescription text never enters logs.
NIROG_LIVE_EVIDENCE_ENABLED	Explicitly enables the Core-authorized live processing path.
NIROG_CORE_INTERNAL_URL	Core private API base URL for leases, evidence access, results, and receipts.
NIROG_INTERNAL_WORKER_SECRET	Shared Core/OCR Ops server identity for Core worker endpoints.
NIROG_DISPATCHER_TO_WORKER_SECRET	Optional dedicated Core dispatcher identity; otherwise the internal worker identity is used for the OCR Ops internal event endpoint.

Managed preview runner

The managed preview environment expects a pnpm run dev entrypoint from its original scaffold. The root package.json is therefore a dependency-free launcher only: its dev script delegates directly to python3 -m nirog_ocr_ops.main. It does not add a Node application runtime, JavaScript source, or Node production dependency; the production Docker entrypoint remains Python-native.

Verification gates

python -m unittest discover -s tests -v
python -m nirog_ocr_ops.migrate
mkdocs build --strict
python -m compileall -q src

Use the API’s OpenAPI view and the generated documentation site for interface verification. The previous bespoke dashboard is not part of this design.

Documentation template

This site uses Material for MkDocs, a Python-installed documentation framework that builds a searchable static documentation site from Markdown. The official setup documents installation through pip and static-site generation through mkdocs build; see Getting started and Creating your site.

Schema migration workflow

Checked-in SQL files under migrations/ are discovered in version order by python -m nirog_ocr_ops.migrate. The runner stores a SHA-256 checksum in ocr_ops_schema_migrations; an edited applied migration stops the process rather than silently altering persistence history. Deployments execute this command before starting the API.