polar-bauhaus

Kausap 🗣️

Personal Tagalog voice-practice app for heritage speakers — real-time spoken roleplay with an AI conversation partner (“kausap”), built on the OpenAI Realtime API over WebRTC.

You pick a scene from Filipino home life (breakfast with Nanay, cooking adobo together, family dinner, Saturday chores, Tita’s merienda visit, calling Lola), set the Taglish dial (how much English your partner mixes in), and just talk. When you’re stuck mid-sentence, the Lifeline button gets you the phrase you need without breaking the scene. After you hang up, a feedback report shows what you said vs. how a native would say it, and new words land in your vocab log.

Setup

npm install
cp .env.example .env.local   # then paste your OpenAI API key
npm run dev

Open http://localhost:3000 in Chrome (or any browser with WebRTC + mic support) and allow microphone access.

Environment variables (.env.local)

Variable	Required	Default	Purpose
OPENAI_API_KEY	yes	—	Server-side only; never sent to browser.
REALTIME_MODEL	no	gpt-realtime-2.1	Realtime speech-to-speech model.
FEEDBACK_MODEL	no	gpt-4o-mini	Model for post-session feedback.
APP_PASSWORD	no	unset (open)	Password-gates every page/route when set.

Deploying (Vercel)

1. Push this branch (or merge it to master).
2. vercel.com → Add New → Project → import willjennings/polar-bauhaus (sign in with GitHub). Framework auto-detects as Next.js; no build settings needed.
3. Under Environment Variables, add OPENAI_API_KEY and — since the URL is public — APP_PASSWORD. Without a password, anyone who finds the URL can hold conversations on your OpenAI credit.
4. Deploy. Visit the *.vercel.app URL; the browser will prompt for the password (any username). HTTPS is automatic, which mobile browsers require for microphone access — so this also unlocks practicing from your phone.

Sessions and vocab are stored per-browser (localStorage), so your phone and laptop keep separate histories.

Two-minute smoke test

1. npm run dev, open the app, pick Cooking together, leave the dial at 3.
2. Click Start conversation and allow the mic. Nanay should greet you in Tagalog within a few seconds, and her words appear in the transcript.
3. Follow along (“Opo, kukunin ko ang toyo”), then tap 🛟 Lifeline — she should briefly break character and teach you a phrase.
4. Click 📞 Hang up. A feedback report appears with corrections and new vocab; check the Vocab tab to see the words saved.
5. Optional A/B: set REALTIME_MODEL=gpt-realtime-2.1-mini in .env.local (~3× cheaper), restart, and repeat — judge the accent, prosody, and Taglish mixing with your own ears. No public benchmark covers Tagalog synthesis quality, so your ears are the test.

Curriculum mode

Underneath free-form scenes sits an optional 10-unit grammar spine (lib/curriculum.ts, original content, u01–u10), each unit with scene seeds — persona, setting, opening line — engineered so the grammar is the natural way to complete the scene (adobo-cooking is the reference seed). The Curriculum page tracks your current unit and rotates seeds.

Every seeded scene runs as a Target scene (engineers and scores chances to produce the unit’s grammar), a Free scene (steered softly toward what you’ve covered), or a Review sprint (a brisk game probing only vocab due in your spaced-repetition box). Advancing units is gated but not locked — it wants can-dos self-checked and two clean Target reports, but you can always force-advance (logged as an override). Lia Prep turns the current unit into printable dinner-table prompt cards; status export pastes a markdown progress summary for asking Claude for help offline.

Notes

• Cost: Realtime audio is billed per token of input/output audio ($32/$64 per 1M audio tokens on gpt-realtime-2.1, $10/$20 on the mini — roughly $0.50–4 per conversation-hour). At 15–60 min/week expect about $1–16/month worst case. Sessions are designed to be short (5–10 min); keep an eye on your OpenAI usage dashboard.
• Why this model: realtime speech-to-speech models cannot be fine-tuned (no provider supports it); per-scenario system prompts are the sanctioned customization path, which is how Kausap works. Filipino ASR is genuinely hard for every vendor in 2026 (~2× English word-error rates on in-the-wild benchmarks), so occasional mis-recognition is expected — the feedback prompt is told to ignore likely transcription errors rather than “correct” them.
• Fallback path: if Tagalog synthesis quality disappoints on both 2.1 and mini, the escape hatch is a pipeline — streaming STT + text LLM + multilingual TTS — swapped in behind lib/realtime.ts’s interface. Not built; revisit only if needed.
• Privacy/storage: everything (sessions, transcripts, vocab) is stored in your browser’s localStorage — there is no database and no accounts. Use the vocab page’s Export JSON to back up words.
• The previous contents of this repo (a Processing.js world-clock experiment) live on in legacy/world-clock/.

Architecture

• app/api/session/route.ts — mints an ephemeral Realtime client secret with the scenario’s system prompt; your API key stays server-side.
• lib/realtime.ts — browser WebRTC session: mic capture, remote audio, transcript events over the data channel, lifeline injection.
• lib/scenarios.ts — scenario definitions + Taglish-dial prompt builder.
• app/api/feedback/route.ts — turns the transcript into structured feedback (corrections, vocab) via a chat-completions call with a JSON schema.
• lib/store.ts — localStorage persistence for sessions and vocab.