Overview

The AI Chatbot is a guided help system integrated into the quiz portion of the mobile application. It provides structured, curriculum-aligned explanations when a student needs additional support. It is not a free-form chatbot; instead, the user selects from predefined prompts, and the AI generates controlled, relevant responses.

The chatbot appears as a popup with a conversation-style interface. AI messages appear on the left, and user-selected prompts appear on the right. The popup includes conversation history, timestamps, optional sound effects, UI animations, and multilingual support.

Core Purpose

• Provide clarification for quiz questions in a controlled format.
• Maintain alignment with existing curriculum content.
• Prevent off-topic or unrestricted AI interactions.
• Help students without requiring teacher intervention.

Main Features

1. Prompt-based interaction

   • No free text input.
   • User selects from predefined follow-up prompts.

2. AI-driven responses

   • Responses are generated using API models.
   • Prompts include the detected topic of the question.

3. Conversation UI

   • Chat-style layout:
     • AI messages on the left
     • User prompt selections on the right
   • Scrollable message history

4. Multilingual Support

   • English
   • Russian
   • Kazakh

5. Additional Enhancements

   • Timestamps on messages
   • Animated popup transitions
   • Optional message sound effects
   • Configurable chatbot personality (name, tone)
   • Clean and consistent visual design

Architecture Overview

Key Files

• main.dart
  Application entry point; includes routing to quiz and chatbot screens.

• chat_popup.dart
  UI for the chatbot popup. Handles:

  • conversation rendering
  • prompt buttons
  • language switching
  • animations
  • sound triggering

• ai_service.dart
  Handles communication with the AI model API. Responsible for:

  • building structured prompts
  • sending requests
  • parsing responses

• sound_service.dart
  Plays optional sound effects for messages.

• quiz_data.dart
  Provides quiz content, including question text and topic metadata.

Data Flow Summary

1. User answers a quiz question.
2. User taps the help/lightbulb button.
3. Chatbot popup opens.
4. Topic is determined based on the current quiz question.
5. User selects a prompt:
   • “Explain in simpler terms”
   • “Give an example”
   • “Explain further”
6. ai_service builds a structured prompt and sends it to the API.
7. Response is returned and displayed as a left-aligned AI message.
8. The selected prompt is shown as a right-aligned user message.
9. Conversation history accumulates until the popup is closed.

Setup Requirements

• Flutter (latest stable recommended)
• Gemini or compatible model API key
• Internet connection for API calls
• Assets folder for sound effects:

Format of .env (located in root; where README is)

GEMINI_API_KEY=KEY
GEMINI_MODEL=gemini-2.5-flash
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/models

Troubleshooting

• if there is an issue with flutter run, delete the build folder