V1 mostly complete except for some testing. Linting in the last step changed nearly every file which is why this commit is so larger.

tests/api/test_error_responses.py

@@ -1,11 +1,12 @@
 """Tests for API error response envelope handlers."""
 
+import pytest
 from fastapi import FastAPI
 from fastapi.testclient import TestClient
-import pytest
 
 from transcription.api.errors import register_error_handlers
-from transcription.errors import AppError, ErrorCategory
+from transcription.errors import AppError
+from transcription.errors import ErrorCategory
 
 
 @pytest.mark.integration

tests/artifacts/transcriptions/Book_Two_-_page_02.jpg.txt

@@ -11,11 +11,11 @@ BOOK 1 had 54 pages; 14 chapters. BOOK 2 has 70 pages; 18 chapters. BOOK 1 con-
 sisted largely of first generation family history. BOOK 2 throws more light on
 the second generation. Sidney promises a BOOK 3 and that may begin to do justice
 to the third generation. We suggest that Sidney get the help of Louis Shinn
-who has a chapter in this book (Chapter 16 - The Last 25 Years on the Doumeeq
+who has a chapter in this book (Chapter 16 - The Last 25 Years on the Doumecq
 Plains. Louis has the gift of seeing, recalling and telling. One sentence in
-his chapter gives a great tribute to the Doumeeqers - so far as he knows no one
-on the Doumeeq Plains went on relief during the depression. That in a nutshell
-shows the sturdy character of the residents of the Doumeeq Plains.
+his chapter gives a great tribute to the Doumeccqers--so [sic] far as he knows no one
+on the Doumecq Plains went on relief during the depression. That in a nutshell
+shows the sturdy character of the residents of the Doumecq Plains.
 
 We promised in BOOK 1 that in BOOK 2 we would give the story of the trip of
 John E. Cochran and wife to Tennessee, Cuba and the Panama Canal. You will see

tests/artifacts/transcriptions/Omie_Writes_Home.pdf.txt

@@ -18,7 +18,6 @@ the family newsletter two years ago.
 
 Nome Alaska August 26, 1923
 My Dear Ethel et al.
-
 I don't know when I did write or when you did
 but I am going to write now however and never
 the less. But I wish I could talk (I can yet but I
@@ -27,7 +26,6 @@ and Polly sit up and listen and that little black
 rascal of yours would fairly sparkle with
 listening. Can't I see him listening now to all the
 yarns we told last summer?
-
 You see, we-Miss Saville and I, took a trip north
 on the Buford and it was very interesting. We
 went north thru the Bering Strait into the Arctic and as far as the Ice Pack. There the captain
@@ -43,14 +41,14 @@ all around it similar to a currycomb in coarseness; no ears but huge tusks of iv
 the most repulsive looking animals imaginable and tho I have always read about them I never
 expect such disagreeable looking creatures. They had a rough brown hairy skin and some of
 them looked warty. They must have weighed two ton at least. Ere we got them back to Nome
-to the natives they were getting extremely odiferous–in fact, you could scarcely stay on the
+to the natives they were getting extremely odiferous—in fact, you could scarcely stay on the
 ship with any degree of comfort unless you had per chance lost your sense of smell.
 
-Then we went north to a few minutes beyond the 70th degree of latitude and thot [sic] for awhile
-we would go to Wrangell Island where some men from Stefflonsons [sic] ship were supposed to be
-stranded but we didn't get there and instead stopped at a small native village at Cape Serdz [sic] in
+Then we went north to a few minutes beyond the 70th degree of latitude and thot for awhile
+we would go to Wrangell Island where some men from Steffonsons ship were supposed to be
+stranded but we didn't get there and instead stopped at a small native village at Cape Serdz in
 Siberia. These Eskimo were very primitive. One white squaw man lived there and had for 23
-years. He was a Swede–who else could. Their houses were circular and built up with dirt 2 or
+years. He was a Swede--who else could. Their houses were circular and built up with dirt 2 or
 3 feet and then skins were stretched over it and weighted down with rocks. Inside, the room
 was partitioned off at the sides with skins for sleeping quarters. In the main part they had the
 fire on the ground and the fish drying on lines and the skins hanging around and the dogs and
@@ -65,22 +63,22 @@ The other place we stopped was at Whalen, a trading post in Siberia. There these
 went wild. They rushed helter-skelter, hither and thither, here and there, trying to find
 something to buy. Prices raised right before your eyes. One would but something for $1.00
 and the next might have to pay $2.00, $4.00 or $10.00. That made no difference. They had to
-have it. One man I was sort of taking care of, tho [sic] he had his son along for the purpose,
-bought 2 ivory tusks, 1 pup, 2 moccasins, 3 or 4 billi[illegible]s, 6 or 8 ivory and silver rings, one
+have it. One man I was sort of taking care of, tho he had his son along for the purpose,
+bought 2 ivory tusks, 1 pup, 2 moccasins, 3 or 4 billikens, 6 or 8 ivory and silver rings, one
 fishing line, hooks, floats, etc. and two bird slings. The slings have rocks at the end and the
 little natives throw them at the flocks of geese and ducks which fly close over the village and
 the slings entangle their wings and legs, sometimes more than one, and they can't fly. They
-come down and the natives capture them. There was more junk brot [sic] aboard than baggage, I
+come down and the natives capture them. There was more junk brot aboard than baggage, I
 do believe. And they say that at the first stop it was worse than here. The red flag was flying
-over Whalen and the Russian soldiers were there–a few, one or two or three, I forget the
+over Whalen and the Russian soldiers were there—a few, one or two or three, I forget the
 number.
 
 We got home yesterday morning at 5 a.m. but missed the first lighter in so had to stay out
 until 2:30. The girls had prepared a big meal for us and invited up the Hartfords and then let
 us talk. Miss Saville talked quite a bit. Any how if you folks don't like this I don't care, it is
-all I had to write about and I know Buster'd [sic] listen anyway and I'd soak ole Peter's head if he
+all I had to write about and I know Buster'ud listen anyway and I'd soak ole Peter's head if he
 didn't and Polly would in my lap and I don't know much about the youngest one of yours so
-likely he would be squawling. But we did surely enjoy our trip and were gone just long enuf [sic].
+likely he would be squawling. But we did surely enjoy our trip and were gone just long enuf.
 
 I expect there were 150 passengers on board and almost or more of the crew and helpers. We
 had a stateroom down next to the kitchen and 'twas pretty fierce for odor at times.
@@ -109,7 +107,7 @@ Ome
 
 Reprinted from Cochran Chronicles, Volume 9, Number 1, November 1986
 
-© [inserted: JECFA] 1986
+© JECFA 1986
 
 Up
 

tests/artifacts/transcriptions/Rod_Moser_Letter_-_p1.jpg.txt

@@ -8,24 +8,23 @@ ISBILL & MOSER
 DEALERS IN
 GENERAL MERCHANDISE
 
-Vonore, Tenn., Jany 27- 1913
-Dear Much Aunt Louie
-How are you a
-few nights ago I sewed a
-letter from your folks, so
+Vonore, Tenn. Jany 27- 1913
+Dear Much Aunt Adeline
+Was at home a
+few nights ago & saw a
+letter from your folks. So
 I decided to write you
 a few lines myself ok
-I am contemplateing a
+I am contemplateing [sic] a
 trip out west next summer
-& I want Some Olders to go
-where I and them.
-
-I am getting
+& [inserted: I] want some of them to go
+when I am [inserted: a] them.
+Am getting
 up in years & unmarried
 so you see the object of
-my trip, is to get a bunch
-of Young & old maids
-& widows out there. I
+my trip, is to get a wife
+& if there is any old maids
+or widows out there, I
 want you to kiss them
-at my fans [sic] mug as they
-as soon as I get there
+at my [hand?] me at there
+as soon as I get there.

tests/integration/test_pipeline_flow.py

@@ -31,7 +31,12 @@ class TestPipelineSuccessFlow:
 
         async def _fake_transcribe(*, prompt_text: str, image_bytes: bytes, mime_type: str) -> TranscriptionResult:
             _ = (prompt_text, image_bytes, mime_type)
-            return TranscriptionResult(text="Pipeline transcript", provider="openrouter", model="test-model", prompt_name="transcribe_document.md")
+            return TranscriptionResult(
+                text="Pipeline transcript",
+                provider="openrouter",
+                model="test-model",
+                prompt_name="transcribe_document.md",
+            )
 
         async def _fake_transcribe_document_image(
             image_path,

tests/providers/test_openrouter.py

@@ -5,8 +5,10 @@ from types import SimpleNamespace
 import pytest
 
 from transcription.config import Settings
-from transcription.providers.base import ProviderError, ProviderResponseError
-from transcription.providers.openrouter import DEFAULT_OPENROUTER_MODEL, OpenRouterTranscriptionProvider
+from transcription.providers.base import ProviderError
+from transcription.providers.base import ProviderResponseError
+from transcription.providers.openrouter import DEFAULT_OPENROUTER_MODEL
+from transcription.providers.openrouter import OpenRouterTranscriptionProvider
 
 
 class _FakeChat:

tests/services/test_job_service.py

@@ -25,7 +25,11 @@ class TestJobService:
         assert fetched.document.id == document.id
 
     @pytest.mark.asyncio
-    async def test_update_job_state_updates_status_and_retry(self, job_service: JobService, document_service: DocumentService):
+    async def test_update_job_state_updates_status_and_retry(
+        self,
+        job_service: JobService,
+        document_service: DocumentService,
+    ):
         document = Document(id=uuid4(), name="test-bundle")
         await document_service.create_document(document=document)
 

tests/services/test_transcription_external.py

@@ -7,7 +7,6 @@ import pytest
 
 from transcription.services.transcription import transcribe_document_image
 
-
 HAS_OPENROUTER_KEY = bool(os.getenv("OPENROUTER_API_KEY"))
 
 REAL_IMAGES_DIR = Path(__file__).resolve().parents[1] / "fixtures" / "images" / "real"
@@ -68,4 +67,4 @@ class TestRealImageExternalTranscription:
             f"{result.text}\n"
         )
         artifact_path.write_text(artifact_text, encoding="utf-8")
-        assert artifact_path.exists()
+        assert artifact_path.exists()

tests/services/test_transcription_service.py

@@ -0,0 +1,85 @@
+"""Tests for revision behavior in TranscriptionService."""
+
+from uuid import uuid4
+
+import pytest
+
+from transcription.models import Document
+from transcription.models import Job
+from transcription.models import JobStatus
+from transcription.models import Source
+from transcription.services.documents import DocumentService
+from transcription.services.jobs import JobService
+from transcription.services.transcription import TranscriptionService
+
+
+@pytest.mark.integration
+class TestTranscriptionServiceRevisionUpsert:
+    """Verify optional single-revision create/update semantics."""
+
+    @pytest.mark.asyncio
+    async def test_upsert_revision_creates_new_revision(self, default_session_factory):
+        documents = DocumentService(session_factory=default_session_factory)
+        jobs = JobService(session_factory=default_session_factory)
+        transcriptions = TranscriptionService(session_factory=default_session_factory)
+
+        document = Document(id=uuid4(), name="revision-create")
+        await documents.create_document(document=document)
+
+        job = Job(document_id=document.id, status=JobStatus.TRANSCRIBED, text="Original text")
+        await jobs.create_job(job=job)
+
+        source = Source(
+            document_id=document.id,
+            job_id=job.id,
+            upload_name="source.jpg",
+            filename="source.jpg",
+            file_path="uploads/source.jpg",
+        )
+        async with transcriptions._session_scope() as session:
+            session.add(source)
+            await session.commit()
+            await session.refresh(source)
+
+        revision = await transcriptions.upsert_revision_for_source(source_id=source.id, text="User revision")
+        fetched = await transcriptions.read_revision_by_source(source.id)
+
+        assert revision.source_id == source.id
+        assert revision.text == "User revision"
+        assert fetched is not None
+        assert fetched.id == revision.id
+        assert fetched.text == "User revision"
+
+    @pytest.mark.asyncio
+    async def test_upsert_revision_updates_existing_single_revision(self, default_session_factory):
+        documents = DocumentService(session_factory=default_session_factory)
+        jobs = JobService(session_factory=default_session_factory)
+        transcriptions = TranscriptionService(session_factory=default_session_factory)
+
+        document = Document(id=uuid4(), name="revision-update")
+        await documents.create_document(document=document)
+
+        job = Job(document_id=document.id, status=JobStatus.TRANSCRIBED, text="Original text")
+        await jobs.create_job(job=job)
+
+        source = Source(
+            document_id=document.id,
+            job_id=job.id,
+            upload_name="source.jpg",
+            filename="source.jpg",
+            file_path="uploads/source.jpg",
+        )
+        async with transcriptions._session_scope() as session:
+            session.add(source)
+            await session.commit()
+            await session.refresh(source)
+
+        first = await transcriptions.upsert_revision_for_source(source_id=source.id, text="Revision v1")
+        second = await transcriptions.upsert_revision_for_source(source_id=source.id, text="Revision v2")
+        revisions = await transcriptions.list_revisions_by_job(job.id)
+
+        assert first.id == second.id
+        assert second.text == "Revision v2"
+        assert len(revisions) == 1
+        assert revisions[0].id == first.id
+        assert revisions[0].text == "Revision v2"

tests/services/test_workflows_reliability.py

@@ -22,9 +22,21 @@ class TestWorkflowReliability:
     async def test_process_queued_job_timeout_marks_job_failed(self, default_session_factory, monkeypatch):
         """Provider timeout transitions a queued job to failed with error detail."""
         services = ServiceBundle()
-        object.__setattr__(services, "documents", services.documents.__class__(session_factory=default_session_factory))
-        object.__setattr__(services, "jobs", services.jobs.__class__(session_factory=default_session_factory))
-        object.__setattr__(services, "transcriptions", services.transcriptions.__class__(session_factory=default_session_factory))
+        object.__setattr__(
+            services,
+            "documents",
+            services.documents.__class__(session_factory=default_session_factory),
+        )
+        object.__setattr__(
+            services,
+            "jobs",
+            services.jobs.__class__(session_factory=default_session_factory),
+        )
+        object.__setattr__(
+            services,
+            "transcriptions",
+            services.transcriptions.__class__(session_factory=default_session_factory),
+        )
 
         async with services.jobs._session_scope() as session:
             document = Document(id=uuid4(), name="timeout-doc")

tests/test_config.py

@@ -5,7 +5,8 @@ from pathlib import Path
 import pytest
 from pydantic import ValidationError
 
-from transcription.config import Provider, Settings
+from transcription.config import Provider
+from transcription.config import Settings
 
 
 def _make_settings(**overrides) -> Settings:

tests/test_errors.py

@@ -2,7 +2,10 @@
 
 import pytest
 
-from transcription.errors import AppError, ErrorCategory, classify_unexpected_error, new_error_id
+from transcription.errors import AppError
+from transcription.errors import ErrorCategory
+from transcription.errors import classify_unexpected_error
+from transcription.errors import new_error_id
 
 
 @pytest.mark.unit

tests/test_models.py

@@ -5,7 +5,11 @@ from uuid import UUID
 import pytest
 from sqlalchemy.exc import IntegrityError
 
-from transcription.models import Document, Job, JobStatus, Revision, Source
+from transcription.models import Document
+from transcription.models import Job
+from transcription.models import JobStatus
+from transcription.models import Revision
+from transcription.models import Source
 
 
 def _make_document(**overrides) -> Document:

tests/test_prompts.py

@@ -2,7 +2,6 @@
 
 from pathlib import Path
 
-
 PROMPT_PATH = Path("prompts/transcribe_document.md")
 
 

tests/ui/test_jobs_page.py

@@ -71,3 +71,37 @@ class TestPageRendering:
 
         assert response.status_code == 200
         assert "Job not found" in response.text
+
+    def test_job_detail_page_shows_revision_editor_when_none_exists(self, app_client, seed_job):
+        """GET /ui/jobs/{job_id} renders revision editor and create action for sources with no revision."""
+        _, client = app_client
+        job_id = seed_job(
+            filename="no-revision.pdf",
+            status=JobStatus.TRANSCRIBED,
+            transcription_text="original text",
+            revision_text=None,
+        )
+
+        response = client.get(f"/ui/jobs/{job_id}")
+
+        assert response.status_code == 200
+        assert "Revision Editor" in response.text
+        assert "Create revision" in response.text
+        assert "No revision exists for this source." in response.text
+
+    def test_job_detail_page_shows_update_action_for_existing_revision(self, app_client, seed_job):
+        """GET /ui/jobs/{job_id} renders revision editor with update action when revision exists."""
+        _, client = app_client
+        job_id = seed_job(
+            filename="with-revision.pdf",
+            status=JobStatus.TRANSCRIBED,
+            transcription_text="original text",
+            revision_text="hello",
+        )
+
+        response = client.get(f"/ui/jobs/{job_id}")
+
+        assert response.status_code == 200
+        assert "Revision Editor" in response.text
+        assert "Update revision" in response.text
+        assert "hello" in response.text