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
WORKER_MAX_RETRIES=0
WORKER_RETRY_BACKOFF_SECONDS=0
WORKER_PROVIDER_TIMEOUT_SECONDS=20
WORKER_MIN_TRANSCRIPTION_CHARS=0
WORKER_MIN_TRANSCRIPTION_LINES=0
WORKER_FAIL_ON_FINISH_REASON_LENGTH=false

3) Run the app

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

4) Open in browser

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

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