blizzarman/polyglot-tutor

🌍 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

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)

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

uv run --group data python scripts/download_data.py

Deployment

1. 1.CI (GitHub Actions) — lint + tests on every push/PR; on main, the Docker image is pushed to ghcr.io/<owner>/polyglot-tutor.
2. 2.HF Space (Docker, cpu-basic) — create the Space once, then set:
3. 3.GitHub → Secrets: HF_TOKEN (write) · Variables: HF_SPACE=<user>/<space>
4. 4.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

Data & licensing

This is a non-commercial portfolio/demo project. CEFR-labeled corpora come from 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.