yashr2020/opendataclean

OpenDataClean 🧹

A 100% Gymnasium-compatible RL Benchmark built for autonomous AI agents to learn and solve real-world tabular data cleaning tasks.

🚀 Overview

OpenDataClean leverages procedurally generated corruptions on pandas DataFrames to challenge RL agents with infinite varieties of messy datasets. The environment exposes native Gymnasium vector observation spaces (Box) and discrete action spaces (MultiDiscrete), ensuring deep integration with libraries like Stable-Baselines3, alongside a robust FastAPI Session Server out-of-the-box for multi-agent tournament deployments.

🛠 Features

• —✅ Full OpenEnv Spec Compliance: Implements the official specification entirely, including Pydantic-typed data schemas in models.py, step() / reset() / state() endpoints in the FastAPI app, agent-specific graders, and a deployed openenv.yaml schema wrapper.
• —Gymnasium API: Inherits gymnasium.Env, supports standard reset() and 5-tuple step(action) mechanisms.
• —Procedural Generation: Every episode spawns dynamically generated tabular noise (missing cells, duplication, type mismatches, category noise, and formatting corruption) using consistent seeds.
• —Dense Step Evaluator: Computes strict [-0.10, +0.10] incremental mathematical rewards based directly on the positive delta your agent actions apply to the dataset.
• —RESTful Multi-Agent Server: Ready to deploy via Docker, supporting robust /session/ interactions where independent agents can connect and compete on identical parameterized seeded drops.

📊 The Tasks

The benchmark includes three modes testing various pipeline heuristics:

• —Easy: Address missing numerical/categorical values (mean/mode imputation) and purge exact duplicates automatically.
• —Medium: Heavily addresses schema typing: format mismatched object types back to datetime64, normalize chaotic string noise using heuristics, and type-cast corrupted numeric variables safely.
• —Hard: A multi-table relational schema benchmark. Resolve primary-key corruption, scrub missing rows across customers and sales datasets, detect mathematical outlier artifacts natively, and ensure clean table merging.

⚙️ Action Space

The agent controls the environment using an explicit MultiDiscrete numeric action vector corresponding to:

1. 1.drop_duplicates
2. 2.drop_missing_rows
3. 3.fill_missing (strategy: mean | mode)
4. 4.cast_type (target: int | float | str)
5. 5.normalize_category
6. 6.standardize_date
7. 7.remove_outliers
8. 8.select_table (hard task)
9. 9.done (terminate sequence)

📡 Deployment

Built instantly via Docker.

# Build the container locally
docker build -t opendataclean .

# Deploy the 0.0.0.0:8000 tournament API
docker run -p 8000:8000 opendataclean

If making API requests directly, the core endpoints are:

• —POST /reset/{task} — Initialize a clean episode
• —POST /step/{task} — Submit unstructured JSON actions without native gymnasium dependencies
• —POST /session/create — Bind and host a deterministic seed for peer-agent testing