# Math & IT Adaptive Learning System -- Software Requirements Specification

> **SUPERSEDED** -- This document has been merged into `ENCOACH_UNIFIED_SRS.md` (v2.0). The adaptive learning engine for Math and IT is now part of the unified platform specification (Part II: Universal Subject Engine, sections 6-11). All features have been implemented and deployed.

**Document Version:** 1.0
**Date:** March 16, 2026
**Status:** ~~Draft -- Architect Review~~ **SUPERSEDED**
**Author:** EnCoach Engineering Team
**Audience:** Architect (initial review), then development team

---

## Table of Contents

1. [Introduction and Scope](#1-introduction-and-scope)
2. [System Overview](#2-system-overview)
3. [Subject Taxonomy and Knowledge Graph](#3-subject-taxonomy-and-knowledge-graph)
4. [Diagnostic Assessment Engine](#4-diagnostic-assessment-engine)
5. [Proficiency Profile](#5-proficiency-profile)
6. [Learning Plan Generation](#6-learning-plan-generation)
7. [Hybrid Content Delivery](#7-hybrid-content-delivery)
8. [Progress Tracking and Reassessment](#8-progress-tracking-and-reassessment)
9. [Data Models -- Odoo 19](#9-data-models----odoo-19)
10. [REST API Specification](#10-rest-api-specification)
11. [AI Integration Specification](#11-ai-integration-specification)
12. [Frontend Requirements](#12-frontend-requirements)
13. [Non-Functional Requirements](#13-non-functional-requirements)

---

## 1. Introduction and Scope

### 1.1 Purpose

This document specifies the requirements for adding **Mathematics** and **Information Technology** adaptive learning modules to the EnCoach platform. The system implements a competency-based adaptive learning loop: diagnostic assessment determines a student's current level, an AI-generated personalized learning plan guides them through content, and continuous reassessment adjusts the path based on progress.

### 1.2 Scope

**In scope:**
- Subject taxonomy and knowledge graph for Math and IT
- Adaptive diagnostic assessment engine (level detection per topic)
- Student proficiency profiling (per-topic mastery tracking)
- AI-powered personalized learning plan generation
- Hybrid content delivery (human-uploaded resources + AI-generated content)
- Progress tracking with mastery-based advancement
- AI coaching (hints, explanations, study suggestions)
- Math-specific features (formula rendering, numerical grading)
- IT-specific features (code highlighting, scenario-based questions)

**Out of scope:**
- English/IELTS module changes (stays as-is)
- Mobile native applications
- Live tutoring / video conferencing
- Payment or subscription changes
- OpenEduCat LMS integration (separate workstream)

### 1.3 Relationship to Existing System

The adaptive learning system is built **on top of** the existing EnCoach Odoo 19 backend. It reuses:

| Existing Component | Reuse |
|-------------------|-------|
| `encoach.exam` model | Extended with `subject_id` and `topic_ids` for subject-scoped exams. `is_diagnostic` flag already exists. |
| `encoach.stat` model | Score tracking per exercise. Extended with `topic_id` for per-topic analytics. |
| `encoach.session` model | Exam session state tracking, reused as-is. |
| `encoach_ai_generation` service | AI generation patterns reused; new prompt templates for Math/IT. |
| `encoach_ai_grading` service | Grading patterns reused; new rubrics for numerical and keyword grading. |
| `EncoachOpenAIService` | Direct reuse for GPT-4o calls with subject-specific prompts. |
| `EncoachMixin` (API controllers) | Authentication, response formatting, error handling reused as-is. |
| Training tips + FAISS | Architecture reused; new subject-specific knowledge bases. |

**New Odoo modules required:**

| Module | Purpose |
|--------|---------|
| `encoach_taxonomy` | Subject, Domain, Topic, Learning Objective models |
| `encoach_adaptive` | Proficiency profile, learning plan, diagnostic engine, progress tracking |
| `encoach_resources` | Human-uploaded learning resources tagged to topics |
| `encoach_adaptive_api` | REST API controllers for all adaptive learning endpoints |
| `encoach_adaptive_ai` | AI services for diagnostic generation, content generation, plan generation, coaching |

### 1.4 Definitions

| Term | Definition |
|------|-----------|
| **Subject** | Top-level academic discipline (Mathematics, Information Technology) |
| **Domain** | Major area within a subject (e.g., Algebra, Networking) |
| **Topic** | Specific teachable unit within a domain (e.g., Linear Equations, TCP/IP Model) |
| **Learning Objective** | Measurable skill/knowledge a student should gain from a topic (e.g., "Solve two-variable linear systems") |
| **Mastery Level** | Numeric score (0-100) indicating proficiency on a topic |
| **Mastery Threshold** | Minimum mastery level required to advance (default: 80%) |
| **Diagnostic Assessment** | Adaptive test that determines initial proficiency across all topics in a subject |
| **Learning Plan** | AI-generated, sequenced list of topics for a student to study, respecting prerequisites |
| **Resource** | Human-uploaded learning material (PDF, video, link, document) tagged to one or more topics |
| **Prerequisite** | A topic that must be mastered before another topic becomes available |

---

## 2. System Overview

### 2.1 The Adaptive Learning Loop

```mermaid
graph TB
    subgraph loop ["Adaptive Learning Loop"]
        A["1. Diagnostic Assessment<br/>Adaptive test determines<br/>per-topic proficiency"] --> B["2. Proficiency Profile<br/>Map of student knowledge<br/>gaps and strengths"]
        B --> C["3. Learning Plan<br/>AI generates personalized<br/>topic sequence"]
        C --> D["4. Content Delivery<br/>Human resources + AI content<br/>+ AI coaching"]
        D --> E["5. Progress Tracking<br/>Mastery quizzes, completion<br/>tracking, reassessment"]
        E -->|"Profile updated"| B
    end

    Entry["Student enrolls<br/>in Subject"] --> A
    E -->|"All topics mastered"| Complete["Subject Complete<br/>Certificate issued"]
```

### 2.2 Actors

| Actor | Role in Adaptive Learning |
|-------|--------------------------|
| **Student** | Takes diagnostic assessment, follows learning plan, consumes content, completes mastery quizzes, receives AI coaching |
| **Teacher / Academic Staff** | Defines subject taxonomy (topics, prerequisites), uploads learning resources (PDFs, videos, links), reviews AI-generated content quality, overrides learning plans |
| **Admin** | Manages subjects and domains, configures diagnostic assessment parameters, monitors system analytics, manages resource library |
| **AI Engine** | Generates diagnostic questions, creates learning plans, produces supplementary content, grades assessments, provides contextual coaching |

### 2.3 Architecture -- New Modules in Context

```mermaid
graph TB
    subgraph frontend ["React Frontend"]
        DiagUI["Diagnostic Test UI"]
        PlanUI["Learning Plan Dashboard"]
        ContentUI["Content Viewer<br/>PDF/Video/AI Content"]
        ProgressUI["Progress Tracker"]
        CoachUI["AI Coach Panel"]
        AdminTaxUI["Taxonomy Admin"]
        ResourceUI["Resource Manager"]
    end

    subgraph newModules ["New Odoo Modules"]
        TaxMod["encoach_taxonomy<br/>Subject, Domain, Topic,<br/>Learning Objective"]
        AdaptMod["encoach_adaptive<br/>Proficiency, Learning Plan,<br/>Diagnostic Config"]
        ResMod["encoach_resources<br/>Resource Library"]
        AdaptAPI["encoach_adaptive_api<br/>REST Controllers"]
        AdaptAI["encoach_adaptive_ai<br/>AI Services"]
    end

    subgraph existing ["Existing Odoo Modules"]
        ExamMod["encoach_exam<br/>Exam model"]
        StatMod["encoach_stats<br/>Session, Stat"]
        AICore["encoach_ai<br/>OpenAI Service"]
        AIGen["encoach_ai_generation<br/>Content Generation"]
        AIGrade["encoach_ai_grading<br/>Grading Service"]
        Core["encoach_core<br/>Users, Entities"]
    end

    subgraph data ["Data Layer"]
        PG["PostgreSQL 16"]
    end

    subgraph ai ["AI Services"]
        GPT["OpenAI GPT-4o"]
        FAISS_DB["FAISS Index<br/>per Subject"]
    end

    frontend -->|"REST API"| AdaptAPI
    AdaptAPI --> TaxMod
    AdaptAPI --> AdaptMod
    AdaptAPI --> ResMod
    AdaptAPI --> AdaptAI
    AdaptAI --> AICore
    AdaptAI --> GPT
    AdaptAI --> FAISS_DB
    AdaptMod --> ExamMod
    AdaptMod --> StatMod
    TaxMod --> PG
    AdaptMod --> PG
    ResMod --> PG
```

---

## 3. Subject Taxonomy and Knowledge Graph

### 3.1 Taxonomy Hierarchy

The taxonomy is a four-level hierarchy that structures all learning content:

```
Subject (e.g., Mathematics)
└── Domain (e.g., Algebra)
    └── Topic (e.g., Linear Equations)
        └── Learning Objective (e.g., "Solve 2-variable linear systems using substitution")
```

Topics form a **directed acyclic graph (DAG)** via prerequisite relationships. A topic may have zero or more prerequisites, and a student cannot begin a topic until all prerequisites are at Proficient level (mastery >= 60%).

### 3.2 Example Taxonomy -- Mathematics

```
Mathematics
├── Arithmetic
│   ├── Number Operations (prerequisites: none)
│   │   ├── LO: Perform addition, subtraction, multiplication, division on integers
│   │   └── LO: Apply order of operations (PEMDAS/BODMAS)
│   ├── Fractions and Decimals (prerequisites: Number Operations)
│   │   ├── LO: Convert between fractions, decimals, and percentages
│   │   └── LO: Perform arithmetic with fractions
│   └── Ratios and Proportions (prerequisites: Fractions and Decimals)
│       └── LO: Solve proportion problems
│
├── Algebra
│   ├── Algebraic Expressions (prerequisites: Arithmetic/Number Operations)
│   │   ├── LO: Simplify algebraic expressions
│   │   └── LO: Evaluate expressions for given variable values
│   ├── Linear Equations (prerequisites: Algebraic Expressions)
│   │   ├── LO: Solve single-variable linear equations
│   │   └── LO: Solve two-variable systems using substitution and elimination
│   ├── Quadratic Equations (prerequisites: Linear Equations)
│   │   ├── LO: Solve quadratics by factoring
│   │   └── LO: Apply the quadratic formula
│   └── Polynomials (prerequisites: Quadratic Equations)
│       └── LO: Factor and divide polynomials
│
├── Geometry
│   ├── Basic Shapes (prerequisites: Number Operations)
│   │   └── LO: Calculate area and perimeter of common shapes
│   ├── Angles and Triangles (prerequisites: Basic Shapes)
│   │   └── LO: Apply angle sum property, classify triangles
│   ├── Coordinate Geometry (prerequisites: Linear Equations, Basic Shapes)
│   │   └── LO: Plot points, calculate distance and midpoint
│   └── Trigonometry (prerequisites: Angles and Triangles, Coordinate Geometry)
│       └── LO: Apply sin, cos, tan to right-angled triangles
│
├── Statistics and Probability
│   ├── Data Representation (prerequisites: Number Operations)
│   │   └── LO: Create and interpret bar charts, histograms, pie charts
│   ├── Measures of Central Tendency (prerequisites: Data Representation)
│   │   └── LO: Calculate mean, median, mode for data sets
│   └── Basic Probability (prerequisites: Fractions and Decimals)
│       └── LO: Calculate probability of simple and compound events
│
└── Calculus (advanced, optional)
    ├── Limits (prerequisites: Polynomials, Coordinate Geometry)
    ├── Derivatives (prerequisites: Limits)
    └── Integrals (prerequisites: Derivatives)
```

### 3.3 Example Taxonomy -- Information Technology

```
Information Technology
├── Computer Fundamentals
│   ├── Hardware Components (prerequisites: none)
│   │   └── LO: Identify and describe CPU, RAM, storage, I/O devices
│   ├── Operating Systems (prerequisites: Hardware Components)
│   │   └── LO: Explain OS functions, file systems, process management
│   └── Number Systems (prerequisites: none)
│       └── LO: Convert between binary, decimal, hexadecimal
│
├── Networking
│   ├── Network Basics (prerequisites: Computer Fundamentals/Hardware)
│   │   └── LO: Describe LAN, WAN, MAN topologies
│   ├── TCP/IP Model (prerequisites: Network Basics)
│   │   └── LO: Explain the 4 layers of TCP/IP with protocols
│   ├── IP Addressing (prerequisites: TCP/IP Model, Number Systems)
│   │   └── LO: Calculate subnets, identify public/private addresses
│   └── Network Security (prerequisites: IP Addressing)
│       └── LO: Describe firewalls, encryption, VPN concepts
│
├── Databases
│   ├── Database Concepts (prerequisites: Computer Fundamentals/OS)
│   │   └── LO: Explain RDBMS, tables, keys, relationships
│   ├── SQL Fundamentals (prerequisites: Database Concepts)
│   │   └── LO: Write SELECT, INSERT, UPDATE, DELETE queries
│   ├── Database Design (prerequisites: SQL Fundamentals)
│   │   └── LO: Apply normalization (1NF, 2NF, 3NF)
│   └── Advanced SQL (prerequisites: Database Design)
│       └── LO: Write JOINs, subqueries, aggregate functions
│
├── Programming
│   ├── Programming Logic (prerequisites: none)
│   │   └── LO: Design algorithms using flowcharts and pseudocode
│   ├── Python Basics (prerequisites: Programming Logic)
│   │   └── LO: Write programs using variables, loops, conditionals
│   ├── Data Structures (prerequisites: Python Basics)
│   │   └── LO: Implement lists, stacks, queues, dictionaries
│   └── Object-Oriented Programming (prerequisites: Data Structures)
│       └── LO: Apply classes, inheritance, polymorphism
│
└── Cybersecurity
    ├── Security Fundamentals (prerequisites: Network Security)
    │   └── LO: Identify common threats, vulnerabilities, attack vectors
    └── Cryptography Basics (prerequisites: Security Fundamentals, Number Systems)
        └── LO: Explain symmetric/asymmetric encryption, hashing
```

### 3.4 Prerequisite Graph Visualization

```mermaid
graph LR
    subgraph mathPrereqs ["Math Prerequisites (simplified)"]
        NumOps["Number Operations"] --> FracDec["Fractions & Decimals"]
        FracDec --> Ratios["Ratios & Proportions"]
        NumOps --> AlgExpr["Algebraic Expressions"]
        AlgExpr --> LinEq["Linear Equations"]
        LinEq --> QuadEq["Quadratic Equations"]
        QuadEq --> Poly["Polynomials"]
        NumOps --> BasicShapes["Basic Shapes"]
        BasicShapes --> Angles["Angles & Triangles"]
        LinEq --> CoordGeom["Coordinate Geometry"]
        BasicShapes --> CoordGeom
        Angles --> Trig["Trigonometry"]
        CoordGeom --> Trig
        Poly --> Limits["Limits"]
        CoordGeom --> Limits
        Limits --> Deriv["Derivatives"]
        Deriv --> Integ["Integrals"]
    end
```

### 3.5 Taxonomy Management

| Action | Actor | Method |
|--------|-------|--------|
| Create/edit subjects | Admin | Admin UI or API |
| Create/edit domains | Admin / Academic Staff | Admin UI or API |
| Create/edit topics | Academic Staff | Admin UI or API, including prerequisite mapping |
| Create/edit learning objectives | Academic Staff | Admin UI, attached to topics |
| Import taxonomy from CSV/JSON | Admin | Bulk import endpoint |
| AI-suggest sub-topics | Academic Staff | Given a domain, AI suggests topic breakdown; staff reviews and approves |

---

## 4. Diagnostic Assessment Engine

### 4.1 Purpose

When a student begins a new subject, a diagnostic assessment determines their current proficiency across all domains and topics. This is the input for learning plan generation.

### 4.2 Adaptive Assessment Algorithm

The diagnostic uses a simplified **Computer Adaptive Testing (CAT)** approach:

```mermaid
sequenceDiagram
    participant Student
    participant System as Diagnostic Engine
    participant AI as GPT-4o
    participant DB as Proficiency Store

    Student->>System: Start diagnostic for "Mathematics"
    System->>System: Load topic list for Mathematics (all domains)
    System->>System: Select first domain, set difficulty = MEDIUM

    loop For each domain (round-robin)
        System->>AI: Generate question for topic X at difficulty MEDIUM
        AI-->>System: Question + correct answer + rubric
        System->>Student: Present question
        Student->>System: Submit answer
        System->>System: Grade answer (auto or AI)

        alt Correct
            System->>System: Increase difficulty for this domain
            System->>System: Add points to related topics
        else Incorrect
            System->>System: Decrease difficulty for this domain
            System->>System: Mark gap in related topics
        end
    end

    System->>DB: Store per-topic mastery scores
    System->>Student: Show proficiency profile summary
```

### 4.3 Algorithm Parameters

| Parameter | Default | Configurable | Description |
|-----------|---------|-------------|-------------|
| `questions_per_domain` | 4 | Yes (admin) | Number of questions asked per domain |
| `total_question_cap` | 25 | Yes (admin) | Maximum total questions in diagnostic |
| `time_limit_minutes` | 45 | Yes (admin) | Time limit for full diagnostic |
| `starting_difficulty` | `medium` | Yes (admin) | Initial difficulty level |
| `difficulty_levels` | `[easy, medium, hard, advanced]` | No | Fixed scale |
| `mastery_per_correct` | +25 | Yes (admin) | Points added to topic mastery for correct answer |
| `mastery_per_incorrect` | -10 | Yes (admin) | Points subtracted for incorrect answer |
| `min_mastery` | 0 | No | Floor value |
| `max_mastery` | 100 | No | Ceiling value |

### 4.4 Question Types per Subject

**Mathematics:**

| Question Type | Format | Example | Grading Method |
|--------------|--------|---------|---------------|
| `multiple_choice` | 4 options, 1 correct | "What is the slope of y = 3x + 2?" (a) 2 (b) 3 (c) 5 (d) 1 | Exact match |
| `numerical` | Student enters a number | "Solve for x: 2x + 6 = 14" → 4 | Numerical tolerance (default: 0.01) |
| `short_answer` | Student types answer | "Factor x² - 9" → "(x+3)(x-3)" | AI-graded (GPT-4o evaluates equivalence) |
| `fill_blanks` | Complete the equation | "The area of a circle is π___²" → r | Exact match (case-insensitive) |
| `worked_problem` | Multi-step solution | "Find the roots of 2x² + 5x - 3 = 0. Show your work." | AI-graded (GPT-4o evaluates steps and final answer) |

**Information Technology:**

| Question Type | Format | Example | Grading Method |
|--------------|--------|---------|---------------|
| `multiple_choice` | 4 options, 1 correct | "Which layer of TCP/IP handles routing?" (a) Application (b) Transport (c) Internet (d) Link | Exact match |
| `true_false` | True or False | "A primary key can contain NULL values." → False | Exact match |
| `short_answer` | Student types answer | "What SQL command retrieves data from a table?" → SELECT | Keyword match (case-insensitive, AI-assisted) |
| `code_completion` | Complete code snippet | "Write a Python function that returns the sum of a list" | AI-graded (GPT-4o evaluates correctness and approach) |
| `scenario` | Read scenario, answer question | "Given this network diagram, identify the subnet..." | AI-graded |

### 4.5 Diagnostic Configuration Model

Each subject has a diagnostic configuration that defines the assessment behavior:

```python
# Diagnostic configuration per subject
{
    "subject_id": 1,                    # Mathematics
    "questions_per_domain": 4,
    "total_question_cap": 25,
    "time_limit_minutes": 45,
    "starting_difficulty": "medium",
    "question_type_weights": {
        "multiple_choice": 0.4,         # 40% of questions
        "numerical": 0.3,              # 30% (Math-specific)
        "short_answer": 0.2,           # 20%
        "fill_blanks": 0.1             # 10%
    },
    "mastery_scoring": {
        "correct_easy": 15,
        "correct_medium": 25,
        "correct_hard": 35,
        "correct_advanced": 45,
        "incorrect_penalty": -10
    }
}
```

### 4.6 Relationship to Existing Exam System

The diagnostic assessment reuses the existing `encoach.exam` model:

- `module` field: new values `math_diagnostic`, `it_diagnostic` added to `MODULE_SELECTION`
- `is_diagnostic` field: already exists, set to `True`
- `parts` field (JSON): stores the adaptive question set
- `encoach.stat`: records per-question scores, linked to `topic_id`
- `encoach.session`: wraps the full diagnostic session

The key difference from regular exams: diagnostic questions are generated **on-the-fly** during the assessment (adaptive), not pre-generated as a fixed exam. The `parts` JSON is built dynamically as the student progresses.

---

## 5. Proficiency Profile

### 5.1 Overview

Every student has a proficiency profile per subject -- a map of their mastery level for every topic in the subject's taxonomy. This profile is the core data structure that drives learning plan generation.

### 5.2 Mastery Levels

| Level | Score Range | Description | Visual |
|-------|-----------|-------------|--------|
| **Not Started** | 0-19% | Topic not yet assessed or extremely weak | Grey |
| **Beginner** | 20-39% | Basic awareness, significant gaps | Red |
| **Developing** | 40-59% | Partial understanding, needs practice | Orange |
| **Proficient** | 60-79% | Good understanding, minor gaps | Yellow |
| **Mastered** | 80-100% | Strong command, ready to advance | Green |

### 5.3 Profile Updates

The proficiency profile updates in these scenarios:

| Trigger | Update Logic |
|---------|-------------|
| **Diagnostic assessment** | Initial scores set per topic based on diagnostic performance |
| **Practice exercises** | Mastery adjusts based on exercise results: +5 per correct, -2 per incorrect (smaller deltas than diagnostic) |
| **Mastery quiz** | Major update: if quiz score >= mastery threshold, topic moves to Mastered. If below, mastery recalculated as weighted average of current mastery and quiz score. |
| **Time decay** | If a student hasn't engaged with a topic for N days (configurable, default: 30), mastery decays by 5% per week of inactivity, down to a floor of the last quiz score minus 20%. Triggers review recommendation. |

### 5.4 Profile Data Structure

```python
# Per-student proficiency profile (stored per subject)
{
    "student_id": 42,
    "subject_id": 1,           # Mathematics
    "overall_mastery": 54.2,   # Weighted average across all topics
    "last_diagnostic": "2026-04-15T10:30:00Z",
    "topics": [
        {
            "topic_id": 101,
            "topic_name": "Number Operations",
            "domain": "Arithmetic",
            "mastery": 92,
            "level": "mastered",
            "last_assessed": "2026-04-15T10:30:00Z",
            "assessment_count": 3,
            "time_spent_minutes": 45,
            "decay_due": "2026-05-15T10:30:00Z"
        },
        {
            "topic_id": 105,
            "topic_name": "Linear Equations",
            "domain": "Algebra",
            "mastery": 35,
            "level": "beginner",
            "last_assessed": "2026-04-15T10:35:00Z",
            "assessment_count": 1,
            "time_spent_minutes": 0,
            "prerequisites_met": true
        },
        {
            "topic_id": 106,
            "topic_name": "Quadratic Equations",
            "domain": "Algebra",
            "mastery": 0,
            "level": "not_started",
            "last_assessed": null,
            "assessment_count": 0,
            "time_spent_minutes": 0,
            "prerequisites_met": false,
            "blocked_by": ["Linear Equations"]
        }
    ]
}
```

---

## 6. Learning Plan Generation

### 6.1 Overview

After the diagnostic assessment produces a proficiency profile, the AI generates a personalized learning plan. The plan is an ordered sequence of topics the student should study, respecting prerequisites and prioritizing the weakest areas.

### 6.2 Plan Generation Algorithm

```mermaid
graph TB
    Input["Inputs:<br/>1. Proficiency Profile<br/>2. Prerequisite Graph<br/>3. Time Constraints"] --> Sort["Topological Sort<br/>Respect prerequisites"]
    Sort --> Filter["Filter Out<br/>Already Mastered topics<br/>(mastery >= 80%)"]
    Filter --> Prioritize["Prioritize by:<br/>1. Prerequisite readiness<br/>2. Lowest mastery first<br/>3. Domain balance"]
    Prioritize --> Estimate["Estimate Duration<br/>per topic based on:<br/>- Current mastery<br/>- Topic complexity<br/>- Historical data"]
    Estimate --> AI["GPT-4o Refinement<br/>Natural language plan<br/>with study advice"]
    AI --> Plan["Learning Plan<br/>Ordered topic list<br/>with milestones"]
```

### 6.3 Plan Generation Logic

**Step 1: Topological Sort**
- Order all topics respecting prerequisite dependencies
- Topics with no unmet prerequisites come first

**Step 2: Filter Mastered Topics**
- Exclude topics where mastery >= 80% (already mastered)
- Exclude topics where all learning objectives are met

**Step 3: Prioritize**
- Among available topics (prerequisites met, not mastered):
  1. Lower mastery = higher priority
  2. Balance across domains (don't cluster all Algebra before any Geometry)
  3. Prerequisite chains: if mastering topic A unlocks 3 more topics, prioritize A

**Step 4: Estimate Duration**
- Base estimate from topic's `estimated_hours` (set by academic staff)
- Adjusted by current mastery: if mastery is 60%, student needs ~40% of full topic time
- If mastery is 0%, student needs 100% of estimated time
- Historical data: if similar students averaged 2.5 hours, use that

**Step 5: AI Refinement**
- GPT-4o receives the ordered topic list with mastery scores
- Generates a natural-language study plan with:
  - Motivational framing ("You're already strong in Arithmetic, let's build on that...")
  - Specific advice per topic ("Focus on the substitution method for Linear Equations")
  - Milestone suggestions ("Complete Algebra foundations by Week 2")

### 6.4 Plan Structure

```python
# Learning Plan
{
    "plan_id": 1,
    "student_id": 42,
    "subject_id": 1,
    "status": "active",                 # active, completed, paused
    "created_at": "2026-04-15T11:00:00Z",
    "target_completion": "2026-06-15T00:00:00Z",
    "ai_summary": "Based on your diagnostic, you have a solid foundation in Arithmetic...",
    "overall_progress": 23.5,           # percentage
    "items": [
        {
            "sequence": 1,
            "topic_id": 103,
            "topic_name": "Fractions and Decimals",
            "domain": "Arithmetic",
            "status": "completed",       # locked, available, in_progress, completed
            "current_mastery": 85,
            "target_mastery": 80,
            "estimated_hours": 1.5,
            "actual_hours": 1.2,
            "started_at": "2026-04-16T09:00:00Z",
            "completed_at": "2026-04-16T10:12:00Z"
        },
        {
            "sequence": 2,
            "topic_id": 105,
            "topic_name": "Linear Equations",
            "domain": "Algebra",
            "status": "in_progress",
            "current_mastery": 45,
            "target_mastery": 80,
            "estimated_hours": 3.0,
            "actual_hours": 1.1,
            "started_at": "2026-04-17T14:00:00Z",
            "completed_at": null
        },
        {
            "sequence": 3,
            "topic_id": 106,
            "topic_name": "Quadratic Equations",
            "domain": "Algebra",
            "status": "locked",
            "current_mastery": 0,
            "target_mastery": 80,
            "estimated_hours": 4.0,
            "blocked_by": ["Linear Equations"]
        }
    ]
}
```

### 6.5 Plan Adjustments

| Trigger | Adjustment |
|---------|-----------|
| Student masters a topic faster than estimated | Next topic unlocks early; remaining estimates tightened |
| Student struggles with a topic (3+ failed mastery quizzes) | Additional resources surfaced; estimated time increased; AI coaching intensified |
| Student skips ahead (teacher override) | Prerequisites bypassed; warning logged |
| New topics added to taxonomy | Plan regenerated to include new topics if prerequisites are met |
| Student hasn't engaged for 7+ days | Notification sent; if 14+ days, plan paused and review recommended |

### 6.6 Teacher Override

Teachers can:
- Reorder topics in a student's plan
- Add or remove specific topics
- Override prerequisite locks ("allow student to skip to Quadratic Equations")
- Set custom target dates
- Force a plan regeneration

All overrides are logged with the teacher's user ID and timestamp.

---

## 7. Hybrid Content Delivery

### 7.1 Content Resolution Order

When a student reaches a topic in their learning plan, the system serves content in this priority order:

```mermaid
graph TB
    TopicStart["Student opens Topic"] --> CheckRes["Check: Human-uploaded<br/>resources exist?"]
    CheckRes -->|"Yes"| ServeHuman["Serve human resources<br/>(PDFs, videos, links)"]
    CheckRes -->|"No"| CheckAI["Check: AI can generate<br/>for this topic?"]
    CheckAI -->|"Yes"| GenAI["AI generates:<br/>- Explanation<br/>- Worked examples<br/>- Summary"]
    CheckAI -->|"No"| FlagGap["Flag content gap<br/>Notify academic staff"]
    ServeHuman --> SupplementAI["AI supplements with:<br/>- Practice questions<br/>- Quick summary<br/>- Key takeaways"]
    GenAI --> Practice["AI generates<br/>practice exercises"]
    SupplementAI --> Practice
    Practice --> MasteryQuiz["Mastery Quiz<br/>(AI-generated, 5-10 questions)"]
```

### 7.2 Human-Uploaded Resources

| Attribute | Detail |
|-----------|--------|
| **Types** | PDF, video (URL or upload), external link, document (DOCX, PPTX), interactive (embedded HTML) |
| **Tagging** | Each resource is tagged to one or more topics and optionally to specific learning objectives |
| **Metadata** | Title, description, author, upload date, estimated reading/viewing time, difficulty level |
| **Ordering** | Academic staff sets display order within a topic (sequence field) |
| **Versioning** | Resources can be updated; previous versions retained |
| **Review** | Optional review workflow before resources are visible to students |

### 7.3 AI-Generated Content

When no human resources exist or as supplementary material, the AI generates:

| Content Type | Generation Method | When Used |
|-------------|------------------|-----------|
| **Topic Explanation** | GPT-4o generates a comprehensive explanation of the topic, tailored to the student's proficiency level | When student first opens a topic |
| **Worked Examples** | GPT-4o generates 2-3 step-by-step worked examples relevant to the topic | After explanation, before practice |
| **Key Takeaways** | GPT-4o summarizes the most important points in 3-5 bullet points | After content consumption |
| **Practice Questions** | GPT-4o generates 5-10 questions at appropriate difficulty | After content, before mastery quiz |
| **Hint / Explanation** | GPT-4o explains why an answer is correct/incorrect | After each practice question |

AI-generated content is **cached** on the first generation and served from cache on subsequent requests. Academic staff can review, edit, or replace cached AI content.

### 7.4 AI Coaching

The AI coach is an always-available assistant that provides contextual support:

| Coaching Action | Trigger | AI Behavior |
|----------------|---------|-------------|
| **Answer explanation** | Student answers a practice question | Explains why the answer is correct or incorrect, references the relevant concept |
| **Hint** | Student requests a hint during practice | Provides a partial clue without giving the full answer |
| **Study suggestion** | Student completes a topic section | Suggests what to focus on next based on performance |
| **Motivational nudge** | Student has been inactive for 3+ days | Personalized message encouraging return to study |
| **Weakness analysis** | Student fails a mastery quiz | Identifies specific concepts within the topic that need more practice |
| **Formula reference** | Student is working on a Math problem (on demand) | Displays relevant formulas for the current topic |

### 7.5 Content Gap Detection

The system automatically identifies topics with insufficient learning materials:

| Condition | Action |
|-----------|--------|
| Topic has 0 human resources and no AI content cached | Flag as "Content Gap -- Critical" and notify admin |
| Topic has human resources but they are >12 months old | Flag as "Review Needed" and notify academic staff |
| AI-generated content for a topic has been rated poorly by students (avg < 3/5) | Flag for human review/replacement |
| A domain has <50% resource coverage across its topics | Flag as "Domain Gap" on admin dashboard |

---

## 8. Progress Tracking and Reassessment

### 8.1 What Is Tracked

| Metric | Granularity | Storage |
|--------|------------|---------|
| **Resource completion** | Per resource per student | Binary (viewed/not viewed) + timestamp + time spent |
| **Practice exercise results** | Per question per student | Score, answer given, correct answer, time taken |
| **Mastery quiz results** | Per topic per student | Score, pass/fail, attempt number |
| **Topic time spent** | Per topic per student | Cumulative minutes |
| **Learning plan progress** | Per plan per student | % of topics completed, % of total estimated hours completed |
| **Login frequency** | Per student | Days active, streak count |

### 8.2 Mastery Quiz

After a student consumes content for a topic, they take a **mastery quiz** to prove proficiency:

| Parameter | Value |
|-----------|-------|
| **Questions** | 5-10 (configurable per subject) |
| **Question types** | Mix of types appropriate for the subject (see Section 4.4) |
| **Time limit** | 15 minutes (configurable) |
| **Pass threshold** | 80% (configurable -- "mastery threshold") |
| **Attempts** | Unlimited, but each attempt generates new questions |
| **Cooldown** | 1 hour between attempts (configurable) |
| **On pass** | Topic status → "completed", mastery updated, next topic unlocked |
| **On fail** | Mastery recalculated, AI coaching suggests what to review, additional resources recommended |

### 8.3 Spaced Repetition

To ensure long-term retention, mastered topics resurface for review:

| Days Since Mastery | Review Action |
|-------------------|---------------|
| 7 days | Light review: 3 quick-recall questions |
| 30 days | Medium review: 5 questions at original difficulty |
| 90 days | Full review: equivalent to mastery quiz |

If a student fails a spaced repetition review, the topic mastery is reduced and it re-enters the active learning plan.

### 8.4 Analytics Dashboard

The following analytics are available to different roles:

**Student Dashboard:**
- Overall subject mastery (percentage, visual progress bar)
- Per-domain mastery breakdown (radar chart)
- Learning plan progress (completed / in progress / locked)
- Study streak and time invested
- Upcoming reviews (spaced repetition schedule)

**Teacher Dashboard:**
- Class-level mastery distribution per topic (heatmap)
- Students at risk (low mastery, low engagement)
- Content gap report
- Average time per topic vs. estimate

**Admin Dashboard:**
- Subject-level statistics (enrollments, completion rates, average mastery)
- AI content generation usage and quality metrics
- Resource utilization (most/least used resources)
- System-wide performance trends

---

## 9. Data Models -- Odoo 19

### 9.1 New Module: `encoach_taxonomy`

#### `encoach.subject`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `Char`, required | Subject name (e.g., "Mathematics", "Information Technology") |
| `code` | `Char`, required, unique | Short code (e.g., "MATH", "IT") |
| `description` | `Text` | Subject description |
| `is_active` | `Boolean`, default True | Whether subject is available to students |
| `icon` | `Char` | Icon identifier for frontend display |
| `domain_ids` | `One2many` → `encoach.domain` | Domains in this subject |
| `diagnostic_config` | `Json` | Diagnostic assessment configuration (see Section 4.5) |
| `mastery_threshold` | `Integer`, default 80 | Minimum mastery % to mark a topic as completed |
| `grading_scale` | `Selection`: `percentage`, `letter`, `custom` | How grades are displayed |
| `grading_scale_config` | `Json` | Custom grade boundaries (e.g., `{"A": 90, "B": 80, ...}`) |

#### `encoach.domain`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `Char`, required | Domain name (e.g., "Algebra", "Networking") |
| `code` | `Char`, required | Short code |
| `subject_id` | `Many2one` → `encoach.subject`, required, ondelete=cascade | Parent subject |
| `sequence` | `Integer`, default 10 | Display order within subject |
| `description` | `Text` | Domain description |
| `topic_ids` | `One2many` → `encoach.topic` | Topics in this domain |

#### `encoach.topic`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `Char`, required | Topic name (e.g., "Linear Equations") |
| `code` | `Char`, required | Short code |
| `domain_id` | `Many2one` → `encoach.domain`, required, ondelete=cascade | Parent domain |
| `sequence` | `Integer`, default 10 | Display order within domain |
| `description` | `Text` | Topic description |
| `estimated_hours` | `Float`, default 2.0 | Estimated study time in hours |
| `difficulty_level` | `Selection`: `beginner`, `intermediate`, `advanced` | Topic complexity |
| `prerequisite_ids` | `Many2many` → `encoach.topic` (self-referential, rel table `encoach_topic_prerequisite_rel`) | Topics that must be mastered before this one |
| `objective_ids` | `One2many` → `encoach.learning.objective` | Learning objectives |
| `resource_ids` | `Many2many` → `encoach.resource` | Tagged resources |
| `question_type_weights` | `Json` | Override default question type distribution for this topic |

#### `encoach.learning.objective`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `Char`, required | Objective description (e.g., "Solve 2-variable linear systems") |
| `topic_id` | `Many2one` → `encoach.topic`, required, ondelete=cascade | Parent topic |
| `bloom_level` | `Selection`: `remember`, `understand`, `apply`, `analyze`, `evaluate`, `create` | Bloom's taxonomy level |
| `sequence` | `Integer`, default 10 | Order within topic |

### 9.2 New Module: `encoach_resources`

#### `encoach.resource`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `Char`, required | Resource title |
| `description` | `Text` | Resource description |
| `resource_type` | `Selection`: `pdf`, `video`, `link`, `document`, `interactive` | Content type |
| `file` | `Binary`, attachment=True | Uploaded file (for pdf, document) |
| `file_name` | `Char` | Original file name |
| `url` | `Char` | External URL (for video, link) |
| `topic_ids` | `Many2many` → `encoach.topic` (rel table `encoach_resource_topic_rel`) | Tagged topics |
| `objective_ids` | `Many2many` → `encoach.learning.objective` | Tagged objectives (optional, finer granularity) |
| `author_id` | `Many2one` → `res.users` | Who uploaded |
| `estimated_minutes` | `Integer` | Estimated consumption time |
| `difficulty_level` | `Selection`: `beginner`, `intermediate`, `advanced` | Resource difficulty |
| `sequence` | `Integer`, default 10 | Display order within topic |
| `is_published` | `Boolean`, default True | Visibility to students |
| `review_status` | `Selection`: `draft`, `reviewed`, `approved` | Review workflow status |

### 9.3 New Module: `encoach_adaptive`

#### `encoach.proficiency`

| Field | Type | Description |
|-------|------|-------------|
| `student_id` | `Many2one` → `res.users`, required, ondelete=cascade, index=True | Student |
| `topic_id` | `Many2one` → `encoach.topic`, required, ondelete=cascade, index=True | Topic |
| `subject_id` | `Many2one` → `encoach.subject`, related='topic_id.domain_id.subject_id', store=True | Denormalized for filtering |
| `mastery` | `Float`, default 0 | Current mastery score (0-100) |
| `mastery_level` | `Selection`: `not_started`, `beginner`, `developing`, `proficient`, `mastered` | Computed from mastery score |
| `last_assessed` | `Datetime` | Last assessment date |
| `assessment_count` | `Integer`, default 0 | Number of assessments taken |
| `time_spent_minutes` | `Integer`, default 0 | Cumulative study time |
| `decay_due` | `Datetime` | When mastery decay is next applied |
| `last_quiz_score` | `Float` | Most recent mastery quiz score |

**SQL constraint:** unique on `(student_id, topic_id)`

**Computed field logic for `mastery_level`:**
```python
if mastery >= 80: return 'mastered'
elif mastery >= 60: return 'proficient'
elif mastery >= 40: return 'developing'
elif mastery >= 20: return 'beginner'
else: return 'not_started'
```

#### `encoach.learning.plan`

| Field | Type | Description |
|-------|------|-------------|
| `student_id` | `Many2one` → `res.users`, required, ondelete=cascade, index=True | Student |
| `subject_id` | `Many2one` → `encoach.subject`, required, ondelete=cascade | Subject |
| `status` | `Selection`: `active`, `completed`, `paused`, `regenerating` | Plan status |
| `created_at` | `Datetime`, default now | Creation timestamp |
| `target_completion` | `Date` | Target completion date |
| `ai_summary` | `Text` | GPT-generated study plan summary |
| `overall_progress` | `Float`, default 0 | Percentage complete (computed) |
| `item_ids` | `One2many` → `encoach.learning.plan.item` | Ordered plan items |
| `override_by` | `Many2one` → `res.users` | If manually overridden, who did it |
| `override_at` | `Datetime` | Override timestamp |

#### `encoach.learning.plan.item`

| Field | Type | Description |
|-------|------|-------------|
| `plan_id` | `Many2one` → `encoach.learning.plan`, required, ondelete=cascade | Parent plan |
| `topic_id` | `Many2one` → `encoach.topic`, required | Topic to study |
| `sequence` | `Integer`, required | Order in the plan |
| `status` | `Selection`: `locked`, `available`, `in_progress`, `completed`, `skipped` | Item status |
| `target_mastery` | `Float`, default 80 | Mastery goal for this item |
| `current_mastery` | `Float`, related to proficiency record | Current mastery (denormalized) |
| `estimated_hours` | `Float` | AI-estimated study hours |
| `actual_hours` | `Float`, default 0 | Actual time spent |
| `started_at` | `Datetime` | When student started |
| `completed_at` | `Datetime` | When student completed |
| `quiz_attempts` | `Integer`, default 0 | Number of mastery quiz attempts |

#### `encoach.resource.completion`

| Field | Type | Description |
|-------|------|-------------|
| `student_id` | `Many2one` → `res.users`, required, ondelete=cascade | Student |
| `resource_id` | `Many2one` → `encoach.resource`, required, ondelete=cascade | Resource |
| `viewed` | `Boolean`, default False | Has student viewed/opened the resource |
| `viewed_at` | `Datetime` | When first viewed |
| `time_spent_minutes` | `Integer`, default 0 | Time spent on resource |
| `rating` | `Integer` | Student's rating (1-5 stars) |
| `feedback` | `Text` | Optional student feedback |

#### `encoach.ai.content.cache`

| Field | Type | Description |
|-------|------|-------------|
| `topic_id` | `Many2one` → `encoach.topic`, required, ondelete=cascade | Topic |
| `content_type` | `Selection`: `explanation`, `worked_example`, `key_takeaways`, `summary` | Type of AI content |
| `difficulty_level` | `Selection`: `beginner`, `intermediate`, `advanced` | Target difficulty |
| `content` | `Text` | Generated content (Markdown) |
| `content_html` | `Html` | Rendered HTML version |
| `generated_at` | `Datetime`, default now | Generation timestamp |
| `model_used` | `Char` | GPT model used (e.g., "gpt-4o") |
| `quality_rating` | `Float` | Average student rating |
| `review_status` | `Selection`: `auto`, `reviewed`, `approved`, `rejected` | Staff review status |
| `reviewed_by` | `Many2one` → `res.users` | Who reviewed |

### 9.4 Extensions to Existing Models

#### `encoach.exam` -- add fields

| Field | Type | Description |
|-------|------|-------------|
| `subject_id` | `Many2one` → `encoach.subject` | Subject this exam belongs to (null for legacy English exams) |
| `topic_ids` | `Many2many` → `encoach.topic` | Topics covered by this exam |

#### `encoach.stat` -- add fields

| Field | Type | Description |
|-------|------|-------------|
| `topic_id` | `Many2one` → `encoach.topic` | Topic this stat relates to |
| `subject_id` | `Many2one` → `encoach.subject` | Subject (denormalized) |

#### `MODULE_SELECTION` -- add values

Add to the existing selection: `math`, `it`, `math_diagnostic`, `it_diagnostic`, `math_mastery`, `it_mastery`

---

## 10. REST API Specification

All endpoints follow existing patterns: `@http.route`, `auth='public'`, JWT via `_authenticate()`, responses via `_json_response()` / `_error_response()`. JSON body uses camelCase keys.

### 10.1 Taxonomy Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/subjects` | List all active subjects | JWT |
| `GET` | `/api/subjects/<int:id>` | Get subject with domains and topics | JWT |
| `POST` | `/api/subjects` | Create subject | JWT (admin) |
| `PATCH` | `/api/subjects/<int:id>` | Update subject | JWT (admin) |
| `DELETE` | `/api/subjects/<int:id>` | Delete subject | JWT (admin) |
| `GET` | `/api/subjects/<int:id>/taxonomy` | Get full taxonomy tree (domains > topics > objectives) | JWT |
| `POST` | `/api/subjects/<int:id>/taxonomy/import` | Bulk import taxonomy from JSON/CSV | JWT (admin) |

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/domains` | List domains (filterable by `subjectId`) | JWT |
| `POST` | `/api/domains` | Create domain | JWT (admin/staff) |
| `PATCH` | `/api/domains/<int:id>` | Update domain | JWT (admin/staff) |
| `DELETE` | `/api/domains/<int:id>` | Delete domain | JWT (admin/staff) |

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/topics` | List topics (filterable by `domainId`, `subjectId`) | JWT |
| `GET` | `/api/topics/<int:id>` | Get topic with objectives and resources | JWT |
| `POST` | `/api/topics` | Create topic | JWT (admin/staff) |
| `PATCH` | `/api/topics/<int:id>` | Update topic (including prerequisites) | JWT (admin/staff) |
| `DELETE` | `/api/topics/<int:id>` | Delete topic | JWT (admin/staff) |

### 10.2 Resource Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/resources` | List resources (filterable by `topicId`, `type`, `published`) | JWT |
| `GET` | `/api/resources/<int:id>` | Get resource detail | JWT |
| `POST` | `/api/resources` | Upload resource (multipart for files) | JWT (staff) |
| `PATCH` | `/api/resources/<int:id>` | Update resource metadata | JWT (staff) |
| `DELETE` | `/api/resources/<int:id>` | Delete resource | JWT (staff) |
| `GET` | `/api/resources/<int:id>/download` | Download resource file | JWT |
| `POST` | `/api/resources/<int:id>/complete` | Mark resource as viewed/completed by current student | JWT |
| `POST` | `/api/resources/<int:id>/rate` | Rate resource (1-5 stars) | JWT |

### 10.3 Diagnostic Assessment Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `POST` | `/api/diagnostic/start` | Start diagnostic for a subject. Body: `{ "subjectId": 1 }`. Returns first question batch. | JWT |
| `POST` | `/api/diagnostic/answer` | Submit answer, get next question. Body: `{ "diagnosticSessionId": "...", "questionId": "...", "answer": "..." }`. Returns: grading result + next question (or completion). | JWT |
| `GET` | `/api/diagnostic/<int:session_id>/result` | Get diagnostic result (proficiency profile). | JWT |
| `POST` | `/api/diagnostic/retake` | Retake diagnostic for a subject. Body: `{ "subjectId": 1 }`. | JWT |

### 10.4 Proficiency Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/proficiency` | Get current student's proficiency profile. Query: `?subjectId=1`. | JWT |
| `GET` | `/api/proficiency/summary` | Get mastery summary across all subjects. | JWT |
| `GET` | `/api/proficiency/class` | Get class-level proficiency (teacher/admin). Query: `?subjectId=1&classroomId=5`. | JWT (teacher/admin) |

### 10.5 Learning Plan Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/learning-plan` | Get current student's active plan. Query: `?subjectId=1`. | JWT |
| `POST` | `/api/learning-plan/generate` | Generate or regenerate plan. Body: `{ "subjectId": 1, "targetDate": "2026-06-15" }`. | JWT |
| `PATCH` | `/api/learning-plan/<int:id>` | Update plan (teacher override). Body: `{ "items": [...] }`. | JWT (teacher) |
| `POST` | `/api/learning-plan/<int:id>/pause` | Pause plan. | JWT |
| `POST` | `/api/learning-plan/<int:id>/resume` | Resume plan. | JWT |
| `GET` | `/api/learning-plan/<int:id>/progress` | Get detailed plan progress. | JWT |

### 10.6 Content and Coaching Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/topics/<int:id>/content` | Get learning content for a topic (human resources + AI-generated, resolved by priority). | JWT |
| `POST` | `/api/topics/<int:id>/generate-content` | Force AI content generation for a topic. Body: `{ "type": "explanation", "difficultyLevel": "intermediate" }`. | JWT (staff) |
| `POST` | `/api/topics/<int:id>/practice` | Generate practice questions. Body: `{ "count": 5, "questionTypes": ["multiple_choice", "numerical"] }`. Returns questions with IDs. | JWT |
| `POST` | `/api/topics/<int:id>/practice/grade` | Submit practice answers for grading. Body: `{ "answers": [{"questionId": "...", "answer": "..."}] }`. Returns grading results with explanations. | JWT |
| `POST` | `/api/topics/<int:id>/mastery-quiz` | Start mastery quiz. Returns question set. | JWT |
| `POST` | `/api/topics/<int:id>/mastery-quiz/submit` | Submit mastery quiz. Body: `{ "answers": [...] }`. Returns score, pass/fail, updated mastery. | JWT |
| `POST` | `/api/coach/hint` | Request a hint. Body: `{ "questionId": "...", "topicId": 105, "currentAnswer": "..." }`. Returns hint text. | JWT |
| `POST` | `/api/coach/explain` | Request explanation. Body: `{ "questionId": "...", "topicId": 105, "studentAnswer": "...", "correctAnswer": "..." }`. Returns detailed explanation. | JWT |
| `POST` | `/api/coach/suggest` | Get study suggestions. Body: `{ "subjectId": 1 }`. Returns personalized study advice. | JWT |

### 10.7 Analytics Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/api/analytics/student` | Student's own analytics. Query: `?subjectId=1`. | JWT |
| `GET` | `/api/analytics/class` | Class-level analytics (teacher/admin). Query: `?subjectId=1&classroomId=5`. | JWT (teacher/admin) |
| `GET` | `/api/analytics/subject` | Subject-level analytics (admin). Query: `?subjectId=1`. | JWT (admin) |
| `GET` | `/api/analytics/content-gaps` | Content gap report (admin/staff). Query: `?subjectId=1`. | JWT (admin/staff) |

---

## 11. AI Integration Specification

### 11.1 New Odoo Module: `encoach_adaptive_ai`

This module provides AI services for the adaptive learning system. It follows the same patterns as `encoach_ai_generation` and `encoach_ai_grading`: a service class that calls `EncoachOpenAIService` with subject-specific prompts.

### 11.2 GPT-4o Prompt Templates

#### 11.2.1 Diagnostic Question Generation

**Math Example:**

```
System: You are a mathematics assessment expert. Generate an adaptive diagnostic question.

Given:
- Subject: Mathematics
- Domain: {domain_name}
- Topic: {topic_name}
- Difficulty: {difficulty_level} (easy/medium/hard/advanced)
- Question type: {question_type}
- Learning objectives: {objectives_list}

Generate a single question with:
1. "question": The question text (use LaTeX notation for formulas: $...$)
2. "options": Array of 4 options (for multiple_choice only)
3. "correct_answer": The correct answer
4. "explanation": Brief explanation of why the answer is correct
5. "grading_rubric": How to grade (for open-ended: key concepts to look for)
6. "difficulty_tag": The actual difficulty of the generated question

Respond in JSON format only.
```

**IT Example:**

```
System: You are an Information Technology assessment expert. Generate an adaptive diagnostic question.

Given:
- Subject: Information Technology
- Domain: {domain_name}
- Topic: {topic_name}
- Difficulty: {difficulty_level}
- Question type: {question_type}
- Learning objectives: {objectives_list}

Generate a single question with:
1. "question": The question text (use ```code blocks``` for code snippets)
2. "options": Array of 4 options (for multiple_choice/true_false)
3. "correct_answer": The correct answer
4. "explanation": Brief explanation
5. "grading_rubric": How to grade
6. "difficulty_tag": Actual difficulty

For code_completion type, include:
- "starter_code": Code with blanks/comments for student to complete
- "expected_output": What correct code should produce
- "evaluation_criteria": ["correctness", "approach", "efficiency"]

Respond in JSON format only.
```

#### 11.2.2 Learning Plan Generation

```
System: You are an adaptive learning plan advisor. Create a personalized study plan.

Given:
- Student proficiency profile:
  {proficiency_json}
- Subject taxonomy with prerequisites:
  {taxonomy_json}
- Target completion date: {target_date}
- Mastery threshold: {mastery_threshold}%

Generate a study plan with:
1. "summary": A 2-3 sentence motivational overview of the plan, acknowledging strengths and addressing weaknesses
2. "recommended_sequence": Ordered list of topic IDs to study, respecting prerequisites
3. "estimated_hours_per_topic": Object mapping topic_id to estimated study hours (adjusted by current mastery)
4. "milestones": Array of milestone objects with {"name", "topic_ids", "target_date", "description"}
5. "focus_areas": Top 3 domains/topics that need the most attention
6. "study_advice": Specific tips for the student based on their profile

Respond in JSON format only.
```

#### 11.2.3 Content Generation

```
System: You are an expert {subject_name} tutor. Generate learning content for the following topic.

Given:
- Subject: {subject_name}
- Topic: {topic_name}
- Learning objectives: {objectives_list}
- Student mastery level: {mastery_level} ({mastery_percentage}%)
- Content type: {content_type} (explanation/worked_example/key_takeaways)
- Available context: {resource_summaries} (summaries of human-uploaded resources, if any)

For "explanation":
Generate a clear, structured explanation of {topic_name} that:
- Starts from the student's current level ({mastery_level})
- Covers all learning objectives
- Uses concrete examples
- For Math: uses LaTeX notation ($...$) for formulas
- For IT: uses ```language``` code blocks for code examples
- Ends with a brief summary

For "worked_example":
Generate 2-3 step-by-step worked examples that:
- Progress from simple to complex
- Show every intermediate step
- Highlight common mistakes to avoid
- For Math: show formula transformations step by step
- For IT: show code evolution or decision reasoning

For "key_takeaways":
Generate 3-5 bullet points summarizing the most important concepts, formulas, or patterns from this topic.

Respond in Markdown format.
```

#### 11.2.4 AI Coaching -- Hint

```
System: You are a helpful {subject_name} tutor providing a hint to a student.

The student is working on this question:
{question_text}

Their current (incomplete or incorrect) answer: {student_answer}
The correct answer: {correct_answer}

Provide a hint that:
- Does NOT reveal the full answer
- Points the student toward the right approach
- References relevant concepts or formulas
- Is encouraging and supportive
- Is 1-3 sentences long

Respond with just the hint text.
```

#### 11.2.5 AI Coaching -- Explanation

```
System: You are a {subject_name} tutor explaining a question result.

Question: {question_text}
Student's answer: {student_answer}
Correct answer: {correct_answer}
Was correct: {is_correct}

Provide an explanation that:
- Acknowledges whether the student was correct or incorrect
- Explains WHY the correct answer is correct
- If the student was wrong, explains the specific misconception
- References the relevant concept/formula/principle
- Suggests what to review if the student was wrong
- For Math: shows the solution steps
- For IT: explains the underlying principle

Respond in Markdown format (2-4 paragraphs).
```

### 11.3 Grading Logic per Question Type

| Question Type | Grading Method | Implementation |
|--------------|---------------|----------------|
| `multiple_choice` | Exact match | Direct comparison: `student_answer == correct_answer` |
| `true_false` | Exact match | Direct comparison |
| `numerical` | Tolerance-based | `abs(student - correct) <= tolerance`. Default tolerance: 0.01. Configurable per topic. |
| `fill_blanks` | Normalized match | Strip whitespace, lowercase, compare. For Math: normalize LaTeX expressions. |
| `short_answer` | AI-graded | GPT-4o evaluates semantic equivalence. Prompt includes correct answer and acceptable variations. |
| `code_completion` | AI-graded | GPT-4o evaluates: (1) correctness of output, (2) approach validity, (3) code quality. Returns score 0-100 + feedback. |
| `worked_problem` | AI-graded | GPT-4o evaluates: (1) final answer correctness, (2) methodology, (3) step completeness. Returns score 0-100 + per-step feedback. |
| `scenario` | AI-graded | GPT-4o evaluates against rubric provided with the question. Returns score 0-100 + explanation. |

### 11.4 FAISS Extension

Create subject-specific FAISS indices for training tips:

| Index | Category | Content Source |
|-------|----------|---------------|
| `math_algebra_tips` | Algebra tips and common mistakes | Curated + AI-generated |
| `math_geometry_tips` | Geometry tips and formulas | Curated + AI-generated |
| `math_statistics_tips` | Statistics tips and methods | Curated + AI-generated |
| `it_networking_tips` | Networking concepts and troubleshooting | Curated + AI-generated |
| `it_database_tips` | SQL tips and database design patterns | Curated + AI-generated |
| `it_programming_tips` | Coding tips and best practices | Curated + AI-generated |

Each index uses `all-MiniLM-L6-v2` for embeddings (same as English), stored as `encoach.training.tip` records with a new `subject_id` field.

---

## 12. Frontend Requirements

### 12.1 New Pages

| Page | Route | Role | Description |
|------|-------|------|-------------|
| **Subject Selection** | `/student/subjects` | Student | List available subjects, show overall mastery per subject, "Start Learning" button |
| **Diagnostic Test** | `/student/diagnostic/:subjectId` | Student | Adaptive test UI: one question at a time, progress indicator, timer, auto-advance on answer |
| **Proficiency Profile** | `/student/proficiency/:subjectId` | Student | Visual mastery map: domain radar chart, per-topic mastery bars, strengths/weaknesses |
| **Learning Plan** | `/student/plan/:subjectId` | Student | Topic sequence with status indicators (locked/available/in-progress/completed), progress bar, timeline |
| **Topic Learning** | `/student/topic/:topicId` | Student | Content viewer: resources list, AI content, practice section, mastery quiz trigger |
| **Practice Session** | `/student/practice/:topicId` | Student | Question-by-question practice with instant feedback, hints, explanations |
| **Mastery Quiz** | `/student/mastery-quiz/:topicId` | Student | Timed quiz, similar to existing exam UI, results with pass/fail and mastery update |
| **AI Coach** | Component (sidebar/modal) | Student | Contextual AI assistant: hint requests, explanations, study suggestions |
| **Taxonomy Manager** | `/admin/taxonomy` | Admin/Staff | CRUD for subjects, domains, topics, objectives, prerequisite mapping |
| **Resource Manager** | `/admin/resources` | Admin/Staff | Upload, tag, manage resources; content gap dashboard |
| **Adaptive Analytics** | `/admin/adaptive-analytics` | Admin | Subject-level analytics, class performance, content gaps |
| **Student Plan View** | `/teacher/student-plan/:studentId/:subjectId` | Teacher | View and override a student's learning plan |

### 12.2 Math-Specific Components

| Component | Technology | Purpose |
|-----------|-----------|---------|
| `MathRenderer` | KaTeX (via `react-katex` or `remark-math` + `rehype-katex`) | Render LaTeX formulas in questions, explanations, and content. Inline: `$x^2$`, block: `$$\frac{a}{b}$$` |
| `MathInput` | `mathlive` or custom LaTeX input | Student enters mathematical expressions as answers. Visual equation editor with keyboard shortcuts. |
| `FormulaReference` | KaTeX | Sidebar panel showing relevant formulas for the current topic |
| `GraphPlot` | `recharts` or `plotly.js` | Display mathematical graphs (for coordinate geometry, functions) |

### 12.3 IT-Specific Components

| Component | Technology | Purpose |
|-----------|-----------|---------|
| `CodeBlock` | `prism-react-renderer` or `react-syntax-highlighter` | Render code snippets with syntax highlighting in questions and content |
| `CodeEditor` | `@monaco-editor/react` (lightweight) or `codemirror` | Student writes/edits code for code_completion questions |
| `TerminalOutput` | Custom styled `<pre>` | Display expected program output |
| `NetworkDiagram` | `react-flow` or Mermaid | Display network topology diagrams for networking questions |

### 12.4 Shared Components

| Component | Purpose |
|-----------|---------|
| `MasteryBar` | Horizontal bar showing mastery level with color coding (grey/red/orange/yellow/green) |
| `DomainRadar` | Radar chart showing mastery across all domains in a subject |
| `TopicCard` | Card showing topic name, mastery, status (locked/available/completed), prerequisite indicator |
| `PlanTimeline` | Vertical timeline of learning plan items with status icons |
| `QuizTimer` | Countdown timer for mastery quizzes (reuse from existing exam timer) |
| `ProgressRing` | Circular progress indicator for overall subject mastery |
| `ResourceCard` | Card for learning resources with type icon, title, estimated time, completion checkbox |
| `CoachBubble` | Chat-like bubble for AI coaching responses |

---

## 13. Non-Functional Requirements

### 13.1 Performance

| Metric | Target |
|--------|--------|
| Diagnostic question generation | < 3 seconds per question |
| Practice question generation (batch of 5) | < 5 seconds |
| AI grading (per answer) | < 5 seconds for auto-gradeable, < 10 seconds for AI-graded |
| Learning plan generation | < 10 seconds |
| AI content generation (explanation) | < 15 seconds |
| AI coaching response (hint/explanation) | < 5 seconds |
| Resource file upload | < 30 seconds for files up to 50 MB |
| Proficiency profile load | < 1 second |
| Taxonomy tree load | < 2 seconds |

### 13.2 Scalability

| Dimension | Target |
|-----------|--------|
| Concurrent students per subject | 200 |
| Total topics per subject | 500 |
| Total resources per subject | 1,000 |
| AI content cache entries | 10,000 |
| Proficiency records | 200 students x 500 topics = 100,000 records |

### 13.3 Data Integrity

- Proficiency scores are never overwritten -- all changes are additive (new assessment results update the score via weighted average, never direct replacement)
- Learning plan changes are logged (who changed, when, what was before/after)
- AI-generated content is cached and versioned; regeneration creates a new version, does not delete the old one
- Resource deletions are soft-deletes (is_active = False) to preserve student completion records

### 13.4 Security

- All endpoints require JWT authentication (via existing `_authenticate()`)
- Students can only access their own proficiency and learning plan data
- Teachers can view (but not modify without explicit override) student data in their classrooms
- Admin has full access
- Resource uploads are scanned for file type validation (no executable uploads)
- AI prompts never include student personal data (only anonymized performance metrics)

---

## Appendix A: Implementation Priority

| Priority | Component | Rationale |
|----------|-----------|-----------|
| **P0** | Subject taxonomy models + CRUD API | Foundation for everything else |
| **P0** | Resource model + upload API | Staff needs to start uploading content immediately |
| **P1** | Diagnostic assessment engine + UI | Entry point for students |
| **P1** | Proficiency profile model + API | Required by learning plan |
| **P1** | Learning plan generation + UI | Core student experience |
| **P2** | Content delivery (resource viewer + AI content) | Content consumption |
| **P2** | Practice questions + grading | Practice before mastery quiz |
| **P2** | Mastery quiz + progression | Advancement mechanism |
| **P3** | AI coaching (hints, explanations) | Enhancement to learning experience |
| **P3** | Spaced repetition | Long-term retention |
| **P3** | Analytics dashboards | Monitoring and optimization |
| **P4** | Content gap detection | Operational efficiency |
| **P4** | FAISS training tips per subject | Advanced personalization |

## Appendix B: Dependency Graph for Implementation

```mermaid
graph TB
    TaxModels["P0: Taxonomy Models<br/>(Subject, Domain, Topic, Objective)"] --> TaxAPI["P0: Taxonomy CRUD API"]
    TaxModels --> ResModels["P0: Resource Model"]
    ResModels --> ResAPI["P0: Resource Upload API"]

    TaxAPI --> DiagEngine["P1: Diagnostic Engine"]
    TaxModels --> ProfModel["P1: Proficiency Model"]
    DiagEngine --> ProfModel
    ProfModel --> PlanGen["P1: Learning Plan Generation"]
    TaxModels --> PlanGen

    ResAPI --> ContentDel["P2: Content Delivery"]
    PlanGen --> ContentDel
    ContentDel --> Practice["P2: Practice Questions"]
    Practice --> MasteryQuiz["P2: Mastery Quiz"]
    MasteryQuiz --> ProfModel

    Practice --> Coaching["P3: AI Coaching"]
    MasteryQuiz --> SpacedRep["P3: Spaced Repetition"]
    ProfModel --> Analytics["P3: Analytics"]

    ResAPI --> GapDetect["P4: Content Gap Detection"]
    ProfModel --> FAISSTips["P4: FAISS Tips per Subject"]
```

---

*Document prepared for architect review. All data models, APIs, and specifications are draft and subject to refinement before handoff to the development team.*