# Persian Learning Agent

Web app + glasses interface for English↔Persian tutoring. Started 2026-06-22.

## What it does

User asks in English ("How do I say good morning?" or "Translate this for me: ...") → gets back:
1. **Persian text** (script)
2. **Transliteration** (English-letter pronunciation guide, "Finglish" style)
3. **English meaning**
4. **Play-audio button** — natural Persian TTS that handles bilingual lines
5. **Tap for word-by-word breakdown**

## Architecture decisions (research findings)

### Translation engine: **Claude (Sonnet 4.6 or Opus 4.7)**
- Best handling of Persian poetic / religious / cultural register (Cameron's family + Sufi context)
- Beats Google Translate dramatically for non-trivial Persian
- DeepL doesn't support Persian
- GPT-4 is also strong but Claude has been the most consistent for Persian formality registers in our testing
- **System prompt approach** (in `prompts/tutor_system.md`) gives consistent response formatting

### Transliteration: **Informal Finglish (Iranian online convention)**
- NOT academic systems (UniPers, DIN 31635, LoC) — those use diacritics English speakers can't read
- Common mapping: `خ → kh`, `ش → sh`, `ع → '`, `غ/ق → gh`, long `ا → aa`, short vowels `a/e/o`
- Claude generates these naturally if prompted to use "informal Iranian phonetic transliteration that English speakers can pronounce"
- Example: صبح بخیر → `sobh bekheyr` → "good morning"

### Text-to-Speech: **ElevenLabs Multilingual v2 (PRIMARY)** + Azure Speech (FALLBACK)
- **ElevenLabs Multilingual v2**: handles Persian + English code-switching in one audio clip with one voice. Critical for bilingual responses like "Here's how you say this: [Persian phrase]. The word [X] means..." The voice stays consistent. Most natural Persian I've heard.
  - Cost: $5/mo for ~30k chars, $22/mo for 100k chars
  - API: simple POST request, returns mp3
  - Endpoint: `https://api.elevenlabs.io/v1/text-to-speech/{voice_id}`
- **Azure Speech Services (fallback)**: Persian (fa-IR) neural voices: `fa-IR-DilaraNeural` (female) and `fa-IR-FaridNeural` (male). Less natural but cheap (~$4/M chars). Doesn't handle bilingual well in one call — you'd need to segment and concat.
- **OpenAI TTS**: multilingual but Persian quality unknown/likely poor
- **Coqui / Mozilla** (open source): can self-host but training Persian voices is non-trivial

### Web framework: **Flask** (small, fast, fits existing pattern)
- Single Python file: `app.py`
- Templates with Jinja2
- One endpoint: `POST /api/ask`
- Static audio served from `/static/audio/`

## File structure

```
/data/cameron/life/projects/persian/
├── README.md                  ← this file
├── app.py                     ← Flask backend (stub, ready to fill)
├── requirements.txt           ← Python deps
├── .env.template              ← API key template (copy to .env, fill in)
├── run.sh                     ← `bash run.sh` to start the dev server
├── prompts/
│   └── tutor_system.md        ← Claude system prompt for the tutor
├── templates/
│   └── chat.html              ← chat UI
└── static/
    ├── chat.js                ← message send + audio playback
    ├── style.css              ← styling
    └── audio/                 ← generated TTS files cached here
```

## What Cameron has to do (~10 min)

1. **Sign up for ElevenLabs:** https://elevenlabs.io/sign-up
   - Free tier gives 10k chars/mo to try
   - Upgrade to Starter ($5/mo) for 30k chars (enough for ~6hr of speech)
2. **Get the API key** from https://elevenlabs.io/app/settings/api-keys
3. **Pick a Persian voice ID:**
   - Browse voices: https://elevenlabs.io/voice-library — filter by Persian
   - Test the multilingual model with sample Persian text
   - Save the voice_id you like
4. **Copy `.env.template` to `.env`** and fill in:
   - `ANTHROPIC_API_KEY` — your existing Claude key
   - `ELEVENLABS_API_KEY` — from step 2
   - `ELEVENLABS_VOICE_ID` — from step 3
5. `pip install -r requirements.txt`
6. `bash run.sh` → opens at http://localhost:5001/persian

## Roadmap (post-scaffolding)

### MVP (v0): basic Q&A
- [ ] User types English question
- [ ] Claude responds with Persian + transliteration + meaning
- [ ] "Play audio" button generates ElevenLabs TTS, caches mp3
- [ ] Chat history persists in browser session

### v1: enrichment
- [ ] "Break down word-by-word" button (tap any Persian phrase)
- [ ] Save phrase to vocabulary list (SQLite)
- [ ] Daily review prompt (5 random phrases from saved list)

### v2: glasses integration
- [ ] Voice input on glasses → STT → POST to `/api/ask` → response on glasses HUD + audio in earbud
- [ ] Proactive mode: at context-triggered moments ("getting coffee" → "want the Persian phrase?")

### v3: spaced repetition + level tracking
- [ ] Track user CEFR level
- [ ] SRS algorithm (SM-2) for vocabulary
- [ ] Adaptive difficulty in prompts

## Honest cost projection
- ElevenLabs: $5/mo light use, $22/mo if used heavily daily
- Claude API: ~$1-5/mo for personal use (few hundred queries)
- Total: ~$10-30/mo when actively using