Getting Started with AI Tutor Course Creator

The AI Tutor Course Creator is a tool in the Admin panel for creating interactive math lessons from PowerPoint slides. Students work through slides with an AI tutor named Ms. Irina, who asks questions, evaluates answers, and provides real-time feedback. This guide covers the core concepts you need to understand before building your first lesson.

Overview

The AI Tutor Course Creator transforms static PPTX presentations into fully interactive lessons. Each slide becomes a learning station where Ms. Irina guides the student through problems, provides hints when they struggle, and gives encouragement when they succeed. Students interact using voice responses, drawing on the screen, dragging labels, filling in answer regions, and selecting multiple-choice options.

The system supports a wide variety of question types including:

• Voice responses — students answer verbally and speech-to-text evaluates their response
• Write regions — students write or type answers into designated areas on the slide
• Draggable labels — students drag answer labels to the correct positions
• Drawing regions — students draw shapes, lines, or diagrams that AI evaluates visually
• Multiple choice — students select from presented options
• Bucket sorting — students drag items into categorized buckets
• Region drawing — students draw directly on specific areas of the slide, evaluated by AI vision

The AI tutor reads each question aloud using text-to-speech, waits for the student's response, checks it against the correct answer (or uses AI evaluation for complex answers), and then provides appropriate feedback before moving to the next question.

How to Access the AI Tutor Course Creator

Go to Admin → AI Tutor Builder in the admin navigation menu. This opens the main page showing all existing courses (grade levels) in a table. From here you can:

• Click View Lessons on any course to see its lessons, then click into a lesson to open the slide editor.
• Click the Import PPTX button (top right) to import a new lesson from a PowerPoint file.
• Delete a course with the Delete button (this removes all its lessons, slides, and questions).

Content Hierarchy

The AI Tutor system organizes content in a four-level hierarchy:

Course

A course represents a grade level or curriculum track. For example, "Grade 3" or "Grade 4". Courses are created automatically when you import a PPTX file for a grade that doesn't have a course yet. The grade dropdown in the import modal marks these as "(new)". Courses serve as containers for lessons.

Lesson

A lesson corresponds to a single PPTX file that has been imported. Each lesson covers a specific topic within the grade level. For example, "Lesson 5: Euler-Venn Diagrams, Subsets" within Grade 3. Lessons contain a sequence of slides that students work through from beginning to end.

Slide

Each slide is one page from the original PPTX presentation. When a PPTX is imported, the system creates a record for each slide and stores the slide as a PNG image. Slides are displayed in order and students progress through them sequentially. Slides can be enabled or disabled:

• Enabled slides are shown to students during the lesson and contain interactive questions.
• Disabled slides are skipped during playback. Solution slides (slides that show answers to problems) should be disabled so students do not see the answers before attempting the problems.

Question

Each slide has one or more questions that the AI tutor asks the student. Questions are ordered within a slide using the question_order field. The ordering follows these rules:

• Question order starts at 1 (not 0).
• Order 1 is typically an introductory __text_only__ question. This is a non-graded question where Ms. Irina introduces the slide content, reads the problem setup, or provides context. The student does not need to answer — the lesson auto-advances after the text is read aloud.
• Order 2 and beyond are the graded questions where students must provide answers. These are the interactive questions that test the student's understanding.

A slide can have as many questions as needed. For example, a slide showing four arithmetic problems might have five questions total: one __text_only__ introduction at order 1, and four graded questions at orders 2 through 5.

Importing a PPTX Lesson

To import a new lesson from a PowerPoint file:

1. Go to Admin → AI Tutor Builder.
2. Click the Import PPTX button in the top-right corner. A modal dialog opens.
3. Select a .pptx file from your computer. If the filename follows the naming convention (e.g., Grade 3_Lesson 5_Euler-Venn_diagrams.pptx), the Grade, Lesson Number, and Title fields will auto-fill from the filename.
4. Review and adjust the fields if needed:
   • Grade — select from Kindergarten through Grade 8. Grades that don't have an existing course yet are marked "(new)" and will be created automatically.
   • Lesson Number — the lesson sequence number within the grade.
   • Lesson Title — a descriptive title for the lesson topic.
5. Click Import. A progress panel appears in the bottom-right corner showing the import status.
6. The import process:
   • Parses the PPTX file and extracts each slide
   • Renders each slide as a PNG image stored in public/courses/BYOM/grade_{n}/lesson_{nn}/
   • Creates a course record if the grade is new
   • Creates a lesson record linked to the course
   • Creates a slide record for each page in the PPTX
7. After import completes, the browser automatically redirects to the slide editor for the new lesson, starting at slide 1.

PPTX Filename Convention

For automatic field filling, name your PPTX files in this format:

Grade {N}_Lesson {N}_{Topic}.pptx

Examples:

• Grade 3_Lesson 5_Euler-Venn_diagrams,_subsets.pptx
• Grade 4_Lesson 2_Solution_sets.pptx
• Kindergarten_Lesson 1_Counting.pptx

Underscores in the topic portion are converted to spaces automatically.

Key Concepts for Lesson Designers

Spotlight and Scratchpad

Each question can define two important visual regions on the slide:

• Spotlight — the area of the slide that is highlighted and fully visible to the student. This focuses the student's attention on the relevant problem or content. The rest of the slide is dimmed with a semi-transparent overlay.
• Scratchpad — a work area placed in the dimmed region of the slide where students can write, draw, or interact. The scratchpad must never overlap with the spotlight area.

Overlay Text

Text can be overlaid on the scratchpad area to display the question, provide instructions, or show answer options. Overlay text coordinates are positioned relative to the slide dimensions, and the text appears inside the scratchpad region.

Ms. Irina Welcome Slide

The first slide of each lesson includes a welcome interaction from Ms. Irina. For the very first lesson of each grade (e.g., Grade 3 Lesson 1), the slide image shows Ms. Irina's character. For all subsequent lessons, the original PPTX title slide image is kept, but Ms. Irina's welcome questions (asking the student's name and introducing the topic) are still included.

Question Types and Keywords

Each question has a correct_keywords field that determines how the student's answer is evaluated:

• Plain keywords (e.g., yes, 5, triangle) — the system tries an instant text match first, then falls back to AI evaluation if no match is found.
• __text_only__ — no answer is expected; the lesson auto-advances after the text is read. Used for introductory slides and transitions.
• __ai_check__ — AI evaluates the student's drawing or written input using vision. Used for region_drawing and write_regions question types.
• __any__ — any non-empty answer is accepted. Used for open-ended discovery questions.
• __ai_guess_game__ — a guessing game where the student describes something and AI tries to guess what it is.

Required Fields for Graded Questions

Every graded question (order 2 and above) must have:

• Question text (atsq_question_text) — what Ms. Irina says aloud to the student.
• Correct response (atsq_correct_response) — what Ms. Irina says when the student answers correctly.
• Wrong response (atsq_wrong_response) — what Ms. Irina says when the student answers incorrectly.
• Hint (atsq_hint) — a hint provided if the student is struggling. The builder validation will block saving without a hint.

Disabling Solution Slides

Many PPTX lessons include solution slides that show the answers to problems. These slides should be disabled in the designer so students do not see the answers before attempting the problems themselves. When a slide is disabled, it is simply skipped during lesson playback.

Database Tables

For developers working with the system, the key database tables are:

• tbl_ai_tutor_courses — course definitions (grade levels)
• tbl_ai_tutor_lessons — lesson records linked to courses
• tbl_ai_tutor_slides — slide records linked to lessons, with ordering and enabled/disabled status
• tbl_ai_tutor_slide_questions — question records linked to slides, containing question text, correct keywords, hints, responses, layout coordinates, and question type configuration

Additional Documentation

For detailed technical documentation on building questions, refer to these internal docs:

• Question Design Rules — question types, spatial layout, coordinates, spotlights, scratchpads, overlays, difficulty calibration, and feedback tone guidelines.
• Code Internals — the choice type system, voice and Deepgram integration, noise filtering, and layout generation.
• Slide Generation — HTML-to-PNG slide generation process, templates, branding, and CLI workflow.