AI Tutor — Feature Documentation

Status: DEPRECATED — superseded by kwilo-intelligence-ai-tutor.md. This doc is kept as history. It contains inaccuracies (claims 5 trainer modes; code has 7) and is missing quota, tool-result rendering, and layout integration coverage. See the replacement doc for current state.

Roles: Learner, Trainer
Route: /ai-tutor

Overview

Dual-mode AI-powered educational assistant. For learners: personalized Socratic learning with 5 modes (Explain, Practice, Clear Doubts, Revise, Exam Prep). For trainers: teaching assistant with 5 modes (Lesson Planning, Content Creation, Question Banking, Teaching Ideas, Learner Feedback). Supports SSE streaming, tool execution, RAG from NCERT textbooks, mock tests, multi-language (en/hi/kn), and deep research.

UX Flow

Entry & Setup

1. Navigate to /ai-tutor → role detection (learner vs trainer)
2. Fetch subjects from user's academic context (GET /ai-tutor/subjects)
3. Load conversation history (GET /ai-tutor/conversations)
4. Show mode selector (role-specific), subject dropdown, language selector
5. Generate welcome message + load suggested questions (GET /ai-tutor/suggestions)

Chat Flow

User selects subject + mode + language
  → Types message (+ optional file attachments for trainers)
  → Files upload to GCS via /media/upload
  → SSE stream opens to POST /ai-tutor/chat/stream
  → Events fire: sources → tool_call → text chunks → tool_result → done
  → Conversation auto-saved, ID stored for continuation

SSE Event Types

Event	UI Display
sources	Blue badge "Found X curriculum sources"
tool_call	Purple spinner with tool name + args
tool_result	Code output / search results / images / RAG sources
text	Real-time markdown streaming (KaTeX, GFM tables)
mock_test	Interactive MockTestCard with question navigation
done	Mark complete, save conversation
error	Error banner

Mock Test Flow

1. AI generates test → MockTestCard renders in chat
2. Learner navigates questions (MCQ, Fill Blank, Short Answer, True/False)
3. Submit → POST /ai-tutor/mock-test/{id}/submit
4. Results: score, breakdown, weak topics, follow-up suggestions

Deep Research (Trainers Only)

1. Switch to Research view → enter query + select depth (brief/standard/comprehensive)
2. Streaming progress: planning → searching → analyzing → writing → completed
3. Report rendered with markdown, Mermaid diagrams, Recharts
4. Download (DOCX/Markdown) or Publish as Lesson to distribute to learners

Tool Execution

Tool	Display
Code Execution	CodeOutputDisplay: stdout, stderr, execution time, visualizations
Web Search	SearchResultsDisplay: answer summary + 5 source links
Knowledge Base (RAG)	RAGSourcesDisplay: curriculum results with relevance scores
Image Generation	GeneratedImageDisplay: image + prompt history

API Endpoints

Method	Endpoint	Purpose
GET	/ai-tutor/subjects	Subject list with academic context
GET	/ai-tutor/suggestions	Suggested questions per mode/subject
POST	/ai-tutor/chat/stream	SSE streaming chat with tools
GET	/ai-tutor/conversations	List conversations
GET	/ai-tutor/conversations/{id}/messages	Get messages
POST	/ai-tutor/conversations/{id}/archive	Archive
DELETE	/ai-tutor/conversations/{id}	Delete
GET	/ai-tutor/conversations/{id}/export	Export (json/md/pdf)
POST	/ai-tutor/mock-test/{id}/submit	Submit mock test
GET	/ai-tutor/learning-profile	Learner learning profile
GET	/ai-tutor/review-topics	Spaced review topics
POST	/deep-research/start	Start research (streaming)
GET	/deep-research/quota	Research quota
GET	/deep-research/sessions	List sessions
POST	/deep-research/sessions/{id}/publish	Publish as lesson

Components

Component	Purpose
AITutorPage	Main orchestrator — state, streaming, mode management
ToolCallIndicator	Shows tool execution with spinner
CodeOutputDisplay	Code execution results
SearchResultsDisplay	Web search results
RAGSourcesDisplay	Curriculum knowledge base results
GeneratedImageDisplay	AI-generated images
MockTestCard	Interactive test container
MCQQuestion / FillBlankQuestion / ShortAnswerQuestion / TrueFalseQuestion	Question type renderers
MockTestResults	Score, breakdown, weak topics
ResearchReportRenderer	Research report with markdown, Mermaid, Recharts
MermaidDiagram	Diagram rendering (sanitized SVG)

Known UX Problems

1. No conversation search — can't find old conversations
2. No retry on failure — failed messages have no retry button
3. Long conversations not paginated — loads all messages at once
4. Mock test results don't connect to learning profile — no spaced repetition loop
5. Research can feel frozen — no cancel or interrupt capability
6. File upload has no drag-drop in main chat input
7. Mobile layout — mode/subject selectors take too much space
8. No keyboard navigation on suggestion buttons
9. Language selector doesn't indicate which features support which languages