Question Fields Reference

This reference covers every question field available in the AI Tutor Course Creator (slide builder). Each field corresponds to a column in the tbl_ai_tutor_slide_questions table. Fields are presented in the order they appear in the builder UI.

Question Type

Column:atsq_question_type

Selects the interaction mode for the question. Each type changes which other fields are relevant.

• AI Voice Prompt (ai_voice_prompt) — Student answers by speaking or typing. Best for short, single-word or single-number answers. Hard limit: max 2 voice questions per slide (excluding text-only intro).
• Region Drawing (region_drawing) — Student draws shapes, symbols, lines, or arrows inside designated regions on the slide.
• Grid (grid) — Student fills in grid cells.
• Draggable Labels (draggable_labels) — Student drags word/phrase labels into drop zones on the slide. One label per zone.
• Drag to Buckets (drag_to_buckets) — Student sorts item chips into category buckets. Multiple items per bucket.
• Write Regions (write_regions) — Student types answers into positioned text input boxes on the slide.
• Choice (choice) — Student taps to cycle through fixed options (Yes/No, True/False, </>, =/≠, ∈/∉, etc.).

When the type is Choice, an additional Choice Subtype dropdown appears with options: Yes/No, True/False, </>, </=/>, </>/≤/≥, =/≠, and ∈/∉.

Question Text

Column:atsq_question_text

What the AI tutor speaks aloud (via TTS) and shows to the student. This is the primary instruction for each question.

Guidelines

• Include the complete problem statement. Never write "Solve it" — always state the full problem (e.g., "What is 215 plus 125?").
• Use TTS-friendly text. Uppercase letter names so TTS pronounces them correctly: "line A" not "line a", "point B" not "point b".
• Spell out symbols. TTS cannot pronounce special characters. Say "times" not "×", "minus" not "−", "belongs to" not "∈". See the Unpronounceable Symbols table in the design doc for the full list.
• Never reveal answers. Russian Math is discovery-based. Don't spoon-feed — scaffold so students figure things out themselves.

Template Variables

Keyword Type / Correct Keywords

Column:atsq_correct_keywords

Controls how the student's answer is evaluated. The builder shows two related controls: a Keyword Type dropdown and a Correct Keywords chip input.

Keyword Type Options

Keyword Tips

• Multiple comma-separated keywords act as OR logic: 5, five, 5.0 accepts any of these.
• The platform auto-parses spoken numbers: "three forty" matches the keyword 340.
• For write_regions and choice types, keywords are typically left empty — correctness is determined by the region labels or choice subtype.

Answer Wait

Column:atsq_answer_wait

Controls how long the system waits for silence before processing the student's spoken response. Also affects the Deepgram streaming utterance_end_ms timeout. Harder questions give students more thinking time.

For interactive types (write_regions, drawing, labels), this setting affects how long the student has before auto-submit triggers after completing their input.

Eval Model

Column:atsq_eval_model

Which AI model evaluates the student's answer. Only relevant for questions using AI evaluation (__ai_check__ keyword or AI fallback on voice).

Only upgrade when needed — GPT-4o is slower and more expensive.

Correct Response

Column:atsq_correct_response

What the AI tutor says when the student answers correctly. Required for all graded questions (any question where keywords are not __text_only__ or __any__).

Guidelines

• Must be plain text (never JSON).
• Should reinforce the correct answer: "That's right, {student_name}! 7 plus 3 equals 10."
• Keep it concise — 1-2 sentences.
• Use {student_name}, {answer}, and {matched} template variables for personalization.
• Spell out symbols for TTS (say "equals" not "=").

Wrong Response

Column:atsq_wrong_response

What the AI tutor says when the student answers incorrectly. Required for all graded questions.

Guidelines

• Should guide the student without revealing the answer: "Not quite. Try counting the shapes again."
• Offer a hint or suggest a strategy.
• Never be discouraging — keep the tone supportive.
• Use template variables ({student_name}, {answer}) for personalization.

Hint for AI

Column:atsq_hint

Instructions for the AI evaluator model. Required for all graded questions — validation blocks saving without it.

Purpose by Question Type

• Voice questions: Tells the AI what the correct answer is and how to evaluate spoken responses. Also displayed to the student as a hint after wrong attempts.
• Drawing questions (__ai_check__): Describes what correct and incorrect drawings look like. Must start with "LOOK AT THE IMAGE" for drawing evaluation.
• AI Guess Game: Tells the AI what the correct object/concept is so it can evaluate the student's description.

Writing Effective Hints

• For counting tasks: demand exact counts. Never say "approximately" — write "There must be EXACTLY 6 triangles."
• For symbol drawing: describe what the symbol looks like ("The = sign is two horizontal parallel lines").
• For creative drawing: be visually lenient. Set age-appropriate expectations for kindergarten scribbles.
• Include explicit WRONG examples: "WRONG: fewer than 6, more than 6, random scribbles."

Hint for Student

Column:atsq_student_hint

A separate hint shown to the student on their first wrong attempt. Unlike the AI hint, this is purely for the student's benefit and is not used by the AI evaluator.

• Can include visual guidance ("Look at the first column"), conceptual hints ("Remember, addition is commutative"), or partial solutions.
• Supports template variables: {student_name}, {answer}, {matched}, {answer:instruction}.
• Keep it short and helpful — one sentence.

Student Hint Overlay

Column:atsq_student_hint_overlay

A JSON overlay text array shown as a visual hint on the slide when the student struggles. This appears as an overlay on the slide image itself (similar to teacher overlay text), but is triggered by student difficulty rather than shown with the response.

Format is the same as atsq_overlay_text — a JSON array of text/shape objects with coordinates, sizes, and colors.

Context Rules

Columns:atsq_context_detect and atsq_context_swap

Conditional logic for adaptive questioning. When a student's previous answers match a pattern, the question can dynamically swap its fields.

Context Detect

A JSON rule that checks the student's previous answers on the current slide. Example:

{"question_order": 3, "answer": "no"}

This checks whether the student answered "no" to question 3 on the same slide.

Context Swap

A JSON object with replacement field values that activate when the context_detect rule matches. Can override:

• question_text — Different question phrasing
• correct_keywords — Different acceptable answers
• correct_response — Different feedback
• wrong_response — Different guidance
• hint — Different AI instructions

This enables branching lesson paths where the tutor adapts based on what the student understood.

Drawing Colors

Column:atsq_drawing_colors

Comma-separated hex color codes for the drawing palette or label/bucket items. Controls what colors the student can draw with, or the text of draggable items.

Rules

• Format: #1B3A6B,#CC3333,#2E7D32 (hex codes, comma-separated, no spaces).
• Never use black (#000000) — it is too harsh. Use dark navy (#1B3A6B) instead.
• Match the slide's color scheme. Always sample actual colors from the slide PNG. Never use random colors.
• For connecting-by-shape tasks: use a single dark pen color.
• For connecting-by-color tasks: use the matching color swatches.
• For coloring tasks: use the colors from the slide's legend or pattern.
• For draggable_labels and drag_to_buckets: this field contains comma-separated item texts (not colors). Item text must NOT contain commas — commas break the parser.

Palette Shapes

Column:atsq_palette_shapes

JSON configuration for interactive palette items. The format depends on the question type.

Draggable Labels

{"labels": ["flowers", "birds", "farm animals"]}

Defines the draggable label chips the student can drag to drop zones.

Drag to Buckets

{"items": [{"text": "daisy", "bucket": "Flowers"}, {"text": "pigeon", "bucket": "Birds"}]}

Each item has a text (shown on the chip) and a bucket (which category it belongs to). The bucket value must match the label or title of a drawing region. Add "reusable": true to the JSON root when you have few labels but many target regions.

Shaped Drawing Swatches

{"shapes": {"#CC3333": "triangle", "#2E7D32": "square"}, "hideLegend": "63,13,34,9"}

Maps each palette color to a shape name, rendering SVG shape icons in the swatch instead of plain squares. Available shapes: circle, triangle, square, rectangle, oval, trapezoid, diamond, star. The optional hideLegend value (x,y,w,h in %) covers the slide's printed color legend so students cannot copy from it.

Drawing Regions

Column:atsq_drawing_regions

JSON array of region objects defining where students can draw, write, or drop labels on the slide. Managed visually through the Region Builder in the builder UI.

Format

[{"x": 10, "y": 50, "w": 12, "h": 8, "colors": ["#1B3A6B"], "label": "answer box"}]

• x, y, w, h — Position and size in percentage of slide dimensions. Must be objects with named keys, never nested arrays.
• colors (optional) — Array of expected hex colors. For region_drawing with __ai_check__, including colors triggers a color-match shortcut (skips AI). Omit colors when correctness depends on what the student drew, not just which color they used.
• label — Description for the AI evaluator, or the expected answer text for write_regions. For write_regions, the code checks $region['label'] against the student's typed input.
• desc (optional) — Extra context for the AI evaluator.
• title (for buckets) — The bucket name shown to the student on the drop zone.

Spotlight Region

Column:atsq_spotlight_region

Defines which area(s) of the slide are highlighted while the rest is dimmed. Managed through the Spotlight layer in the Region Builder.

Format

• Single region: x,y,w,h (percentages, e.g., 0,0,50,60)
• Multiple regions: x1,y1,w1,h1; x2,y2,w2,h2 (semicolon-separated for disconnected content like a problem box + its illustration)
• Empty string: no dimming (full slide visible)

Required for all graded questions. Spotlights should trace the PPTX element borders with precision — never use crude full-width rectangles.

Overlay Text (Teacher Pad)

Column:atsq_overlay_text

JSON array of text annotations and shapes displayed on a yellow scratchpad area. Used to show worked solutions, step-by-step explanations, or instructional diagrams after the student answers.

Text Items

{"text": "7 + 3 = 10", "x": 55, "y": 58, "size": 20, "color": "#2e7d32", "font": "mono"}

Shape Items

{"type": "rect", "x": 3, "y": 5, "w": 3.5, "h": 5, "fill": "#CC3333", "stroke": "#999"}

All coordinates are in percentages. Overlay text y-coordinates must be inside the scratchpad region. Default spacing: 7% between lines. Default style: size:20, color:#2e7d32, font:mono for solution lines.

Related Fields

• atsq_overlay_scratchpad — Set to 1 to enable the scratchpad. If this is 0, overlay text is invisible.
• atsq_scratchpad_region — Position of the yellow scratchpad pad: x,y,w,h in percentages. Must be in the dimmed area (outside the spotlight).
• atsq_scratchpad_timing — When the scratchpad appears:
  • response (default, most common) — Shows after the student answers. Prevents revealing the answer before they try.
  • question — Shows with the question. Used for instruction scratchpads (color legends, equation labels).
  • both — Shows during both question and response.

Second Overlay / Second Scratchpad

Columns:atsq_overlay_text_2, atsq_scratchpad_region_2, atsq_scratchpad_timing_2

A second independent scratchpad layer. Useful when a question needs both an instruction scratchpad during the question (e.g., a color legend with timing: question) AND a solution scratchpad after the response (with timing: response). The second scratchpad can be positioned in a different area of the slide and has its own timing control.

Laser Pointer

Column:atsq_pointer

JSON array of timed pointer positions that create a red laser dot on the slide, directing the student's attention to specific elements. Managed through the Pointer layer in the Region Builder.

Format

[{"x": 83, "y": 28, "delay": 0}, {"x": 85, "y": 37, "delay": 1.5}, {"hide": true, "delay": 5}]

• x, y — Percentage coordinates on the slide
• delay — Seconds from question start when the pointer moves to this position
• hide — Set to true to hide the pointer at the given delay

Pointer Styles

Use pointers for diagrams and visual elements only. Never sweep across text. Never place pointers on scratchpad sticky notes.

Brush Size / Interaction Mode

Column:atsq_brush_size

Controls the drawing tool or interaction mode. This is typically set automatically by the question type, but some types have multiple brush options.

Requires Drawing

Column:atsq_requires_drawing

Set to 1 for any interactive question type: write_regions, region_drawing, draggable_labels, drag_to_buckets, choice, and grid. Set to 0 for voice-only questions. This flag tells the student-facing UI to render the interactive canvas layer.

Question Order

Column:atsq_question_order

Order of this question within the slide. Starts at 1 (not 0). The intro __text_only__ question is typically order 1, and graded questions start at order 2. Questions can be reordered by dragging in the builder.