📝 MCQ Grading Bot

Automatically grade solved MCQ answer sheets from images using Google Gemini 1.5 Vision, displayed through an elegant Gradio web app.

---

---

Table of Contents

1. Overview
2. Key Features
3. Live Demo (Colab)
4. Architecture
5. Installation
6. Configuration & API Keys
7. Running the App
8. Output Format
9. Project Structure
10. Roadmap
11. Contributing
12. License
13. Acknowledgements

---

Overview

MCQ Grading Bot is a lightweight Python application that turns handwritten or printed multiple‑choice answer sheets into structured feedback in seconds. By combining Google Gemini 1.5 Vision’s image‑understanding power with an intuitive Gradio interface, teachers and automated testing systems can:

• Scan a photo of a completed MCQ paper.
• Instantly obtain the student’s name, total questions, correct/wrong counts, score %, and a detailed per‑question breakdown.
• Export or copy results for record‑keeping or analytics workflows.

Average response time is <5 seconds on a Colab GPU (Gemini Flash model, temperature 0.1).

---

Key Features

Capability	Details
📸 Image Upload	Accepts PNG/JPG; auto‑converts to bytes for the API.
🧠 Gemini Vision Grading	Generates a strict JSON report, then prettifies it for display.
💡 Name Detection	Parses student name from the sheet if present.
📊 Detailed Analytics	Correct ✓ / wrong ✗ tag on every answer plus overall percentage.
⚡ Fast & Lightweight	No server‑side storage; everything happens in‑memory.
🌐 Colab‑Friendly	One‑click run in Google Colab; sharing enabled.

---

Live Demo (Colab)

Launch	Link
▶️ Open in Colab	click-to-open

The Colab notebook comes pre‑installed with requirements and uses Colab Secrets so your API keys stay private.

---

Architecture

┌───────────────┐     Image (PNG/JPG)     ┌──────────────────┐
│   Frontend    │ ───────────────────────►│  Gemini Vision    │
│  (Gradio UI)  │◄──────── Report JSON ── │  (1.5‑Flash)      │
└─────▲─┬───────┘                          └────────▲─────────┘
      │ |  Prettify + Stats                         |
      │ └───────────────────────────────────────────┘
      │            Backend (Fast in‑memory)
      └────────── Results to User (Markdown Textbox)

---

Installation

1. Clone the repo

   git clone https://github.com/choudaryhussainali/MCQ_Grading_Bot.git
   cd MCQ_Grading_Bot

2. Create a virtual environment (optional)

   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

---

Configuration & API Keys

The app needs Google Gemini (and optionally Groq) API keys.

Variable	Description	Required
GEMINI_API_KEY	Key for Gemini 1.5 Vision	✅
GROQ_API_KEY	Key for Groq LLMs (future use)	⬜

### Option A — Colab Secrets

from google.colab import userdata
# then access with userdata.get("GEMINI_API_KEY")

### Option B — Environment File Create a .env in project root:

GEMINI_API_KEY=your_gemini_key_here
GROQ_API_KEY=your_groq_key_here

pip install python-dotenv

The script will fall back to os.getenv() if google.colab isn’t present.

---

Running the App

python mcq_grading_bot.py      # or the filename you saved

The terminal prints a local URL (e.g. http://127.0.0.1:7860). Open it in your browser, upload an MCQ sheet image, and click “Grade Answers”.

---

Output Format

Internally the bot expects Gemini to return pure JSON:

{
  "student_name": "John Doe",
  "total_questions": 20,
  "correct_answers": 18,
  "wrong_answers": 2,
  "score_percentage": 90,
  "mcqs": [
    {
      "question_number": "Q1",
      "question": "What is 2 + 2?",
      "correct_answer": "B",
      "student_answer": "B",
      "is_correct": true
    }
  ]
}

This is parsed and rendered as a neat, human‑readable Markdown report in the Gradio textbox.

---

Project Structure

MCQ_Grading_Bot/
├─ mcq_grading_bot.py          # Main Gradio app
├─ requirements.txt
├─ screenshots/
│  └─ demo.png                 # UI screenshot
├─ .env.example                # Sample env file
└─ README.md

---

Roadmap

• CSV / PDF export of grading results
• Bulk image upload & batch grading
• Integration with LMS APIs (Moodle, Canvas)
• UI theme switcher (light/dark)
• Automated unit tests & CI workflow

---

🖼️ Screenshots

---

Contributing

Pull requests are welcome!

1. Fork the repo
2. Create a feature branch: git checkout -b feat/your‑feature
3. Commit & push: git commit -m "Add feature"
4. Open a PR describing your changes.

Please run black and flake8 before submitting.

---

📄 License

This project is proprietary and confidential. All rights reserved.

© 2025 HUSSAIN ALI. This code may not be copied, modified, distributed, or used without explicit permission.

---

📬 Contact

For questions or collaboration requests:

• 📧 Email: choudaryhussainali@outlook.com
• 🌐 GitHub: choudaryhussainali

---

Acknowledgements

• Google Generative AI Python SDK
• Gradio
• Pillow
• Inspired by educators streamlining assessment workflows.

---

Happy grading! If this project helps you, please ⭐️ the repo and share feedback.