readme

README.md

@@ -14,537 +14,323 @@ tags:
   - code-review
 ---
 
-<!-- Banner -->
-<div align="center">
+# Code Review OpenEnv Benchmark
 
-# Code Review Environment
+## 🚀 Scaler March 2026 Hackathon Submission
 
-### An OpenEnv Benchmark for AI-Driven Pull-Request Review
+This project was built as part of the **Scaler March 2026 Hackathon**.
 
-[![OpenEnv](https://img.shields.io/badge/OpenEnv-compliant-blue?style=for-the-badge&logo=meta)](https://github.com/meta-pytorch/OpenEnv)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
-[![Docker](https://img.shields.io/badge/docker-ready-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com)
-[![License](https://img.shields.io/badge/license-BSD--3-green?style=for-the-badge)](LICENSE)
-
----
-
-**🚀 Scaler March 2026 Hackathon Submission**
-
-**Author:** [Dolphin-Syndrom](https://github.com/Dolphin-Syndrom) &nbsp;|&nbsp; **Type:** OpenEnv Benchmark &nbsp;|&nbsp; **Focus:** Security-Aware Code Review
-
-</div>
+**Author:** Dolphin-Syndrom  
+**Type:** OpenEnv Benchmark Environment  
+**Focus:** Evaluating LLM agents on security-aware code review tasks
 
 ---
 
 ## ⚡ TL;DR
 
-A benchmark environment that evaluates whether an LLM agent can review buggy Python code, identify security vulnerabilities and logic errors using a fixed taxonomy, and articulate its findings — just like a senior engineer doing a pull-request review.
-
-- **3 progressive tasks** — easy → medium → hard
-- **12-tag issue taxonomy** — from `null_pointer` to `timing_attack`
-- **Deterministic multi-dimensional grading** — recall + precision + articulation quality
-- **Dense reward shaping** — signal at every step, not just episode end
-- **Structured actions & observations** — typed Pydantic models with full schema
-- **Dual inference modes** — LLM-backed or rule-based fallback
-- **Deployable** via Docker on Hugging Face Spaces
-- **Fully OpenEnv compliant** — passes `openenv validate`
-
----
-
-> *Designed to evaluate whether AI agents can perform structured, taxonomy-driven code review under constrained interaction loops — a high-value, real-world software engineering workflow.*
-
----
-
-## 📑 Table of Contents
+A benchmark environment for evaluating LLM agents on taxonomy-driven pull-request reviews.
 
-- [Environment Description](#-environment-description)
-- [Why This Domain?](#-why-this-domain)
-- [Action Space](#-action-space)
-- [Observation Space](#-observation-space)
-- [Reward Function](#-reward-function)
-- [Tasks](#-tasks)
-- [Setup & Usage](#-setup--usage)
-- [Running the Baseline](#-running-the-baseline)
-- [Baseline Scores](#-baseline-scores)
-- [Deployment (HF Spaces + Docker)](#-deployment)
+- 3 tasks (easy → medium → hard)
+- structured actions and observations
+- reward-based learning signals
+- deterministic grading (0.0–1.0)
+- deployable via Docker on Hugging Face Spaces
+- fully OpenEnv compliant
 
 ---
 
-## 🧠 Environment Description
-
-This OpenEnv environment simulates a real software engineering task: **reviewing buggy Python code and identifying security and logic issues** using a fixed taxonomy of tags.
-
-Each episode presents the agent with a Python code snippet containing **planted vulnerabilities**. The agent must:
-
-1. **Identify** the issues using tags from a 12-item taxonomy
-2. **Assess** overall severity (`low` / `medium` / `high` / `critical`)
-3. **Articulate** its findings in a human-readable review comment
-
-Performance is measured by a **deterministic, multi-dimensional grader** that scores recall, penalizes false positives, and rewards articulation quality — producing a final score in `[0.0, 1.0]`.
-
-### Episode Flow
-
-```
-┌─────────┐     ┌──────────────┐     ┌────────────┐     ┌────────────┐
-│  reset() │────▶│  Observation  │────▶│  Agent Act  │────▶│  Grading   │
-│ (task_id)│     │ code_snippet  │     │ issues_found│     │ score/done │
-└─────────┘     │ file_name     │     │ comment     │     └─────┬──────┘
-                │ description   │     │ severity    │           │
-                └──────────────┘     └────────────┘     ┌─────▼──────┐
-                                                         │  Feedback   │
-                                                         │ + next obs  │
-                                                         └────────────┘
-```
-
-- `reset(task_id)` loads a task and returns the initial observation
-- `step(action)` grades the agent's review and returns `(observation, reward, done)`
-- Episode ends when score ≥ 0.95 **or** the step limit (3) is reached
+> Designed to evaluate whether AI agents can perform structured, taxonomy-driven code review under constrained interaction loops.
+>
+> Suitable for benchmarking agent performance, reward shaping strategies, and detection accuracy without hallucinating false positives.
 
-### Internal State
+This environment models a real-world engineering task: pull-request review. It evaluates whether an agent can read code snippets, identify security vulnerabilities and logic errors using a fixed taxonomy, and articulate its findings clearly.
 
-The environment tracks:
-- Current task ID, file name, and planted issues
-- Episode ID and step count
-- Maximum allowed steps (3 per episode)
+## Overview
 
-The full state is available through the OpenEnv `state()` API for debugging, but the agent **does not** observe the ground-truth issues during normal play.
+This project is designed for OpenEnv-style agent evaluation with:
 
----
-
-## 🎯 Why This Domain?
+- a real-world task instead of a toy problem
+- typed `Observation`, `Action`, `Reward`, and `State` models
+- `step()`, `reset()`, and `state()` APIs
+- three tasks with deterministic graders
+- dense reward shaping for partial progress
+- a reproducible baseline `inference.py`
+- a FastAPI server and Dockerfile for deployment
 
-| Criteria | How Code Review Fits |
-|----------|---------------------|
-| **Real-world utility** | PR review is a daily, high-value engineering workflow |
-| **RL-friendly** | Structured action space with dense rewards and a deterministic grader |
-| **Progressive difficulty** | Easy → Medium → Hard with increasing issue complexity |
-| **Measurable precision** | False positives are explicitly penalized — no reward hacking |
-| **Articulation matters** | Bonus for explaining *why* an issue exists, not just tagging it |
-| **Security relevance** | Covers OWASP-style vulnerabilities (SQLi, hardcoded secrets, timing attacks) |
+The environment models a practical workflow engineers actually do:
 
----
+- static code analysis
+- vulnerability detection
+- taxonomy-driven bug tagging
+- code review articulation
 
-## 🕹️ Action Space
+## Environment Specification
 
-The agent submits a `ReviewAction` (defined in `models.py`) with three fields:
+### Objective
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `review_comment` | `str` | Human-readable explanation of identified issues and suggested fixes |
-| `issues_found` | `list[str]` | Issue tags selected from the 12-tag `ISSUE_TAXONOMY` |
-| `severity` | `"low"` \| `"medium"` \| `"high"` \| `"critical"` | Overall severity assessment |
+For each episode, the agent sees a Python code snippet containing planted issues and must make structured decisions:
 
-### Issue Taxonomy (12 Tags)
+1. identify issues using tags from a 12-item `ISSUE_TAXONOMY` (e.g., `null_pointer`, `sql_injection`, `race_condition`)
+2. assess overall severity (`low`, `medium`, `high`, `critical`)
+3. articulate its findings in a human-readable `review_comment`
 
-```
-┌──────────────────────┬──────────────────────────┬────────────────────────┐
-│   Logic Errors       │   Security Vulns         │   Robustness           │
-├──────────────────────┼──────────────────────────┼────────────────────────┤
-│  null_pointer        │  sql_injection           │  race_condition        │
-│  missing_return      │  hardcoded_secret        │  timing_attack         │
-│  type_error          │  path_traversal          │  improper_error_       │
-│  index_out_of_bounds │  missing_input_          │    handling            │
-│                      │    validation            │  integer_overflow      │
-└──────────────────────┴──────────────────────────┴────────────────────────┘
-```
+Performance is measured two ways:
 
-### Example Action
+- dense step rewards during interaction
+- final deterministic grader scores between `0.0` and `1.0`
 
-```json
-{
-  "review_comment": "The function uses .get() for birthdate but doesn't guard against None before arithmetic. Also, the function builds a profile dict but never returns it.",
-  "issues_found": ["null_pointer", "missing_return"],
-  "severity": "high"
-}
-```
-
----
+### State
 
-## 👁️ Observation Space
+The internal environment state tracks:
 
-The agent receives a `ReviewObservation` (defined in `models.py`) after every `reset()` and `step()`:
+- current task ID, file name, and planted issues
+- episode ID and step count
+- maximum allowed steps (3 per episode)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `task_id` | `str` | Task identifier (`task_easy`, `task_medium`, `task_hard`) |
-| `file_name` | `str` | Simulated file under review (e.g., `auth.py`) |
-| `task_description` | `str` | Instructions for the agent |
-| `code_snippet` | `str` | Python source code containing planted bugs |
-| `feedback` | `str` | Grading breakdown after each step |
-| `step_number` | `int` | Current step in the episode (0-indexed) |
-| `available_issue_tags` | `list[str]` | Full taxonomy for reference |
-| `reward` | `float` | Score from the grader (0.0 – 1.0) |
-| `done` | `bool` | Whether the episode has ended |
-| `metadata` | `dict` | Diagnostics: correctly found, missed, false positives |
+The full state is available through the OpenEnv `state()` API for debugging and validation, but the agent does not directly observe the ground-truth issues during normal play.
 
----
+### Observation Space
 
-## 📊 Reward Function
+The agent receives:
 
-The environment uses a **deterministic, multi-dimensional** reward function implemented in `server/graders.py`. Agents receive dense signal at every step.
+- `task_id`
+- `file_name`
+- `task_description`
+- `code_snippet`
+- `feedback` from previous grading
+- `step_number`
+- `available_issue_tags`
 
-### Formula
+### Action Space
 
-```
-base_score       = |correctly_found ∩ planted| / |planted|
-quality_bonus    = +0.05  ×  (# correct issues with keyword match in comment)
-precision_penalty = −0.10  ×  (# false-positive issues)
+The environment accepts structured actions:
 
-final_score = clamp(base_score + quality_bonus − precision_penalty,  0.0,  1.0)
-```
+- `issues_found(list[str])` selected from the 12-tag `ISSUE_TAXONOMY`
+- `severity(level)` where `level` is one of `low`, `medium`, `high`, `critical`
+- `review_comment(text)` explaining the identified issues
 
-### Components Explained
+Invalid or hallucinated tags are penalized as false positives.
 
-| Component | Value | Purpose |
-|-----------|-------|---------|
-| **Recall Reward** | `|correct| / |planted|` | Primary signal — find what's actually broken |
-| **Quality Bonus** | `+0.05` per issue | Rewards articulation — mentioning *why* an issue matters |
-| **Precision Penalty** | `−0.10` per FP | Discourages hallucinated / over-aggressive flagging |
+### Episode Flow
 
-### Keyword Bonus Examples
+1. `reset()` loads a task and returns the initial observation
+2. the agent receives an observation with the code snippet
+3. the agent acts through `step(action)`
+4. the environment returns `(observation, reward, done, info)`
+5. the episode ends when the score ≥ 0.95 or the maximum step limit (3) is reached
 
-| Issue Tag | Triggering Keywords |
-|-----------|-------------------|
-| `sql_injection` | sql, injection, f-string, sanitize, parameterize |
-| `hardcoded_secret` | hardcoded, secret, credential, env var, plaintext |
-| `race_condition` | race, atomic, concurrent, lock, thread |
-| `timing_attack` | timing, constant time, hmac, compare_digest |
-| `improper_error_handling` | except, swallow, silent, bare except |
+## Tasks
 
-> **Design rationale:** Random or naive strategies produce low scores (missed issues + penalties). Agents must demonstrate both *detection accuracy* and *communication quality* to score well.
+### Easy Task
 
----
+Null Pointer & Missing Return.
 
-## 📝 Tasks
+- goal: evaluate `user_service.py` to catch a `.get()` missing a null check, and a missing return statement.
+- grader: weighted string-matching and set intersection
 
-Three tasks with progressive difficulty. Each task presents a different Python file with distinct planted vulnerabilities.
+### Medium Task
 
-### `task_easy` — User Service (`user_service.py`)
+SQL Injection & Hardcoded Secret.
 
-| Property | Value |
-|----------|-------|
-| **Planted Issues** | `null_pointer`, `missing_return` |
-| **Difficulty** | Easy |
-| **Description** | Review a function that uses `.get()` without null-guarding and never returns its result |
-| **Grader** | Deterministic — recall + quality bonus − FP penalty |
+- goal: evaluate `auth.py` to identify f-string SQL injection and a plaintext secret key.
+- grader: weighted string-matching and set intersection
 
-<details>
-<summary>📄 Code Snippet</summary>
+### Hard Task
 
-```python
-def get_user_age(user):
-    # Returns age in years from user profile dict
-    birthdate = user.get("birthdate")
-    if user.get("is_active"):
-        account_label = f"active:{user.get('id')}"
-    else:
-        account_label = "inactive"
+Race Condition, Error Handling & Timing Attack.
 
-    age = (datetime.now() - birthdate).days // 365
-    profile = {"label": account_label, "age": age}
-    # TODO: return something
-```
+- goal: evaluate `payments.py` for non-atomic operations, bare excepts, and non-constant-time comparisons.
+- grader: weighted string-matching and set intersection
 
-</details>
+## Reward Design
 
----
+**Summary:** Correct behavior yields positive reward (~1.0), random strategies are penalized (negative reward), ensuring meaningful learning signals.
 
-### `task_medium` — Auth Module (`auth.py`)
+The benchmark uses dense, shaped rewards so agents receive signal across the full trajectory instead of only at episode end.
 
-| Property | Value |
-|----------|-------|
-| **Planted Issues** | `sql_injection`, `hardcoded_secret` |
-| **Difficulty** | Medium |
-| **Description** | Review an authentication function with f-string SQL interpolation and a plaintext secret key |
-| **Grader** | Deterministic — recall + quality bonus − FP penalty |
+Core components:
 
-<details>
-<summary>📄 Code Snippet</summary>
+- recall reward (fractional points for correctly identified issues)
+- quality bonus (+0.05 per correct issue with a matching keyword in the comment)
+- precision penalty (-0.10 for hallucinated or false-positive issues)
 
-```python
-SECRET_KEY = "supersecret123"   # used for JWT signing
+This gives a better learning signal for agent training while the final graders still produce simple deterministic scores in the `0.0` to `1.0` range.
 
-def authenticate_user(db_conn, username, password):
-    query = f"SELECT * FROM users WHERE username='{username}' AND password='{password}'"
-    result = db_conn.execute(query)
-    user = result.fetchone()
+## Dataset
 
-    if user:
-        audit_line = f"auth ok for {username}"
-        token = jwt.encode({"user_id": user.id}, SECRET_KEY)
-        return token
-```
+The built-in dataset contains 3 distinct tasks covering a range of issues:
 
-</details>
+- `task_easy`: Logic errors (`null_pointer`, `missing_return`)
+- `task_medium`: Security vulnerabilities (`sql_injection`, `hardcoded_secret`)
+- `task_hard`: Robustness issues (`race_condition`, `improper_error_handling`, `timing_attack`)
 
----
+## Project Structure
 
-### `task_hard` — Payment Processing (`payments.py`)
-
-| Property | Value |
-|----------|-------|
-| **Planted Issues** | `race_condition`, `improper_error_handling`, `timing_attack` |
-| **Difficulty** | Hard |
-| **Description** | Review a payment function for non-atomic balance ops, silently swallowed exceptions, and non-constant-time comparisons |
-| **Grader** | Deterministic — recall + quality bonus − FP penalty |
-
-<details>
-<summary>📄 Code Snippet</summary>
-
-```python
-def process_payment(user_id, amount, card_token):
-    user = db.get_user(user_id)
-    if user.balance >= amount:
-        user.balance -= amount    # checked and modified non-atomically
-        db.save_user(user)
-
-        try:
-            charge_result = payment_gateway.charge(card_token, amount)
-        except:
-            pass  # silently swallow all payment errors
-
-        expected = db.get_token_hash(card_token)
-        actual = hash(card_token)
-        if expected == actual:    # non-constant-time comparison
-            return {"status": "success", "charge": charge_result}
+```text
+.
+├── code_review_env/
+│   ├── __init__.py
+│   ├── client.py
+│   ├── models.py
+│   ├── inference.py
+│   ├── openenv.yaml
+│   ├── pyproject.toml
+│   ├── requirements.txt
+│   ├── Dockerfile
+│   ├── README.md
+│   ├── scripts/
+│   │   └── validate-submission.sh
+│   └── server/
+│       ├── __init__.py
+│       ├── app.py
+│       ├── code_review_env_environment.py
+│       ├── graders.py
+│       ├── tasks.py
+│       ├── requirements.txt
+│       └── Dockerfile
 ```
 
-</details>
-
----
-
-## 🔧 Setup & Usage
-
-### Prerequisites
-
-- Python ≥ 3.10
-- [uv](https://github.com/astral-sh/uv) (recommended) or pip
+## Setup
 
-### Install Dependencies
+From the repository root:
 
 ```bash
-# Clone the repository
-git clone https://github.com/Dolphin-Syndrom/code-review-env.git
-cd code-review-env
-
-# Using uv (recommended)
-uv sync
-
-# Or using pip
-pip install -e .
+uv sync --frozen
+# OR using pip:
+pip install -r requirements.txt
+pip install -r server/requirements.txt
 ```
 
-### Start the Server
+## Local Usage
+
+### Start the OpenEnv server
 
 ```bash
-# Using uv
 uv run uvicorn server.app:app --host 0.0.0.0 --port 8000
-
-# Or using pip-installed packages
-uvicorn server.app:app --host 0.0.0.0 --port 8000
 ```
-
-### Verify It's Running
-
+or without uv:
 ```bash
-# Health check
-curl http://localhost:8000/health
-
-# List all tasks
-curl http://localhost:8000/tasks
-
-# Run the built-in baseline
-curl -X POST http://localhost:8000/baseline
-
-# Score a custom submission
-curl -X POST http://localhost:8000/grader \
-  -H "Content-Type: application/json" \
-  -d '{
-    "task_id": "task_easy",
-    "issues_found": ["null_pointer", "missing_return"],
-    "review_comment": "Null dereference risk on birthdate and missing return statement"
-  }'
+python -m code_review_env.server.app
 ```
 
----
-
-## 🤖 Running the Baseline
+## Baseline Inference
 
-The baseline script (`inference.py`) supports two modes and follows the **mandatory OpenEnv stdout format**.
+The baseline script uses the OpenAI Python client and reads configuration from environment variables:
 
-### Environment Variables
+- `API_BASE_URL`
+- `MODEL_NAME`
+- `HF_TOKEN`
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `API_BASE_URL` | No | `https://router.huggingface.co/v1` | LLM API endpoint |
-| `MODEL_NAME` | No | `Qwen/Qwen2.5-72B-Instruct` | Model identifier |
-| `HF_TOKEN` | For LLM mode | — | Hugging Face / API key |
-| `ENV_URL` | No | `http://localhost:8000` | Environment server URL |
-| `IMAGE_NAME` | No | — | Docker image name (if using `from_docker_image()`) |
-
-### Run Locally
+Example:
 
 ```bash
-# Rule-based fallback (no API key needed)
-python inference.py
-
-# LLM-backed mode
-API_BASE_URL=https://router.huggingface.co/v1 \
-MODEL_NAME=Qwen/Qwen2.5-72B-Instruct \
-HF_TOKEN=hf_your_token_here \
+export API_BASE_URL=https://router.huggingface.co/v1
+export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
+export HF_TOKEN=your-token
 python inference.py
-
-# Against a deployed HF Space
-ENV_URL=https://your-space.hf.space python inference.py
 ```
 
-### Structured Stdout Output (Mandatory)
-
-The script emits exactly three line types for the OpenEnv validator:
-
-```
-[START] task=task_easy env=code_review_env model=Qwen/Qwen2.5-72B-Instruct
-[STEP]  step=1 action={"issues_found":["null_pointer","missing_return"],...} reward=1.00 done=true error=null
-[END]   success=true steps=1 score=1.000 rewards=1.00
-```
-
-**Rules:**
-- One `[START]` at episode begin
-- One `[STEP]` per step, immediately after `env.step()` returns
-- One `[END]` after episode completes (always emitted, even on exception)
-- `reward` and `rewards` formatted to 2 decimal places
-- `done` and `success` are lowercase booleans
-- Each task score must be in `(0.0, 1.0)` — strictly between, not exactly 0 or 1
-
----
-
-## 📈 Baseline Scores
-
-Performance of the built-in rule-based baseline (no LLM required):
+Behavior:
 
-| Task | Difficulty | Issues Detected | Score |
-|------|-----------|----------------|-------|
-| `task_easy` | 🟢 Easy | `null_pointer`, `missing_return` | **1.00** |
-| `task_medium` | 🟡 Medium | `sql_injection`, `hardcoded_secret` | **1.00** |
-| `task_hard` | 🔴 Hard | `race_condition`, `timing_attack`, `improper_error_handling` | **1.00** |
+- tries an LLM-backed agent first
+- falls back to deterministic heuristics when credentials or network access are unavailable
+- emits structured `[START]`, `[STEP]`, and `[END]` logs
+- safely handles rate-limit and transient LLM errors
 
-> The rule-based baseline uses pattern-matching heuristics (e.g., detecting `.get(` for null pointers, `f"select` for SQL injection). LLM agents are expected to **match or exceed** these scores while providing richer, more actionable review comments.
+## Validation
 
----
+```bash
+openenv validate .
+./scripts/validate-submission.sh http://localhost:8000 .
+```
 
-## 🚀 Deployment
+## 🔌 API Usage
 
-### Docker
+All endpoints are OpenEnv-compatible and return structured JSON responses.
 
-```bash
-# Build
-docker build -t code-review-env:latest .
+### Health Check
+GET /health
 
-# Run
-docker run -p 8000:8000 code-review-env:latest
+### Reset Environment
+POST /reset  
+Optional body:
+```json
+{"task_id": "task_easy"}
 ```
 
-### Hugging Face Spaces
+### Take Step
 
-This repo is structured for Docker-based deployment to HF Spaces.
+POST /step
+Body:
 
-```bash
-# Using the OpenEnv CLI
-openenv push --repo-id Dolphin-Syndrom/code-review-env
+```json
+{
+  "review_comment": "Null dereference risk on birthdate.",
+  "issues_found": ["null_pointer"],
+  "severity": "medium"
+}
 ```
 
-**Recommended Space Settings:**
-- **SDK:** Docker
-- **Hardware:** CPU Basic (sufficient)
-- **Secrets:** Set `API_BASE_URL`, `MODEL_NAME`, `HF_TOKEN` if you want LLM baseline enabled
+### Get State
 
-### Pre-Validation
+GET /state
 
-Run the validation script before submitting:
+## Docker
+
+Build and run:
 
 ```bash
-./scripts/validate-submission.sh https://Dolphin-Syndrom-code-review-env.hf.space .
+docker build -t code-review-openenv -f Dockerfile .
+docker run -p 8000:8000 code-review-openenv
 ```
 
----
+## Hugging Face Spaces
 
-## 🔌 API Reference
+This repo is structured for Docker-based deployment to Hugging Face Spaces.
 
-All endpoints are OpenEnv-compatible and return structured JSON.
+Recommended setup:
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/health` | Health check |
-| `GET` | `/tasks` | List all tasks with schemas |
-| `POST` | `/reset` | Reset episode for a given task |
-| `POST` | `/step` | Submit a review action |
-| `GET` | `/state` | Get current episode state |
-| `POST` | `/grader` | Score an action against a task |
-| `POST` | `/baseline` | Run built-in rule-based baseline across all tasks |
-| `WS` | `/ws` | WebSocket for real-time interaction |
+- SDK: `Docker`
+- hardware: CPU Basic is sufficient
+- set `API_BASE_URL`, `MODEL_NAME`, and `HF_TOKEN` in Space secrets if you want the LLM baseline enabled
 
----
+## 🏁 Submission Status
 
-## 📁 Project Structure
+This environment:
 
-```
-code-review-env/
-├── __init__.py                          # Package exports
-├── client.py                            # CodeReviewEnv — WebSocket client (EnvClient subclass)
-├── models.py                            # ReviewAction, ReviewObservation, ReviewState, ISSUE_TAXONOMY
-├── inference.py                         # Baseline inference (LLM + rule-based fallback)
-├── openenv.yaml                         # OpenEnv manifest with grader blocks
-├── pyproject.toml                       # Project metadata & dependencies
-├── Dockerfile                           # Production container
-├── README.md
-├── scripts/
-│   └── validate-submission.sh           # Pre-submission validator
-└── server/
-    ├── __init__.py
-    ├── app.py                           # FastAPI server + Gradio dashboard
-    ├── code_review_env_environment.py   # Environment implementation (reset/step/state)
-    ├── graders.py                       # Deterministic grading logic
-    ├── tasks.py                         # Task definitions with planted issues
-    ├── requirements.txt
-    └── Dockerfile
-```
+- passes OpenEnv validation
+- successfully deploys via Docker on Hugging Face Spaces
+- supports full agent interaction through API endpoints
+- was tested end-to-end including inference and grading pipeline
 
----
+Built, debugged, and deployed under hackathon constraints.
 
-## 🏁 Submission Checklist
-
-| # | Check | Status |
-|---|-------|--------|
-| 1 | Docker build succeeds | ✅ |
-| 2 | `POST /reset` returns 200 | ✅ |
-| 3 | 3 tasks with `grader:` blocks in `openenv.yaml` | ✅ |
-| 4 | `inference.py` exits with code 0 | ✅ |
-| 5 | `[START]`, `[STEP]`, `[END]` in stdout | ✅ |
-| 6 | LLM calls via `API_BASE_URL` proxy | ✅ |
-| 7 | All task scores strictly in `(0.0, 1.0)` | ✅ |
+---
 
-### Submission Links (Both Required)
+## 🔗 Links
 
-1. **GitHub Repository:** [Dolphin-Syndrom/code-review-env](https://github.com/Dolphin-Syndrom/code-review-env)
-2. **Hugging Face Space:** [Dolphin-Syndrom/code-review-env](https://huggingface.co/spaces/Dolphin-Syndrom/code-review-env)
+- GitHub Repository: https://github.com/Dolphin-Syndrom/code-review-env
+- Hugging Face Space: https://huggingface.co/spaces/Dolphin-Syndrom/code-review-env
 
----
+## Why This Environment Fits The Problem Statement
 
-## 🔮 Extensibility
+- real-world utility: code review is a practical daily workflow
+- three tasks with deterministic graders: easy, medium, hard
+- meaningful reward shaping: partial progress, articulation bonuses, and hallucination penalties
+- OpenEnv-compatible API and typed models
+- baseline inference script included at repo root
+- containerization included for deployment
 
-Possible next steps for this benchmark:
+## Extensibility
 
-- **More languages** — Extend beyond Python to JavaScript, Go, Rust
-- **Multi-file reviews** — Cross-file dependency analysis
-- **Diff-based input** — Review git diffs instead of full files
-- **Severity grading** — Score severity accuracy, not just issue detection
-- **Exploit generation** — Ask agents to produce PoC exploits for found vulnerabilities
-- **Agentic tool use** — Let agents run linters, type checkers, or tests as sub-actions
-
----
+Possible next steps:
 
-<div align="center">
+- more languages such as JavaScript, Go, or Rust
+- multi-file reviews and cross-file dependency analysis
+- diff-based input instead of full files
+- severity grading accuracy
+- target exploit generation
 
-**Built with [OpenEnv](https://github.com/meta-pytorch/OpenEnv) by Meta** &nbsp;·&nbsp; **Deployed on [Hugging Face Spaces](https://huggingface.co/spaces)**
+## License
 
-</div>
+BSD-3-Clause