generated from john/python-template
116 lines
2.9 KiB
Markdown
116 lines
2.9 KiB
Markdown
# Transcription
|
|
|
|
Historical document transcription system for family-history documents.
|
|
|
|
The app lets you upload a document image/PDF, queues a background transcription job, and then shows job status and results in a web UI.
|
|
|
|
## What the app does
|
|
|
|
- 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
|
|
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
### 2) Configure environment
|
|
|
|
Create a `.env` file in the project root (minimum required setting shown):
|
|
|
|
```env
|
|
OPENROUTER_API_KEY=your_openrouter_api_key
|
|
```
|
|
|
|
Optional settings (defaults shown):
|
|
|
|
```env
|
|
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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](http://[IP_ADDRESS]:8000/ui)
|
|
- Health check: [http://[IP_ADDRESS]:8000/healthz](http://[IP_ADDRESS]:8000/healthz)
|
|
|
|
### Schema safety settings
|
|
|
|
Optional environment settings (defaults shown):
|
|
|
|
```env
|
|
MIGRATION_AUTO_APPLY_ON_STARTUP=false
|
|
VALIDATE_SCHEMA_ON_STARTUP=true
|
|
```
|
|
|
|
### Step 5 security settings
|
|
|
|
Use this baseline for trusted private-network operation:
|
|
|
|
```env
|
|
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`
|