AI engine

We run Claude Sonnet 4.6 as the primary reasoning model for the kid build loop. The constant lives at ANTHROPIC_MODEL in lib/anthropic/client.ts, so the model is swappable in one line as Anthropic ships tier upgrades. Sonnet handles planning, scaffolding, error explanation, and the tool call that becomes the patch. Haiku is the classifier tier in Stage 2, not the kid-facing conversation.

The selection is not about benchmark scores. It is about the safety posture, the refusal behavior, the reading-level steering, and the data-use contract. Anthropic treats a kid-facing use case the way we need a kid-facing use case to be treated. OpenAI moderation handles the content classification on both sides of the call (cheap, fast, and purpose-built for that job) while Anthropic handles the reasoning.

Cost discipline rides on prompt caching. Input is $3 per 1M, output is $15 per 1M, cache reads land at $0.30 per 1M and cache writes at $3.75 per 1M (see computeCost in lib/anthropic/client.ts). The system prompt and the per-template prompt are cached server-side at the Anthropic layer. The running transcript is the only full-price spend per turn. A full build session lands between $1.50 and $3.00. That envelope is what makes $149 per month with 50 sessions a month sit above gross margin.

The concept graph is the translation layer between what a kid wrote and what a parent reads. Every time a kid saves code, Tekku walks the file with a regex detector and tags the concepts it finds. The Stage 1 set is five concepts: state, effects, events, lists, and conditionals. Each carries a kid-facing phrase (grade 5) and a parent-facing phrase (adult English) in lib/concepts/catalog.ts. The detector lives in lib/concepts/detector.ts and is 20 lines long.

The regex shape is narrow on purpose. useState matches state, useEffect matches effects, onClick and its siblings match events, Array.map inside JSX matches lists, and a ternary or short-circuit in JSX context matches conditionals. The detector ships with a known false-positive rate around 5% on strings in JSX attribute values that happen to look like event handlers. Acceptable for Stage 1, documented in the file header. That cost is the price we pay for shipping the weekly email loop today rather than next quarter.

Stage 2 replaces the regex with a Claude Haiku classifier (TODO-002 in TODOS.md). Input is the kid code plus the running AI transcript. Output is concepts with evidence lines and confidence scores. Cost per save is about $0.001. At 100 projects per month that is 30 cents. The accuracy gain is the difference between a parent trusting the weekly email and a parent unsubscribing.

Kids quit products that feel like tests. The teaching evaluator is the reason Tekku never has to ask a kid to prove anything. The evidence of learning is the work itself. A kid who shipped a clicker that survives a page refresh has used state. The detector saw it. The snapshot stores the code and the transcript side by side. The parent-facing claim is auditable, because the evidence line is a real code snippet from a real session.

What the evaluator returns is a concept-per-session record plus a first-time-used flag per concept per kid. The first time a kid uses state across any project is the event that triggers the parent-facing claim "Maya learned state this week." Subsequent uses feed the retention curve on that concept, which is what determines when we promote a concept from "new" to "confident" in the parent dashboard. TODO(learning): the first-to-confident threshold is not yet sourced in published pedagogy work. We will either cite the source at Stage 2 or soften the parent-facing language.

What the evaluator deliberately does not do: grade kid code, score kid output, or expose a rubric to the kid. The kid ships. The parent reads. The concept evidence is the bridge.

Every Claude call is three layers stacked. The first is the system prompt: kid-first voice, pedagogy rules, moderation floor, reading-level targets (grade 3 for errors, grade 5 for checkpoints), refusal patterns, and output format. It lives in lib/prompts/build-assistant.md and is loaded via loadPrompt in lib/ai/system-prompt.ts, with an in-process cache in production. On the wire it is cached at the Anthropic prompt-cache tier so the first token after a cache hit lands fast.

The second layer is the per-template cached prompt. Each starter template (clicker, timer, scorekeeper, drawing pad, reaction tester) has its own scoped prompt that defines what good looks like for that app type. This cuts token cost on repeat sessions and raises answer quality at the same time. Both cached layers read at $0.30 per 1M tokens, against $3 per 1M for a cold input.

The third layer is the running transcript plus the current file state. This is the only per-turn full-price spend. It is bounded so the session never exceeds the $3 soft cap. The transcript is truncated at turn boundaries; no message window management is done inside a single Claude call because the tool-call shape does the right work already.

Guardrails live at two additional layers. Inside the system prompt, refusal patterns and reading-level constraints are declarative. Outside the model, the two build tools (submit_patch, checkpoint_question in lib/ai/tools.ts) are the only write primitives. The model cannot emit free-form code that lands in the workspace. It cannot emit a partial diff. submit_patch demands a full replacement file with an explanation string. checkpoint_question demands exactly three choices. tool_choice is forced on the classifier and idea-generator calls so the model cannot drop out into free text.

A kid holding the Enter key is a predictable failure mode for a conversational AI product. lib/cost/caps.ts implements the Stage 1 cap check with three dimensions. The turn cap is 30 per project per session. The per-parent cap is $30 in the last 24 hours, summed across that parent's kid accounts. The platform cap is $200 in the last 24 hours across everything. When any cap trips, the API returns a cap code and the UI shows a kid-legible message.

The read-then-act shape of the Stage 1 implementation is documented inside the file: a burst of 5 to 10 calls can slip past before the first write lands. The burst mitigation (an advisory-lock plus reservation-row pattern) is in the v1.1 queue and ships before the Stage 2 public pilot. Today the platform is small enough and the founding cohort is controlled enough that the simple shape is enough.

Cost caps are instrumented in Supabase via the ai_transcripts table. Every transcript row carries a cost_usd column computed by computeCost in lib/anthropic/client.ts. The caps query sums that column over the 24-hour window for the parent and for the platform. No cost-estimation math lives outside that computeCost function, so every pricing decision touches one file.