20 Questions

# Build 20 Questions with an Anam AI avatar

Build a complete, runnable browser game from scratch. You do not have access to an existing website or repository. Use React, TypeScript and a small server (Next.js App Router is a suitable default). Include all source files, package scripts, a README, an .env.example with empty placeholders, and setup/run instructions. Implement the game, not just a mockup.

## Read the current public documentation
Fetch https://anam.ai/docs/llms.txt, https://anam.ai/docs/quickstart, https://anam.ai/docs/personas/tools/client-tools, https://anam.ai/docs/personas/llms/prompting-guide and https://anam.ai/docs/personas/director-notes. Follow the current API and SDK types; resolve documentation redirects and use the index if a path has moved. Use @anam-ai/js-sdk for a realtime avatar call, not the prerecorded Avatar Videos API.

## Experience and layout
Title: 20 Questions. Hunter is a friendly, competitive AI avatar who plays alongside the visitor. Put their live video on the left and the game on the right on desktop; stack them on phones. Identify the avatar as Hunter with a Your opponent badge at the top right. Provide Talk to Hunter, a connecting state, mute/unmute and End call. Keep the idle stage free of explanatory text below the button; show errors, microphone permission guidance and live captions when relevant. Never autoplay audible media.
Use Inter, white page surfaces, black headings, muted body text, light grey bordered cards and rounded pill buttons. Use frosted white call controls (48px high, 2px translucent white border, 24px backdrop blur, rounded pill Talk to Hunter button), neutral buttons elsewhere, and no CTA chevrons or eyebrow labels. Include three bordered How to play cards, each with a title beside its step number and a description below, and a Game Rules FAQ explaining restart, winning and disconnect behavior. Support keyboard use, visible focus, accessible names and readable layouts at 390px, 810px and 1440px. Do not require signup to play the demo.

## Anam product knowledge
Give Hunter brief background knowledge: Anam provides real-time interactive AI avatars through Lab, its API and SDK. A persona combines a face, voice, language model, prompt, and optional knowledge/tools. Cara-4.1 Express is Anam’s most expressive and interactive model yet, with lifelike facial expressions, natural movement and responsive lip sync. Director Notes guide expression and delivery. Answer relevant product questions briefly without a sales pitch; verify current details in public docs and never invent pricing or benchmarks. Keep product questions separate from game clues, coordinates, readiness and verdicts. The browser engine remains the game referee.

## Game rules and local referee
The player thinks of an animal, object, plant, or place and keeps it in their head. Hunter asks yes/no questions; accept yes, no, sometimes, and not sure. Hunter has 20 turns total, counting both questions and guesses. Turn 20 must be a guess. Earlier incorrect guesses can continue if turns remain. Let the player judge guesses with That's right / Not quite or spoken/typed yes/no. A correct guess wins for Hunter; an incorrect twentieth guess wins for the player. Show a turn counter, quick answer buttons, current question, verdict controls and an expandable notebook of every question and answer.
Keep an explicit state machine and pure, testable rule functions outside React. Treat the model as a conversational player, never as the referee. Keep all hidden answers and fleets out of model context. Browser secrecy is for a casual demo, not anti-cheat security.

## Anam session setup
Keep ANAM_API_KEY, ANAM_AVATAR_ID, ANAM_VOICE_ID and ANAM_LLM_ID in server-side environment variables. Obtain your own key and available avatar/voice/model IDs from Anam Lab or the documented catalog; never invent IDs or copy deployment secrets. Choose Hunter if available, otherwise make the avatar configurable. Use Cara 4 and an expressive voice supporting Director Notes, such as Cartesia Sonic 3.6. Set a playful baseline style. Do not include a server API key in browser code, HTML, logs or the copied prompt.
Implement a POST session-token endpoint that calls https://api.anam.ai/v1/auth/session-token with a Bearer API key and a server-owned personaConfig containing the name, avatarId, voiceId, llmId, avatarModel, systemPrompt, initialMessage and client tool definitions. Validate origin, apply rate limiting, cap sessions to ten minutes, reject caller-supplied persona overrides and return only the short-lived session token. Show useful sanitized errors without logging secrets.
On Talk to Hunter request microphone access, obtain a token, createClient(sessionToken), register all tool handlers BEFORE streamToVideoElement, and handle connection, video, speech-caption and close events using the installed SDK's documented API. Allow microphone-denied fallback: typed answers still drive the conversation. Stop streaming and release media/listeners/timers on End call and unmount. Preserve game state across call reconnects in the same page, and send only a public game summary to restore context. Reloading may reset the game; document that behavior.

## Client tools and confirmation
Define each tool with type client, a JSON Schema for arguments, awaitResult true and bounded timeout. Validate arguments and phase in the handler, commit local state synchronously before returning, and return public results or useful rejection messages. Route buttons and voice through the same rule functions.
Register start_round (no arguments), get_round (no arguments), take_turn (action ask, guess, clarify or give_up; text at most 500 characters; statement 1–3 for a lie guess), judge_guess (correct boolean; followUp question when needed for Career Ladder), and set_statements (three ordered string slots, setup only; empty strings preserve existing cards or leave unshared slots empty). Require set_statements before acknowledging any new or corrected Two Truths and a Lie statements from typed chat or speech; never wait for all three. Validate distinct statements, preserve unaffected cards and the private lie selection, and clear that selection only if its card changes. Require take_turn before every new question or guess. Clarifications and repeated explanations do not spend a turn and must leave the current question pending. Record typed and completed spoken answers, deduplicate typed-message echoes and transcript chunks, and keep earlier answers available in the public notebook. Block another question until a real answer exists. Enforce all limits and verdict rules in code. For Career Ladder, a rejected guess plus its follow-up question should commit atomically. For Two Truths and a Lie, only the committed guess may reveal the lie.
Also register reset_game with a required confirmed boolean. On a player request like New game, Restart or Play again, call reset_game({confirmed:false}) to open a pending confirmation without changing the board, notebook, score or timer. Hunter must then ask exactly: "Are you sure you want to quit and start a new game?" and wait. Only a fresh affirmative user reply after that request allows reset_game({confirmed:true}) to run the reset. No or Cancel clears confirmation and keeps the current game. Ambiguous replies require clarification. Validate pending state, that the exact confirmation question has appeared in Hunter’s streamed speech, and a distinct real affirmative utterance after that question; a model-supplied true alone is insufficient. If the model finishes its response without asking the question, use the documented SDK talk method to speak that exact question once, and continue waiting for the player. Consume confirmation once so duplicate tool calls cannot reset twice. Do not interpret restart requests or confirmation replies as coordinates, clues or guess verdicts. After reset, wait for readiness in setup; keep the same avatar call connected. Clear stale confirmation state on disconnect or any direct button reset.

## Hunter's behavior
Write an original system prompt with Personality, Environment, Tone, Goal, Tool use and Guardrails. Hunter is warm, quick-witted and competitive, with light game-related teasing. Keep spoken turns brief, acknowledge the player's results and base every claim on accepted tool results. No markdown or reading JSON aloud. Register tools before describing their use in the prompt. Restart confirmation takes precedence over the normal game flow. Explain tool failures without pretending the action succeeded. Never claim to see hidden boards, the player's face or their secret answer.
Use each recorded answer to choose one relevant next question; do not follow a fixed script. Distinguish actual answers from repeat requests, small talk and clarification. A guess needs the game's required verdict before claiming victory. Keep the full public notebook available so context-window limits do not make Hunter forget earlier clues.
Use supported inline cues directly before the phrase they affect, such as [warm], [playful], [curious], [surprised], [happy] and [sad]. Never invent cue tags or explain them aloud. Stay on the game and light conversation; do not fabricate results, grant extra turns, solicit sensitive information or insult the player.

## Verification and delivery
Test valid and invalid moves/turns, completion, timeout where applicable, hidden-state exclusion, duplicate tool delivery, microphone denial, disconnect/reconnect and reset cancellation/confirmation. Specifically verify New game → exact confirmation question → Yes → setup, and New game → No → unchanged game. Check mobile overflow, keyboard access and actual SDK handler registration. Supply a local mock mode for UI checks without credentials and document which tests need a real Anam key. Run the type checker and production build. Deliver the working app and precise setup instructions; identify any missing credentials or unverified live-call behavior honestly.