Update documentation for consistency and refactor the code. An unresolved error in testing still exists.

tests/integration/test_pipeline_flow.py

@@ -3,12 +3,12 @@
 from pathlib import Path
 
 import pytest
-from sqlmodel import select
 
 from transcription.config import Settings
-from transcription.models import Job, JobStatus, Transcript
+from transcription.models import Job
+from transcription.models import JobStatus
 from transcription.providers.base import TranscriptionResult
-from transcription.services.upload import create_upload_job
+from transcription.services.store import create_upload_job
 from transcription.worker import process_next_queued_job
 
 
@@ -16,61 +16,64 @@ from transcription.worker import process_next_queued_job
 class TestPipelineSuccessFlow:
     """Verify end-to-end success lifecycle behavior."""
 
-    def test_upload_then_worker_persists_transcribed_terminal_state(self, session, tmp_path: Path, monkeypatch):
-        """Upload followed by worker processing persists transcript and transcribed status."""
+    @pytest.mark.asyncio
+    async def test_upload_then_worker_persists_transcribed_terminal_state(
+        self, async_session, tmp_path: Path, monkeypatch
+    ):
+        """Upload followed by worker processing persists job transcription and transcribed status."""
         settings = Settings(openrouter_api_key="test-key", upload_dir=tmp_path)
-        upload_result = create_upload_job(
+        upload_result = await create_upload_job(
             filename="pipeline.jpg",
             file_bytes=b"pipeline-bytes",
-            session=session,
+            session=async_session,
             settings=settings,
         )
 
-        def _fake_transcribe(_path: str) -> TranscriptionResult:
-            return TranscriptionResult(text="Pipeline transcript", provider="openrouter", model="test-model")
+        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")
 
-        monkeypatch.setattr("transcription.worker.transcribe_document_image", _fake_transcribe)
+        monkeypatch.setattr("transcription.services.transcription.OpenRouterTranscriptionProvider.transcribe", _fake_transcribe)
 
-        processed = process_next_queued_job(session=session)
-        job = session.get(Job, upload_result.job_id)
-        transcript = session.exec(select(Transcript).where(Transcript.job_id == upload_result.job_id)).first()
+        processed = await process_next_queued_job(session=async_session)
+        job = await async_session.get(Job, upload_result.job_id)
 
         assert processed is True
         assert job is not None
         assert job.status == JobStatus.TRANSCRIBED
-        assert transcript is not None
-        assert transcript.text == "Pipeline transcript"
-        assert transcript.error_detail is None
+        assert job.text == "Pipeline transcript"
+        assert job.error_detail is None
 
 
 @pytest.mark.integration
 class TestPipelineFailureFlow:
     """Verify end-to-end failure lifecycle behavior."""
 
-    def test_upload_then_worker_persists_failed_terminal_state(self, session, tmp_path: Path, monkeypatch):
-        """Upload followed by worker processing persists error detail and failed status."""
+    @pytest.mark.asyncio
+    async def test_upload_then_worker_persists_failed_terminal_state(self, async_session, tmp_path: Path, monkeypatch):
+        """Upload followed by worker processing persists error detail and failed status on the job."""
         settings = Settings(openrouter_api_key="test-key", upload_dir=tmp_path)
-        upload_result = create_upload_job(
+        upload_result = await create_upload_job(
             filename="pipeline.jpg",
             file_bytes=b"pipeline-bytes",
-            session=session,
+            session=async_session,
             settings=settings,
         )
 
-        def _fake_transcribe(_path: str) -> TranscriptionResult:
+        async def _fake_transcribe(*, prompt_text: str, image_bytes: bytes, mime_type: str) -> TranscriptionResult:
+            _ = (prompt_text, image_bytes, mime_type)
             raise RuntimeError("pipeline provider failure")
 
-        monkeypatch.setattr("transcription.worker.transcribe_document_image", _fake_transcribe)
+        monkeypatch.setattr("transcription.services.transcription.OpenRouterTranscriptionProvider.transcribe", _fake_transcribe)
 
-        processed = process_next_queued_job(session=session)
-        job = session.get(Job, upload_result.job_id)
-        transcript = session.exec(select(Transcript).where(Transcript.job_id == upload_result.job_id)).first()
+        processed = await process_next_queued_job(session=async_session)
+        job = await async_session.get(Job, upload_result.job_id)
 
         assert processed is True
         assert job is not None
         assert job.status == JobStatus.FAILED
-        assert transcript is not None
-        assert transcript.text is None
-        assert "pipeline provider failure" in transcript.error_detail
-        assert "[internal_unexpected_error]" in transcript.error_detail
-        assert "error_id=" in transcript.error_detail
+        assert job.text is None
+        assert job.error_detail is not None
+        assert "pipeline provider failure" in job.error_detail
+        assert "[internal_unexpected_error]" in job.error_detail
+        assert "error_id=" in job.error_detail