blizzarman/polyglot-tutor

1---2title: Polyglot Tutor3emoji: 🌍4colorFrom: indigo5colorTo: green6sdk: docker7app_port: 78608pinned: false9---10 11# 🌍 Polyglot Tutor12 13> Adaptive language tutor covering the four skills (reading, listening, writing, speaking),14> driven by a CEFR classifier and a predictive spaced-repetition learner model.15> Runs for free on a Hugging Face Space (CPU) with an optional local-GPU "premium" mode.16 17**Status: M0 — walking skeleton.** CI, Docker → GHCR, HF Space deploy and all service18contracts (LLM / ASR / TTS / storage) are live; features land milestone by milestone.19 20<!-- The YAML front-matter above is Hugging Face Space metadata: this repo is synced21     as-is to a Docker Space by .github/workflows/deploy-space.yml -->22 23## TL;DR (for recruiters)24 25- **ML core**: fine-tuned multilingual CEFR (A1–C2) text classifier benchmarked against a26  published baseline; FSRS-style spaced repetition evaluated offline on public review logs;27  LLM-generated exercises gated by an LLM-as-judge.28- **Engineering**: provider-agnostic services (`typing.Protocol` + env-driven factories),29  pinned toolchain (uv, ruff, pre-commit), tested fakes, CI → GHCR, free-tier deployment with30  documented constraints (ephemeral disk, cold starts, rate limits).31- **Honest evals**: every milestone ships metrics with caveats, tracked in MLflow32  (see `docs/evals/`).33 34## Architecture35 36```mermaid37flowchart LR38    UI[Gradio UI<br/>4 skill tabs] --> EX[Exercise generators<br/>+ cache]39    EX --> LLM[LLMClient<br/>Gemini / Mistral / Ollama / fake]40    EX --> ASR[ASRClient<br/>faster-whisper / remote / fake]41    EX --> TTS[TTSClient<br/>edge-tts / local / fake]42    EX --> CEFR[CEFR classifier<br/>ONNX int8, CPU]43    UI --> SRS[Learner model<br/>FSRS + ability estimate]44    SRS --> DB[(Repository<br/>memory / SQLite / Supabase)]45    EX --> DB46```47 48Each box on the right is a `Protocol` with swappable implementations selected by environment49variables — the same image runs as the free Space ("light") or against a local GPU box over50Tailscale ("premium"). See `docs/adr/` for the reasoning.51 52## Quickstart (dev)53 54```bash55uv sync                      # runtime + dev deps (pinned via uv.lock)56uv run pre-commit install57cp .env.example .env         # defaults to the offline fake provider58uv run python -m tutor.app.main   # http://localhost:786059uv run pytest60```61 62To talk to a real LLM, set in `.env`: `LLM_PROVIDER=gemini`, `LLM_API_KEY=...`63(free key at https://aistudio.google.com/apikey), then check the *Diagnostics* tab → *Ping LLM*.64 65Dataset download / EDA (kept out of the runtime image):66 67```bash68uv run --group data python scripts/download_data.py69```70 71## Deployment72 731. **CI (GitHub Actions)** — lint + tests on every push/PR; on `main`, the Docker image is74   pushed to `ghcr.io/<owner>/polyglot-tutor`.752. **HF Space (Docker, cpu-basic)** — create the Space once, then set:76   - GitHub → *Secrets*: `HF_TOKEN` (write) · *Variables*: `HF_SPACE=<user>/<space>`77   - Space → *Settings*: `LLM_PROVIDER`, `LLM_MODEL`, `LLM_API_KEY`,78     `GRADIO_AUTH_USERNAME`, `GRADIO_AUTH_PASSWORD`79   Every push to `main` syncs the repo to the Space, which rebuilds from the same Dockerfile80   (a Docker Space cannot pull the GHCR image — GHCR is the CI artifact, see ADR 0001).81 82## Roadmap83 84| Milestone | Scope | Headline eval |85|---|---|---|86| **M0** ✅ | Walking skeleton: CI, GHCR, Space, Protocols + fakes | CI green, live Space |87| **M1** | CEFR classifier + reading comprehension (LLM questions, cached & judge-gated) | macro-F1 / adjacent acc. / QWK vs published UniversalCEFR baseline |88| **M2** | TTS + dictation with light ASR | WER (incl. non-native audio) justifying tiny vs small |89| **M3** | Supabase persistence + writing correction (typed errors via ERRANT, per-learner profile) | error-type P/R on W&I+LOCNESS sample |90| **M4** | Learner model: FSRS scheduling + ability estimate, next-exercise policy | AUC / log-loss / calibration on public Anki review logs |91| **M5** | Pronunciation scoring + premium local-GPU mode (Tailscale) | correlation with expert scores on speechocean762 |92| **M6** (stretch) | Real-time voice conversation tab (Gemini Live API behind a ConversationClient Protocol) | qualitative demo; latency budget documented |93 94## Data & licensing95 96This is a **non-commercial portfolio/demo project**. CEFR-labeled corpora come from97[UniversalCEFR](https://huggingface.co/UniversalCEFR) (per-subset, mostly research-only98licenses — original papers cited); SRS benchmarks use the open Anki review-log datasets;99pronunciation evaluation uses speechocean762 (free for any use). No licensed text is100committed to this repo; `data/` is gitignored and rebuilt by `scripts/download_data.py`.101Details and caveats: `docs/adr/0003-datasets-and-licensing.md`.102