YeboLearn AI Features

Deep dive into AI-powered features using Google Gemini.

Overview

YeboLearn integrates Google Gemini AI to provide intelligent educational features across all user roles.

AI Service Architecture

┌─────────────────────────────────────────────────────────┐
│                     AIService                            │
│                                                         │
│  ┌─────────────────┐    ┌─────────────────┐            │
│  │  Gemini Flash   │    │  Gemini Pro     │            │
│  │  (Fast, cheap)  │    │  (High quality) │            │
│  └────────┬────────┘    └────────┬────────┘            │
│           │                      │                      │
│           └──────────┬───────────┘                      │
│                      │                                  │
│              ┌───────▼───────┐                         │
│              │  Redis Cache  │                         │
│              │  (1hr TTL)    │                         │
│              └───────────────┘                         │
└─────────────────────────────────────────────────────────┘

Model Selection

Use Case	Model	Reason
Chatbot, tutoring	Flash	Fast, interactive
Essay grading	Pro	Complex analysis
Lesson plans	Pro	Comprehensive output
Quiz generation	Flash	Structured, fast
Reports	Flash/Pro	Based on complexity

Features by Role

Student Features

1. AI Tutor (24/7 Homework Help)

// Request
POST /api/ai/tutor
{
  "question": "How do I solve 2x + 5 = 15?",
  "subject": "Mathematics",
  "gradeLevel": "Grade 7",
  "context": "We're learning about linear equations"
}

// Response
{
  "success": true,
  "data": {
    "response": "Let's solve this step by step!\n\n**Step 1:** We need to isolate x...",
    "followUpQuestions": [
      "What happens if we have 3x + 5 = 20?",
      "Can you try solving 2x - 3 = 9?"
    ]
  }
}

Key Principles:

• Never gives direct answers
• Guides step-by-step
• Encourages critical thinking
• Age-appropriate language

2. Personalized Learning Path

// Input
POST /api/ai/learning-path
{
  "studentName": "John",
  "subject": "Mathematics",
  "currentLevel": "Grade 6",
  "strengths": ["Addition", "Basic geometry"],
  "weaknesses": ["Fractions", "Word problems"],
  "goals": ["Master fractions", "Improve problem-solving"]
}

// Output
{
  "duration": "6 weeks",
  "path": [
    {
      "week": 1,
      "topic": "Fraction Fundamentals",
      "activities": [
        "Visual fraction practice",
        "Pizza fraction game"
      ],
      "resources": [
        "Khan Academy: Fractions Intro",
        "Fraction flashcards"
      ]
    },
    // ... more weeks
  ]
}

Teacher Features

1. Lesson Plan Generator

// Input
POST /api/ai/lesson-plan
{
  "subject": "Science",
  "topic": "Photosynthesis",
  "gradeLevel": "Grade 5",
  "duration": 45,
  "learningObjectives": [
    "Explain what photosynthesis is",
    "Identify the parts of a plant involved"
  ],
  "curriculumFramework": "Cambridge Primary"
}

// Output
{
  "title": "The Amazing Process of Photosynthesis",
  "objectives": [
    "Students will be able to define photosynthesis",
    "Students will identify leaves, stem, and roots",
    "Students will explain why plants need sunlight"
  ],
  "materials": [
    "Real plant specimen",
    "Diagram of plant anatomy",
    "Colored pencils"
  ],
  "introduction": "Begin by asking: Have you ever wondered how plants eat?...",
  "mainActivity": "1. Show the plant specimen...",
  "assessment": "Quick quiz with 5 questions...",
  "conclusion": "Review key terms: chlorophyll, oxygen, glucose...",
  "homework": "Draw and label a plant, showing photosynthesis"
}

2. Quiz Generator

// Input
POST /api/ai/quiz
{
  "subject": "History",
  "topic": "Ancient Egypt",
  "gradeLevel": "Grade 4",
  "numberOfQuestions": 10,
  "questionTypes": ["multiple-choice", "true-false"]
}

// Output
{
  "questions": [
    {
      "type": "multiple-choice",
      "question": "What river was essential to Ancient Egyptian civilization?",
      "options": [
        "A) Amazon River",
        "B) Nile River",
        "C) Ganges River",
        "D) Mississippi River"
      ],
      "correctAnswer": "B",
      "explanation": "The Nile River provided water for farming and transportation."
    },
    {
      "type": "true-false",
      "question": "Pyramids were built as tombs for pharaohs.",
      "correctAnswer": "True",
      "explanation": "The pyramids served as grand burial sites for Egyptian rulers."
    }
    // ... more questions
  ]
}

3. Essay Grader

// Input
POST /api/ai/grade-essay
{
  "essayText": "The water cycle is when water goes up and down...",
  "rubric": [
    { "criteria": "Content Accuracy", "maxPoints": 30 },
    { "criteria": "Organization", "maxPoints": 25 },
    { "criteria": "Grammar & Spelling", "maxPoints": 20 },
    { "criteria": "Vocabulary", "maxPoints": 15 },
    { "criteria": "Conclusion", "maxPoints": 10 }
  ],
  "gradingGuidelines": "Focus on understanding of evaporation, condensation, precipitation"
}

// Output
{
  "totalScore": 72,
  "maxScore": 100,
  "criteriaScores": [
    {
      "criteria": "Content Accuracy",
      "score": 22,
      "feedback": "Good understanding of basic concepts. Missing details on condensation process."
    },
    // ... more criteria
  ],
  "feedback": "This essay shows a basic understanding of the water cycle. The student correctly identifies evaporation and precipitation but could expand on how condensation forms clouds..."
}

4. Worksheet Generator

// Input
POST /api/ai/worksheet
{
  "subject": "Mathematics",
  "topic": "Multiplication Tables (1-5)",
  "gradeLevel": "Grade 2",
  "numberOfProblems": 15,
  "includeAnswerKey": true
}

// Output
{
  "problems": [
    "1. 2 × 3 = ___",
    "2. 4 × 5 = ___",
    // ...
  ],
  "answerKey": [
    "1. 6",
    "2. 20",
    // ...
  ]
}

Parent Features

1. Progress Reports

// Daily Report
POST /api/ai/daily-report
{
  "studentName": "Sarah",
  "attendanceToday": "present",
  "recentGrades": [
    { "subject": "Math", "score": 85, "maxScore": 100, "date": "2024-01-15" }
  ],
  "behaviorNotes": "Participated actively in class discussion",
  "classParticipation": "Excellent"
}

// Returns 2-3 paragraph summary

// Weekly Report
POST /api/ai/weekly-report
{
  "studentName": "Sarah",
  "weekStartDate": "2024-01-08",
  "weekEndDate": "2024-01-12",
  "attendanceRate": 100,
  "grades": [
    { "subject": "Math", "averageScore": 82, "trend": "improving" },
    { "subject": "English", "averageScore": 78, "trend": "stable" }
  ],
  "strengths": ["Problem-solving", "Reading comprehension"],
  "areasForImprovement": ["Spelling", "Time management"]
}

// Returns 4-5 paragraph detailed report

2. EduAssist Chatbot

Parent support chatbot for questions about:

• Platform features
• Child's progress
• Educational guidance
• School policies

POST /api/ai/chatbot
{
  "question": "How can I help my child with math homework?",
  "context": {
    "schoolName": "Springfield Elementary",
    "userRole": "parent"
  }
}

School Admin Features

1. Behavior Analysis

POST /api/ai/behavior-analysis
{
  "studentName": "Michael",
  "behaviorLogs": [
    { "date": "2024-01-10", "incident": "Disrupted class", "severity": "minor" },
    { "date": "2024-01-12", "incident": "Late to class", "severity": "minor" }
  ],
  "academicPerformance": [
    { "subject": "Math", "trend": "declining" },
    { "subject": "English", "trend": "stable" }
  ]
}

// Output
{
  "analysis": "The pattern of behavior suggests possible engagement issues...",
  "recommendations": [
    "Schedule a parent-teacher meeting",
    "Consider one-on-one academic support",
    "Implement a daily check-in routine"
  ],
  "riskLevel": "medium"
}

Caching Strategy

To reduce API costs and improve response times:

private async generateWithCache(
  prompt: string,
  model: 'flash' | 'pro' = 'flash',
  cacheKey?: string
): Promise<string> {
  // Check cache
  if (cacheKey) {
    const cached = await redisClient.get(cacheKey);
    if (cached) {
      logger.info(`AI cache hit: ${cacheKey}`);
      return cached;
    }
  }

  // Generate
  const response = await this.models[model].generateContent(prompt);
  const text = response.response.text();

  // Cache for 1 hour
  if (cacheKey) {
    await redisClient.setex(cacheKey, 3600, text);
  }

  return text;
}

Cache Keys:

• Daily reports: ai:daily-report:{studentName}:{date}
• Quizzes: ai:quiz:{subject}:{topic}:{count}
• Learning paths: ai:path:{studentId}:{subject}

Rate Limiting

AI endpoints have stricter rate limits:

const aiLimiter = rateLimit({
  windowMs: 60 * 1000,  // 1 minute
  max: 10,              // 10 requests per minute
  message: 'AI rate limit exceeded. Please wait.',
});

app.use('/api/ai', authenticate, aiLimiter);

Error Handling

try {
  const result = await aiService.generateQuiz(data);
  return res.json({ success: true, data: result });
} catch (error) {
  if (error.message.includes('SAFETY')) {
    return res.status(400).json({
      success: false,
      error: 'Content could not be generated due to safety guidelines'
    });
  }
  
  if (error.message.includes('QUOTA')) {
    return res.status(503).json({
      success: false,
      error: 'AI service temporarily unavailable'
    });
  }
  
  throw error;
}

Cost Optimization

Strategy	Implementation
Model selection	Flash for simple tasks, Pro for complex
Response caching	1-hour Redis cache
Prompt optimization	Concise, structured prompts
Rate limiting	Prevent abuse
Batch processing	Group similar requests