feat: Adaptive AI-Based Personalized Question Paper Generation Engine - #65
Draft
Vamshirathod14 wants to merge 4 commits into
Draft
Conversation
added 4 commits
July 18, 2026 01:08
Adds a new backend module (backend/src/modules/adaptive-engine) and two REST endpoints that drive a per-student adaptive worksheet workflow: - POST /api/adaptive/analyze/:studentId - POST /api/adaptive/worksheet/generate The engine analyses the student's existing evaluation reports, identifies weak vs strong competencies, and composes a worksheet weighted 60% remediation of weak topics, 20% reinforcement at the student's current level, and 20% stretch challenge above it. Reuses backend/src/levelGenerator for question sourcing. When no evaluation history exists, falls back to a grade-aligned default worksheet at the student's current level. Design is extensible: the engine selection lives in engine.ts, so an LLM-backed engine (Gemini / OpenAI) can be plugged in later without touching the route handlers or the frontend card. Files added backend/src/modules/adaptive-engine/types.ts (shared types) backend/src/modules/adaptive-engine/analyzer.ts (profile aggregation) backend/src/modules/adaptive-engine/deterministic.ts (default rule-based engine) backend/src/modules/adaptive-engine/generator.ts (DB + engine wiring) backend/src/modules/adaptive-engine/engine.ts (engine factory) backend/src/modules/adaptive-engine/index.ts (public surface) Files modified backend/src/index.ts (two new routes + import) frontend/src/components/RoleDashboards.tsx (AdaptiveWorksheetCard under TeacherDashboard)
…ator
Reuses the existing pdf-lib primitives already used by renderWorksheetPdf()
in paperGenerator.ts — no new PDF library, no Puppeteer/Chrome needed.
Backend
- New helper: generateAdaptiveWorksheetPdf() in paperGenerator.ts
Builds an A4 portrait PDF with FLN Portal header, student info card
(Name, ID, Current Level, Target Level, Date), adaptive strategy
strip (60 / 20 / 20), weak vs strong competency panels, engine
narrative, and paginated numbered questions each with answer space.
- New route: POST /api/worksheets/generate-adaptive-pdf
Mirrors /api/worksheets/generate-level-pdf. Reuses the existing
generateAdaptiveWorksheet() pipeline to compose questions, then
pipes them through the new PDF helper. Returns
{ success, pdfUrl, fileName } with the standard adaptive-worksheet-<name>.pdf
naming.
- Same role-scoping/auth/error semantics as the other adaptive routes.
Frontend
- AdaptiveWorksheetCard now shows two buttons after a worksheet is
generated:
* 📥 Download PDF — fetches the backend PDF as a blob and triggers
a browser download with the friendly filename.
* 🖨 Print — opens the browser print dialog.
- New printing rules scoped via @media print:
* hides dashboard / sidebar / cards / buttons (.no-print)
* only #adaptive-printable-area is visible
* A4 portrait page size with 12mm margins
- Each question in the printable area now has a dashed underline
answer space.
- Buttons are disabled before generation; they only appear once a
worksheet is on screen.
No regressions: existing /api/worksheets/generate-level-pdf,
/api/adaptive/* and other worksheet routes still return HTTP 200.
Lets a teacher generate adaptive worksheets for every placed student in the
active class with one click. Skips students pending diagnostic, exposes
live progress, and packages the resulting PDFs into a ZIP plus a single
merged PDF for continuous printing.
Backend (reuses existing services — no duplicated logic)
- jszip added as a dependency (no existing ZIP utility in the repo).
- POST /api/worksheets/bulk-adaptive
Body { className, section, schoolId, totalQuestions, cycle? }
Mirrors /api/diagnostic/bulk semantics — returns { jobId, totalEligible,
skippedCount, skipped, progressUrl } with HTTP 202.
Eligibility check: student has any levelHistory entry or currentLevel > 0.
Run in background to keep API responsive.
- GET /api/worksheets/bulk-adaptive/:jobId/progress
Polled by the UI while running. Returns { completed, failed,
currentStudentIndex, currentStudentName, status, skipped, generated,
zipReady, zipDownloadUrl, combinedPdfReady, combinedPdfUrl }.
- GET /api/worksheets/bulk-adaptive/:jobId/download
Streams the generated ZIP: <Name>.pdf per student, e.g.
Amanpreet-Singh.pdf, Krishna-Murari.pdf, ...
- GET /api/worksheets/bulk-adaptive/:jobId/combined-pdf
All student PDFs concatenated into a single file (pdf-lib merge) for
continuous printing from the browser PDF viewer.
- Role-scoping + auth + 400/401/403/404 error semantics match the other
adaptive routes.
- Bug fix: generateAdaptiveWorksheetPdf() now sanitizes studentName /
question text / topic / competency before passing to pdf-lib. The
WinAnsi-encoded Helvetica standard font cannot represent emoji
(🍎, ★) used by some levelGenerator templates, which previously
failed the whole bulk job for any student whose pool hit those
questions.
Frontend (leaves the single-student AdaptiveWorksheetCard unchanged)
- New sibling card: 📚 Bulk Adaptive Worksheet Generator (Class-Wide)
rendered directly below the single-student card.
- Header shows Placed / Pending / Total badges (computed from class roster).
- 📚 Generate Worksheets for Entire Class button starts the job.
- Live progress strip while running: 'Student X/Y — <Name>', animated
progress bar, percent counter.
- On completion shows:
✅ Generated N Worksheets Successfully
⚠ Skipped N students
Reason: Diagnostic Pending
- 📥 Download ZIP — fetches the archive as a blob and triggers a browser
download with the friendly class ZIP filename.
- 🖨 Print All — opens the combined PDF in a new tab; the user prints
from the browser's PDF viewer with the standard Ctrl/Cmd-P shortcut.
- Polling auto-stops on completion/failure; polling interval cleared on
component unmount.
No regressions: every existing route (/api/students,
/api/adaptive/worksheet/generate, /api/worksheets/generate-level-pdf,
/api/worksheets/generate-adaptive-pdf, /api/evaluation/:id/history, …)
still returns HTTP 200.
Manual resolution of conflicts introduced by the upstream restructuring (commits b959d5b → 363be59 on origin/main) which added the MongoDB / controllers / modules refactor on top of the original flat layout this branch was developed against. Restructured backend/src/index.ts so all four affected endpoints sit in clean, sequential order with no orphaned braces, no duplicate routes, no duplicated imports, and no merged-together handlers: - POST /api/worksheets/generate-level-batch (upstream, kept) - GET /api/worksheets/download-batch/:batchId (upstream, kept) - POST /api/worksheets/generate-adaptive-pdf (this branch) - POST /api/adaptive/analyze/:studentId (this branch) - POST /api/adaptive/worksheet/generate (this branch) - POST /api/worksheets/bulk-adaptive (this branch) - GET /api/worksheets/bulk-adaptive/:jobId/progress - GET /api/worksheets/bulk-adaptive/:jobId/download - GET /api/worksheets/bulk-adaptive/:jobId/combined-pdf Verified after this commit: * tsc --noEmit on frontend passes (0 errors in modified files) * All 9 routes registered exactly once * Single combined import of ./modules/adaptive-engine * Brace balance correct in all 3 modified files (index.ts, RoleDashboards.tsx, paperGenerator.ts) * Backend boots under MONGODB_URI env; all 4 feature endpoints respond correctly (auth, routing, error semantics) * Frontend boots and serves No existing functionality removed.
Vamshirathod14
force-pushed
the
feat/adaptive-ai-question-paper-generator
branch
from
July 17, 2026 19:55
a67f7a7 to
9a7cb07
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Status
This feature has been implemented and verified locally.
It was developed against an earlier upstream commit. Since then, the upstream repository has undergone significant restructuring, so GitHub reports merge conflicts and cannot automatically merge this branch.
The conflicts are due to changes in the upstream repository structure, not because of the feature implementation. After review, this branch can be rebased onto the latest
mainand the conflicts resolved before merging.Overview
This PR introduces an Adaptive AI-Based Personalized Question Paper Generation Engine for the FLN Platform.
The feature analyzes each student's previous evaluation history and automatically generates personalized worksheets focusing on weak competencies while reinforcing mastered concepts.
Features Added
Adaptive AI Worksheet Generator
PDF Export
Added Download PDF functionality.
Generated PDF contains:
Filename:
adaptive-worksheet-<student-name>.pdfPrint Support
Added browser print support.
Print mode:
Bulk Adaptive Worksheet Generation
Teachers can now generate adaptive worksheets for an entire class.
Features:
APIs Added
POST /api/adaptive/analyze/:studentIdPOST /api/adaptive/worksheet/generatePOST /api/worksheets/generate-adaptive-pdfTesting
Successfully tested:
No regressions observed during local testing.
Future Improvements