Add persian-tutor: Gradio-based GCSE Persian language learning app
Vocabulary study with FSRS spaced repetition, AI tutoring (Ollama/Claude), essay marking, idioms browser, Anki export, and dashboard. 918 vocabulary entries across 39 categories. 41 tests passing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
57
python/persian-tutor/README.md
Normal file
57
python/persian-tutor/README.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Persian Language Tutor
|
||||
|
||||
A Gradio-based Persian (Farsi) language learning app for English speakers, built around GCSE Persian vocabulary (Pearson specification).
|
||||
|
||||
## Features
|
||||
|
||||
- **Vocabulary Study** — Search, browse, and study 918 GCSE Persian words across 39 categories
|
||||
- **Flashcards with FSRS** — Spaced repetition scheduling (same algorithm as Anki)
|
||||
- **Idioms & Expressions** — 25 Persian social conventions with cultural context
|
||||
- **AI Tutor** — Conversational Persian lessons by GCSE theme (via Ollama)
|
||||
- **Essay Marking** — Write Persian essays, get AI feedback and grading (via Claude)
|
||||
- **Dashboard** — Track progress, streaks, and mastery
|
||||
- **Anki Export** — Generate .apkg decks for offline study
|
||||
- **Voice Input** — Speak Persian via microphone (Whisper STT) in the Tutor tab
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `whisper-ollama` conda environment with Python 3.10+
|
||||
- Ollama running locally with `qwen2.5:7b` (or another model)
|
||||
- Claude CLI installed (for essay marking / smart mode)
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
/home/ys/miniforge3/envs/whisper-ollama/bin/pip install gradio genanki fsrs
|
||||
```
|
||||
|
||||
## Running the app
|
||||
|
||||
```bash
|
||||
cd /home/ys/family-repo/Code/python/persian-tutor
|
||||
/home/ys/miniforge3/envs/whisper-ollama/bin/python app.py
|
||||
```
|
||||
|
||||
Then open http://localhost:7860 in your browser.
|
||||
|
||||
## Running tests
|
||||
|
||||
```bash
|
||||
cd /home/ys/family-repo/Code/python/persian-tutor
|
||||
/home/ys/miniforge3/envs/whisper-ollama/bin/python -m pytest tests/ -v
|
||||
```
|
||||
|
||||
41 tests covering db, vocab, ai, and anki_export modules.
|
||||
|
||||
## Expanding vocabulary
|
||||
|
||||
The vocabulary can be expanded by editing `data/vocabulary.json` directly or by updating `scripts/build_vocab.py` and re-running it:
|
||||
|
||||
```bash
|
||||
/home/ys/miniforge3/envs/whisper-ollama/bin/python scripts/build_vocab.py
|
||||
```
|
||||
|
||||
## TODO
|
||||
|
||||
- [ ] Voice-based vocabulary testing — answer flashcard prompts by speaking Persian
|
||||
- [ ] Improved UI theme and layout polish
|
||||
Reference in New Issue
Block a user