EiplGrader Documentation

An Automatic Grading Suite for “Explain in Plain Language” Questions

EiplGrader automatically grades programming assignments where students explain algorithms in natural language. It uses large language models to generate code from student explanations and tests that code against predefined test cases.

🚀 Quick Start

Installation

pip install eiplgrader

Set Your API Key

export OPENAI_API_KEY="your-api-key-here"

Basic Example

from eiplgrader.codegen import CodeGenerator
from eiplgrader.tester import CodeTester

# Generate code from natural language
code_generator = CodeGenerator(api_key, language="python")
result = code_generator.generate_code(
    student_response="that adds two numbers and returns the result",
    function_name="add_numbers",
    gen_type="cgbg"
)

# Test the generated code
test_cases = [
    {"parameters": {"a": 1, "b": 2}, "expected": 3},
    {"parameters": {"a": -1, "b": 1}, "expected": 0}
]

code_tester = CodeTester(
    code=result["code"][0],
    test_cases=test_cases,
    function_name="add_numbers",
    language="python"
)

test_result = code_tester.run_tests()
print(f"Tests passed: {test_result.successes}/{test_result.testsRun}")

🎯 Key Features

Multi-language Support: Python, JavaScript, Java, C++, C, Go, and Haskell
Intelligent Type Inference: Automatic type detection for dynamic languages
Multiple Generation Modes: CGBG, function redefinition, and code segmentation
Comprehensive Testing: Built-in test runner with detailed results
Research-backed: Based on peer-reviewed educational research
Flexible Architecture: Easy to extend with new languages and features

📚 Documentation Sections

Quickstart Guides

Get up and running quickly with language-specific examples:

User Guide

Learn how to use all features effectively:

Basic Usage - Core concepts and workflows
Advanced Features - Multiple variants, segmentation, in-place operations
Test Case Format - Comprehensive test case documentation
Language Support - Detailed language capabilities and requirements
Error Handling - Understanding and resolving errors

Developer Documentation

Extend and contribute to EiplGrader:

Architecture Overview - System design and components
Core Components - Deep dive into CodeGenerator and CodeTester
Language System - Adding new languages and executors
API Reference - Complete method documentation
Testing - Test suite and quality assurance
Contributing - How to contribute

🔧 Installation Options

Standard Installation

pip install eiplgrader

Development Installation

git clone https://github.com/hamiltonfour/eiplgrader.git
cd eiplgrader
pip install -e ".[dev]"

🌟 Language Support at a Glance

Language	Type System	Type Inference	Test Format
Python	Dynamic	✅ Automatic	Simplified
JavaScript	Dynamic	✅ Automatic	Simplified
Go	Static	❌ Required	Explicit
Java	Static	❌ Required	Explicit
C++	Static	❌ Required	Explicit
C	Static	❌ Required	Explicit
Haskell	Static	❌ Required	Explicit

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Setting up a development environment
Running tests and linting
Submitting pull requests
Adding new languages or features

📖 Citation

If you use EiplGrader in your research or teaching, please cite:

@inproceedings{smith2024code,
    author = {Smith IV, David H. and Zilles, Craig},
    title = {Code Generation Based Grading: Evaluating an Auto-grading Mechanism 
             for "Explain-in-Plain-English" Questions},
    year = {2024},
    publisher = {Association for Computing Machinery},
    doi = {10.1145/3649217.3653582},
    booktitle = {Proceedings of the 2024 on Innovation and Technology 
                 in Computer Science Education V. 1},
    pages = {171–177}
}

⚠️ Important Notice

This is a research tool. Breaking changes between versions are expected. Always test thoroughly before using in production grading scenarios.

🔗 Quick Links

Ready to get started? Check out our Python Quickstart or browse the full documentation.