README.md

metadata

title: EuropaLex
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: docker
sdk_version: latest
python_version: '3.12'
app_file: app.py
pinned: false
tags:
  - track:backyard
  - sponsor:openbmb
  - achievement:offgrid
  - achievement:offbrand
  - achievement:llama
  - achievement:sharing

EuropaLex — Docker / Hugging Face Spaces Deployment

AI-powered flashcard generator for European languages, deployed as a Docker container on Hugging Face 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.

Model weights

Model	HF Hub Repo	GGUF File	Runtime	Params	Size	Role
MiniCPM5-1B Q8_0	Abiray/MiniCPM5-1B-GGUF	minicpm5-1b-Q8_0.gguf	llama-cpp-python	1.08 B	~1.1 GB	English text generation (Phase 1)
tiny-aya-water Q4_K_M	CohereLabs/tiny-aya-water-GGUF	tiny-aya-water-q4_k_m.gguf	llama-cpp-python	3.35 B	~2.1 GB	Translation (active)
OmniVoice Q8_0 (base + tokenizer)	Serveurperso/OmniVoice-GGUF	omnivoice-base-Q8_0.gguf + omnivoice-tokenizer-Q8_0.gguf	omnivoice.cpp	0.6 B	~950 MB	Text-to-speech
FLUX.2-klein 4B Q4_K_M	unsloth/FLUX.2-klein-4B-GGUF	flux-2-klein-4b-Q4_K_M.gguf	diffusers	4 B	~2.6 GB	Image generation

Links

Social Media Post

Traces

Demo Video

The demo works on my machine, two days to figure out how to deploy and still was stuck.

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:

# 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)