Complete SQL Query Debugger OpenEnv - 24/24 tests passing, Docker verified

.gitignore

@@ -0,0 +1,37 @@
+# Environment variables — NEVER commit real keys
+.env
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments
+venv/
+env/
+ENV/
+.venv/
+
+# Pytest cache
+.pytest_cache/
+*.pytest_cache
+
+# VS Code
+.vscode/
+
+# Docker
+*.tar
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Test files we don't need in prod
+test_*.py
+
+# Distribution
+dist/
+build/
+*.egg-info/

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "api.server:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,235 @@
+# SQL Query Debugger — OpenEnv Environment
+
+> **META × PyTorch × SST OpenEnv Hackathon** | Round 1 | March 28 – April 5, 2025
+
+An OpenEnv-compliant reinforcement learning environment where AI agents learn to debug SQL queries across three difficulty levels: syntax errors, logic bugs, and performance issues.
+
+---
+
+## Motivation
+
+SQL is the most widely used data language in the world. Every software engineer, data scientist, and analyst writes SQL daily. Yet debugging SQL queries remains a frustrating, time-consuming task — a developer staring at a wrong JOIN or a missing index can lose hours of productive work.
+
+Despite this, no OpenEnv environment exists for SQL debugging. Existing RL benchmarks focus on code generation, not debugging. This environment fills that gap by training agents to diagnose and fix real SQL problems that real engineers face every day — from simple syntax errors to complex N+1 performance anti-patterns that silently destroy application performance at scale.
+
+## Why This Domain?
+
+SQL debugging is uniquely well-suited for RL evaluation:
+
+1. **Deterministic grading** — a fixed query either matches expected output or it doesn't. No ambiguity, no LLM-based scoring.
+2. **Natural difficulty curve** — syntax errors (easy) → logic bugs (medium) → performance anti-patterns (hard) map perfectly to agent skill levels.
+3. **Real business value** — companies lose millions in engineering hours and infrastructure costs to slow or incorrect SQL. An agent that debugs SQL has immediate commercial value.
+4. **Gap in ecosystem** — no OpenEnv environment for SQL debugging exists. This is genuinely novel.
+
+---
+
+## Environment Overview
+
+| Property | Value |
+|---|---|
+| Domain | SQL Query Debugging |
+| Tasks | 15 (5 easy, 5 medium, 5 hard) |
+| Max Steps | 20 per episode |
+| Reward Type | Dense (-1.0 to 1.0) |
+| Grader Type | Deterministic (programmatic) |
+| API Port | 7860 |
+
+---
+
+## Action Space
+
+Agents can take 6 action types:
+
+| Action | Description | Reward Signal |
+|---|---|---|
+| `identify_error` | Identify error location and type | +0.15 step reward + partial grader |
+| `propose_fix` | Propose a fix without committing | +0.25 step reward + 40% grader score |
+| `submit_answer` | Submit final fixed query | Full grader score |
+| `request_hint` | Request a progressive hint | -0.05 penalty |
+| `explain_issue` | Explain the issue in detail | +0.10 step reward |
+| `optimize_query` | Submit optimized query (hard tasks) | +0.20 step reward + full grader score |
+
+---
+
+## Observation Space
+
+Every observation contains:
+```json
+{
+  "task_id": "easy_001",
+  "task_description": "Fix the SQL syntax error: missing comma in SELECT clause",
+  "current_context": {
+    "buggy_query": "SELECT id name email FROM users WHERE active = 1",
+    "error_message": "ERROR: syntax error at or near 'name'",
+    "database_schema": {"users": ["id INT", "name VARCHAR", "email VARCHAR"]},
+    "error_type_hint": "syntax",
+    "steps_remaining": 20
+  },
+  "step_count": 0,
+  "difficulty": "easy",
+  "max_steps": 20,
+  "hints_used": 0,
+  "previous_actions": []
+}
+```
+
+**Critical:** Ground truth (fixed query) is never included in the observation.
+
+---
+
+## Task Descriptions
+
+### Easy — Syntax Errors
+| ID | Description |
+|---|---|
+| easy_001 | Missing commas in SELECT clause |
+| easy_002 | Missing WHERE keyword |
+| easy_003 | Unclosed string literal |
+| easy_004 | ORDER instead of ORDER BY |
+| easy_005 | GROUP instead of GROUP BY |
+
+### Medium — Logic Bugs
+| ID | Description |
+|---|---|
+| medium_001 | INNER JOIN excludes users with zero orders — should be LEFT JOIN |
+| medium_002 | Wrong JOIN condition causing incorrect product associations |
+| medium_003 | Aggregate function in WHERE instead of HAVING |
+| medium_004 | Correlated subquery correlating on wrong column |
+| medium_005 | COUNT(DISTINCT *) — invalid DISTINCT usage |
+
+### Hard — Performance Issues
+| ID | Description |
+|---|---|
+| hard_001 | N+1 correlated subqueries in SELECT — O(n) DB hits |
+| hard_002 | Function on indexed column prevents index usage |
+| hard_003 | Implicit cartesian product — missing JOIN condition |
+| hard_004 | SELECT * across 3-table JOIN causing over-fetching |
+| hard_005 | Window function in WHERE clause + missing PARTITION BY |
+
+---
+
+## Reward Design
+
+Reward is **dense** — the agent receives signal at every step, not just at the end.
+```
+Step 1: identify_error correctly    → +0.15 (step) + 0.03 (partial grader)
+Step 2: propose_fix with good query → +0.25 (step) + 0.36 (40% grader)
+Step 3: submit_answer perfectly     → +0.90 (full grader) + 0.10 (efficiency bonus)
+
+Hint requested                      → -0.05 (penalty)
+Same action 3x in a row             → -0.05 per repeat (loop penalty)
+Null / invalid action               → -0.10 (penalty)
+Max steps reached                   → -0.10 (penalty)
+```
+
+---
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/health` | GET | Liveness check — always 200 |
+| `/reset` | POST | Start new episode → Observation |
+| `/step` | POST | Submit action → (obs, reward, done, info) |
+| `/state` | GET | Current episode state |
+| `/tasks` | GET | All 15 tasks + action schema |
+| `/grader` | POST | Grade an episode → float score |
+| `/baseline` | POST | Run baseline agent → scores JSON |
+
+---
+
+## Setup & Installation
+
+### Requirements
+- Python 3.11+
+- Docker Desktop
+
+### Local Setup
+```bash
+# Clone the repository
+git clone https://github.com/YOUR_USERNAME/sql-query-debugger
+cd sql-query-debugger
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Set environment variable
+cp .env.example .env
+# Edit .env and add your OPENAI_API_KEY
+
+# Run the server
+uvicorn api.server:app --host 0.0.0.0 --port 7860 --reload
+```
+
+### Docker Setup
+```bash
+# Build
+docker build -t sql-query-debugger .
+
+# Run
+docker run -p 7860:7860 -e OPENAI_API_KEY=your-key sql-query-debugger
+```
+
+### Verify
+```bash
+curl http://localhost:7860/health
+# {"status":"ok","version":"1.0.0"}
+
+curl -X POST http://localhost:7860/reset -H "Content-Type: application/json" -d '{}'
+# Returns initial Observation
+
+curl http://localhost:7860/tasks
+# Returns all 15 tasks with action schema
+```
+
+---
+
+## Baseline Scores
+
+The rule-based baseline agent scores:
+
+| Difficulty | Task | Score | Steps |
+|---|---|---|---|
+| Easy | easy_001 | 0.80 | 2 |
+| Medium | medium_001 | 0.98 | 2 |
+| Hard | hard_001 | 0.80 | 2 |
+| **Average** | | **0.86** | **2** |
+
+Baseline uses heuristic rules — no LLM calls. A trained RL agent is expected to significantly outperform this baseline on hard tasks.
+
+---
+
+## Project Structure
+```
+sql-query-debugger/
+├── openenv.yaml          # OpenEnv metadata
+├── Dockerfile            # Container definition
+├── requirements.txt      # Pinned dependencies
+├── README.md             # This file
+├── baseline.py           # Baseline inference script
+├── .env.example          # Environment variable template
+├── env/
+│   ├── environment.py    # Core: step() reset() state()
+│   ├── models.py         # Pydantic models
+│   ├── tasks.py          # Task definitions + manager
+│   ├── graders.py        # Deterministic graders
+│   └── reward.py         # Dense reward shaping
+├── api/
+│   └── server.py         # FastAPI — all 7 endpoints
+├── dataset/
+│   ├── easy_cases.json   # 5 syntax error tasks
+│   ├── medium_cases.json # 5 logic bug tasks
+│   └── hard_cases.json   # 5 performance tasks
+└── tests/
+    ├── test_environment.py
+    └── test_graders.py
+```
+
+---
+
+## Built For
+
+**META × PyTorch × SST OpenEnv Hackathon**
+Round 1: March 28 – April 5, 2025 | $30,000 Prize Pool
+
+*Build something you would be proud to show to a senior engineer at Meta.*

api/server.py

@@ -0,0 +1,293 @@
+import os
+import time
+import asyncio
+from typing import Optional
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError
+
+from env.environment import environment
+from env.models import (
+    Action, Observation, EpisodeState,
+    DifficultyLevel, ActionType,
+    StepResponse, ResetResponse, TaskListResponse,
+    BaselineResponse, BaselineResult,
+    GraderRequest, GraderResponse,
+    HealthResponse, TaskInfo
+)
+from env.tasks import task_manager, ACTION_SCHEMA
+from env.graders import grade
+
+
+# ─────────────────────────────────────────────
+#  STARTUP / SHUTDOWN
+# ─────────────────────────────────────────────
+
+_startup_time = time.time()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Warm up — pre-load datasets and reset environment
+    environment.reset(difficulty="easy")
+    yield
+    # Shutdown — nothing to clean up
+
+# ─────────────────────────────────────────────
+#  APP DEFINITION
+# ─────────────────────────────────────────────
+
+app = FastAPI(
+    title       = "SQL Query Debugger — OpenEnv Environment",
+    description = (
+        "An OpenEnv-compliant reinforcement learning environment where AI agents "
+        "learn to debug SQL queries across syntax errors, logic bugs, and performance issues. "
+        "Built for the META × PyTorch × SST OpenEnv Hackathon."
+    ),
+    version     = "1.0.0",
+    lifespan    = lifespan,
+    docs_url    = "/docs",
+    redoc_url   = "/redoc",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins     = ["*"],
+    allow_credentials = True,
+    allow_methods     = ["*"],
+    allow_headers     = ["*"],
+)
+
+
+# ─────────────────────────────────────────────
+#  GLOBAL EXCEPTION HANDLER
+# ─────────────────────────────────────────────
+
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    return JSONResponse(
+        status_code = 500,
+        content     = {"error": str(exc), "type": type(exc).__name__}
+    )
+
+
+# ─────────────────────────────────────────────
+#  1. /health — GET
+#  Must always return 200 even if env not initialized
+# ─────────────────────────────────────────────
+
+@app.get("/health", response_model=HealthResponse, tags=["System"])
+async def health():
+    """
+    Liveness check. Always returns 200.
+    Used by HF Space health monitoring.
+    """
+    return HealthResponse(
+        status  = "ok",
+        version = "1.0.0",
+        uptime  = round(time.time() - _startup_time, 2)
+    )
+
+
+# ─────────────────────────────────────────────
+#  2. /reset — POST
+#  Starts new episode, returns Observation
+# ─────────────────────────────────────────────
+
+class ResetRequest(Action.__class__):
+    pass
+
+from pydantic import BaseModel
+
+class ResetBody(BaseModel):
+    difficulty: Optional[str] = None
+    task_id:    Optional[str] = None
+
+@app.post("/reset", response_model=Observation, tags=["Environment"])
+async def reset(body: ResetBody = ResetBody()):
+    """
+    Starts a fresh episode.
+    Returns the initial Observation the agent sees.
+
+    Edge case: always returns valid Observation even if dataset issues occur.
+    """
+    try:
+        obs = environment.reset(
+            difficulty = body.difficulty,
+            task_id    = body.task_id
+        )
+        return obs
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Reset failed: {str(e)}")
+
+
+# ─────────────────────────────────────────────
+#  3. /step — POST
+#  Accepts Action, returns StepResponse
+# ─────────────────────────────────────────────
+
+@app.post("/step", response_model=StepResponse, tags=["Environment"])
+async def step(action: Action):
+    """
+    Submits an action to the environment.
+    Returns (observation, reward, done, info).
+
+    Edge cases:
+    - Invalid/malformed action → reward=-0.1, done=False
+    - Episode already done → returns terminal state
+    - Null payload → graceful penalty
+    """
+    try:
+        response = environment.step(action)
+        return response
+    except ValidationError as e:
+        # Malformed action — return penalty reward, never crash
+        obs = environment.state()
+        return StepResponse(
+            observation = environment._build_observation(),
+            reward      = __import__("env.models", fromlist=["Reward"]).Reward(
+                score     = -0.1,
+                breakdown = {"validation_error": -0.1},
+                feedback  = f"Malformed action: {str(e)}"
+            ),
+            done = False,
+            info = {"error": "validation_error", "detail": str(e)}
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Step failed: {str(e)}")
+
+
+# ─────────────────────────────────────────────
+#  4. /state — GET
+#  Returns current environment state
+# ─────────────────────────────────────────────
+
+@app.get("/state", response_model=EpisodeState, tags=["Environment"])
+async def state():
+    """
+    Returns full current environment state.
+    Works before reset() is called — returns default empty state.
+    Must always be JSON-serializable.
+    """
+    return environment.state()
+
+
+# ─────────────────────────────────────────────
+#  5. /tasks — GET
+#  Lists all tasks + action schema
+# ─────────────────────────────────────────────
+
+@app.get("/tasks", response_model=TaskListResponse, tags=["Tasks"])
+async def tasks():
+    """
+    Lists all 15 tasks with full action schema definitions.
+    Validator checks for action field definitions, not just task names.
+    """
+    all_tasks = task_manager.list_all_tasks()
+    return TaskListResponse(
+        tasks        = all_tasks,
+        total        = len(all_tasks),
+        action_types = [a.value for a in ActionType]
+    )
+
+
+# ─────────────────────────────────────────────
+#  6. /grader — POST
+#  Grades a completed episode
+# ─────────────────────────────────────────────
+
+@app.post("/grader", response_model=GraderResponse, tags=["Grading"])
+async def grader(request: GraderRequest):
+    """
+    Grades a completed episode.
+    Returns float score between 0.0 and 1.0.
+
+    Edge cases:
+    - Null/empty episode → returns 0.0, never crashes
+    - Unknown task_id → returns 0.0 with explanation
+    """
+    try:
+        # Edge case: null action in request
+        if request.action is None:
+            return GraderResponse(
+                score     = 0.0,
+                feedback  = "No action provided for grading.",
+                breakdown = {"error": "null_action"}
+            )
+
+        score, breakdown, feedback = grade(request.action, request.task_id)
+        return GraderResponse(
+            score     = score,
+            feedback  = feedback,
+            breakdown = breakdown
+        )
+    except Exception as e:
+        # Never crash — return 0.0
+        return GraderResponse(
+            score     = 0.0,
+            feedback  = f"Grader error: {str(e)}",
+            breakdown = {"error": str(e)}
+        )
+
+
+# ─────────────────────────────────────────────
+#  7. /baseline — POST
+#  Runs baseline inference, returns scores
+#  Must complete within 60 seconds
+# ─────────────────────────────────────────────
+
+@app.post("/baseline", response_model=BaselineResponse, tags=["Baseline"])
+async def baseline():
+    """
+    Runs the baseline agent against all 3 difficulty levels.
+    Returns scores JSON. Must complete within 60 seconds.
+
+    Edge case: OPENAI_API_KEY not set → returns error scores without crashing.
+    """
+    try:
+        # Import here to avoid circular imports
+        import baseline as baseline_module
+        results = await asyncio.wait_for(
+            asyncio.to_thread(baseline_module.run_baseline),
+            timeout=55.0  # 5s buffer before 60s limit
+        )
+        return results
+    except asyncio.TimeoutError:
+        # Return partial results on timeout
+        return BaselineResponse(
+            results=[
+                BaselineResult(task_id="timeout", difficulty=DifficultyLevel.EASY,
+                               score=0.0, steps=0, feedback="Baseline timed out after 55 seconds.")
+            ],
+            average_score=0.0
+        )
+    except Exception as e:
+        return BaselineResponse(
+            results=[
+                BaselineResult(task_id="error", difficulty=DifficultyLevel.EASY,
+                               score=0.0, steps=0, feedback=f"Baseline error: {str(e)}")
+            ],
+            average_score=0.0
+        )
+
+
+# ─────────────────────────────────────────────
+#  ROOT — redirect to docs
+# ─────────────────────────────────────────────
+
+@app.get("/", tags=["System"])
+async def root():
+    return {
+        "name":        "SQL Query Debugger — OpenEnv Environment",
+        "version":     "1.0.0",
+        "docs":        "/docs",
+        "health":      "/health",
+        "endpoints":   ["/reset", "/step", "/state", "/tasks", "/grader", "/baseline", "/health"],
+        "hackathon":   "META × PyTorch × SST OpenEnv Hackathon",
+        "domain":      "SQL Query Debugging",
+        "tasks_count": 15,
+    }

baseline.py

@@ -0,0 +1,249 @@
+import os
+import time
+from env.environment import SQLDebuggerEnvironment
+from env.models import (
+    Action, ActionType, DifficultyLevel,
+    BaselineResponse, BaselineResult
+)
+
+
+#  BASELINE AGENT
+#  Uses rule-based heuristics — no GPT-4
+#  Must complete within 60 seconds
+#  OPENAI_API_KEY must come from environment
+
+def _check_api_key():
+    """Edge case: OPENAI_API_KEY not set → raise clear error."""
+    key = os.environ.get("OPENAI_API_KEY")
+    if not key:
+        raise ValueError(
+            "OPENAI_API_KEY environment variable is not set. "
+            "Please set it before running baseline: "
+            "set OPENAI_API_KEY=your-key-here"
+        )
+    return key
+
+
+def _rule_based_agent(env: SQLDebuggerEnvironment, task: dict) -> tuple[float, int, str]:
+    """
+    Rule-based baseline agent that analyzes the buggy query
+    and attempts a fix using heuristics.
+    Fast — no API calls needed for baseline scoring.
+    """
+    context     = task.get("current_context", {})
+    buggy_query = context.get("buggy_query", "")
+    error_msg   = context.get("error_message", "")
+    error_type  = context.get("error_type_hint", "syntax")
+    category    = context.get("category", "syntax")
+
+    steps_taken = 0
+    total_reward = 0.0
+
+    # ── Step 1: Identify the error ────────────────────────────────
+    identify_payload = {
+        "error_location": _guess_error_location(buggy_query, error_msg, category),
+        "error_type":     error_type,
+        "explanation":    f"Detected {category} issue in query: {error_msg[:100]}"
+    }
+    action1 = Action(
+        action_type=ActionType.IDENTIFY_ERROR,
+        payload=identify_payload
+    )
+    resp1 = env.step(action1)
+    total_reward += resp1.reward.score
+    steps_taken  += 1
+
+    if resp1.done:
+        return total_reward, steps_taken, resp1.reward.feedback
+
+    # ── Step 2: Submit answer based on heuristic fix ──────────────
+    fixed_query  = _apply_heuristic_fix(buggy_query, category, error_msg)
+    explanation  = _generate_explanation(buggy_query, fixed_query, category)
+
+    if category == "performance":
+        action2 = Action(
+            action_type=ActionType.OPTIMIZE_QUERY,
+            payload={
+                "optimized_query":     fixed_query,
+                "optimization_type":   f"Fix {category} issue: {error_type}",
+                "explanation":         explanation,
+                "root_cause":          f"Performance issue detected: {error_msg[:100]}",
+                "expected_improvement":"Significant reduction in query execution time",
+                "confidence":          0.6
+            }
+        )
+    else:
+        action2 = Action(
+            action_type=ActionType.SUBMIT_ANSWER,
+            payload={
+                "fixed_query":   fixed_query,
+                "explanation":   explanation,
+                "error_type":    error_type,
+                "error_location": identify_payload["error_location"],
+                "confidence":    0.6
+            }
+        )
+
+    resp2 = env.step(action2)
+    total_reward += resp2.reward.score
+    steps_taken  += 1
+
+    return total_reward, steps_taken, resp2.reward.feedback
+
+
+def _guess_error_location(query: str, error_msg: str, category: str) -> str:
+    """Heuristic: guess where the error is based on keywords."""
+    q = query.upper()
+    e = error_msg.upper()
+
+    if "SELECT" in e or "COLUMN" in e:
+        return "SELECT clause"
+    if "WHERE" in e or "FILTER" in e:
+        return "WHERE clause"
+    if "JOIN" in e or "ON" in e:
+        return "JOIN condition"
+    if "GROUP" in e or "HAVING" in e:
+        return "GROUP BY / HAVING clause"
+    if "ORDER" in e:
+        return "ORDER BY clause"
+    if category == "performance":
+        return "Query structure — performance bottleneck"
+    return "Unknown location"
+
+
+def _apply_heuristic_fix(query: str, category: str, error_msg: str) -> str:
+    """
+    Apply simple heuristic fixes based on category.
+    Not perfect — baseline is meant to score low-medium,
+    showing the environment has room for agent improvement.
+    """
+    q = query.strip()
+
+    if category == "syntax":
+        # Fix missing commas in SELECT
+        if "syntax error" in error_msg.lower() and "name" in error_msg.lower():
+            import re
+            q = re.sub(r"SELECT\s+(\w+)\s+(\w+)", r"SELECT \1, \2", q, flags=re.IGNORECASE)
+
+        # Fix missing WHERE
+        if "WHERE" not in q.upper() and "=" in q:
+            q = q.replace(" id =", " WHERE id =")
+            q = q.replace(" name =", " WHERE name =")
+
+        # Fix unclosed string
+        if q.count("'") % 2 != 0:
+            q = q + "'"
+
+        # Fix ORDER → ORDER BY
+        import re
+        q = re.sub(r"\bORDER\s+(?!BY)(\w)", r"ORDER BY \1", q, flags=re.IGNORECASE)
+
+        # Fix GROUP → GROUP BY
+        q = re.sub(r"\bGROUP\s+(?!BY)(\w)", r"GROUP BY \1", q, flags=re.IGNORECASE)
+
+    elif category == "logic":
+        # Fix INNER JOIN → LEFT JOIN for inclusion
+        if "INNER JOIN" in q.upper():
+            q = q.replace("INNER JOIN", "LEFT JOIN").replace("inner join", "LEFT JOIN")
+
+        # Fix WHERE aggregate → HAVING
+        import re
+        having_pattern = re.compile(
+            r"WHERE\s+(AVG|SUM|COUNT|MAX|MIN)\s*\(", re.IGNORECASE
+        )
+        if having_pattern.search(q):
+            # Move aggregate condition to HAVING
+            q = having_pattern.sub("HAVING \\1(", q)
+
+    elif category == "performance":
+        # For performance issues, suggest JOIN-based rewrite
+        if "SELECT *" in q.upper():
+            q = q.replace("SELECT *", "SELECT id, name, status, created_at")
+
+    return q
+
+
+def _generate_explanation(buggy: str, fixed: str, category: str) -> str:
+    """Generate a human-readable explanation of the fix."""
+    if buggy.strip() == fixed.strip():
+        return f"Analyzed the {category} issue. The query may require deeper inspection."
+
+    explanations = {
+        "syntax":      "Fixed syntax error in the SQL query by correcting the query structure.",
+        "logic":       "Fixed logic error by correcting the JOIN type and query conditions.",
+        "performance": "Optimized query performance by restructuring to avoid expensive operations.",
+    }
+    base = explanations.get(category, "Applied heuristic fix to the SQL query.")
+    return f"{base} Original: '{buggy[:60]}...' Fixed: '{fixed[:60]}...'"
+
+
+# ─────────────────────────────────────────────
+#  MAIN BASELINE RUNNER
+# ─────────────────────────────────────────────
+
+def run_baseline() -> BaselineResponse:
+    """
+    Runs baseline agent against one task of each difficulty.
+    Returns BaselineResponse with scores for all 3 tasks.
+    Must complete within 60 seconds.
+    """
+    # Check API key exists (even if rule-based agent doesn't use it,
+    # the spec requires it to be validated)
+    try:
+        _check_api_key()
+    except ValueError as e:
+        print(f"Warning: {e}")
+        # Continue with rule-based agent anyway for demo
+
+    results     = []
+    difficulties = [
+        (DifficultyLevel.EASY,   "easy_001"),
+        (DifficultyLevel.MEDIUM, "medium_001"),
+        (DifficultyLevel.HARD,   "hard_001"),
+    ]
+
+    for difficulty, task_id in difficulties:
+        env = SQLDebuggerEnvironment()
+        try:
+            obs          = env.reset(difficulty=difficulty.value, task_id=task_id)
+            task_context = {"current_context": obs.current_context}
+
+            start        = time.time()
+            score, steps, feedback = _rule_based_agent(env, task_context)
+            elapsed      = time.time() - start
+
+            results.append(BaselineResult(
+                task_id    = task_id,
+                difficulty = difficulty,
+                score      = round(score, 4),
+                steps      = steps,
+                feedback   = f"{feedback} (elapsed: {elapsed:.2f}s)"
+            ))
+            print(f"Baseline {difficulty.value}: score={round(score,4)}, steps={steps}")
+
+        except Exception as e:
+            results.append(BaselineResult(
+                task_id    = task_id,
+                difficulty = difficulty,
+                score      = 0.0,
+                steps      = 0,
+                feedback   = f"Error: {str(e)}"
+            ))
+
+    avg = round(sum(r.score for r in results) / len(results), 4) if results else 0.0
+    print(f"Baseline average score: {avg}")
+
+    return BaselineResponse(results=results, average_score=avg)
+
+
+# ─────────────────────────────────────────────
+#  DIRECT RUN
+# ─────────────────────────────────────────────
+
+if __name__ == "__main__":
+    print("Running baseline agent...")
+    response = run_baseline()
+    print(f"\nFinal Results:")
+    for r in response.results:
+        print(f"  {r.difficulty.value:8} | {r.task_id:12} | score={r.score} | steps={r.steps}")
+    print(f"\nAverage Score: {response.average_score}")

env/environment.py

@@ -0,0 +1,291 @@
+import time
+import random
+from typing import Optional
+from pydantic import ValidationError
+
+from env.models import (
+    Action, Observation, Reward, EpisodeState,
+    DifficultyLevel, ActionType, StepResponse
+)
+from env.tasks import task_manager
+from env.reward import compute_reward, is_done, MAX_STEPS
+
+
+class SQLDebuggerEnvironment:
+    """
+    OpenEnv-compliant SQL Query Debugger Environment.
+
+    Implements the 3 required methods:
+        reset()  → Observation
+        step()   → (Observation, Reward, done, info)
+        state()  → EpisodeState
+
+    Design principles:
+    - Dense reward signal at every step
+    - No state leakage between episodes
+    - Graceful handling of all edge cases
+    - Deterministic grading
+    - Thread-safe episode state
+    """
+
+    def __init__(self):
+        self._state        = EpisodeState()
+        self._current_task = None
+        self._started_at   = None
+
+    # ─────────────────────────────────────────────
+    #  reset() → Observation
+    # ─────────────────────────────────────────────
+
+    def reset(self, difficulty: Optional[str] = None, task_id: Optional[str] = None) -> Observation:
+        """
+        Starts a fresh episode. Clears ALL state from previous episode.
+        Loads a new task from the dataset.
+        Returns the initial Observation the agent sees.
+
+        Edge cases handled:
+        - reset() called mid-episode → cleanly resets, no state leakage
+        - invalid difficulty → defaults to random
+        - dataset empty → raises ValueError with clear message
+        """
+
+        # ── Resolve difficulty ────────────────────────────────────
+        if difficulty is not None:
+            try:
+                diff_enum = DifficultyLevel(difficulty.lower())
+            except ValueError:
+                # Invalid difficulty — pick random
+                diff_enum = random.choice(list(DifficultyLevel))
+        else:
+            diff_enum = random.choice(list(DifficultyLevel))
+
+        # ── Load task ─────────────────────────────────────────────
+        try:
+            task = task_manager.get_task(diff_enum, task_id=task_id)
+        except Exception as e:
+            raise ValueError(f"Failed to load task: {str(e)}")
+
+        # ── Reset ALL state — no leakage ──────────────────────────
+        self._current_task = task
+        self._started_at   = time.time()
+        self._state        = EpisodeState(
+            task_id          = task["id"],
+            difficulty       = diff_enum,
+            step_count       = 0,
+            total_reward     = 0.0,
+            done             = False,
+            hints_used       = 0,
+            previous_actions = [],
+            action_counts    = {},
+            started_at       = self._started_at,
+            last_reward      = 0.0,
+            initialized      = True,
+        )
+
+        # ── Build initial observation ─────────────────────────────
+        context = task_manager.build_observation_context(task)
+        return Observation(
+            task_id          = task["id"],
+            task_description = task["description"],
+            current_context  = context,
+            step_count       = 0,
+            difficulty       = diff_enum,
+            max_steps        = MAX_STEPS,
+            hints_used       = 0,
+            previous_actions = [],
+            metadata         = {
+                "category":        task.get("category", ""),
+                "estimated_steps": task.get("estimated_fix_steps", 5),
+                "started_at":      self._started_at,
+            }
+        )
+
+    # ─────────────────────────────────────────────
+    #  step() → (Observation, Reward, done, info)
+    # ─────────────────────────────────────────────
+
+    def step(self, action: Optional[Action]) -> StepResponse:
+        """
+        Accepts an Action, processes it, updates state,
+        computes dense reward, returns next Observation.
+
+        Edge cases handled:
+        - step() called before reset() → auto-resets
+        - null action → reward=-0.1, done=False, never crash
+        - malformed action payload → catches ValidationError
+        - agent loops (same action 3+ times) → loop penalty
+        - episode already done → returns terminal observation
+        - max steps reached → forces done=True
+        - extremely long payload → truncated in models.py
+        """
+
+        # ── Auto-reset if not initialized ────────────────────────
+        if not self._state.initialized or self._current_task is None:
+            obs = self.reset()
+            return StepResponse(
+                observation=obs,
+                reward=Reward(score=0.0, breakdown={"auto_reset": True}, feedback="Environment auto-reset."),
+                done=False,
+                info={"auto_reset": True}
+            )
+
+        # ── Episode already done ──────────────────────────────────
+        if self._state.done:
+            obs = self._build_observation()
+            return StepResponse(
+                observation=obs,
+                reward=Reward(score=0.0, breakdown={"episode_done": True}, feedback="Episode already finished. Call reset()."),
+                done=True,
+                info={"episode_done": True, "total_reward": self._state.total_reward}
+            )
+
+        # ── Handle null / invalid action ─────────────────────────
+        if action is None or action.payload is None:
+            self._state.step_count += 1
+            obs = self._build_observation()
+            reward = Reward(
+                score=-0.1,
+                breakdown={"invalid_action": -0.1},
+                feedback="Null or invalid action received. Penalty -0.1."
+            )
+            self._state.last_reward   = -0.1
+            self._state.total_reward  = round(self._state.total_reward - 0.1, 4)
+            done = self._state.step_count >= MAX_STEPS
+            self._state.done = done
+            return StepResponse(observation=obs, reward=reward, done=done, info={"error": "null_action"})
+
+        # ── Validate action type ──────────────────────────────────
+        try:
+            action_type_val = action.action_type.value if hasattr(action.action_type, "value") else str(action.action_type)
+        except Exception:
+            action_type_val = "unknown"
+
+        # ── Update step count ─────────────────────────────────────
+        self._state.step_count += 1
+        self._state.previous_actions.append(action_type_val)
+        self._state.action_counts[action_type_val] = self._state.action_counts.get(action_type_val, 0) + 1
+
+        # ── Track hints ───────────────────────────────────────────
+        if action.action_type == ActionType.REQUEST_HINT:
+            self._state.hints_used += 1
+            # Inject hint into next observation context
+            hint_text = task_manager.get_hint(self._current_task, self._state.hints_used)
+            self._current_task["_last_hint"] = hint_text
+
+        # ── Compute dense reward ──────────────────────────────────
+        reward = compute_reward(
+            action           = action,
+            task_id          = self._state.task_id,
+            difficulty       = self._state.difficulty,
+            step_count       = self._state.step_count,
+            previous_actions = self._state.previous_actions[:-1],  # exclude current
+            hints_used       = self._state.hints_used,
+            estimated_steps  = self._current_task.get("estimated_fix_steps", 5),
+            action_counts    = self._state.action_counts,
+        )
+
+        # ── Update cumulative reward ──────────────────────────────
+        self._state.last_reward  = reward.score
+        self._state.total_reward = round(self._state.total_reward + reward.score, 4)
+
+        # ── Check done condition ──────────────────────────────────
+        done = is_done(
+            action_type  = action.action_type,
+            step_count   = self._state.step_count,
+            grader_score = reward.breakdown.get("grader_score", 0.0),
+        )
+        self._state.done = done
+
+        # ── Build next observation ────────────────────────────────
+        obs = self._build_observation()
+
+        # ── Build info dict ───────────────────────────────────────
+        info = {
+            "step_count":    self._state.step_count,
+            "total_reward":  self._state.total_reward,
+            "hints_used":    self._state.hints_used,
+            "action_counts": self._state.action_counts,
+            "task_id":       self._state.task_id,
+            "difficulty":    self._state.difficulty.value if self._state.difficulty else None,
+        }
+        if done:
+            info["episode_summary"] = {
+                "total_steps":  self._state.step_count,
+                "total_reward": self._state.total_reward,
+                "hints_used":   self._state.hints_used,
+                "duration_sec": round(time.time() - (self._started_at or time.time()), 2),
+            }
+
+        return StepResponse(observation=obs, reward=reward, done=done, info=info)
+
+    # ─────────────────────────────────────────────
+    #  state() → EpisodeState
+    # ─────────────────────────────────────────────
+
+    def state(self) -> EpisodeState:
+        """
+        Returns the full current state at any point.
+        Must be JSON-serializable. Must always reflect latest step.
+
+        Edge case: state() called before reset() → returns default empty state.
+        Never crashes.
+        """
+        return self._state
+
+    # ─────────────────────────────────────────────
+    #  INTERNAL HELPERS
+    # ─────────────────────────────────────────────
+
+    def _build_observation(self) -> Observation:
+        """
+        Builds the current Observation from internal state.
+        Injects hint into context if one was just requested.
+        CRITICAL: Never leaks fixed_query (ground truth) to agent.
+        """
+        if self._current_task is None:
+            # Fallback safe observation
+            return Observation(
+                task_id          = "none",
+                task_description = "No task loaded. Call reset() first.",
+                current_context  = {},
+                step_count       = self._state.step_count,
+                difficulty       = DifficultyLevel.EASY,
+                max_steps        = MAX_STEPS,
+                hints_used       = self._state.hints_used,
+                previous_actions = self._state.previous_actions,
+                metadata         = {}
+            )
+
+        context = task_manager.build_observation_context(self._current_task)
+
+        # Inject hint if available
+        if "_last_hint" in self._current_task:
+            context["last_hint"] = self._current_task["_last_hint"]
+
+        # Add step progress info
+        context["steps_remaining"] = MAX_STEPS - self._state.step_count
+        context["total_reward_so_far"] = self._state.total_reward
+
+        return Observation(
+            task_id          = self._state.task_id or "none",
+            task_description = self._current_task.get("description", ""),
+            current_context  = context,
+            step_count       = self._state.step_count,
+            difficulty       = self._state.difficulty or DifficultyLevel.EASY,
+            max_steps        = MAX_STEPS,
+            hints_used       = self._state.hints_used,
+            previous_actions = self._state.previous_actions.copy(),
+            metadata         = {
+                "category":        self._current_task.get("category", ""),
+                "estimated_steps": self._current_task.get("estimated_fix_steps", 5),
+                "total_reward":    self._state.total_reward,
+                "action_counts":   self._state.action_counts,
+            }
+        )
+
+
+# ─────────────────────────────────────────────
+#  SINGLETON INSTANCE (used by FastAPI)
+# ─────────────────────────────────────────────
+
+environment = SQLDebuggerEnvironment()

env/graders.py

@@ -0,0 +1,440 @@
+import re
+from env.models import Action, DifficultyLevel
+from env.tasks import task_manager
+
+#  HELPERS
+
+
+def _normalize(text: str) -> str:
+    """Normalize SQL for comparison — lowercase, strip whitespace, collapse spaces."""
+    if not isinstance(text, str):
+        return ""
+    return re.sub(r"\s+", " ", text.strip().lower())
+
+def _safe_get(payload: dict, key: str, default=None):
+    """Safe dict access — never KeyError."""
+    if not isinstance(payload, dict):
+        return default
+    return payload.get(key, default)
+
+def _score_explanation(explanation: str) -> float:
+    """Score explanation quality by length and keyword richness."""
+    if not explanation or not isinstance(explanation, str):
+        return 0.0
+    explanation = explanation.strip()
+    if len(explanation) < 10:
+        return 0.0
+    if len(explanation) < 30:
+        return 0.05
+    if len(explanation) < 80:
+        return 0.10
+    return 0.15
+
+def _score_confidence(confidence) -> float:
+    """Give partial credit for providing a valid confidence score."""
+    try:
+        c = float(confidence)
+        if 0.0 <= c <= 1.0:
+            return 0.05
+    except (TypeError, ValueError):
+        pass
+    return 0.0
+
+def _query_similarity(submitted: str, expected: str) -> float:
+    """
+    Multi-level SQL similarity check.
+    Returns 0.0 - 1.0 based on how close the submitted query is to expected.
+    Handles case, whitespace, and keyword-level matching.
+    """
+    s = _normalize(submitted)
+    e = _normalize(expected)
+
+    # Exact match after normalization
+    if s == e:
+        return 1.0
+
+    # Tokenize and check keyword overlap
+    s_tokens = set(s.split())
+    e_tokens = set(e.split())
+
+    if not e_tokens:
+        return 0.0
+
+    overlap = len(s_tokens & e_tokens) / len(e_tokens)
+
+    # Check critical keywords present
+    critical_keywords = _extract_critical_keywords(e)
+    critical_found = sum(1 for kw in critical_keywords if kw in s)
+    critical_score = critical_found / len(critical_keywords) if critical_keywords else 0.0
+
+    # Weighted combination
+    return round((overlap * 0.4) + (critical_score * 0.6), 4)
+
+def _extract_critical_keywords(query: str) -> list[str]:
+    """Extract SQL keywords that are critical to correctness."""
+    keywords = [
+        "left join", "inner join", "right join",
+        "group by", "order by", "having",
+        "partition by", "coalesce", "distinct",
+        "where", "on", "and", "or", "not",
+        "count", "sum", "avg", "max", "min",
+        "select", "from", "join"
+    ]
+    found = []
+    q = query.lower()
+    for kw in keywords:
+        if kw in q:
+            found.append(kw)
+    return found
+
+def _score_error_type(submitted_type: str, expected_type: str) -> float:
+    """Score for correctly identifying the error type."""
+    if not submitted_type:
+        return 0.0
+    s = submitted_type.strip().lower()
+    e = expected_type.strip().lower()
+    if s == e:
+        return 0.10
+    # Partial: performance ↔ optimization are related
+    related = {
+        "performance": ["optimization", "slow", "index", "scan"],
+        "logic":       ["semantic", "incorrect", "wrong"],
+        "syntax":      ["parse", "grammar", "token"]
+    }
+    for canonical, aliases in related.items():
+        if e == canonical and any(alias in s for alias in aliases):
+            return 0.05
+    return 0.0
+
+def _score_error_location(submitted_location: str, expected_location: str) -> float:
+    """Score for correctly identifying WHERE in the query the error is."""
+    if not submitted_location or not expected_location:
+        return 0.0
+    s = submitted_location.strip().lower()
+    e = expected_location.strip().lower()
+    if s == e:
+        return 0.15
+    # Partial: check if key location words overlap
+    e_words = set(e.split())
+    s_words = set(s.split())
+    overlap = len(e_words & s_words) / len(e_words) if e_words else 0.0
+    return round(overlap * 0.10, 4)
+
+
+#  GRADERS PER DIFFICULTY
+
+def grade_easy(action: Action, ground_truth: dict) -> tuple[float, dict, str]:
+    """
+    Easy task grader — syntax errors.
+    Max score: 1.0
+    Partial credit across: fix correctness, error location, error type, explanation, confidence.
+    DETERMINISTIC: same input always returns same score.
+    """
+    # Edge case: null or malformed action
+    if action is None or action.payload is None:
+        return 0.0, {"error": "null_action"}, "No action provided."
+
+    payload = action.payload
+    score   = 0.0
+    breakdown = {}
+    feedback_parts = []
+
+    action_type = action.action_type.value if hasattr(action.action_type, "value") else str(action.action_type)
+
+    # ── 1. Query fix correctness (0.50) ──────────────────────────
+    submitted_query = _safe_get(payload, "fixed_query", "") or _safe_get(payload, "optimized_query", "")
+    expected_query  = ground_truth.get("fixed_query", "")
+    similarity      = _query_similarity(submitted_query, expected_query)
+
+    if similarity >= 1.0:
+        fix_score = 0.50
+        feedback_parts.append("Correct fix applied.")
+    elif similarity >= 0.75:
+        fix_score = 0.30
+        feedback_parts.append("Fix is mostly correct but has minor differences.")
+    elif similarity >= 0.50:
+        fix_score = 0.15
+        feedback_parts.append("Fix is partially correct.")
+    else:
+        fix_score = 0.0
+        feedback_parts.append("Fix is incorrect or not provided.")
+
+    score += fix_score
+    breakdown["fix_correctness"] = round(fix_score, 4)
+
+    # ── 2. Error location (0.15) ─────────────────────────────────
+    submitted_location = _safe_get(payload, "error_location", "")
+    expected_location  = ground_truth.get("error_location", "")
+    loc_score          = _score_error_location(str(submitted_location), expected_location)
+    score             += loc_score
+    breakdown["error_location"] = round(loc_score, 4)
+    if loc_score > 0:
+        feedback_parts.append("Correctly identified error location.")
+
+    # ── 3. Error type (0.10) ─────────────────────────────────────
+    submitted_type = _safe_get(payload, "error_type", "")
+    expected_type  = ground_truth.get("error_type", "syntax")
+    type_score     = _score_error_type(str(submitted_type), expected_type)
+    score         += type_score
+    breakdown["error_type"] = round(type_score, 4)
+    if type_score > 0:
+        feedback_parts.append("Correctly identified error type.")
+
+    # ── 4. Explanation quality (0.15) ────────────────────────────
+    explanation   = _safe_get(payload, "explanation", "") or _safe_get(payload, "change_made", "")
+    expl_score    = _score_explanation(str(explanation) if explanation else "")
+    score        += expl_score
+    breakdown["explanation"] = round(expl_score, 4)
+    if expl_score > 0:
+        feedback_parts.append("Explanation provided.")
+
+    # ── 5. Confidence (0.05) ─────────────────────────────────────
+    confidence   = _safe_get(payload, "confidence", None)
+    conf_score   = _score_confidence(confidence)
+    score       += conf_score
+    breakdown["confidence"] = round(conf_score, 4)
+
+    # ── 6. Hint penalty ──────────────────────────────────────────
+    # Hint penalty is applied in reward.py, not here
+
+    final_score = round(min(score, 1.0), 4)
+    feedback    = " ".join(feedback_parts) if feedback_parts else "No valid response provided."
+    return final_score, breakdown, feedback
+
+
+def grade_medium(action: Action, ground_truth: dict) -> tuple[float, dict, str]:
+    """
+    Medium task grader — logic errors (wrong JOINs, wrong aggregations, etc).
+    Max score: 1.0
+    Higher bar: must correctly identify the logic flaw, not just syntax.
+    DETERMINISTIC: same input always returns same score.
+    """
+    if action is None or action.payload is None:
+        return 0.0, {"error": "null_action"}, "No action provided."
+
+    payload   = action.payload
+    score     = 0.0
+    breakdown = {}
+    feedback_parts = []
+
+    # ── 1. Query fix correctness (0.40) ──────────────────────────
+    submitted_query = _safe_get(payload, "fixed_query", "") or _safe_get(payload, "optimized_query", "")
+    expected_query  = ground_truth.get("fixed_query", "")
+    similarity      = _query_similarity(submitted_query, expected_query)
+
+    if similarity >= 1.0:
+        fix_score = 0.40
+        feedback_parts.append("Correct fix applied.")
+    elif similarity >= 0.80:
+        fix_score = 0.28
+        feedback_parts.append("Fix is mostly correct.")
+    elif similarity >= 0.60:
+        fix_score = 0.16
+        feedback_parts.append("Fix is partially correct.")
+    elif similarity >= 0.40:
+        fix_score = 0.08
+        feedback_parts.append("Fix shows some understanding.")
+    else:
+        fix_score = 0.0
+        feedback_parts.append("Fix is incorrect or missing.")
+
+    score += fix_score
+    breakdown["fix_correctness"] = round(fix_score, 4)
+
+    # ── 2. Identifies the logic flaw (0.20) ──────────────────────
+    explanation = str(_safe_get(payload, "explanation", "") or _safe_get(payload, "change_made", "") or "")
+    error_type  = ground_truth.get("error_type", "logic")
+    category    = ground_truth.get("category", "")
+
+    logic_keywords = {
+        "logic": ["join", "left join", "inner join", "having", "where", "group by",
+                  "aggregate", "subquery", "correlation", "distinct", "count"],
+        "performance": ["index", "scan", "n+1", "correlated", "cartesian", "window"]
+    }
+
+    keywords_to_check = logic_keywords.get(error_type, logic_keywords["logic"])
+    expl_lower        = explanation.lower()
+    keyword_hits      = sum(1 for kw in keywords_to_check if kw in expl_lower)
+    logic_score       = min(keyword_hits * 0.05, 0.20)
+    score            += logic_score
+    breakdown["logic_flaw_identification"] = round(logic_score, 4)
+    if logic_score > 0:
+        feedback_parts.append("Shows understanding of the logic flaw.")
+
+    # ── 3. Error location (0.15) ─────────────────────────────────
+    submitted_location = _safe_get(payload, "error_location", "")
+    expected_location  = ground_truth.get("error_location", "")
+    loc_score          = _score_error_location(str(submitted_location), expected_location)
+    score             += loc_score
+    breakdown["error_location"] = round(loc_score, 4)
+
+    # ── 4. Explanation quality (0.15) ────────────────────────────
+    expl_score = _score_explanation(explanation)
+    score     += expl_score
+    breakdown["explanation"] = round(expl_score, 4)
+
+    # ── 5. Confidence (0.05) ─────────────────────────────────────
+    confidence = _safe_get(payload, "confidence", None)
+    conf_score = _score_confidence(confidence)
+    score     += conf_score
+    breakdown["confidence"] = round(conf_score, 4)
+
+    # ── 6. Impact analysis bonus (0.05) ──────────────────────────
+    impact     = str(_safe_get(payload, "impact", "") or "")
+    if len(impact.strip()) > 20:
+        score += 0.05
+        breakdown["impact_analysis"] = 0.05
+        feedback_parts.append("Impact analysis provided.")
+    else:
+        breakdown["impact_analysis"] = 0.0
+
+    final_score = round(min(score, 1.0), 4)
+    feedback    = " ".join(feedback_parts) if feedback_parts else "No valid response provided."
+    return final_score, breakdown, feedback
+
+
+def grade_hard(action: Action, ground_truth: dict) -> tuple[float, dict, str]:
+    """
+    Hard task grader — performance issues (N+1, missing index, cartesian, etc).
+    Max score: 1.0 but frontier models expected ~0.10-0.20.
+    Extremely strict — requires deep understanding of performance concepts.
+    DETERMINISTIC: same input always returns same score.
+    """
+    if action is None or action.payload is None:
+        return 0.0, {"error": "null_action"}, "No action provided."
+
+    payload   = action.payload
+    score     = 0.0
+    breakdown = {}
+    feedback_parts = []
+
+    rubric = ground_truth.get("scoring_rubric", {})
+
+    # ── 1. Query correctness (0.30) ──────────────────────────────
+    submitted_query = (
+        _safe_get(payload, "optimized_query", "")
+        or _safe_get(payload, "fixed_query", "")
+        or ""
+    )
+    expected_query = ground_truth.get("fixed_query", "")
+    similarity     = _query_similarity(submitted_query, expected_query)
+
+    if similarity >= 1.0:
+        fix_score = 0.30
+        feedback_parts.append("Perfectly optimized query.")
+    elif similarity >= 0.85:
+        fix_score = 0.22
+        feedback_parts.append("Query is mostly correct.")
+    elif similarity >= 0.65:
+        fix_score = 0.14
+        feedback_parts.append("Query shows correct approach but incomplete.")
+    elif similarity >= 0.40:
+        fix_score = 0.07
+        feedback_parts.append("Query partially addresses the issue.")
+    else:
+        fix_score = 0.0
+        feedback_parts.append("Query does not address the performance issue.")
+
+    score += fix_score
+    breakdown["query_correctness"] = round(fix_score, 4)
+
+    # ── 2. Performance concept identification (0.30) ──────────────
+    explanation      = str(_safe_get(payload, "explanation", "") or _safe_get(payload, "change_made", "") or "")
+    optimization     = str(_safe_get(payload, "optimization_type", "") or "")
+    combined_text    = (explanation + " " + optimization).lower()
+    perf_issue       = ground_truth.get("performance_issue", {})
+    issue_type       = perf_issue.get("type", "").lower()
+
+    performance_concept_map = {
+        "n+1":               ["n+1", "correlated subquery", "subquery per row", "multiple queries", "join instead"],
+        "full table scan":   ["full table scan", "index not used", "function on column", "sargable", "range scan", "seek"],
+        "cartesian product": ["cartesian", "cross join", "missing join condition", "implicit join", "comma join"],
+        "select *":          ["select *", "over-fetch", "covering index", "column projection", "unnecessary columns"],
+        "window function":   ["window function", "partition by", "row_number", "subquery filter", "where clause window"]
+    }
+
+    concept_score = 0.0
+    for concept, keywords in performance_concept_map.items():
+        if any(concept_part in issue_type for concept_part in concept.split()):
+            hits = sum(1 for kw in keywords if kw in combined_text)
+            concept_score = min(hits * 0.06, 0.30)
+            break
+
+    score += concept_score
+    breakdown["performance_concept"] = round(concept_score, 4)
+    if concept_score > 0:
+        feedback_parts.append("Demonstrates understanding of the performance issue.")
+
+    # ── 3. Explanation depth (0.15) ───────────────────────────────
+    expl_score = _score_explanation(explanation)
+    # Hard tasks require deeper explanations — bonus for long explanations
+    if len(explanation.strip()) > 150:
+        expl_score = min(expl_score + 0.05, 0.15)
+    score += expl_score
+    breakdown["explanation_depth"] = round(expl_score, 4)
+
+    # ── 4. Root cause analysis (0.10) ─────────────────────────────
+    root_cause = str(_safe_get(payload, "root_cause", "") or "")
+    if len(root_cause.strip()) > 30:
+        score += 0.10
+        breakdown["root_cause_analysis"] = 0.10
+        feedback_parts.append("Root cause analysis provided.")
+    else:
+        breakdown["root_cause_analysis"] = 0.0
+
+    # ── 5. Expected improvement (0.10) ────────────────────────────
+    improvement = str(_safe_get(payload, "expected_improvement", "") or "")
+    if len(improvement.strip()) > 20:
+        score += 0.10
+        breakdown["expected_improvement"] = 0.10
+        feedback_parts.append("Performance improvement estimate provided.")
+    else:
+        breakdown["expected_improvement"] = 0.0
+
+    # ── 6. Confidence (0.05) ──────────────────────────────────────
+    confidence = _safe_get(payload, "confidence", None)
+    conf_score = _score_confidence(confidence)
+    score     += conf_score
+    breakdown["confidence"] = round(conf_score, 4)
+
+    # Hard cap: frontier model should score ~0.10-0.20
+    # We do NOT artificially cap — the rubric naturally produces low scores
+    final_score = round(min(score, 1.0), 4)
+    feedback    = " ".join(feedback_parts) if feedback_parts else "Performance issue not identified."
+    return final_score, breakdown, feedback
+
+
+# ─────────────────────────────────────────────
+#  MAIN GRADER DISPATCHER
+# ─────────────────────────────────────────────
+
+def grade(action: Action, task_id: str) -> tuple[float, dict, str]:
+    """
+    Main grader entry point.
+    Looks up ground truth, dispatches to correct grader by difficulty.
+    ALWAYS returns (float, dict, str) — never crashes.
+    """
+    # Edge case: null action
+    if action is None:
+        return 0.0, {"error": "null_action"}, "No action provided."
+
+    # Edge case: unknown task
+    ground_truth = task_manager.get_ground_truth(task_id)
+    if ground_truth is None:
+        return 0.0, {"error": "unknown_task"}, f"Task '{task_id}' not found."
+
+    # Dispatch by difficulty
+    difficulty = ground_truth.get("id", "").split("_")[0]
+
+    try:
+        if difficulty == "easy":
+            return grade_easy(action, ground_truth)
+        elif difficulty == "medium":
+            return grade_medium(action, ground_truth)
+        elif difficulty == "hard":
+            return grade_hard(action, ground_truth)
+        else:
+            return 0.0, {"error": "unknown_difficulty"}, f"Unknown difficulty: {difficulty}"
+    except Exception as e:
+        # Never crash — return 0.0 with error info
+        return 0.0, {"error": str(e)}, f"Grader error: {str(e)}"

env/reward.py

@@ -0,0 +1,204 @@
+from env.models import Action, Reward, DifficultyLevel, ActionType
+from env.graders import grade
+
+#  CONSTANTS
+
+MAX_STEPS        = 20
+HINT_PENALTY     = -0.05   # Per hint requested
+LOOP_PENALTY     = -0.05   # Same action 3+ times in a row
+INVALID_PENALTY  = -0.10   # Null / malformed action
+STEP_EFFICIENCY_BONUS = 0.10  # Bonus for solving in fewer steps than estimated
+
+# Dense reward per action type (before grader score)
+STEP_REWARDS = {
+    ActionType.IDENTIFY_ERROR:  0.15,  # Rewarded for diagnosing
+    ActionType.PROPOSE_FIX:     0.25,  # Rewarded for attempting fix
+    ActionType.SUBMIT_ANSWER:   0.00,  # Final score comes from grader
+    ActionType.REQUEST_HINT:    0.00,  # No reward, only penalty
+    ActionType.EXPLAIN_ISSUE:   0.10,  # Rewarded for explaining
+    ActionType.OPTIMIZE_QUERY:  0.20,  # Rewarded for optimization attempt
+}
+
+
+#  LOOP DETECTOR
+
+
+def _detect_loop(previous_actions: list[str], current_action: str) -> bool:
+    """
+    Returns True if the agent has submitted the same action type
+    3 or more times in a row — indicating a stuck loop.
+    """
+    if len(previous_actions) < 2:
+        return False
+    last_two = previous_actions[-2:]
+    return all(a == current_action for a in last_two)
+
+
+def _count_consecutive(previous_actions: list[str], current_action: str) -> int:
+    """Count how many times the current action has been repeated consecutively."""
+    count = 1
+    for a in reversed(previous_actions):
+        if a == current_action:
+            count += 1
+        else:
+            break
+    return count
+
+
+#  EFFICIENCY BONUS
+
+
+def _efficiency_bonus(step_count: int, estimated_steps: int) -> float:
+    """
+    Bonus reward if agent solves faster than estimated.
+    Encourages efficient reasoning, not just correct answers.
+    """
+    if step_count <= 0 or estimated_steps <= 0:
+        return 0.0
+    if step_count <= estimated_steps:
+        ratio = step_count / estimated_steps
+        # More bonus the faster — scales from 0.10 down to 0.0
+        return round(STEP_EFFICIENCY_BONUS * (1.0 - ratio + 0.1), 4)
+    return 0.0
+
+
+#  MAIN REWARD FUNCTION
+
+def compute_reward(
+    action:           Action,
+    task_id:          str,
+    difficulty:       DifficultyLevel,
+    step_count:       int,
+    previous_actions: list[str],
+    hints_used:       int,
+    estimated_steps:  int,
+    action_counts:    dict[str, int],
+) -> Reward:
+    """
+    Computes a DENSE reward signal for every step.
+    Never returns 0.0 for all steps — reward varies at each step.
+
+    Dense reward components:
+    1. Step reward     — small reward just for taking valid action
+    2. Grader score    — full grader score on submit_answer / optimize_query
+    3. Loop penalty    — repeated same action 3+ times
+    4. Hint penalty    — accumulated hint cost
+    5. Efficiency bonus — solved faster than estimated steps
+    6. Invalid penalty — null / malformed action
+
+    Score is always clamped to [-1.0, 1.0].
+    """
+
+    breakdown     = {}
+    feedback_parts = []
+    final_score   = 0.0
+
+    # ── Edge case: null action ────────────────────────────────────
+    if action is None or action.payload is None:
+        return Reward(
+            score=-0.1,
+            breakdown={"invalid_action": -0.1},
+            feedback="Invalid or null action received. Penalty applied."
+        )
+
+    action_type_val = action.action_type.value if hasattr(action.action_type, "value") else str(action.action_type)
+    action_type_enum = action.action_type
+
+    # ── 1. Step reward (dense signal) ────────────────────────────
+    step_reward = STEP_REWARDS.get(action_type_enum, 0.05)
+    breakdown["step_reward"] = round(step_reward, 4)
+    final_score += step_reward
+    if step_reward > 0:
+        feedback_parts.append(f"Action '{action_type_val}' rewarded +{step_reward}.")
+
+    # ── 2. Grader score for terminal actions ──────────────────────
+    grader_score = 0.0
+    is_terminal  = action_type_enum in (ActionType.SUBMIT_ANSWER, ActionType.OPTIMIZE_QUERY)
+
+    if is_terminal:
+        raw_score, grader_breakdown, grader_feedback = grade(action, task_id)
+        grader_score = raw_score
+        breakdown["grader_score"]    = round(grader_score, 4)
+        breakdown["grader_breakdown"] = grader_breakdown
+        final_score += grader_score
+        feedback_parts.append(grader_feedback)
+
+        # Efficiency bonus — only on correct terminal action
+        if grader_score >= 0.5:
+            eff_bonus = _efficiency_bonus(step_count, estimated_steps)
+            if eff_bonus > 0:
+                final_score += eff_bonus
+                breakdown["efficiency_bonus"] = round(eff_bonus, 4)
+                feedback_parts.append(f"Efficiency bonus +{eff_bonus} for solving in {step_count} steps.")
+
+    elif action_type_enum == ActionType.PROPOSE_FIX:
+        # Partial grader score for propose_fix — encourages iterative improvement
+        raw_score, grader_breakdown, _ = grade(action, task_id)
+        partial = round(raw_score * 0.4, 4)  # 40% of full grader score
+        grader_score = partial
+        breakdown["partial_grader_score"] = partial
+        final_score += partial
+        if partial > 0:
+            feedback_parts.append(f"Partial fix credit +{partial}.")
+
+    elif action_type_enum == ActionType.IDENTIFY_ERROR:
+        # Small grader check on error identification
+        raw_score, _, _ = grade(action, task_id)
+        partial = round(raw_score * 0.2, 4)  # 20% for identification step
+        breakdown["identification_score"] = partial
+        final_score += partial
+
+    # ── 3. Loop penalty ───────────────────────────────────────────
+    if _detect_loop(previous_actions, action_type_val):
+        consecutive = _count_consecutive(previous_actions, action_type_val)
+        loop_pen    = LOOP_PENALTY * min(consecutive - 2, 3)  # Cap at 3x penalty
+        final_score += loop_pen
+        breakdown["loop_penalty"] = round(loop_pen, 4)
+        feedback_parts.append(f"Loop detected ({consecutive}x same action). Penalty {loop_pen}.")
+
+    # ── 4. Hint penalty ───────────────────────────────────────────
+    if action_type_enum == ActionType.REQUEST_HINT:
+        hint_pen     = HINT_PENALTY
+        final_score += hint_pen
+        breakdown["hint_penalty"] = round(hint_pen, 4)
+        feedback_parts.append(f"Hint requested. Penalty {hint_pen}.")
+
+    # ── 5. Max steps penalty ──────────────────────────────────────
+    if step_count >= MAX_STEPS - 1:
+        final_score += -0.10
+        breakdown["max_steps_penalty"] = -0.10
+        feedback_parts.append("Approaching max steps limit. Penalty applied.")
+
+    # ── Clamp to [-1.0, 1.0] ─────────────────────────────────────
+    final_score = round(max(-1.0, min(1.0, final_score)), 4)
+    breakdown["total"] = final_score
+
+    feedback = " ".join(feedback_parts) if feedback_parts else "Step processed."
+
+    return Reward(
+        score=final_score,
+        breakdown=breakdown,
+        feedback=feedback
+    )
+
+
+#  EPISODE DONE CONDITION
+
+def is_done(
+    action_type:      ActionType,
+    step_count:       int,
+    grader_score:     float = 0.0,
+) -> bool:
+    """
+    Episode ends when:
+    1. Agent submits final answer (submit_answer / optimize_query)
+    2. Max steps reached
+    3. Perfect score achieved
+    """
+    if action_type in (ActionType.SUBMIT_ANSWER, ActionType.OPTIMIZE_QUERY):
+        return True
+    if step_count >= MAX_STEPS:
+        return True
+    if grader_score >= 1.0:
+        return True
+    return False

openenv.yaml

@@ -0,0 +1,108 @@
+name: sql-query-debugger
+version: '1.0.0'
+description: 'An OpenEnv environment where AI agents learn to debug SQL queries across syntax errors, logic bugs, and performance issues'
+tags: [openenv, real-world, sql, debugging, performance, reinforcement-learning]
+
+tasks:
+  - id: easy_001
+    difficulty: easy
+    description: 'Fix SQL syntax error: missing commas in SELECT clause'
+
+  - id: easy_002
+    difficulty: easy
+    description: 'Fix SQL syntax error: missing WHERE keyword'
+
+  - id: easy_003
+    difficulty: easy
+    description: 'Fix SQL syntax error: unclosed string literal'
+
+  - id: easy_004
+    difficulty: easy
+    description: 'Fix SQL syntax error: ORDER used instead of ORDER BY'
+
+  - id: easy_005
+    difficulty: easy
+    description: 'Fix SQL syntax error: GROUP used instead of GROUP BY'
+
+  - id: medium_001
+    difficulty: medium
+    description: 'Fix wrong JOIN type: INNER JOIN excludes users with no orders'
+
+  - id: medium_002
+    difficulty: medium
+    description: 'Fix wrong JOIN condition causing incorrect product associations'
+
+  - id: medium_003
+    difficulty: medium
+    description: 'Fix aggregation logic: HAVING clause used incorrectly as WHERE'
+
+  - id: medium_004
+    difficulty: medium
+    description: 'Fix correlated subquery correlating on wrong column'
+
+  - id: medium_005
+    difficulty: medium
+    description: 'Fix DISTINCT misuse with COUNT causing invalid query'
+
+  - id: hard_001
+    difficulty: hard
+    description: 'Detect and fix N+1 query pattern with correlated subqueries'
+
+  - id: hard_002
+    difficulty: hard
+    description: 'Fix function on indexed column preventing index usage'
+
+  - id: hard_003
+    difficulty: hard
+    description: 'Fix implicit cartesian product from missing JOIN condition'
+
+  - id: hard_004
+    difficulty: hard
+    description: 'Fix SELECT * in multi-table JOIN causing over-fetching'
+
+  - id: hard_005
+    difficulty: hard
+    description: 'Fix window function misuse with missing PARTITION BY and ORDER BY'
+
+action_space:
+  type: discrete
+  actions:
+    - identify_error
+    - propose_fix
+    - submit_answer
+    - request_hint
+    - explain_issue
+    - optimize_query
+
+observation_space:
+  type: dict
+  fields:
+    - task_id
+    - task_description
+    - current_context
+    - step_count
+    - difficulty
+    - max_steps
+    - hints_used
+    - previous_actions
+
+reward:
+  min: -1.0
+  max: 1.0
+  type: dense
+  description: 'Dense reward signal at every step. Partial credit for identification, fixing, and explanation quality.'
+
+episode:
+  max_steps: 20
+  termination: 'submit_answer or optimize_query action, or max_steps reached'
+
+api:
+  port: 7860
+  endpoints:
+    - GET  /health
+    - POST /reset
+    - POST /step
+    - GET  /state
+    - GET  /tasks
+    - POST /grader
+    - POST /baseline

requirements.txt

@@ -0,0 +1,7 @@
+fastapi==0.135.2
+uvicorn==0.42.0
+pydantic==2.12.5
+openai==2.30.0
+python-dotenv==1.2.2
+pytest==9.0.2
+huggingface_hub==1.8.0

tests/test_environment.py

@@ -0,0 +1,139 @@
+import pytest
+from env.environment import SQLDebuggerEnvironment
+from env.models import Action, ActionType, DifficultyLevel
+
+
+@pytest.fixture
+def env():
+    e = SQLDebuggerEnvironment()
+    return e
+
+
+def test_state_before_reset(env):
+    """state() before reset must not crash — returns default state."""
+    s = env.state()
+    assert s.initialized == False
+    assert s.step_count == 0
+
+
+def test_reset_easy(env):
+    obs = env.reset(difficulty="easy")
+    assert obs.task_id.startswith("easy")
+    assert obs.step_count == 0
+    assert obs.difficulty == DifficultyLevel.EASY
+    assert "fixed_query" not in obs.current_context
+    assert "buggy_query" in obs.current_context
+
+
+def test_reset_medium(env):
+    obs = env.reset(difficulty="medium")
+    assert obs.task_id.startswith("medium")
+
+
+def test_reset_hard(env):
+    obs = env.reset(difficulty="hard")
+    assert obs.task_id.startswith("hard")
+
+
+def test_reset_clears_state(env):
+    """Reset mid-episode must clear all state — no leakage."""
+    env.reset(difficulty="easy")
+    action = Action(action_type=ActionType.IDENTIFY_ERROR,
+                    payload={"error_location": "SELECT", "error_type": "syntax"})
+    env.step(action)
+    assert env.state().step_count == 1
+
+    # Reset mid-episode
+    env.reset(difficulty="medium")
+    assert env.state().step_count == 0
+    assert env.state().total_reward == 0.0
+    assert env.state().previous_actions == []
+
+
+def test_step_identify_error(env):
+    env.reset(difficulty="easy")
+    action = Action(action_type=ActionType.IDENTIFY_ERROR,
+                    payload={"error_location": "SELECT clause", "error_type": "syntax",
+                             "explanation": "Missing commas"})
+    resp = env.step(action)
+    assert resp.reward.score > 0
+    assert resp.done == False
+    assert resp.observation.step_count == 1
+
+
+def test_step_null_action(env):
+    """Null action must return -0.1, never crash."""
+    env.reset(difficulty="easy")
+    resp = env.step(None)
+    assert resp.reward.score == -0.1
+    assert resp.done == False
+
+
+def test_step_after_done(env):
+    """Step after done must not crash."""
+    env.reset(difficulty="easy", task_id="easy_001")
+    action = Action(action_type=ActionType.SUBMIT_ANSWER,
+                    payload={"fixed_query": "SELECT id, name, email FROM users WHERE active = 1",
+                             "explanation": "Fixed", "confidence": 0.9})
+    env.step(action)
+    assert env.state().done == True
+
+    # Step again after done
+    resp = env.step(action)
+    assert resp.done == True
+    assert "Call reset()" in resp.reward.feedback
+
+
+def test_dense_reward(env):
+    """Reward must vary at each step — not only at end."""
+    env.reset(difficulty="easy")
+    rewards = []
+    actions = [
+        Action(action_type=ActionType.IDENTIFY_ERROR,
+               payload={"error_location": "SELECT", "error_type": "syntax"}),
+        Action(action_type=ActionType.EXPLAIN_ISSUE,
+               payload={"explanation": "Missing commas between column names in SELECT"}),
+    ]
+    for a in actions:
+        r = env.step(a)
+        rewards.append(r.reward.score)
+        if r.done:
+            break
+
+    # Rewards must not all be zero
+    assert any(r != 0.0 for r in rewards)
+
+
+def test_max_steps(env):
+    """Episode must terminate at max_steps."""
+    env.reset(difficulty="easy")
+    action = Action(action_type=ActionType.IDENTIFY_ERROR,
+                    payload={"error_location": "x", "error_type": "syntax"})
+    done = False
+    for _ in range(25):
+        resp = env.step(action)
+        if resp.done:
+            done = True
+            break
+    assert done == True
+
+
+def test_hint_injected_in_context(env):
+    """Hint must appear in next observation after request_hint."""
+    env.reset(difficulty="easy")
+    action = Action(action_type=ActionType.REQUEST_HINT,
+                    payload={"hint_type": "location"})
+    resp = env.step(action)
+    assert "last_hint" in resp.observation.current_context
+
+
+def test_state_reflects_latest_step(env):
+    """state() must always reflect the latest step accurately."""
+    env.reset(difficulty="easy")
+    action = Action(action_type=ActionType.IDENTIFY_ERROR,
+                    payload={"error_location": "SELECT", "error_type": "syntax"})
+    env.step(action)
+    s = env.state()
+    assert s.step_count == 1
+    assert s.initialized == True
+    assert "identify_error" in s.previous_actions

tests/test_graders.py

@@ -0,0 +1,140 @@
+import pytest
+from env.models import Action, ActionType
+from env.graders import grade, _normalize, _query_similarity
+
+
+def test_easy_perfect_score():
+    action = Action(
+        action_type=ActionType.SUBMIT_ANSWER,
+        payload={
+            "fixed_query":   "SELECT id, name, email FROM users WHERE active = 1",
+            "explanation":   "Added missing commas between column names in SELECT clause",
+            "error_type":    "syntax",
+            "error_location":"SELECT clause",
+            "confidence":    0.95
+        }
+    )
+    score, breakdown, feedback = grade(action, "easy_001")
+    assert score > 0.5
+    assert 0.0 <= score <= 1.0
+
+
+def test_null_action_returns_zero():
+    score, breakdown, feedback = grade(None, "easy_001")
+    assert score == 0.0
+    assert "null" in feedback.lower() or "no action" in feedback.lower()
+
+
+def test_unknown_task_returns_zero():
+    action = Action(action_type=ActionType.SUBMIT_ANSWER,
+                    payload={"fixed_query": "SELECT 1", "explanation": "test"})
+    score, _, _ = grade(action, "nonexistent_task_999")
+    assert score == 0.0
+
+
+def test_determinism():
+    """Same input must always return same score."""
+    action = Action(
+        action_type=ActionType.SUBMIT_ANSWER,
+        payload={
+            "fixed_query":   "SELECT id, name, email FROM users WHERE active = 1",
+            "explanation":   "Fixed commas",
+            "error_type":    "syntax",
+            "error_location":"SELECT clause",
+            "confidence":    0.9
+        }
+    )
+    scores = [grade(action, "easy_001")[0] for _ in range(5)]
+    assert len(set(scores)) == 1
+
+
+def test_score_range():
+    """All graders must return score in 0.0 - 1.0."""
+    action = Action(action_type=ActionType.SUBMIT_ANSWER,
+                    payload={"fixed_query": "SELECT 1", "explanation": "test"})
+    for task_id in ["easy_001", "medium_001", "hard_001"]:
+        score, _, _ = grade(action, task_id)
+        assert 0.0 <= score <= 1.0, f"Score out of range for {task_id}: {score}"
+
+
+def test_no_binary_graders():
+    """Graders must not always return only 0 or only 1."""
+    payloads = [
+        {"fixed_query": "SELECT id, name, email FROM users WHERE active = 1",
+         "explanation": "Fixed", "confidence": 0.9},
+        {"fixed_query": "SELECT *", "explanation": "wrong"},
+        {"fixed_query": "", "explanation": ""},
+    ]
+    for task_id in ["easy_001", "medium_001", "hard_001"]:
+        scores = set()
+        for p in payloads:
+            action = Action(action_type=ActionType.SUBMIT_ANSWER, payload=p)
+            score, _, _ = grade(action, task_id)
+            scores.add(score)
+        assert len(scores) > 1, f"Grader for {task_id} returns same score always"
+
+
+def test_empty_string_answer():
+    """Empty string must return 0.0, not crash."""
+    action = Action(action_type=ActionType.SUBMIT_ANSWER,
+                    payload={"fixed_query": "", "explanation": ""})
+    score, _, _ = grade(action, "easy_001")
+    assert score == 0.0 or score < 0.3
+
+
+def test_case_insensitive_normalization():
+    """Grader normalizes case — UPPER and lower should score similarly."""
+    action_upper = Action(action_type=ActionType.SUBMIT_ANSWER,
+                          payload={"fixed_query": "SELECT ID, NAME, EMAIL FROM USERS WHERE ACTIVE = 1",
+                                   "explanation": "Fixed", "confidence": 0.9})
+    action_lower = Action(action_type=ActionType.SUBMIT_ANSWER,
+                          payload={"fixed_query": "select id, name, email from users where active = 1",
+                                   "explanation": "Fixed", "confidence": 0.9})
+    score_upper, _, _ = grade(action_upper, "easy_001")
+    score_lower, _, _ = grade(action_lower, "easy_001")
+    assert abs(score_upper - score_lower) < 0.1
+
+
+def test_whitespace_normalization():
+    """Extra whitespace must not affect score."""
+    action = Action(action_type=ActionType.SUBMIT_ANSWER,
+                    payload={"fixed_query": "  SELECT   id,  name,  email  FROM  users  WHERE  active = 1  ",
+                             "explanation": "Fixed", "confidence": 0.9})
+    score, _, _ = grade(action, "easy_001")
+    assert score > 0.5
+
+
+def test_medium_logic_grader():
+    action = Action(
+        action_type=ActionType.SUBMIT_ANSWER,
+        payload={
+            "fixed_query":    "SELECT u.id, u.name, COUNT(o.id) as order_count FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id, u.name",
+            "explanation":    "Changed INNER JOIN to LEFT JOIN to include users with zero orders",
+            "error_type":     "logic",
+            "error_location": "JOIN type",
+            "confidence":     0.9
+        }
+    )
+    score, _, _ = grade(action, "medium_001")
+    assert score > 0.4
+
+
+def test_hard_grader_frontier_model_range():
+    """Hard grader must allow scores in 0.10-0.20 range for partial answers."""
+    action = Action(
+        action_type=ActionType.OPTIMIZE_QUERY,
+        payload={
+            "optimized_query": "SELECT u.id FROM users u LEFT JOIN orders o ON u.id = o.user_id",
+            "optimization_type": "Replace N+1 with JOIN",
+            "explanation": "N+1 pattern detected",
+            "confidence": 0.5
+        }
+    )
+    score, _, _ = grade(action, "hard_001")
+    assert 0.0 <= score <= 1.0
+
+
+def test_query_similarity_helper():
+    assert _query_similarity("SELECT id FROM users", "SELECT id FROM users") == 1.0
+    assert _query_similarity("", "SELECT id FROM users") < 0.5
+    assert _query_similarity("SELECT id FROM users", "") == 0.0