README.md

metadata

title: Data Cleaning Environment
emoji: 🧹
colorFrom: blue
colorTo: green
sdk: docker
app_port: 8000
base_path: /web

Data Cleaning Environment

A real-world OpenEnv environment where an AI agent learns to clean tabular data through the standard step() / reset() / state() API.

The agent receives a dirty CSV-style dataset and must apply cleaning operations step-by-step to maximise a data-quality score (0.0 → 1.0).

---

Tasks

Task ID	Difficulty	Description	Max Steps
easy	Easy	Fix 3 missing values (name / age) in a 5-row table	10
medium	Medium	Remove 2 duplicate rows and fix 2 type errors in age	15
hard	Hard	Full pipeline: missing values + duplicates + outliers + normalise text	25

---

Action Space

{
  "operation": "<string>",
  "column":    "<string | null>"
}

Operation	Task(s)	Effect
impute_mean	easy	Fill numeric None with column mean
impute_mode	easy	Fill string None with column mode
drop_missing_rows	easy / medium	Drop all rows containing any None
remove_duplicates	medium	Drop exact-duplicate rows
fix_type_errors	medium	Coerce non-numeric values to float (or None)
remove_outliers	hard	Drop rows where price ≤ 0 or price ≥ 500
normalize_text	hard	Strip whitespace + title-case all string columns
fill_quantity_mean	hard	Fill missing quantity with column mean

---

Observation Space

Field	Type	Description
current_text	str	Human-readable table of current rows
is_normalized	bool	True when no missing values, duplicates, or outliers left
remaining_typos	int	Composite issue count (missing + dupes + outliers)
html_found	bool	Always False (compatibility field)
done	bool	Episode ended (score=1.0 or step limit reached)
reward	float	Δ quality score from this step (partial progress signal)
metadata	dict	Full row data, per-field diagnostics, valid ops list

---

Reward Function

reward = (quality_score_after - quality_score_before) + 0.01   # if improvement
reward = (quality_score_after - quality_score_before) - 0.01   # if no improvement

Each task has its own grader:

• Easy: fraction of the 3 original missing values that are resolved
• Medium: average of (dedup score, type-fix score)
• Hard: average of 4 sub-scores (no missing, no dupes, no outliers, normalised text)

Invalid operations incur a −0.05 penalty but do not end the episode.

---

Baseline Scores

Deterministic rule-based agent (reproducible, seed=42):

Task	Score
easy	1.0
medium	1.0
hard	1.0

---

API Endpoints

Method	Path	Description
POST	/reset	Start new episode. Body: {"task":"easy"}
POST	/step	Apply action. Body: {"action":{...}}
GET	/state	Current episode state
GET	/schema	Action + Observation JSON schemas
GET	/tasks	Task list + action schema per difficulty
POST	/grader	Score the current episode (0.0–1.0)
POST	/baseline	Run baseline agent on all 3 tasks
GET	/health	Health check
WS	/ws	WebSocket for low-latency persistent sessions

---

Quick Start

1. Reset to a task

curl -X POST http://localhost:8000/reset \
  -H "Content-Type: application/json" \
  -d '{"task": "easy"}'

2. Apply a cleaning operation

curl -X POST http://localhost:8000/step \
  -H "Content-Type: application/json" \
  -d '{"action": {"operation": "impute_mean"}}'

3. Get current state

curl http://localhost:8000/state

4. Score the episode

curl -X POST http://localhost:8000/grader

5. Run baseline on all tasks

curl -X POST http://localhost:8000/baseline

---

Setup

Run locally

uv run server
# or
uvicorn server.app:app --reload --host 0.0.0.0 --port 8000

Run with Docker

docker build -t data-cleaning-env:latest -f server/Dockerfile .
docker run -p 8000:8000 data-cleaning-env:latest

Deploy to Hugging Face Spaces

openenv push --repo-id your-username/data-cleaning-env

---

Project Structure

data_cleaning_env/
├── README.md                          # This file
├── openenv.yaml                       # OpenEnv manifest
├── pyproject.toml                     # Project metadata & dependencies
├── uv.lock                            # Locked dependencies
├── models.py                          # Action + Observation Pydantic models
├── client.py                          # DataCleaningEnv HTTP/WS client
└── server/
    ├── app.py                         # FastAPI app + /tasks /grader /baseline
    ├── data_cleaning_env_environment.py  # Core environment logic + graders
    └── Dockerfile                     # Container image

---

Dependencies

• openenv-core[core] >= 0.2.2 — OpenEnv runtime
• Python 3.10+
• No external data dependencies — all datasets are generated synthetically at runtime