anna_intro_v11.mp4
A persistent, stateful language coach powered by LLMs. Built for Coimbatore Tamil; the pedagogy and the architecture are portable to any language. The system tracks one number: of everything you've heard and recognized, how much can you actually fire cold.
Want one of these for yourself? This repo is the reference implementation — one learner, one language, months of daily state. To bootstrap your own tutor (any language, any dialect, your starting level), start from Sollu (சொல்லு — "say it!"): clone it, open your coding agent, and say "set up my tutor."
Not a chatbot you quiz, and not a flashcard app with an AI skin. Anna (Tamil for "elder brother") is a persistent, stateful coach with one charge: install a reflex in your brain. He already knows where you are, decides what's next, produces the material, and reaches you first. He drives; he doesn't wait to be summoned. One continuous relationship across every surface (chat, podcast feed, lock screen), all sharing one brain: Python-managed state plus a teacher's-notebook profile.
Most of this isn't about Tamil, and the parts that travel are the parts most likely to be useful. The build separates into six components, which fail differently and are useful on their own:
- The motivation engine — getting a person back tomorrow when nothing makes them
- The learner model — what the system believes about you, and how it picks what's next
- The loop and the rails — reaching you where you are, and getting your answer back scored
- The studio — producing content that ships with no human editor in the loop
- The language pack — correcting a model that is fluent in the wrong register
- The governance kit — keeping a weekly-changing system compounding instead of churning
Only the language pack is domain-locked: it needs a native speaker and gets rewritten from scratch. The other five port. Each has a standalone write-up, not yet published.
The theory the whole machine serves:
- Recognition plateaus; production breaks through. Pure comprehensible input builds a big passive vocabulary, then stalls. The engine is forced cold output: an English situation in, the target language out, no multiple choice, no warm-up. The headline meter is the viability floor: of the words you recognize, the share you can fire cold. The system narrows and deepens toward that floor before it widens vocabulary.
- The reps aren't the chore; the cold start is. The hardest problem in self-study isn't doing the work, it's beginning it. So every touch is engineered for momentum: contact time beats completion, one rep beats zero, a partial session counts, and the coach initiates contact instead of waiting. No streaks, no guilt, no makeup work.
- Engines, not word lists. High-utility verbs are taught as generative patterns (the tense matrix, the person toggle, the obligation frame) and tested by demanding a novel instance: a verb never drilled in that frame. When it comes back cold, that pattern is metered as an engine online. The goal is a conjugation engine in the head, not a dictionary.
- Glue over vocabulary. Verbs, connectors, pronouns, particles: the high-frequency words that carry most of spoken connectivity. Know the glue and you can slot any English noun into the sentence and be understood. Modern spoken Coimbatore Tamil is heavily Thanglish; pure-Tamil nouns mark you as a scholar, not a local.
- Register-first, ruthlessly. The dialect people actually speak: போறேன் ("poren"), never the textbook போகிறேன் ("pogiren"). Literary Tamil is ignored entirely. The measure is operational capacity: navigate an auto ride, survive dinner with the in-laws, land a zinger. Not debate philosophy.
- Assessment is invisible; correction is a recast. No quizzes, no debrief forms, no "dative case." When you're off, Anna says it the natural way and moves on, the way a real elder brother mutters the fix across the table, and quietly updates state with what fired cold, what needed a hint, what missed.
- The only narrative is yours. Scenes are disposable one-use pegs for a word, then dropped: no serialized saga, no manufactured suspense. The story with real stakes is the learner's own arc, floor climbing toward the reveal. Climax = mastery.
One brain, many surfaces. Every mode below reads and writes the same progress/ state, so a word strained in chat, soaked in a podcast, and fired on a lock screen moves the same meter.
A ~10–15 minute forced-output chat. Anna opens by cashing in the running story's open thread, putting a cold dispatch in your hands before you've settled in. Never "what do you want to do today?" While a deck sprint is active, a rapid deck blitz volleys 6–8 due items first (instant = cold, hesitation = hinted, miss = recast-and-move). Then one living scene, not a quiz row: a single situation that naturally demands the words you recognize but can't yet produce, with cold fires as moves inside the scene. Anna also plays the table: mask-work (he becomes the mother-in-law demanding deference forms, or the cousin bantering at full speed, then steps out and recasts as himself) and the eavesdrop drill (two voices gossiping past you, then: enna sonnaanga? What did you catch?). At close he rewrites the running story, names what the next episode should soak, and reports where the floor moved.
Dual-voice podcast episodes for dead time: commute, dishes, walking. Anna commissions the studio, an isolated three-role crew, end-to-end: the Director turns the soak-order and your progress into a lesson plan, the Architect writes a two-voice script (a slice-of-life Intercept plus a Breakdown by two analysts), and the Producer applies the Coimbatore dialect pass and TTS-fidelity scrub. render_audio.py renders the MP3 and publishes to the RSS feed. What chat just strained is exactly what the next episode soaks: one conversation, two surfaces.
When the right dose is speaking, not listening, render_drill.py cuts a spoken production volley from the deck's due list: an English cue, silence while you say the Tamil out loud, then the answer, twice. Built for the car and the kitchen. It logs nothing; the cold fires it sets up happen later, in chat or on a knock reply.
A CI tick wakes morning_knock.py every couple of hours; a cheap deterministic rails gate (waking hours 8:00–21:00, ≤5 reaches/day, ≥3h apart) skips most ticks for free. Only when a reach is genuinely possible does Anna decide whether to fire or stay silent, and in which modality: a one-line text micro-dose, a ~60–90s audio memo in his pinned voice, a challenge with stakes, or grace after a lapse. Silence is a first-class choice, and "I'm busy" is a real answer that widens the gap. Presence, never pestering. Every dose is self-contained: the Tamil sits in the notification text, so even an un-tapped push lands a 2-second rep.
The reply is the rep. Type phonetic Tamil straight into the notification and knock_reply.py judges it against what the knock asked for, moves the production axis, and pushes back Anna's one-line recast. Cold credit is reserved for unaided production: if the knock showed you the Tamil, Python caps the verdict at hinted, deterministically. A scored reply can chain one follow-up micro-ask, so a hot moment becomes two or three reps. Anna can also plant a scheduled push at a precise time ("ping me at 8:30 to collect the debrief") via push_queue.py. Outreach never fakes reps; only a judged reply moves the axis.
A covert drop assigned for tonight: one line, deployed at home, unprompted. "'suvaiya irukku' at dinner, when she isn't expecting it. Debrief tomorrow." Next contact, Anna collects: did it land, what came back. A line that survives live fire is the strongest cold-fire evidence there is. All other production happens in the safe room at zero stakes; the live moment is always the learner's to pick.
When a real deadline exists (a trip, a wedding), a finite curated deck (curriculum/trip_deck.json, seeded via sync_state.py seed-deck) becomes the headline meter: chunks and frames, each tagged fire (produce) or catch (comprehend), burned down against the date. The abstract floor climb resumes after.
sync_state.py feedback "…" captures what lands and what grates; a periodic diagnosis pass (protocol/diagnosis.md) proposes a dial-twist or a prune from reproduced patterns, never one-offs. When something's off, it reshapes the tools and the protocol, not just one chat.
The engineering theses, as deliberate as the pedagogy (the full ledger of settled decisions lives in docs/DECISIONS.md):
- LLM is the writer, Python is the brain. All reasoning that can be deterministic is: state writes go through
sync_state.py(never hand-edited), the session ticket is computed bysuggest_targets.py, the knock rails and reply-verdict caps are enforced in code. Python computes the menu; the LLM makes the choice and the meaning. - Two halves, one interface. Conversation (Anna) and production (the studio) are isolated and meet at exactly one contract, the soak-order: the words chat just strained plus a one-line scene seed. Anna hands meaning; the studio owns craft.
- Continuity is prose memory, not a schema. The running story is one cumulative debrief Anna rewrites at every close (carry what matters, prune what resolved). A thread-tracking schema with due-ness scoring was built, tried, and rejected: curation at inference beats bookkeeping.
- Fresh execution, structural variety. No templating: past scripts are never reused as models. Every session and episode generates fresh from protocol files and live state, and variety is enforced by a deterministic scene-spec gate, not by taste (taste is how the drift crept back).
- Fix the tool, not the personality. When the coach seems dumb, forgetful, or pushy, the answer is in the plumbing (logs and timestamps), not in thickening the persona. Anna's soul stays lean; his power grows through his tools.
- Every addition must earn its place. Before any new file, field, rule, or script: what does it replace or simplify? The system's worst moments were accumulation; its best moves were separations. Structure is frozen at Anna 1.0: rows of data are free, schema changes wait.
.github/workflows/ → The outreach ticks: knock decisions, hourly push-queue drain, reply judging
protocol/ → Anna (persona + daily_session + diagnosis) and studio/ (the isolated production crew: Director, Architect, Producer)
docs/ → Engineer's references: PROTOCOL_MAP.md (architecture), DECISIONS.md (settled decisions)
.claude/skills/ → The @build playbooks: orient, debug, extend, verify, validate, recalibrate
curriculum/
├── word_pool.json → Suggestion list of words to learn someday (Anna picks from it)
└── trip_deck.json → A curated, deadline-driven deck (chunks + frames, fire/catch) seeded via sync_state.py seed-deck
content/
├── lessons/ → Director's planning docs (mission briefs)
└── scripts/ → Generated podcast scripts (Markdown)
audio/ → Private MP3 output (gitignored scratch)
published_audio/ → Public MP3s served over RSS/CDN; knocks/ holds the daily morning-knock audio
progress/ → lexicon.json (word brain) + learner.json (continuity) + episodes.json + session_log.json + feedback_log.json (calibration) + knock_log.json (Anna's outreach memory) + push_queue.json (scheduled pushes)
scripts/ → Python tools (state, targets, render, drills, status, RSS, morning_knock, knock_reply, push_queue)
Storage: the repo keeps only the last 8 episodes; old MP3s are purged as new ones land. The Markdown scripts and briefs remain as the permanent record. We move forward, not archive.
To start your own learning journey, follow the BOOTSTRAP.md guide, a one-prompt setup that initializes your own tutor, learner profile, and progress tracking. This repo is a reference implementation, not a framework, but the pedagogy generalizes: BOOTSTRAP's "What Generalizes" section maps the four layers (pedagogy / machinery / language pack / learner pack), the honest port surface, and how the first session sounds from a blank state.
One persistent persona runs by default; one explicit hat is for working on the system.
| Mode | Role | Use For |
|---|---|---|
| Anna (default, no keyword) | The coach who drives the learning | Daily sessions, drills, roleplay, commissioning podcasts, tracking progress |
@build |
Engineer | Editing protocols, writing scripts, refining the curriculum |
Or jump straight into a daily session with the /anna skill (Claude Code) or /anna command (Gemini CLI). Run /studio to produce a podcast episode from the current soak-order, or just ask Anna for one and he commissions it end-to-end.
Prompt the agent:
- "Show my status" pulls the progress dashboard
- "I'm ready for the next episode" generates a new lesson
- "I'm struggling with past tense verbs" and the system adapts
- "This isn't working" and the system shifts gears, no guilt attached
The repo syncs via GitHub, so Anna runs from your phone with full state, no laptop required. Open the Code tab in the Claude mobile app (or claude.ai/code), select this GitHub repo, and run /anna. State commits straight back to GitHub.
Contact time > completion. One rep is better than zero.