Natarajan-Networks/grading-env

1---2title: Grading Env3emoji: 📚4colorFrom: blue5colorTo: green6sdk: docker7pinned: false8license: apache-2.09tags:10  - openenv11  - reinforcement-learning12  - education13  - grading14  - rl-environment15---16 17# EduEval — Automated Answer Sheet Grading Environment18 19An OpenEnv-compatible reinforcement learning environment for training and evaluating AI agents on automated answer sheet grading tasks.20 21## 🎯 Motivation22 23Manual grading of student answer sheets is time-consuming, inconsistent, and does not scale. EduEval provides a structured RL environment where an AI agent learns to grade three distinct types of student answers — factual, conceptual, and essay — matching human expert graders across varying complexity levels.24 25## 🌍 Environment Description26 27EduEval simulates a real-world educational grading pipeline with **3 distinct grading tasks**. Each task requires a different grading strategy:28 29- **Task 1 (Factual)**: Objective questions with clear right/wrong answers30- **Task 2 (Conceptual)**: Questions requiring partial credit based on concept coverage31- **Task 3 (Essay)**: Complex descriptive answers requiring holistic evaluation32 33Each episode randomly selects 3 questions from a pool of 10, making every episode unique and preventing overfitting.34 35## 📐 Action Space36 37| Field | Type | Range | Description |38|---|---|---|---|39| marks_awarded | float | 0.0 – 1.0 | Marks given to the student answer |40 41## 👁️ Observation Space42 43| Field | Type | Description |44|---|---|---|45| question_text | string | The exam question being graded |46| student_answer | string | The student's response |47| answer_key | string | The correct reference answer |48| answer_summary | string | Summary of student answer quality |49| semantic_similarity | float | Keyword-based similarity score (0.0-1.0) |50| concept_coverage | float | How well key concepts are covered (0.0-1.0) |51| question_number | int | Current question number in episode |52| total_questions | int | Total questions in episode (always 3) |53| max_marks | float | Maximum marks for this question |54| task_id | int | Task type (1=factual, 2=conceptual, 3=essay) |55| done | bool | Whether episode is complete |56 57## 📋 Tasks58 59### Task 1 — Factual Grading (Easy)60Grade objective factual questions with clear right or wrong answers. The agent must identify whether the student answer matches the correct answer and award full or zero marks with strict accuracy.61 62**Example:**63- Question: "What is the chemical formula for water?"64- Student Answer: "H2O"65- Expected Mark: 1.066 67### Task 2 — Conceptual Grading (Medium)68Grade concept-based answers requiring partial credit scoring. The agent must evaluate how well the student covers key concepts and award graduated marks based on concept coverage.69 70**Example:**71- Question: "Explain how vaccines work."72- Student Answer: "Vaccines introduce weak viruses so the immune system learns to fight them."73- Expected Mark: 0.8 (covers main idea but misses immunological memory)74 75### Task 3 — Essay Grading (Hard)76Grade complex descriptive essays requiring holistic evaluation of content accuracy, concept coverage, and critical analysis depth.77 78**Example:**79- Question: "Critically analyze the impact of the Industrial Revolution."80- Student Answer: "The Industrial Revolution changed working conditions and urbanization..."81- Expected Mark: 0.65 (partial coverage, lacks critical analysis depth)82 83## 🏆 Reward Functions84 85### Task 1 — Factual (Strict)86| Accuracy | Reward |87|---|---|88| Exact match | 1.0 |89| diff ≤ 0.1 | 0.7 |90| diff ≤ 0.2 | 0.4 |91| diff ≤ 0.3 | 0.2 |92| diff > 0.3 | 0.0 |93 94### Task 2 — Conceptual (Graduated)95| Accuracy | Reward |96|---|---|97| Exact match | 1.0 |98| diff ≤ 0.1 | 0.85 |99| diff ≤ 0.2 | 0.6 |100| diff ≤ 0.3 | 0.4 |101| diff > 0.4 | 0.0 |102 103### Task 3 — Essay (Holistic)104| Accuracy | Reward |105|---|---|106| Exact match | 1.0 |107| diff ≤ 0.1 | 0.8 |108| diff ≤ 0.2 | 0.6 |109| diff ≤ 0.3 | 0.4 |110| diff > 0.4 | 0.0 |111 112**All tasks include:**113- Penalty of -0.4 for extreme over-grading114- Penalty of -0.4 for extreme under-grading115- Bonus of up to +0.1 for semantic signal alignment116- Bonus of +0.05 for consecutive accurate gradings117 118## 🚀 Setup & Usage119 120### Run locally121 122```bash123git clone https://github.com/natarajannetworks/edueval-grading-env124cd edueval-grading-env125pip install -r requirements.txt126set PYTHONPATH=src  # Windows127# export PYTHONPATH=src  # Linux/Mac128uvicorn src.envs.grading_env.server.app:app --reload129```130 131### Run inference132 133```bash134export HF_TOKEN=your_huggingface_token135export API_BASE_URL=https://router.huggingface.co/v1136export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct137python inference.py138```139 140### Run with Docker141 142```bash143docker build -t edueval .144docker run -p 7860:7860 -e HF_TOKEN=your_token edueval145```146 147## 📊 Baseline Scores148 149Scores from running `inference.py` with `Qwen/Qwen2.5-72B-Instruct`:150 151| Task | Type | Avg Reward | Steps | Success |152|---|---|---|---|---|153| Task 1 | Factual | 0.97 | 3 | ✅ true |154| Task 2 | Conceptual | 0.88 | 3 | ✅ true |155| Task 3 | Essay | 0.77 | 3 | ✅ true |156 157## 🔗 API Endpoints158 159| Endpoint | Method | Description |160|---|---|---|161| `/reset?task_id=1` | POST | Start new episode |162| `/step?task_id=1` | POST | Submit grading action |163| `/state?task_id=1` | GET | Get current state |164| `/health` | GET | Health check |165| `/docs` | GET | Interactive API docs |166 167## 🏗️ Project Structure168 169```170edueval-grading-env/171├── inference.py              # Baseline inference script172├── Dockerfile                # Container configuration173├── requirements.txt          # Python dependencies174├── openenv.yaml             # OpenEnv metadata175└── src/176    ├── data/sample_papers/  # Question banks (10 questions each)177    │   ├── task1_easy.json  # Factual questions178    │   ├── task2_medium.json # Conceptual questions179    │   └── task3_hard.json  # Essay questions180    └── envs/grading_env/181        ├── models.py        # Pydantic models182        └── server/183            ├── app.py       # FastAPI application184            └── environment.py # Core RL environment185```