encoach_frontend_v4/docs/MATH_IT_ADAPTIVE_LEARNING_SRS.md

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
2. System Overview
3. Subject Taxonomy and Knowledge Graph
4. Diagnostic Assessment Engine
5. Proficiency Profile
6. Learning Plan Generation
7. Hybrid Content Delivery
8. Progress Tracking and Reassessment
9. Data Models -- Odoo 19
10. REST API Specification
11. AI Integration Specification
12. Frontend 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

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

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

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:

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:

# 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

# 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

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

# 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:

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:

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

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.