bbchops/transcription
1
0
Fork 0
generated from john/python-template
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

Revised and simplified V4 Plan and core documents.

Browse Source
This commit is contained in:
Jim Lancaster
2026-08-10 10:53:13 -05:00
parent 9b4d6f0340
commit 4b3baf5a3e
7 changed files with 495 additions and 578 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ver4/index_v4.md
+28 -37
View File
@@ -1,49 +1,40 @@
# Document-Person Expansion Overview (Version 4)
# Document Transcription System Overview (Version 4)
Version 4 defines the relationship-model evolution track for linking `Document` and `Person` entities with extensible roles, suggestion review, and policy enforcement.
This project is a personal-scale application for transcribing, organizing, and preserving historical documents, images, and related people records.
## Start Here
Read [scope_boundary_v4.md](scope_boundary_v4.md) first to confirm scope and non-scope before implementation work begins.
Read [architecture_v4.md](architecture_v4.md) first for the technical overview and system design.
## Core V4 Capabilities
## Core Capabilities
- Extensible relationship role taxonomy.
- Many-people-per-role linking for documents.
- Explicit distinction between canonical asserted links and pending suggested links.
- Human-in-the-loop suggestion accept/reject workflow.
- Role exclusivity policy enforcement for configured role pairs.
- Role/state-aware API and UI retrieval/presentation behavior.
- Minimal document type governance rollout for the current corpus, with one-time manual mapping and no alias helper table.
- Folder and multi-image ingestion into sequential `Source` pages under a single `Document`.
- Parallel asynchronous AI vision transcription using Python `asyncio` bounded by rate limits.
- Portable relational storage using SQLModel and SQLAlchemy across SQLite and PostgreSQL.
- Complete prompt and response provenance for every transcription job and page execution.
- File-integrity tracking through SHA-256 hashing and stored file sizes.
- Historical `Person` management with many-to-many document links and extensible relationship roles.
- Registry-driven `DocumentType` classification with stable codes and controlled selection.
- Inline human revision of transcribed pages while preserving immutable machine output.
- Partial-failure recovery for multi-page jobs.
- Cross-platform operational workflows driven by Python-based tooling.
## V4 Documentation Index
## Technical Stack
- [Scope Boundary](scope_boundary_v4.md)
- Application Web Framework: FastAPI + NiceGUI
- Persistence Engine: SQLModel / SQLAlchemy
- Data Validation and Schemas: Pydantic V2
- Concurrency and Workers: Python `asyncio`
- Vision Providers: OpenAI, Anthropic, and OpenRouter adapters
## Core Documentation Index
- [System Architecture](architecture_v4.md)
- [System Requirements](requirements_v4.md)
- [Data Model](schema_v4.md)
- [System Architecture](architecture_v4.md)
- [Error Handling Policy](error_handling_v4.md)
## Transition Documents
- [Scope Boundary](scope_boundary_v4.md)
- [Implementation Plan](implementation_plan_v4.md)
## Relationship To V3
V3 remains the baseline production architecture and requirements set for transcription pipeline behavior. V4 is an additive evolution track focused on document-person relationship semantics and workflows.
## Decision Status
Locked decisions:
1. Role extensibility uses registry tables.
2. Suggestion storage uses a separate suggestion table.
3. Exclusivity baseline is `author` vs `recipient` exclusive, with `mentioned` non-exclusive.
4. API evolution is additive in development mode with explicit deprecate-then-remove behavior.
Remaining decision:
1. Suggestion generation strategy (deterministic rules/NLP vs LLM extraction).
## Related Local References
- [V3 System Overview](../index_v3.md)
- [V3 Requirements](../requirements_v3.md)
- [V3 Schema](../schema_v3.md)