feat(deps): migrate backend packaging from pip/Poetry to uv

Replace the dual-manifest setup (Poetry-format pyproject.toml that nothing
installed from + requirements.txt that everything installed from) with a
single PEP 621 pyproject.toml and a committed uv.lock:

- pyproject.toml: PEP 621 [project] with the requirements.txt ranges as
  truth (Poetry file was missing tenacity, the SSO stack, and
  cryptography), PEP 735 dev dependency group, [tool.uv] package=false
  (the API is an app, not an installable package). Dead [tool.black] and
  [tool.isort] sections removed — pre-commit already enforces ruff +
  ruff-format; [tool.ruff] added (line-length 88, py312).
- uv.lock: first real lockfile for the backend (85 packages).
- requirements.txt: deleted.
- ci.yml: SHA-pinned astral-sh/setup-uv + `uv sync --locked`; .venv/bin
  goes on GITHUB_PATH so existing bare pytest invocations are untouched.
- security.yml: pip-audit now audits `uv export --locked --no-dev` — the
  dependency set that actually ships, not a loose manifest.
- Dockerfile.backend: uv-based builder (uv 0.10.0, UV_COMPILE_BYTECODE,
  UV_PYTHON_DOWNLOADS=never); the `pip uninstall pip` hack is gone since
  uv venvs contain no pip.
- dependabot.yml: pip -> uv ecosystem for /apps/api, same groups.
- package.json test:api:* scripts and docs updated to `uv run`.
- .python-version pins 3.12 to match CI and Docker.

Verified: full backend suite 1254 passed / 33 skipped / 11 xfailed under
uv + Python 3.12; Docker image builds and serves {"ready":true} on
/ready; uv export + pip-audit runs clean (no known vulnerabilities).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: gr8monk3ys

.github/dependabot.yml

@@ -1,7 +1,7 @@
 version: 2
 updates:
-  # Backend Python dependencies
-  - package-ecosystem: "pip"
+  # Backend Python dependencies (uv.lock + pyproject.toml)
+  - package-ecosystem: "uv"
     directory: "/apps/api"
     schedule:
       interval: "weekly"

.github/workflows/ci.yml

@@ -32,13 +32,16 @@ jobs:
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-          cache-dependency-path: apps/api/requirements.txt
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt pytest pytest-asyncio pytest-cov
+          uv sync --locked
+          echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
 
       - name: Run smoke suite (blocking)
         run: |
@@ -119,13 +122,16 @@ jobs:
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-          cache-dependency-path: apps/api/requirements.txt
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt pytest pytest-asyncio
+          uv sync --locked
+          echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
 
       - name: Run full backend tests
         run: pytest -q
@@ -352,13 +358,16 @@ jobs:
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-          cache-dependency-path: apps/api/requirements.txt
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt pytest pytest-asyncio
+          uv sync --locked
+          echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
 
       # Apply db/migrations so the asyncpg-backed services have their tables.
       - name: Apply db/migrations

.github/workflows/security.yml

@@ -29,16 +29,15 @@ jobs:
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: ${{ env.PYTHON_VERSION }}
-          cache: pip
-          cache-dependency-path: apps/api/requirements.txt
 
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt pip-audit
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Export locked runtime dependencies
+        run: uv export --locked --no-dev --no-hashes --format requirements-txt -o /tmp/requirements-audit.txt
 
       - name: Run pip-audit
-        run: pip-audit --strict --desc
+        run: uvx --python "$PYTHON_VERSION" pip-audit --strict --desc --no-deps -r /tmp/requirements-audit.txt
 
   bun-audit:
     name: Frontend Dependency Audit

CLAUDE.md

@@ -27,11 +27,10 @@ bun run audit:runtime    # Runtime audit policy
 
 ```bash
 cd apps/api
-python -m venv .venv && source .venv/bin/activate
-pip install -r requirements.txt
-python server.py                    # Start FastAPI on :8000
-pytest -q                           # Run all backend tests
-pytest tests/test_ci_smoke.py -q    # Quick smoke tests only
+uv sync                                    # Install deps into .venv from uv.lock
+uv run python server.py                    # Start FastAPI on :8000
+uv run pytest -q                           # Run all backend tests
+uv run pytest tests/test_ci_smoke.py -q    # Quick smoke tests only
 ```
 
 From repo root:
@@ -50,10 +49,10 @@ cd apps/web && bunx vitest run tests/lib/api.test.ts
 cd apps/web && bunx playwright test e2e/navigation.spec.ts
 
 # Backend (pytest) — single file
-cd apps/api && pytest tests/test_blog.py -q
+cd apps/api && uv run pytest tests/test_blog.py -q
 
 # Backend — single test function
-cd apps/api && pytest tests/test_blog.py::test_function_name -q
+cd apps/api && uv run pytest tests/test_blog.py::test_function_name -q
 ```
 
 ### Pre-PR checks
@@ -133,9 +132,9 @@ The frontend uses `NEXT_PUBLIC_API_URL` (default `http://localhost:8000` in dev)
 
 ## Conventions
 
-- **Package manager**: Bun for the frontend workspace. Python pip/poetry for the backend.
+- **Package manager**: Bun for the frontend workspace. **uv** for the backend (`apps/api/pyproject.toml` + `uv.lock` are the single source of truth; there is no requirements.txt).
 - **Commit messages**: Conventional prefixes (`feat:`, `fix:`, `docs:`, `chore:`).
-- **Python formatting**: Black (line-length 88) + isort (black profile) + Ruff. Pre-commit hooks enforce this.
+- **Python formatting/linting**: Ruff only (line-length 88, `ruff format` + `ruff check`, configured in `apps/api/pyproject.toml`). Black and isort are retired. Pre-commit runs the ruff hooks on changed files; note the repo carries pre-existing ruff debt in unchanged files (the required `precommit` CI check runs only hygiene hooks, not ruff).
 - **TypeScript linting**: ESLint flat config (`eslint.config.mjs`) with `@typescript-eslint`, Next.js core-web-vitals, and react-hooks rules. `no-explicit-any` is warn-level.
 - **Testing**: Vitest (jsdom) for frontend unit tests, Playwright for E2E, pytest for backend. Frontend coverage uses `all: true` (measures every source file) with a **ratchet floor** set to the current real baseline (~10%) that only moves up toward the branches 70% / functions+lines+statements 85% target — never lower the thresholds to make a build pass (see `docs/REMEDIATION_PLAN.md`).
 - **Turbopack**: Default bundler in dev. E2E tests use `--webpack` flag for stability.

CONTRIBUTING.md

@@ -22,10 +22,8 @@ Start the backend:
 
 ```bash
 cd apps/api
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python server.py
+uv sync                  # installs Python 3.12 deps into .venv from uv.lock
+uv run python server.py
 ```
 
 Start the web app from the repository root:
@@ -50,7 +48,7 @@ For backend changes, also run:
 
 ```bash
 bun run test:api:smoke
-cd apps/api && pytest -q
+cd apps/api && uv run pytest -q
 ```
 
 For UI or user-flow changes, also run:

Dockerfile.backend

@@ -14,13 +14,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     build-essential \
     && rm -rf /var/lib/apt/lists/*
 
-RUN python -m venv /opt/venv
-ENV PATH="/opt/venv/bin:$PATH"
+COPY --from=ghcr.io/astral-sh/uv:0.10.0 /uv /uvx /bin/
+
+# uv builds the venv at /opt/venv from the lockfile; it contains no pip at all.
+ENV UV_PROJECT_ENVIRONMENT=/opt/venv \
+    UV_PYTHON_DOWNLOADS=never \
+    UV_COMPILE_BYTECODE=1
 
-COPY apps/api/requirements.txt ./
-RUN pip install --no-cache-dir --upgrade pip && \
-    pip install --no-cache-dir -r requirements.txt && \
-    pip uninstall -y pip
+COPY apps/api/pyproject.toml apps/api/uv.lock ./
+RUN uv sync --locked --no-dev
 
 # -----------------------------------------------------------------------------
 # Stage 2: Runtime - lean production image

README.md

@@ -72,10 +72,8 @@ Minimum local values:
 
 ```bash
 cd apps/api
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-python server.py
+uv sync                  # installs Python 3.12 deps into .venv from uv.lock
+uv run python server.py
 ```
 
 ### 4. Start the web app

apps/api/.python-version

@@ -0,0 +1 @@
+3.12

apps/api/pyproject.toml

@@ -1,64 +1,67 @@
-[tool.poetry]
+[project]
 name = "blog-ai"
 version = "0.1.0"
 description = "AI-driven solution for generating blog posts and books"
-authors = ["Lorenzo"]
+authors = [{ name = "Lorenzo" }]
 license = "AGPL-3.0-only"
 readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "tenacity>=9.1.4",
+    "openai>=2.15.0",
+    "anthropic>=0.76.0",
+    "google-generativeai>=0.3.1",
+    "requests>=2.31.0",
+    "pydantic>=2.5.2,<3.0.0",
+    "pydantic-settings>=2.1.0",
+    "python-dotenv>=1.0.0",
+    # Image generation (Stability AI uses REST API via httpx, no SDK needed)
+    "Pillow>=12.1.1",
+    # Transitive dependency pins (Dependabot security alerts)
+    "starlette>=0.47.2",  # CVE: DoS via multipart/form-data (transitive via fastapi)
+    "protobuf>=5.29.6",  # CVE: JSON recursion depth bypass (transitive via google-generativeai)
+    # Backend server
+    "fastapi>=0.115.0,<1.0.0",
+    "uvicorn>=0.27.0,<1.0.0",
+    "websockets>=12.0",
+    "python-multipart>=0.0.9",
+    "uvloop>=0.19.0; platform_system != 'Windows'",
+    # Postgres driver (Neon / managed Postgres)
+    "asyncpg>=0.29.0",
+    # Security
+    "bcrypt>=4.0.0,<5.0.0",
+    "nh3>=0.2.14",
+    # SSO (Single Sign-On)
+    "python3-saml>=1.16.0",  # SAML 2.0 support
+    "authlib>=1.7.2",  # OIDC/OAuth2 support
+    "httpx>=0.27.0,<1.0.0",  # Async HTTP client for OIDC
+    "PyJWT>=2.13.0",  # JWT token validation
+    "cryptography>=50.0.0,<51.0.0",  # CVE fixes + certificate handling
+    # Redis for job storage
+    "redis>=5.0.0",
+    # Payment processing
+    "stripe>=7.0.0",
+    # Monitoring and error tracking
+    "sentry-sdk[fastapi]>=1.40.0",
+]
 
-[tool.poetry.dependencies]
-python = "^3.12"
-openai = "^2.15.0"
-anthropic = "^0.76.0"
-google-generativeai = ">=0.3.1"
-requests = "^2.31.0"
-pydantic = "^2.5.2"
-pydantic-settings = "^2.1.0"
-python-dotenv = "^1.0.0"
-fastapi = ">=0.115.0,<1.0.0"
-uvicorn = "^0.27.0"
-websockets = "^12.0"
-python-multipart = "^0.0.9"
-uvloop = { version = "^0.19.0", markers = "platform_system != 'Windows'" }
-
-# Transitive dependency pins (security)
-starlette = ">=0.47.2"  # CVE fix: DoS via multipart
-protobuf = ">=5.29.6"  # CVE fix: JSON recursion bypass
-
-# Database client (Neon / managed Postgres)
-asyncpg = "^0.29.0"
-
-# Image generation (Stability AI uses REST API via httpx, no SDK needed)
-Pillow = ">=12.1.1"
-httpx = "^0.27.0"
-
-# Security
-bcrypt = "^4.0.0"
-nh3 = "^0.2.14"
-
-# Redis for job storage
-redis = "^5.0.0"
-
-# Payment processing
-stripe = "^7.0.0"
-
-# Monitoring and error tracking
-sentry-sdk = { version = "^1.40.0", extras = ["fastapi"] }
+[dependency-groups]
+dev = [
+    "pytest>=8.2,<10",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=6.0.0",
+    "mypy>=1.5.1",
+    "ruff>=0.9.10",
+]
 
-[tool.poetry.group.dev.dependencies]
-pytest = ">=8.2,<10"
-pytest-asyncio = "^1.3.0"
-black = "^24.3.0"
-isort = "^7.0.0"
-mypy = "^1.5.1"
+[tool.uv]
+# The API is an application (server.py + app/ + src/), not an installable
+# package — uv sync installs only the dependencies.
+package = false
 
-[tool.black]
+[tool.ruff]
 line-length = 88
-target-version = ["py312"]
-
-[tool.isort]
-profile = "black"
-line_length = 88
+target-version = "py312"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
@@ -68,7 +71,3 @@ markers = [
     "security: marks tests as security-related",
     "slow: marks tests as slow-running",
 ]
-
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"