Upload document files (.jpg, .jpeg, .png, .tif, .tiff, .pdf)
Persist document + job records in SQLite
Process jobs in a background worker (queued -> processing -> transcribed/failed)
Store transcript text (or failure detail)
Show status and results in the NiceGUI interface

Quick start

1) Install dependencies

uv sync

2) Configure environment

Create a .env file in the project root (minimum required setting shown):

OPENROUTER_API_KEY=your_openrouter_api_key

Optional settings (defaults shown):

DATABASE_URL=sqlite:///./transcription.db
UPLOAD_DIR=./uploads
PROMPT_DIR=./prompts
MAX_UPLOAD_BYTES=15728640
OPERATOR_ACCESS_ENABLED=false
OPERATOR_USERNAME=operator
# OPERATOR_PASSWORD=replace_with_secure_value

3) Run the app

uv run uvicorn transcription.app:create_app --factory --reload

4) (Optional) Run explicit migrations/checks

Use the migration runner for Step 4 schema safety workflows:

uv run python -m transcription.migration_runner --list
uv run python -m transcription.migration_runner --apply
uv run python -m transcription.migration_runner --check

5) Open in browser

GUI: http://[IP_ADDRESS]:8000/ui
Health check: http://[IP_ADDRESS]:8000/healthz

Schema safety settings

Optional environment settings (defaults shown):

MIGRATION_AUTO_APPLY_ON_STARTUP=false
VALIDATE_SCHEMA_ON_STARTUP=true

Step 5 security settings

Use this baseline for trusted private-network operation:

OPERATOR_ACCESS_ENABLED=true
OPERATOR_USERNAME=operator
OPERATOR_PASSWORD=replace_with_strong_local_secret
MAX_UPLOAD_BYTES=15728640

Notes:

/healthz remains unauthenticated for operational checks.
/ui and /api require HTTP Basic credentials when operator access is enabled.
Keep OPERATOR_PASSWORD in environment variables only (never commit secrets).

How to navigate the GUI

Upload page (/ui)
- Select a supported file to upload.
- The app creates a queued transcription job.
- Use the View jobs link to inspect progress.
Jobs page (/ui/jobs)
- See all jobs and their status.
- Use Refresh to reload current states.
- Open a specific job to see details.
Job detail page (/ui/jobs/{job_id})
- Shows job metadata and status.
- Displays transcript text when successful.
- Displays failure detail when transcription fails.

Prompt artifacts

Prompt files are stored in prompts/ and loaded from PROMPT_DIR (default: ./prompts).

The canonical MVP prompt is:

prompts/transcribe_document.md