generated from john/python-template
46 lines
3.3 KiB
Markdown
46 lines
3.3 KiB
Markdown
# 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](index_v3.md)
|
|
- [System Design Intent](invariant/intent.md)
|
|
- [Transcription Methodology](invariant/transcription_methodology.md)
|
|
- [System Architecture](architecture_v3.md)
|
|
- System Requirements (this document)
|
|
- [Data model](schema_v3.md)
|
|
- [Error Handling Policy](error_handling_v3.md)
|
|
- [Implementation Plan](implementation_plan_v3.md)
|
|
|
|
|