Question Types Reference

The AI Tutor supports several interactive question types, each suited to different kinds of math problems and learning goals. This reference covers every question type, when to use it, and how it works.

1. Voice (ai_voice_prompt)

The tutor asks a question and the student answers by speaking into the microphone or typing in a text box. Voice questions are evaluated against a set of correct keywords.

When to Use

• Simple, instant-recall answers: a single number ("340"), a single word ("yes"), or a very short phrase ("2 and 4")
• Conversational intro questions ("What's your name?", "Have you seen this before?")
• Quick factual recall the student should know by heart ("How many meters in a kilometer?")

When NOT to Use

• Word problems requiring multi-step reasoning — use write_regions instead
• Answers longer than 2-3 words — speech recognition struggles with longer responses
• Any question that requires subtraction, multiplication, or intermediate calculation steps

Hard Limit

Maximum 2 voice questions per slide (excluding __text_only__ intro questions). Voice is the last resort, not the default. Before making a voice question, ask: "Can this be write_regions, draggable_labels, choice, or region_drawing instead?" If yes, use the interactive type.

How It Works

The student's spoken or typed answer is matched against the correct_keywords field using a three-level matching system:

1. Substring match — short keywords use word boundaries; longer keywords use substring matching to handle plurals
2. Fuzzy phrase match — sliding window with per-word fuzzy matching
3. Phonetic match — metaphone + Levenshtein distance for accents and speech-to-text errors

The platform also has spokenNumbersToDigits() which automatically converts spoken numbers to digits, so keywords only need the numeric form (e.g., 140 instead of listing "one hundred forty").

Keyword Modes

The correct_keywords field controls how the answer is evaluated:

• Plain keywords (e.g., 340, yes, no) — try instant keyword match first, then AI fallback if no match
• __text_only__ — no answer expected; the tutor speaks the text and auto-advances. Only use when the text contains NO question or prompt. If it ends with a question mark, use __any__ instead
• __any__ — accept any non-empty answer. Used for open-ended discovery questions where any thoughtful response is valid
• __ai_check__ — AI evaluates the student's answer against the correct response. Used when the answer could be phrased many different ways
• __ai_guess_game__ — structured guessing game where the student describes something and the AI teacher guesses. Used in younger grades (K-2) for engagement. Requires hint to be populated with what the student is describing

2. Drawing (region_drawing)

The student draws directly on the slide inside designated rectangular boxes. A drawing toolbar with color swatches and brush tools appears at the bottom of the screen.

When to Use

• Drawing shapes, geometric figures, or patterns
• Drawing comparison symbols (<, >, =) in boxes between two values
• Connecting items with lines or arrows
• Circling or coloring items (color-legend tasks)
• Ordering items by drawing arrows between them
• Any task where the student needs to physically draw something to demonstrate understanding

How It Works

Each drawing region is a positioned rectangle on the slide where the student can draw. The correct_keywords is always set to __ai_check__ because drawings are evaluated by AI vision (GPT-4o-mini by default, or GPT-4o for counting/complex spatial tasks).

Brush Sizes

The brush_size field controls the drawing tool:

• pen — thin line for precise drawing (comparison symbols, small shapes)
• marker — medium line for general drawing
• thick_marker — thick line for coloring/filling areas
• line — straight line tool for connecting items
• arrow — arrow tool for ordering or showing direction

Color Evaluation

The colors array in each drawing region controls the evaluation path:

• With colors array: The server does a color match pre-check — if the student used the correct colors in the correct regions, it returns CORRECT without calling AI vision. Fast and deterministic. Best for pattern coloring, color-legend tasks, and per-item coloring where correctness = right color in right region.
• Without colors array: The color match is skipped and AI vision evaluates the actual drawing content. Use when correctness depends on what the student drew (shape, pattern, arrangement), not just which color they used.

Pattern Coloring: Per-Item Regions

When a slide has a sequence of items with a color pattern that the student must continue, create one drawing region per empty item, each with the expected color in its colors array. This enables instant color-match evaluation without AI, which is more reliable than single-region AI vision for pattern tasks.

Eval Model Override

For counting tasks and complex spatial evaluation, switch the Eval Model dropdown from GPT-4o Mini to GPT-4o. Mini cannot reliably count shapes in images even with strict hints. GPT-4o is slower and more expensive but significantly better at counting and spatial reasoning.

3. Grid/Write (write_regions)

The student types answers into positioned input boxes overlaid on the slide. Each box appears as a small text field at a precise location, aligned with blanks or answer spaces on the slide image.

When to Use

• Fill-in-the-blank math equations (e.g., "3 + ___ = 8")
• Calculation results where the student needs time to think and compute
• Multi-step word problems where the answer is a number or short expression
• Table/grid fill-in tasks
• Any problem requiring subtraction, multiplication, or intermediate calculation steps (NOT voice)

How It Works

Each region has a label field containing the expected answer. The server checks the student's typed input against label directly — no AI needed for deterministic answers. Set correct_keywords to empty string ("").

Exception: Use __ai_check__ only when the answer is an algebraic expression that can be written multiple ways (e.g., 5*(a/b) vs 5a/b).

Any-Order Answers

When a question has multiple write boxes and the student can enter answers in any order, use pipe-separated labels encoding all permutations. For example, if the answers are -2, 2, and 6:

• Region 0 label: -2|-2|2|2|6|6
• Region 1 label: 2|6|-2|6|-2|2
• Region 2 label: 6|2|6|-2|2|-2

The grading code tries each permutation and picks the best match.

Width Sizing

Limits

Maximum 6 write regions per question. If a problem needs more, split into multiple questions (e.g., "rows 1-2" and "rows 3-4").

4. Labels (draggable_labels)

The student drags word or phrase labels from a floating palette into drop zones positioned on the slide. Each drop zone accepts specific labels.

When to Use

• Classification tasks ("drag each animal to the correct group")
• Matching terms to definitions
• Labeling parts of a diagram
• Ordering items by dragging labels into a sequence
• Any task where the student matches text items to positions on the slide

How It Works

• palette_shapes uses the "labels" key with an array of available label strings: {"labels":["flowers","birds","farm animals"]}
• Each drawing region has a colors array listing which label(s) are correct for that drop zone
• The label field in each region is a descriptive name shown in the builder (not displayed to the student)
• correct_keywords is always set to empty string ("") — grading uses the colors array, not keywords

Example

For a task where the student classifies items into three groups:

• Palette: {"labels":["flowers","birds","farm animals"]}
• Region 1: colors: ["flowers"] — accepts the "flowers" label
• Region 2: colors: ["birds"] — accepts the "birds" label
• Region 3: colors: ["farm animals"] — accepts the "farm animals" label

5. Buckets (drag_to_buckets)

The student sorts item chips from a palette into labeled category buckets. Unlike draggable_labels (one label per zone), each bucket can hold multiple items, making this ideal for sorting and categorization tasks.

When to Use

• Sorting items into categories ("sort these numbers into Even and Odd")
• Grouping by property ("which shapes have 4 sides?")
• Set classification ("drag each element into Set A or Set B")
• Any task where multiple items belong in the same category

How It Works

• palette_shapes uses the "items" key (NOT "labels"). Each item is {"text":"...", "bucket":"..."} where bucket matches a region's label/title
• Each region has a title field (the bucket name shown to the student on the drop zone) and a colors array listing which item texts are correct for that bucket
• correct_keywords is always set to empty string ("")

Critical Differences from Labels

Important Rules

• Item text must NOT contain commas — commas break the parser. Use spaces instead (e.g., {a b} not {a, b})
• One region per category — no need for separate "slot 1"/"slot 2" regions within a bucket
• The drawing_colors field is comma-separated item texts matching the palette items

6. Choice

The student clicks toggle buttons to cycle through predefined options. Each drawing region becomes a clickable button positioned on the slide. This is ideal for problems where every item on the slide needs the same type of binary or comparison response.

When to Use

• True/False evaluation of multiple statements on a slide
• Yes/No questions for a series of items
• Comparison tasks: is the left side less than, equal to, or greater than the right side?
• Equal or not-equal classification
• Set membership (∈ / ∉)
• Any task where the student picks from a small fixed set of options for each item

Subtypes

The subtype is stored in the brush_size field:

Internal Label Values

The region label must use internal values, not display labels. The frontend sends internal values to the server:

Multi-Region Pattern

When a slide has many items that each need the same type of response, use a single question with one drawing region per item. This lets the student see all items at once and work through them freely, without spotlight transitions between items. For example, 12 true/false statements become one question with 12 toggle regions, not 12 separate questions.

Placement

• Place all toggles in a consistent vertical column — same x-coordinate for all regions
• Position the column just past the text end (if text ends at x=74%, place toggles at x=75-76%)
• Typical toggle size: w=4, h=3

7. Keyword Modes — Special Evaluation Behaviors

Several special keyword values control how answers are evaluated, regardless of question type:

Important Rules

• For write_regions, choice, draggable_labels, and drag_to_buckets: always set correct_keywords to empty string. These types are graded by label matching, not keyword matching.
• __text_only__ vs __any__: if the text ends with a question mark or invites a response, use __any__. Only use __text_only__ for pure narration with no question.
• Never invent new keyword modes — only the five listed above exist.

Choosing the Right Question Type

Use this decision guide when creating questions:

Difficulty Levels

Every question should have a difficulty level set via the answer_wait field. This controls both how long the system waits for speech input and the tone of evaluation feedback:

General Rules

• Variety: Aim for at least 3 different question types across a lesson's slides. Never use only one type throughout.
• Max 2 voice per slide: Voice is the last resort. Prefer interactive types (write_regions, draggable_labels, choice, region_drawing).
• Max 6 write regions per question: Split larger problems into multiple questions.
• Never combine voice + drawing: If a problem needs both a verbal response and a drawing action, split into two separate questions.
• Always include hints: Every graded question must have a hint. The AI uses hints to explain the answer when a student struggles.
• Correct and wrong responses are required: Every graded question needs both correct_response (spoken when right) and wrong_response (spoken when wrong).
• Read the full problem: The tutor speaks the question text aloud. Always include the complete problem statement — never write "Solve it" or "Do the problem."