Merge branch 'development' into deck-pitch

Author: marcvergees

.github/workflows/lint.yml

@@ -19,10 +19,11 @@ jobs:
         with:
           python-version: "3.11"
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
       - name: Install linter
-        run: |
-          python -m pip install --upgrade pip
-          pip install ruff
+        run: uv pip install --system ruff
 
       - name: Run linter
         run: |

.github/workflows/tests.yml

@@ -18,13 +18,20 @@ jobs:
         with:
           python-version: "3.11"
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
+        run: uv pip install --system -r requirements.txt
 
       - name: Run tests
         env:
           PYTHONPATH: .
         run: |
-          python -m pytest tests/ -v --tb=short
+          python -m pytest tests/ -v --tb=short
+
+      - name: Check for un-migrated model changes
+        env:
+          PYTHONPATH: .
+        run: |
+          python -m alembic check

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help init fireform build up down logs logs-app logs-ollama shell pull-model test clean super-clean
+.PHONY: help init fireform build up down logs logs-app logs-ollama shell pull-model test clean super-clean status ready-banner sync
 
 COMPOSE     = docker compose -f docker/dev/compose.yml --env-file docker/.env.dev
 ENV_DEV     = docker/.env.dev
@@ -22,13 +22,17 @@ help:
 	@echo "make build        - Build Docker images"
 	@echo "make up           - Start all containers (detached)"
 	@echo "make down         - Stop all containers"
+	@echo "make sync         - Fast-install new requirements.txt deps into running app (no rebuild)"
+	@echo "make status       - Show compact container health summary"
 	@echo "make logs         - Stream all container logs"
 	@echo "make logs-app     - Stream app container logs"
 	@echo "make logs-ollama  - Stream Ollama container logs"
 	@echo "make logs-worker  - Stream Celery worker logs"
 	@echo "make shell        - Open shell in running app container"
 	@echo "make pull-model   - Pull Ollama model from .env.dev ($(OLLAMA_MODEL))"
 	@echo "make test         - Run test suite"
+	@echo "make migrate      - Run pending Alembic migrations"
+	@echo "make migration    - Generate new migration (msg='description')"
 	@echo "make clean        - Stop containers (preserves volumes)"
 	@echo "make super-clean  - [CAUTION] Stop containers, delete volumes, prune Docker"
 
@@ -44,30 +48,38 @@ init:
 		*) echo "Run 'make fireform' when ready." ;; \
 	esac
 
-fireform: build up
-	@printf "Waiting for Ollama to be ready..."
-	@until $(COMPOSE) exec -T ollama ollama list > /dev/null 2>&1; do \
-		printf '.'; sleep 2; \
-	done
-	@echo " ready."
+fireform:
+	@$(COMPOSE) up -d --build
 	@if $(COMPOSE) exec -T ollama ollama list 2>/dev/null | grep -q "^$(OLLAMA_MODEL)"; then \
 		echo "  Model $(OLLAMA_MODEL) already pulled."; \
 	else \
 		echo "  Pulling $(OLLAMA_MODEL)..."; \
 		$(COMPOSE) exec -T ollama ollama pull $(OLLAMA_MODEL); \
 	fi
-	@echo ""
-	@echo "FireForm is ready!"
-	@echo "   API:      http://localhost:8000"
-	@echo "   API Docs: http://localhost:8000/docs"
-	@echo ""
-	@echo "Run 'make logs' to view live logs, 'make down' to stop."
+	@$(MAKE) --no-print-directory ready-banner
 
 build:
 	@$(COMPOSE) build
 
 up:
 	@$(COMPOSE) up -d
+	@$(MAKE) --no-print-directory ready-banner
+
+# Fast path for "I added a package": install the delta into the running container
+# (no image rebuild, no 1.6GB layer re-export). uv installs only what's missing in
+sync:
+	@$(COMPOSE) exec -T app sh -c "UV_TORCH_BACKEND=cpu uv pip install --system -r requirements.txt"
+
+status:
+	@$(COMPOSE) ps --format 'table {{.Service}}\t{{.Status}}'
+
+ready-banner:
+	@echo ""
+	@echo "FireForm is ready!"
+	@echo "   API:      http://localhost:8000"
+	@echo "   API Docs: http://localhost:8000/docs"
+	@echo ""
+	@echo "Run 'make logs' to view live logs, 'make down' to stop."
 
 down:
 	@$(COMPOSE) down --remove-orphans
@@ -93,6 +105,12 @@ pull-model:
 test:
 	@$(COMPOSE) exec -T app python3 -m pytest tests/ -v
 
+migrate:
+	@$(COMPOSE) exec -T app alembic upgrade head
+
+migration:
+	@$(COMPOSE) exec -T app alembic revision --autogenerate -m "$(msg)"
+
 clean:
 	@$(COMPOSE) down
 

alembic.ini

@@ -0,0 +1,37 @@
+[alembic]
+script_location = alembic
+prepend_sys_path = .
+path_separator = os
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/env.py

@@ -0,0 +1,51 @@
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from sqlmodel import SQLModel
+
+from app.core.config import DATABASE_URL
+from app.models import FormSubmission, Job, Template 
+
+config = context.config
+
+if not config.get_main_option("sqlalchemy.url"):
+    config.set_main_option("sqlalchemy.url", DATABASE_URL)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = SQLModel.metadata
+
+
+def run_migrations_offline():
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online():
+    connectable = config.attributes.get("connection", None)
+
+    if connectable is None:
+        connectable = engine_from_config(
+            config.get_section(config.config_ini_section, {}),
+            prefix="sqlalchemy.",
+            poolclass=pool.NullPool,
+        )
+        with connectable.connect() as connection:
+            context.configure(connection=connection, target_metadata=target_metadata)
+            with context.begin_transaction():
+                context.run_migrations()
+    else:
+        context.configure(connection=connectable, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

alembic/versions/001_initial_schema.py

@@ -0,0 +1,64 @@
+"""Initial schema — Template, FormSubmission, and Job tables.
+
+Revision ID: 001
+Revises:
+Create Date: 2026-06-22
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+revision: str = "001"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "template",
+        sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+        sa.Column("name", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("fields", sa.JSON, nullable=False),
+        sa.Column("pdf_path", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("created_at", sa.DateTime, nullable=False),
+    )
+
+    op.create_table(
+        "formsubmission",
+        sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+        sa.Column("template_id", sa.Integer, sa.ForeignKey("template.id"), nullable=False),
+        sa.Column("input_text", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("output_pdf_path", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("created_at", sa.DateTime, nullable=False),
+    )
+
+    op.create_table(
+        "job",
+        sa.Column("id", sa.Integer, primary_key=True, autoincrement=True),
+        sa.Column("job_id", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("celery_task_id", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("job_type", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("template_id", sa.Integer, sa.ForeignKey("template.id"), nullable=True),
+        sa.Column("input_text", sqlmodel.sql.sqltypes.AutoString, nullable=True),
+        sa.Column("status", sqlmodel.sql.sqltypes.AutoString, nullable=False),
+        sa.Column("progress_percent", sa.Integer, nullable=False),
+        sa.Column("result_url", sqlmodel.sql.sqltypes.AutoString, nullable=True),
+        sa.Column("error", sa.JSON, nullable=True),
+        sa.Column("model", sqlmodel.sql.sqltypes.AutoString, nullable=True),
+        sa.Column("created_at", sa.DateTime, nullable=False),
+        sa.Column("updated_at", sa.DateTime, nullable=False),
+    )
+    op.create_index("ix_job_job_id", "job", ["job_id"], unique=True)
+    op.create_index("ix_job_celery_task_id", "job", ["celery_task_id"], unique=False)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_job_celery_task_id", table_name="job")
+    op.drop_index("ix_job_job_id", table_name="job")
+    op.drop_table("job")
+    op.drop_table("formsubmission")
+    op.drop_table("template")

app/db/init_db.py

@@ -1,24 +1,37 @@
 import datetime
 import logging
+from pathlib import Path
 
-from sqlmodel import Session, SQLModel, select
+from alembic import command
+from alembic.config import Config
+from sqlmodel import Session, select
 
 from app.core.config import DEFAULT_TEMPLATE_DIR
 from app.db.database import engine
-
 from app.models import FormSubmission, Template  # noqa: F401
 
 logger = logging.getLogger(__name__)
 
+ALEMBIC_INI = str(Path(__file__).resolve().parents[2] / "alembic.ini")
+
+
+def _alembic_cfg() -> Config:
+    cfg = Config(ALEMBIC_INI)
+    return cfg
+
+
+def run_migrations():
+    logger.info("Running Alembic migrations...")
+    command.upgrade(_alembic_cfg(), "head")
+    logger.info("Migrations complete.")
+
 
 def seed_db():
     with Session(engine) as session:
-        # Check if we already have templates
         statement = select(Template)
         try:
             results = session.exec(statement).first()
         except Exception:
-            # Table might not exist yet if called at a weird time
             results = None
 
         if not results:
@@ -33,7 +46,6 @@ def seed_db():
                 "Date": "string",
             }
 
-            # Using ID 2 as agreed to avoid any ID 1 corruption
             default_template = Template(
                 id=2,
                 name="Manual Test Template",
@@ -47,7 +59,7 @@ def seed_db():
 
 
 def init_db():
-    SQLModel.metadata.create_all(engine)
+    run_migrations()
     seed_db()
 
 

app/models/models.py

@@ -8,7 +8,7 @@
 class Template(SQLModel, table=True):
     id: int | None = Field(default=None, primary_key=True)
     name: str
-    fields: dict = Field(sa_column=Column(JSON))
+    fields: dict = Field(sa_column=Column(JSON, nullable=False))
     pdf_path: str
     created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))