Using the AI Assistant

The AI Assistant is a powerful tool built into the AI Tutor Course Creator that generates questions, computes layouts, and manages slide content. It runs Claude Code via SSH and understands the full structure of each lesson's slides, enabling it to produce complete question sets with accurate coordinates and pedagogically sound content.

Opening the Assistant

Click the Assistant button in the slide toolbar to open the side panel. The assistant appears as a chat interface on the right side of the designer. It connects to Claude Code via SSH, which gives it direct access to the slide images, PPTX content, database, and the question design rules defined in ai-tutor-question-design.md.

The assistant panel stays open as you navigate between slides and questions, maintaining conversation context throughout your editing session.

Build Lesson

The Build Lesson command generates questions for all slides in the lesson from the PPTX content. This is typically the first step when setting up a new lesson.

When you trigger Build Lesson, the AI:

1. Analyzes each slide's text and images from the PPTX file
2. Identifies problems, exercises, and instructional content on each slide
3. Determines the appropriate question type for each problem (voice for simple recall, write_regions for calculations, draggable_labels for sorting/matching, choice for multiple choice, etc.)
4. Computes spotlight and scratchpad coordinates by reading the slide image dimensions and content positions
5. Creates overlay text with properly positioned instructions and answer fields
6. Inserts all question records into the database

During generation, a progress modal appears showing:

• Animated stage indicators for each phase of generation
• Cost and token breakdown for the AI processing
• An auto-reload countdown that refreshes the designer when generation completes

Build Lesson is best used once when first creating a lesson. For subsequent adjustments, use Redo Slide or Redo Question instead.

Redo Slide

The Redo Slide command regenerates all questions for the currently displayed slide. It deletes every existing question on that slide and creates new ones from scratch based on the slide content.

Use Redo Slide when:

• The initial Build Lesson output for a particular slide needs significant rework
• The slide image or PPTX content has been updated and questions need to reflect the changes
• Multiple questions on a slide have issues and it is faster to regenerate than fix individually

Redo Slide only affects the current slide. Questions on all other slides remain untouched.

Redo Question

The Redo Question command regenerates just the currently selected question. All other questions on the slide are preserved.

This is the most surgical option and is ideal for:

• Fine-tuning a single question's type, text, or coordinates
• Fixing an incorrect answer or response message
• Adjusting a question that has the wrong difficulty level or pedagogical approach

After regeneration, the question panel updates to show the new content. You can continue editing from there.

Context Sync

The assistant automatically knows which slide and question you are currently viewing. A context file (.claude-tmp/ai-tutor-builder-context.json) is auto-updated whenever you switch slides or select a different question in the questions panel.

This means you can simply say things like "fix this question" or "redo this slide" and the assistant knows exactly what you are referring to. You do not need to specify slide numbers or question IDs.

The context file includes:

• Current lesson and slide identifiers
• Selected question ID and order
• Slide image path and dimensions
• Current question data (type, text, coordinates, responses)

Restart

The Restart button clears the assistant conversation history and starts a fresh session. Use this when:

• The assistant seems confused or is referencing outdated information from earlier in the conversation
• You are switching to a completely different task
• You want a clean slate after a series of complex edits

Restarting does not affect any questions or data in the database. It only resets the conversation context.

How the AI Generates Questions

Understanding the generation process helps you work more effectively with the assistant:

1. Slide Analysis — The AI reads the slide image and parses text positions from the PPTX file. It identifies which areas contain problems, instructions, diagrams, and empty space.
2. Question Type Selection — Based on the content, the AI selects the most appropriate question type:
   • Voice — For simple verbal recall, reading numbers aloud, or describing observations (limited to 2 per slide maximum)
   • write_regions — For any numeric or calculated answer, even simple ones. All fill-in answers use this type, never voice.
   • draggable_labels — For sorting, ordering, categorizing, or placing items into groups
   • choice — For multiple-choice questions with distinct options
   • region_drawing — For drawing shapes, lines, or marking areas on the slide
   • buckets — For drag-and-drop categorization into labeled containers
3. Coordinate Computation — The AI reads the slide image to determine spotlight regions (which area to highlight), scratchpad placement (always in the dimmed area, never overlapping the spotlight), and overlay text positioning.
4. Content Creation — The AI writes question text that reads the full problem aloud (never just "Solve it"), creates correct and wrong responses following Russian Math pedagogy (rigorous, discovery-based, no spoon-feeding), and sets appropriate hints.
5. Database Insertion — All question data is inserted into tbl_ai_tutor_slide_questions with the computed coordinates, and a browser reload is triggered so you see the results immediately.

The AI follows the comprehensive rules defined in ai-tutor-question-design.md, which covers question types, spatial layout, coordinates, spotlights, scratchpads, overlays, difficulty progression, feedback tone, and pedagogical principles.

After Generation

Once questions are generated, you should:

1. Review the questions panel — Check each question's type, text, correct keywords, and response messages. Make sure the content matches what is shown on the slide.
2. Preview the lesson — Use the lesson preview to experience the questions as a student would. Listen to the TTS narration, test interactions, and verify the flow makes sense.
3. Fine-tune coordinates — If a spotlight or scratchpad is slightly misaligned, use the Region Builder tool to visually adjust positions. The builder shows an interactive overlay on the slide image.
4. Adjust text and responses — Edit question text, correct/wrong responses, and hints directly in the question form fields. Remember that question text should always include the full problem statement.
5. Test voice questions — Verify that voice-based questions accept the expected keywords and that the TTS reads the question naturally. Check that letter references use uppercase ("line A" not "line a") for proper TTS pronunciation.

If a question needs more than minor adjustments, use Redo Question to regenerate it. If an entire slide's questions are off, use Redo Slide.