generated from john/python-template
3.3 KiB
3.3 KiB
Document Transcription System Requirements (Version 3)
This document captures the Version 3 baseline requirements for the production implementation.
Requirements Model
| ID | Category | Requirement | Verify Method |
|---|---|---|---|
| REQ-0 | System | Provide end-to-end multi-page document transcription with persistent, inspectable async job states. | demonstration |
| REQ-1 | Functional | Allow users to upload multi-image batches as sequential Source pages under a Document. |
test |
| REQ-2 | Functional | Process multi-page jobs asynchronously using an asyncio worker pool bounded by rate limits. |
test |
| REQ-3 | Functional | Persist frozen submission-time execution parameters and full input prompts (system_prompt, user_prompt, prompt_name, prompt_hash, temperature, top_p) on Job, and persist page-level output responses (raw_transcription, ai_metadata, raw_api_response) on JobSource. |
test |
| REQ-4 | Functional | Support job states (queued, processing, completed, partial_success, failed) and page states (pending, transcribed, failed). |
inspection |
| REQ-5 | Functional | Allow users to manage historical Person records and link multiple authors/recipients to a Document via DocumentPerson. |
test |
| REQ-6 | Functional | Maintain immutable original machine output on Source.raw_transcription while permitting inline human edits on Source.revised_text. |
test |
| REQ-7 | Data Constraint | Use SQLModel/SQLAlchemy to preserve a portable relational domain model and compatible data shape across the supported backends, with SQLite for local development/testing and PostgreSQL as the production system of record. | inspection |
| REQ-8 | Data Constraint | Validate all API requests, database rows, and JSON structures using Pydantic V2 schemas and SQLModel. | test |
| REQ-9 | Interface | Render multi-page transcriptions sequentially by page_number in the web UI with author/recipient metadata. |
demonstration |
| REQ-10 | Operations | Allow operators to resubmit only failed pages for queued reprocessing while preserving the frozen prompt snapshot on the existing Job. |
test |
| REQ-11 | Data Constraint | Calculate and store cryptographic file hashes (SHA-256) and file sizes for uploaded source images to track asset integrity. | test |
| REQ-12 | Operations Constraint | Keep core development, testing, restore, and recovery workflows OS-independent across Windows, Linux, and macOS; do not require a platform-specific shell for canonical project processes. | inspection |
Element Satisfaction Mapping
- UI (NiceGUI): Satisfies REQ-1, REQ-5, REQ-6, REQ-9, REQ-10.
- API (FastAPI): Satisfies REQ-1, REQ-4, REQ-5, REQ-8.
- WORKER (asyncio): Satisfies REQ-2, REQ-3, REQ-4, REQ-10.
- PERSISTENCE (SQLModel/SQLAlchemy): Satisfies REQ-3, REQ-6, REQ-7, REQ-11.
- MODELS (Pydantic V2 / SQLModel): Satisfies REQ-8.
- OPERATIONS TOOLING (Python / OS-neutral automation): Satisfies REQ-12.
Related Local References
- System Overview
- System Design Intent
- Transcription Methodology
- System Architecture
- System Requirements (this document)
- Data model
- Error Handling Policy
- Implementation Plan