Assignment Checker

An automated assignment evaluation system that uses Google's Gemini AI to evaluate student GitHub repository submissions and provide detailed feedback with scores out of 10.

Features

• 🤖 AI-Powered Evaluation: Uses Google Gemini AI for intelligent code assessment
• 📊 Comprehensive Scoring: Evaluates based on functionality, code quality, documentation, best practices, and creativity
• 🔗 GitHub Integration: Automatically fetches and analyzes repository content
• 📈 Detailed Reports: Generates individual feedback and summary statistics
• 💾 Export Results: Saves evaluation results to JSON format
• 🎨 Colored Output: Beautiful terminal interface with progress indicators

Setup

1. Install Dependencies

# Activate virtual environment
source venv/bin/activate

# Install required packages
pip install -r requirements.txt

2. Configure API Keys

1. Copy the example environment file:

   cp env_example.txt .env

2. Edit .env and add your API keys:

   GEMINI_API_KEY=your_actual_gemini_api_key
   GITHUB_TOKEN=your_github_token_optional
   

3. Get API Keys

Gemini API Key (Required)

1. Visit Google AI Studio
2. Create a new API key
3. Copy it to your .env file

GitHub Token (Optional)

• Provides higher rate limits for repository access
• Get from GitHub Settings > Personal Access Tokens
• Only needs "public_repo" scope for public repositories

Usage

Run the Assignment Checker

python main.py

Interactive Process

1. Enter Assignment Description: Provide details about what students were supposed to implement
2. Add Repository URLs: Enter GitHub repository URLs one by one
3. Confirm and Start: The system will evaluate each submission

Example Session

Assignment Description: Create a Python calculator with basic operations (+, -, *, /) and error handling

Repo URL: https://github.com/student1/python-calculator
✓ Added: https://github.com/student1/python-calculator

Repo URL: https://github.com/student2/calculator-project
✓ Added: https://github.com/student2/calculator-project

Repo URL: done

Ready to evaluate 2 submissions.
Continue? (y/n): y

Evaluation Criteria

The system evaluates submissions based on:

• Functionality (30%): Does the code work and meet requirements?
• Code Quality (25%): Is the code clean, readable, and well-structured?
• Documentation (20%): Are there adequate comments and documentation?
• Best Practices (15%): Are coding standards followed?
• Creativity/Innovation (10%): Any creative solutions or extra features?

Output

Individual Results

• Student name and repository URL
• Score out of 10
• Detailed feedback with specific suggestions

Summary Report

• Average, highest, and lowest scores
• Score distribution visualization
• Failed submission details

Saved Files

• evaluation_results.json: Complete results in JSON format

Supported Repository Formats

The system accepts various GitHub URL formats:

• https://github.com/username/repository
• https://github.com/username/repository.git
• https://github.com/username/repository/tree/branch

Limitations

• Public repositories only (unless GitHub token provided)
• Maximum 50 files per repository (configurable)
• Files larger than 100KB are skipped
• Binary files are automatically excluded

Troubleshooting

Common Issues

1. "GEMINI_API_KEY not found"

   • Ensure your .env file exists and contains the API key
   • Check the key is correctly formatted

2. GitHub rate limits

   • Add a GitHub token to your .env file
   • Wait a few minutes between large batches

3. Repository access errors

   • Ensure repositories are public or you have access
   • Check repository URLs are correctly formatted

Getting Help

• Check the terminal output for specific error messages
• Ensure all dependencies are installed in the virtual environment
• Verify your API keys are valid and have necessary permissions

Example Output

ASSIGNMENT EVALUATION SUMMARY
=============================

Total Submissions: 3
Successful Evaluations: 3
Failed Evaluations: 0

SCORE STATISTICS:
- Average Score: 7.7/10
- Highest Score: 9/10
- Lowest Score: 6/10

SCORE DISTRIBUTION:
   9/10: █ (1)
   8/10: █ (1)  
   6/10: █ (1)