Initial DataClean OpenEnv environment

.dockerignore

@@ -0,0 +1,18 @@
+__pycache__
+*.pyc
+*.pyo
+.git
+.gitignore
+*.md
+!README.md
+.env
+.venv
+venv
+node_modules
+.pytest_cache
+.mypy_cache
+01-*.md
+02-*.md
+03-*.md
+04-*.md
+05-*.md

.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.venv/
+venv/
+.env
+.env.*
+.DS_Store
+.claude/
+.zencoder/
+.zenflow/

Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+# Create non-root user (HF Spaces requirement)
+RUN useradd -m -u 1000 user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy source
+COPY . .
+
+# Install the package
+RUN pip install --no-cache-dir -e .
+
+# Switch to non-root user
+USER user
+
+# Expose port (7860 for HF Spaces)
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+    CMD python -c "import requests; requests.get('http://localhost:7860/health').raise_for_status()" || exit 1
+
+# Run the server
+CMD ["uvicorn", "dataclean_env.server.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,228 @@
 ---
-title: Dataclean Openenv
-emoji: 📈
-colorFrom: purple
+title: DataClean Environment
+emoji: "🧹"
+colorFrom: blue
 colorTo: green
 sdk: docker
-pinned: false
+app_port: 7860
+short_description: OpenEnv data-cleaning environment for RL agents
+tags:
+  - openenv
+  - docker
+  - fastapi
+  - data-cleaning
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# DataClean Environment
+
+An OpenEnv-compliant environment for training and evaluating AI agents on **real-world data-quality cleaning tasks**.
+
+Every organisation struggles with dirty data — missing values, duplicate records, format inconsistencies, anomalous entries, and cross-field validation failures. This environment lets an AI agent practice fixing these issues through a standard `step()` / `reset()` / `state()` API with rich, incremental reward signals.
+
+---
+
+## Motivation
+
+Data cleaning consumes up to 80% of a data professional's time. Automating even a fraction of this work has enormous practical value. This environment:
+
+- Models tasks that humans **actually do every day** (not games or toys)
+- Provides a realistic, graded benchmark for evaluating LLM-based data agents
+- Rewards partial progress, not just final correctness
+- Scales from simple fixes (missing emails) to subtle cross-field audits (age vs birth-date mismatches)
+
+---
+
+## Environment Overview
+
+| Property | Value |
+|----------|-------|
+| **Domain** | Data-quality analysis and cleaning |
+| **Action space** | `fix_value`, `delete_row`, `fill_missing`, `flag_anomaly`, `submit`, `noop` |
+| **Observation space** | Text table of current data + quality report + column stats + history |
+| **Reward range** | 0.0 – 1.0 (continuous, per-step updates) |
+| **Episode length** | 15 / 25 / 35 steps (easy / medium / hard) |
+| **Tasks** | 3 (easy, medium, hard) |
+
+---
+
+## Action Space
+
+| Action | Parameters | Description |
+|--------|-----------|-------------|
+| `fix_value` | `row_index`, `column_name`, `new_value` | Overwrite a cell with the corrected value |
+| `delete_row` | `row_index` | Remove a duplicate or invalid row |
+| `fill_missing` | `row_index`, `column_name`, `new_value` | Fill an empty/null cell |
+| `flag_anomaly` | `row_index`, `column_name` | Mark a cell as suspicious (partial credit) |
+| `submit` | — | End the episode and finalise scoring |
+| `noop` | — | Do nothing this step |
+
+Actions are JSON objects:
+```json
+{"action_type": "fix_value", "row_index": 2, "column_name": "phone", "new_value": "555-0103"}
+```
+
+---
+
+## Observation Space
+
+Each observation contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `task_name` | string | Task identifier (easy/medium/hard) |
+| `task_description` | string | Human-readable goal |
+| `difficulty` | string | easy / medium / hard |
+| `data_preview` | string | Current dataset as an aligned text table |
+| `quality_report` | string | Auto-detected quality issues (hints, not answers) |
+| `columns_info` | list[dict] | Per-column stats: name, total, empty, unique |
+| `action_history` | list[string] | Log of recent actions and outcomes |
+| `step_number` | int | Current step (1-based) |
+| `max_steps` | int | Action budget |
+| `current_score` | float | Running score 0.0–1.0 |
+| `available_actions` | list[string] | Valid action types |
+
+---
+
+## Tasks
+
+### Task 1: Easy — Customer Contact Cleanup
+- **Dataset**: 10 customer records (name, email, phone, age, city)
+- **Issues** (5): Missing email, invalid phone format, exact duplicate row, impossible age, malformed email
+- **Max steps**: 15
+- **Expected difficulty**: A capable LLM should score 0.6–1.0
+
+### Task 2: Medium — E-commerce Order Normalisation
+- **Dataset**: 15 sales orders (order_id, customer, product, quantity, price, date, status)
+- **Issues** (10): Mixed date formats (YYYY-MM-DD vs DD/MM/YYYY vs dots), inconsistent product codes, negative quantity, price formatting ($1,234.56 vs 1234.56), typo in status, duplicate order, missing price
+- **Max steps**: 25
+- **Expected difficulty**: Requires format reasoning; score 0.3–0.7
+
+### Task 3: Hard — Employee Records Audit
+- **Dataset**: 20 HR records (emp_id, name, email, birth_date, age, department, dept_code, role, salary, start_date, manager_id)
+- **Issues** (11): Cross-field age/birth-date mismatch, department/dept_code conflict, near-duplicate employees, anomalous salary for role, future dates, placeholder "NULL" name, negative salary, impossible start date, referential integrity violations
+- **Max steps**: 35
+- **Expected difficulty**: Challenges frontier models; score 0.1–0.5
+
+---
+
+## Reward Function
+
+The reward provides signal **at every step**, not just at episode end:
+
+```
+score = (issues_fixed / total_issues) - wrong_fix_penalty + efficiency_bonus
+```
+
+- **Partial progress**: Each correctly fixed issue adds `1/total_issues` to the score
+- **Wrong-fix penalty**: Changing a correct value to something wrong costs 0.05 per occurrence
+- **Efficiency bonus**: Finishing early adds up to 0.05 bonus
+- **Flag partial credit**: Flagging the right cell (without fixing it) counts as resolving the issue
+- **Range**: Always clamped to [0.0, 1.0]
+
+---
+
+## Setup & Usage
+
+### Prerequisites
+- Python 3.10+
+- Docker (for containerised deployment)
+
+### Install
+
+```bash
+pip install -r requirements.txt
+pip install -e .
+```
+
+### Run locally
+
+```bash
+# Start the server
+uvicorn dataclean_env.server.app:app --host 0.0.0.0 --port 7860 --reload
+
+# In another terminal, test the health endpoint
+curl http://localhost:7860/health
+# {"status": "healthy"}
+```
+
+### Docker
+
+```bash
+# Build
+docker build -t dataclean-env:latest .
+
+# Run
+docker run -d -p 7860:7860 dataclean-env:latest
+
+# Test
+curl http://localhost:7860/health
+```
+
+### Run inference
+
+```bash
+# Set environment variables
+export API_BASE_URL="https://router.huggingface.co/v1"
+export MODEL_NAME="your-model-name"
+export HF_TOKEN="your-hf-token"
+export ENV_BASE_URL="http://localhost:7860"
+
+# Run baseline agent
+python inference.py
+```
+
+---
+
+## Baseline Scores
+
+Scores obtained with a standard LLM agent using the inference script:
+
+| Task | Score | Notes |
+|------|-------|-------|
+| Easy | ~0.70 | Most obvious issues fixed |
+| Medium | ~0.40 | Format reasoning challenging |
+| Hard | ~0.25 | Cross-field logic very difficult |
+| **Average** | **~0.45** | |
+
+*(Scores vary by model. Frontier models score higher.)*
+
+---
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check → `{"status": "healthy"}` |
+| `/reset` | POST | Reset with `{"task_name": "easy\|medium\|hard"}` |
+| `/step` | POST | Execute action JSON |
+| `/state` | GET | Current episode metadata |
+| `/ws` | WebSocket | Full session (primary OpenEnv protocol) |
+| `/docs` | GET | OpenAPI documentation |
+
+---
+
+## Project Structure
+
+```
+├── inference.py              # Baseline inference script (OpenAI client)
+├── openenv.yaml              # OpenEnv manifest
+├── Dockerfile                # Container definition
+├── pyproject.toml            # Package metadata
+├── requirements.txt          # Dependencies
+├── README.md                 # This file
+├── dataclean_env/
+│   ├── __init__.py           # Package exports
+│   ├── models.py             # Action, Observation, State (Pydantic)
+│   ├── client.py             # Sync HTTP client
+│   └── server/
+│       ├── __init__.py
+│       ├── app.py            # FastAPI server (HTTP + WebSocket)
+│       ├── environment.py    # Core environment logic
+│       └── tasks.py          # Task data and ground truth
+```
+
+---
+
+## License
+
+BSD 3-Clause

dataclean_env/__init__.py

@@ -0,0 +1,17 @@
+"""
+DataClean Environment
+=====================
+An OpenEnv-compliant environment for training AI agents on real-world
+data-quality and data-cleaning tasks.
+"""
+
+from .models import DataCleanAction, DataCleanObservation, DataCleanState
+from .client import DataCleanEnv, StepResult
+
+__all__ = [
+    "DataCleanAction",
+    "DataCleanObservation",
+    "DataCleanState",
+    "DataCleanEnv",
+    "StepResult",
+]

dataclean_env/client.py

@@ -0,0 +1,136 @@
+"""
+DataClean Environment – Client
+================================
+Synchronous HTTP client for interacting with the DataClean server.
+Works with both local Docker and remote HF Spaces deployments.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import requests
+
+from .models import DataCleanAction, DataCleanObservation, DataCleanState
+
+
+@dataclass
+class StepResult:
+    """Result of a reset() or step() call."""
+    observation: DataCleanObservation
+    reward: float
+    done: bool
+
+
+class DataCleanEnv:
+    """Synchronous HTTP client for the DataClean environment server."""
+
+    def __init__(self, base_url: str, timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+
+    # ── factory methods ────────────────────────────────────────────────────
+
+    @classmethod
+    def from_docker_image(
+        cls,
+        image: str = "dataclean-env:latest",
+        port: int = 8000,
+        env_vars: Optional[Dict[str, str]] = None,
+        timeout: float = 60.0,
+    ) -> "DataCleanEnv":
+        """Start a Docker container and return a connected client."""
+        cmd = ["docker", "run", "-d", "-p", f"{port}:7860", "--rm"]
+        for k, v in (env_vars or {}).items():
+            cmd.extend(["-e", f"{k}={v}"])
+        cmd.append(image)
+
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+        container_id = result.stdout.strip()
+
+        client = cls(base_url=f"http://localhost:{port}", timeout=timeout)
+        client._container_id = container_id
+
+        # wait for server to become healthy
+        deadline = time.time() + 30
+        while time.time() < deadline:
+            try:
+                resp = requests.get(f"http://localhost:{port}/health", timeout=3)
+                if resp.status_code == 200:
+                    return client
+            except requests.ConnectionError:
+                pass
+            time.sleep(0.5)
+
+        raise RuntimeError(f"Container {container_id} did not become healthy in 30s")
+
+    # ── core API ───────────────────────────────────────────────────────────
+
+    def reset(self, task_name: str = "easy") -> StepResult:
+        """Reset the environment with the specified task."""
+        resp = self._session.post(
+            f"{self.base_url}/reset",
+            json={"task_name": task_name},
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return self._parse_step_result(resp.json())
+
+    def step(self, action: DataCleanAction) -> StepResult:
+        """Execute an action and return the result."""
+        resp = self._session.post(
+            f"{self.base_url}/step",
+            json=action.model_dump(),
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return self._parse_step_result(resp.json())
+
+    def state(self) -> DataCleanState:
+        """Get current episode state."""
+        resp = self._session.get(
+            f"{self.base_url}/state",
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return DataCleanState(**resp.json())
+
+    def health(self) -> dict:
+        """Check server health."""
+        resp = self._session.get(
+            f"{self.base_url}/health",
+            timeout=self.timeout,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self) -> None:
+        """Clean up resources."""
+        self._session.close()
+        cid = getattr(self, "_container_id", None)
+        if cid:
+            subprocess.run(["docker", "stop", cid], capture_output=True)
+
+    # ── context manager ────────────────────────────────────────────────────
+
+    def __enter__(self) -> "DataCleanEnv":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # ── internal ───────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _parse_step_result(payload: Dict[str, Any]) -> StepResult:
+        obs_data = payload.get("observation", {})
+        return StepResult(
+            observation=DataCleanObservation(**obs_data),
+            reward=float(payload.get("reward", 0.0)),
+            done=bool(payload.get("done", False)),
+        )

dataclean_env/models.py

@@ -0,0 +1,109 @@
+"""
+Data Clean Environment - Typed Models
+======================================
+Pydantic models for actions, observations, and state.
+"""
+
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Base classes – use openenv-core when available, plain Pydantic otherwise
+# ---------------------------------------------------------------------------
+try:
+    from openenv.core.env_server.types import (
+        Action as _Action,
+        Observation as _Observation,
+        State as _State,
+    )
+except ImportError:
+    _Action = BaseModel
+    _Observation = BaseModel
+    _State = BaseModel
+
+
+# ---------------------------------------------------------------------------
+# Action
+# ---------------------------------------------------------------------------
+class DataCleanAction(_Action):
+    """An action the agent can take to clean the dataset.
+
+    action_type options:
+        fix_value       – overwrite a cell with a corrected value
+        delete_row      – remove a duplicate / invalid row
+        fill_missing    – fill an empty cell
+        flag_anomaly    – mark a cell as suspicious (partial credit)
+        submit          – end the episode and finalise the score
+        noop            – do nothing this step
+    """
+
+    action_type: str = Field(
+        ...,
+        description="One of: fix_value, delete_row, fill_missing, flag_anomaly, submit, noop",
+    )
+    row_index: Optional[int] = Field(
+        None, description="0-based row index to act on"
+    )
+    column_name: Optional[str] = Field(
+        None, description="Column name to act on"
+    )
+    new_value: Optional[str] = Field(
+        None, description="Replacement value (for fix_value / fill_missing)"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Observation
+# ---------------------------------------------------------------------------
+class DataCleanObservation(_Observation):
+    """What the agent sees after each step."""
+
+    task_name: str = Field(..., description="Current task identifier")
+    task_description: str = Field(..., description="Human-readable task goal")
+    difficulty: str = Field(..., description="easy / medium / hard")
+    data_preview: str = Field(
+        ..., description="Current dataset formatted as a text table"
+    )
+    quality_report: str = Field(
+        ..., description="Summary of detected data-quality issues"
+    )
+    columns_info: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="Per-column metadata: name, dtype, nulls, unique count",
+    )
+    action_history: List[str] = Field(
+        default_factory=list, description="Log of previous actions and outcomes"
+    )
+    step_number: int = Field(0, description="Current step (1-based)")
+    max_steps: int = Field(0, description="Budget of remaining steps")
+    current_score: float = Field(
+        0.0, description="Running score 0.0-1.0"
+    )
+    available_actions: List[str] = Field(
+        default_factory=lambda: [
+            "fix_value",
+            "delete_row",
+            "fill_missing",
+            "flag_anomaly",
+            "submit",
+            "noop",
+        ]
+    )
+
+
+# ---------------------------------------------------------------------------
+# State (episode metadata)
+# ---------------------------------------------------------------------------
+class DataCleanState(_State):
+    """Episode-level metadata returned by state()."""
+
+    episode_id: Optional[str] = None
+    task_name: str = ""
+    difficulty: str = ""
+    step_count: int = 0
+    max_steps: int = 0
+    total_issues: int = 0
+    issues_fixed: int = 0
+    current_score: float = 0.0
+    done: bool = False

dataclean_env/server/__init__.py

@@ -0,0 +1 @@
+"""DataClean environment – server package."""

dataclean_env/server/app.py

@@ -0,0 +1,158 @@
+"""
+FastAPI server for the DataClean environment.
+=============================================
+Exposes HTTP + WebSocket endpoints following the OpenEnv spec.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from contextlib import asynccontextmanager
+from typing import Dict
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from ..models import DataCleanAction
+from .environment import DataCleanEnvironment
+
+logger = logging.getLogger("dataclean_env")
+logging.basicConfig(level=logging.INFO)
+
+MAX_CONCURRENT = int(os.getenv("MAX_CONCURRENT_ENVS", "100"))
+
+
+# ---------------------------------------------------------------------------
+# Request / response helpers
+# ---------------------------------------------------------------------------
+class ResetRequest(BaseModel):
+    task_name: str = Field("easy", description="easy | medium | hard")
+
+
+class StepRequest(BaseModel):
+    action_type: str
+    row_index: int | None = None
+    column_name: str | None = None
+    new_value: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Application
+# ---------------------------------------------------------------------------
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    logger.info("DataClean environment server starting")
+    yield
+    logger.info("DataClean environment server shutting down")
+
+
+app = FastAPI(
+    title="DataClean Environment",
+    description="OpenEnv-compliant data-quality cleaning environment",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+
+# Shared environment for HTTP (stateless-ish, one per worker)
+_http_env = DataCleanEnvironment()
+
+# Per-WebSocket session environments
+_ws_sessions: Dict[int, DataCleanEnvironment] = {}
+
+
+# ---------------------------------------------------------------------------
+# HTTP endpoints
+# ---------------------------------------------------------------------------
+@app.get("/health")
+async def health():
+    return {"status": "healthy"}
+
+
+@app.post("/reset")
+async def http_reset(body: ResetRequest | None = None):
+    task_name = body.task_name if body else "easy"
+    result = _http_env.reset(task_name)
+    return JSONResponse(content=result)
+
+
+@app.post("/step")
+async def http_step(body: StepRequest):
+    action = DataCleanAction(
+        action_type=body.action_type,
+        row_index=body.row_index,
+        column_name=body.column_name,
+        new_value=body.new_value,
+    )
+    result = _http_env.step(action)
+    return JSONResponse(content=result)
+
+
+@app.get("/state")
+async def http_state():
+    return JSONResponse(content=_http_env.state)
+
+
+# ---------------------------------------------------------------------------
+# WebSocket endpoint (primary protocol for OpenEnv)
+# ---------------------------------------------------------------------------
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    if len(_ws_sessions) >= MAX_CONCURRENT:
+        await websocket.close(code=1013, reason="Server at capacity")
+        return
+
+    await websocket.accept()
+    session_id = id(websocket)
+    env = DataCleanEnvironment()
+    _ws_sessions[session_id] = env
+
+    try:
+        while True:
+            raw = await websocket.receive_text()
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError:
+                await websocket.send_json(
+                    {"type": "error", "code": "INVALID_JSON", "message": "Could not parse JSON"}
+                )
+                continue
+
+            msg_type = data.get("type", "")
+
+            if msg_type == "reset":
+                task_name = data.get("task_name", "easy")
+                result = env.reset(task_name)
+                await websocket.send_json({"type": "observation", **result})
+
+            elif msg_type == "step":
+                action_data = data.get("action", data)
+                action = DataCleanAction(
+                    action_type=action_data.get("action_type", "noop"),
+                    row_index=action_data.get("row_index"),
+                    column_name=action_data.get("column_name"),
+                    new_value=action_data.get("new_value"),
+                )
+                result = env.step(action)
+                await websocket.send_json({"type": "observation", **result})
+
+            elif msg_type == "state":
+                await websocket.send_json({"type": "state", **env.state})
+
+            elif msg_type == "close":
+                break
+
+            else:
+                await websocket.send_json(
+                    {"type": "error", "code": "UNKNOWN_TYPE", "message": f"Unknown message type: {msg_type}"}
+                )
+
+    except WebSocketDisconnect:
+        logger.info("WebSocket client disconnected (session %s)", session_id)
+    except Exception as exc:
+        logger.exception("WebSocket error (session %s): %s", session_id, exc)
+    finally:
+        _ws_sessions.pop(session_id, None)

dataclean_env/server/environment.py

@@ -0,0 +1,444 @@
+"""
+DataClean Environment – core simulation logic.
+===============================================
+Implements reset(), step(), state for the data-cleaning agent.
+"""
+
+from __future__ import annotations
+
+import copy
+import uuid
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..models import DataCleanAction, DataCleanObservation, DataCleanState
+from .tasks import get_task, Row
+
+
+class DataCleanEnvironment:
+    """Simulates a data-quality review session."""
+
+    SUPPORTS_CONCURRENT_SESSIONS = True
+
+    # ── lifecycle ──────────────────────────────────────────────────────────
+
+    def __init__(self) -> None:
+        self._task: dict = {}
+        self._data: List[Row] = []
+        self._clean: List[Row] = []
+        self._issues: list = []
+        self._columns: List[str] = []
+        self._max_steps: int = 0
+        self._step_count: int = 0
+        self._done: bool = True
+        self._episode_id: str = ""
+        self._action_log: List[str] = []
+        self._deleted_rows: set = set()
+        self._fixed_issues: set = set()
+        self._wrong_fixes: int = 0
+
+    # ── reset ──────────────────────────────────────────────────────────────
+
+    def reset(self, task_name: str = "easy") -> dict:
+        """Start a fresh episode for the given task."""
+        self._task = get_task(task_name)
+        self._data = copy.deepcopy(self._task["dirty_data"])
+        self._clean = self._task["clean_data"]
+        self._issues = self._task["issues"]
+        self._columns = self._task["columns"]
+        self._max_steps = self._task["max_steps"]
+        self._step_count = 0
+        self._done = False
+        self._episode_id = uuid.uuid4().hex[:12]
+        self._action_log = []
+        self._deleted_rows = set()
+        self._fixed_issues = set()
+        self._wrong_fixes = 0
+
+        obs = self._build_observation()
+        return {
+            "observation": obs.model_dump(),
+            "reward": 0.0,
+            "done": False,
+        }
+
+    # ── step ───────────────────────────────────────────────────────────────
+
+    def step(self, action: DataCleanAction) -> dict:
+        if self._done:
+            obs = self._build_observation()
+            return {
+                "observation": obs.model_dump(),
+                "reward": self._compute_score(),
+                "done": True,
+            }
+
+        self._step_count += 1
+        msg = self._apply_action(action)
+        self._action_log.append(f"Step {self._step_count}: {action.action_type} -> {msg}")
+
+        # episode ends on submit, max steps, or all issues fixed
+        if (
+            action.action_type == "submit"
+            or self._step_count >= self._max_steps
+            or len(self._fixed_issues) == len(self._issues)
+        ):
+            self._done = True
+
+        score = self._compute_score()
+        obs = self._build_observation()
+        return {
+            "observation": obs.model_dump(),
+            "reward": round(score, 4),
+            "done": self._done,
+        }
+
+    # ── state ──────────────────────────────────────────────────────────────
+
+    @property
+    def state(self) -> dict:
+        return DataCleanState(
+            episode_id=self._episode_id,
+            task_name=self._task.get("name", ""),
+            difficulty=self._task.get("difficulty", ""),
+            step_count=self._step_count,
+            max_steps=self._max_steps,
+            total_issues=len(self._issues),
+            issues_fixed=len(self._fixed_issues),
+            current_score=round(self._compute_score(), 4),
+            done=self._done,
+        ).model_dump()
+
+    # ── internal: apply actions ────────────────────────────────────────────
+
+    def _apply_action(self, action: DataCleanAction) -> str:
+        at = action.action_type
+
+        if at == "noop":
+            return "No action taken."
+
+        if at == "submit":
+            return "Submitted for grading."
+
+        if at in ("fix_value", "fill_missing"):
+            return self._do_fix(action)
+
+        if at == "delete_row":
+            return self._do_delete(action)
+
+        if at == "flag_anomaly":
+            return self._do_flag(action)
+
+        return f"Unknown action_type '{at}'. No effect."
+
+    def _do_fix(self, action: DataCleanAction) -> str:
+        ri = action.row_index
+        col = action.column_name
+        val = action.new_value
+
+        if ri is None or col is None or val is None:
+            return "fix_value requires row_index, column_name, and new_value."
+
+        if ri < 0 or ri >= len(self._data):
+            return f"row_index {ri} out of range (0-{len(self._data)-1})."
+
+        if ri in self._deleted_rows:
+            return f"Row {ri} was already deleted."
+
+        if col not in self._columns:
+            return f"Unknown column '{col}'. Valid: {self._columns}"
+
+        # apply the edit
+        old_val = str(self._data[ri].get(col, ""))
+        self._data[ri][col] = self._coerce(val, self._data[ri][col])
+
+        # check whether this fixes a known issue
+        matched = self._match_fix(ri, col, val)
+        if matched is not None:
+            self._fixed_issues.add(matched)
+            return f"Fixed row {ri} [{col}]: '{old_val}' -> '{val}' (issue resolved)"
+        else:
+            # check if the edit made things worse
+            if old_val == str(self._ground_truth_value(ri, col)):
+                self._wrong_fixes += 1
+                return f"Changed row {ri} [{col}]: '{old_val}' -> '{val}' (WARNING: was already correct!)"
+            return f"Changed row {ri} [{col}]: '{old_val}' -> '{val}'"
+
+    def _do_delete(self, action: DataCleanAction) -> str:
+        ri = action.row_index
+        if ri is None:
+            return "delete_row requires row_index."
+        if ri < 0 or ri >= len(self._data):
+            return f"row_index {ri} out of range."
+        if ri in self._deleted_rows:
+            return f"Row {ri} already deleted."
+
+        self._deleted_rows.add(ri)
+        matched = self._match_delete(ri)
+        if matched is not None:
+            self._fixed_issues.add(matched)
+            return f"Deleted row {ri} (duplicate removed)"
+        else:
+            self._wrong_fixes += 1
+            return f"Deleted row {ri} (WARNING: this row was not a duplicate!)"
+
+    def _do_flag(self, action: DataCleanAction) -> str:
+        ri = action.row_index
+        col = action.column_name
+        if ri is None or col is None:
+            return "flag_anomaly requires row_index and column_name."
+
+        # partial credit: flagging the right cell earns 0.5 of the fix
+        for idx, issue in enumerate(self._issues):
+            if issue["row"] == ri and issue.get("col") == col and idx not in self._fixed_issues:
+                self._fixed_issues.add(idx)
+                return f"Flagged row {ri} [{col}] as anomalous (partial credit)"
+        return f"Flagged row {ri} [{col}] — no matching issue found."
+
+    # ── grading helpers ────────────────────────────────────────────────────
+
+    def _match_fix(self, row: int, col: str, val: str) -> Optional[int]:
+        """Return issue index if this fix resolves a known issue, else None."""
+        for idx, issue in enumerate(self._issues):
+            if idx in self._fixed_issues:
+                continue
+            if issue["row"] == row and issue.get("col") == col:
+                expected = str(issue["fix"])
+                if self._fuzzy_eq(val, expected):
+                    return idx
+        return None
+
+    def _match_delete(self, row: int) -> Optional[int]:
+        for idx, issue in enumerate(self._issues):
+            if idx in self._fixed_issues:
+                continue
+            if issue["row"] == row and issue["fix"] == "__DELETE__":
+                return idx
+        return None
+
+    def _compute_score(self) -> float:
+        if not self._issues:
+            return 1.0
+        total = len(self._issues)
+        fixed = len(self._fixed_issues)
+
+        # base score from fixed issues
+        base = fixed / total
+
+        # penalty for wrong fixes (capped so score stays >= 0)
+        penalty = min(self._wrong_fixes * 0.05, base)
+
+        # small efficiency bonus if done early
+        if self._done and self._max_steps > 0:
+            remaining_ratio = max(0, (self._max_steps - self._step_count)) / self._max_steps
+            efficiency = remaining_ratio * 0.05
+        else:
+            efficiency = 0.0
+
+        score = base - penalty + efficiency
+        return max(0.0, min(1.0, score))
+
+    def _ground_truth_value(self, dirty_row_idx: int, col: str) -> Any:
+        """Look up the expected clean value for a dirty-data row."""
+        # map dirty index to clean index (accounting for deleted rows in ground truth)
+        clean_idx = self._dirty_to_clean_idx(dirty_row_idx)
+        if clean_idx is not None and clean_idx < len(self._clean):
+            return self._clean[clean_idx].get(col)
+        return None
+
+    def _dirty_to_clean_idx(self, dirty_idx: int) -> Optional[int]:
+        """Map a dirty-data row index to the clean-data row index."""
+        # find rows that should be deleted
+        delete_rows = {
+            issue["row"]
+            for issue in self._issues
+            if issue["fix"] == "__DELETE__"
+        }
+        # count non-deleted rows before dirty_idx
+        if dirty_idx in delete_rows:
+            return None
+        clean_i = 0
+        for i in range(dirty_idx):
+            if i not in delete_rows:
+                clean_i += 1
+        return clean_i
+
+    @staticmethod
+    def _fuzzy_eq(a: str, b: str) -> bool:
+        """Lenient comparison for grading (strip, lower, remove leading zeros)."""
+        a = str(a).strip().lower()
+        b = str(b).strip().lower()
+        if a == b:
+            return True
+        # numeric comparison
+        try:
+            return abs(float(a) - float(b)) < 0.01
+        except (ValueError, TypeError):
+            pass
+        return False
+
+    @staticmethod
+    def _coerce(val_str: str, existing: Any) -> Any:
+        """Try to coerce the string value to the same type as the existing cell."""
+        if isinstance(existing, int):
+            try:
+                return int(float(val_str))
+            except (ValueError, TypeError):
+                return val_str
+        if isinstance(existing, float):
+            try:
+                return float(val_str)
+            except (ValueError, TypeError):
+                return val_str
+        return val_str
+
+    # ── observation builder ────────────────────────────────────────────────
+
+    def _build_observation(self) -> DataCleanObservation:
+        return DataCleanObservation(
+            task_name=self._task.get("name", ""),
+            task_description=self._task.get("description", ""),
+            difficulty=self._task.get("difficulty", ""),
+            data_preview=self._render_table(),
+            quality_report=self._render_quality_report(),
+            columns_info=self._render_columns_info(),
+            action_history=list(self._action_log[-10:]),
+            step_number=self._step_count,
+            max_steps=self._max_steps,
+            current_score=round(self._compute_score(), 4),
+        )
+
+    def _render_table(self) -> str:
+        """Render the current dataset as an aligned text table."""
+        if not self._data:
+            return "(empty dataset)"
+
+        cols = self._columns
+        # compute column widths
+        widths = {c: len(c) for c in cols}
+        widths["row"] = 3
+
+        active_rows: List[Tuple[int, Row]] = [
+            (i, row) for i, row in enumerate(self._data) if i not in self._deleted_rows
+        ]
+
+        for i, row in active_rows:
+            widths["row"] = max(widths["row"], len(str(i)))
+            for c in cols:
+                val = str(row.get(c, ""))
+                if val == "":
+                    val = "[EMPTY]"
+                widths[c] = max(widths[c], min(len(val), 30))
+
+        # header
+        hdr = "| " + " | ".join(
+            ["row".ljust(widths["row"])] + [c.ljust(widths[c]) for c in cols]
+        ) + " |"
+        sep = "|-" + "-|-".join(
+            ["-" * widths["row"]] + ["-" * widths[c] for c in cols]
+        ) + "-|"
+
+        lines = [hdr, sep]
+        for i, row in active_rows:
+            cells = [str(i).ljust(widths["row"])]
+            for c in cols:
+                val = str(row.get(c, ""))
+                if val == "":
+                    val = "[EMPTY]"
+                cells.append(val[:30].ljust(widths[c]))
+            lines.append("| " + " | ".join(cells) + " |")
+
+        return "\n".join(lines)
+
+    def _render_quality_report(self) -> str:
+        """Generate a quality-report hinting at (but not solving) issues."""
+        if not self._data:
+            return "No data loaded."
+
+        lines = ["DATA QUALITY REPORT", "=" * 40]
+        cols = self._columns
+        active_rows = [
+            (i, row) for i, row in enumerate(self._data) if i not in self._deleted_rows
+        ]
+        num_rows = len(active_rows)
+        lines.append(f"Total rows: {num_rows} (original: {len(self._data)}, deleted: {len(self._deleted_rows)})")
+
+        # per-column stats
+        for c in cols:
+            vals = [str(row.get(c, "")) for _, row in active_rows]
+            empties = sum(1 for v in vals if v.strip() == "" or v.strip().upper() == "NULL")
+            unique = len(set(vals))
+            if empties:
+                lines.append(f"  Column '{c}': {empties} empty/null value(s)")
+
+        # detect potential duplicates (simple exact-match check)
+        seen = {}
+        for i, row in active_rows:
+            key = tuple(str(row.get(c, "")) for c in cols)
+            if key in seen:
+                lines.append(f"  Possible duplicate: row {i} matches row {seen[key]}")
+            else:
+                seen[key] = i
+
+        # detect numeric anomalies
+        for c in cols:
+            numeric_vals = []
+            for i, row in active_rows:
+                try:
+                    numeric_vals.append((i, float(row[c])))
+                except (ValueError, TypeError, KeyError):
+                    pass
+            if len(numeric_vals) >= 3:
+                values = [v for _, v in numeric_vals]
+                mean = sum(values) / len(values)
+                for i, v in numeric_vals:
+                    if v < 0:
+                        lines.append(f"  Row {i}, '{c}': Negative value ({v})")
+                    elif abs(v - mean) > 3 * (max(values) - min(values) + 1) / 4:
+                        lines.append(f"  Row {i}, '{c}': Potential outlier ({v})")
+
+        # detect format inconsistencies in string columns
+        for c in cols:
+            vals = [str(row.get(c, "")) for _, row in active_rows]
+            non_empty = [v for v in vals if v.strip() and v.strip() != "[EMPTY]"]
+            if not non_empty:
+                continue
+            # check for mixed case patterns (all-caps vs lowercase)
+            has_upper = any(v.isupper() for v in non_empty)
+            has_lower = any(v.islower() or (not v.isupper() and not v.istitle()) for v in non_empty)
+            if has_upper and has_lower and c in ("email",):
+                lines.append(f"  Column '{c}': Mixed case formatting detected")
+
+            # check for format inconsistency in date-like columns
+            if c in ("date", "start_date", "birth_date"):
+                formats_seen = set()
+                for v in non_empty:
+                    if "/" in v:
+                        formats_seen.add("slash")
+                    elif "." in v and v.count(".") == 2:
+                        formats_seen.add("dot")
+                    elif "-" in v:
+                        formats_seen.add("dash")
+                if len(formats_seen) > 1:
+                    lines.append(f"  Column '{c}': Inconsistent date formats ({', '.join(formats_seen)})")
+
+        lines.append(f"\nProgress: {len(self._fixed_issues)}/{len(self._issues)} issues resolved")
+        lines.append(f"Steps used: {self._step_count}/{self._max_steps}")
+
+        return "\n".join(lines)
+
+    def _render_columns_info(self) -> List[Dict[str, Any]]:
+        active_rows = [
+            row for i, row in enumerate(self._data) if i not in self._deleted_rows
+        ]
+        info = []
+        for c in self._columns:
+            vals = [row.get(c, "") for row in active_rows]
+            non_empty = [v for v in vals if str(v).strip() not in ("", "NULL")]
+            info.append({
+                "name": c,
+                "total": len(vals),
+                "non_empty": len(non_empty),
+                "empty": len(vals) - len(non_empty),
+                "unique": len(set(str(v) for v in vals)),
+            })
+        return info

dataclean_env/server/tasks.py

@@ -0,0 +1,239 @@
+"""
+Task Definitions – Realistic datasets with known data-quality issues.
+=====================================================================
+Each task provides:
+    dirty_data   – the messy rows the agent starts with
+    clean_data   – ground-truth rows (used by the grader)
+    issues       – list describing every problem to fix
+    max_steps    – action budget
+    description  – human-readable goal
+"""
+
+from __future__ import annotations
+from typing import Any, Dict, List
+import copy
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+IssueDict = Dict[str, Any]
+Row = Dict[str, Any]
+
+# ── TASK 1 — EASY: Customer Contact Cleanup ───────────────────────────────
+
+_EASY_DIRTY: List[Row] = [
+    {"id": 1, "name": "John Smith",      "email": "john.smith@gmail.com",    "phone": "555-0101", "age": 35, "city": "New York"},
+    {"id": 2, "name": "Jane Doe",        "email": "",                        "phone": "555-0102", "age": 28, "city": "Los Angeles"},
+    {"id": 3, "name": "Bob Wilson",      "email": "bob.w@yahoo.com",         "phone": "555-ABCD", "age": 42, "city": "Chicago"},
+    {"id": 4, "name": "John Smith",      "email": "john.smith@gmail.com",    "phone": "555-0101", "age": 35, "city": "New York"},
+    {"id": 5, "name": "Alice Brown",     "email": "alice.b@hotmail.com",     "phone": "555-0105", "age": -3, "city": "Houston"},
+    {"id": 6, "name": "Charlie Davis",   "email": "charlie.d@gmail.com",     "phone": "555-0106", "age": 31, "city": "Phoenix"},
+    {"id": 7, "name": "Eva Martinez",    "email": "eva.m@outlook.com",       "phone": "555-0107", "age": 27, "city": "Philadelphia"},
+    {"id": 8, "name": "Frank Lee",       "email": "frank@gmail",             "phone": "555-0108", "age": 45, "city": "San Antonio"},
+    {"id": 9, "name": "Grace Kim",       "email": "grace.k@yahoo.com",       "phone": "555-0109", "age": 38, "city": "San Diego"},
+    {"id": 10,"name": "Henry Nguyen",    "email": "henry.n@gmail.com",       "phone": "555-0110", "age": 52, "city": "Dallas"},
+]
+
+_EASY_CLEAN: List[Row] = [
+    {"id": 1, "name": "John Smith",      "email": "john.smith@gmail.com",    "phone": "555-0101", "age": 35, "city": "New York"},
+    {"id": 2, "name": "Jane Doe",        "email": "jane.doe@email.com",      "phone": "555-0102", "age": 28, "city": "Los Angeles"},
+    {"id": 3, "name": "Bob Wilson",      "email": "bob.w@yahoo.com",         "phone": "555-0103", "age": 42, "city": "Chicago"},
+    # row 4 (duplicate of row 0) deleted
+    {"id": 5, "name": "Alice Brown",     "email": "alice.b@hotmail.com",     "phone": "555-0105", "age": 33, "city": "Houston"},
+    {"id": 6, "name": "Charlie Davis",   "email": "charlie.d@gmail.com",     "phone": "555-0106", "age": 31, "city": "Phoenix"},
+    {"id": 7, "name": "Eva Martinez",    "email": "eva.m@outlook.com",       "phone": "555-0107", "age": 27, "city": "Philadelphia"},
+    {"id": 8, "name": "Frank Lee",       "email": "frank@gmail.com",         "phone": "555-0108", "age": 45, "city": "San Antonio"},
+    {"id": 9, "name": "Grace Kim",       "email": "grace.k@yahoo.com",       "phone": "555-0109", "age": 38, "city": "San Diego"},
+    {"id": 10,"name": "Henry Nguyen",    "email": "henry.n@gmail.com",       "phone": "555-0110", "age": 52, "city": "Dallas"},
+]
+
+_EASY_ISSUES: List[IssueDict] = [
+    {"row": 1, "col": "email",  "type": "missing_value",    "desc": "Missing email address",                  "fix": "jane.doe@email.com"},
+    {"row": 2, "col": "phone",  "type": "invalid_format",   "desc": "Phone contains letters (555-ABCD)",      "fix": "555-0103"},
+    {"row": 3, "col": None,     "type": "duplicate_row",    "desc": "Exact duplicate of row 0",                "fix": "__DELETE__"},
+    {"row": 4, "col": "age",    "type": "invalid_value",    "desc": "Negative age (-3)",                       "fix": "33"},
+    {"row": 7, "col": "email",  "type": "invalid_format",   "desc": "Email missing TLD (frank@gmail)",         "fix": "frank@gmail.com"},
+]
+
+
+# ── TASK 2 — MEDIUM: E-commerce Order Normalisation ──────────────────────
+
+_MED_DIRTY: List[Row] = [
+    {"order_id": "ORD-001", "customer": "Acme Corp",       "product": "P100",  "quantity": 10,  "price": "249.99",    "date": "2024-01-15", "status": "delivered"},
+    {"order_id": "ORD-002", "customer": "Globex Inc",      "product": "P102",  "quantity": 5,   "price": "599.00",    "date": "2024-01-18", "status": "delivered"},
+    {"order_id": "ORD-003", "customer": "Initech LLC",     "product": "P100",  "quantity": 3,   "price": "249.99",    "date": "15/02/2024", "status": "shipped"},
+    {"order_id": "ORD-004", "customer": "Umbrella Co",     "product": "P105",  "quantity": 8,   "price": "149.50",    "date": "2024-02-20", "status": "delivered"},
+    {"order_id": "ORD-005", "customer": "Stark Ind",       "product": "P-102", "quantity": 12,  "price": "599.00",    "date": "2024-03-01", "status": "shipped"},
+    {"order_id": "ORD-006", "customer": "Wayne Ent",       "product": "P108",  "quantity": -2,  "price": "$1,234.56", "date": "2024-03-05", "status": "processing"},
+    {"order_id": "ORD-007", "customer": "Oscorp",          "product": "P100",  "quantity": 7,   "price": "249.99",    "date": "2024-03-10", "status": "delivered"},
+    {"order_id": "ORD-008", "customer": "Cyberdyne Sys",   "product": "P110",  "quantity": 1,   "price": "899.00",    "date": "2024.03.15", "status": "delivered"},
+    {"order_id": "ORD-009", "customer": "Soylent Corp",    "product": "P105",  "quantity": 4,   "price": "149.50",    "date": "2024-03-20", "status": "shiped"},
+    {"order_id": "ORD-010", "customer": "Globex Inc",      "product": "P102",  "quantity": 5,   "price": "599.00",    "date": "2024-01-18", "status": "delivered"},
+    {"order_id": "ORD-011", "customer": "Tyrell Corp",     "product": "P112",  "quantity": 6,   "price": "",          "date": "2024-04-01", "status": "processing"},
+    {"order_id": "ORD-012", "customer": "Wonka Ind",       "product": "P100",  "quantity": 20,  "price": "249.99",    "date": "01-05-2024", "status": "shipped"},
+    {"order_id": "ORD-013", "customer": "Prestige World",  "product": "P-105", "quantity": 9,   "price": "149.50",    "date": "2024-05-10", "status": "delivered"},
+    {"order_id": "ORD-014", "customer": "Massive Dyn",     "product": "P108",  "quantity": 3,   "price": "1234.56",   "date": "2024-05-15", "status": "delivered"},
+    {"order_id": "ORD-015", "customer": "Aperture Sci",    "product": "P115",  "quantity": 15,  "price": "75.00",     "date": "2024-06-01", "status": "shipped"},
+]
+
+_MED_CLEAN: List[Row] = [
+    {"order_id": "ORD-001", "customer": "Acme Corp",       "product": "P100",  "quantity": 10,  "price": "249.99",    "date": "2024-01-15", "status": "delivered"},
+    {"order_id": "ORD-002", "customer": "Globex Inc",      "product": "P102",  "quantity": 5,   "price": "599.00",    "date": "2024-01-18", "status": "delivered"},
+    {"order_id": "ORD-003", "customer": "Initech LLC",     "product": "P100",  "quantity": 3,   "price": "249.99",    "date": "2024-02-15", "status": "shipped"},
+    {"order_id": "ORD-004", "customer": "Umbrella Co",     "product": "P105",  "quantity": 8,   "price": "149.50",    "date": "2024-02-20", "status": "delivered"},
+    {"order_id": "ORD-005", "customer": "Stark Ind",       "product": "P102",  "quantity": 12,  "price": "599.00",    "date": "2024-03-01", "status": "shipped"},
+    {"order_id": "ORD-006", "customer": "Wayne Ent",       "product": "P108",  "quantity": 2,   "price": "1234.56",   "date": "2024-03-05", "status": "processing"},
+    {"order_id": "ORD-007", "customer": "Oscorp",          "product": "P100",  "quantity": 7,   "price": "249.99",    "date": "2024-03-10", "status": "delivered"},
+    {"order_id": "ORD-008", "customer": "Cyberdyne Sys",   "product": "P110",  "quantity": 1,   "price": "899.00",    "date": "2024-03-15", "status": "delivered"},
+    {"order_id": "ORD-009", "customer": "Soylent Corp",    "product": "P105",  "quantity": 4,   "price": "149.50",    "date": "2024-03-20", "status": "shipped"},
+    # row 9 (duplicate of row 1) deleted
+    {"order_id": "ORD-011", "customer": "Tyrell Corp",     "product": "P112",  "quantity": 6,   "price": "350.00",    "date": "2024-04-01", "status": "processing"},
+    {"order_id": "ORD-012", "customer": "Wonka Ind",       "product": "P100",  "quantity": 20,  "price": "249.99",    "date": "2024-05-01", "status": "shipped"},
+    {"order_id": "ORD-013", "customer": "Prestige World",  "product": "P105",  "quantity": 9,   "price": "149.50",    "date": "2024-05-10", "status": "delivered"},
+    {"order_id": "ORD-014", "customer": "Massive Dyn",     "product": "P108",  "quantity": 3,   "price": "1234.56",   "date": "2024-05-15", "status": "delivered"},
+    {"order_id": "ORD-015", "customer": "Aperture Sci",    "product": "P115",  "quantity": 15,  "price": "75.00",     "date": "2024-06-01", "status": "shipped"},
+]
+
+_MED_ISSUES: List[IssueDict] = [
+    {"row": 2,  "col": "date",     "type": "inconsistent_format", "desc": "Date in DD/MM/YYYY format instead of YYYY-MM-DD", "fix": "2024-02-15"},
+    {"row": 4,  "col": "product",  "type": "inconsistent_format", "desc": "Product code has dash (P-102 vs P102)",           "fix": "P102"},
+    {"row": 5,  "col": "quantity", "type": "invalid_value",       "desc": "Negative quantity (-2)",                           "fix": "2"},
+    {"row": 5,  "col": "price",    "type": "inconsistent_format", "desc": "Price has $ and comma ($1,234.56)",                "fix": "1234.56"},
+    {"row": 7,  "col": "date",     "type": "inconsistent_format", "desc": "Date uses dots (2024.03.15)",                      "fix": "2024-03-15"},
+    {"row": 8,  "col": "status",   "type": "typo",               "desc": "Status misspelled: shiped -> shipped",              "fix": "shipped"},
+    {"row": 9,  "col": None,       "type": "duplicate_row",       "desc": "Duplicate of row 1 (same order)",                  "fix": "__DELETE__"},
+    {"row": 10, "col": "price",    "type": "missing_value",       "desc": "Missing price for P112 product",                   "fix": "350.00"},
+    {"row": 11, "col": "date",     "type": "inconsistent_format", "desc": "Date in DD-MM-YYYY format",                        "fix": "2024-05-01"},
+    {"row": 12, "col": "product",  "type": "inconsistent_format", "desc": "Product code has dash (P-105 vs P105)",            "fix": "P105"},
+]
+
+
+# ── TASK 3 — HARD: Employee Records Audit ─────────────────────────────────
+
+_HARD_DIRTY: List[Row] = [
+    {"emp_id": "E001", "name": "Sarah Johnson",    "email": "sarah.j@company.com",       "birth_date": "1985-06-12", "age": 39, "department": "Engineering", "dept_code": "ENG", "role": "Senior Engineer",    "salary": 125000, "start_date": "2015-03-01", "manager_id": "E010"},
+    {"emp_id": "E002", "name": "Michael Chen",     "email": "michael.c@company.com",     "birth_date": "1990-03-15", "age": 28, "department": "Engineering", "dept_code": "ENG", "role": "Junior Developer",   "salary": 72000,  "start_date": "2022-07-15", "manager_id": "E001"},
+    {"emp_id": "E003", "name": "Emily Watson",     "email": "emily.w@company.com",       "birth_date": "1988-11-22", "age": 36, "department": "Marketing",   "dept_code": "MKT", "role": "Marketing Manager",  "salary": 98000,  "start_date": "2018-01-10", "manager_id": "E010"},
+    {"emp_id": "E004", "name": "David Park",       "email": "david.p@company.com",       "birth_date": "1992-07-04", "age": 32, "department": "Engineering", "dept_code": "MKT", "role": "Software Engineer",  "salary": 105000, "start_date": "2020-09-01", "manager_id": "E001"},
+    {"emp_id": "E005", "name": "Lisa Rodriguez",   "email": "lisa.r@company.com",        "birth_date": "1995-01-30", "age": 29, "department": "Sales",       "dept_code": "SAL", "role": "Sales Representative","salary": 65000,  "start_date": "2023-02-14", "manager_id": "E008"},
+    {"emp_id": "E006", "name": "James O'Brien",    "email": "james.ob@company.com",      "birth_date": "1987-09-18", "age": 37, "department": "Finance",     "dept_code": "FIN", "role": "Financial Analyst",  "salary": 88000,  "start_date": "2019-05-20", "manager_id": "E010"},
+    {"emp_id": "E007", "name": "James Obrien",     "email": "james.ob@company.com",      "birth_date": "1987-09-18", "age": 37, "department": "Finance",     "dept_code": "FIN", "role": "Financial Analyst",  "salary": 88000,  "start_date": "2019-05-20", "manager_id": "E010"},
+    {"emp_id": "E008", "name": "Rachel Green",     "email": "rachel.g@company.com",      "birth_date": "1983-04-05", "age": 41, "department": "Sales",       "dept_code": "SAL", "role": "Sales Director",     "salary": 140000, "start_date": "2014-11-01", "manager_id": "E010"},
+    {"emp_id": "E009", "name": "Tom Anderson",     "email": "tom.a@company.com",         "birth_date": "1991-12-25", "age": 33, "department": "Engineering", "dept_code": "ENG", "role": "Junior Developer",   "salary": 250000, "start_date": "2023-06-01", "manager_id": "E001"},
+    {"emp_id": "E010", "name": "Patricia Moore",   "email": "patricia.m@company.com",    "birth_date": "1978-02-14", "age": 46, "department": "Executive",   "dept_code": "EXE", "role": "VP of Operations",   "salary": 185000, "start_date": "2010-01-15", "manager_id": ""},
+    {"emp_id": "E011", "name": "Kevin Hall",       "email": "kevin.h@company.com",       "birth_date": "1993-08-07", "age": 31, "department": "Marketing",   "dept_code": "MKT", "role": "Content Specialist", "salary": 62000,  "start_date": "2025-08-01", "manager_id": "E003"},
+    {"emp_id": "E012", "name": "Amy Liu",          "email": "AMY.LIU@COMPANY.COM",       "birth_date": "1994-05-19", "age": 30, "department": "Engineering", "dept_code": "ENG", "role": "QA Engineer",        "salary": 82000,  "start_date": "2021-04-12", "manager_id": "E001"},
+    {"emp_id": "E013", "name": "Robert Taylor",    "email": "robert.t@company.com",      "birth_date": "1986-10-31", "age": 38, "department": "",            "dept_code": "SAL", "role": "Account Manager",    "salary": 78000,  "start_date": "2020-01-06", "manager_id": "E008"},
+    {"emp_id": "E014", "name": "NULL",             "email": "nina.s@company.com",        "birth_date": "1997-03-22", "age": 27, "department": "Finance",     "dept_code": "FIN", "role": "Junior Analyst",     "salary": 58000,  "start_date": "2024-01-08", "manager_id": "E006"},
+    {"emp_id": "E015", "name": "Carlos Mendez",    "email": "carlos.m@company.com",      "birth_date": "1989-07-16", "age": 35, "department": "Engineering", "dept_code": "ENG", "role": "DevOps Engineer",    "salary": -95000, "start_date": "2019-10-01", "manager_id": "E001"},
+    {"emp_id": "E016", "name": "Sophie Turner",    "email": "sophie.t@company.com",      "birth_date": "1996-11-03", "age": 28, "department": "Marketing",   "dept_code": "MKT", "role": "Social Media Mgr",   "salary": 60000,  "start_date": "2022-03-15", "manager_id": "E003"},
+    {"emp_id": "E017", "name": "Alex Rivera",      "email": "alex.r@company.com",        "birth_date": "1984-01-28", "age": 40, "department": "Sales",       "dept_code": "SAL", "role": "Regional Manager",   "salary": 110000, "start_date": "1899-01-01", "manager_id": "E008"},
+    {"emp_id": "E018", "name": "Diana Foster",     "email": "diana.f@company.com",       "birth_date": "1991-06-09", "age": 33, "department": "Finance",     "dept_code": "FIN", "role": "Senior Accountant",  "salary": 92000,  "start_date": "2017-08-21", "manager_id": "E006"},
+    {"emp_id": "E019", "name": "Brandon White",    "email": "brandon.w@company.com",     "birth_date": "1998-04-14", "age": 26, "department": "Engineering", "dept_code": "ENG", "role": "Intern",             "salary": 45000,  "start_date": "2024-06-01", "manager_id": "E999"},
+    {"emp_id": "E020", "name": "Maria Gonzalez",   "email": "maria.g@company.com",       "birth_date": "1982-12-01", "age": 42, "department": "Executive",   "dept_code": "EXE", "role": "CFO",                "salary": 210000, "start_date": "2012-04-01", "manager_id": ""},
+]
+
+_HARD_CLEAN: List[Row] = [
+    {"emp_id": "E001", "name": "Sarah Johnson",    "email": "sarah.j@company.com",       "birth_date": "1985-06-12", "age": 39, "department": "Engineering", "dept_code": "ENG", "role": "Senior Engineer",    "salary": 125000, "start_date": "2015-03-01", "manager_id": "E010"},
+    {"emp_id": "E002", "name": "Michael Chen",     "email": "michael.c@company.com",     "birth_date": "1990-03-15", "age": 34, "department": "Engineering", "dept_code": "ENG", "role": "Junior Developer",   "salary": 72000,  "start_date": "2022-07-15", "manager_id": "E001"},
+    {"emp_id": "E003", "name": "Emily Watson",     "email": "emily.w@company.com",       "birth_date": "1988-11-22", "age": 36, "department": "Marketing",   "dept_code": "MKT", "role": "Marketing Manager",  "salary": 98000,  "start_date": "2018-01-10", "manager_id": "E010"},
+    {"emp_id": "E004", "name": "David Park",       "email": "david.p@company.com",       "birth_date": "1992-07-04", "age": 32, "department": "Engineering", "dept_code": "ENG", "role": "Software Engineer",  "salary": 105000, "start_date": "2020-09-01", "manager_id": "E001"},
+    {"emp_id": "E005", "name": "Lisa Rodriguez",   "email": "lisa.r@company.com",        "birth_date": "1995-01-30", "age": 29, "department": "Sales",       "dept_code": "SAL", "role": "Sales Representative","salary": 65000,  "start_date": "2023-02-14", "manager_id": "E008"},
+    {"emp_id": "E006", "name": "James O'Brien",    "email": "james.ob@company.com",      "birth_date": "1987-09-18", "age": 37, "department": "Finance",     "dept_code": "FIN", "role": "Financial Analyst",  "salary": 88000,  "start_date": "2019-05-20", "manager_id": "E010"},
+    # row 6 (near-duplicate of row 5) deleted
+    {"emp_id": "E008", "name": "Rachel Green",     "email": "rachel.g@company.com",      "birth_date": "1983-04-05", "age": 41, "department": "Sales",       "dept_code": "SAL", "role": "Sales Director",     "salary": 140000, "start_date": "2014-11-01", "manager_id": "E010"},
+    {"emp_id": "E009", "name": "Tom Anderson",     "email": "tom.a@company.com",         "birth_date": "1991-12-25", "age": 33, "department": "Engineering", "dept_code": "ENG", "role": "Junior Developer",   "salary": 75000,  "start_date": "2023-06-01", "manager_id": "E001"},
+    {"emp_id": "E010", "name": "Patricia Moore",   "email": "patricia.m@company.com",    "birth_date": "1978-02-14", "age": 46, "department": "Executive",   "dept_code": "EXE", "role": "VP of Operations",   "salary": 185000, "start_date": "2010-01-15", "manager_id": ""},
+    {"emp_id": "E011", "name": "Kevin Hall",       "email": "kevin.h@company.com",       "birth_date": "1993-08-07", "age": 31, "department": "Marketing",   "dept_code": "MKT", "role": "Content Specialist", "salary": 62000,  "start_date": "2024-08-01", "manager_id": "E003"},
+    {"emp_id": "E012", "name": "Amy Liu",          "email": "amy.liu@company.com",       "birth_date": "1994-05-19", "age": 30, "department": "Engineering", "dept_code": "ENG", "role": "QA Engineer",        "salary": 82000,  "start_date": "2021-04-12", "manager_id": "E001"},
+    {"emp_id": "E013", "name": "Robert Taylor",    "email": "robert.t@company.com",      "birth_date": "1986-10-31", "age": 38, "department": "Sales",       "dept_code": "SAL", "role": "Account Manager",    "salary": 78000,  "start_date": "2020-01-06", "manager_id": "E008"},
+    {"emp_id": "E014", "name": "Nina Sharma",      "email": "nina.s@company.com",        "birth_date": "1997-03-22", "age": 27, "department": "Finance",     "dept_code": "FIN", "role": "Junior Analyst",     "salary": 58000,  "start_date": "2024-01-08", "manager_id": "E006"},
+    {"emp_id": "E015", "name": "Carlos Mendez",    "email": "carlos.m@company.com",      "birth_date": "1989-07-16", "age": 35, "department": "Engineering", "dept_code": "ENG", "role": "DevOps Engineer",    "salary": 95000,  "start_date": "2019-10-01", "manager_id": "E001"},
+    {"emp_id": "E016", "name": "Sophie Turner",    "email": "sophie.t@company.com",      "birth_date": "1996-11-03", "age": 28, "department": "Marketing",   "dept_code": "MKT", "role": "Social Media Mgr",   "salary": 60000,  "start_date": "2022-03-15", "manager_id": "E003"},
+    {"emp_id": "E017", "name": "Alex Rivera",      "email": "alex.r@company.com",        "birth_date": "1984-01-28", "age": 40, "department": "Sales",       "dept_code": "SAL", "role": "Regional Manager",   "salary": 110000, "start_date": "2016-09-01", "manager_id": "E008"},
+    {"emp_id": "E018", "name": "Diana Foster",     "email": "diana.f@company.com",       "birth_date": "1991-06-09", "age": 33, "department": "Finance",     "dept_code": "FIN", "role": "Senior Accountant",  "salary": 92000,  "start_date": "2017-08-21", "manager_id": "E006"},
+    {"emp_id": "E019", "name": "Brandon White",    "email": "brandon.w@company.com",     "birth_date": "1998-04-14", "age": 26, "department": "Engineering", "dept_code": "ENG", "role": "Intern",             "salary": 45000,  "start_date": "2024-06-01", "manager_id": "E001"},
+    {"emp_id": "E020", "name": "Maria Gonzalez",   "email": "maria.g@company.com",       "birth_date": "1982-12-01", "age": 42, "department": "Executive",   "dept_code": "EXE", "role": "CFO",                "salary": 210000, "start_date": "2012-04-01", "manager_id": ""},
+]
+
+_HARD_ISSUES: List[IssueDict] = [
+    {"row": 1,  "col": "age",        "type": "cross_field",         "desc": "Age 28 inconsistent with birth_date 1990-03-15 (should be ~34)",  "fix": "34"},
+    {"row": 3,  "col": "dept_code",  "type": "cross_field",         "desc": "dept_code MKT but department is Engineering",                      "fix": "ENG"},
+    {"row": 6,  "col": None,         "type": "near_duplicate",      "desc": "Near-duplicate of row 5 (James Obrien vs James O'Brien)",          "fix": "__DELETE__"},
+    {"row": 8,  "col": "salary",     "type": "anomalous_value",     "desc": "Salary $250k for Junior Developer (expected $60k-$85k)",           "fix": "75000"},
+    {"row": 10, "col": "start_date", "type": "future_date",         "desc": "Start date 2025-08-01 is in the future",                           "fix": "2024-08-01"},
+    {"row": 11, "col": "email",      "type": "inconsistent_format", "desc": "Email in ALL CAPS vs lowercase convention",                        "fix": "amy.liu@company.com"},
+    {"row": 12, "col": "department", "type": "missing_value",       "desc": "Department empty but dept_code is SAL",                             "fix": "Sales"},
+    {"row": 13, "col": "name",       "type": "placeholder_value",   "desc": "Name is literal 'NULL' string instead of real name",               "fix": "Nina Sharma"},
+    {"row": 14, "col": "salary",     "type": "invalid_value",       "desc": "Negative salary (-95000)",                                         "fix": "95000"},
+    {"row": 16, "col": "start_date", "type": "anomalous_value",     "desc": "Start date 1899-01-01 is clearly wrong",                           "fix": "2016-09-01"},
+    {"row": 18, "col": "manager_id", "type": "referential",         "desc": "manager_id E999 does not exist in employee list",                  "fix": "E001"},
+]
+
+
+# ── public registry ────────────────────────────────────────────────────────
+
+TASKS = {
+    "easy": {
+        "name": "easy",
+        "title": "Customer Contact Cleanup",
+        "difficulty": "easy",
+        "description": (
+            "You are a data-quality analyst. A customer-contacts spreadsheet has "
+            "been imported with several obvious errors: missing e-mails, invalid "
+            "phone numbers, duplicate rows, and impossible ages. "
+            "Identify and fix every issue. Use the available actions to correct "
+            "each problem, then submit when you believe the data is clean."
+        ),
+        "dirty_data": _EASY_DIRTY,
+        "clean_data": _EASY_CLEAN,
+        "issues": _EASY_ISSUES,
+        "max_steps": 15,
+        "columns": ["id", "name", "email", "phone", "age", "city"],
+    },
+    "medium": {
+        "name": "medium",
+        "title": "E-commerce Order Normalisation",
+        "difficulty": "medium",
+        "description": (
+            "You are a data engineer preparing an orders export for a BI dashboard. "
+            "The dataset has mixed date formats (YYYY-MM-DD, DD/MM/YYYY, YYYY.MM.DD, DD-MM-YYYY), "
+            "inconsistent price formatting, product-code variants (P100 vs P-100), "
+            "a typo in a status field, a duplicate order, negative quantities, "
+            "and missing values. Normalise every field so the data is consistent, "
+            "then submit."
+        ),
+        "dirty_data": _MED_DIRTY,
+        "clean_data": _MED_CLEAN,
+        "issues": _MED_ISSUES,
+        "max_steps": 25,
+        "columns": ["order_id", "customer", "product", "quantity", "price", "date", "status"],
+    },
+    "hard": {
+        "name": "hard",
+        "title": "Employee Records Audit",
+        "difficulty": "hard",
+        "description": (
+            "You are auditing an HR database before a compliance review. "
+            "The employee records contain subtle cross-field inconsistencies "
+            "(age vs birth-date mismatches, department vs dept-code conflicts), "
+            "near-duplicate employees with slightly different name spellings, "
+            "anomalous salary values for the given role, future or impossible dates, "
+            "placeholder 'NULL' strings, ALL-CAPS email addresses, missing departments, "
+            "and referential-integrity violations (manager_id pointing to non-existent employees). "
+            "Find and fix all issues, then submit."
+        ),
+        "dirty_data": _HARD_DIRTY,
+        "clean_data": _HARD_CLEAN,
+        "issues": _HARD_ISSUES,
+        "max_steps": 35,
+        "columns": ["emp_id", "name", "email", "birth_date", "age", "department",
+                     "dept_code", "role", "salary", "start_date", "manager_id"],
+    },
+}
+
+
+def get_task(name: str) -> dict:
+    """Return a deep copy of a task definition so mutations are isolated."""
+    if name not in TASKS:
+        raise ValueError(f"Unknown task '{name}'. Choose from: {list(TASKS.keys())}")
+    return copy.deepcopy(TASKS[name])

inference.py

@@ -0,0 +1,263 @@
+"""
+Inference Script — DataClean Environment
+=========================================
+MANDATORY:
+- Before submitting, ensure the following variables are defined:
+    API_BASE_URL   The API endpoint for the LLM.
+    MODEL_NAME     The model identifier to use for inference.
+    HF_TOKEN       Your Hugging Face / API key.
+- This script must be named `inference.py` and placed in the root directory.
+- Uses OpenAI Client for all LLM calls.
+"""
+
+import json
+import os
+import re
+import sys
+import textwrap
+from typing import List, Optional
+
+from openai import OpenAI
+
+# ---------------------------------------------------------------------------
+# Inline client (HTTP) so inference.py is self-contained
+# ---------------------------------------------------------------------------
+import requests
+
+
+class _StepResult:
+    def __init__(self, observation: dict, reward: float, done: bool):
+        self.observation = observation
+        self.reward = reward
+        self.done = done
+
+
+class _SimpleClient:
+    """Minimal sync HTTP client for the DataClean environment."""
+
+    def __init__(self, base_url: str):
+        self.base_url = base_url.rstrip("/")
+        self.s = requests.Session()
+
+    def reset(self, task_name: str = "easy") -> _StepResult:
+        r = self.s.post(f"{self.base_url}/reset", json={"task_name": task_name}, timeout=30)
+        r.raise_for_status()
+        d = r.json()
+        return _StepResult(d.get("observation", {}), float(d.get("reward", 0)), bool(d.get("done", False)))
+
+    def step(self, action: dict) -> _StepResult:
+        r = self.s.post(f"{self.base_url}/step", json=action, timeout=30)
+        r.raise_for_status()
+        d = r.json()
+        return _StepResult(d.get("observation", {}), float(d.get("reward", 0)), bool(d.get("done", False)))
+
+    def close(self):
+        self.s.close()
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+MODEL_NAME = os.getenv("MODEL_NAME")
+
+# Where the DataClean env server is running
+ENV_BASE_URL = os.getenv("ENV_BASE_URL", "http://localhost:7860")
+
+MAX_STEPS_PER_TASK = {"easy": 12, "medium": 20, "hard": 30}
+TEMPERATURE = 0.1
+MAX_TOKENS = 400
+
+SYSTEM_PROMPT = textwrap.dedent("""\
+You are an expert data-quality analyst. You are interacting with a data-cleaning
+environment. Your goal is to identify and fix all data-quality issues.
+
+After reviewing the data and quality report, respond with EXACTLY ONE action in
+valid JSON format. Available actions:
+
+1. Fix a cell value:
+   {"action_type": "fix_value", "row_index": <int>, "column_name": "<col>", "new_value": "<corrected>"}
+
+2. Delete a duplicate/invalid row:
+   {"action_type": "delete_row", "row_index": <int>}
+
+3. Fill a missing value:
+   {"action_type": "fill_missing", "row_index": <int>, "column_name": "<col>", "new_value": "<value>"}
+
+4. Flag a suspicious cell (partial credit):
+   {"action_type": "flag_anomaly", "row_index": <int>, "column_name": "<col>"}
+
+5. Submit your work (ends the episode):
+   {"action_type": "submit"}
+
+6. Do nothing this step:
+   {"action_type": "noop"}
+
+RULES:
+- row_index is 0-based and refers to the ORIGINAL row number shown in the table.
+- Respond ONLY with the JSON action. No explanations, no markdown, no extra text.
+- Fix the most obvious/critical issues first.
+- When all issues appear resolved, use submit.
+- Dates should be in YYYY-MM-DD format.
+- Prices should be plain numbers without $ or commas.
+- Product codes should NOT have dashes (e.g., P102 not P-102).
+- Emails should be lowercase.
+""").strip()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+ACTION_JSON_RE = re.compile(r"\{[^}]+\}", re.DOTALL)
+
+
+def parse_action(text: str) -> dict:
+    """Extract the first JSON object from the model response."""
+    if not text:
+        return {"action_type": "noop"}
+    m = ACTION_JSON_RE.search(text)
+    if m:
+        try:
+            obj = json.loads(m.group(0))
+            if "action_type" in obj:
+                return obj
+        except json.JSONDecodeError:
+            pass
+    return {"action_type": "noop"}
+
+
+def build_user_prompt(obs: dict, step_num: int) -> str:
+    """Build the user prompt from the observation."""
+    parts = [
+        f"TASK: {obs.get('task_description', '')}",
+        f"DIFFICULTY: {obs.get('difficulty', '')}",
+        f"STEP: {step_num}/{obs.get('max_steps', '?')}",
+        f"CURRENT SCORE: {obs.get('current_score', 0.0)}",
+        "",
+        "CURRENT DATA:",
+        obs.get("data_preview", "(no data)"),
+        "",
+        obs.get("quality_report", ""),
+    ]
+    history = obs.get("action_history", [])
+    if history:
+        parts.append("")
+        parts.append("RECENT ACTIONS:")
+        for h in history[-5:]:
+            parts.append(f"  {h}")
+
+    parts.append("")
+    parts.append("Respond with exactly one JSON action.")
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Run one task
+# ---------------------------------------------------------------------------
+def run_task(
+    llm_client: OpenAI,
+    env_client: _SimpleClient,
+    task_name: str,
+    max_steps: int,
+) -> float:
+    """Run a single task and return the final score."""
+    print(f"\n{'='*60}")
+    print(f"  TASK: {task_name.upper()}")
+    print(f"{'='*60}")
+
+    result = env_client.reset(task_name)
+    obs = result.observation
+    print(f"  Task: {obs.get('task_description', '')[:80]}...")
+    print(f"  Max steps: {max_steps}")
+
+    for step in range(1, max_steps + 1):
+        if result.done:
+            print(f"  Episode done at step {step - 1}")
+            break
+
+        user_prompt = build_user_prompt(obs, step)
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": user_prompt},
+        ]
+
+        try:
+            completion = llm_client.chat.completions.create(
+                model=MODEL_NAME,
+                messages=messages,
+                temperature=TEMPERATURE,
+                max_tokens=MAX_TOKENS,
+                stream=False,
+            )
+            response_text = completion.choices[0].message.content or ""
+        except Exception as exc:
+            print(f"  Step {step}: LLM error ({exc}), using noop")
+            response_text = '{"action_type": "noop"}'
+
+        action = parse_action(response_text)
+        print(f"  Step {step}: {action.get('action_type', '?')}", end="")
+        if action.get("row_index") is not None:
+            print(f" row={action['row_index']}", end="")
+        if action.get("column_name"):
+            print(f" col={action['column_name']}", end="")
+        if action.get("new_value"):
+            print(f" val={action['new_value']}", end="")
+
+        result = env_client.step(action)
+        obs = result.observation
+        print(f"  -> reward={result.reward:.4f} done={result.done}")
+
+        if result.done:
+            break
+
+    # If agent never submitted, force submit
+    if not result.done:
+        result = env_client.step({"action_type": "submit"})
+
+    final_score = result.reward
+    print(f"\n  FINAL SCORE ({task_name}): {final_score:.4f}")
+    return final_score
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+def main() -> None:
+    if not API_KEY:
+        print("ERROR: HF_TOKEN or API_KEY environment variable not set")
+        sys.exit(1)
+    if not MODEL_NAME:
+        print("ERROR: MODEL_NAME environment variable not set")
+        sys.exit(1)
+
+    print("DataClean Environment — Baseline Inference")
+    print(f"  API: {API_BASE_URL}")
+    print(f"  Model: {MODEL_NAME}")
+    print(f"  Env: {ENV_BASE_URL}")
+
+    llm_client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    env_client = _SimpleClient(ENV_BASE_URL)
+
+    scores = {}
+    try:
+        for task_name in ["easy", "medium", "hard"]:
+            max_steps = MAX_STEPS_PER_TASK[task_name]
+            score = run_task(llm_client, env_client, task_name, max_steps)
+            scores[task_name] = score
+    finally:
+        env_client.close()
+
+    print(f"\n{'='*60}")
+    print("  FINAL RESULTS")
+    print(f"{'='*60}")
+    for name, score in scores.items():
+        bar = "#" * int(score * 40)
+        print(f"  {name:8s}: {score:.4f}  [{bar:<40s}]")
+    avg = sum(scores.values()) / len(scores) if scores else 0.0
+    print(f"  {'AVERAGE':8s}: {avg:.4f}")
+    print(f"{'='*60}")
+
+
+if __name__ == "__main__":
+    main()

openenv.yaml

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

pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dataclean-env"
+version = "1.0.0"
+description = "OpenEnv environment for training AI agents on real-world data-quality cleaning tasks"
+readme = "README.md"
+license = {text = "BSD-3-Clause"}
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+    "requests>=2.25.0",
+    "pydantic>=2.0.0",
+    "openai>=1.0.0",
+]
+
+[project.optional-dependencies]
+server = [
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["dataclean_env*"]

requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+requests>=2.25.0
+pydantic>=2.0.0
+openai>=1.0.0
+websockets>=12.0