Feat/remediation

[02Tirtha]

PR: Remediation Sheet Generation Feature

Overview

The Remediation Feature is a powerful AI-driven, personalized practice generation system. It automatically creates targeted practice questions for students based on their incorrect answers in assessments. Operating as an asynchronous background service triggered post-evaluation, it generates 5 customized practice variants per failed question, providing concept-matched and human-readable content to help students master the topics they struggle with.

Highlights

• AI-Driven Personalization: Generates practice questions tailored exactly to the student's specific failure points.
• Resilient Fallback Chain: Employs a guaranteed fallback mechanism (AI → Blueprint → Inline) ensuring that practice content is always delivered, even if AI services are unavailable.
• Smart 3-Engine Router: Intelligently classifies questions and routes them to the most suitable generation engine (Numeric, Matrix, or AI API).
• Extensive Concept Library: Features over 50+ concept-specific deterministic generators and a 200+ keyword-to-concept mapping dictionary.
• Asynchronous Processing: Two-phase pipeline that immediately acknowledges generation requests while processing the heavy lifting in the background, keeping the system responsive.

Architecture

The system employs a modular architecture bridging Python and Node.js ecosystems:

┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   EVALUATION │     │  REMEDIATION     │     │  BLUEPRINT       │
│   ENGINE     │────▶│  SERVICE         │────▶│  ENGINE          │
│   (Python)   │     │  (Node/TypeScript)     │  (TypeScript)    │
└──────────────┘     └────────┬─────────┘     └────────┬─────────┘
                              │                        │
                              ▼                        ▼
                     ┌──────────────────┐     ┌──────────────────┐
                     │  GENERATIVE      │     │  CONCEPT         │
                     │  ENGINE          │     │  DICTIONARY      │
                     │  (Smart Router)  │     │  (JSON + AI)     │
                     └────────┬─────────┘     └──────────────────┘
                              │
            ┌─────────────────┼─────────────────┐
            ▼                 ▼                 ▼
     ┌────────────┐    ┌────────────┐    ┌────────────┐
     │ NUMERIC    │    │ MATRIX     │    │ AI/GEMINI  │
     │ ENGINE     │    │ ENGINE     │    │ API        │
     └────────────┘    └────────────┘    └────────────┘

Workflow

1. Trigger: A student submits a worksheet or diagnostic (e.g., via ICR scan).
2. Evaluation: The Evaluation Engine grades the submission and identifies failed questions.
3. Phase A (Immediate): RemediationService.startGeneration() is called. A RemediationLedger is created in MongoDB with a pending status, returning immediately to the caller.
4. Phase B (Background):
   • The service resolves the original question text.
   • Detects the core mathematical or logical concept.
   • Routes the question to the GenerativeEngine.
5. Generation: The engine generates 5 variants using the best available method.
6. Completion: The ledger is updated to completed and the practice questions are available for the student.

Generation Engine (Smart Router)

The GenerativeEngine acts as a smart router, classifying the original question and dispatching it to one of three specialized engines:

• Numeric Engine: Ideal for arithmetic, counting, and measurements. It extracts numbers and mutates them with deterministic offsets while preserving the original sentence structure.
• Matrix Engine: Handles classification, odd-one-out, and shape matching by building target/foil item groups and returning dropdown options.
• AI/Gemini API: Handles complex reasoning or visual descriptions (e.g., tracing, clock/time, tally marks) by generating 5 variants in a single structured JSON request.

Major Components

• RemediationService: The main orchestrator handling the async Phase A/B pipeline.
• GenerativeEngine: The smart 3-engine classification and routing layer.
• BlueprintEngine: A deterministic concept-based generator providing zero-AI dependency fallbacks.
• Concept Dictionary: A JSON-based mapping of 200+ keywords to concepts for auto-detection.
• Models (RemediationLedger, ExamBlueprint): The data layer tracking generation status and blueprint metadata.
• RemediationNotesView: The React frontend component that renders the generated practice variants.

Benefits

• Targeted Learning: Directly addresses individual student knowledge gaps.
• High Reliability: Zero-downtime generation thanks to the robust AI-to-Blueprint fallback chain.
• Teacher Efficiency: Eliminates the manual effort of creating customized remediation worksheets for every student.
• Highly Extensible: New mathematical or logical concepts can be easily added to the BlueprintEngine and Concept Dictionary.

Real Implementation of the Remediation Sheet

• API Triggers: /api/students/:id/level-worksheet/submit and /api/students/:id/diagnostic/submit
• Data Persistence: Stored as a RemediationLedger containing the original failed question, the student's incorrect answer, and the 5 generated practice variants (with answers and hints).
• Frontend Display: Accessible at /remediation-note/:studentId/:examId. The RemediationNotesView fetches the ledger and displays:
  • The original failed question and student's answer.
  • 5 interactive practice variants (supporting both text and dropdown answer modes).
  • Remediation hints and concept tags.
  • Badges indicating whether the question was AI-generated or generated by the fallback system.