Auto-Grading System (ACE-V1)

An automated grading system that extracts questions and answers from images, stores them in MongoDB, and uses BAML to grade student responses.

Overview

This system automates the grading process for exams by:

1. Extracting exam questions from images
2. Extracting student answers from images
3. Storing both in MongoDB collections
4. Matching questions with corresponding answers
5. Grading answers using BAML's AI-powered grading function
6. Storing grading results in MongoDB for future reference

Project Structure

ACE-V1/
├── Python/                       # Python source code directory
│   ├── Extract_Text.py           # Functions for extracting text from images
│   ├── Grade.py                  # Functions for grading student answers
│   ├── baml_src/                 # BAML source files
│   │   ├── Grade.baml            # BAML grading function definitions
│   │   ├── Question_Extraction.baml  # BAML question extraction definitions
│   │   └── generators.baml       # BAML generator definitions
│   ├── Questions.png             # Sample exam questions image
│   ├── Answers_name.png          # Sample student answers image
│   └── Bad_answers.png           # Alternative student answers image
├── main.py                       # Main entry point for the application
├── setup_env.py                  # Script to set up environment variables
├── .gitignore                    # Git ignore file
├── requirements.txt              # Python dependencies
└── README.md                     # This file

Features

• Image-to-Text Extraction: Converts exam questions and student answers from images to structured data
• MongoDB Integration: Stores and retrieves data from MongoDB collections
• AI-Powered Grading: Uses BAML to grade student answers with configurable toughness levels
• Detailed Feedback: Provides explanations for each graded answer
• Organized Output: Clear, well-formatted console output with visual separators
• Latest Data Retrieval: Always uses the most recently added data from MongoDB collections
• Comprehensive Grading: Evaluates answers based on correctness and explanation quality

Requirements

• Python 3.8+
• MongoDB Atlas account
• BAML client (baml-client)
• PIL/Pillow for image processing
• pymongo for MongoDB operations
• API keys for OpenAI and DeepSeekor (see Setup section)

Setup

Prerequisites

• Node.js 18+ and npm
• Python 3.8+ (with python3 on your PATH)
• MongoDB Atlas connection string
• API keys for the LLM providers you intend to use (OpenRouter, OpenAI, etc.)

One-time bootstrap

1. Clone the repository:

   git clone <repository-url>
   cd ACE-V1

2. Run the automated setup script (macOS/Linux/Git Bash):

   ./setup-dev.sh

   This script will:

   • Install npm dependencies in the root workspace, client, and server
   • Create Python/.venv and install Python requirements (including baml-py)
   • Remind you to populate any missing .env files

   Windows PowerShell: run bash setup-dev.sh instead.

3. Populate environment files:

   • Copy client/.env.example → client/.env and fill in the values
   • Copy server/.env.example → server/.env
   • Create/update Python/.env with your API keys and MongoDB URI

4. (Optional) Review Grade.py and Extract_Text.py if you need to adjust default MongoDB configuration or API clients.

Running the Application

Development Mode

After the one-time bootstrap, start the full stack with:

npm run dev

This command launches:

• The React client on http://localhost:5173 (or another port if 5173 is in use)
• The Node.js server on http://localhost:5001/api

Individual Components

If you need to run the client or server individually:

# Run only the client
npm run client

# Run only the server
npm run server

Environment Setup

Make sure you have the following environment files configured:

1. /client/.env - For Clerk authentication and API URL:

VITE_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
VITE_CLERK_SECRET_KEY=your_clerk_secret_key
VITE_API_BASE_URL=http://localhost:5001/api

2. /server/.env - For MongoDB connection:

PORT=5001
MONGODB_URI=your_mongodb_connection_string

Usage

Run the main script to process and grade exam answers:

python main.py

The script will:

1. Add exam questions to MongoDB (if not commented out)
2. Add student answers to MongoDB
3. Grade the student answers using BAML
4. Save the grading results to MongoDB

Customizing Execution

You can modify main.py to:

• Comment out specific steps (e.g., skip adding questions if they're already in the database)
• Change the image files used for questions and answers
• Adjust the grading toughness level

MongoDB Collections

The system uses three collections in the BadriNath-Org database:

1. Exam-Questions: Stores exam questions with categories and point values

   • Structure: { category: string, questions: [{ question: string, points: number }] }

2. Answers: Stores student answers with student information

   • Structure: { name: string, student_id: string, autograde: boolean, answers: [{ category: string, answers: [{ true_or_false: boolean, answer: string }] }] }

3. Grades: Stores grading results with detailed feedback

   • Structure: { student_name: string, student_id: string, grades: { grade: [{ points: number, explanation: string }] }, total_points: number, percentage: number }

Grading Logic

The system grades answers by:

1. Retrieving the latest student answers and exam questions from MongoDB (sorted by _id in descending order)
2. Matching questions with corresponding answers by their index position
3. Sending the combined data to BAML's GradeQuestion function with a specified toughness level
4. Processing the grading results and calculating total scores
5. Storing the results in the Grades collection with timestamps

Customization

• Toughness Level: Adjust the toughness level (1-5) when calling grade_student_answers() to make grading more or less strict
• Output Format: Modify print statements in the code to change output formatting
• Database Connection: Update MongoDB connection details as needed
• Image Sources: Change the image files used for questions and answers

Security Note

The MongoDB connection URI and API keys contain sensitive credentials. For production use, it's recommended to:

1. Use environment variables to store credentials (already implemented with the .env file)
2. Implement proper access controls for your MongoDB instance
3. Never commit credentials to version control (the .gitignore file is configured to exclude .env files)

Troubleshooting

• MongoDB Connection Issues: Verify your network connection and MongoDB Atlas credentials
• Image Processing Errors: Ensure the image files exist and are readable
• BAML Errors: Check that your API keys are correctly set in the .env file
• Grading Issues: Verify that the question and answer formats match the expected structure

License

[Your License Here]

Contact

[Your Contact Information]