Begin implementation of Step 1. Implementation interrupted when I ran out of credits at openrouter. Credits added. Now trying to figure out how to restart the process...

src/transcription/config.py

@@ -0,0 +1,77 @@
+"""Centralized application configuration.
+
+All settings are loaded from environment variables (or a .env file)
+once at startup. Provider-specific defaults (model names, base URLs)
+are resolved by the provider adapters, not here.
+"""
+
+import logging
+import logging.config
+from enum import StrEnum
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Provider(StrEnum):
+    OPENROUTER = "openrouter"
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # --- AI provider ---
+    provider: Provider = Provider.OPENROUTER
+    openrouter_api_key: str
+    provider_model: str | None = None
+    openrouter_http_referer: str | None = None
+    openrouter_app_title: str | None = None
+
+    # --- persistence ---
+    database_url: str = "sqlite:///./transcription.db"
+
+    # --- filesystem paths ---
+    upload_dir: Path = Path("./uploads")
+    prompt_dir: Path = Path("./prompts")
+
+
+LOGGING_CONFIG: dict[str, object] = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "standard": {
+            "format": "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        }
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": "standard",
+            "stream": "ext://sys.stdout",
+        }
+    },
+    "root": {
+        "level": "INFO",
+        "handlers": ["console"],
+    },
+}
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return the singleton Settings instance.
+
+    Cached so the entire application shares one validated config.
+    """
+    return Settings()
+
+
+def setup_logging() -> None:
+    """Configure root logging once at startup."""
+    logging.config.dictConfig(LOGGING_CONFIG)

src/transcription/db.py

@@ -0,0 +1,39 @@
+"""Database engine, session factory, and schema bootstrap.
+
+MVP uses SQLite with auto-create-tables at startup.
+PostgreSQL migration is a post-MVP configuration change.
+"""
+
+import contextlib
+from collections.abc import Generator
+
+from sqlmodel import Session, SQLModel, create_engine
+
+from transcription.config import get_settings
+
+
+def _build_engine():
+    settings = get_settings()
+    connect_args = {}
+    if settings.database_url.startswith("sqlite"):
+        connect_args["check_same_thread"] = False
+    return create_engine(
+        settings.database_url,
+        echo=False,
+        connect_args=connect_args,
+    )
+
+
+engine = _build_engine()
+
+
+def create_all() -> None:
+    """Create all tables. Called once at application startup."""
+    SQLModel.metadata.create_all(engine)
+
+
+@contextlib.contextmanager
+def get_session() -> Generator[Session]:
+    """Yield a database session and ensure cleanup."""
+    with Session(engine) as session:
+        yield session

src/transcription/models.py

@@ -0,0 +1,65 @@
+"""SQLModel domain models for the transcription system.
+
+Three models capture the MVP lifecycle:
+  Document  ->  one-to-many  ->  Job  ->  one-to-one  ->  Transcript
+"""
+
+from datetime import datetime, timezone
+from enum import StrEnum
+from uuid import UUID, uuid4
+
+from sqlmodel import Field, Relationship, SQLModel
+
+
+class JobStatus(StrEnum):
+    QUEUED = "queued"
+    PROCESSING = "processing"
+    TRANSCRIBED = "transcribed"
+    FAILED = "failed"
+
+
+class Document(SQLModel, table=True):
+    """An uploaded document image."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    filename: str
+    file_path: str
+    uploaded_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    # --- relationships ---
+    jobs: list["Job"] = Relationship(back_populates="document")
+
+
+class Job(SQLModel, table=True):
+    """A transcription job tied to a single document."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    document_id: UUID = Field(foreign_key="document.id")
+    status: JobStatus = Field(default=JobStatus.QUEUED)
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    # --- relationships ---
+    document: Document = Relationship(back_populates="jobs")
+    transcript: "Transcript | None" = Relationship(back_populates="job")
+
+
+class Transcript(SQLModel, table=True):
+    """The output of a transcription job."""
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    job_id: UUID = Field(foreign_key="job.id", unique=True)
+    text: str | None = None
+    error_detail: str | None = None
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )
+
+    # --- relationships ---
+    job: Job = Relationship(back_populates="transcript")