Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,219 @@
 ---
-title: Api Debug Env
-emoji: 📈
-colorFrom: red
-colorTo: yellow
+title: API Debug Environment
+emoji: "🔧"
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
+license: mit
+base_path: /web
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# API Debug Environment
+
+An OpenEnv reinforcement learning environment where LLM agents learn to debug malformed API requests. The agent receives a broken request and its API specification, then must diagnose the error, fix the request, and explain the fix.
+
+Built for the Meta PyTorch OpenEnv Hackathon x Scaler School of Technology 2026.
+
+## Why This Domain
+
+Developers spend significant time debugging API contract mismatches. Research from Calendar Gym shows that malformed tool arguments caused more than half of agent failures. This environment trains agents to identify and fix these errors systematically.
+
+**Real-world applications:** API gateway validation, automated debugging assistants, developer tooling, CI/CD request validation, LLM tool-use reliability.
+
+## How It Works
+
+1. On `reset()`, the environment picks a random API spec from 30 templates and injects 1-3 errors
+2. The agent receives the broken request, headers, and the API specification
+3. The agent submits a fix attempt via `step()`
+4. The environment grades the attempt and returns structured feedback
+5. The agent can iterate (multi-turn) using the feedback to improve
+
+Each episode allows multiple attempts. Perfect answers on early steps earn full reward. Later steps get decayed reward, encouraging efficient debugging.
+
+## Tasks
+
+| Task | Difficulty | Max Steps | Errors | Grading |
+|------|-----------|-----------|--------|---------|
+| easy | Identify error type and affected fields | 3 | 1 | Deterministic: 0.6 x type_match + 0.4 x fields_match |
+| medium | Fix the broken request | 5 | 1 | Deterministic: per-field validation against spec |
+| hard | Fix request + explain for developers | 7 | 2-3 | 70% deterministic fix + 30% LLM-as-judge explanation |
+
+## Error Types
+
+| Error Type | Description | Example |
+|-----------|-------------|---------|
+| missing_required_field | A required field is removed | `email` missing from Create User |
+| wrong_field_type | Field has wrong type | `amount` sent as `"2500"` instead of `2500` |
+| invalid_email_format | Email field is malformed | `user@` instead of `user@example.com` |
+| missing_auth_header | Authorization header removed | No `Bearer` token |
+| extra_unknown_field | Unknown field added | `debug_mode: true` in production request |
+| null_value_in_required | Required field set to null | `name: null` |
+| wrong_http_method | Wrong HTTP method used | `GET` instead of `POST` |
+| malformed_json_value | Corrupted field value | `{broken` as a value |
+| invalid_enum_value | Value not in allowed list | `currency: "xyz"` |
+| datetime_format_error | Wrong date format | `04/01/2026` instead of ISO 8601 |
+
+## API Spec Domains (30 templates)
+
+| Domain | Count | Examples |
+|--------|-------|---------|
+| Payment (Stripe-like) | 5 | Create Customer, Create Charge, Process Refund |
+| User Management | 5 | Create User, Update Profile, Reset Password |
+| Content (GitHub-like) | 5 | Create Repository, Create Issue, Merge PR |
+| Messaging (Twilio-like) | 5 | Send SMS, Send Email, Create Webhook |
+| E-Commerce | 5 | Create Order, Process Payment, Create Shipping Label |
+| Calendar and Auth | 5 | Create Event, OAuth Token, Create API Key |
+
+## Action Space
+
+The agent sends an `APIDebugAction` with these fields (all optional, submit what you have):
+
+| Field | Type | Used In | Description |
+|-------|------|---------|-------------|
+| error_type | string | easy, hard | Diagnosed error type |
+| affected_fields | list[string] | easy, hard | Fields affected by the error |
+| fixed_request | string (JSON) | medium, hard | Corrected request body |
+| fixed_headers | dict | medium, hard | Corrected HTTP headers |
+| explanation | string | hard | Developer-facing explanation |
+
+## Observation Space
+
+The environment returns an `APIDebugObservation` with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| task | string | Current difficulty: easy, medium, hard |
+| api_name | string | Name of the API (e.g. "Create Customer") |
+| http_method | string | HTTP method of the request |
+| endpoint | string | API endpoint path |
+| broken_request | string (JSON) | The malformed request body |
+| broken_headers | dict | HTTP headers sent with the request |
+| api_spec | string (JSON) | API specification with required fields and types |
+| error_count | int | Number of errors injected |
+| step_number | int | Current step in the episode |
+| max_steps | int | Maximum steps allowed |
+| feedback | string | Structured validation feedback from last action |
+| message | string | Human-readable status |
+| done | bool | Whether the episode has ended |
+| reward | float | Reward signal (0.0 to 1.0) |
+
+## Reward Design
+
+Rewards are shaped per-step with decay to encourage efficient debugging:
+
+```
+reward = raw_score x max(1.0 - 0.1 x (step - 1), 0.3)
+```
+
+- Step 1: full reward (1.0x multiplier)
+- Step 2: 0.9x multiplier
+- Step 5: 0.6x multiplier
+- Step 7+: 0.3x floor (agent still gets credit for late fixes)
+
+At episode end, the best reward achieved across all steps is returned.
+
+## Baseline Scores
+
+Scores will be updated after running inference against the live HF Space.
+
+| Task | Episodes | Avg Score | Model |
+|------|----------|-----------|-------|
+| easy | 3 | TBD | Qwen/Qwen2.5-72B-Instruct |
+| medium | 3 | TBD | Qwen/Qwen2.5-72B-Instruct |
+| hard | 3 | TBD | Qwen/Qwen2.5-72B-Instruct |
+
+## Setup
+
+### Prerequisites
+
+- Python 3.12+
+- Docker (for container deployment)
+- uv (Python package manager)
+
+### Local Development
+
+```bash
+git clone https://github.com/Avi-chauhan/api-debug-env.git
+cd api-debug-env
+uv venv --python 3.12
+source .venv/bin/activate
+uv pip install -r requirements.txt
+```
+
+### Run Server Locally
+
+```bash
+uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### Docker
+
+```bash
+docker build -t api-debug-env:latest .
+docker run -p 7860:7860 api-debug-env:latest
+```
+
+### Test
+
+```python
+import asyncio
+from client import APIDebugEnv
+from models import APIDebugAction
+
+async def test():
+    async with APIDebugEnv(base_url="http://localhost:8000") as env:
+        result = await env.reset(task="easy")
+        print(result.observation.message)
+
+        action = APIDebugAction(
+            error_type="missing_required_field",
+            affected_fields=["email"]
+        )
+        result = await env.step(action)
+        print(f"Reward: {result.reward}, Feedback: {result.observation.feedback}")
+
+asyncio.run(test())
+```
+
+## Project Structure
+
+```
+api-debug-env/
+├── Dockerfile              # Root level (required for HF Spaces)
+├── requirements.txt
+├── inference.py            # Baseline inference script (mandatory)
+├── openenv.yaml            # OpenEnv manifest
+├── pyproject.toml
+├── README.md
+├── models.py               # APIDebugAction, APIDebugObservation
+├── client.py               # APIDebugEnv(EnvClient)
+├── __init__.py
+└── server/
+    ├── __init__.py
+    ├── app.py              # FastAPI app via create_app()
+    ├── environment.py      # Core logic: reset(), step(), graders
+    ├── api_specs.py        # 30 API spec templates
+    ├── error_injectors.py  # 10 error injection functions
+    └── validators.py       # Field type validation helpers
+```
+
+## Deployment
+
+### HuggingFace Spaces
+
+```bash
+openenv push --repo-id avichauhan/api-debug-env
+```
+
+HF Space URL: https://avichauhan-api-debug-env.hf.space
+
+### Validation
+
+```bash
+./validate-submission.sh https://avichauhan-api-debug-env.hf.space .
+```
+
+## License
+
+MIT

__init__.py

@@ -0,0 +1,4 @@
+from .models import APIDebugAction, APIDebugObservation
+from .client import APIDebugEnv
+
+__all__ = ["APIDebugAction", "APIDebugObservation", "APIDebugEnv"]

client.py

@@ -0,0 +1,79 @@
+"""
+Client SDK for the API Debug Environment.
+
+Implements the three required abstract methods from EnvClient:
+- _step_payload: converts APIDebugAction to JSON dict
+- _parse_result: converts server response to StepResult
+- _parse_state: converts server state to State object
+
+Usage:
+    async with APIDebugEnv(base_url="http://localhost:8000") as env:
+        result = await env.reset(task="easy")
+        result = await env.step(APIDebugAction(error_type="missing_required_field"))
+"""
+
+from typing import Any, Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from models import APIDebugAction, APIDebugObservation
+
+
+class APIDebugEnv(EnvClient[APIDebugAction, APIDebugObservation, State]):
+
+    def _step_payload(self, action: APIDebugAction) -> Dict[str, Any]:
+        """Convert action to JSON dict, including only non-None fields."""
+        payload = {}
+        if action.error_type is not None:
+            payload["error_type"] = action.error_type
+        if action.affected_fields is not None:
+            payload["affected_fields"] = action.affected_fields
+        if action.fixed_request is not None:
+            payload["fixed_request"] = action.fixed_request
+        if action.fixed_headers is not None:
+            payload["fixed_headers"] = action.fixed_headers
+        if action.explanation is not None:
+            payload["explanation"] = action.explanation
+        return payload
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[APIDebugObservation]:
+        """Convert server JSON response to StepResult.
+
+        The server sends:
+        {
+            "observation": { ...fields except reward/done/metadata... },
+            "reward": float,
+            "done": bool,
+        }
+        """
+        obs_data = payload.get("observation", {})
+        observation = APIDebugObservation(
+            task=obs_data.get("task", "easy"),
+            api_name=obs_data.get("api_name", ""),
+            http_method=obs_data.get("http_method", "POST"),
+            endpoint=obs_data.get("endpoint", ""),
+            broken_request=obs_data.get("broken_request", ""),
+            broken_headers=obs_data.get("broken_headers", {}),
+            api_spec=obs_data.get("api_spec", ""),
+            error_count=obs_data.get("error_count", 1),
+            step_number=obs_data.get("step_number", 0),
+            max_steps=obs_data.get("max_steps", 3),
+            feedback=obs_data.get("feedback", ""),
+            message=obs_data.get("message", ""),
+            done=payload.get("done", False),
+            reward=payload.get("reward", 0.0),
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", 0.0),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> State:
+        """Convert server state JSON to State object."""
+        return State(
+            episode_id=payload.get("episode_id", ""),
+            step_count=payload.get("step_count", 0),
+        )

inference.py

@@ -0,0 +1,313 @@
+"""
+Baseline inference script for the API Debug Environment.
+
+MANDATORY:
+- Must be named inference.py and placed in the root directory.
+- Must use OpenAI Client for all LLM calls.
+- Must read env vars: API_BASE_URL, MODEL_NAME, HF_TOKEN.
+- Must emit [START], [STEP], [END] structured logs to stdout.
+
+STDOUT FORMAT:
+    [START] task=<task_name> env=<benchmark> model=<model_name>
+    [STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+    [END]   success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...,rn>
+"""
+
+import asyncio
+import json
+import os
+import re
+import textwrap
+from typing import List, Optional
+
+from openai import OpenAI
+
+from client import APIDebugEnv
+from models import APIDebugAction
+
+# Environment variables (mandatory for hackathon evaluation)
+API_BASE_URL = os.getenv("API_BASE_URL") or "https://router.huggingface.co/v1"
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+MODEL_NAME = os.getenv("MODEL_NAME") or "Qwen/Qwen2.5-72B-Instruct"
+ENV_URL = os.getenv("ENV_URL") or "https://avichauhan-api-debug-env.hf.space"
+IMAGE_NAME = os.getenv("IMAGE_NAME")
+
+# Task configuration
+TASKS = ["easy", "medium", "hard"]
+EPISODES_PER_TASK = 3
+MAX_STEPS = {"easy": 3, "medium": 5, "hard": 7}
+BENCHMARK_NAME = "api_debug"
+
+
+# =========================================================================
+# Structured logging (exact format required by evaluator)
+# =========================================================================
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(
+    step: int, action: str, reward: float, done: bool, error: Optional[str]
+) -> None:
+    done_val = str(done).lower()
+    error_val = error if error else "null"
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.2f} "
+        f"done={done_val} error={error_val}",
+        flush=True,
+    )
+
+
+def log_end(
+    success: bool, steps: int, score: float, rewards: List[float]
+) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} "
+        f"score={score:.3f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# =========================================================================
+# System prompts per task
+# =========================================================================
+
+SYSTEM_PROMPTS = {
+    "easy": textwrap.dedent("""
+        You are an API debugging expert. You receive a broken API request and its specification.
+        Your job: identify the error type and the affected fields.
+
+        Respond with ONLY a JSON object in this format:
+        {"error_type": "<type>", "affected_fields": ["field1", "field2"]}
+
+        Valid error types:
+        missing_required_field, wrong_field_type, invalid_email_format,
+        missing_auth_header, extra_unknown_field, null_value_in_required,
+        wrong_http_method, malformed_json_value, invalid_enum_value,
+        datetime_format_error
+    """).strip(),
+
+    "medium": textwrap.dedent("""
+        You are an API debugging expert. You receive a broken API request and its specification.
+        Your job: fix the request so it matches the spec.
+
+        Respond with ONLY a JSON object in this format:
+        {"fixed_request": "<valid JSON string matching the spec>", "fixed_headers": {"Header": "value"}}
+
+        The fixed_request must be a valid JSON string. Include all required fields with correct types.
+    """).strip(),
+
+    "hard": textwrap.dedent("""
+        You are an API debugging expert. You receive a broken API request with multiple errors.
+        Your job: diagnose the errors, fix the request, and explain the fix for a developer.
+
+        Respond with ONLY a JSON object in this format:
+        {
+            "error_type": "<primary error type>",
+            "affected_fields": ["field1"],
+            "fixed_request": "<valid JSON string>",
+            "fixed_headers": {"Header": "value"},
+            "explanation": "Clear explanation of what was wrong and how to fix it."
+        }
+    """).strip(),
+}
+
+
+# =========================================================================
+# Prompt building
+# =========================================================================
+
+def build_user_prompt(obs, step_num: int) -> str:
+    """Build the user prompt from the observation."""
+    parts = [
+        f"API: {obs.http_method} {obs.endpoint} ({obs.api_name})",
+        f"Error count: {obs.error_count}",
+        f"Step {step_num}/{obs.max_steps}",
+        f"\nBroken request body:\n{obs.broken_request}",
+        f"\nRequest headers: {json.dumps(obs.broken_headers)}",
+        f"\nAPI Specification:\n{obs.api_spec}",
+    ]
+    if obs.feedback:
+        parts.append(f"\nFeedback from previous attempt:\n{obs.feedback}")
+    return "\n".join(parts)
+
+
+# =========================================================================
+# LLM response parsing
+# =========================================================================
+
+def parse_llm_response(text: str) -> dict:
+    """Extract a JSON object from the LLM response.
+
+    Handles cases where the LLM wraps JSON in markdown code blocks
+    or adds extra text around it.
+    """
+    if not text:
+        return {}
+
+    # Try direct parse first
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    # Try extracting from markdown code block
+    code_block = re.search(r"```(?:json)?\s*\n?(.*?)\n?\s*```", text, re.DOTALL)
+    if code_block:
+        try:
+            return json.loads(code_block.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    # Try finding any JSON object in the text
+    brace_match = re.search(r"\{[^{}]*\}", text, re.DOTALL)
+    if brace_match:
+        try:
+            return json.loads(brace_match.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    return {}
+
+
+def build_action(data: dict) -> APIDebugAction:
+    """Convert parsed JSON dict to APIDebugAction."""
+    # Handle fixed_request: if it's a dict, serialize to JSON string
+    fixed_req = data.get("fixed_request")
+    if isinstance(fixed_req, dict):
+        fixed_req = json.dumps(fixed_req)
+
+    return APIDebugAction(
+        error_type=data.get("error_type"),
+        affected_fields=data.get("affected_fields"),
+        fixed_request=fixed_req,
+        fixed_headers=data.get("fixed_headers"),
+        explanation=data.get("explanation"),
+    )
+
+
+# =========================================================================
+# Episode runner
+# =========================================================================
+
+async def run_episode(
+    env: APIDebugEnv,
+    llm_client: OpenAI,
+    task: str,
+) -> float:
+    """Run a single episode for the given task. Returns the final score."""
+    log_start(task=task, env=BENCHMARK_NAME, model=MODEL_NAME)
+
+    result = await env.reset(task=task)
+    obs = result.observation
+    rewards: List[float] = []
+    steps_taken = 0
+
+    max_steps = MAX_STEPS[task]
+
+    for step in range(1, max_steps + 1):
+        if result.done:
+            break
+
+        user_prompt = build_user_prompt(obs, step)
+
+        # Call the LLM
+        try:
+            completion = llm_client.chat.completions.create(
+                model=MODEL_NAME,
+                messages=[
+                    {"role": "system", "content": SYSTEM_PROMPTS[task]},
+                    {"role": "user", "content": user_prompt},
+                ],
+                max_tokens=500,
+                temperature=0.0,
+            )
+            llm_text = completion.choices[0].message.content or ""
+        except Exception as exc:
+            print(f"[DEBUG] LLM request failed: {exc}", flush=True)
+            llm_text = ""
+
+        # Parse LLM output into action
+        parsed = parse_llm_response(llm_text)
+        action = build_action(parsed)
+
+        # Step the environment
+        result = await env.step(action)
+        obs = result.observation
+        reward = result.reward or 0.0
+        done = result.done
+
+        rewards.append(reward)
+        steps_taken = step
+
+        # Build a short action summary for the log
+        action_summary = _action_summary(action, task)
+        log_step(step=step, action=action_summary, reward=reward, done=done, error=None)
+
+        if done:
+            break
+
+    # Final score is the max reward achieved (environment already tracks best)
+    score = max(rewards) if rewards else 0.0
+    score = min(max(score, 0.0), 1.0)
+    success = score >= 0.5
+
+    log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+    return score
+
+
+def _action_summary(action: APIDebugAction, task: str) -> str:
+    """Short summary of the action for logging."""
+    if task == "easy":
+        return f"diagnose:{action.error_type or 'none'}"
+    elif task == "medium":
+        fix_len = len(action.fixed_request or "")
+        return f"fix:len={fix_len}"
+    else:
+        fix_len = len(action.fixed_request or "")
+        exp_len = len(action.explanation or "")
+        return f"fix:len={fix_len}+explain:len={exp_len}"
+
+
+# =========================================================================
+# Main
+# =========================================================================
+
+async def main() -> None:
+    llm_client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+
+    # Connect to environment (via Docker image or direct URL)
+    if IMAGE_NAME:
+        env = await APIDebugEnv.from_docker_image(IMAGE_NAME)
+    else:
+        env = APIDebugEnv(base_url=ENV_URL)
+
+    all_scores: dict = {}
+
+    try:
+        for task in TASKS:
+            task_scores = []
+            for ep in range(EPISODES_PER_TASK):
+                score = await run_episode(env, llm_client, task)
+                task_scores.append(score)
+            avg = sum(task_scores) / len(task_scores)
+            all_scores[task] = avg
+
+        # Print summary
+        print("\n--- Baseline Scores ---", flush=True)
+        for task, avg in all_scores.items():
+            print(f"  {task}: {avg:.3f}", flush=True)
+        overall = sum(all_scores.values()) / len(all_scores)
+        print(f"  overall: {overall:.3f}", flush=True)
+
+    finally:
+        try:
+            await env.close()
+        except Exception as e:
+            print(f"[DEBUG] env.close() error: {e}", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,96 @@
+"""
+Pydantic models for the API Debug Environment.
+
+APIDebugAction: What the agent sends each step.
+APIDebugObservation: What the environment returns each step.
+
+All Action fields are Optional so the agent can submit only what it has.
+For example, on an easy task the agent only needs error_type and affected_fields.
+On medium, it needs fixed_request. On hard, it needs everything plus explanation.
+"""
+
+from typing import Dict, List, Optional
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import Field
+
+
+class APIDebugAction(Action):
+    """Agent's response at each step of the debugging episode."""
+
+    error_type: Optional[str] = Field(
+        default=None,
+        description="Diagnosed error type, e.g. 'missing_required_field'"
+    )
+    affected_fields: Optional[List[str]] = Field(
+        default=None,
+        description="List of field names affected by the error"
+    )
+    fixed_request: Optional[str] = Field(
+        default=None,
+        description="JSON string of the corrected request body"
+    )
+    fixed_headers: Optional[Dict[str, str]] = Field(
+        default=None,
+        description="Corrected HTTP headers if applicable"
+    )
+    explanation: Optional[str] = Field(
+        default=None,
+        description="Developer-facing explanation of the fix (hard task only)"
+    )
+
+
+class APIDebugObservation(Observation):
+    """Environment's response at each step.
+
+    Inherits done, reward, and metadata from Observation base class.
+    """
+
+    task: str = Field(
+        default="easy",
+        description="Current task difficulty: easy, medium, hard"
+    )
+    api_name: str = Field(
+        default="",
+        description="Name of the API being debugged"
+    )
+    http_method: str = Field(
+        default="POST",
+        description="HTTP method of the broken request"
+    )
+    endpoint: str = Field(
+        default="",
+        description="API endpoint path"
+    )
+    broken_request: str = Field(
+        default="",
+        description="JSON string of the malformed request body"
+    )
+    broken_headers: Dict[str, str] = Field(
+        default_factory=dict,
+        description="HTTP headers sent with the broken request"
+    )
+    api_spec: str = Field(
+        default="",
+        description="JSON string of the API specification"
+    )
+    error_count: int = Field(
+        default=1,
+        description="Number of errors injected in this episode"
+    )
+    step_number: int = Field(
+        default=0,
+        description="Current step in this episode"
+    )
+    max_steps: int = Field(
+        default=3,
+        description="Maximum steps allowed for this task"
+    )
+    feedback: str = Field(
+        default="",
+        description="Structured validation feedback from the last action"
+    )
+    message: str = Field(
+        default="",
+        description="Human-readable status message"
+    )

openenv.yaml

@@ -0,0 +1,5 @@
+name: api-debug-env
+version: 0.1.0
+description: API Contract Validation RL environment for debugging malformed API requests
+sdk: docker
+dockerfile: Dockerfile

pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "api-debug-env"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core",
+    "fastapi",
+    "uvicorn[standard]",
+    "pydantic",
+    "websockets",
+    "openai",
+]
+
+[project.scripts]
+server = "server.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

requirements.txt

@@ -0,0 +1,6 @@
+openenv-core
+fastapi
+uvicorn[standard]
+pydantic
+websockets
+openai

server/__init__.py

@@ -0,0 +1,3 @@
+from .environment import APIDebugEnvironment
+
+__all__ = ["APIDebugEnvironment"]

server/api_specs.py

@@ -0,0 +1,639 @@
+"""
+30 API spec templates covering 6 real-world domains.
+
+Each spec defines:
+- api_name: Human-readable name
+- http_method: GET, POST, PUT, PATCH, DELETE
+- endpoint: API path
+- required_headers: Headers that must be present
+- required_fields: Fields that must be in the request body
+- optional_fields: Fields that may be in the request body
+- field_types: Expected type for each field (used for validation)
+- valid_example: A correct request body (used to generate broken requests)
+
+Supported field types:
+- "string", "integer", "float", "boolean"
+- "email" (validated by regex)
+- "datetime" (ISO 8601 format)
+- "enum:val1,val2,val3" (one of the listed values)
+- "url" (validated by pattern)
+- "phone" (validated by pattern)
+- "object" (nested dict, not deeply validated)
+- "array" (list)
+"""
+
+from typing import Any, Dict, List
+
+
+def _spec(
+    api_name: str,
+    http_method: str,
+    endpoint: str,
+    required_fields: List[str],
+    field_types: Dict[str, str],
+    valid_example: Dict[str, Any],
+    optional_fields: List[str] = None,
+    required_headers: Dict[str, str] = None,
+) -> Dict[str, Any]:
+    """Build a spec dict with sensible defaults."""
+    return {
+        "api_name": api_name,
+        "http_method": http_method,
+        "endpoint": endpoint,
+        "required_headers": required_headers or {
+            "Authorization": "Bearer sk_test_abc123",
+            "Content-Type": "application/json",
+        },
+        "required_fields": required_fields,
+        "optional_fields": optional_fields or [],
+        "field_types": field_types,
+        "valid_example": valid_example,
+    }
+
+
+# =========================================================================
+# Domain 1: Payment APIs (Stripe-like)
+# =========================================================================
+
+PAYMENT_SPECS = [
+    _spec(
+        api_name="Create Customer",
+        http_method="POST",
+        endpoint="/v1/customers",
+        required_fields=["email", "name"],
+        optional_fields=["phone", "description", "address"],
+        field_types={
+            "email": "email",
+            "name": "string",
+            "phone": "phone",
+            "description": "string",
+            "address": "object",
+        },
+        valid_example={
+            "email": "alice@example.com",
+            "name": "Alice Johnson",
+        },
+    ),
+    _spec(
+        api_name="Create Charge",
+        http_method="POST",
+        endpoint="/v1/charges",
+        required_fields=["amount", "currency", "customer_id"],
+        optional_fields=["description", "receipt_email"],
+        field_types={
+            "amount": "integer",
+            "currency": "enum:usd,eur,gbp,inr,jpy",
+            "customer_id": "string",
+            "description": "string",
+            "receipt_email": "email",
+        },
+        valid_example={
+            "amount": 2500,
+            "currency": "usd",
+            "customer_id": "cus_abc123",
+        },
+    ),
+    _spec(
+        api_name="Create Subscription",
+        http_method="POST",
+        endpoint="/v1/subscriptions",
+        required_fields=["customer_id", "plan_id", "start_date"],
+        optional_fields=["trial_days", "auto_renew"],
+        field_types={
+            "customer_id": "string",
+            "plan_id": "string",
+            "start_date": "datetime",
+            "trial_days": "integer",
+            "auto_renew": "boolean",
+        },
+        valid_example={
+            "customer_id": "cus_abc123",
+            "plan_id": "plan_monthly_pro",
+            "start_date": "2026-04-01T00:00:00Z",
+        },
+    ),
+    _spec(
+        api_name="Process Refund",
+        http_method="POST",
+        endpoint="/v1/refunds",
+        required_fields=["charge_id", "amount"],
+        optional_fields=["reason"],
+        field_types={
+            "charge_id": "string",
+            "amount": "integer",
+            "reason": "enum:duplicate,fraudulent,requested_by_customer",
+        },
+        valid_example={
+            "charge_id": "ch_abc123",
+            "amount": 1500,
+        },
+    ),
+    _spec(
+        api_name="List Transactions",
+        http_method="GET",
+        endpoint="/v1/transactions",
+        required_fields=["account_id"],
+        optional_fields=["start_date", "end_date", "limit"],
+        field_types={
+            "account_id": "string",
+            "start_date": "datetime",
+            "end_date": "datetime",
+            "limit": "integer",
+        },
+        valid_example={
+            "account_id": "acc_abc123",
+        },
+    ),
+]
+
+# =========================================================================
+# Domain 2: User Management
+# =========================================================================
+
+USER_SPECS = [
+    _spec(
+        api_name="Create User",
+        http_method="POST",
+        endpoint="/api/users",
+        required_fields=["email", "username", "password"],
+        optional_fields=["full_name", "role"],
+        field_types={
+            "email": "email",
+            "username": "string",
+            "password": "string",
+            "full_name": "string",
+            "role": "enum:admin,editor,viewer",
+        },
+        valid_example={
+            "email": "bob@example.com",
+            "username": "bob_smith",
+            "password": "SecurePass123!",
+        },
+    ),
+    _spec(
+        api_name="Update Profile",
+        http_method="PATCH",
+        endpoint="/api/users/{user_id}/profile",
+        required_fields=["user_id", "display_name"],
+        optional_fields=["bio", "avatar_url", "timezone"],
+        field_types={
+            "user_id": "string",
+            "display_name": "string",
+            "bio": "string",
+            "avatar_url": "url",
+            "timezone": "string",
+        },
+        valid_example={
+            "user_id": "usr_abc123",
+            "display_name": "Bob Smith",
+        },
+    ),
+    _spec(
+        api_name="Reset Password",
+        http_method="POST",
+        endpoint="/api/auth/reset-password",
+        required_fields=["email"],
+        optional_fields=["redirect_url"],
+        field_types={
+            "email": "email",
+            "redirect_url": "url",
+        },
+        valid_example={
+            "email": "bob@example.com",
+        },
+    ),
+    _spec(
+        api_name="Verify Email",
+        http_method="POST",
+        endpoint="/api/auth/verify-email",
+        required_fields=["token", "email"],
+        field_types={
+            "token": "string",
+            "email": "email",
+        },
+        valid_example={
+            "token": "verify_abc123xyz",
+            "email": "bob@example.com",
+        },
+    ),
+    _spec(
+        api_name="Delete Account",
+        http_method="DELETE",
+        endpoint="/api/users/{user_id}",
+        required_fields=["user_id", "confirmation"],
+        field_types={
+            "user_id": "string",
+            "confirmation": "enum:DELETE,CONFIRM",
+        },
+        valid_example={
+            "user_id": "usr_abc123",
+            "confirmation": "DELETE",
+        },
+    ),
+]
+
+# =========================================================================
+# Domain 3: Content APIs (GitHub-like)
+# =========================================================================
+
+CONTENT_SPECS = [
+    _spec(
+        api_name="Create Repository",
+        http_method="POST",
+        endpoint="/api/repos",
+        required_fields=["name", "visibility"],
+        optional_fields=["description", "auto_init", "license"],
+        field_types={
+            "name": "string",
+            "visibility": "enum:public,private,internal",
+            "description": "string",
+            "auto_init": "boolean",
+            "license": "string",
+        },
+        valid_example={
+            "name": "my-project",
+            "visibility": "public",
+        },
+    ),
+    _spec(
+        api_name="Create Issue",
+        http_method="POST",
+        endpoint="/api/repos/{repo_id}/issues",
+        required_fields=["title", "repo_id"],
+        optional_fields=["body", "assignee", "labels", "priority"],
+        field_types={
+            "title": "string",
+            "repo_id": "string",
+            "body": "string",
+            "assignee": "string",
+            "labels": "array",
+            "priority": "enum:low,medium,high,critical",
+        },
+        valid_example={
+            "title": "Fix login page redirect",
+            "repo_id": "repo_abc123",
+        },
+    ),
+    _spec(
+        api_name="Create Comment",
+        http_method="POST",
+        endpoint="/api/issues/{issue_id}/comments",
+        required_fields=["issue_id", "body"],
+        optional_fields=["mentions"],
+        field_types={
+            "issue_id": "string",
+            "body": "string",
+            "mentions": "array",
+        },
+        valid_example={
+            "issue_id": "issue_abc123",
+            "body": "This looks like a duplicate of #42.",
+        },
+    ),
+    _spec(
+        api_name="Merge Pull Request",
+        http_method="PUT",
+        endpoint="/api/repos/{repo_id}/pulls/{pr_id}/merge",
+        required_fields=["repo_id", "pr_id", "merge_method"],
+        optional_fields=["commit_title", "delete_branch"],
+        field_types={
+            "repo_id": "string",
+            "pr_id": "string",
+            "merge_method": "enum:merge,squash,rebase",
+            "commit_title": "string",
+            "delete_branch": "boolean",
+        },
+        valid_example={
+            "repo_id": "repo_abc123",
+            "pr_id": "pr_456",
+            "merge_method": "squash",
+        },
+    ),
+    _spec(
+        api_name="Create Release",
+        http_method="POST",
+        endpoint="/api/repos/{repo_id}/releases",
+        required_fields=["repo_id", "tag_name", "name"],
+        optional_fields=["body", "draft", "prerelease"],
+        field_types={
+            "repo_id": "string",
+            "tag_name": "string",
+            "name": "string",
+            "body": "string",
+            "draft": "boolean",
+            "prerelease": "boolean",
+        },
+        valid_example={
+            "repo_id": "repo_abc123",
+            "tag_name": "v1.0.0",
+            "name": "Version 1.0.0",
+        },
+    ),
+]
+
+# =========================================================================
+# Domain 4: Messaging (Twilio-like)
+# =========================================================================
+
+MESSAGING_SPECS = [
+    _spec(
+        api_name="Send SMS",
+        http_method="POST",
+        endpoint="/api/messages/sms",
+        required_fields=["to", "from_number", "body"],
+        optional_fields=["callback_url"],
+        field_types={
+            "to": "phone",
+            "from_number": "phone",
+            "body": "string",
+            "callback_url": "url",
+        },
+        valid_example={
+            "to": "+14155551234",
+            "from_number": "+14155550000",
+            "body": "Your verification code is 123456",
+        },
+    ),
+    _spec(
+        api_name="Send Email",
+        http_method="POST",
+        endpoint="/api/messages/email",
+        required_fields=["to_email", "subject", "body"],
+        optional_fields=["cc", "bcc", "reply_to"],
+        field_types={
+            "to_email": "email",
+            "subject": "string",
+            "body": "string",
+            "cc": "email",
+            "bcc": "email",
+            "reply_to": "email",
+        },
+        valid_example={
+            "to_email": "customer@example.com",
+            "subject": "Order Confirmation",
+            "body": "Your order #1234 has been confirmed.",
+        },
+    ),
+    _spec(
+        api_name="Create Webhook",
+        http_method="POST",
+        endpoint="/api/webhooks",
+        required_fields=["url", "events"],
+        optional_fields=["secret", "active"],
+        field_types={
+            "url": "url",
+            "events": "array",
+            "secret": "string",
+            "active": "boolean",
+        },
+        valid_example={
+            "url": "https://myapp.com/webhook",
+            "events": ["message.sent", "message.delivered"],
+        },
+    ),
+    _spec(
+        api_name="Create Template",
+        http_method="POST",
+        endpoint="/api/templates",
+        required_fields=["name", "content", "channel"],
+        optional_fields=["variables", "language"],
+        field_types={
+            "name": "string",
+            "content": "string",
+            "channel": "enum:sms,email,push",
+            "variables": "array",
+            "language": "string",
+        },
+        valid_example={
+            "name": "welcome_message",
+            "content": "Hello {{name}}, welcome to our service!",
+            "channel": "email",
+        },
+    ),
+    _spec(
+        api_name="Verify Phone",
+        http_method="POST",
+        endpoint="/api/verify/phone",
+        required_fields=["phone_number", "code"],
+        field_types={
+            "phone_number": "phone",
+            "code": "string",
+        },
+        valid_example={
+            "phone_number": "+14155551234",
+            "code": "123456",
+        },
+    ),
+]
+
+# =========================================================================
+# Domain 5: E-Commerce
+# =========================================================================
+
+ECOMMERCE_SPECS = [
+    _spec(
+        api_name="Create Order",
+        http_method="POST",
+        endpoint="/api/orders",
+        required_fields=["customer_id", "items", "shipping_address"],
+        optional_fields=["notes", "coupon_code"],
+        field_types={
+            "customer_id": "string",
+            "items": "array",
+            "shipping_address": "object",
+            "notes": "string",
+            "coupon_code": "string",
+        },
+        valid_example={
+            "customer_id": "cust_abc123",
+            "items": [{"product_id": "prod_1", "quantity": 2}],
+            "shipping_address": {"line1": "123 Main St", "city": "Portland", "zip": "97201"},
+        },
+    ),
+    _spec(
+        api_name="Add Cart Item",
+        http_method="POST",
+        endpoint="/api/cart/items",
+        required_fields=["product_id", "quantity"],
+        optional_fields=["variant_id", "notes"],
+        field_types={
+            "product_id": "string",
+            "quantity": "integer",
+            "variant_id": "string",
+            "notes": "string",
+        },
+        valid_example={
+            "product_id": "prod_abc123",
+            "quantity": 1,
+        },
+    ),
+    _spec(
+        api_name="Process Payment",
+        http_method="POST",
+        endpoint="/api/payments",
+        required_fields=["order_id", "amount", "currency", "payment_method"],
+        optional_fields=["billing_email"],
+        field_types={
+            "order_id": "string",
+            "amount": "float",
+            "currency": "enum:usd,eur,gbp,inr",
+            "payment_method": "enum:card,bank_transfer,wallet",
+            "billing_email": "email",
+        },
+        valid_example={
+            "order_id": "ord_abc123",
+            "amount": 49.99,
+            "currency": "usd",
+            "payment_method": "card",
+        },
+    ),
+    _spec(
+        api_name="Apply Coupon",
+        http_method="POST",
+        endpoint="/api/cart/coupon",
+        required_fields=["coupon_code", "cart_id"],
+        field_types={
+            "coupon_code": "string",
+            "cart_id": "string",
+        },
+        valid_example={
+            "coupon_code": "SAVE20",
+            "cart_id": "cart_abc123",
+        },
+    ),
+    _spec(
+        api_name="Create Shipping Label",
+        http_method="POST",
+        endpoint="/api/shipping/labels",
+        required_fields=["order_id", "carrier", "weight"],
+        optional_fields=["insurance", "signature_required"],
+        field_types={
+            "order_id": "string",
+            "carrier": "enum:usps,fedex,ups,dhl",
+            "weight": "float",
+            "insurance": "boolean",
+            "signature_required": "boolean",
+        },
+        valid_example={
+            "order_id": "ord_abc123",
+            "carrier": "usps",
+            "weight": 2.5,
+        },
+    ),
+]
+
+# =========================================================================
+# Domain 6: Calendar and Auth
+# =========================================================================
+
+CALENDAR_AUTH_SPECS = [
+    _spec(
+        api_name="Create Event",
+        http_method="POST",
+        endpoint="/api/calendar/events",
+        required_fields=["title", "start_time", "end_time"],
+        optional_fields=["description", "location", "attendees", "recurrence"],
+        field_types={
+            "title": "string",
+            "start_time": "datetime",
+            "end_time": "datetime",
+            "description": "string",
+            "location": "string",
+            "attendees": "array",
+            "recurrence": "enum:none,daily,weekly,monthly",
+        },
+        valid_example={
+            "title": "Team Standup",
+            "start_time": "2026-04-05T09:00:00Z",
+            "end_time": "2026-04-05T09:30:00Z",
+        },
+    ),
+    _spec(
+        api_name="OAuth Token Request",
+        http_method="POST",
+        endpoint="/oauth/token",
+        required_fields=["grant_type", "client_id", "client_secret"],
+        optional_fields=["scope", "redirect_uri"],
+        field_types={
+            "grant_type": "enum:authorization_code,client_credentials,refresh_token",
+            "client_id": "string",
+            "client_secret": "string",
+            "scope": "string",
+            "redirect_uri": "url",
+        },
+        valid_example={
+            "grant_type": "client_credentials",
+            "client_id": "app_abc123",
+            "client_secret": "secret_xyz789",
+        },
+        required_headers={
+            "Content-Type": "application/json",
+        },
+    ),
+    _spec(
+        api_name="Create API Key",
+        http_method="POST",
+        endpoint="/api/keys",
+        required_fields=["name", "permissions"],
+        optional_fields=["expires_at"],
+        field_types={
+            "name": "string",
+            "permissions": "array",
+            "expires_at": "datetime",
+        },
+        valid_example={
+            "name": "production-key",
+            "permissions": ["read", "write"],
+        },
+    ),
+    _spec(
+        api_name="Invite User",
+        http_method="POST",
+        endpoint="/api/teams/{team_id}/invites",
+        required_fields=["team_id", "email", "role"],
+        optional_fields=["message"],
+        field_types={
+            "team_id": "string",
+            "email": "email",
+            "role": "enum:admin,member,viewer",
+            "message": "string",
+        },
+        valid_example={
+            "team_id": "team_abc123",
+            "email": "newuser@example.com",
+            "role": "member",
+        },
+    ),
+    _spec(
+        api_name="Update Permissions",
+        http_method="PUT",
+        endpoint="/api/users/{user_id}/permissions",
+        required_fields=["user_id", "permissions"],
+        optional_fields=["effective_from"],
+        field_types={
+            "user_id": "string",
+            "permissions": "array",
+            "effective_from": "datetime",
+        },
+        valid_example={
+            "user_id": "usr_abc123",
+            "permissions": ["read", "write", "admin"],
+        },
+    ),
+]
+
+
+# All 30 specs in a single flat list
+ALL_SPECS = (
+    PAYMENT_SPECS
+    + USER_SPECS
+    + CONTENT_SPECS
+    + MESSAGING_SPECS
+    + ECOMMERCE_SPECS
+    + CALENDAR_AUTH_SPECS
+)
+
+
+def get_random_spec(rng) -> Dict[str, Any]:
+    """Pick a random spec using the provided RNG instance."""
+    return rng.choice(ALL_SPECS)

server/app.py

@@ -0,0 +1,39 @@
+"""
+FastAPI application for the API Debug Environment.
+
+Uses OpenEnv's create_app() to generate all endpoints:
+POST /reset, POST /step, GET /state, GET /schema, WS /ws, GET /health
+"""
+
+from openenv.core.env_server.http_server import create_app
+
+try:
+    from ..models import APIDebugAction, APIDebugObservation
+    from .environment import APIDebugEnvironment
+except ImportError:
+    from models import APIDebugAction, APIDebugObservation
+    from server.environment import APIDebugEnvironment
+
+app = create_app(
+    APIDebugEnvironment,
+    APIDebugAction,
+    APIDebugObservation,
+    env_name="api_debug",
+    max_concurrent_envs=10,
+)
+
+
+def main():
+    """Run the server directly."""
+    import sys
+    import uvicorn
+
+    port = 8000
+    if len(sys.argv) > 1:
+        port = int(sys.argv[1])
+
+    uvicorn.run(app, host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()

server/environment.py

@@ -0,0 +1,456 @@
+"""
+Core environment for the API Debug Environment.
+
+Implements the OpenEnv Environment interface with:
+- 3 task difficulty levels (easy, medium, hard)
+- Multi-turn episodes with structured feedback
+- Deterministic grading for easy/medium, LLM-as-judge for hard
+- Step reward decay to encourage efficient debugging
+"""
+
+import copy
+import json
+import os
+import random
+from typing import Any, Dict, List, Optional, Tuple
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import APIDebugAction, APIDebugObservation
+except ImportError:
+    from models import APIDebugAction, APIDebugObservation
+
+from .api_specs import get_random_spec
+from .error_injectors import (
+    ERROR_TYPES,
+    inject_error,
+    inject_multiple_errors,
+)
+from .validators import (
+    validate_field_type,
+    validate_headers_against_spec,
+    validate_request_against_spec,
+)
+
+
+# Task configuration: max steps and error count per difficulty
+TASK_CONFIG = {
+    "easy": {"max_steps": 3, "error_count": 1},
+    "medium": {"max_steps": 5, "error_count": 1},
+    "hard": {"max_steps": 7, "min_errors": 2, "max_errors": 3},
+}
+
+
+class APIDebugEnvironment(Environment):
+    """API Contract Validation environment.
+
+    An LLM agent receives a broken API request and must:
+    - Easy: Identify the error type and affected fields
+    - Medium: Fix the request to match the API spec
+    - Hard: Fix the request and explain the fix for developers
+
+    Each episode allows multiple attempts. Perfect answers on early
+    steps get full reward. Later steps get decayed reward.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        super().__init__()
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self.task = "easy"
+        self.spec: Dict[str, Any] = {}
+        self.broken_request: Dict[str, Any] = {}
+        self.broken_headers: Dict[str, str] = {}
+        self.ground_truths: List[Dict[str, Any]] = []
+        self.current_step = 0
+        self.max_steps = 3
+        self.episode_done = False
+        self.best_reward = 0.0
+        self.rng = random.Random()
+        # For wrong_http_method error: the method shown to the agent
+        self.shown_http_method = ""
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        task: str = "easy",
+        **kwargs,
+    ) -> APIDebugObservation:
+        """Start a new debugging episode.
+
+        Args:
+            seed: Random seed for reproducible episodes.
+            episode_id: Custom episode identifier.
+            task: Difficulty level (easy, medium, hard).
+        """
+        # Initialize RNG
+        if seed is not None:
+            self.rng = random.Random(seed)
+        else:
+            self.rng = random.Random()
+
+        # Validate task
+        self.task = task if task in TASK_CONFIG else "easy"
+        config = TASK_CONFIG[self.task]
+        self.max_steps = config["max_steps"]
+        self.current_step = 0
+        self.episode_done = False
+        self.best_reward = 0.0
+
+        # Fresh state
+        self._state = State(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+        )
+
+        # Pick random spec and build valid request
+        self.spec = copy.deepcopy(get_random_spec(self.rng))
+        valid_request = copy.deepcopy(self.spec["valid_example"])
+        valid_headers = copy.deepcopy(self.spec["required_headers"])
+
+        # Inject errors based on difficulty
+        if self.task == "hard":
+            error_count = self.rng.randint(config["min_errors"], config["max_errors"])
+            self.broken_request, self.broken_headers, self.ground_truths = (
+                inject_multiple_errors(
+                    valid_request, valid_headers, self.spec, self.rng, error_count
+                )
+            )
+        else:
+            error_type = self.rng.choice(ERROR_TYPES)
+            self.broken_request, self.broken_headers, gt = inject_error(
+                error_type, valid_request, valid_headers, self.spec, self.rng
+            )
+            self.ground_truths = [gt]
+
+        # Handle wrong_http_method: show the wrong method to the agent
+        self.shown_http_method = self.spec["http_method"]
+        for gt in self.ground_truths:
+            if gt["error_type"] == "wrong_http_method":
+                self.shown_http_method = gt.get("wrong_method", self.spec["http_method"])
+                break
+
+        error_count = len(self.ground_truths)
+        return APIDebugObservation(
+            task=self.task,
+            api_name=self.spec["api_name"],
+            http_method=self.shown_http_method,
+            endpoint=self.spec["endpoint"],
+            broken_request=json.dumps(self.broken_request, indent=2),
+            broken_headers=self.broken_headers,
+            api_spec=self._build_spec_string(),
+            error_count=error_count,
+            step_number=0,
+            max_steps=self.max_steps,
+            feedback="",
+            message=(
+                f"Debug this {self.shown_http_method} {self.spec['endpoint']} request. "
+                f"It contains {error_count} error(s). "
+                f"You have {self.max_steps} steps."
+            ),
+            done=False,
+            reward=0.0,
+        )
+
+    def step(
+        self,
+        action: APIDebugAction,
+        timeout_s: Optional[float] = None,
+        **kwargs,
+    ) -> APIDebugObservation:
+        """Process the agent's debugging attempt.
+
+        The agent can submit a partial or complete response.
+        The grader evaluates whatever fields are present.
+        """
+        self.current_step += 1
+        self._state.step_count = self.current_step
+
+        if self.episode_done:
+            return self._make_observation(
+                feedback="Episode already ended.",
+                reward=0.0,
+                done=True,
+            )
+
+        # Grade based on task type
+        if self.task == "easy":
+            raw_score, feedback = self._grade_easy(action)
+        elif self.task == "medium":
+            raw_score, feedback = self._grade_medium(action)
+        else:
+            raw_score, feedback = self._grade_hard(action)
+
+        # Apply step decay: step 1 = 1.0x, step 2 = 0.9x, etc. Floor at 0.3x
+        step_multiplier = max(1.0 - 0.1 * (self.current_step - 1), 0.3)
+        reward = round(raw_score * step_multiplier, 4)
+
+        # Track best reward across all steps
+        self.best_reward = max(self.best_reward, reward)
+
+        # Episode ends if score is near-perfect or out of steps
+        near_perfect = raw_score >= 0.95
+        out_of_steps = self.current_step >= self.max_steps
+        done = near_perfect or out_of_steps
+
+        if done:
+            self.episode_done = True
+            # Return best reward achieved during the episode
+            reward = self.best_reward
+
+        return self._make_observation(
+            feedback=feedback,
+            reward=reward,
+            done=done,
+        )
+
+    @property
+    def state(self) -> State:
+        return self._state
+
+    # =====================================================================
+    # Grading methods
+    # =====================================================================
+
+    def _grade_easy(self, action: APIDebugAction) -> Tuple[float, str]:
+        """Grade error identification. Fully deterministic.
+
+        Scoring: 0.6 for correct error_type + 0.4 for correct affected_fields.
+        Fields use Jaccard similarity for partial credit.
+        """
+        score = 0.0
+        parts = []
+
+        # Collect all ground truth error types and affected fields
+        gt_types = {gt["error_type"] for gt in self.ground_truths}
+        gt_fields: set = set()
+        for gt in self.ground_truths:
+            gt_fields.update(gt.get("affected_fields", []))
+
+        # Check error type (0.6 weight)
+        if action.error_type and action.error_type in gt_types:
+            score += 0.6
+            parts.append("error_type: CORRECT")
+        else:
+            given = action.error_type or "(none)"
+            parts.append(f"error_type: INCORRECT (you said '{given}')")
+
+        # Check affected fields using Jaccard similarity (0.4 weight)
+        agent_fields = set(action.affected_fields or [])
+        if gt_fields and agent_fields:
+            intersection = gt_fields & agent_fields
+            union = gt_fields | agent_fields
+            jaccard = len(intersection) / len(union) if union else 0.0
+            score += 0.4 * jaccard
+            parts.append(
+                f"affected_fields: {len(intersection)}/{len(gt_fields)} correct, "
+                f"{len(agent_fields - gt_fields)} extra"
+            )
+        elif not agent_fields:
+            parts.append("affected_fields: MISSING (none provided)")
+        else:
+            parts.append("affected_fields: INCORRECT (0 matches)")
+
+        return round(score, 4), "; ".join(parts)
+
+    def _grade_medium(self, action: APIDebugAction) -> Tuple[float, str]:
+        """Grade request fix. Fully deterministic per-field validation.
+
+        Validates the fixed request against the spec: required fields present,
+        field types correct, headers present. Each check is equally weighted.
+        """
+        if not action.fixed_request:
+            return 0.0, "No fixed_request provided."
+
+        try:
+            fixed = json.loads(action.fixed_request)
+        except (json.JSONDecodeError, TypeError):
+            return 0.0, "fixed_request is not valid JSON."
+
+        if not isinstance(fixed, dict):
+            return 0.0, "fixed_request must be a JSON object."
+
+        # Validate request body against spec
+        body_score, body_feedback = validate_request_against_spec(fixed, self.spec)
+
+        # Validate headers if provided
+        header_score = 0.0
+        header_feedback = ""
+        has_header_errors = any(
+            gt["error_type"] == "missing_auth_header" for gt in self.ground_truths
+        )
+
+        if has_header_errors and action.fixed_headers:
+            header_score, header_feedback = validate_headers_against_spec(
+                action.fixed_headers, self.spec
+            )
+            # Blend: 80% body + 20% headers when header errors exist
+            total_score = 0.8 * body_score + 0.2 * header_score
+            feedback = body_feedback + "\n" + header_feedback
+        elif has_header_errors and not action.fixed_headers:
+            feedback = body_feedback + "\nHeaders: NOT PROVIDED (header fix needed)"
+            total_score = 0.8 * body_score
+        else:
+            total_score = body_score
+            feedback = body_feedback
+
+        return round(total_score, 4), feedback
+
+    def _grade_hard(self, action: APIDebugAction) -> Tuple[float, str]:
+        """Grade fix + explanation. 70% deterministic fix, 30% explanation.
+
+        The explanation is scored by LLM-as-judge if available,
+        with a heuristic fallback if the LLM is not reachable.
+        """
+        # Deterministic fix scoring (same as medium)
+        fix_score, fix_feedback = self._grade_medium(action)
+
+        # Explanation scoring
+        explain_score = 0.0
+        explain_feedback = "No explanation provided."
+
+        if action.explanation and len(action.explanation.strip()) > 10:
+            explain_score = self._score_explanation(action.explanation)
+            explain_feedback = f"Explanation quality: {explain_score:.2f}/1.0"
+
+        total = 0.7 * fix_score + 0.3 * explain_score
+        feedback = (
+            f"Fix score: {fix_score:.2f} (70% weight)\n"
+            f"{fix_feedback}\n"
+            f"{explain_feedback}"
+        )
+        return round(total, 4), feedback
+
+    def _score_explanation(self, explanation: str) -> float:
+        """Score an explanation using LLM-as-judge with heuristic fallback.
+
+        Tries to call the LLM via the HF router. If that fails for any
+        reason, falls back to a keyword + length heuristic.
+        """
+        # Try LLM-as-judge first
+        try:
+            llm_score = self._llm_judge_explanation(explanation)
+            if llm_score is not None:
+                return llm_score
+        except Exception:
+            pass
+
+        # Heuristic fallback
+        return self._heuristic_score_explanation(explanation)
+
+    def _llm_judge_explanation(self, explanation: str) -> Optional[float]:
+        """Call LLM to score the explanation. Returns None if unavailable."""
+        api_base = os.getenv("API_BASE_URL")
+        api_key = os.getenv("HF_TOKEN")
+        model = os.getenv("MODEL_NAME")
+
+        if not all([api_base, api_key, model]):
+            return None
+
+        from openai import OpenAI
+
+        client = OpenAI(base_url=api_base, api_key=api_key)
+
+        error_types = [gt["error_type"] for gt in self.ground_truths]
+        prompt = (
+            "Rate this API debugging explanation on a 0.0 to 1.0 scale.\n\n"
+            "Criteria:\n"
+            "- Correctly identifies root cause (0 to 0.4)\n"
+            "- Provides actionable fix guidance (0 to 0.3)\n"
+            "- Includes prevention advice for developers (0 to 0.3)\n\n"
+            f"API: {self.spec['api_name']} {self.spec['endpoint']}\n"
+            f"Errors present: {json.dumps(error_types)}\n"
+            f"Explanation: {explanation}\n\n"
+            'Return ONLY a JSON object: {"score": 0.0}'
+        )
+
+        response = client.chat.completions.create(
+            model=model,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=50,
+            temperature=0.0,
+        )
+        text = response.choices[0].message.content or ""
+
+        # Parse score from response
+        result = json.loads(text)
+        raw_score = float(result["score"])
+        return max(0.0, min(1.0, raw_score))
+
+    def _heuristic_score_explanation(self, explanation: str) -> float:
+        """Simple heuristic scoring based on length and keyword presence.
+
+        This is the fallback when LLM-as-judge is not available.
+        Not perfect, but ensures non-zero scores for reasonable explanations.
+        """
+        keywords = [
+            "because", "should", "instead", "required", "missing",
+            "type", "format", "expected", "invalid", "correct",
+            "field", "header", "value", "fix", "error",
+        ]
+        keyword_hits = sum(1 for k in keywords if k in explanation.lower())
+        keyword_score = min(keyword_hits / 6.0, 1.0)
+
+        # Length score: reward explanations between 50 and 500 chars
+        length = len(explanation.strip())
+        if length < 20:
+            length_score = 0.1
+        elif length < 50:
+            length_score = 0.3
+        elif length <= 500:
+            length_score = 0.6
+        else:
+            length_score = 0.5  # Slightly penalize very long explanations
+
+        return round(0.5 * keyword_score + 0.5 * length_score, 2)
+
+    # =====================================================================
+    # Helpers
+    # =====================================================================
+
+    def _build_spec_string(self) -> str:
+        """Build a JSON string of the spec info the agent needs to see."""
+        visible_spec = {
+            "required_fields": self.spec["required_fields"],
+            "optional_fields": self.spec.get("optional_fields", []),
+            "field_types": self.spec["field_types"],
+            "required_headers": list(self.spec.get("required_headers", {}).keys()),
+        }
+        return json.dumps(visible_spec, indent=2)
+
+    def _make_observation(
+        self,
+        feedback: str,
+        reward: float,
+        done: bool,
+    ) -> APIDebugObservation:
+        """Build an observation with the current episode state."""
+        if done and not feedback:
+            msg = "Episode complete."
+        elif done:
+            msg = f"Episode complete. Final reward: {reward:.2f}"
+        else:
+            remaining = self.max_steps - self.current_step
+            msg = f"{remaining} step(s) remaining. Use the feedback to improve."
+
+        return APIDebugObservation(
+            task=self.task,
+            api_name=self.spec.get("api_name", ""),
+            http_method=self.shown_http_method,
+            endpoint=self.spec.get("endpoint", ""),
+            broken_request=json.dumps(self.broken_request, indent=2),
+            broken_headers=self.broken_headers,
+            api_spec=self._build_spec_string(),
+            error_count=len(self.ground_truths),
+            step_number=self.current_step,
+            max_steps=self.max_steps,
+            feedback=feedback,
+            message=msg,
+            done=done,
+            reward=reward,
+        )

server/error_injectors.py

@@ -0,0 +1,388 @@
+"""
+10 error injection functions for the API Debug Environment.
+
+Each injector takes a valid request + headers + spec + RNG and returns:
+  (broken_request, broken_headers, ground_truth)
+
+ground_truth contains the error_type, affected_fields, and the original
+valid request/headers so the grader knows the correct answer.
+"""
+
+import copy
+import random as random_module
+from typing import Any, Dict, List, Tuple
+
+GroundTruth = Dict[str, Any]
+InjectorResult = Tuple[Dict[str, Any], Dict[str, str], GroundTruth]
+
+
+def _ground_truth(
+    error_type: str,
+    affected_fields: List[str],
+    valid_request: Dict[str, Any],
+    valid_headers: Dict[str, str],
+) -> GroundTruth:
+    """Build a standard ground truth dict."""
+    return {
+        "error_type": error_type,
+        "affected_fields": affected_fields,
+        "valid_request": valid_request,
+        "valid_headers": valid_headers,
+    }
+
+
+# =========================================================================
+# 1. missing_required_field
+# =========================================================================
+
+def inject_missing_required_field(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Remove a random required field from the request."""
+    broken = copy.deepcopy(request)
+    candidates = [f for f in spec["required_fields"] if f in broken]
+    if not candidates:
+        return broken, headers, _ground_truth(
+            "missing_required_field", [], request, headers
+        )
+    field = rng.choice(candidates)
+    del broken[field]
+    return broken, headers, _ground_truth(
+        "missing_required_field", [field], request, headers
+    )
+
+
+# =========================================================================
+# 2. wrong_field_type
+# =========================================================================
+
+def inject_wrong_field_type(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Change a field's value to the wrong type (e.g. int to string)."""
+    broken = copy.deepcopy(request)
+    candidates = [f for f in spec["required_fields"] if f in broken]
+    if not candidates:
+        return broken, headers, _ground_truth(
+            "wrong_field_type", [], request, headers
+        )
+    field = rng.choice(candidates)
+    original = broken[field]
+
+    # Pick a wrong type based on what the original is
+    if isinstance(original, int):
+        broken[field] = str(original)
+    elif isinstance(original, float):
+        broken[field] = str(original)
+    elif isinstance(original, bool):
+        broken[field] = "true"
+    elif isinstance(original, str):
+        broken[field] = 12345
+    elif isinstance(original, list):
+        broken[field] = "should_be_array"
+    elif isinstance(original, dict):
+        broken[field] = "should_be_object"
+    else:
+        broken[field] = "wrong_type"
+
+    return broken, headers, _ground_truth(
+        "wrong_field_type", [field], request, headers
+    )
+
+
+# =========================================================================
+# 3. invalid_email_format
+# =========================================================================
+
+def inject_invalid_email_format(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Corrupt an email field to an invalid format."""
+    broken = copy.deepcopy(request)
+    email_fields = [
+        f for f in spec["field_types"]
+        if spec["field_types"][f] == "email" and f in broken
+    ]
+    if not email_fields:
+        # Fallback: inject a missing field instead
+        return inject_missing_required_field(request, headers, spec, rng)
+
+    field = rng.choice(email_fields)
+    bad_emails = ["not-an-email", "user@", "@domain.com", "user@.com", "user space@example.com"]
+    broken[field] = rng.choice(bad_emails)
+    return broken, headers, _ground_truth(
+        "invalid_email_format", [field], request, headers
+    )
+
+
+# =========================================================================
+# 4. missing_auth_header
+# =========================================================================
+
+def inject_missing_auth_header(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Remove the Authorization header."""
+    broken_headers = copy.deepcopy(headers)
+    if "Authorization" in broken_headers:
+        del broken_headers["Authorization"]
+        return request, broken_headers, _ground_truth(
+            "missing_auth_header", ["Authorization"], request, headers
+        )
+    # If no auth header exists in spec, remove Content-Type instead
+    if "Content-Type" in broken_headers:
+        del broken_headers["Content-Type"]
+        return request, broken_headers, _ground_truth(
+            "missing_auth_header", ["Content-Type"], request, headers
+        )
+    return request, broken_headers, _ground_truth(
+        "missing_auth_header", [], request, headers
+    )
+
+
+# =========================================================================
+# 5. extra_unknown_field
+# =========================================================================
+
+def inject_extra_unknown_field(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Add a field that is not in the spec."""
+    broken = copy.deepcopy(request)
+    unknown_fields = [
+        ("unknown_field", "unexpected_value"),
+        ("debug_mode", True),
+        ("internal_id", 99999),
+        ("_private", "should_not_exist"),
+        ("extra_data", {"nested": "bad"}),
+    ]
+    field_name, field_value = rng.choice(unknown_fields)
+    broken[field_name] = field_value
+    return broken, headers, _ground_truth(
+        "extra_unknown_field", [field_name], request, headers
+    )
+
+
+# =========================================================================
+# 6. null_value_in_required
+# =========================================================================
+
+def inject_null_value_in_required(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Set a required field to null."""
+    broken = copy.deepcopy(request)
+    candidates = [f for f in spec["required_fields"] if f in broken]
+    if not candidates:
+        return broken, headers, _ground_truth(
+            "null_value_in_required", [], request, headers
+        )
+    field = rng.choice(candidates)
+    broken[field] = None
+    return broken, headers, _ground_truth(
+        "null_value_in_required", [field], request, headers
+    )
+
+
+# =========================================================================
+# 7. wrong_http_method
+# =========================================================================
+
+def inject_wrong_http_method(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Indicate the wrong HTTP method was used.
+
+    The error is stored in the ground truth. The request body stays the same
+    but the observation will show a different http_method.
+    """
+    all_methods = ["GET", "POST", "PUT", "PATCH", "DELETE"]
+    correct = spec["http_method"]
+    wrong_methods = [m for m in all_methods if m != correct]
+    wrong = rng.choice(wrong_methods)
+
+    gt = _ground_truth("wrong_http_method", ["http_method"], request, headers)
+    gt["wrong_method"] = wrong
+    gt["correct_method"] = correct
+    return request, headers, gt
+
+
+# =========================================================================
+# 8. malformed_json_value
+# =========================================================================
+
+def inject_malformed_json_value(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Corrupt a field value so it looks like broken JSON.
+
+    Since we work with Python dicts (already parsed), we simulate this
+    by inserting strings that look like malformed JSON fragments.
+    """
+    broken = copy.deepcopy(request)
+    candidates = [f for f in spec["required_fields"] if f in broken]
+    if not candidates:
+        return broken, headers, _ground_truth(
+            "malformed_json_value", [], request, headers
+        )
+    field = rng.choice(candidates)
+    bad_values = [
+        "{broken",
+        "[unclosed",
+        "value with 'mixed\" quotes",
+        "undefined",
+        "NaN",
+    ]
+    broken[field] = rng.choice(bad_values)
+    return broken, headers, _ground_truth(
+        "malformed_json_value", [field], request, headers
+    )
+
+
+# =========================================================================
+# 9. invalid_enum_value
+# =========================================================================
+
+def inject_invalid_enum_value(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Use a value not in the enum list for an enum field."""
+    broken = copy.deepcopy(request)
+    enum_fields = [
+        f for f in spec["field_types"]
+        if spec["field_types"][f].startswith("enum:") and f in broken
+    ]
+    if not enum_fields:
+        # Fallback: inject wrong type instead
+        return inject_wrong_field_type(request, headers, spec, rng)
+
+    field = rng.choice(enum_fields)
+    broken[field] = "INVALID_ENUM_VALUE"
+    return broken, headers, _ground_truth(
+        "invalid_enum_value", [field], request, headers
+    )
+
+
+# =========================================================================
+# 10. datetime_format_error
+# =========================================================================
+
+def inject_datetime_format_error(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Replace a datetime field with the wrong format."""
+    broken = copy.deepcopy(request)
+    datetime_fields = [
+        f for f in spec["field_types"]
+        if spec["field_types"][f] == "datetime" and f in broken
+    ]
+    if not datetime_fields:
+        # Fallback: inject wrong type instead
+        return inject_wrong_field_type(request, headers, spec, rng)
+
+    field = rng.choice(datetime_fields)
+    bad_formats = [
+        "04/01/2026",
+        "2026.04.01",
+        "April 1, 2026",
+        "1711929600",
+        "2026-04-01 09:00",
+    ]
+    broken[field] = rng.choice(bad_formats)
+    return broken, headers, _ground_truth(
+        "datetime_format_error", [field], request, headers
+    )
+
+
+# =========================================================================
+# Registry and helpers
+# =========================================================================
+
+ERROR_TYPES = [
+    "missing_required_field",
+    "wrong_field_type",
+    "invalid_email_format",
+    "missing_auth_header",
+    "extra_unknown_field",
+    "null_value_in_required",
+    "wrong_http_method",
+    "malformed_json_value",
+    "invalid_enum_value",
+    "datetime_format_error",
+]
+
+INJECTOR_MAP = {
+    "missing_required_field": inject_missing_required_field,
+    "wrong_field_type": inject_wrong_field_type,
+    "invalid_email_format": inject_invalid_email_format,
+    "missing_auth_header": inject_missing_auth_header,
+    "extra_unknown_field": inject_extra_unknown_field,
+    "null_value_in_required": inject_null_value_in_required,
+    "wrong_http_method": inject_wrong_http_method,
+    "malformed_json_value": inject_malformed_json_value,
+    "invalid_enum_value": inject_invalid_enum_value,
+    "datetime_format_error": inject_datetime_format_error,
+}
+
+
+def inject_error(
+    error_type: str,
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+) -> InjectorResult:
+    """Inject a single error of the specified type."""
+    injector = INJECTOR_MAP[error_type]
+    return injector(request, headers, spec, rng)
+
+
+def inject_multiple_errors(
+    request: Dict[str, Any],
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+    rng: random_module.Random,
+    count: int = 2,
+) -> Tuple[Dict[str, Any], Dict[str, str], List[GroundTruth]]:
+    """Inject multiple errors sequentially. Returns list of ground truths."""
+    broken_req = copy.deepcopy(request)
+    broken_hdrs = copy.deepcopy(headers)
+    all_truths = []
+
+    chosen_types = rng.sample(ERROR_TYPES, min(count, len(ERROR_TYPES)))
+    for err_type in chosen_types:
+        injector = INJECTOR_MAP[err_type]
+        broken_req, broken_hdrs, gt = injector(broken_req, broken_hdrs, spec, rng)
+        all_truths.append(gt)
+
+    return broken_req, broken_hdrs, all_truths

server/validators.py

@@ -0,0 +1,150 @@
+"""
+Field validation helpers used by the graders.
+
+Each validator returns True if the value matches the expected type,
+False otherwise. These are intentionally simple and deterministic.
+"""
+
+import re
+from typing import Any, Dict, List, Tuple
+
+
+EMAIL_RE = re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")
+PHONE_RE = re.compile(r"^\+?[1-9]\d{6,14}$")
+URL_RE = re.compile(r"^https?://[^\s]+$")
+ISO_DATETIME_RE = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$"
+)
+
+
+def validate_email(value: Any) -> bool:
+    return isinstance(value, str) and bool(EMAIL_RE.match(value))
+
+
+def validate_phone(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    cleaned = value.replace(" ", "").replace("-", "")
+    return bool(PHONE_RE.match(cleaned))
+
+
+def validate_url(value: Any) -> bool:
+    return isinstance(value, str) and bool(URL_RE.match(value))
+
+
+def validate_datetime(value: Any) -> bool:
+    return isinstance(value, str) and bool(ISO_DATETIME_RE.match(value))
+
+
+def validate_enum(value: Any, allowed_values: List[str]) -> bool:
+    return isinstance(value, str) and value in allowed_values
+
+
+def validate_field_type(value: Any, expected_type: str) -> bool:
+    """Check if a value matches the expected type string from the spec.
+
+    Supported types: string, integer, float, boolean, email, datetime,
+    url, phone, enum:val1,val2, object, array.
+    """
+    if value is None:
+        return False
+
+    if expected_type == "string":
+        return isinstance(value, str)
+    elif expected_type == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    elif expected_type == "float":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    elif expected_type == "boolean":
+        return isinstance(value, bool)
+    elif expected_type == "email":
+        return validate_email(value)
+    elif expected_type == "datetime":
+        return validate_datetime(value)
+    elif expected_type == "url":
+        return validate_url(value)
+    elif expected_type == "phone":
+        return validate_phone(value)
+    elif expected_type.startswith("enum:"):
+        allowed = expected_type.split(":", 1)[1].split(",")
+        return validate_enum(value, allowed)
+    elif expected_type == "object":
+        return isinstance(value, dict)
+    elif expected_type == "array":
+        return isinstance(value, list)
+    else:
+        # Unknown type, accept anything non-None
+        return True
+
+
+def validate_request_against_spec(
+    request: Dict[str, Any],
+    spec: Dict[str, Any],
+) -> Tuple[float, str]:
+    """Validate a request body against its spec.
+
+    Returns (score, feedback_string) where score is 0.0 to 1.0
+    based on how many checks pass.
+    """
+    checks = []
+    total = 0
+    passed = 0
+
+    # Check required fields are present and non-null
+    for field in spec["required_fields"]:
+        total += 1
+        if field in request and request[field] is not None:
+            passed += 1
+            checks.append(f"  {field}: PRESENT")
+        else:
+            checks.append(f"  {field}: MISSING")
+
+    # Check field types for fields that are present
+    for field, expected_type in spec["field_types"].items():
+        if field not in request or request[field] is None:
+            continue
+        total += 1
+        if validate_field_type(request[field], expected_type):
+            passed += 1
+            checks.append(f"  {field} type: VALID ({expected_type})")
+        else:
+            checks.append(f"  {field} type: INVALID (expected {expected_type})")
+
+    # Check no extra unknown fields
+    all_known = set(spec["required_fields"]) | set(spec.get("optional_fields", []))
+    for field in request:
+        if field not in all_known:
+            total += 1
+            checks.append(f"  {field}: UNKNOWN FIELD (not in spec)")
+
+    score = passed / total if total > 0 else 0.0
+    feedback = f"Validation: {passed}/{total} checks passed.\n" + "\n".join(checks)
+    return round(score, 4), feedback
+
+
+def validate_headers_against_spec(
+    headers: Dict[str, str],
+    spec: Dict[str, Any],
+) -> Tuple[float, str]:
+    """Validate request headers against the spec's required_headers.
+
+    Returns (score, feedback_string).
+    """
+    required = spec.get("required_headers", {})
+    if not required:
+        return 1.0, "No required headers."
+
+    total = len(required)
+    passed = 0
+    checks = []
+
+    for header_name in required:
+        if header_name in headers:
+            passed += 1
+            checks.append(f"  {header_name}: PRESENT")
+        else:
+            checks.append(f"  {header_name}: MISSING")
+
+    score = passed / total if total > 0 else 1.0
+    feedback = f"Headers: {passed}/{total} present.\n" + "\n".join(checks)
+    return round(score, 4), feedback