Gradence – AI-Powered Question Paper Analyzer

🔗 Try it live: gradence-xw5o.onrender.com

Hosted on Render's free tier — the first request after a period of inactivity may take ~50s to wake the server.

Gradence is an AI-powered academic analytics tool that extracts questions from university examination papers and analyzes them using Bloom's Taxonomy and Course Outcome (CO) mapping.

Most real question papers are scanned images — either image-only PDFs or images pasted into a Word document — so Gradence reads them with a vision model (Google Gemini) instead of relying on brittle OCR. Clean text papers are parsed directly.

---

Screenshots

Upload any paper — PDF, DOCX, or scanned image:

Instant dashboard — Bloom's taxonomy distribution and course-outcome coverage:

Per-question breakdown — every question tagged with its Bloom's level (colour-coded) and mapped course outcome:

Balance recommendations — actionable suggestions on which questions and COs to add for a more balanced paper:

---

Features

Question Extraction

• Reads PDF, DOCX, and TXT question papers
• Uses Google Gemini vision to read scanned / image-based papers (image PDFs, image-filled DOCX, and PDFs with a poor OCR text layer)
• Parses genuine text papers directly (no API call needed)

Bloom's Taxonomy Classification

Classifies each question into one of six cognitive levels:

Level	Meaning
BT1	Remember
BT2	Understand
BT3	Apply
BT4	Analyze
BT5	Evaluate
BT6	Create

Subject & Course Outcome Mapping

• Detects the subject from the paper
• Maps each question to predefined, subject-specific Course Outcomes

Analytics & Insights

• Total questions and dominant Bloom's level
• Bloom's distribution and CO coverage charts
• Balance Recommendations — actionable suggestions on which questions / COs to add to make the paper more balanced (e.g. "add ~3 higher-order questions", "CO4 is not assessed")

---

Tech Stack

Area	Technology
Backend	Python, Flask
Vision extraction	Google Gemini (gemini-2.5-flash) via google-genai
Bloom classifier	scikit-learn model (models/bloom_classifier/bloom_model.pkl)
Document parsing	PyMuPDF (PDF), python-docx (DOCX)
Frontend	HTML, CSS, JavaScript, Chart.js
Data	JSON-based CO mappings (data/co_mapping.json)

---

Project Structure

Gradence Final/
├── app.py                     # Flask entry point
├── routes/                    # HTTP routes (/analyze)
├── services/                  # extraction, LLM vision, bloom, CO mapping, balance advisor
├── extractor/                 # PDF type detection + text extraction + parser
├── models/                    # bloom_classifier/bloom_model.pkl
├── static/                    # style.css, app.js
├── templates/                 # index.html
├── data/                      # co_mapping.json
├── requirements.txt
└── README.md

---

Setup

1. Clone the repository

git clone https://github.com/devika-nair-s/Gradence-QP-Analyzer-Tool.git
cd Gradence-QP-Analyzer-Tool

2. Create a virtual environment

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Add your Gemini API key (required)

Vision extraction calls Google Gemini, so you need a free API key.

1. Get one (no billing needed) at https://aistudio.google.com/apikey
2. Create a .env file in the project root:

echo 'GEMINI_API_KEY=your-key-here' > .env

.env is git-ignored — never commit your key.

Optional environment variables:

• GRADENCE_GEMINI_MODEL — override the vision model (default gemini-2.5-flash)
• GRADENCE_LLM_BATCH — images sent per Gemini call (default 5)
• GRADENCE_USE_LLM=0 — disable vision extraction (text-only papers)

---

Run

python3 app.py

The app runs on http://127.0.0.1:5000.

macOS note: port 5000 is used by the AirPlay Receiver. Either disable it (System Settings → General → AirDrop & Handoff → AirPlay Receiver) or run on another port, e.g.:

python3 -c "from app import app; app.run(port=5001, debug=True)"

---

Deployment (Render)

The repo ships with a render.yaml, Procfile, and runtime.txt for a free one-click deploy on Render.

1. Push the repo to GitHub (already done).
2. On Render: New → Blueprint, connect this repository. Render reads render.yaml and creates a free web service.
3. When prompted, paste your GEMINI_API_KEY (stored as a secret, never in the repo).
4. Deploy. Render gives you a public URL like https://gradence.onrender.com.

The service runs under gunicorn with a 300s request timeout (vision analysis of large scans can take a minute or two). On the free plan the service sleeps after inactivity, so the first request after idle takes ~50s to wake.

---

Workflow

1. Upload a question paper (PDF / DOCX / TXT)
2. Detect the file type and whether it is text or image-based
3. Extract questions — via Gemini vision for scans, or the text parser for clean text
4. Detect the subject
5. Classify each question's Bloom's level
6. Map each question to a Course Outcome
7. Generate charts and balance recommendations

---

Sample Output

For each extracted question:

Question:   Compare the time complexity of merge sort and quick sort.
Bloom Level: BT4 – Analyze
CO:          CO3 – Problem Solving

Plus paper-level analytics: Bloom's distribution, CO coverage, and balance suggestions.

---

Future Enhancements

• CO mapping using semantic similarity (beyond keyword matching)
• Explicit question difficulty prediction (Easy / Medium / Hard)
• Department-wide analytics dashboard
• Export reports as PDF
• .doc (legacy Word) support

---

Author

Devika Nair

AI-powered academic assessment and question paper analysis project, developed as part of engineering coursework and research.