🏫 Build a Local AI Tutor

🎯 For students: this is what "infrastructure as code" means

Your install is no longer a process — it's a file you can read. The bot's deployment is a piece of source code, just like the application logic itself. You can git diff it. You can git revert it. You can code review the install of your own software.

This is one of the most important shifts in modern software engineering, and it applies to AI systems exactly the same way. The model files are huge binaries, but the wiring that makes them useful — the network, the volumes, the environment variables, the startup order — is plain text, version-controlled, and reproducible. That is what Docker buys you.

🎯 The teacher's path through these stages

Most single teachers stop at Stage 4 and are happy. The voice bot grounds answers in their wiki (stages 0–2), they have a console to inspect it (stage 3), and the nightly worker keeps the wiki tidy (stage 4). That covers 90% of the value with about 3 hours of total install time.

Stages 5–8 are for teachers who want the bot to generate new content (5), want the rich starter media (6), want phone-based remote control (7), or care about sealing the network for compliance audits (8). They're all worth doing eventually — but not on day one.

🎯 Three design rules that shape every decision below

1. Student data never leaves the machine. LlamaIndex, STORM, Hermes, Wiki — all local on Ollama. NotebookLM runs once at install on public reference works only, then the Docker host disconnects from the internet permanently.
2. The bot drafts; the teacher approves. Nothing the bot writes goes live to students without a teacher diff-review. The Wiki uses git so every approval is a recorded signal.
3. The Wiki is plain markdown. No proprietary format, no vector-DB-only knowledge. If any tool in this stack disappears tomorrow, your knowledge base survives unchanged.

🔑 The key insight

These are not competitors — they are five different layers of the same problem. LlamaIndex retrieves grounded passages in real time. STORM drafts long-form lesson articles overnight. NotebookLM is reserved for the one thing only it does well — Audio Overviews on public references. Wiki is the curated, human-readable layer everything else reads from and writes to. Hermes is the night manager that decides which of the others to call. A real production bot uses all five, each in its proper role.

🎯 The big unlock

You already have generate_tefl_*.py scripts that produce content from one-off prompts. This architecture turns those scripts into tools the agent can compose. Instead of you running five scripts in sequence and stitching the outputs together, you tell the bot "build Week 4" and it picks the tools, runs them in order, grounds each step in cited sources, and posts a coherent lesson packet to the Wiki for your morning review.

The teacher's job shifts from authoring to editing — and the corpus compounds: every lesson you ship enriches the Wiki, which makes the next lesson easier to ground.

🔑 Who actually drives the learning

Look at the "driver" column. Three loops are teacher-driven (3, 5, 6 + the implicit one). Two are bot-driven (2, 4). One is student-driven (1). The teacher's signal is the smallest in volume but the highest in quality — it's the only loop that decides what becomes truth. The bot's loops are mechanical: they capture and curate, but they never promote DRAFT to live and they never rewrite the system prompt. This split is intentional — it's what keeps the bot useful instead of confidently wrong.

🎯 Write the Lesson Expectations doc first — it shapes everything else

If you only have 10 minutes for this step, spend them on wiki/pedagogy/expectations.md. That document tells the bot how you teach: your timing preferences, your error-correction style, your homework expectations, how strict to be, how feedback is given. Every lesson Hermes ever drafts, every reply LlamaIndex ever supports, will be informed by this file. It's the highest-leverage artifact in the wiki.

🔒 What "fully offline" buys you

After this step, the bot literally cannot leak student data — not by accident, not by a misconfigured tool, not by an agent's bad decision. Every layer (Whisper, LlamaIndex, Ollama, Hermes, STORM, XTTS) runs against local files on local network. The only path data takes is mic → orchestrator → wiki → speaker, all on one machine. PDPA compliance becomes a property of the network topology, not a policy you have to enforce.

🔒 Why this design preserves the "offline" property

Step 8a cut outbound internet from Docker. LINE and Slack control still works because webhooks are inbound — Cloudflare Tunnel accepts an incoming HTTPS connection from LINE's servers, forwards it to owner-bridge over the tunnel's reverse connection. The reply travels back on the same socket. No outbound DNS, no outbound TCP. The only deliberate exception is the morning SMTP email, which is one allowlisted outbound rule. Everything else stays sealed.

🎯 You're done. What happens next?

1. Tomorrow's first session — student talks to the bot. LlamaIndex grounds the answer in the school profile, lesson expectations, syllabus, and any imported lesson plans you prepared in Step 2. The orchestrator writes the transcript to transcripts/.
2. Tomorrow night at 2 AM — Hermes wakes up. Reads the transcript. Appends a session note to that student's page. Re-embeds the vector index. Emails you a summary.
3. The day after — when that student returns, the bot already knows what they practiced yesterday and still respects every rule in pedagogy/expectations.md. The Wiki has compounded by one session.

From here, every interaction enriches the Wiki, every night Hermes maintains it, and once a week you spend 15 minutes reviewing DRAFTs Hermes proposed. That's the steady state.

🎯 The shortest path to value

If you only have an afternoon, follow Getting Started Steps 1–4 (pull Docker, prepare docs, bootstrap wiki, import) and skip everything after. You'll have a bot that grounds answers in your school's actual documents within an hour — even without Hermes, STORM, or the NotebookLM bootstrap. Add the nightly worker (Steps 5 + 8) the next week, and the NotebookLM media pack (Step 6) once you're sure about your public source list. The Wiki + LlamaIndex alone is already most of the value.