Gemini AI
Handles the two-step AI generation pipeline — the core differentiator of LessonPlay. Gemini processes lesson content + learning objectives to produce (1) structured questions and (2) a self-contained HTML game that runs in a sandboxed iframe.
Overview
- SDK:
@google/genai npm package (GoogleGenAI class)
- Input: Lesson text content + learning objective + objective type
- Step 1 Output: 8-10 structured questions as JSON (for scoring/analytics)
- Step 2 Output: Self-contained HTML game (inline CSS/JS, no external deps) that renders the questions
- Key: Questions test understanding, not recall. Games are unique every time.
- Format: Step 1 uses structured JSON output; Step 2 uses plain text (HTML string)
When to Use This Skill
- Building or modifying the two-step generation pipeline
- Engineering or iterating on the question generation prompt
- Engineering or iterating on the HTML game generation prompt
- Parsing and validating Gemini's structured output
- Validating generated HTML (postMessage protocol, no external URLs)
- Handling generation errors or retries
- Mapping objective types to question/game formats
Key Concepts
SDK Usage
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey });
const response = await ai.models.generateContent({ model, contents, config });
const text = response.text; // property, NOT a method
Structured Output
Use config.responseMimeType: "application/json" and config.responseSchema to enforce JSON structure. The SDK handles schema validation — no need to manually parse or hope for correct formatting.
Objective Type → Question Format Mapping
| Objective Type |
Preferred Question Types |
| Understand |
Multiple choice (concept questions) |
| Explain |
Multiple choice (why/how questions) |
| Apply |
Multiple choice (scenario-based) |
| Distinguish |
Categorization (sort into groups) |
| Perform |
Ordering (sequence steps) |
| Analyze |
Multiple choice + categorization |
Calling from Convex
Gemini calls MUST happen in a Convex action (not query or mutation). Use ctx.runMutation(internal.xxx.yyy, args) to store results in the database.
Question Quality Markers
- Tests understanding over recall
- Wrong answers are plausible misconceptions, not random
- Explanation teaches, not just confirms
- Question maps to the stated learning objective
HTML Game Generation Requirements
The generated HTML must:
- Be a complete
<!DOCTYPE html> document with inline <style> and <script>
- Include
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- Use no external dependencies (no CDN scripts, no external CSS, no images via URL)
- Implement the postMessage communication protocol (GAME_READY, ANSWER_SUBMITTED, GAME_OVER)
- Use CSS relative units (%, vh, vw, rem) and pointer events (not click-only)
- Have touch targets >= 44px
- Not use localStorage, sessionStorage, fetch, or XMLHttpRequest (sandbox blocks these)
HTML Validation
Before storing, validate:
- Contains
postMessage or port.postMessage code
- No external
src= or href= pointing to other domains
- Contains the question data
- Is structurally valid HTML
Related Files
convex/generate.ts — Gemini API action (two-step: questions + HTML game)docs/PRD.md — Architecture and AI generation sections
Reference Files
- reference.md — Prompt templates, API examples, HTML generation
1---2name: gemini-ai3description: Gemini API integration for generating pedagogically-grounded game questions from lesson content4---56# Gemini AI78Handles the two-step AI generation pipeline — the core differentiator of LessonPlay. Gemini processes lesson content + learning objectives to produce (1) structured questions and (2) a self-contained HTML game that runs in a sandboxed iframe.910## Overview1112- **SDK**: `@google/genai` npm package (`GoogleGenAI` class)13- **Input**: Lesson text content + learning objective + objective type14- **Step 1 Output**: 8-10 structured questions as JSON (for scoring/analytics)15- **Step 2 Output**: Self-contained HTML game (inline CSS/JS, no external deps) that renders the questions16- **Key**: Questions test understanding, not recall. Games are unique every time.17- **Format**: Step 1 uses structured JSON output; Step 2 uses plain text (HTML string)1819## When to Use This Skill2021- Building or modifying the two-step generation pipeline22- Engineering or iterating on the question generation prompt23- Engineering or iterating on the HTML game generation prompt24- Parsing and validating Gemini's structured output25- Validating generated HTML (postMessage protocol, no external URLs)26- Handling generation errors or retries27- Mapping objective types to question/game formats2829## Key Concepts3031### SDK Usage3233```typescript34import { GoogleGenAI } from "@google/genai";35const ai = new GoogleGenAI({ apiKey });36const response = await ai.models.generateContent({ model, contents, config });37const text = response.text; // property, NOT a method38```3940### Structured Output4142Use `config.responseMimeType: "application/json"` and `config.responseSchema` to enforce JSON structure. The SDK handles schema validation — no need to manually parse or hope for correct formatting.4344### Objective Type → Question Format Mapping4546| Objective Type | Preferred Question Types |47|----------------|------------------------|48| Understand | Multiple choice (concept questions) |49| Explain | Multiple choice (why/how questions) |50| Apply | Multiple choice (scenario-based) |51| Distinguish | Categorization (sort into groups) |52| Perform | Ordering (sequence steps) |53| Analyze | Multiple choice + categorization |5455### Calling from Convex5657Gemini calls MUST happen in a Convex **action** (not query or mutation). Use `ctx.runMutation(internal.xxx.yyy, args)` to store results in the database.5859### Question Quality Markers6061- Tests understanding over recall62- Wrong answers are plausible misconceptions, not random63- Explanation teaches, not just confirms64- Question maps to the stated learning objective6566### HTML Game Generation Requirements6768The generated HTML must:69- Be a complete `<!DOCTYPE html>` document with inline `<style>` and `<script>`70- Include `<meta name="viewport" content="width=device-width, initial-scale=1.0">`71- Use no external dependencies (no CDN scripts, no external CSS, no images via URL)72- Implement the postMessage communication protocol (GAME_READY, ANSWER_SUBMITTED, GAME_OVER)73- Use CSS relative units (%, vh, vw, rem) and pointer events (not click-only)74- Have touch targets >= 44px75- Not use localStorage, sessionStorage, fetch, or XMLHttpRequest (sandbox blocks these)7677### HTML Validation7879Before storing, validate:80- Contains `postMessage` or `port.postMessage` code81- No external `src=` or `href=` pointing to other domains82- Contains the question data83- Is structurally valid HTML8485## Related Files8687- `convex/generate.ts` — Gemini API action (two-step: questions + HTML game)88- `docs/PRD.md` — Architecture and AI generation sections8990## Reference Files9192- [reference.md](reference.md) — Prompt templates, API examples, HTML generation
seanchiuai