fix: add HF Space metadata + full docs

README.md

@@ -1,68 +1,161 @@
-# Data Cleaning & ETL OpenEnv Environment
-
-This environment simulates a real-world data cleaning and ETL pipeline task where an AI agent must clean messy CSV/Excel data through a series of operations. It is designed for training and evaluating reinforcement learning agents on data preparation tasks.
-
-## Motivation
-
-Data cleaning is a common, time-consuming task in data science and analytics. Automating it with AI can save significant time and reduce errors. This environment provides a structured way to train agents to perform typical data cleaning operations: fixing nulls, correcting data types, removing duplicates, normalizing values, merging tables, and more.
-
-## Action and Observation Spaces
-
-### Actions
-Each action is a JSON object with an `operation` field and other fields as needed.
-
-- `fill_nulls`: Fill missing values in a column.
-  - Required: `column`, `strategy` (`mean`, `median`, `mode`, `constant`, `forward_fill`, `backward_fill`)
-  - Optional: `value` (for constant fill)
-- `cast_column`: Change data type.
-  - Required: `column`, `dtype` (`int`, `float`, `str`, `datetime`)
-- `remove_duplicates`: Remove duplicate rows.
-  - Optional: `subset` (list of columns), `keep` (`first`, `last`, `false`)
-- `normalize_values`: Normalize string values.
-  - Required: `column`, `method` (`lower`, `upper`, `regex`)
-  - For regex: `pattern`, `replacement`
-- `filter_outliers`: Remove outliers based on z-score.
-  - Required: `column`, `method` (`zscore`)
-  - Optional: `threshold` (default 3.0)
-- `merge_tables`: Join two tables.
-  - Required: `left_table`, `right_table`, `on`
-  - Optional: `how` (`inner`, `left`, `right`, `outer`), `output_table`
-- `add_derived_column`: Create a new column from an existing one.
-  - Required: `column_name`, `source_column`, `transform` (`year_from_date`, `log1p`, `abs`, `len`, `upper`, `lower`)
-- `submit`: End episode.
-
-### Observations
-Observations provide:
-- Task description and progress (step count, max steps)
-- Current state of tables (head, dtypes, null counts, duplicates, row counts)
-- Reward and done flag
-- Partial score (current grader score)
+---
+title: Dataclean Env
+emoji: 🧹
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+tags:
+  - openenv
+  - data-cleaning
+  - etl
+  - real-world
+  - tabular
+  - data-drift
+  - streaming
+---
+
+# DataClean OpenEnv
+
+A **real-world data cleaning and ETL environment** for AI agent RL training, built on the [OpenEnv](https://meta-pytorch.org/OpenEnv/) framework by Meta-PyTorch and Hugging Face.
+
+Agents learn to fix messy tabular data — filling nulls, normalising inconsistent values, removing duplicates, filtering outliers, performing multi-table ETL joins, and handling **live data drift** (novel: fresh dirty rows injected mid-episode every 5 steps).
+
+---
+
+## Why This Environment
+
+Data cleaning is one of the most common, time-consuming tasks in real data engineering. Every company with a data pipeline does this daily. Training an RL agent on this task has immediate real-world value — unlike game-based environments.
+
+**What makes this different from other OpenEnv submissions:**
+- Task 4 (Data Drift) is genuinely novel — no existing OpenEnv environment simulates live streaming row injection mid-episode
+- Parallel baseline using `concurrent.futures.ThreadPoolExecutor` — all 4 tasks run simultaneously
+- Deterministic graders using seeded dataset generation — perfectly reproducible scores
+- Dense reward signal: reward = grader(new_state) − grader(prev_state) at every step
+
+---
 
 ## Tasks
 
-1. **Easy: Null Fixer**
-   - Fix nulls and data types in a 50-row customer dataset (age as string, salary nulls).
-   - Expected: age integer, salary integer, no nulls.
-   - Max steps: 10
+| Task | Difficulty | Description | Max Steps |
+|------|-----------|-------------|-----------|
+| `task1` | Easy | Fix nulls + dtypes in 50-row customer CSV | 10 |
+| `task2` | Medium | Dedup + normalize strings + fix dates + fill nulls | 20 |
+| `task3` | Hard | Multi-table merge + outlier removal + derived column | 30 |
+| `task4_data_drift` | **Expert** | Live streaming table — 7 dirty rows injected every 5 steps | 40 |
+
+---
+
+## Action Space
+
+Every action is a JSON object with an `operation` field:
+
+```json
+{"operation": "fill_nulls",   "column": "age",          "strategy": "median"}
+{"operation": "cast_column",  "column": "age",           "dtype": "int"}
+{"operation": "remove_duplicates"}
+{"operation": "normalize_values", "column": "country",   "method": "upper"}
+{"operation": "cast_column",  "column": "order_date",    "dtype": "datetime"}
+{"operation": "filter_outliers", "column": "amount",     "method": "iqr", "threshold": 1.5}
+{"operation": "merge_tables", "left_table": "orders",    "right_table": "customers", "on": "customer_id", "output_table": "merged"}
+{"operation": "add_derived_column", "column_name": "order_year", "source_column": "order_date", "transform": "year_from_date", "table_name": "merged"}
+{"operation": "submit"}
+```
+
+## Observation Space
+
+After each `reset()` / `step()` the agent receives:
+
+- `task_id`, `task_description`, `step_count`, `max_steps`, `message`
+- `tables` — dict of `{table_name → JSON string of df.head(10)}`
+- `column_dtypes`, `null_counts`, `duplicate_count`, `row_count`
+- `schema_errors` — list of detected problems to guide the agent
+- `reward`, `done`, `partial_score` — RL signals
+
+---
+
+## Reward Function
 
-2. **Medium: Schema Normalizer**
-   - Clean a 200-row orders dataset: remove duplicates, normalize country names (USA/usa/U.S.A → US), fix date format (YYYY/MM/DD → YYYY-MM-DD), fill null amounts.
-   - Max steps: 20
+```
+step_reward = grader(current_state) − grader(previous_state)   # dense delta signal
+invalid_op  = −0.02                                              # bad operation penalty
+terminal    = final grader score on submit or max_steps
+```
 
-3. **Hard: ETL Pipeline**
-   - Join orders and customers tables (400 orders, 100 customers), remove outliers in amount (z-score >3), add a derived column `year` from date.
-   - Max steps: 30
+Partial credit per sub-dimension. Score range: `[0.0, 1.0]`.
 
-## Setup and Usage
+---
 
-### Local Development
-1. Clone the repository.
-2. Install dependencies: `pip install -r requirements.txt`
-3. Run the server: `uvicorn server.app:app --reload --port 7860`
-4. Interact with the environment using HTTP requests or the OpenEnv client.
+## Baseline Scores (llama-3.3-70b-versatile, seed=42, parallel run)
+
+| Task | Score | Time |
+|------|-------|------|
+| task1 (easy) | 1.0000 | 11.8s |
+| task2 (medium) | 1.0000 | 34.1s |
+| task3 (hard) | 0.8000 | 22.4s |
+| task4_data_drift (expert) | 0.9297 | 26.6s |
+| **mean** | **0.9324** | **34.3s wall** |
+
+All 4 tasks run in parallel — wall time = slowest task, not sum.
+
+---
+
+## Setup & Local Run
 
-### Docker
-Build and run:
 ```bash
-docker build -t dataclean-env ./server
-docker run -p 7860:7860 dataclean-env
+pip install -r requirements.txt
+uvicorn server.app:app --host 0.0.0.0 --port 7860 --reload
+```
+
+```bash
+curl http://localhost:7860/health
+curl http://localhost:7860/tasks
+```
+
+```bash
+export OPENAI_API_KEY=your_key
+export OPENAI_BASE_URL=https://api.groq.com/openai/v1
+export BASELINE_MODEL=llama-3.3-70b-versatile
+python baseline.py
+```
+
+## Docker
+
+```bash
+docker build -t dataclean-env .
+docker run -p 7860:7860 -e OPENAI_API_KEY=your_key dataclean-env
+```
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/reset` | Start new episode |
+| POST | `/step` | Execute one cleaning operation |
+| GET | `/state` | Current episode metadata |
+| GET | `/tasks` | All tasks + action schema |
+| GET | `/grader` | Score current episode state |
+| GET | `/baseline` | Run baseline agent on all tasks |
+| GET | `/health` | Liveness probe |
+| GET | `/docs` | Interactive Swagger UI |
+
+---
+
+## Project Structure
+
+```
+dataCleaningProject/
+├── server/
+│   ├── app.py              # FastAPI server — all endpoints
+│   ├── environment.py      # Core env logic — reset/step/state + drift injection
+│   ├── graders.py          # Deterministic scoring for all 4 tasks
+│   └── dataset_factory.py  # Seeded dirty+expected dataset generation + drift batches
+├── models.py               # Pydantic Action + Observation models
+├── baseline.py             # Parallel baseline (ThreadPoolExecutor, 4 tasks at once)
+├── client.py               # HTTP client
+├── openenv.yaml            # OpenEnv manifest
+├── Dockerfile              # Port 7860, Python 3.11-slim
+└── requirements.txt
+```