Evalify

AI-Assisted Answer Sheet Evaluation System

Evalify is a comprehensive automated grading system designed to streamline the evaluation of handwritten student answer sheets. It leverages OCR (Optical Character Recognition) and configurable keyword-based algorithms to grade student answers against a provided marking scheme.

Features

Phase 1: Foundation (Completed)

• Role-Based Authentication: Secure login for Admin, Teacher, and Student roles.
• Dashboards: Dedicated interfaces for each user role.
• Teacher Tools: Create exams, manage marking schemes.

Phase 2: Upload & OCR (Completed)

• File Upload: Support for PDF and Image uploads (Answer Sheets & Marking Schemes).
• OCR Engine:
  • EasyOCR (default): Deep-learning based OCR with superior handwriting recognition.
  • Tesseract (fallback): Traditional OCR for printed text.
  • Converts PDFs to high-quality images.
  • Handles various file formats (PNG, JPG, PDF).

Phase 3: Evaluation Engine (Completed)

• Configurable Grading Logic:
  • Fuzzy Matching: Uses Levenshtein distance to handle OCR typos and handwriting variations (e.g., "Algoritm" ≈ "Algorithm").
  • Stopword Removal: Toggle to ignore noise words ("the", "is") for concept-focused grading.
  • Scoring Modes:
    • Linear: Partial credit based on keyword coverage.
    • Binary: Strict all-or-nothing grading.
• REST API: Flexible endpoints to trigger evaluation with custom configurations.

Tech Stack

• Backend: Python 3.14, FastAPI
• Database: SQLite (SQLAlchemy ORM)
• OCR: EasyOCR (primary), Tesseract, pytesseract, pdf2image
• Matching: FuzzyWuzzy, python-Levenshtein
• Frontend: HTML5, CSS3, Vanilla JavaScript

Installation

1. Clone the repository:

   git clone https://gitlab.com/medhxnsh/evalify.git
   cd evalify

2. Create a virtual environment:

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

3. Install dependencies:

   pip install -r backend/requirements.txt

4. Install System Dependencies:

   • Tesseract OCR:
     • Mac: brew install tesseract
     • Linux: sudo apt-get install tesseract-ocr
     • Windows: Download installer from UB-Mannheim.
   • Poppler (for PDF conversion):
     • Mac: brew install poppler

Usage

1. Start the Server:

   uvicorn backend.app:app --reload --port 6001

   The API will be available at http://localhost:6001.

2. Access the App: Open http://localhost:6001/shared/login.html in your browser.

   Default Credentials:

   • Teacher: teacher / teacher123
   • Student: student / student123

Testing

Run userspace test scripts to verify core logic:

# Test Phase 3 Grading Logic (Fuzzy Match, Scoring)
python backend/test_phase3_logic.py

# Test OCR Pipeline (EasyOCR - default)
python backend/test_ocr_script.py

# Test OCR Pipeline (Tesseract fallback)
python backend/test_ocr_script.py --engine tesseract