instantgrade 0.1.14

An automated evaluation framework for Python notebooks and Excel assignments

InstantGrade An automated evaluation framework for Python notebooks and Excel assignments

---

🌱 Dr. Chandravesh Chaudhari

Dr. Chandravesh Chaudhari is the maintainer of InstantGrade — an automated evaluation platform currently focused on grading Python Jupyter notebooks and Excel assignments and more to follow in future.

Contact & social links:

• Email: [e-mail]
• Website: https://chandraveshchaudhari.github.io/website/
• LinkedIn: https://www.linkedin.com/in/chandraveshchaudhari

---

📚 Documentation

Read the full documentation →

• Installation Guide - Get started in minutes
• Quick Start - Your first evaluation
• Usage Guide - Comprehensive features
• API Reference - Complete API documentation
• Examples - Real-world use cases

---

• Introduction
• Features
• Installation
• Usage
• Supported File Types
• Contribution
• Future Improvements

Introduction

InstantGrade is a comprehensive, extensible evaluation framework designed to automatically grade student submissions against instructor solution files. It supports multiple file formats including Python Jupyter notebooks and Excel files, making it ideal for educational institutions and online learning platforms.

The framework was created to streamline the grading process for programming and data analysis assignments, reducing manual effort while providing detailed, actionable feedback to students. The vision is to expand support to additional file types and programming languages, creating a universal evaluation platform for technical education.

👩‍🏫 About the Maintainer

Dr. Chandravesh Chaudhari

📧 [e-mail] 🌐 Website 🔗 LinkedIn

Features

• Automated Evaluation: Compare student submissions against instructor solutions automatically
• Multiple File Format Support: Currently supports Python Jupyter notebooks (.ipynb) and Excel files (.xlsx, .xls)
• Comprehensive Reporting: Generate detailed HTML reports with visual feedback and scoring
• AST Analysis: Deep code comparison using Abstract Syntax Tree analysis for Python code
• Flexible Configuration: Customizable evaluation criteria through JSON configuration
• Batch Processing: Evaluate multiple student submissions in one run
• Extensible Architecture: Easy to add support for new file types and evaluation strategies

Significance

• Time-Saving: Reduces manual grading effort by 90% for programming assignments
• Consistency: Ensures uniform evaluation criteria across all student submissions
• Detailed Feedback: Provides students with specific areas of improvement
• Scalability: Handles large classes with hundreds of submissions efficiently
• Educational Focus: Allows instructors to focus on teaching rather than repetitive grading tasks

Installation

This project is available at PyPI. For help in installation check instructions

python3 -m pip install instantgrade  

For development installation:

git clone https://github.com/chandraveshchaudhari/instantgrade.git
cd evaluator
python3 -m pip install -e .

Docker (recommended for notebook isolation)

InstantGrade uses Docker to run student notebooks in an isolated environment. For the Docker-backed grading to work, users should install Docker Desktop (macOS/Windows) or Docker Engine (Linux).

• Install Docker Desktop: https://www.docker.com/products/docker-desktop
• After installing Docker, make sure the daemon is running before invoking grading with use_docker=True.

When upgrading InstantGrade (new release), existing local Docker images named instantgrade:latest may be stale and could cause import or runtime errors inside the container. To avoid this, do one of the following after upgrading:

• Prefetch a new image tagged to the current commit (recommended):

# from the repository root
python tools/docker_build_image.py

# to force a rebuild even if an image exists
python tools/docker_build_image.py --force

• Or allow the runtime to rebuild automatically by setting the environment variable for a single run:

instantgrade_FORCE_REBUILD=1 instantgrade --solution sample_solutions.ipynb --submissions ./submissions/

• Developer fast-iteration option: bind-mount the src directory into the container so you don't need to rebuild the image on small changes.

The repository ships a small helper at tools/docker_build_image.py that builds a git-SHA-tagged image (and also tags instantgrade:latest for convenience). This is the recommended step for administrators preparing a new release in their environment.

Dependencies

Required

• pandas - Data manipulation and analysis for comparison results
• openpyxl - Reading and writing Excel files
• nbformat - Working with Jupyter notebook files
• nbclient - Executing Jupyter notebooks programmatically
• click - Creating command-line interfaces

Optional

• xlwings - Advanced Excel automation capabilities (Windows/macOS only)

Usage

Basic Usage

Python API

from instantgrade import Evaluator

# Initialize evaluator with solution and submissions folder
evaluator = Evaluator(
    solution_file_path="path/to/solution.ipynb",
    submission_folder_path="path/to/submissions/"
)

# Run complete evaluation pipeline
report = evaluator.run()

Command Line Interface

# Evaluate Python notebook submissions
instantgrade --solution sample_solutions.ipynb --submissions ./submissions/ --output ./report/

# Evaluate Excel submissions
instantgrade --solution solution.xlsx --submissions ./excel_submissions/ --output ./excel_report/

Supported File Types

Python Jupyter Notebooks (.ipynb)

• Executes code cells and compares outputs
• AST-based code structure comparison
• Variable and function definition verification
• Exception and error handling analysis

Excel Files (.xlsx, .xls)

• Cell value comparison across worksheets
• Formula evaluation and verification
• Conditional formatting checks
• Chart and pivot table analysis (with xlwings)

Future Support (Planned)

• R Markdown files (.Rmd)
• Python scripts (.py)
• SQL files (.sql)
• MATLAB scripts (.m)

Important links

• Documentation
• Quick tour
• Project maintainer (feel free to contact)
• Future Improvements
• License

Contribution

All kinds of contributions are appreciated:

• Improving readability of documentation
• Feature Request
• Reporting bugs
• Contribute code
• Asking questions in discussions

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For detailed contribution guidelines, see the Contributing Guide.