docs: add Docker/HF Spaces deployment plan and design spec

docs/superpowers/plans/2026-06-14-docker-hf-spaces-deployment.md

@@ -0,0 +1,428 @@
+# Docker / HF Spaces Deployment Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Containerize EuropaLex for zero-cost deployment on Hugging Face Spaces with CPU-only inference and baked-in model weights.
+
+**Architecture:** A single-stage Dockerfile downloads all four AI models at build time (using a HF token secret), installs CPU-only dependencies, and launches Gradio on port 7860. The existing `_auto_download_models()` in `app.py` already skips download when `.gguf` files exist, so no code changes are needed — the runtime simply finds the pre-baked models and starts instantly.
+
+**Tech Stack:** Docker (python:3.12-slim base), CPU-only PyTorch, llama-cpp-python (CPU backend), Hugging Face Hub CLI for model download.
+
+---
+
+### Task 1: Archive Current README
+
+**Files:**
+- Create: `docs/europalex-readme-old.md`
+- Modify: `README.md` (replaced in Task 2)
+
+- [ ] **Step 1: Copy current README to archive location**
+
+Run:
+```bash
+cp README.md docs/europalex-readme-old.md
+```
+
+This preserves the current development-focused README before replacing it with the deployment-focused version.
+
+- [ ] **Step 2: Verify the archive**
+
+Run:
+```bash
+diff <(head -5 README.md) <(head -5 docs/europalex-readme-old.md)
+# Should show no differences
+ls -la docs/europalex-readme-old.md
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add docs/europalex-readme-old.md
+git commit -m "docs: archive current README before Docker deployment rewrite"
+```
+
+---
+
+### Task 2: Create New Deployment-Focused README
+
+**Files:**
+- Modify: `README.md`
+
+Replace the entire file with:
+
+```markdown
+# EuropaLex — Docker / Hugging Face Spaces Deployment
+
+AI-powered flashcard generator for European languages, deployed as a Docker container on [Hugging Face Spaces](https://huggingface.co/spaces). All four AI models are baked into the image at build time — the app starts instantly with zero wait.
+
+> **CPU-only inference:** All inference runs on CPU. Expect slower performance (30+ seconds per sentence for translation, longer for TTS/images) in exchange for free hosting.
+
+## Quick Start: Deploy to HF Spaces
+
+1. **Create a new Space** on Hugging Face → select **Docker** as the framework
+2. **Upload these files** from this repository: `Dockerfile`, `.dockerignore`, and all project files (`app.py`, `core/`, `frontend/`, `models/`, `export/`, `configs/`)
+3. **Set secret** `HUGGING_FACE_HUB_TOKEN` in your Space settings (under **Secrets**) — this authenticates model download during the Docker build step
+4. **Push to repo** — Hugging Face automatically builds the image and deploys
+
+That's it. The first build takes ~5–15 minutes (downloading ~26 GB of models). Subsequent visits start instantly.
+
+## What Gets Deployed
+
+| Model | Role | Size | Runtime |
+|---|---|---|---|
+| MiniCPM5-1B Q8_0 | English text generation (Phase 1) | ~1.1 GB | llama-cpp-python |
+| tiny-aya-water Q4_K_M | Translation (Phase 2) | ~2.1 GB | llama-cpp-python |
+| OmniVoice Q8_0 | Text-to-speech audio | ~950 MB | omnivoice.cpp |
+| FLUX.2-klein 4B Q4_K_M | Image generation | ~2.6 GB | diffusers |
+
+**Total image size:** ~20–30 GB (models baked in at build time)
+
+## How It Works
+
+```
+Docker build:
+  python:3.12-slim → pip install CPU deps → huggingface-cli login (build secret) → download all models → CMD ["python", "app.py"]
+
+HF Spaces runtime:
+  Container starts → _auto_download_models() finds GGUF files → skips download → launches Gradio on :7860
+```
+
+The Dockerfile downloads all models during `docker build` using your HF token as a build secret. At runtime, the app detects pre-existing model files and skips download entirely — no authentication needed, no waiting.
+
+## CPU Performance Expectations
+
+| Operation | Expected Time |
+|---|---|
+| Phase 1: Generate 3 English sentences | ~30–60 seconds |
+| Phase 2: Translate 3 sentences (tiny-aya) | ~1–3 minutes |
+| Phase 2: TTS audio per sentence | ~5–15 seconds |
+| Phase 2: Image generation per card | ~30–60+ seconds |
+
+These are approximate and depend on the HF Spaces CPU tier. All features remain functional — just slower than a GPU setup.
+
+## Local Docker Testing (Optional)
+
+Build and test locally before deploying:
+
+```bash
+# Build the image (requires your HF token)
+docker build \
+  --secret id=hf_token,env=HUGGING_FACE_HUB_TOKEN \
+  -t europalex .
+
+# Run locally (port 7860)
+docker run -p 7860:7860 europalex
+```
+
+The container serves Gradio on `http://localhost:7860`. Press Ctrl+C to stop.
+
+## Architecture
+
+EuropaLex uses a two-phase generation workflow:
+
+1. **Phase 1** — Enter a scenario, select CEFR level (A0–C2), set batch size → MiniCPM5-1B generates English sentences
+2. **Phase 2** — Select target language, toggle Audio/Images → tiny-aya translates, OmniVoice generates TTS, FLUX generates illustrations
+
+Cards export as Anki `.apkg` files or zipped CSV folders with flat media files.
+
+## Repository Structure
+
+```
+EuropaLex/
+├── Dockerfile              # Single-stage build: deps + model download + Gradio launch
+├── .dockerignore           # Exclude .venv, .git, models from build context
+├── README.md               # This file — HF Spaces deployment guide
+├── app.py                  # Entry point — Gradio UI wiring, two-phase generation handlers
+├── pyproject.toml          # Project config (uv)
+├── requirements.txt        # pip install dependencies
+├── configs/settings.yaml   # App settings, model paths, batch defaults
+├── core/                   # Business logic
+│   ├── types.py            # Pydantic models: CardData, CEFRLevel, TextResult, etc.
+│   ├── engine.py           # MiniCPMTextEngine, LlamaCppTextEngine, EnginePool
+│   ├── audio_gen.py        # TTSEngine (OmniVoice)
+│   ├── image_gen.py        # ImageGenEngine (diffusers Flux2KleinPipeline)
+│   ├── text_gen.py         # Sentence extraction + generation with retry loop
+│   └── pipeline.py         # Phase 2 translation orchestration
+├── frontend/               # Gradio 6 UI
+│   ├── ui/
+│   │   ├── widgets.py      # Styled toggle checkbox wrappers, Blocks builder
+│   │   └── cards.py        # Card rendering, gallery layout, progress bar
+│   └── css/custom.css      # Plain-white theme, card styling, disabled states
+├── models/
+│   └── download_models.py  # HF Hub model downloader (runtime fallback)
+├── export/                 # Export formats
+│   ├── apkg_export.py      # Anki .apkg export via genanki
+│   ├── csv_export.py       # CSV zip export with flat media files
+│   └── anki_tunnel.py      # MCP tunnel sync for live Anki import
+├── docs/                   # Design specs and implementation plans
+│   └── superpowers/        # Planning documents
+└── tests/                  # Test suite (pytest)
+```
+
+## CEFR Levels
+
+`[A0, A1, A2, B1, B2, C1, C2]`
+
+- **A0:** Uses curated common words list (no text generation model needed)
+- **A1–C2:** MiniCPM5-1B generates English sentences at the selected level in Phase 1; tiny-aya-water translates them in Phase 2
+```
+
+- [ ] **Step 2: Write the new README**
+
+Write the content above to `README.md`, replacing all existing content.
+
+- [ ] **Step 3: Verify**
+
+Run:
+```bash
+head -5 README.md
+# Should show "# EuropaLex — Docker / HF Spaces Deployment"
+grep -c "Dockerfile\|HF Spaces\|HUGGING_FACE_HUB_TOKEN" README.md
+# Should be > 0 for each term
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md docs/europalex-readme-old.md
+git commit -m "docs: rewrite README for Docker/HF Spaces deployment"
+```
+
+---
+
+### Task 3: Create the Dockerfile
+
+**Files:**
+- Create: `Dockerfile`
+
+Create `Dockerfile` with these exact contents:
+
+```dockerfile
+# EuropaLex — Docker / Hugging Face Spaces Deployment
+# Single-stage build: CPU-only deps + model download + Gradio launch
+#
+# Build:
+#   docker build --secret id=hf_token,env=HUGGING_FACE_HUB_TOKEN -t europalex .
+#
+# Run (local test):
+#   docker run -p 7860:7860 europalex
+
+FROM python:3.12-slim
+
+# ─── System dependencies ───────────────────────────────────────────────
+# git for huggingface-cli, build-essential for llama-cpp-python compilation
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# ─── Build secret: Hugging Face token ──────────────────────────────────
+# Mounted at /run/secrets/hf_token during docker build.
+# Used to authenticate huggingface-cli download of gated models.
+RUN --mount=type=secret,id=hf_token \
+    if [ -f /run/secrets/hf_token ]; then \
+        echo "Authenticated as $(huggingface-cli whoami --token $(cat /run/secrets/hf_token) 2>/dev/null || echo 'unknown')"; \
+    else \
+        echo "WARNING: No HUGGING_FACE_HUB_TOKEN secret provided. Model download will fail for gated models."; \
+    fi
+
+# ─── CPU-only PyTorch ──────────────────────────────────────────────────
+# Install from the official CPU wheel index to avoid ~2 GB of CUDA deps.
+RUN pip install --no-cache-dir \
+    --extra-index-url https://download.pytorch.org/whl/cpu \
+    torch>=2.1.0
+
+# ─── llama-cpp-python (CPU backend, no CUDA flags) ─────────────────────
+# Build with default CPU backend — no CUDA/MKL flags needed on slim base.
+RUN pip install --no-cache-dir \
+    llama-cpp-python>=0.3.28
+
+# ─── Other Python dependencies ─────────────────────���───────────────────
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ─── Copy project source ───────────────────────────────────────────────
+COPY . /app
+WORKDIR /app
+
+# ─── Download models at build time ─────────────────────────────────────
+# Uses the HF token secret for authenticated downloads.
+# Models are baked into the image (~26 GB total).
+RUN --mount=type=secret,id=hf_token \
+    if [ -f /run/secrets/hf_token ]; then \
+        export HUGGING_FACE_HUB_TOKEN=$(cat /run/secrets/hf_token); \
+    fi && \
+    python -m models.download_models
+
+# ─── Launch ────────────────────────────────────────────────────────────
+EXPOSE 7860
+CMD ["python", "app.py"]
+```
+
+- [ ] **Step 1: Write the Dockerfile**
+
+Write the content above to `Dockerfile`.
+
+- [ ] **Step 2: Verify syntax**
+
+Run:
+```bash
+# Check Dockerfile syntax (requires docker)
+docker build --check -f Dockerfile . 2>&1 || echo "Docker not available — manual review required"
+```
+
+If Docker is not available, do a manual review:
+- Verify `FROM python:3.12-slim` is the first instruction
+- Verify `--mount=type=secret,id=hf_token` appears in both the auth check and model download steps
+- Verify CPU-only PyTorch uses `--extra-index-url https://download.pytorch.org/whl/cpu`
+- Verify `EXPOSE 7860` and `CMD ["python", "app.py"]` are at the end
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add Dockerfile
+git commit -m "feat: add Dockerfile for HF Spaces deployment (CPU-only)"
+```
+
+---
+
+### Task 4: Create `.dockerignore`
+
+**Files:**
+- Create: `.dockerignore`
+
+Create `.dockerignore` with these exact contents:
+
+```dockerignore
+# ─── Version control ───────────────────────────────────────────────────
+.git/
+.gitignore
+
+# ─── Virtual environment (not needed — Docker installs deps) ───────────
+.venv/
+venv/
+
+# ─── Python cache ──────────────────────────────────────────────────────
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+
+# ─── Model weights — downloaded inside Dockerfile, NOT from build context
+.local/models/
+
+# ─── Gradio cache ─────────────────────────────────────────────────────
+.gradio/
+
+# ─── OS files ──────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+
+# ─── Test output files (from tests/test_outputs/) ──────────────────────
+tests/test_outputs/
+
+# ─── Lock file — not needed inside container (pip install handles it) ──
+uv.lock
+
+# ─── Docs / plans (not needed at runtime) ──────────────────────────────
+docs/
+
+# ─── Agent conventions (not needed at runtime) ─────────────────────────
+AGENTS.md
+```
+
+- [ ] **Step 1: Write the .dockerignore**
+
+Write the content above to `.dockerignore`.
+
+- [ ] **Step 2: Verify it excludes key paths**
+
+Run:
+```bash
+grep -c "local/models" .dockerignore   # Should be 1
+grep -c ".venv" .dockerignore          # Should be >= 1
+grep -c "__pycache__" .dockerignore    # Should be 1
+grep -c "docs/" .dockerignore          # Should be 1
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .dockerignore
+git commit -m "feat: add .dockerignore for HF Spaces deployment"
+```
+
+---
+
+### Task 5: Final Verification
+
+**Files:**
+- All created files above
+
+- [ ] **Step 1: Verify all files exist and are non-empty**
+
+Run:
+```bash
+for f in Dockerfile .dockerignore README.md docs/europalex-readme-old.md; do
+    echo "$f: $(wc -l < $f) lines, $(wc -c < $f) bytes"
+done
+```
+
+Expected output:
+- `Dockerfile`: ~70 lines
+- `.dockerignore`: ~35 lines
+- `README.md`: ~120 lines (new deployment-focused version)
+- `docs/europalex-readme-old.md`: ~180 lines (archived original)
+
+- [ ] **Step 2: Verify the Dockerfile references correct paths**
+
+Run:
+```bash
+grep "models.download_models" Dockerfile    # Should find the download command
+grep "requirements.txt" Dockerfile           # Should find COPY + pip install
+grep "EXPOSE 7860" Dockerfile               # Should find port exposure
+grep 'CMD \["python"' Dockerfile            # Should find launch command
+```
+
+- [ ] **Step 3: Verify .dockerignore does NOT exclude files needed at runtime**
+
+Run:
+```bash
+# These should NOT appear in .dockerignore (they are needed):
+grep "app.py" .dockerignore && echo "FAIL: app.py excluded" || echo "OK: app.py not excluded"
+grep "core/" .dockerignore && echo "FAIL: core/ excluded" || echo "OK: core/ not excluded"
+grep "frontend/" .dockerignore && echo "FAIL: frontend/ excluded" || echo "OK: frontend/ not excluded"
+```
+
+- [ ] **Step 4: Final commit (if any uncommitted changes remain)**
+
+```bash
+git status
+git add -A
+git diff --cached --stat
+git commit -m "feat: Docker/HF Spaces deployment — Dockerfile, .dockerignore, README rewrite"
+```
+
+---
+
+## Self-Review Checklist
+
+1. **Spec coverage:** All four spec requirements are addressed — `Dockerfile` (Task 3), `.dockerignore` (Task 4), `README.md` replacement (Task 2), archived README (Task 1). No code changes needed because `_auto_download_models()` already skips download when GGUF files exist.
+
+2. **Placeholder scan:** No placeholders found. All file contents are complete with exact text.
+
+3. **Type consistency:** N/A — no code changes, only infrastructure and documentation files.
+
+4. **Dockerfile correctness:**
+   - `python:3.12-slim` base ✓
+   - Build-essential for llama-cpp-python compilation ✓
+   - CPU-only PyTorch via `--extra-index-url https://download.pytorch.org/whl/cpu` ✓
+   - `llama-cpp-python>=0.3.28` without CUDA flags ✓
+   - HF token build secret (`--mount=type=secret,id=hf_token`) ✓
+   - Model download via `python -m models.download_models` at build time ✓
+   - `EXPOSE 7860` and `CMD ["python", "app.py"]` ✓
+
+5. **`.dockerignore` correctness:**
+   - Excludes `.local/models/` (models downloaded inside Dockerfile) ✓
+   - Excludes `.venv/`, `__pycache__/`, test outputs, docs ✓
+   - Does NOT exclude `core/`, `frontend/`, `app.py`, `configs/` ✓

docs/superpowers/specs/2026-06-14-europalex-docker-hf-spaces-deployment-design.md

@@ -0,0 +1,65 @@
+# EuropaLex — Docker / Hugging Face Spaces Deployment
+
+**Date:** 2026-06-14  
+**Status:** Approved  
+**Scope:** Containerize EuropaLex for deployment on Hugging Face Spaces (CPU tier)
+
+## Overview
+
+EuropaLex is a Gradio-based flashcard generator that uses four local AI models (MiniCPM5-1B, tiny-aya-water, OmniVoice, FLUX.2-klein). This design specifies how to deploy it as a Docker container on Hugging Face Spaces with CPU-only inference, accepting slower performance in exchange for zero-cost hosting.
+
+## Design Decisions
+
+### 1. Keep All Four Models
+All four models are retained: MiniCPM5-1B (text generation), tiny-aya-water (translation), OmniVoice (TTS), FLUX.2-klein (image generation). CPU inference will be slow — expect 30+ seconds per sentence for translation and longer for TTS/image generation — but all features remain functional.
+
+### 2. Model Download at Docker Build Time
+Models are downloaded during the `docker build` step, not at runtime. The resulting image is ~20–30 GB but the app starts instantly when deployed to HF Spaces. This avoids timeout issues with HF Spaces' build limits and means users don't wait minutes on first visit.
+
+### 3. Single-Stage Dockerfile
+A single `Dockerfile` handles everything: base image, dependency installation, model download, and launch. No multi-stage complexity. HF Spaces handles large images without issue.
+
+### 4. Build-Time Hugging Face Token
+The `HUGGING_FACE_HUB_TOKEN` is passed as a Docker build secret (`--secret id=hf_token`). This authenticates the `huggingface-cli download` step during build time so models are baked into the image. No runtime authentication is needed.
+
+### 5. CPU-Only PyTorch
+PyTorch is installed from the official CPU wheel index (`https://download.pytorch.org/whl/cpu`) to avoid pulling in ~2 GB of CUDA dependencies. llama-cpp-python is built with the default CPU backend (no CUDA flags). diffusers and omnivoice fall back to CPU automatically when no GPU is available.
+
+## Files to Create / Modify
+
+| File | Action | Purpose |
+|---|---|---|
+| `Dockerfile` | **Create** | Single-stage build: deps + model download + Gradio launch |
+| `.dockerignore` | **Create** | Exclude `.venv/`, `.git/`, `__pycache__/`, test outputs, large binaries. Explicitly exclude `.local/models/` from build context (models downloaded inside Dockerfile). |
+| `README.md` | **Replace** | New README focused on HF Spaces deployment instructions |
+| `docs/europalex-readme-old.md` | **Create** | Archive of current README for reference |
+
+## Data Flow
+
+```
+Docker build:
+  python:3.12-slim → pip install deps → huggingface-cli login (build secret) → download models → CMD ["python", "app.py"]
+
+HF Spaces runtime:
+  Container starts → _auto_download_models() checks .local/models/ → finds GGUF files → skips download → launches Gradio on :7860
+```
+
+## Error Handling
+
+- **Model download failure at build time:** Docker build fails with a clear error. User knows immediately, not after deploying to HF Spaces.
+- **Missing HF token:** Build fails with `huggingface-cli` auth error. Documented in README as a known setup step.
+- **CPU OOM at runtime:** If RAM is insufficient, PyTorch/llama-cpp-python will fail gracefully. `app.py` already has try/except around engine initialization that surfaces errors to the Gradio UI.
+
+## HF Spaces Configuration (Documented in New README)
+
+User workflow:
+1. Create a new Hugging Face Space → select **Docker** framework
+2. Upload `Dockerfile`, `.dockerignore`, and project files
+3. Set secret `HUGGING_FACE_HUB_TOKEN` in Space settings (under Secrets)
+4. Push to repo — HF builds the image automatically
+
+## Constraints
+
+- **CPU performance:** All inference runs on CPU. Translation of a batch of 3 sentences may take 1–3 minutes. TTS and image generation are slower still. This is acceptable for a free-tier demo.
+- **Image size:** ~20–30 GB due to model weights baked in. HF Spaces handles this, but the initial build takes longer (5–15 minutes).
+- **No GPU acceleration:** FLUX.2-klein and OmniVoice are designed for GPU. CPU inference will be very slow but functional.