feat: M0 walking skeleton (app, service protocols, CI/CD, Space deploy)

- Gradio app: one tab per skill + diagnostics tab with LLM ping
- Provider-agnostic services via typing.Protocol + tested fakes
(single OpenAI-compatible LLM client: Gemini/Mistral/Ollama/OpenAI)
- Env-driven config (pydantic-settings), offline-safe defaults
- CI: ruff + pytest, Docker image pushed to GHCR on main
- Repo sync workflow to HF Space (Docker SDK, cpu-basic)
- ADRs: stack & architecture, LLM provider strategy, datasets & licensing

.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.venv
+.env*
+data
+models
+mlruns
+docs
+evals
+scripts
+tests
+training
+.pytest_cache
+.ruff_cache
+.gradio
+__pycache__
+*.md
+!README.md

.env.example

@@ -0,0 +1,29 @@
+# Copy to .env for local dev. Never commit .env (gitignored).
+# On the HF Space, set these in Settings > Variables and secrets.
+
+# --- App ---
+APP_ENV=dev                      # dev | prod
+LOG_LEVEL=INFO
+
+# --- Languages (per-learner override comes in M3) ---
+DEFAULT_SOURCE_LANG=fr
+DEFAULT_TARGET_LANG=en
+
+# --- LLM (provider-agnostic via OpenAI-compatible endpoints, see ADR 0002) ---
+LLM_PROVIDER=fake                # fake | gemini | openai | mistral | ollama
+LLM_MODEL=gemini-2.5-flash       # safe default; check AI Studio for the current free-tier flash (e.g. gemini-3-flash)
+LLM_API_KEY=                     # Gemini: https://aistudio.google.com/apikey
+                                 # NB: Gemini free tier => prompts may be used for training. Demo data only.
+# LLM_BASE_URL=                  # override the per-provider preset endpoint if needed
+LLM_TIMEOUT_S=30
+
+# --- ASR / TTS / storage (real implementations land in M2 / M3) ---
+ASR_PROVIDER=fake
+TTS_PROVIDER=fake
+STORAGE_BACKEND=memory
+
+# --- Gradio ---
+HOST=0.0.0.0
+PORT=7860
+GRADIO_AUTH_USERNAME=            # set both to enable basic auth (recruiter demo account)
+GRADIO_AUTH_PASSWORD=

.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install dependencies (frozen)
+        run: uv sync --frozen
+
+      - name: Ruff format check
+        run: uv run ruff format --check .
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Tests
+        run: uv run pytest
+
+  docker:
+    needs: quality
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build & push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:latest
+            ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/deploy-space.yml

@@ -0,0 +1,34 @@
+name: Deploy to HF Space
+
+# A Docker Space rebuilds from the Dockerfile inside the Space repo: it cannot
+# pull the GHCR image directly. GHCR remains the CI artifact / portability story;
+# this job syncs the exact same repo (same Dockerfile) to the Space.
+#
+# One-time setup:
+#   1. Create a Docker Space on Hugging Face (SDK: Docker, hardware: cpu-basic).
+#   2. GitHub repo  -> Settings > Secrets  : HF_TOKEN (write token)
+#   3. GitHub repo  -> Settings > Variables: HF_SPACE = "<hf-username>/<space-name>"
+#   4. HF Space     -> Settings > Variables/Secrets: LLM_PROVIDER, LLM_MODEL, LLM_API_KEY,
+#      GRADIO_AUTH_USERNAME, GRADIO_AUTH_PASSWORD
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    if: ${{ vars.HF_SPACE != '' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Push to Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_SPACE: ${{ vars.HF_SPACE }}
+        run: |
+          HF_USER="${HF_SPACE%%/*}"
+          git push --force "https://${HF_USER}:${HF_TOKEN}@huggingface.co/spaces/${HF_SPACE}" HEAD:main

.gitignore

@@ -0,0 +1,34 @@
+# Secrets & env
+.env
+.env.*
+!.env.example
+
+# Data, models, experiment tracking (ephemeral / heavy)
+data/
+models/
+mlruns/
+*.db
+*.sqlite3
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Gradio
+.gradio/
+flagged/
+
+# OS / IDE
+.DS_Store
+.idea/
+.vscode/

.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+      - id: detect-private-key
+
+  # rev mirrors the exact ruff version pinned in pyproject.toml ([dependency-groups].dev)
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format

.python-version

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

Dockerfile

@@ -0,0 +1,31 @@
+# Runtime image for HF Spaces (Docker SDK, cpu-basic) and GHCR.
+# Heavy ML deps (torch, transformers) are deliberately absent until M1,
+# and training deps never enter this image (see docs/adr/0001).
+FROM python:3.12-slim-bookworm
+
+# uv — pinned to the same version as local dev
+COPY --from=ghcr.io/astral-sh/uv:0.11.20 /uv /uvx /bin/
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never \
+    PYTHONUNBUFFERED=1
+
+# Non-root user with uid 1000 (Hugging Face Spaces requirement)
+RUN useradd -m -u 1000 app
+WORKDIR /app
+
+# Layer 1: dependencies only (cached as long as pyproject/uv.lock don't change)
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-install-project --no-dev
+
+# Layer 2: project code
+COPY README.md ./
+COPY src ./src
+RUN uv sync --frozen --no-dev && chown -R app:app /app
+
+USER app
+ENV PATH="/app/.venv/bin:$PATH"
+EXPOSE 7860
+
+CMD ["python", "-m", "tutor.app.main"]

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Arthur_Diaz
+Copyright (c) 2026 Arthur
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1 +1,101 @@
-# polyglot-tutor
+---
+title: Polyglot Tutor
+emoji: 🌍
+colorFrom: indigo
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# 🌍 Polyglot Tutor
+
+> Adaptive language tutor covering the four skills (reading, listening, writing, speaking),
+> driven by a CEFR classifier and a predictive spaced-repetition learner model.
+> Runs for free on a Hugging Face Space (CPU) with an optional local-GPU "premium" mode.
+
+**Status: M0 — walking skeleton.** CI, Docker → GHCR, HF Space deploy and all service
+contracts (LLM / ASR / TTS / storage) are live; features land milestone by milestone.
+
+<!-- The YAML front-matter above is Hugging Face Space metadata: this repo is synced
+     as-is to a Docker Space by .github/workflows/deploy-space.yml -->
+
+## TL;DR (for recruiters)
+
+- **ML core**: fine-tuned multilingual CEFR (A1–C2) text classifier benchmarked against a
+  published baseline; FSRS-style spaced repetition evaluated offline on public review logs;
+  LLM-generated exercises gated by an LLM-as-judge.
+- **Engineering**: provider-agnostic services (`typing.Protocol` + env-driven factories),
+  pinned toolchain (uv, ruff, pre-commit), tested fakes, CI → GHCR, free-tier deployment with
+  documented constraints (ephemeral disk, cold starts, rate limits).
+- **Honest evals**: every milestone ships metrics with caveats, tracked in MLflow
+  (see `docs/evals/`).
+
+## Architecture
+
+```mermaid
+flowchart LR
+    UI[Gradio UI<br/>4 skill tabs] --> EX[Exercise generators<br/>+ cache]
+    EX --> LLM[LLMClient<br/>Gemini / Mistral / Ollama / fake]
+    EX --> ASR[ASRClient<br/>faster-whisper / remote / fake]
+    EX --> TTS[TTSClient<br/>edge-tts / local / fake]
+    EX --> CEFR[CEFR classifier<br/>ONNX int8, CPU]
+    UI --> SRS[Learner model<br/>FSRS + ability estimate]
+    SRS --> DB[(Repository<br/>memory / SQLite / Supabase)]
+    EX --> DB
+```
+
+Each box on the right is a `Protocol` with swappable implementations selected by environment
+variables — the same image runs as the free Space ("light") or against a local GPU box over
+Tailscale ("premium"). See `docs/adr/` for the reasoning.
+
+## Quickstart (dev)
+
+```bash
+uv sync                      # runtime + dev deps (pinned via uv.lock)
+uv run pre-commit install
+cp .env.example .env         # defaults to the offline fake provider
+uv run python -m tutor.app.main   # http://localhost:7860
+uv run pytest
+```
+
+To talk to a real LLM, set in `.env`: `LLM_PROVIDER=gemini`, `LLM_API_KEY=...`
+(free key at https://aistudio.google.com/apikey), then check the *Diagnostics* tab → *Ping LLM*.
+
+Dataset download / EDA (kept out of the runtime image):
+
+```bash
+uv run --group data python scripts/download_data.py
+```
+
+## Deployment
+
+1. **CI (GitHub Actions)** — lint + tests on every push/PR; on `main`, the Docker image is
+   pushed to `ghcr.io/<owner>/polyglot-tutor`.
+2. **HF Space (Docker, cpu-basic)** — create the Space once, then set:
+   - GitHub → *Secrets*: `HF_TOKEN` (write) · *Variables*: `HF_SPACE=<user>/<space>`
+   - Space → *Settings*: `LLM_PROVIDER`, `LLM_MODEL`, `LLM_API_KEY`,
+     `GRADIO_AUTH_USERNAME`, `GRADIO_AUTH_PASSWORD`
+   Every push to `main` syncs the repo to the Space, which rebuilds from the same Dockerfile
+   (a Docker Space cannot pull the GHCR image — GHCR is the CI artifact, see ADR 0001).
+
+## Roadmap
+
+| Milestone | Scope | Headline eval |
+|---|---|---|
+| **M0** ✅ | Walking skeleton: CI, GHCR, Space, Protocols + fakes | CI green, live Space |
+| **M1** | CEFR classifier + reading comprehension (LLM questions, cached & judge-gated) | macro-F1 / adjacent acc. / QWK vs published UniversalCEFR baseline |
+| **M2** | TTS + dictation with light ASR | WER (incl. non-native audio) justifying tiny vs small |
+| **M3** | Supabase persistence + writing correction (typed errors via ERRANT, per-learner profile) | error-type P/R on W&I+LOCNESS sample |
+| **M4** | Learner model: FSRS scheduling + ability estimate, next-exercise policy | AUC / log-loss / calibration on public Anki review logs |
+| **M5** | Pronunciation scoring + premium local-GPU mode (Tailscale) | correlation with expert scores on speechocean762 |
+| **M6** (stretch) | Real-time voice conversation tab (Gemini Live API behind a ConversationClient Protocol) | qualitative demo; latency budget documented |
+
+## Data & licensing
+
+This is a **non-commercial portfolio/demo project**. CEFR-labeled corpora come from
+[UniversalCEFR](https://huggingface.co/UniversalCEFR) (per-subset, mostly research-only
+licenses — original papers cited); SRS benchmarks use the open Anki review-log datasets;
+pronunciation evaluation uses speechocean762 (free for any use). No licensed text is
+committed to this repo; `data/` is gitignored and rebuilt by `scripts/download_data.py`.
+Details and caveats: `docs/adr/0003-datasets-and-licensing.md`.

docs/adr/0001-stack-and-architecture.md

@@ -0,0 +1,30 @@
+# ADR 0001 — Stack & architecture de base
+
+- **Statut** : accepté (M0)
+- **Date** : 2026-06-11
+
+## Contexte
+Tuteur de langue adaptatif (4 compétences, modèle d'apprenant prédictif), déployé gratuitement
+sur HF Spaces `cpu-basic` (2 vCPU / 16 GB / disque éphémère), avec un mode "premium" optionnel
+sur GPU local (WSL2, RTX 3070) accessible via Tailscale. Budget ~0–10 €/mois.
+
+## Décisions
+1. **Python 3.12 + uv**, src-layout, ruff (lint + format) via pre-commit, pytest. Versions
+   pinnées : `uv.lock` (exact), `ruff` épinglé à l'identique dans pyproject et pre-commit.
+2. **Protocols + fakes d'abord** : `LLMClient`, `ASRClient`, `TTSClient`, `Repository` sont des
+   `typing.Protocol`. Chaque backend réel (API/local) est interchangeable par variable d'env ;
+   les fakes rendent l'app démarrable et testable sans aucun secret ni réseau.
+3. **`training/` hors du paquet runtime** : le fine-tuning (XLM-R, M1) tourne sur le GPU local ;
+   l'image Docker du Space n'embarque jamais torch-CUDA. L'inférence du classifieur sera
+   exportée ONNX int8 pour le CPU du Space.
+4. **Déploiement** : un Docker Space rebuild depuis le Dockerfile du repo Space (impossible de
+   pointer une image externe) → GHCR = artefact CI/portabilité, et un workflow synchronise le
+   même repo vers le Space. Image non-root (uid 1000), port 7860, front-matter HF dans README.
+5. **Modèle d'apprenant multilingue par construction** : `target_lang` est une donnée
+   (domaine + config), pas une constante — l'anglais est la cible de lancement, l'ajout d'une
+   langue ne doit exiger ni migration ni refonte.
+
+## Conséquences
+- Cold start Space (mise en veille après inactivité) → lazy-loading des modèles (M1+).
+- edge-tts (API non officielle) impose un fallback TTS local derrière le Protocol (M2).
+- Les fakes servent aussi de documentation exécutable des contrats.

docs/adr/0002-llm-provider-strategy.md

@@ -0,0 +1,23 @@
+# ADR 0002 — Stratégie provider LLM : un client OpenAI-compatible unique
+
+- **Statut** : accepté (M0)
+- **Date** : 2026-06-11
+
+## Contexte
+Le projet exige de basculer API ↔ local par variable d'env. Gemini (endpoint de compatibilité
+OpenAI), Mistral et Ollama exposent tous une API chat-completions compatible OpenAI.
+
+## Décision
+Un seul client `OpenAICompatClient(model, api_key, base_url)` couvre les quatre providers via
+des presets de `base_url` ; `LLM_PROVIDER=fake` reste le défaut zéro-config (tests, CI, premier
+boot du Space). **Provider principal : Gemini Flash** (free tier ~1 500 req/jour sur les
+modèles Flash, soit un budget ~0 €).
+
+## Conséquences / caveats
+- Free tier Gemini : ~10–15 RPM et données potentiellement utilisées pour l'entraînement →
+  données de démo uniquement, et retry/backoff sur 429 à implémenter en M1 (avec cache
+  d'exercices pour minimiser les appels).
+- Le nom de modèle est entièrement piloté par `LLM_MODEL` (les noms bougent : 2.5-flash,
+  3-flash…) — aucun nom de modèle codé en dur.
+- Les fonctionnalités spécifiques (structured output natif, etc.) pourront justifier des
+  implémentations dédiées derrière le même Protocol, sans toucher au reste du code.

docs/adr/0003-datasets-and-licensing.md

@@ -0,0 +1,21 @@
+# ADR 0003 — Datasets & licences
+
+- **Statut** : accepté (M0) — mix d'entraînement M1 à finaliser après EDA
+- **Date** : 2026-06-11
+
+## Décisions
+| Besoin | Source | Licence / accès |
+|---|---|---|
+| Classif CECRL (M1) | **UniversalCEFR** (HF org), sous-jeux EN `reference` (cefr_sp_en, readme_en, cambridge-exams, …) | non-commercial research, par sous-corpus ; citer les papiers sources |
+| Baselines M1 | `UniversalCEFR/xlm-roberta-base-cefr-all-classifier` (+ ModernBERT) | comparaison directe à une baseline publiée |
+| Éval correction écrite (M3) | ERRANT (typage auto, EN) + W&I+LOCNESS (BEA-2019) | W&I : ToU séparées à accepter |
+| Benchmark SRS offline (M4) | `open-spaced-repetition/anki-revlogs-10k` (échantillon ~200–500 users) ; HLR vs FSRS via srs-benchmark | licence dédiée FSRS-Anki ; caveat : Anki ≠ notre app (domain shift documenté) |
+| Prononciation (M5) + WER non-natif (M2) | **speechocean762** (OpenSLR 101) | libre, y compris usage commercial |
+
+## Conséquences
+- Le projet est **explicitement non commercial** (portfolio/démo) : compatible avec les
+  licences research-only ; section "Data & licensing" du README à maintenir en phase.
+- ERRANT étant anglais-only, le typage d'erreurs pour d'autres langues cibles passera par un
+  rubric LLM derrière le même contrat de service.
+- Aucun texte sous licence restrictive n'est commité dans le repo (`data/` gitignoré),
+  uniquement des scripts de téléchargement reproductibles.

evals/README.md

@@ -0,0 +1,4 @@
+# evals/
+
+Evaluation harness (MLflow tracking on local SQLite, LLM-as-judge for generated exercises).
+First real content lands with M1; per-milestone reports go to docs/evals/.

pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+      - id: detect-private-key
+
+  # rev mirrors the exact ruff version pinned in pyproject.toml ([dependency-groups].dev)
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+      - id: ruff-check
+        args: ["--fix"]
+      - id: ruff-format

pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "polyglot-tutor"
+version = "0.1.0"
+description = "Adaptive language tutor: CEFR-aware exercises across the four skills, driven by a predictive spaced-repetition learner model."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "Arthur" }]
+dependencies = [
+    # Runtime deps only — keep the Docker image (HF Space, cpu-basic) lean.
+    "gradio>=6.17,<7",
+    "openai>=2.41,<3",          # single OpenAI-compatible client: Gemini / Mistral / Ollama / OpenAI (ADR 0002)
+    "pydantic>=2.8",
+    "pydantic-settings>=2.14,<3",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0",
+    "pytest-asyncio>=1.4",
+    "ruff==0.15.16",            # exact pin, mirrored in .pre-commit-config.yaml
+    "pre-commit>=4.6",
+]
+data = [
+    # Dataset download / EDA (UniversalCEFR & friends). Not in the runtime image.
+    "datasets>=5.0",
+]
+train = [
+    # M1: transformers, torch (CUDA, local GPU), optimum/onnxruntime for CPU export.
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tutor"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",    # pycodestyle
+    "F",         # pyflakes
+    "I",         # isort
+    "UP",        # pyupgrade
+    "B",         # bugbear
+    "SIM",       # simplify
+    "C4",        # comprehensions
+    "PTH",       # pathlib
+    "RET",       # return
+    "ASYNC",     # async pitfalls
+    "RUF",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-q"

scripts/download_data.py

@@ -0,0 +1,66 @@
+"""Download UniversalCEFR subsets and print a quick EDA (level/granularity stats).
+
+UniversalCEFR (Imperial et al., EMNLP 2025) standardises 26 CEFR-labeled
+corpora across 13 languages into one JSON schema:
+    https://huggingface.co/UniversalCEFR
+
+Usage (deps live in the "data" group, kept out of the runtime image):
+    uv run --group data python scripts/download_data.py
+    uv run --group data python scripts/download_data.py --datasets UniversalCEFR/readme_fr --save
+
+Notes:
+- Default subsets below are confirmed English sets; the final M1 training mix
+  (e.g. cambridge-exams for document-level texts) is decided in ADR 0003 after
+  reviewing the org's data directory.
+- Licenses are per-subset and mostly non-commercial research: keep the README
+  licensing section in sync with whatever lands here.
+"""
+
+import argparse
+from collections import Counter
+from pathlib import Path
+
+from datasets import load_dataset
+
+DEFAULT_DATASETS = [
+    "UniversalCEFR/cefr_sp_en",  # sentence-level, expert-annotated (CEFR-SP)
+    "UniversalCEFR/readme_en",  # document-level readability (ReadMe++)
+]
+
+RAW_DIR = Path("data/raw")
+
+
+def summarize(dataset_id: str, save: bool) -> None:
+    dataset = load_dataset(dataset_id, split="train")
+    levels = Counter(dataset["cefr_level"])
+    formats = Counter(dataset["format"]) if "format" in dataset.column_names else {}
+    categories = Counter(dataset["category"]) if "category" in dataset.column_names else {}
+
+    print(f"\n=== {dataset_id} — {len(dataset)} rows ===")
+    print(f"  levels    : {dict(sorted(levels.items()))}")
+    if formats:
+        print(f"  formats   : {dict(formats)}")
+    if categories:
+        print(f"  categories: {dict(categories)}")
+
+    if save:
+        RAW_DIR.mkdir(parents=True, exist_ok=True)
+        out_path = RAW_DIR / f"{dataset_id.split('/')[-1]}.parquet"
+        dataset.to_parquet(out_path)
+        print(f"  saved -> {out_path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--datasets", nargs="+", default=DEFAULT_DATASETS)
+    parser.add_argument(
+        "--save", action="store_true", help="save each subset to data/raw/*.parquet"
+    )
+    args = parser.parse_args()
+
+    for dataset_id in args.datasets:
+        summarize(dataset_id, save=args.save)
+
+
+if __name__ == "__main__":
+    main()

src/tutor/app/main.py

@@ -0,0 +1,76 @@
+"""Gradio entrypoint — M0 walking skeleton.
+
+One tab per skill (wired milestone by milestone) plus a Diagnostics tab that
+shows the resolved configuration and can ping the configured LLM, which makes
+the deployed Space verifiable end to end from day one.
+"""
+
+import gradio as gr
+
+from tutor.config import Settings, get_settings
+from tutor.services.llm.base import ChatMessage, LLMError
+from tutor.services.llm.factory import create_llm_client
+
+
+def build_app(settings: Settings | None = None) -> gr.Blocks:
+    settings = settings or get_settings()
+    llm = create_llm_client(settings)
+
+    async def ping_llm() -> str:
+        try:
+            response = await llm.complete(
+                [ChatMessage(role="user", content="Reply with exactly one word: pong")],
+                temperature=0.0,
+                max_tokens=16,
+            )
+        except LLMError as exc:
+            return f"❌ {exc}"
+        return f"✅ [{response.model}] {response.text.strip()}"
+
+    with gr.Blocks(title="Polyglot Tutor") as app:
+        gr.Markdown(
+            "# 🌍 Polyglot Tutor\n"
+            f"Adaptive language tutor — learning **{settings.default_target_lang}** "
+            f"from **{settings.default_source_lang}**. *M0 walking skeleton.*"
+        )
+
+        with gr.Tab("📖 Reading"):
+            gr.Markdown("CEFR-graded texts + generated comprehension questions — **M1**.")
+        with gr.Tab("🎧 Listening"):
+            gr.Markdown("TTS audio + dictation with ASR scoring — **M2**.")
+        with gr.Tab("✍️ Writing"):
+            gr.Markdown("LLM correction with typed errors, per-learner error profile — **M3**.")
+        with gr.Tab("🗣️ Speaking"):
+            gr.Markdown("Read-aloud exercises with pronunciation scoring — **M5**.")
+
+        with gr.Tab("⚙️ Diagnostics"):
+            gr.Markdown(
+                f"- env: `{settings.app_env}`\n"
+                f"- LLM: `{settings.llm_provider}` / `{settings.llm_model}`\n"
+                f"- ASR: `{settings.asr_provider}` · TTS: `{settings.tts_provider}` · "
+                f"storage: `{settings.storage_backend}`"
+            )
+            ping_button = gr.Button("Ping LLM", variant="primary")
+            ping_output = gr.Textbox(label="LLM response", interactive=False)
+            ping_button.click(ping_llm, outputs=ping_output)
+
+    return app
+
+
+def main() -> None:
+    settings = get_settings()
+    auth: tuple[str, str] | None = None
+    if settings.gradio_auth_username and settings.gradio_auth_password:
+        auth = (
+            settings.gradio_auth_username,
+            settings.gradio_auth_password.get_secret_value(),
+        )
+    build_app(settings).launch(
+        server_name=settings.host,
+        server_port=settings.port,
+        auth=auth,
+    )
+
+
+if __name__ == "__main__":
+    main()

src/tutor/config.py

@@ -0,0 +1,56 @@
+"""Centralised, environment-driven configuration.
+
+Every provider choice (LLM, ASR, TTS, storage) is a plain env var so the same
+image runs as the free HF Space ("light" mode) or against the local GPU box
+("premium" mode) without code changes.
+
+The `Literal` types are intentionally restricted to *implemented* providers:
+adding an implementation means widening the Literal, so the config can never
+silently point at a backend that does not exist yet.
+"""
+
+from functools import lru_cache
+from typing import Literal
+
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # --- App ---
+    app_env: Literal["dev", "prod"] = "dev"
+    log_level: str = "INFO"
+
+    # --- Languages ---
+    default_source_lang: str = "fr"
+    default_target_lang: str = "en"
+
+    # --- LLM ---
+    llm_provider: Literal["fake", "gemini", "openai", "mistral", "ollama"] = "fake"
+    llm_model: str = "gemini-2.5-flash"
+    llm_api_key: SecretStr | None = None
+    llm_base_url: str | None = None
+    llm_timeout_s: float = 30.0
+
+    # --- ASR / TTS / storage (implementations land in M2 / M3) ---
+    asr_provider: Literal["fake"] = "fake"
+    tts_provider: Literal["fake"] = "fake"
+    storage_backend: Literal["memory"] = "memory"
+
+    # --- Gradio ---
+    host: str = "0.0.0.0"
+    port: int = 7860
+    gradio_auth_username: str | None = None
+    gradio_auth_password: SecretStr | None = None
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Process-wide settings singleton (tests build `Settings` directly instead)."""
+    return Settings()

src/tutor/domain/models.py

@@ -0,0 +1,98 @@
+"""Core domain entities, persistence- and framework-agnostic.
+
+Languages are first-class data (`source_lang` / `target_lang`, ISO 639-1) rather
+than constants: English is the launch target, but the model must not need a
+migration to add Spanish or German later.
+"""
+
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+
+def _new_id() -> str:
+    return uuid4().hex
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+class CEFRLevel(StrEnum):
+    A1 = "A1"
+    A2 = "A2"
+    B1 = "B1"
+    B2 = "B2"
+    C1 = "C1"
+    C2 = "C2"
+
+    @property
+    def rank(self) -> int:
+        """0-based ordinal position (A1=0 ... C2=5), for ordinal metrics and adjacency."""
+        return list(CEFRLevel).index(self)
+
+    def distance(self, other: "CEFRLevel") -> int:
+        """Absolute level distance; `<= 1` is the classic 'adjacent accuracy' criterion."""
+        return abs(self.rank - other.rank)
+
+
+class ExerciseType(StrEnum):
+    READING_QA = "reading_qa"  # M1 — comprehension questions on a CEFR-graded text
+    DICTATION = "dictation"  # M2 — TTS audio, learner types what they hear
+    WRITING = "writing"  # M3 — free writing, LLM correction with typed errors
+    PRONUNCIATION = "pronunciation"  # M5 — read-aloud with pronunciation scoring
+
+
+class Learner(BaseModel):
+    id: str = Field(default_factory=_new_id)
+    display_name: str
+    source_lang: str = "fr"
+    target_lang: str = "en"
+    created_at: datetime = Field(default_factory=_now)
+
+
+class Exercise(BaseModel):
+    """A generated, cacheable exercise.
+
+    `payload` is type-specific content (text, questions, audio reference...).
+    Generated exercises are content-addressed upstream (hash of source text +
+    prompt version) so LLM cost stays ~0 and evals are reproducible.
+    """
+
+    id: str = Field(default_factory=_new_id)
+    type: ExerciseType
+    target_lang: str
+    cefr_level: CEFRLevel
+    payload: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=_now)
+
+
+class Attempt(BaseModel):
+    """One learner answer to one exercise, with its scoring/feedback."""
+
+    id: str = Field(default_factory=_new_id)
+    learner_id: str
+    exercise_id: str
+    response: dict[str, Any] = Field(default_factory=dict)
+    score: float | None = Field(default=None, ge=0.0, le=1.0)
+    feedback: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=_now)
+
+
+class ReviewItem(BaseModel):
+    """An atomic, schedulable knowledge item (vocab word, recurring error, ...).
+
+    `scheduler_state` is an opaque dict owned by the SRS engine (FSRS-ready in
+    M4) so the domain model is not coupled to one algorithm's parameters.
+    """
+
+    id: str = Field(default_factory=_new_id)
+    learner_id: str
+    kind: str  # "vocab" | "error" | ... (free-form until M4 hardens it)
+    content: dict[str, Any] = Field(default_factory=dict)
+    due_at: datetime | None = None
+    scheduler_state: dict[str, Any] = Field(default_factory=dict)
+    created_at: datetime = Field(default_factory=_now)

src/tutor/services/asr/base.py

@@ -0,0 +1,33 @@
+"""ASR client contract + offline fake.
+
+Real implementations land in M2 (faster-whisper tiny/small, int8, on the Space
+CPU) and M5 (remote large model on the local GPU box). The fake keeps the UI
+and tests fully wired in the meantime.
+"""
+
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+class Transcription(BaseModel):
+    text: str
+    language: str | None = None
+
+
+@runtime_checkable
+class ASRClient(Protocol):
+    async def transcribe(
+        self, audio_path: Path, *, language: str | None = None
+    ) -> Transcription: ...
+
+
+class FakeASRClient:
+    def __init__(self, text: str = "(fake transcription)") -> None:
+        self._text = text
+        self.calls: list[Path] = []
+
+    async def transcribe(self, audio_path: Path, *, language: str | None = None) -> Transcription:
+        self.calls.append(audio_path)
+        return Transcription(text=self._text, language=language)

src/tutor/services/llm/base.py

@@ -0,0 +1,40 @@
+"""LLM client contract.
+
+Anything that can turn a chat into text satisfies `LLMClient` — the app, the
+exercise generators and the evals only ever depend on this Protocol, never on
+a vendor SDK (same pattern for ASR / TTS / storage).
+"""
+
+from collections.abc import Sequence
+from typing import Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+Role = Literal["system", "user", "assistant"]
+
+
+class ChatMessage(BaseModel):
+    role: Role
+    content: str
+
+
+class LLMResponse(BaseModel):
+    text: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+
+
+class LLMError(RuntimeError):
+    """A completion failed (network, auth, rate limit, provider error...)."""
+
+
+@runtime_checkable
+class LLMClient(Protocol):
+    async def complete(
+        self,
+        messages: Sequence[ChatMessage],
+        *,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+    ) -> LLMResponse: ...

src/tutor/services/llm/factory.py

@@ -0,0 +1,34 @@
+"""Provider resolution: Settings -> LLMClient."""
+
+from tutor.config import Settings
+from tutor.services.llm.base import LLMClient
+from tutor.services.llm.fake import FakeLLMClient
+from tutor.services.llm.openai_compat import OpenAICompatClient
+
+GEMINI_OPENAI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+
+_PRESET_BASE_URLS: dict[str, str | None] = {
+    "gemini": GEMINI_OPENAI_BASE_URL,
+    "mistral": "https://api.mistral.ai/v1",
+    "ollama": "http://localhost:11434/v1",  # premium mode: reached over Tailscale in M5
+    "openai": None,  # SDK default
+}
+
+
+def create_llm_client(settings: Settings) -> LLMClient:
+    if settings.llm_provider == "fake":
+        return FakeLLMClient()
+
+    api_key = settings.llm_api_key.get_secret_value() if settings.llm_api_key else None
+    if settings.llm_provider == "ollama":
+        api_key = api_key or "ollama"  # local servers accept any non-empty key
+    if not api_key:
+        msg = f"LLM_API_KEY is required for provider '{settings.llm_provider}'"
+        raise ValueError(msg)
+
+    return OpenAICompatClient(
+        model=settings.llm_model,
+        api_key=api_key,
+        base_url=settings.llm_base_url or _PRESET_BASE_URLS[settings.llm_provider],
+        timeout_s=settings.llm_timeout_s,
+    )

src/tutor/services/llm/fake.py

@@ -0,0 +1,26 @@
+"""Deterministic, offline LLM client.
+
+Used by the test suite and as the zero-config default provider, so the app
+boots (locally, in CI, on a fresh Space) without any API key.
+"""
+
+from collections.abc import Sequence
+
+from tutor.services.llm.base import ChatMessage, LLMResponse
+
+
+class FakeLLMClient:
+    def __init__(self, responses: Sequence[str] | None = None) -> None:
+        self._responses: list[str] = list(responses or [])
+        self.calls: list[list[ChatMessage]] = []
+
+    async def complete(
+        self,
+        messages: Sequence[ChatMessage],
+        *,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+    ) -> LLMResponse:
+        self.calls.append(list(messages))
+        text = self._responses.pop(0) if self._responses else "(fake) pong"
+        return LLMResponse(text=text, model="fake", input_tokens=0, output_tokens=0)

src/tutor/services/llm/openai_compat.py

@@ -0,0 +1,52 @@
+"""One client, four providers.
+
+Gemini, Mistral and Ollama all expose OpenAI-compatible chat-completions
+endpoints, so a single implementation parameterised by `base_url` covers the
+whole "light API / premium local" matrix (ADR 0002). Provider-specific
+features (native structured output, etc.) can later get dedicated
+implementations behind the same `LLMClient` Protocol.
+"""
+
+from collections.abc import Sequence
+
+from openai import AsyncOpenAI, OpenAIError
+
+from tutor.services.llm.base import ChatMessage, LLMError, LLMResponse
+
+
+class OpenAICompatClient:
+    def __init__(
+        self,
+        *,
+        model: str,
+        api_key: str,
+        base_url: str | None = None,
+        timeout_s: float = 30.0,
+    ) -> None:
+        self.model = model
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url, timeout=timeout_s)
+
+    async def complete(
+        self,
+        messages: Sequence[ChatMessage],
+        *,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+    ) -> LLMResponse:
+        try:
+            response = await self._client.chat.completions.create(
+                model=self.model,
+                messages=[m.model_dump() for m in messages],  # type: ignore[misc]
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+        except OpenAIError as exc:
+            raise LLMError(f"LLM call failed (model={self.model}): {exc}") from exc
+
+        usage = response.usage
+        return LLMResponse(
+            text=response.choices[0].message.content or "",
+            model=response.model,
+            input_tokens=usage.prompt_tokens if usage else None,
+            output_tokens=usage.completion_tokens if usage else None,
+        )

src/tutor/services/storage/base.py

@@ -0,0 +1,22 @@
+"""Persistence contract.
+
+The surface is deliberately minimal at M0 (learners + attempts) and grows with
+real needs: review items and error profiles arrive with M3/M4, when the
+SQLite/Supabase implementations replace the in-memory one behind this same
+Protocol.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from tutor.domain.models import Attempt, Learner
+
+
+@runtime_checkable
+class Repository(Protocol):
+    async def save_learner(self, learner: Learner) -> None: ...
+
+    async def get_learner(self, learner_id: str) -> Learner | None: ...
+
+    async def save_attempt(self, attempt: Attempt) -> None: ...
+
+    async def list_attempts(self, learner_id: str) -> list[Attempt]: ...

src/tutor/services/storage/memory.py

@@ -0,0 +1,26 @@
+"""In-memory Repository: M0 default, and the reference fake for tests.
+
+Single-process only (fine for one Gradio app); durable backends (SQLite local,
+Supabase Postgres on the Space) land in M3.
+"""
+
+from tutor.domain.models import Attempt, Learner
+
+
+class InMemoryRepository:
+    def __init__(self) -> None:
+        self._learners: dict[str, Learner] = {}
+        self._attempts: dict[str, Attempt] = {}
+
+    async def save_learner(self, learner: Learner) -> None:
+        self._learners[learner.id] = learner
+
+    async def get_learner(self, learner_id: str) -> Learner | None:
+        return self._learners.get(learner_id)
+
+    async def save_attempt(self, attempt: Attempt) -> None:
+        self._attempts[attempt.id] = attempt
+
+    async def list_attempts(self, learner_id: str) -> list[Attempt]:
+        attempts = [a for a in self._attempts.values() if a.learner_id == learner_id]
+        return sorted(attempts, key=lambda a: a.created_at)

src/tutor/services/tts/base.py

@@ -0,0 +1,48 @@
+"""TTS client contract + offline fake.
+
+Real implementations land in M2: edge-tts as primary (unofficial API, hence
+fragile) plus a local fallback behind this same Protocol (ADR 0001).
+
+The fake returns a *valid* WAV (short silence) so audio components and tests
+exercise the real byte path end to end.
+"""
+
+import io
+import wave
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+class TTSResult(BaseModel):
+    audio: bytes
+    format: str = "wav"
+    voice: str | None = None
+
+
+@runtime_checkable
+class TTSClient(Protocol):
+    async def synthesize(
+        self, text: str, *, language: str = "en", voice: str | None = None
+    ) -> TTSResult: ...
+
+
+def _silent_wav(duration_s: float = 0.2, sample_rate: int = 16_000) -> bytes:
+    buffer = io.BytesIO()
+    with wave.open(buffer, "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)  # 16-bit PCM
+        wav.setframerate(sample_rate)
+        wav.writeframes(b"\x00\x00" * int(duration_s * sample_rate))
+    return buffer.getvalue()
+
+
+class FakeTTSClient:
+    def __init__(self) -> None:
+        self.calls: list[str] = []
+
+    async def synthesize(
+        self, text: str, *, language: str = "en", voice: str | None = None
+    ) -> TTSResult:
+        self.calls.append(text)
+        return TTSResult(audio=_silent_wav(), format="wav", voice=voice or f"fake-{language}")

tests/test_app.py

@@ -0,0 +1,10 @@
+import gradio as gr
+
+from tutor.app.main import build_app
+from tutor.config import Settings
+
+
+def test_build_app_with_fake_provider() -> None:
+    settings = Settings(_env_file=None)  # type: ignore[call-arg]
+    app = build_app(settings)
+    assert isinstance(app, gr.Blocks)

tests/test_config.py

@@ -0,0 +1,31 @@
+from pydantic import SecretStr
+
+from tutor.config import Settings
+
+
+def _settings(**overrides: object) -> Settings:
+    # _env_file=None: ignore any local .env so tests are hermetic.
+    return Settings(_env_file=None, **overrides)  # type: ignore[arg-type]
+
+
+def test_defaults_are_offline_safe() -> None:
+    settings = _settings()
+    assert settings.llm_provider == "fake"
+    assert settings.storage_backend == "memory"
+    assert settings.port == 7860
+
+
+def test_env_overrides(monkeypatch) -> None:
+    monkeypatch.setenv("LLM_PROVIDER", "gemini")
+    monkeypatch.setenv("LLM_MODEL", "gemini-2.5-flash")
+    monkeypatch.setenv("LLM_API_KEY", "sk-test")
+    settings = _settings()
+    assert settings.llm_provider == "gemini"
+    assert settings.llm_model == "gemini-2.5-flash"
+    assert isinstance(settings.llm_api_key, SecretStr)
+
+
+def test_api_key_is_not_leaked_in_repr() -> None:
+    settings = _settings(llm_api_key=SecretStr("sk-very-secret"))
+    assert "sk-very-secret" not in repr(settings)
+    assert "sk-very-secret" not in str(settings)

tests/test_llm.py

@@ -0,0 +1,52 @@
+import pytest
+
+from tutor.config import Settings
+from tutor.services.llm.base import ChatMessage, LLMClient
+from tutor.services.llm.factory import GEMINI_OPENAI_BASE_URL, create_llm_client
+from tutor.services.llm.fake import FakeLLMClient
+from tutor.services.llm.openai_compat import OpenAICompatClient
+
+
+def _settings(**overrides: object) -> Settings:
+    return Settings(_env_file=None, **overrides)  # type: ignore[arg-type]
+
+
+async def test_fake_client_is_deterministic_and_records_calls() -> None:
+    client = FakeLLMClient(responses=["first", "second"])
+    messages = [ChatMessage(role="user", content="hello")]
+
+    first = await client.complete(messages)
+    second = await client.complete(messages)
+    third = await client.complete(messages)  # queue exhausted -> default
+
+    assert (first.text, second.text) == ("first", "second")
+    assert third.text == "(fake) pong"
+    assert len(client.calls) == 3
+    assert client.calls[0][0].content == "hello"
+
+
+def test_fake_satisfies_protocol() -> None:
+    assert isinstance(FakeLLMClient(), LLMClient)
+
+
+def test_factory_returns_fake_by_default() -> None:
+    client = create_llm_client(_settings())
+    assert isinstance(client, FakeLLMClient)
+
+
+def test_factory_requires_api_key_for_remote_providers() -> None:
+    with pytest.raises(ValueError, match="LLM_API_KEY"):
+        create_llm_client(_settings(llm_provider="gemini"))
+
+
+def test_factory_builds_openai_compat_client_with_gemini_preset() -> None:
+    settings = _settings(llm_provider="gemini", llm_api_key="sk-test", llm_model="gemini-2.5-flash")
+    client = create_llm_client(settings)
+    assert isinstance(client, OpenAICompatClient)
+    assert client.model == "gemini-2.5-flash"
+    assert str(client._client.base_url) == GEMINI_OPENAI_BASE_URL
+
+
+def test_factory_allows_keyless_ollama() -> None:
+    client = create_llm_client(_settings(llm_provider="ollama", llm_model="llama3"))
+    assert isinstance(client, OpenAICompatClient)

tests/test_services.py

@@ -0,0 +1,52 @@
+import io
+import wave
+from pathlib import Path
+
+from tutor.domain.models import Attempt, CEFRLevel, Learner
+from tutor.services.asr.base import FakeASRClient
+from tutor.services.storage.memory import InMemoryRepository
+from tutor.services.tts.base import FakeTTSClient
+
+
+def test_cefr_level_ordering() -> None:
+    assert CEFRLevel.A1.rank == 0
+    assert CEFRLevel.C2.rank == 5
+    assert CEFRLevel.B1.distance(CEFRLevel.B2) == 1
+    assert CEFRLevel.A1.distance(CEFRLevel.C2) == 5
+
+
+async def test_fake_tts_returns_a_valid_wav() -> None:
+    result = await FakeTTSClient().synthesize("Hello world", language="en")
+    assert result.format == "wav"
+    with wave.open(io.BytesIO(result.audio), "rb") as wav:
+        assert wav.getnchannels() == 1
+        assert wav.getnframes() > 0
+
+
+async def test_fake_asr_transcribes() -> None:
+    client = FakeASRClient(text="bonjour")
+    transcription = await client.transcribe(Path("/tmp/whatever.wav"), language="fr")
+    assert transcription.text == "bonjour"
+    assert transcription.language == "fr"
+    assert client.calls == [Path("/tmp/whatever.wav")]
+
+
+async def test_memory_repository_roundtrip() -> None:
+    repo = InMemoryRepository()
+    learner = Learner(display_name="Arthur", source_lang="fr", target_lang="en")
+    await repo.save_learner(learner)
+
+    assert await repo.get_learner(learner.id) == learner
+    assert await repo.get_learner("missing") is None
+
+    first = Attempt(learner_id=learner.id, exercise_id="ex1", score=0.5)
+    second = Attempt(learner_id=learner.id, exercise_id="ex2", score=1.0)
+    await repo.save_attempt(second)
+    await repo.save_attempt(first)
+
+    attempts = await repo.list_attempts(learner.id)
+    assert [a.exercise_id for a in attempts] == sorted(
+        [a.exercise_id for a in attempts],
+        key=lambda ex_id: next(a.created_at for a in attempts if a.exercise_id == ex_id),
+    )
+    assert await repo.list_attempts("missing") == []

training/README.md

@@ -0,0 +1,5 @@
+# training/
+
+Fine-tuning code (M1: CEFR classifier on XLM-R) lives here. It runs on the local GPU box
+(WSL2, RTX 3070) with the `train` dependency group and is **never** part of the runtime
+Docker image. Exported artifacts (ONNX int8) are what the Space serves.