Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,29 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy and install Python dependencies first (cache layer)
+COPY server/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project files
+COPY . .
+
+# Set PYTHONPATH so imports resolve correctly
+ENV PYTHONPATH="/app:$PYTHONPATH"
+
+# Expose the port HF Spaces expects
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Run the FastAPI server
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,178 @@
 ---
-title: Api Contract Validator
-emoji: 🏢
+title: API Contract Validator
+emoji: 📋
 colorFrom: blue
-colorTo: red
+colorTo: green
 sdk: docker
+app_port: 7860
+tags:
+  - openenv
 pinned: false
+base_path: /web
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# API Contract Validator — OpenEnv Environment
+
+An OpenEnv RL environment where AI agents learn to validate API request/response payloads against OpenAPI specifications. Agents identify type mismatches, missing required fields, invalid enum values, and breaking changes between API versions.
+
+## Why This Environment?
+
+API contract violations are one of the **top causes of production incidents** in microservice architectures. Every API integration requires validating payloads against specs — a tedious, error-prone task that developers perform daily. This environment trains agents to automate this critical workflow.
+
+**Real-world applications:**
+- CI/CD pipeline contract testing
+- API gateway validation
+- SDK compatibility checking
+- Migration safety audits between API versions
+
+## How It Works
+
+Each episode presents the agent with:
+1. An **OpenAPI specification** defining expected types, required fields, and constraints
+2. A **payload** containing planted violations
+
+The agent inspects both and reports violations **one per step**. The environment grades each report against ground-truth violations and provides immediate feedback.
+
+```
+reset() → Agent sees spec + payload
+step(violation_report) → Correct? +1.0 | False positive? -0.3 | Duplicate? -0.1
+step(DONE) → Episode ends with completeness bonus
+```
+
+## Tasks (4 difficulty levels)
+
+| Task | Difficulty | Violations | Max Steps | What the Agent Must Find |
+|------|-----------|------------|-----------|--------------------------|
+| `find_type_mismatches` | Easy | 4 | 10 | Type mismatches, missing required fields, invalid enums at the top level |
+| `validate_nested_objects` | Medium | 7 | 15 | Violations inside nested objects and arrays — requires traversing deep structures |
+| `detect_breaking_changes` | Hard | 9 | 20 | Breaking changes between two API spec versions — type changes, removed fields, narrowed enums, new requirements |
+| `validate_response_schema` | Expert | 10 | 25 | Subtle format errors in an API response: invalid date formats, pattern mismatches, out-of-range numerics, and bad enum values scattered across nested objects and arrays |
+
+### Randomised Episode Generation
+
+All tasks support seed-based randomisation, making the environment suitable for **training** agents, not just evaluating them:
+
+- `find_type_mismatches` — samples 4 violations from a pool of 8 (70 unique combinations)
+- `validate_nested_objects` — two complete scenario variants (Order Service / Event Booking)
+- `validate_response_schema` — two complete scenario variants with different violation sets
+- Pass `seed` in the `reset()` call to select a deterministic episode
+
+## Action Space
+
+Each step the agent submits a `ValidatorAction`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `field_path` | `str` | Dot-notation path to the violated field (e.g., `customer.email`, `items[1].quantity`). Use `DONE` to end. |
+| `violation_type` | `str` | One of: `type_mismatch`, `missing_required`, `invalid_enum`, `format_error`, `extra_field`, `breaking_change` |
+| `description` | `str` | Human-readable explanation of the violation |
+| `suggested_fix` | `str` | Optional suggested correction |
+
+## Observation Space
+
+After each step the agent receives a `ValidatorObservation`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_name` | `str` | Current task identifier |
+| `task_description` | `str` | Natural-language instructions |
+| `api_spec` | `dict` | The OpenAPI specification (or version diff for hard task) |
+| `payload` | `dict` | The payload to validate |
+| `violations_found` | `list[dict]` | Violations correctly identified so far |
+| `violations_remaining` | `int` | How many planted violations are still undetected |
+| `feedback` | `str` | Result of the last submitted report |
+| `max_steps` | `int` | Step budget for the episode |
+| `done` | `bool` | Whether the episode has ended |
+| `reward` | `float` | Reward for the last action |
+
+## Reward Function
+
+The reward function provides **partial progress signals** — not binary end-of-episode scoring:
+
+| Event | Reward | Rationale |
+|-------|--------|-----------|
+| Correct violation found | +1.0 | Primary incentive — each discovery is rewarded |
+| False positive | -0.3 | Penalises guessing without being too harsh |
+| Duplicate report | -0.1 | Light penalty — agent should track what it already reported |
+| DONE signal | +0.5 × (found/total) | Bonus proportional to completeness |
+
+**Final score** = `correct_violations / total_violations` ∈ [0.0, 1.0]
+
+## Setup
+
+### Prerequisites
+
+- Python 3.10+
+- Docker (for containerised deployment)
+- `openenv-core` (`pip install openenv-core`)
+
+### Local Development
+
+```bash
+git clone <your-repo-url>
+cd api_contract_validator
+pip install -e .
+
+uvicorn server.app:app --host 0.0.0.0 --port 7860 --reload
+```
+
+### Docker
+
+```bash
+docker build -t api-contract-validator .
+docker run -p 7860:7860 api-contract-validator
+```
+
+### Run Inference
+
+```bash
+export API_BASE_URL="https://router.huggingface.co/v1"
+export MODEL_NAME="Qwen/Qwen2.5-72B-Instruct"
+export HF_TOKEN="your-token-here"
+
+python inference.py
+```
+
+## Validate Submission
+
+```bash
+openenv validate
+
+# Full pre-submission check
+./validate-submission.sh https://your-space.hf.space
+```
+
+## Baseline Scores
+
+| Task | Model | Score | Steps |
+|------|-------|-------|-------|
+| `find_type_mismatches` | Qwen2.5-72B-Instruct | ~0.75 | 5–7 |
+| `validate_nested_objects` | Qwen2.5-72B-Instruct | ~0.57 | 8–12 |
+| `detect_breaking_changes` | Qwen2.5-72B-Instruct | ~0.44 | 12–18 |
+
+*Scores are approximate and may vary with temperature/sampling.*
+
+## Project Structure
+
+```
+api_contract_validator/
+├── openenv.yaml              # OpenEnv manifest
+├── pyproject.toml             # Python project metadata
+├── Dockerfile                 # Container definition
+├── inference.py               # Baseline inference script
+├── README.md                  # This file
+├── models.py                  # Pydantic models (Action, Observation, State)
+├── client.py                  # WebSocket client (EnvClient subclass)
+├── __init__.py                # Package exports
+└── server/
+    ├── __init__.py
+    ├── app.py                 # FastAPI wiring (create_app)
+    ├── environment.py         # Core environment logic (reset/step/state)
+    ├── spec_generator.py      # Task scenarios with planted violations
+    ├── rewards.py             # Reward computation
+    └── requirements.txt       # Server dependencies
+```
+
+## License
+
+BSD-style — see LICENSE file.

__init__.py

@@ -0,0 +1,15 @@
+"""API Contract Validator Environment."""
+
+try:
+    from .client import ValidatorEnv
+    from .models import ValidatorAction, ValidatorObservation, ValidatorState
+except (ImportError, ModuleNotFoundError):
+    from client import ValidatorEnv
+    from models import ValidatorAction, ValidatorObservation, ValidatorState
+
+__all__ = [
+    "ValidatorAction",
+    "ValidatorObservation",
+    "ValidatorState",
+    "ValidatorEnv",
+]

client.py

@@ -0,0 +1,87 @@
+"""
+API Contract Validator Environment Client.
+
+Maintains a persistent WebSocket connection to the environment server.
+Each client instance has its own isolated session.
+"""
+
+from typing import Any, Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+
+try:
+    from .models import ValidatorAction, ValidatorObservation, ValidatorState
+except (ImportError, ModuleNotFoundError):
+    from models import ValidatorAction, ValidatorObservation, ValidatorState
+
+
+class ValidatorEnv(
+    EnvClient[ValidatorAction, ValidatorObservation, ValidatorState]
+):
+    """Client for the API Contract Validator Environment.
+
+    Example::
+
+        with ValidatorEnv(base_url="http://localhost:7860").sync() as env:
+            result = env.reset()
+            print(result.observation.task_name)
+            result = env.step(ValidatorAction(
+                field_path="email",
+                violation_type="missing_required",
+                description="Required field 'email' is missing.",
+            ))
+            print(result.observation.feedback)
+
+    Example with Docker::
+
+        env = ValidatorEnv.from_docker_image("api-contract-validator:latest")
+        result = env.reset()
+        ...
+        env.close()
+    """
+
+    def _step_payload(self, action: ValidatorAction) -> Dict[str, Any]:
+        """Convert action to JSON payload for the step message."""
+        return {
+            "field_path": action.field_path,
+            "violation_type": action.violation_type,
+            "description": action.description,
+            "suggested_fix": action.suggested_fix,
+        }
+
+    def _parse_result(
+        self, payload: Dict[str, Any]
+    ) -> StepResult[ValidatorObservation]:
+        """Parse the server response into a typed StepResult."""
+        obs_data = payload.get("observation", {})
+        observation = ValidatorObservation(
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            task_name=obs_data.get("task_name", ""),
+            task_description=obs_data.get("task_description", ""),
+            api_spec=obs_data.get("api_spec", {}),
+            payload=obs_data.get("payload", {}),
+            violations_found=obs_data.get("violations_found", []),
+            violations_remaining=obs_data.get("violations_remaining", 0),
+            feedback=obs_data.get("feedback", ""),
+            max_steps=obs_data.get("max_steps", 0),
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> ValidatorState:
+        """Parse the state response into a typed ValidatorState."""
+        return ValidatorState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            task_name=payload.get("task_name", ""),
+            total_violations=payload.get("total_violations", 0),
+            correct_reports=payload.get("correct_reports", 0),
+            false_positives=payload.get("false_positives", 0),
+            duplicate_reports=payload.get("duplicate_reports", 0),
+            score=payload.get("score", 0.0),
+        )

inference.py

@@ -0,0 +1,344 @@
+"""
+Baseline Inference Script for API Contract Validator Environment.
+
+Runs an LLM agent against all tasks and produces scores.
+Uses the OpenAI client for all LLM calls.
+
+Environment variables:
+    API_BASE_URL      — API endpoint (default: HF router)
+    MODEL_NAME        — Model identifier (default: Qwen2.5-72B-Instruct)
+    HF_TOKEN          — Hugging Face / API key (no default)
+    LOCAL_IMAGE_NAME  — Docker image name when using from_docker_image()
+
+STDOUT format follows the hackathon specification exactly:
+    [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> rewards=<r1,r2,...,rn>
+"""
+
+import asyncio
+import json
+import os
+import textwrap
+from typing import Any, Dict, List, Optional
+
+from openai import OpenAI
+
+from client import ValidatorEnv
+from models import ValidatorAction
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+LOCAL_IMAGE_NAME = os.getenv("LOCAL_IMAGE_NAME")
+HF_TOKEN = os.getenv("HF_TOKEN")
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-72B-Instruct")
+
+BENCHMARK = "api_contract_validator"
+TASKS = [
+    "find_type_mismatches",
+    "validate_nested_objects",
+    "detect_breaking_changes",
+    "validate_response_schema",
+    "validate_cross_field_constraints",
+]
+MAX_STEPS_PER_TASK = {
+    "find_type_mismatches": 10,
+    "validate_nested_objects": 15,
+    "detect_breaking_changes": 20,
+    "validate_response_schema": 25,
+    "validate_cross_field_constraints": 18,
+}
+TEMPERATURE = 0.2
+MAX_TOKENS = 1024
+SUCCESS_SCORE_THRESHOLD = 0.3
+
+
+# ---------------------------------------------------------------------------
+# Structured stdout logging
+# ---------------------------------------------------------------------------
+
+
+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:
+    error_val = error if error else "null"
+    done_val = str(done).lower()
+    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} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Prompt construction
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = textwrap.dedent("""\
+You are an expert API contract validator. You will be given an OpenAPI \
+specification and an API payload. Your job is to find violations in the \
+payload that do not conform to the spec.
+
+Each turn you must respond with EXACTLY one JSON object (no markdown, no \
+explanation outside the JSON) with these fields:
+{
+    "field_path": "<dot-notation path to the violated field, or 'DONE' if no more violations>",
+    "violation_type": "<type_mismatch|missing_required|invalid_enum|format_error|extra_field|breaking_change|cross_field_constraint>",
+    "description": "<brief explanation>",
+    "suggested_fix": "<how to fix it>"
+}
+
+Rules:
+- Report ONE violation per turn.
+- Use dot-notation for nested paths: 'customer.email'
+- Use bracket notation for arrays: 'items[1].quantity'
+- For breaking changes use path format: 'METHOD /path.field' e.g. 'POST /products.price'
+- For breaking changes between API versions, ALWAYS use violation_type='breaking_change'.
+- For cross-field constraints (arithmetic, date ordering, conditional requirements), use violation_type='cross_field_constraint'.
+- The field_path must contain ONLY the path — never include the violation_type inside the field_path.
+- When you have found all violations, respond with field_path set to 'DONE'.
+- Do NOT repeat a violation you already reported.
+- You may submit field_path='HINT' to receive a location hint at a cost of -0.5 reward.
+""")
+
+
+def build_user_prompt(
+    observation: Dict[str, Any],
+    step: int,
+    history: List[str],
+) -> str:
+    """Build the user prompt from the current observation."""
+    violations_found = observation.get("violations_found", [])
+    found_summary = "None yet"
+    if violations_found:
+        found_lines = []
+        for v in violations_found:
+            found_lines.append(f"  - {v['field_path']}: {v['violation_type']}")
+        found_summary = "\n".join(found_lines)
+
+    history_block = "\n".join(history[-5:]) if history else "None"
+
+    return textwrap.dedent(f"""\
+Step: {step}
+Task: {observation.get('task_name', '')}
+Instructions: {observation.get('task_description', '')}
+
+API Specification:
+{json.dumps(observation.get('api_spec', {}), indent=2)}
+
+Payload to validate:
+{json.dumps(observation.get('payload', {}), indent=2)}
+
+Violations found so far:
+{found_summary}
+
+Violations remaining: {observation.get('violations_remaining', '?')}
+Last feedback: {observation.get('feedback', '')}
+
+Previous steps:
+{history_block}
+
+Respond with a single JSON object for the next violation (or DONE).
+""")
+
+
+# ---------------------------------------------------------------------------
+# LLM interaction
+# ---------------------------------------------------------------------------
+
+
+def parse_llm_response(text: str) -> Dict[str, str]:
+    """Parse the LLM response into a violation dict.
+
+    Handles cases where the model wraps JSON in markdown fences.
+    """
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        lines = cleaned.split("\n")
+        lines = [l for l in lines if not l.strip().startswith("```")]
+        cleaned = "\n".join(lines).strip()
+
+    _VALID_TYPES = {
+        "type_mismatch", "missing_required", "invalid_enum",
+        "format_error", "extra_field", "breaking_change", "cross_field_constraint",
+    }
+
+    try:
+        data = json.loads(cleaned)
+        field_path = str(data.get("field_path", "DONE"))
+        violation_type = str(data.get("violation_type", "unknown"))
+
+        # LLMs sometimes embed ":violation_type" inside field_path — strip it
+        if ":" in field_path:
+            parts = field_path.split(":")
+            # Only strip if the suffix looks like a violation type keyword
+            if any(vt in parts[-1].lower() for vt in _VALID_TYPES):
+                field_path = parts[0].strip()
+
+        return {
+            "field_path": field_path,
+            "violation_type": violation_type,
+            "description": str(data.get("description", "")),
+            "suggested_fix": str(data.get("suggested_fix", "")),
+        }
+    except json.JSONDecodeError:
+        # If the model just says "DONE" or similar
+        upper = cleaned.upper()
+        if "DONE" in upper:
+            return {
+                "field_path": "DONE",
+                "violation_type": "",
+                "description": "",
+                "suggested_fix": "",
+            }
+        return {
+            "field_path": "DONE",
+            "violation_type": "unknown",
+            "description": f"Failed to parse: {cleaned[:100]}",
+            "suggested_fix": "",
+        }
+
+
+def query_llm(
+    client: OpenAI,
+    observation: Dict[str, Any],
+    step: int,
+    history: List[str],
+) -> Dict[str, str]:
+    """Send the current observation to the LLM and return a parsed action."""
+    user_prompt = build_user_prompt(observation, step, history)
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            stream=False,
+        )
+        raw_text = (completion.choices[0].message.content or "").strip()
+        return parse_llm_response(raw_text)
+    except Exception as exc:
+        print(f"[DEBUG] LLM request failed: {exc}", flush=True)
+        return {
+            "field_path": "DONE",
+            "violation_type": "",
+            "description": f"LLM error: {exc}",
+            "suggested_fix": "",
+        }
+
+
+# ---------------------------------------------------------------------------
+# Main loop
+# ---------------------------------------------------------------------------
+
+
+async def run_single_task(
+    client: OpenAI,
+    env: ValidatorEnv,
+    task_name: str,
+) -> None:
+    """Run a single task episode and emit structured logs."""
+    max_steps = MAX_STEPS_PER_TASK.get(task_name, 15)
+    history: List[str] = []
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+
+    log_start(task=task_name, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        result = await env.reset(task_name=task_name)
+        obs_dict = result.observation.model_dump() if hasattr(result.observation, 'model_dump') else result.observation.__dict__
+
+        for step in range(1, max_steps + 1):
+            if result.done:
+                break
+
+            action_data = query_llm(client, obs_dict, step, history)
+
+            action = ValidatorAction(
+                field_path=action_data["field_path"],
+                violation_type=action_data["violation_type"],
+                description=action_data["description"],
+                suggested_fix=action_data["suggested_fix"],
+            )
+
+            result = await env.step(action)
+            obs_dict = result.observation.model_dump() if hasattr(result.observation, 'model_dump') else result.observation.__dict__
+
+            reward = result.reward or 0.0
+            done = result.done
+            error = None
+
+            rewards.append(reward)
+            steps_taken = step
+
+            action_str = f"{action_data['field_path']}:{action_data['violation_type']}"
+            log_step(step=step, action=action_str, reward=reward, done=done, error=error)
+
+            history.append(
+                f"Step {step}: {action_str} → reward {reward:+.2f}"
+            )
+
+            if done:
+                break
+
+        # Compute final score
+        if rewards:
+            correct_count = sum(1 for r in rewards if r >= 1.0)
+            total_violations = obs_dict.get("violations_remaining", 0) + len(
+                obs_dict.get("violations_found", [])
+            )
+            score = (
+                correct_count / total_violations if total_violations > 0 else 0.0
+            )
+        score = min(max(score, 0.0), 1.0)
+        success = score >= SUCCESS_SCORE_THRESHOLD
+
+    finally:
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+
+async def main() -> None:
+    """Run the inference agent against all tasks."""
+    openai_client = OpenAI(base_url=API_BASE_URL, api_key=HF_TOKEN)
+
+    if LOCAL_IMAGE_NAME:
+        env = await ValidatorEnv.from_docker_image(LOCAL_IMAGE_NAME)
+    else:
+        env_url = os.getenv("ENV_BASE_URL", "http://localhost:7860")
+        env = ValidatorEnv(base_url=env_url)
+
+    try:
+        for task_name in TASKS:
+            await run_single_task(openai_client, env, task_name)
+    finally:
+        try:
+            await env.close()
+        except Exception as exc:
+            print(f"[DEBUG] env.close() error: {exc}", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,112 @@
+"""
+Data models for the API Contract Validator Environment.
+
+Defines typed Action, Observation, and State models that form the
+contract between the agent and the environment.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from openenv.core.env_server.types import Action, Observation, State
+from pydantic import Field
+
+
+# ---------------------------------------------------------------------------
+# Action — what the agent submits each step
+# ---------------------------------------------------------------------------
+
+class ValidatorAction(Action):
+    """A single violation report submitted by the agent.
+
+    The agent inspects an API spec + payload pair and reports one violation
+    per step.  Submitting ``field_path="DONE"`` signals the agent is finished.
+    """
+
+    field_path: str = Field(
+        ...,
+        description=(
+            "Dot-notation path to the violated field, e.g. 'user.email'. "
+            "Use 'DONE' to signal no more violations. "
+            "Use 'HINT' to receive a location hint at -0.5 reward cost."
+        ),
+    )
+    violation_type: str = Field(
+        ...,
+        description=(
+            "Category of violation: type_mismatch | missing_required | "
+            "invalid_enum | format_error | extra_field | breaking_change | "
+            "cross_field_constraint"
+        ),
+    )
+    description: str = Field(
+        default="",
+        description="Human-readable explanation of the violation.",
+    )
+    suggested_fix: str = Field(
+        default="",
+        description="Optional suggested correction for the violation.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Observation — what the agent sees after each step
+# ---------------------------------------------------------------------------
+
+class ValidatorObservation(Observation):
+    """What the environment returns after each agent action.
+
+    Inherits ``done: bool`` and ``reward: Optional[float]`` from the
+    ``Observation`` base class.
+    """
+
+    task_name: str = Field(
+        default="",
+        description="Identifier for the current task.",
+    )
+    task_description: str = Field(
+        default="",
+        description="Natural-language instructions for the agent.",
+    )
+    api_spec: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="The OpenAPI specification (or spec diff for hard tasks).",
+    )
+    payload: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="The API request/response payload to validate.",
+    )
+    violations_found: List[Dict[str, str]] = Field(
+        default_factory=list,
+        description="Violations the agent has correctly identified so far.",
+    )
+    violations_remaining: int = Field(
+        default=0,
+        description="Number of planted violations still undetected.",
+    )
+    feedback: str = Field(
+        default="",
+        description="Result of the agent's last submitted report.",
+    )
+    max_steps: int = Field(
+        default=0,
+        description="Maximum steps allowed for the current episode.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# State — internal environment state (includes ground-truth)
+# ---------------------------------------------------------------------------
+
+class ValidatorState(State):
+    """Full environment state including ground-truth violations.
+
+    Inherits ``episode_id: Optional[str]`` and ``step_count: int`` from
+    the ``State`` base class.
+    """
+
+    task_name: str = ""
+    total_violations: int = 0
+    correct_reports: int = 0
+    false_positives: int = 0
+    duplicate_reports: int = 0
+    score: float = 0.0

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: api_contract_validator
+type: space
+runtime: fastapi
+app: server.app:app
+port: 7860

pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-api-contract-validator"
+version = "0.1.0"
+description = "API Contract Validator — an OpenEnv RL environment for validating API payloads against OpenAPI specifications."
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core[core]>=0.2.2",
+    "openai>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.scripts]
+server = "api_contract_validator.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["api_contract_validator", "api_contract_validator.server"]
+[tool.setuptools.package-dir]
+"api_contract_validator" = "."
+"api_contract_validator.server" = "server"

server/__init__.py

@@ -0,0 +1 @@
+"""API Contract Validator — server package."""

server/app.py

@@ -0,0 +1,51 @@
+"""
+FastAPI application for the API Contract Validator Environment.
+
+Exposes the ValidatorEnvironment over HTTP and WebSocket endpoints
+using ``openenv.core.env_server.http_server.create_app``.
+
+Endpoints created automatically:
+    - POST /reset   — Reset the environment
+    - POST /step    — Execute an action
+    - GET  /state   — Get current environment state
+    - GET  /health  — Health check
+    - WS   /ws      — WebSocket for persistent sessions
+    - GET  /docs    — Swagger UI
+"""
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as exc:
+    raise ImportError(
+        "openenv is required. Install with: pip install openenv-core"
+    ) from exc
+
+try:
+    from ..models import ValidatorAction, ValidatorObservation
+    from .environment import ValidatorEnvironment
+except (ImportError, ModuleNotFoundError):
+    import sys
+    import os
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from models import ValidatorAction, ValidatorObservation
+    from server.environment import ValidatorEnvironment
+
+
+app = create_app(
+    ValidatorEnvironment,
+    ValidatorAction,
+    ValidatorObservation,
+    env_name="api_contract_validator",
+    max_concurrent_envs=10,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 7860) -> None:
+    """Entry point for ``uv run server`` or direct execution."""
+    import uvicorn
+
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/environment.py

@@ -0,0 +1,425 @@
+"""
+API Contract Validator Environment Implementation.
+
+The agent validates API payloads against OpenAPI specifications by
+reporting violations one at a time.  The environment grades each
+report against planted ground-truth violations and provides partial
+reward signals.
+
+Special field_path values:
+  'DONE' — end the episode and collect the completeness bonus
+  'HINT' — receive a location hint (costs -0.5 reward)
+"""
+
+from typing import Any, Dict, List, Optional, Set
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import ValidatorAction, ValidatorObservation, ValidatorState
+except (ImportError, ModuleNotFoundError):
+    import sys
+    import os
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    from models import ValidatorAction, ValidatorObservation, ValidatorState
+
+from .rewards import (
+    RewardBreakdown,
+    compute_episode_score,
+    compute_step_reward,
+)
+from .spec_generator import (
+    AVAILABLE_TASKS,
+    PlantedViolation,
+    TaskScenario,
+    generate_scenario_for_task,
+)
+
+
+def _normalise_path(path: str) -> str:
+    """Lower-case and strip whitespace for fuzzy path matching."""
+    return path.strip().lower().replace(" ", "")
+
+
+def _find_matching_violation(
+    reported_path: str,
+    reported_type: str,
+    ground_truth: List[PlantedViolation],
+) -> Optional[PlantedViolation]:
+    """Return the first ground-truth violation that matches both path and type.
+
+    Matching is intentionally lenient: paths are compared after normalisation
+    and violation_type uses substring matching.
+    """
+    norm_path = _normalise_path(reported_path)
+    norm_type = reported_type.strip().lower()
+
+    for violation in ground_truth:
+        gt_path = _normalise_path(violation.field_path)
+        gt_type = violation.violation_type.strip().lower()
+
+        path_match = (norm_path == gt_path) or (
+            norm_path in gt_path or gt_path in norm_path
+        )
+        type_match = (norm_type == gt_type) or (
+            norm_type in gt_type or gt_type in norm_type
+        )
+
+        if path_match and type_match:
+            return violation
+    return None
+
+
+def _find_path_only_match(
+    reported_path: str,
+    ground_truth: List[PlantedViolation],
+    already_matched: Set[str],
+    already_proximity: Set[str],
+) -> Optional[PlantedViolation]:
+    """Return a violation whose path matches but has not yet been fully matched.
+
+    Used for the proximity reward: agent found the right field but wrong type.
+    Ignores violations that have already been correctly reported OR already
+    received a proximity reward (to prevent reward farming).
+    """
+    norm_path = _normalise_path(reported_path)
+
+    for violation in ground_truth:
+        gt_path = _normalise_path(violation.field_path)
+        if gt_path in already_matched or gt_path in already_proximity:
+            continue
+        path_match = (norm_path == gt_path) or (
+            norm_path in gt_path or gt_path in norm_path
+        )
+        if path_match:
+            return violation
+    return None
+
+
+def _hint_section(field_path: str) -> str:
+    """Extract the top-level section name from a field path.
+
+    Examples:
+        'customer.email'           → 'customer'
+        'items[1].quantity'        → 'items'
+        'billing.tax_rate'         → 'billing'
+        'due_date'                 → 'due_date'
+        'POST /products.price'     → 'POST /products'
+    """
+    path = field_path.strip()
+    # Handle breaking-change paths like "POST /products.price"
+    if path.startswith(("GET ", "POST ", "PUT ", "PATCH ", "DELETE ")):
+        dot_idx = path.find(".")
+        return path[:dot_idx] if dot_idx != -1 else path
+    # Standard paths: split on first dot or bracket
+    for i, ch in enumerate(path):
+        if ch in (".", "["):
+            return path[:i]
+    return path
+
+
+class ValidatorEnvironment(Environment):
+    """API Contract Validator — an OpenEnv RL environment.
+
+    At the start of each episode the environment loads a task scenario
+    containing an API spec, a payload, and a set of planted violations.
+    The agent inspects the spec + payload and reports violations one per
+    step.  The episode ends when the agent sends ``DONE`` or exhausts its
+    step budget.
+
+    Special actions:
+      field_path='DONE'  — end episode, collect completeness bonus
+      field_path='HINT'  — receive a location hint, pay -0.5 reward
+
+    Attributes
+    ----------
+    SUPPORTS_CONCURRENT_SESSIONS : bool
+        True — each WebSocket connection gets its own isolated instance.
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._state = ValidatorState()
+        self._scenario: Optional[TaskScenario] = None
+        self._matched_paths: Set[str] = set()
+        self._proximity_paths: Set[str] = set()
+        self._reported_violations: List[Dict[str, str]] = []
+        self._task_index: int = 0
+
+    # ── reset ─────────────────────────────────────────────────────────
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> ValidatorObservation:
+        """Start a new episode.
+
+        If ``task_name`` is passed in *kwargs* it selects a specific task;
+        otherwise the environment cycles through all available tasks.
+        """
+        task_name = kwargs.get("task_name") or AVAILABLE_TASKS[
+            self._task_index % len(AVAILABLE_TASKS)
+        ]
+        self._task_index += 1
+
+        self._scenario = generate_scenario_for_task(task_name, seed=seed)
+        self._matched_paths = set()
+        self._proximity_paths = set()
+        self._reported_violations = []
+
+        self._state = ValidatorState(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+            task_name=self._scenario.task_name,
+            total_violations=len(self._scenario.violations),
+            correct_reports=0,
+            false_positives=0,
+            duplicate_reports=0,
+            score=0.0,
+        )
+
+        return ValidatorObservation(
+            done=False,
+            reward=0.0,
+            task_name=self._scenario.task_name,
+            task_description=self._scenario.task_description,
+            api_spec=self._scenario.api_spec,
+            payload=self._scenario.payload,
+            violations_found=[],
+            violations_remaining=len(self._scenario.violations),
+            feedback="Episode started. Inspect the spec and payload, then report violations.",
+            max_steps=self._scenario.max_steps,
+        )
+
+    # ── step ──────────────────────────────────────────────────────────
+
+    def step(
+        self,
+        action: ValidatorAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> ValidatorObservation:
+        """Process one violation report from the agent."""
+        if self._scenario is None:
+            raise RuntimeError("Call reset() before step().")
+
+        self._state.step_count += 1
+        signal = action.field_path.strip().upper()
+
+        # ── HINT request ──────────────────────────────────────────────
+        if signal == "HINT":
+            remaining = [
+                v for v in self._scenario.violations
+                if _normalise_path(v.field_path) not in self._matched_paths
+            ]
+            if remaining:
+                section = _hint_section(remaining[0].field_path)
+                hint_msg = (
+                    f"Hint: An undetected violation is in the '{section}' section. "
+                    f"(-0.5 reward)"
+                )
+            else:
+                hint_msg = "All violations have already been found. Submit DONE."
+
+            breakdown = compute_step_reward(
+                is_correct=False,
+                is_path_match=False,
+                is_duplicate=False,
+                is_done_signal=False,
+                is_hint=True,
+                correct_so_far=self._state.correct_reports,
+                total_violations=self._state.total_violations,
+            )
+            return self._build_observation(
+                reward=breakdown.reward,
+                done=False,
+                feedback=hint_msg,
+            )
+
+        # ── DONE signal ───────────────────────────────────────────────
+        if signal == "DONE":
+            breakdown = compute_step_reward(
+                is_correct=False,
+                is_path_match=False,
+                is_duplicate=False,
+                is_done_signal=True,
+                correct_so_far=self._state.correct_reports,
+                total_violations=self._state.total_violations,
+            )
+            self._state.score = compute_episode_score(
+                self._state.correct_reports,
+                self._state.total_violations,
+            )
+            return self._build_observation(
+                reward=breakdown.reward,
+                done=True,
+                feedback=breakdown.explanation,
+            )
+
+        # ── Duplicate check ───────────────────────────────────────────
+        norm_reported = _normalise_path(action.field_path)
+        if norm_reported in self._matched_paths:
+            breakdown = compute_step_reward(
+                is_correct=False,
+                is_path_match=False,
+                is_duplicate=True,
+                is_done_signal=False,
+                correct_so_far=self._state.correct_reports,
+                total_violations=self._state.total_violations,
+            )
+            self._state.duplicate_reports += 1
+            return self._build_observation(
+                reward=breakdown.reward,
+                done=False,
+                feedback=breakdown.explanation,
+            )
+
+        # ── Full match (path + type) ──────────────────────────────────
+        matched = _find_matching_violation(
+            action.field_path,
+            action.violation_type,
+            self._scenario.violations,
+        )
+
+        if matched is not None:
+            gt_path = _normalise_path(matched.field_path)
+            self._matched_paths.add(gt_path)
+            self._proximity_paths.discard(gt_path)
+            self._state.correct_reports += 1
+            self._reported_violations.append(
+                {
+                    "field_path": matched.field_path,
+                    "violation_type": matched.violation_type,
+                    "description": matched.description,
+                }
+            )
+            breakdown = compute_step_reward(
+                is_correct=True,
+                is_path_match=False,
+                is_duplicate=False,
+                is_done_signal=False,
+                correct_so_far=self._state.correct_reports,
+                total_violations=self._state.total_violations,
+            )
+
+            all_found = self._state.correct_reports >= self._state.total_violations
+            steps_exhausted = self._state.step_count >= self._scenario.max_steps
+            done = all_found or steps_exhausted
+
+            if done:
+                self._state.score = compute_episode_score(
+                    self._state.correct_reports,
+                    self._state.total_violations,
+                )
+
+            feedback = breakdown.explanation
+            if all_found:
+                feedback += " All violations found — episode complete!"
+            elif steps_exhausted:
+                remaining = self._state.total_violations - self._state.correct_reports
+                feedback += f" Step limit reached. {remaining} violation(s) missed."
+
+            return self._build_observation(
+                reward=breakdown.reward,
+                done=done,
+                feedback=feedback,
+            )
+
+        # ── Proximity match (right path, wrong type) ──────────────────
+        path_match = _find_path_only_match(
+            action.field_path,
+            self._scenario.violations,
+            self._matched_paths,
+            self._proximity_paths,
+        )
+
+        if path_match is not None:
+            self._proximity_paths.add(_normalise_path(path_match.field_path))
+            breakdown = compute_step_reward(
+                is_correct=False,
+                is_path_match=True,
+                is_duplicate=False,
+                is_done_signal=False,
+                correct_so_far=self._state.correct_reports,
+                total_violations=self._state.total_violations,
+            )
+            steps_exhausted = self._state.step_count >= self._scenario.max_steps
+            if steps_exhausted:
+                self._state.score = compute_episode_score(
+                    self._state.correct_reports,
+                    self._state.total_violations,
+                )
+            return self._build_observation(
+                reward=breakdown.reward,
+                done=steps_exhausted,
+                feedback=breakdown.explanation,
+            )
+
+        # ── False positive ────────────────────────────────────────────
+        self._state.false_positives += 1
+        breakdown = compute_step_reward(
+            is_correct=False,
+            is_path_match=False,
+            is_duplicate=False,
+            is_done_signal=False,
+            correct_so_far=self._state.correct_reports,
+            total_violations=self._state.total_violations,
+        )
+
+        steps_exhausted = self._state.step_count >= self._scenario.max_steps
+        done = steps_exhausted
+
+        if done:
+            self._state.score = compute_episode_score(
+                self._state.correct_reports,
+                self._state.total_violations,
+            )
+
+        feedback = breakdown.explanation
+        if steps_exhausted:
+            remaining = self._state.total_violations - self._state.correct_reports
+            feedback += f" Step limit reached. {remaining} violation(s) missed."
+
+        return self._build_observation(
+            reward=breakdown.reward,
+            done=done,
+            feedback=feedback,
+        )
+
+    # ── state ─────────────────────────────────────────────────────────
+
+    @property
+    def state(self) -> ValidatorState:
+        """Return current internal state (includes ground-truth counts)."""
+        return self._state
+
+    # ── helpers ────────────────────────────────────────────────────────
+
+    def _build_observation(
+        self,
+        *,
+        reward: float,
+        done: bool,
+        feedback: str,
+    ) -> ValidatorObservation:
+        """Construct an observation from current state."""
+        assert self._scenario is not None
+        remaining = self._state.total_violations - self._state.correct_reports
+        return ValidatorObservation(
+            done=done,
+            reward=reward,
+            task_name=self._scenario.task_name,
+            task_description=self._scenario.task_description,
+            api_spec=self._scenario.api_spec,
+            payload=self._scenario.payload,
+            violations_found=list(self._reported_violations),
+            violations_remaining=max(remaining, 0),
+            feedback=feedback,
+            max_steps=self._scenario.max_steps,
+        )

server/requirements.txt

@@ -0,0 +1,4 @@
+openenv-core[core]>=0.2.2
+fastapi>=0.115.0
+uvicorn>=0.24.0
+openai>=1.0.0

server/rewards.py

@@ -0,0 +1,168 @@
+"""
+Reward computation for the API Contract Validator Environment.
+
+Provides partial-progress reward signals rather than binary end-of-episode
+scoring.  The reward function has several interesting properties:
+
+  - Correct violation found          → +1.0  (primary incentive)
+  - Path-only match (wrong type)     → +0.3  (proximity signal — learn location first)
+  - HINT requested                   → -0.5  (expensive but informative)
+  - Duplicate report                 → -0.1  (light penalty, track what you've found)
+  - False positive                   → -0.3  (penalise guessing)
+  - DONE signal                      → +0.5 × (found/total)  (completeness bonus)
+
+The proximity reward creates a richer gradient: agents learn to locate the
+right field first, then refine their violation classification.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class RewardBreakdown:
+    """Detailed breakdown of a single-step reward."""
+
+    reward: float
+    is_correct: bool
+    is_path_match: bool
+    is_duplicate: bool
+    is_false_positive: bool
+    is_done_signal: bool
+    is_hint: bool
+    explanation: str
+
+
+# ── Per-step reward values ────────────────────────────────────────────────
+
+CORRECT_VIOLATION_REWARD = 1.0
+PATH_MATCH_REWARD = 0.3          # right field, wrong violation_type
+HINT_PENALTY = -0.5              # cost of requesting a location hint
+DUPLICATE_PENALTY = -0.1
+FALSE_POSITIVE_PENALTY = -0.3
+DONE_BONUS_MULTIPLIER = 0.5      # bonus = multiplier * (correct / total)
+
+
+def compute_step_reward(
+    *,
+    is_correct: bool,
+    is_path_match: bool = False,
+    is_duplicate: bool,
+    is_done_signal: bool,
+    is_hint: bool = False,
+    correct_so_far: int,
+    total_violations: int,
+) -> RewardBreakdown:
+    """Compute reward for a single agent step.
+
+    Parameters
+    ----------
+    is_correct:
+        Whether the report fully matches a ground-truth violation (path + type).
+    is_path_match:
+        Whether the field_path matches a violation but violation_type is wrong.
+    is_duplicate:
+        Whether the agent already reported this violation.
+    is_done_signal:
+        Whether the agent submitted ``field_path='DONE'``.
+    is_hint:
+        Whether the agent submitted ``field_path='HINT'``.
+    correct_so_far:
+        Number of unique correct violations found before this step.
+    total_violations:
+        Total planted violations in the current scenario.
+
+    Returns
+    -------
+    RewardBreakdown
+        Contains the scalar reward and a human-readable explanation.
+    """
+    if is_hint:
+        return RewardBreakdown(
+            reward=HINT_PENALTY,
+            is_correct=False,
+            is_path_match=False,
+            is_duplicate=False,
+            is_false_positive=False,
+            is_done_signal=False,
+            is_hint=True,
+            explanation="Hint requested. -0.5 reward.",
+        )
+
+    if is_done_signal:
+        completeness = correct_so_far / max(total_violations, 1)
+        bonus = DONE_BONUS_MULTIPLIER * completeness
+        return RewardBreakdown(
+            reward=round(bonus, 4),
+            is_correct=False,
+            is_path_match=False,
+            is_duplicate=False,
+            is_false_positive=False,
+            is_done_signal=True,
+            is_hint=False,
+            explanation=(
+                f"Agent signalled DONE. "
+                f"Completeness {correct_so_far}/{total_violations} "
+                f"→ bonus {bonus:.2f}"
+            ),
+        )
+
+    if is_duplicate:
+        return RewardBreakdown(
+            reward=DUPLICATE_PENALTY,
+            is_correct=False,
+            is_path_match=False,
+            is_duplicate=True,
+            is_false_positive=False,
+            is_done_signal=False,
+            is_hint=False,
+            explanation="Duplicate violation report — already submitted.",
+        )
+
+    if is_correct:
+        return RewardBreakdown(
+            reward=CORRECT_VIOLATION_REWARD,
+            is_correct=True,
+            is_path_match=False,
+            is_duplicate=False,
+            is_false_positive=False,
+            is_done_signal=False,
+            is_hint=False,
+            explanation="Correct! Violation matches ground truth.",
+        )
+
+    if is_path_match:
+        return RewardBreakdown(
+            reward=PATH_MATCH_REWARD,
+            is_correct=False,
+            is_path_match=True,
+            is_duplicate=False,
+            is_false_positive=False,
+            is_done_signal=False,
+            is_hint=False,
+            explanation=(
+                "Correct field location! The field_path matches a violation, "
+                "but the violation_type is wrong. Try again with the right type."
+            ),
+        )
+
+    # False positive
+    return RewardBreakdown(
+        reward=FALSE_POSITIVE_PENALTY,
+        is_correct=False,
+        is_path_match=False,
+        is_duplicate=False,
+        is_false_positive=True,
+        is_done_signal=False,
+        is_hint=False,
+        explanation="False positive — no matching violation in ground truth.",
+    )
+
+
+def compute_episode_score(correct_count: int, total_violations: int) -> float:
+    """Compute the final normalised score for the episode.
+
+    Returns a float in ``[0.0, 1.0]``.
+    """
+    if total_violations == 0:
+        return 1.0
+    return round(correct_count / total_violations, 4)

server/spec_generator.py

@@ -0,0 +1,1655 @@
+"""
+Spec generator for the API Contract Validator Environment.
+
+Generates OpenAPI specifications, payloads with planted violations,
+and ground-truth violation records for four difficulty levels.
+
+Each generator accepts an optional *seed* for deterministic randomisation:
+- seed=None  → fixed canonical scenario (backward-compatible)
+- seed=int   → reproducible randomised variant
+
+This makes the environment suitable for both evaluation (fixed seed) and
+training (varied seeds), which is the key distinction between a one-shot
+evaluator and a genuine RL training environment.
+"""
+
+import random
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+
+# Sentinel used in violation pool entries to signal "remove key from payload"
+_REMOVE = object()
+
+
+@dataclass
+class PlantedViolation:
+    """A single ground-truth violation planted in a payload."""
+
+    field_path: str
+    violation_type: str
+    description: str
+    expected_value: str
+    actual_value: str
+
+
+@dataclass
+class TaskScenario:
+    """Everything the environment needs for one episode."""
+
+    task_name: str
+    task_description: str
+    api_spec: Dict[str, Any]
+    payload: Dict[str, Any]
+    violations: List[PlantedViolation]
+    max_steps: int
+
+
+# ── Easy Task — pool-based randomisation ──────────────────────────────────
+#
+# The spec exposes 8 fields.  Each episode seeds a random draw of 4 of the
+# 8 possible violations, giving 70 unique episode combinations — enough to
+# train an agent rather than just evaluate it once.
+
+_EASY_SPEC: Dict[str, Any] = {
+    "openapi": "3.0.3",
+    "info": {"title": "User Service API", "version": "1.0.0"},
+    "paths": {
+        "/users": {
+            "post": {
+                "summary": "Create a new user",
+                "requestBody": {
+                    "required": True,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "object",
+                                "required": ["username", "email", "age", "is_active"],
+                                "properties": {
+                                    "username": {
+                                        "type": "string",
+                                        "minLength": 3,
+                                        "maxLength": 32,
+                                    },
+                                    "email": {
+                                        "type": "string",
+                                        "format": "email",
+                                    },
+                                    "age": {
+                                        "type": "integer",
+                                        "minimum": 0,
+                                        "maximum": 120,
+                                    },
+                                    "is_active": {"type": "boolean"},
+                                    "role": {
+                                        "type": "string",
+                                        "enum": ["admin", "editor", "viewer"],
+                                    },
+                                    "phone": {
+                                        "type": "string",
+                                        "pattern": r"^\+[1-9][0-9]{7,14}$",
+                                    },
+                                    "account_balance": {
+                                        "type": "number",
+                                        "minimum": 0.0,
+                                    },
+                                    "terms_accepted": {"type": "boolean"},
+                                },
+                            }
+                        }
+                    },
+                },
+            }
+        }
+    },
+}
+
+# Base payload — all fields valid.  Pool entries mutate specific keys.
+_EASY_VALID_PAYLOAD: Dict[str, Any] = {
+    "username": "alice_smith",
+    "email": "alice@example.com",
+    "age": 28,
+    "is_active": True,
+    "role": "editor",
+    "phone": "+14155551234",
+    "account_balance": 250.00,
+    "terms_accepted": True,
+}
+
+# Pool: (top-level key, bad value or _REMOVE, PlantedViolation)
+# The first 4 entries reproduce the original fixed scenario (seed=None).
+_EASY_POOL: List[Tuple[str, Any, PlantedViolation]] = [
+    (
+        "email",
+        _REMOVE,
+        PlantedViolation(
+            field_path="email",
+            violation_type="missing_required",
+            description="Required field 'email' is missing from the payload.",
+            expected_value="(present, type: string, format: email)",
+            actual_value="(missing)",
+        ),
+    ),
+    (
+        "age",
+        "twenty-five",
+        PlantedViolation(
+            field_path="age",
+            violation_type="type_mismatch",
+            description="Field 'age' should be integer but received string.",
+            expected_value="integer",
+            actual_value="string ('twenty-five')",
+        ),
+    ),
+    (
+        "is_active",
+        "yes",
+        PlantedViolation(
+            field_path="is_active",
+            violation_type="type_mismatch",
+            description="Field 'is_active' should be boolean but received string.",
+            expected_value="boolean",
+            actual_value="string ('yes')",
+        ),
+    ),
+    (
+        "role",
+        "superadmin",
+        PlantedViolation(
+            field_path="role",
+            violation_type="invalid_enum",
+            description="Value 'superadmin' is not in allowed enum [admin, editor, viewer].",
+            expected_value="one of: admin, editor, viewer",
+            actual_value="superadmin",
+        ),
+    ),
+    (
+        "phone",
+        "555-CALL-US",
+        PlantedViolation(
+            field_path="phone",
+            violation_type="format_error",
+            description="Field 'phone' contains letters; must match international format +E.164.",
+            expected_value=r"pattern: ^\+[1-9][0-9]{7,14}$",
+            actual_value="555-CALL-US",
+        ),
+    ),
+    (
+        "account_balance",
+        -50.00,
+        PlantedViolation(
+            field_path="account_balance",
+            violation_type="format_error",
+            description="Field 'account_balance' is -50.0, below the minimum of 0.",
+            expected_value="number >= 0",
+            actual_value="-50.0",
+        ),
+    ),
+    (
+        "terms_accepted",
+        "agreed",
+        PlantedViolation(
+            field_path="terms_accepted",
+            violation_type="type_mismatch",
+            description="Field 'terms_accepted' should be boolean but received string.",
+            expected_value="boolean",
+            actual_value="string ('agreed')",
+        ),
+    ),
+    (
+        "username",
+        "ab",
+        PlantedViolation(
+            field_path="username",
+            violation_type="format_error",
+            description="Field 'username' is 'ab' (length 2), below minLength of 3.",
+            expected_value="string, minLength: 3",
+            actual_value="'ab' (length 2)",
+        ),
+    ),
+]
+
+
+def generate_easy_scenario(seed: Optional[int] = None) -> TaskScenario:
+    """Easy scenario: 4 violations sampled from a pool of 8.
+
+    seed=None always returns the original canonical 4 violations.
+    Any integer seed reproducibly draws a different subset.
+    """
+    if seed is None:
+        selected = _EASY_POOL[:4]
+    else:
+        rng = random.Random(seed)
+        selected = rng.sample(_EASY_POOL, 4)
+
+    payload = dict(_EASY_VALID_PAYLOAD)
+    violations: List[PlantedViolation] = []
+    for key, bad_val, planted in selected:
+        if bad_val is _REMOVE:
+            payload.pop(key, None)
+        else:
+            payload[key] = bad_val
+        violations.append(planted)
+
+    return TaskScenario(
+        task_name="find_type_mismatches",
+        task_description=(
+            "You are given an OpenAPI specification and an API request payload. "
+            "Find all violations in the payload: type mismatches, missing required "
+            "fields, invalid enum values, and format errors. "
+            "Report one violation per step using the field's dot-notation path. "
+            "Submit field_path='DONE' when finished."
+        ),
+        api_spec=_EASY_SPEC,
+        payload=payload,
+        violations=violations,
+        max_steps=10,
+    )
+
+
+# ── Medium Task — two complete scenario variants ──────────────────────────
+
+def _medium_scenario_a() -> TaskScenario:
+    """Original Order Service scenario with 7 nested violations."""
+    api_spec: Dict[str, Any] = {
+        "openapi": "3.0.3",
+        "info": {"title": "Order Service API", "version": "2.1.0"},
+        "paths": {
+            "/orders": {
+                "post": {
+                    "summary": "Place a new order",
+                    "requestBody": {
+                        "required": True,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "customer",
+                                        "items",
+                                        "shipping_address",
+                                        "payment_method",
+                                    ],
+                                    "properties": {
+                                        "customer": {
+                                            "type": "object",
+                                            "required": ["id", "email"],
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "email": {
+                                                    "type": "string",
+                                                    "format": "email",
+                                                },
+                                                "loyalty_tier": {
+                                                    "type": "string",
+                                                    "enum": [
+                                                        "bronze",
+                                                        "silver",
+                                                        "gold",
+                                                        "platinum",
+                                                    ],
+                                                },
+                                            },
+                                        },
+                                        "items": {
+                                            "type": "array",
+                                            "minItems": 1,
+                                            "items": {
+                                                "type": "object",
+                                                "required": [
+                                                    "product_id",
+                                                    "quantity",
+                                                    "unit_price",
+                                                ],
+                                                "properties": {
+                                                    "product_id": {"type": "string"},
+                                                    "quantity": {
+                                                        "type": "integer",
+                                                        "minimum": 1,
+                                                    },
+                                                    "unit_price": {
+                                                        "type": "number",
+                                                        "minimum": 0,
+                                                    },
+                                                },
+                                            },
+                                        },
+                                        "shipping_address": {
+                                            "type": "object",
+                                            "required": [
+                                                "street",
+                                                "city",
+                                                "zip_code",
+                                                "country",
+                                            ],
+                                            "properties": {
+                                                "street": {"type": "string"},
+                                                "city": {"type": "string"},
+                                                "zip_code": {"type": "string"},
+                                                "country": {
+                                                    "type": "string",
+                                                    "pattern": "^[A-Z]{2}$",
+                                                },
+                                            },
+                                        },
+                                        "payment_method": {
+                                            "type": "string",
+                                            "enum": [
+                                                "credit_card",
+                                                "debit_card",
+                                                "paypal",
+                                                "bank_transfer",
+                                            ],
+                                        },
+                                    },
+                                }
+                            }
+                        },
+                    },
+                }
+            }
+        },
+    }
+
+    payload: Dict[str, Any] = {
+        "customer": {
+            "id": "C-1001",
+            "loyalty_tier": "diamond",
+        },
+        "items": [
+            {"product_id": "SKU-001", "quantity": 2, "unit_price": 29.99},
+            {"product_id": 12345, "quantity": "three", "unit_price": 15.50},
+        ],
+        "shipping_address": {
+            "street": "123 Main St",
+            "city": "Springfield",
+            "zip_code": 62704,
+            "country": "usa",
+        },
+        "payment_method": "crypto",
+    }
+
+    violations = [
+        PlantedViolation(
+            field_path="customer.email",
+            violation_type="missing_required",
+            description="Required field 'email' missing from 'customer' object.",
+            expected_value="(present, type: string, format: email)",
+            actual_value="(missing)",
+        ),
+        PlantedViolation(
+            field_path="customer.id",
+            violation_type="type_mismatch",
+            description="Field 'customer.id' should be integer, got string.",
+            expected_value="integer",
+            actual_value="string ('C-1001')",
+        ),
+        PlantedViolation(
+            field_path="customer.loyalty_tier",
+            violation_type="invalid_enum",
+            description="Value 'diamond' not in enum [bronze, silver, gold, platinum].",
+            expected_value="one of: bronze, silver, gold, platinum",
+            actual_value="diamond",
+        ),
+        PlantedViolation(
+            field_path="items[1].product_id",
+            violation_type="type_mismatch",
+            description="Array item 'items[1].product_id' should be string, got integer.",
+            expected_value="string",
+            actual_value="integer (12345)",
+        ),
+        PlantedViolation(
+            field_path="items[1].quantity",
+            violation_type="type_mismatch",
+            description="Array item 'items[1].quantity' should be integer, got string.",
+            expected_value="integer",
+            actual_value="string ('three')",
+        ),
+        PlantedViolation(
+            field_path="shipping_address.zip_code",
+            violation_type="type_mismatch",
+            description="Field 'shipping_address.zip_code' should be string, got integer.",
+            expected_value="string",
+            actual_value="integer (62704)",
+        ),
+        PlantedViolation(
+            field_path="payment_method",
+            violation_type="invalid_enum",
+            description="Value 'crypto' not in enum [credit_card, debit_card, paypal, bank_transfer].",
+            expected_value="one of: credit_card, debit_card, paypal, bank_transfer",
+            actual_value="crypto",
+        ),
+    ]
+
+    return TaskScenario(
+        task_name="validate_nested_objects",
+        task_description=(
+            "You are given an OpenAPI specification and an API request payload "
+            "with nested objects and arrays. Find all violations including type "
+            "mismatches in nested fields, missing required fields inside objects, "
+            "invalid enum values, and type errors in array items. Use dot-notation "
+            "for nested paths (e.g. 'customer.email') and bracket notation for "
+            "arrays (e.g. 'items[1].quantity'). Submit field_path='DONE' when finished."
+        ),
+        api_spec=api_spec,
+        payload=payload,
+        violations=violations,
+        max_steps=15,
+    )
+
+
+def _medium_scenario_b() -> TaskScenario:
+    """Alternate Event Booking scenario — different domain, 7 nested violations."""
+    api_spec: Dict[str, Any] = {
+        "openapi": "3.0.3",
+        "info": {"title": "Event Booking API", "version": "1.5.0"},
+        "paths": {
+            "/bookings": {
+                "post": {
+                    "summary": "Book an event",
+                    "requestBody": {
+                        "required": True,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": ["event", "attendees", "organizer", "payment"],
+                                    "properties": {
+                                        "event": {
+                                            "type": "object",
+                                            "required": ["id", "type", "capacity"],
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "type": {
+                                                    "type": "string",
+                                                    "enum": [
+                                                        "concert",
+                                                        "conference",
+                                                        "sports",
+                                                        "theater",
+                                                    ],
+                                                },
+                                                "capacity": {
+                                                    "type": "integer",
+                                                    "minimum": 1,
+                                                },
+                                                "date": {
+                                                    "type": "string",
+                                                    "format": "date",
+                                                },
+                                            },
+                                        },
+                                        "attendees": {
+                                            "type": "array",
+                                            "minItems": 1,
+                                            "items": {
+                                                "type": "object",
+                                                "required": ["name", "email", "ticket_type"],
+                                                "properties": {
+                                                    "name": {"type": "string"},
+                                                    "email": {
+                                                        "type": "string",
+                                                        "format": "email",
+                                                    },
+                                                    "age": {
+                                                        "type": "integer",
+                                                        "minimum": 0,
+                                                        "maximum": 120,
+                                                    },
+                                                    "ticket_type": {
+                                                        "type": "string",
+                                                        "enum": [
+                                                            "vip",
+                                                            "standard",
+                                                            "economy",
+                                                        ],
+                                                    },
+                                                },
+                                            },
+                                        },
+                                        "organizer": {
+                                            "type": "object",
+                                            "required": ["name", "contact_email"],
+                                            "properties": {
+                                                "name": {"type": "string"},
+                                                "contact_email": {
+                                                    "type": "string",
+                                                    "format": "email",
+                                                },
+                                                "phone": {"type": "string"},
+                                            },
+                                        },
+                                        "payment": {
+                                            "type": "object",
+                                            "required": ["method", "total_amount"],
+                                            "properties": {
+                                                "method": {
+                                                    "type": "string",
+                                                    "enum": [
+                                                        "card",
+                                                        "invoice",
+                                                        "cash",
+                                                    ],
+                                                },
+                                                "total_amount": {
+                                                    "type": "number",
+                                                    "minimum": 0,
+                                                },
+                                            },
+                                        },
+                                    },
+                                }
+                            }
+                        },
+                    },
+                }
+            }
+        },
+    }
+
+    payload: Dict[str, Any] = {
+        "event": {
+            "id": "EVT-001",
+            "type": "festival",
+            "capacity": 500,
+            "date": "2025-06-15",
+        },
+        "attendees": [
+            {
+                "name": "Sarah Chen",
+                "ticket_type": "vip",
+            },
+            {
+                "name": "Mark Rivera",
+                "email": "mark@example.com",
+                "age": 135,
+                "ticket_type": "premium",
+            },
+        ],
+        "organizer": {
+            "name": "LiveNation Events",
+            "contact_email": "organizer.example.com",
+            "phone": "+442071234567",
+        },
+        "payment": {
+            "method": "card",
+            "total_amount": "free",
+        },
+    }
+
+    violations = [
+        PlantedViolation(
+            field_path="event.id",
+            violation_type="type_mismatch",
+            description="Field 'event.id' should be integer, got string.",
+            expected_value="integer",
+            actual_value="string ('EVT-001')",
+        ),
+        PlantedViolation(
+            field_path="event.type",
+            violation_type="invalid_enum",
+            description="Value 'festival' not in enum [concert, conference, sports, theater].",
+            expected_value="one of: concert, conference, sports, theater",
+            actual_value="festival",
+        ),
+        PlantedViolation(
+            field_path="attendees[0].email",
+            violation_type="missing_required",
+            description="Required field 'email' missing from attendees[0].",
+            expected_value="(present, type: string, format: email)",
+            actual_value="(missing)",
+        ),
+        PlantedViolation(
+            field_path="attendees[1].age",
+            violation_type="format_error",
+            description="Field 'attendees[1].age' is 135, exceeds maximum of 120.",
+            expected_value="integer, maximum: 120",
+            actual_value="135",
+        ),
+        PlantedViolation(
+            field_path="attendees[1].ticket_type",
+            violation_type="invalid_enum",
+            description="Value 'premium' not in enum [vip, standard, economy].",
+            expected_value="one of: vip, standard, economy",
+            actual_value="premium",
+        ),
+        PlantedViolation(
+            field_path="organizer.contact_email",
+            violation_type="format_error",
+            description="Field 'organizer.contact_email' is not a valid email (missing @).",
+            expected_value="string, format: email",
+            actual_value="'organizer.example.com'",
+        ),
+        PlantedViolation(
+            field_path="payment.total_amount",
+            violation_type="type_mismatch",
+            description="Field 'payment.total_amount' should be number, got string.",
+            expected_value="number",
+            actual_value="string ('free')",
+        ),
+    ]
+
+    return TaskScenario(
+        task_name="validate_nested_objects",
+        task_description=(
+            "You are given an OpenAPI specification and an API request payload "
+            "with nested objects and arrays. Find all violations including type "
+            "mismatches in nested fields, missing required fields inside objects, "
+            "invalid enum values, format errors, and type errors in array items. "
+            "Use dot-notation for nested paths (e.g. 'organizer.contact_email') "
+            "and bracket notation for arrays (e.g. 'attendees[1].age'). "
+            "Submit field_path='DONE' when finished."
+        ),
+        api_spec=api_spec,
+        payload=payload,
+        violations=violations,
+        max_steps=15,
+    )
+
+
+def generate_medium_scenario(seed: Optional[int] = None) -> TaskScenario:
+    """Medium scenario: two complete variants selected by seed.
+
+    seed=None or even seed → Order Service (variant A, original).
+    Odd seed → Event Booking (variant B).
+    """
+    if seed is None or seed % 2 == 0:
+        return _medium_scenario_a()
+    return _medium_scenario_b()
+
+
+# ── Hard Task — breaking changes (fixed, no variant needed) ───────────────
+
+
+def generate_hard_scenario(seed: Optional[int] = None) -> TaskScenario:
+    """Hard scenario: 9 breaking changes between two API spec versions.
+
+    The task is inherently complex (spec-diffing); a single well-designed
+    scenario is more valuable than noisy variants.  seed is accepted for
+    API uniformity but not used.
+    """
+    api_spec: Dict[str, Any] = {
+        "description": (
+            "Compare v1 (old) and v2 (new) of the Product Catalog API. "
+            "Identify all BREAKING changes that would cause existing v1 "
+            "clients to fail when calling the v2 API."
+        ),
+        "v1": {
+            "openapi": "3.0.3",
+            "info": {"title": "Product Catalog API", "version": "1.0.0"},
+            "paths": {
+                "/products": {
+                    "post": {
+                        "summary": "Create a product",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "required": ["name", "price", "category"],
+                                        "properties": {
+                                            "name": {"type": "string"},
+                                            "description": {"type": "string"},
+                                            "price": {"type": "number"},
+                                            "category": {
+                                                "type": "string",
+                                                "enum": [
+                                                    "electronics",
+                                                    "clothing",
+                                                    "books",
+                                                    "home",
+                                                    "sports",
+                                                ],
+                                            },
+                                            "tags": {
+                                                "type": "array",
+                                                "items": {"type": "string"},
+                                            },
+                                            "weight_kg": {"type": "number"},
+                                            "supplier_code": {"type": "string"},
+                                        },
+                                    }
+                                }
+                            },
+                        },
+                    },
+                    "get": {
+                        "summary": "List products",
+                        "responses": {
+                            "200": {
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "array",
+                                            "items": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "id": {"type": "integer"},
+                                                    "name": {"type": "string"},
+                                                    "price": {"type": "number"},
+                                                    "category": {"type": "string"},
+                                                    "discount_percent": {
+                                                        "type": "number"
+                                                    },
+                                                },
+                                            },
+                                        }
+                                    }
+                                }
+                            }
+                        },
+                    },
+                }
+            },
+        },
+        "v2": {
+            "openapi": "3.0.3",
+            "info": {"title": "Product Catalog API", "version": "2.0.0"},
+            "paths": {
+                "/products": {
+                    "post": {
+                        "summary": "Create a product",
+                        "requestBody": {
+                            "required": True,
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "type": "object",
+                                        "required": [
+                                            "name",
+                                            "price",
+                                            "category",
+                                            "sku",
+                                        ],
+                                        "properties": {
+                                            "name": {"type": "string"},
+                                            "description": {"type": "string"},
+                                            "price": {"type": "string"},
+                                            "category": {
+                                                "type": "string",
+                                                "enum": [
+                                                    "electronics",
+                                                    "clothing",
+                                                    "books",
+                                                ],
+                                            },
+                                            "tags": {"type": "integer"},
+                                            "sku": {"type": "string"},
+                                            "weight_grams": {"type": "integer"},
+                                        },
+                                    }
+                                }
+                            },
+                        },
+                    },
+                    "get": {
+                        "summary": "List products",
+                        "responses": {
+                            "200": {
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "type": "array",
+                                            "items": {
+                                                "type": "object",
+                                                "properties": {
+                                                    "id": {"type": "string"},
+                                                    "name": {"type": "string"},
+                                                    "price": {"type": "string"},
+                                                    "category": {"type": "string"},
+                                                },
+                                            },
+                                        }
+                                    }
+                                }
+                            }
+                        },
+                    },
+                }
+            },
+        },
+    }
+
+    payload: Dict[str, Any] = {
+        "name": "Wireless Headphones",
+        "description": "Noise-cancelling over-ear headphones",
+        "price": 79.99,
+        "category": "sports",
+        "tags": ["audio", "wireless"],
+        "weight_kg": 0.35,
+        "supplier_code": "SUP-442",
+    }
+
+    violations = [
+        PlantedViolation(
+            field_path="POST /products.price",
+            violation_type="breaking_change",
+            description="Field 'price' type changed from 'number' to 'string' in v2.",
+            expected_value="number (v1)",
+            actual_value="string (v2)",
+        ),
+        PlantedViolation(
+            field_path="POST /products.category",
+            violation_type="breaking_change",
+            description="Enum for 'category' narrowed: 'home' and 'sports' removed in v2.",
+            expected_value="enum: electronics, clothing, books, home, sports (v1)",
+            actual_value="enum: electronics, clothing, books (v2)",
+        ),
+        PlantedViolation(
+            field_path="POST /products.tags",
+            violation_type="breaking_change",
+            description="Field 'tags' type changed from 'array of strings' to 'integer' in v2.",
+            expected_value="array of strings (v1)",
+            actual_value="integer (v2)",
+        ),
+        PlantedViolation(
+            field_path="POST /products.sku",
+            violation_type="breaking_change",
+            description="New required field 'sku' added in v2 — breaks existing clients.",
+            expected_value="(not required in v1)",
+            actual_value="required string (v2)",
+        ),
+        PlantedViolation(
+            field_path="POST /products.supplier_code",
+            violation_type="breaking_change",
+            description="Field 'supplier_code' removed in v2 — clients sending it get rejected.",
+            expected_value="string (v1)",
+            actual_value="(removed in v2)",
+        ),
+        PlantedViolation(
+            field_path="POST /products.weight_kg",
+            violation_type="breaking_change",
+            description="Field 'weight_kg' removed; replaced by 'weight_grams' with different type.",
+            expected_value="number 'weight_kg' (v1)",
+            actual_value="integer 'weight_grams' (v2)",
+        ),
+        PlantedViolation(
+            field_path="GET /products[].id",
+            violation_type="breaking_change",
+            description="Response field 'id' type changed from 'integer' to 'string' in v2.",
+            expected_value="integer (v1)",
+            actual_value="string (v2)",
+        ),
+        PlantedViolation(
+            field_path="GET /products[].price",
+            violation_type="breaking_change",
+            description="Response field 'price' type changed from 'number' to 'string' in v2.",
+            expected_value="number (v1)",
+            actual_value="string (v2)",
+        ),
+        PlantedViolation(
+            field_path="GET /products[].discount_percent",
+            violation_type="breaking_change",
+            description="Response field 'discount_percent' removed in v2 — dependent clients break.",
+            expected_value="number (v1)",
+            actual_value="(removed in v2)",
+        ),
+    ]
+
+    return TaskScenario(
+        task_name="detect_breaking_changes",
+        task_description=(
+            "You are given two versions (v1 and v2) of a Product Catalog API "
+            "specification, plus a sample v1 client payload. Identify all "
+            "BREAKING changes between v1 and v2 that would cause existing "
+            "clients to fail. Breaking changes include: type changes, removed "
+            "fields, narrowed enums, new required fields, and removed response "
+            "fields. Use the format 'METHOD /path.field' for paths "
+            "(e.g. 'POST /products.price'). Submit field_path='DONE' when finished."
+        ),
+        api_spec=api_spec,
+        payload=payload,
+        violations=violations,
+        max_steps=20,
+    )
+
+
+# ── Expert Task — response schema format validation ───────────────────────
+#
+# Agents must validate an API *response* (not a request) against the spec.
+# Violations are subtle: pattern mismatches, out-of-range numerics, wrong
+# date formats, and invalid enum values scattered across nested objects and
+# arrays.  Two complete variants are provided via seed selection.
+
+_RESPONSE_SPEC: Dict[str, Any] = {
+    "openapi": "3.0.3",
+    "info": {"title": "E-Commerce Order API", "version": "3.0.0"},
+    "paths": {
+        "/orders/{order_id}": {
+            "get": {
+                "summary": "Retrieve a single order",
+                "responses": {
+                    "200": {
+                        "description": "Order details",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "order_id",
+                                        "created_at",
+                                        "status",
+                                        "customer",
+                                        "items",
+                                        "billing",
+                                    ],
+                                    "properties": {
+                                        "order_id": {
+                                            "type": "string",
+                                            "pattern": "^ORD-[0-9]{6}$",
+                                            "description": "Must match ORD-NNNNNN exactly",
+                                        },
+                                        "created_at": {
+                                            "type": "string",
+                                            "format": "date-time",
+                                            "description": "ISO 8601 date-time, e.g. 2024-01-15T10:30:00Z",
+                                        },
+                                        "promised_delivery_date": {
+                                            "type": "string",
+                                            "format": "date",
+                                            "description": "ISO 8601 date, e.g. 2024-03-20",
+                                        },
+                                        "status": {
+                                            "type": "string",
+                                            "enum": [
+                                                "pending",
+                                                "processing",
+                                                "shipped",
+                                                "delivered",
+                                                "cancelled",
+                                            ],
+                                        },
+                                        "customer": {
+                                            "type": "object",
+                                            "required": ["email", "phone", "loyalty_points"],
+                                            "properties": {
+                                                "email": {
+                                                    "type": "string",
+                                                    "format": "email",
+                                                },
+                                                "phone": {
+                                                    "type": "string",
+                                                    "pattern": r"^\+[1-9][0-9]{7,14}$",
+                                                    "description": "E.164 format, e.g. +14155552671",
+                                                },
+                                                "loyalty_points": {
+                                                    "type": "integer",
+                                                    "minimum": 0,
+                                                },
+                                            },
+                                        },
+                                        "items": {
+                                            "type": "array",
+                                            "minItems": 1,
+                                            "items": {
+                                                "type": "object",
+                                                "required": [
+                                                    "sku",
+                                                    "unit_price",
+                                                    "quantity",
+                                                    "discount_rate",
+                                                ],
+                                                "properties": {
+                                                    "sku": {
+                                                        "type": "string",
+                                                        "pattern": "^SKU-[A-Z0-9]{6}$",
+                                                        "description": "Must match SKU-XXXXXX",
+                                                    },
+                                                    "unit_price": {
+                                                        "type": "number",
+                                                        "minimum": 0.01,
+                                                    },
+                                                    "quantity": {
+                                                        "type": "integer",
+                                                        "minimum": 1,
+                                                        "maximum": 100,
+                                                    },
+                                                    "discount_rate": {
+                                                        "type": "number",
+                                                        "minimum": 0,
+                                                        "maximum": 1,
+                                                    },
+                                                },
+                                            },
+                                        },
+                                        "billing": {
+                                            "type": "object",
+                                            "required": ["subtotal", "tax_rate", "total"],
+                                            "properties": {
+                                                "subtotal": {
+                                                    "type": "number",
+                                                    "minimum": 0,
+                                                },
+                                                "tax_rate": {
+                                                    "type": "number",
+                                                    "minimum": 0,
+                                                    "maximum": 0.5,
+                                                    "description": "Fraction 0.0–0.5 (max 50%)",
+                                                },
+                                                "total": {
+                                                    "type": "number",
+                                                    "minimum": 0,
+                                                },
+                                            },
+                                        },
+                                        "tracking_code": {
+                                            "type": "string",
+                                            "pattern": "^[A-Z]{2}[0-9]{9}[A-Z]{2}$",
+                                            "description": "2 upper letters + 9 digits + 2 upper letters",
+                                        },
+                                        "estimated_days": {
+                                            "type": "integer",
+                                            "minimum": 1,
+                                            "maximum": 30,
+                                        },
+                                    },
+                                }
+                            }
+                        },
+                    }
+                },
+            }
+        }
+    },
+}
+
+_RESPONSE_TASK_DESCRIPTION = (
+    "You are given an OpenAPI response schema for GET /orders/{order_id} "
+    "and an actual API response. Validate the response against the schema. "
+    "Find all violations including: format errors (invalid date/time formats, "
+    "pattern mismatches, out-of-range numeric values), type mismatches, and "
+    "invalid enum values. These are subtle — read the spec constraints carefully "
+    "(patterns, minimum/maximum, format strings). "
+    "Use dot-notation for nested paths and bracket notation for arrays. "
+    "Submit field_path='DONE' when finished."
+)
+
+
+def _response_scenario_a() -> TaskScenario:
+    """Expert variant A: 10 format/constraint violations in an order response."""
+    payload: Dict[str, Any] = {
+        "order_id": "ORDER-123456",           # format_error: must be ORD-NNNNNN
+        "created_at": "2024-01-15 10:30:00",  # format_error: missing T separator (not ISO 8601)
+        "promised_delivery_date": "15/01/2024",  # format_error: DD/MM/YYYY not YYYY-MM-DD
+        "status": "refunded",                 # invalid_enum
+        "customer": {
+            "email": "customer@@example.com", # format_error: double @
+            "phone": "555-1234",              # format_error: not E.164
+            "loyalty_points": 1500,           # valid
+        },
+        "items": [
+            {
+                "sku": "SKU-AB1234",           # valid
+                "unit_price": 0.00,           # format_error: below minimum 0.01
+                "quantity": 2,
+                "discount_rate": 0.1,
+            },
+            {
+                "sku": "SKU-CD5678",           # valid
+                "unit_price": 49.99,
+                "quantity": 150,              # format_error: exceeds maximum 100
+                "discount_rate": 0.15,
+            },
+        ],
+        "billing": {
+            "subtotal": 149.97,
+            "tax_rate": 0.65,                 # format_error: exceeds maximum 0.5
+            "total": 248.95,
+        },
+        "tracking_code": "TRACK123456789",    # format_error: wrong pattern
+        "estimated_days": 5,
+    }
+
+    violations = [
+        PlantedViolation(
+            field_path="order_id",
+            violation_type="format_error",
+            description="'ORDER-123456' does not match required pattern ^ORD-[0-9]{6}$.",
+            expected_value="string matching ^ORD-[0-9]{6}$",
+            actual_value="'ORDER-123456'",
+        ),
+        PlantedViolation(
+            field_path="created_at",
+            violation_type="format_error",
+            description="'2024-01-15 10:30:00' is not valid ISO 8601 date-time (missing T separator).",
+            expected_value="date-time, e.g. 2024-01-15T10:30:00Z",
+            actual_value="'2024-01-15 10:30:00'",
+        ),
+        PlantedViolation(
+            field_path="promised_delivery_date",
+            violation_type="format_error",
+            description="'15/01/2024' is not valid ISO 8601 date (expected YYYY-MM-DD).",
+            expected_value="date, e.g. 2024-01-15",
+            actual_value="'15/01/2024'",
+        ),
+        PlantedViolation(
+            field_path="status",
+            violation_type="invalid_enum",
+            description="Value 'refunded' not in enum [pending, processing, shipped, delivered, cancelled].",
+            expected_value="one of: pending, processing, shipped, delivered, cancelled",
+            actual_value="'refunded'",
+        ),
+        PlantedViolation(
+            field_path="customer.email",
+            violation_type="format_error",
+            description="'customer@@example.com' is not a valid email (double @ symbol).",
+            expected_value="string, format: email",
+            actual_value="'customer@@example.com'",
+        ),
+        PlantedViolation(
+            field_path="customer.phone",
+            violation_type="format_error",
+            description="'555-1234' does not match E.164 pattern ^\\+[1-9][0-9]{7,14}$.",
+            expected_value=r"string matching ^\+[1-9][0-9]{7,14}$",
+            actual_value="'555-1234'",
+        ),
+        PlantedViolation(
+            field_path="items[0].unit_price",
+            violation_type="format_error",
+            description="'items[0].unit_price' is 0.0, below minimum of 0.01.",
+            expected_value="number >= 0.01",
+            actual_value="0.0",
+        ),
+        PlantedViolation(
+            field_path="items[1].quantity",
+            violation_type="format_error",
+            description="'items[1].quantity' is 150, exceeds maximum of 100.",
+            expected_value="integer, maximum: 100",
+            actual_value="150",
+        ),
+        PlantedViolation(
+            field_path="billing.tax_rate",
+            violation_type="format_error",
+            description="'billing.tax_rate' is 0.65, exceeds maximum of 0.5 (50%).",
+            expected_value="number, maximum: 0.5",
+            actual_value="0.65",
+        ),
+        PlantedViolation(
+            field_path="tracking_code",
+            violation_type="format_error",
+            description="'TRACK123456789' does not match pattern ^[A-Z]{2}[0-9]{9}[A-Z]{2}$.",
+            expected_value="string matching ^[A-Z]{2}[0-9]{9}[A-Z]{2}$",
+            actual_value="'TRACK123456789'",
+        ),
+    ]
+
+    return TaskScenario(
+        task_name="validate_response_schema",
+        task_description=_RESPONSE_TASK_DESCRIPTION,
+        api_spec=_RESPONSE_SPEC,
+        payload=payload,
+        violations=violations,
+        max_steps=25,
+    )
+
+
+def _response_scenario_b() -> TaskScenario:
+    """Expert variant B: 10 different format/constraint violations — harder to spot."""
+    payload: Dict[str, Any] = {
+        "order_id": "ORD-12AB56",             # format_error: non-digits in numeric portion
+        "created_at": "2024-13-01T10:30:00Z", # format_error: month 13 is invalid
+        "promised_delivery_date": "2024-00-15", # format_error: month 0 is invalid
+        "status": "returned",                  # invalid_enum
+        "customer": {
+            "email": "user@",                  # format_error: incomplete email, no domain
+            "phone": "+14155551234",           # valid
+            "loyalty_points": "1500",          # type_mismatch: string instead of integer
+        },
+        "items": [
+            {
+                "sku": "PROD-AB1234",          # format_error: wrong prefix (PROD vs SKU)
+                "unit_price": 29.99,
+                "quantity": 2,
+                "discount_rate": 1.5,          # format_error: exceeds maximum 1.0
+            },
+            {
+                "sku": "SKU-CD5678",           # valid
+                "unit_price": 49.99,
+                "quantity": 3,
+                "discount_rate": 0.0,
+            },
+        ],
+        "billing": {
+            "subtotal": "99.50",              # type_mismatch: string instead of number
+            "tax_rate": 0.18,
+            "total": 117.41,
+        },
+        "tracking_code": "AB123456789CD",     # valid — matches ^[A-Z]{2}[0-9]{9}[A-Z]{2}$
+        "estimated_days": 0,                  # format_error: below minimum 1
+    }
+
+    violations = [
+        PlantedViolation(
+            field_path="order_id",
+            violation_type="format_error",
+            description="'ORD-12AB56' does not match ^ORD-[0-9]{6}$ (non-digit chars 'AB').",
+            expected_value="string matching ^ORD-[0-9]{6}$",
+            actual_value="'ORD-12AB56'",
+        ),
+        PlantedViolation(
+            field_path="created_at",
+            violation_type="format_error",
+            description="'2024-13-01T10:30:00Z' has invalid month 13 — not a valid date-time.",
+            expected_value="date-time with valid calendar date",
+            actual_value="'2024-13-01T10:30:00Z'",
+        ),
+        PlantedViolation(
+            field_path="promised_delivery_date",
+            violation_type="format_error",
+            description="'2024-00-15' has month 0, which is not a valid calendar month.",
+            expected_value="date with valid month (01–12)",
+            actual_value="'2024-00-15'",
+        ),
+        PlantedViolation(
+            field_path="status",
+            violation_type="invalid_enum",
+            description="Value 'returned' not in enum [pending, processing, shipped, delivered, cancelled].",
+            expected_value="one of: pending, processing, shipped, delivered, cancelled",
+            actual_value="'returned'",
+        ),
+        PlantedViolation(
+            field_path="customer.email",
+            violation_type="format_error",
+            description="'user@' is not a valid email address (missing domain after @).",
+            expected_value="string, format: email",
+            actual_value="'user@'",
+        ),
+        PlantedViolation(
+            field_path="customer.loyalty_points",
+            violation_type="type_mismatch",
+            description="Field 'customer.loyalty_points' should be integer, got string.",
+            expected_value="integer",
+            actual_value="string ('1500')",
+        ),
+        PlantedViolation(
+            field_path="items[0].sku",
+            violation_type="format_error",
+            description="'PROD-AB1234' does not match required pattern ^SKU-[A-Z0-9]{6}$.",
+            expected_value="string matching ^SKU-[A-Z0-9]{6}$",
+            actual_value="'PROD-AB1234'",
+        ),
+        PlantedViolation(
+            field_path="items[0].discount_rate",
+            violation_type="format_error",
+            description="'items[0].discount_rate' is 1.5, exceeds maximum of 1.0.",
+            expected_value="number, maximum: 1.0",
+            actual_value="1.5",
+        ),
+        PlantedViolation(
+            field_path="billing.subtotal",
+            violation_type="type_mismatch",
+            description="Field 'billing.subtotal' should be number, got string.",
+            expected_value="number",
+            actual_value="string ('99.50')",
+        ),
+        PlantedViolation(
+            field_path="estimated_days",
+            violation_type="format_error",
+            description="'estimated_days' is 0, below minimum of 1.",
+            expected_value="integer, minimum: 1",
+            actual_value="0",
+        ),
+    ]
+
+    return TaskScenario(
+        task_name="validate_response_schema",
+        task_description=_RESPONSE_TASK_DESCRIPTION,
+        api_spec=_RESPONSE_SPEC,
+        payload=payload,
+        violations=violations,
+        max_steps=25,
+    )
+
+
+def generate_format_validation_scenario(seed: Optional[int] = None) -> TaskScenario:
+    """Expert scenario: validate an API response for format/constraint violations.
+
+    seed=None or even seed → variant A.
+    Odd seed → variant B (different set of violations, same spec).
+    """
+    if seed is None or seed % 2 == 0:
+        return _response_scenario_a()
+    return _response_scenario_b()
+
+
+# ── Expert Task 2 — cross-field constraint validation ─────────────────────
+#
+# Violations require multi-field reasoning: arithmetic, date ordering, and
+# conditional requirements.  Standard schema validators cannot catch these;
+# an agent must actively compute and cross-reference values.
+
+
+def generate_cross_field_scenario(seed: Optional[int] = None) -> TaskScenario:
+    """Expert scenario: 7 cross-field constraint violations.
+
+    Requires the agent to:
+    - Verify arithmetic (line_total = quantity * unit_price)
+    - Check date ordering (due_date after invoice_date)
+    - Validate computed totals (tax_amount = subtotal * tax_rate)
+    - Enforce conditional rules (trial accounts: discount_amount = 0)
+    - Count array elements (item_count = len(line_items))
+
+    seed is accepted for API uniformity but not used (single canonical scenario).
+    """
+    api_spec: Dict[str, Any] = {
+        "openapi": "3.0.3",
+        "info": {"title": "Invoice Service API", "version": "1.0.0"},
+        "paths": {
+            "/invoices": {
+                "post": {
+                    "summary": "Create a new invoice",
+                    "description": (
+                        "Cross-field constraints (not expressible in JSON Schema): "
+                        "(1) due_date must be strictly after invoice_date. "
+                        "(2) Each line_items[N].line_total must equal quantity * unit_price. "
+                        "(3) billing.subtotal must equal the sum of all line_items[N].line_total values. "
+                        "(4) billing.tax_amount must equal billing.subtotal * billing.tax_rate. "
+                        "(5) billing.total must equal billing.subtotal + billing.tax_amount - billing.discount_amount. "
+                        "(6) billing.item_count must equal the number of elements in the line_items array. "
+                        "(7) If customer.account_type is 'trial', billing.discount_amount must be 0."
+                    ),
+                    "requestBody": {
+                        "required": True,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "invoice_date",
+                                        "due_date",
+                                        "customer",
+                                        "line_items",
+                                        "billing",
+                                    ],
+                                    "properties": {
+                                        "invoice_date": {
+                                            "type": "string",
+                                            "format": "date",
+                                        },
+                                        "due_date": {
+                                            "type": "string",
+                                            "format": "date",
+                                            "description": "Must be strictly after invoice_date",
+                                        },
+                                        "customer": {
+                                            "type": "object",
+                                            "required": ["id", "name", "account_type"],
+                                            "properties": {
+                                                "id": {"type": "integer"},
+                                                "name": {"type": "string"},
+                                                "account_type": {
+                                                    "type": "string",
+                                                    "enum": [
+                                                        "trial",
+                                                        "standard",
+                                                        "premium",
+                                                        "enterprise",
+                                                    ],
+                                                },
+                                            },
+                                        },
+                                        "line_items": {
+                                            "type": "array",
+                                            "minItems": 1,
+                                            "items": {
+                                                "type": "object",
+                                                "required": [
+                                                    "description",
+                                                    "quantity",
+                                                    "unit_price",
+                                                    "line_total",
+                                                ],
+                                                "properties": {
+                                                    "description": {"type": "string"},
+                                                    "quantity": {
+                                                        "type": "integer",
+                                                        "minimum": 1,
+                                                    },
+                                                    "unit_price": {
+                                                        "type": "number",
+                                                        "minimum": 0,
+                                                    },
+                                                    "line_total": {
+                                                        "type": "number",
+                                                        "description": "Must equal quantity * unit_price",
+                                                    },
+                                                },
+                                            },
+                                        },
+                                        "billing": {
+                                            "type": "object",
+                                            "required": [
+                                                "subtotal",
+                                                "tax_rate",
+                                                "tax_amount",
+                                                "discount_amount",
+                                                "total",
+                                                "item_count",
+                                                "currency",
+                                            ],
+                                            "properties": {
+                                                "subtotal": {
+                                                    "type": "number",
+                                                    "minimum": 0,
+                                                    "description": "Sum of all line_items[N].line_total",
+                                                },
+                                                "tax_rate": {
+                                                    "type": "number",
+                                                    "minimum": 0,
+                                                    "maximum": 1,
+                                                },
+                                                "tax_amount": {
+                                                    "type": "number",
+                                                    "description": "Must equal subtotal * tax_rate",
+                                                },
+                                                "discount_amount": {
+                                                    "type": "number",
+                                                    "minimum": 0,
+                                                    "description": "Must be 0 when customer.account_type is 'trial'",
+                                                },
+                                                "total": {
+                                                    "type": "number",
+                                                    "description": "Must equal subtotal + tax_amount - discount_amount",
+                                                },
+                                                "item_count": {
+                                                    "type": "integer",
+                                                    "description": "Must equal number of elements in line_items",
+                                                },
+                                                "currency": {
+                                                    "type": "string",
+                                                    "enum": ["USD", "EUR", "GBP", "INR"],
+                                                },
+                                            },
+                                        },
+                                    },
+                                }
+                            }
+                        },
+                    },
+                }
+            }
+        },
+    }
+
+    # Planted violations (7):
+    # 1  due_date before invoice_date
+    # 2  line_items[0].line_total arithmetic wrong  (80 ≠ 3 × 25)
+    # 3  billing.subtotal wrong                     (200 ≠ 80+49.99+60 = 189.99)
+    # 4  billing.tax_amount wrong                   (14.40 ≠ 200 × 0.08 = 16.00)
+    # 5  billing.item_count wrong                   (4 ≠ 3)
+    # 6  billing.discount_amount > 0 for trial      (25 ≠ 0)
+    # 7  billing.total inconsistent                 (195 ≠ 200+14.40-25 = 189.40)
+    payload: Dict[str, Any] = {
+        "invoice_date": "2024-03-15",
+        "due_date": "2024-03-10",        # VIOLATION 1 — before invoice_date
+        "customer": {
+            "id": 1042,
+            "name": "Acme Corp",
+            "account_type": "trial",     # triggers VIOLATION 6
+        },
+        "line_items": [
+            {
+                "description": "Cloud Storage 100 GB/mo",
+                "quantity": 3,
+                "unit_price": 25.00,
+                "line_total": 80.00,     # VIOLATION 2 — should be 3 × 25.00 = 75.00
+            },
+            {
+                "description": "API Calls 1M/mo",
+                "quantity": 1,
+                "unit_price": 49.99,
+                "line_total": 49.99,     # valid
+            },
+            {
+                "description": "Support Package",
+                "quantity": 2,
+                "unit_price": 30.00,
+                "line_total": 60.00,     # valid
+            },
+        ],
+        "billing": {
+            "subtotal": 200.00,          # VIOLATION 3 — sum of line_totals = 189.99
+            "tax_rate": 0.08,
+            "tax_amount": 14.40,         # VIOLATION 4 — should be 200.00 × 0.08 = 16.00
+            "discount_amount": 25.00,   # VIOLATION 6 — trial account; must be 0
+            "total": 195.00,             # VIOLATION 7 — should be 200+14.40-25 = 189.40
+            "item_count": 4,             # VIOLATION 5 — 3 line_items, not 4
+            "currency": "USD",
+        },
+    }
+
+    violations = [
+        PlantedViolation(
+            field_path="due_date",
+            violation_type="cross_field_constraint",
+            description=(
+                "due_date '2024-03-10' is before invoice_date '2024-03-15'; "
+                "due_date must be strictly after invoice_date."
+            ),
+            expected_value="date after 2024-03-15",
+            actual_value="2024-03-10",
+        ),
+        PlantedViolation(
+            field_path="line_items[0].line_total",
+            violation_type="cross_field_constraint",
+            description=(
+                "line_items[0].line_total is 80.00 but "
+                "quantity(3) × unit_price(25.00) = 75.00."
+            ),
+            expected_value="75.00",
+            actual_value="80.00",
+        ),
+        PlantedViolation(
+            field_path="billing.subtotal",
+            violation_type="cross_field_constraint",
+            description=(
+                "billing.subtotal is 200.00 but the sum of line_totals "
+                "(80.00 + 49.99 + 60.00) = 189.99."
+            ),
+            expected_value="189.99",
+            actual_value="200.00",
+        ),
+        PlantedViolation(
+            field_path="billing.tax_amount",
+            violation_type="cross_field_constraint",
+            description=(
+                "billing.tax_amount is 14.40 but "
+                "billing.subtotal(200.00) × tax_rate(0.08) = 16.00."
+            ),
+            expected_value="16.00",
+            actual_value="14.40",
+        ),
+        PlantedViolation(
+            field_path="billing.item_count",
+            violation_type="cross_field_constraint",
+            description=(
+                "billing.item_count is 4 but there are 3 elements in line_items."
+            ),
+            expected_value="3",
+            actual_value="4",
+        ),
+        PlantedViolation(
+            field_path="billing.discount_amount",
+            violation_type="cross_field_constraint",
+            description=(
+                "billing.discount_amount is 25.00 but customer.account_type "
+                "is 'trial'; trial accounts must have discount_amount = 0."
+            ),
+            expected_value="0",
+            actual_value="25.00",
+        ),
+        PlantedViolation(
+            field_path="billing.total",
+            violation_type="cross_field_constraint",
+            description=(
+                "billing.total is 195.00 but "
+                "subtotal(200.00) + tax_amount(14.40) - discount_amount(25.00) = 189.40."
+            ),
+            expected_value="189.40",
+            actual_value="195.00",
+        ),
+    ]
+
+    return TaskScenario(
+        task_name="validate_cross_field_constraints",
+        task_description=(
+            "You are given an API spec for POST /invoices and a request payload. "
+            "The spec defines cross-field constraints that cannot be checked by "
+            "standard JSON Schema validation. You must actively compute and "
+            "cross-reference values to find violations. "
+            "Constraints to check: "
+            "(1) due_date must be strictly after invoice_date. "
+            "(2) Each line_items[N].line_total must equal quantity × unit_price. "
+            "(3) billing.subtotal must equal the sum of all line_items[N].line_total. "
+            "(4) billing.tax_amount must equal billing.subtotal × billing.tax_rate. "
+            "(5) billing.total must equal billing.subtotal + billing.tax_amount - billing.discount_amount. "
+            "(6) billing.item_count must equal the number of elements in line_items. "
+            "(7) If customer.account_type is 'trial', billing.discount_amount must be 0. "
+            "Use violation_type='cross_field_constraint' for these. "
+            "Report one violation per step. Submit field_path='DONE' when finished."
+        ),
+        api_spec=api_spec,
+        payload=payload,
+        violations=violations,
+        max_steps=18,
+    )
+
+
+# ── Registry ──────────────────────────────────────────────────────────────
+
+TASK_GENERATORS = {
+    "find_type_mismatches": generate_easy_scenario,
+    "validate_nested_objects": generate_medium_scenario,
+    "detect_breaking_changes": generate_hard_scenario,
+    "validate_response_schema": generate_format_validation_scenario,
+    "validate_cross_field_constraints": generate_cross_field_scenario,
+}
+
+AVAILABLE_TASKS = list(TASK_GENERATORS.keys())
+
+
+def generate_scenario_for_task(
+    task_name: str, seed: Optional[int] = None
+) -> TaskScenario:
+    """Return a ``TaskScenario`` for the requested task.
+
+    Parameters
+    ----------
+    task_name:
+        One of the keys in ``AVAILABLE_TASKS``.
+    seed:
+        Optional integer seed for deterministic randomisation.
+        seed=None → canonical fixed scenario (backward-compatible).
+        seed=int  → reproducible randomised variant.
+
+    Raises
+    ------
+    ValueError
+        If *task_name* is not recognised.
+    """
+    generator = TASK_GENERATORS.get(task_name)
+    if generator is None:
+        raise ValueError(
+            f"Unknown task '{task_name}'. Available: {AVAILABLE_TASKS}"
+        )
+    return generator(seed=seed)

tests/test_environment.py

@@ -0,0 +1,191 @@
+"""
+Tests for the API Contract Validator Environment.
+
+Run from the api_contract_validator/ directory:
+    pytest tests/ -v
+"""
+
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import pytest
+from server.environment import ValidatorEnvironment
+from server.spec_generator import generate_scenario_for_task, AVAILABLE_TASKS
+from models import ValidatorAction
+
+
+@pytest.fixture
+def env():
+    """Fresh environment for each test."""
+    return ValidatorEnvironment()
+
+
+# ── Task structure ─────────────────────────────────────────────────────────
+
+
+def test_five_tasks_registered():
+    assert len(AVAILABLE_TASKS) == 5
+    expected = {
+        "find_type_mismatches",
+        "validate_nested_objects",
+        "detect_breaking_changes",
+        "validate_response_schema",
+        "validate_cross_field_constraints",
+    }
+    assert set(AVAILABLE_TASKS) == expected
+
+
+def test_all_tasks_have_violations():
+    for task_name in AVAILABLE_TASKS:
+        scenario = generate_scenario_for_task(task_name)
+        assert len(scenario.violations) >= 4, (
+            f"{task_name} has only {len(scenario.violations)} violations"
+        )
+        assert scenario.max_steps >= len(scenario.violations), (
+            f"{task_name}: max_steps({scenario.max_steps}) < violations({len(scenario.violations)})"
+        )
+
+
+# ── Reset behaviour ────────────────────────────────────────────────────────
+
+
+def test_all_tasks_reset_cleanly(env):
+    for task_name in AVAILABLE_TASKS:
+        obs = env.reset(task_name=task_name)
+        assert obs.task_name == task_name
+        assert obs.done is False
+        assert obs.reward == 0.0
+        assert obs.violations_found == []
+        assert obs.violations_remaining > 0
+
+
+# ── Correct violation reward ───────────────────────────────────────────────
+
+
+def test_correct_violation_gives_plus_one(env):
+    scenario = generate_scenario_for_task("find_type_mismatches")
+    env.reset(task_name="find_type_mismatches")
+
+    first = scenario.violations[0]
+    action = ValidatorAction(
+        field_path=first.field_path,
+        violation_type=first.violation_type,
+        description="test",
+    )
+    result = env.step(action)
+    assert result.reward == 1.0
+    assert len(result.violations_found) == 1
+
+
+# ── False positive penalty ─────────────────────────────────────────────────
+
+
+def test_false_positive_gives_negative_reward(env):
+    env.reset(task_name="find_type_mismatches")
+    action = ValidatorAction(
+        field_path="nonexistent_field_xyz_abc",
+        violation_type="type_mismatch",
+        description="fabricated",
+    )
+    result = env.step(action)
+    assert result.reward == pytest.approx(-0.3)
+
+
+# ── Duplicate penalty ──────────────────────────────────────────────────────
+
+
+def test_duplicate_gives_small_penalty(env):
+    scenario = generate_scenario_for_task("find_type_mismatches")
+    env.reset(task_name="find_type_mismatches")
+
+    first = scenario.violations[0]
+    action = ValidatorAction(
+        field_path=first.field_path,
+        violation_type=first.violation_type,
+        description="test",
+    )
+    result1 = env.step(action)
+    assert result1.reward == 1.0
+
+    result2 = env.step(action)  # duplicate
+    assert result2.reward == pytest.approx(-0.1)
+
+
+# ── DONE signal ────────────────────────────────────────────────────────────
+
+
+def test_done_signal_ends_episode(env):
+    env.reset(task_name="find_type_mismatches")
+    action = ValidatorAction(field_path="DONE", violation_type="", description="")
+    result = env.step(action)
+    assert result.done is True
+    assert result.reward >= 0.0
+
+
+# ── HINT mechanic ──────────────────────────────────────────────────────────
+
+
+def test_hint_costs_half_point(env):
+    env.reset(task_name="find_type_mismatches")
+    action = ValidatorAction(field_path="HINT", violation_type="", description="")
+    result = env.step(action)
+    assert result.reward == pytest.approx(-0.5)
+    assert "Hint:" in result.feedback
+    assert result.done is False
+
+
+# ── Proximity reward ────────────────────────────────────���──────────────────
+
+
+def test_proximity_reward_for_correct_path_wrong_type(env):
+    scenario = generate_scenario_for_task("find_type_mismatches")
+    env.reset(task_name="find_type_mismatches")
+
+    first = scenario.violations[0]
+    action = ValidatorAction(
+        field_path=first.field_path,
+        violation_type="extra_field",  # wrong type on purpose
+        description="proximity test",
+    )
+    result = env.step(action)
+    assert result.reward == pytest.approx(0.3)
+
+
+# ── Seed reproducibility ───────────────────────────────────────────────────
+
+
+def test_seed_gives_same_scenario():
+    for task_name in AVAILABLE_TASKS:
+        s1 = generate_scenario_for_task(task_name, seed=42)
+        s2 = generate_scenario_for_task(task_name, seed=42)
+        assert [v.field_path for v in s1.violations] == [
+            v.field_path for v in s2.violations
+        ], f"{task_name}: seed=42 gave different results across calls"
+
+
+def test_different_seeds_give_different_easy_scenarios():
+    """Easy task pool should vary with different seeds."""
+    paths_by_seed = set()
+    for seed in range(8):
+        s = generate_scenario_for_task("find_type_mismatches", seed=seed)
+        key = tuple(sorted(v.field_path for v in s.violations))
+        paths_by_seed.add(key)
+    assert len(paths_by_seed) > 1, "Different seeds produced identical scenarios"
+
+
+# ── Cross-field task ───────────────────────────────────────────────────────
+
+
+def test_cross_field_task_has_seven_violations():
+    scenario = generate_scenario_for_task("validate_cross_field_constraints")
+    assert len(scenario.violations) == 7
+
+
+def test_cross_field_violations_use_correct_type():
+    scenario = generate_scenario_for_task("validate_cross_field_constraints")
+    for v in scenario.violations:
+        assert v.violation_type == "cross_field_constraint", (
+            f"Expected cross_field_constraint, got {v.violation_type} for {v.field_path}"
+        )