changes made in readme.md file

README.md

@@ -1,493 +1,705 @@
+# 🧹 CleanifyAI — Data Cleaning OpenEnv
+
+<div align="center">
+
+[![HuggingFace Space](https://img.shields.io/badge/🤗%20HuggingFace-Space-blue)](https://huggingface.co/spaces/cleanify-ai/Data-cleaning)
+[![GitHub](https://img.shields.io/badge/GitHub-ReverseCoder1%2FCleanifyAI-black?logo=github)](https://github.com/ReverseCoder1/CleanifyAI)
+[![OpenEnv](https://img.shields.io/badge/OpenEnv-Compliant-green)](https://huggingface.co/spaces/cleanify-ai/Data-cleaning)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10](https://img.shields.io/badge/Python-3.10-blue?logo=python)](https://python.org)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.104.1-009688?logo=fastapi)](https://fastapi.tiangolo.com)
+
+**A reinforcement-learning environment where AI agents learn to clean real-world messy datasets — step by step.**
+
+*Scaler × OpenEnv Hackathon Submission*
+
+[🚀 Live API](https://thorodin103-data-cleaning-openenv.hf.space) · [📖 Swagger Docs](https://thorodin103-data-cleaning-openenv.hf.space/docs) · [🤗 HuggingFace](https://huggingface.co/spaces/cleanify-ai/Data-cleaning)
+
+</div>
+
 ---
-title: Data Cleaning OpenEnv
-sdk: docker
-tags:
-  - openenv
-  - data-cleaning
-  - reinforcement-learning
-  - agent
-  - real-world
-  - tabular
-  - pandas
----
 
-# 🧹 Data Cleaning OpenEnv
+## 📋 Table of Contents
+
+- [Overview](#-overview)
+- [Project Structure](#-project-structure)
+- [Setup & Installation](#-setup--installation)
+- [Tasks](#-tasks)
+- [Operations Reference](#-operations-reference)
+- [Reward & Scoring System](#-reward--scoring-system)
+- [API Reference](#-api-reference)
+- [Inference Script](#-inference-script)
+- [Data Models](#-data-models)
+- [Datasets](#-datasets)
+- [Troubleshooting](#-troubleshooting)
+- [Baseline Scores](#-baseline-scores)
+- [License](#-license)
+
+---
 
-> *An OpenEnv-compliant environment where AI agents learn to clean messy real-world datasets — step by step, with dense reward signals and sequence-aware penalties.*
+## 🌟 Overview
 
-[![Live Demo](https://img.shields.io/badge/🚀%20Live%20Demo-HF%20Space-blue)](https://thorodin103-data-cleaning.hf.space/ui)
-[![HF Space](https://img.shields.io/badge/🤗%20HuggingFace-Space-yellow)](https://huggingface.co/spaces/thorodin103/Data-cleaning/tree/main)
-[![OpenEnv Valid](https://img.shields.io/badge/openenv%20validate-✅%20passing-brightgreen)](#-openenv-spec-compliance)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Docker](https://img.shields.io/badge/Docker-Ready-blue?logo=docker)](Dockerfile)
+**CleanifyAI** is a fully OpenEnv-compliant environment that challenges AI agents to autonomously clean messy, real-world datasets through a sequence of structured operations. It mimics professional data engineering pipelines and rewards agents that apply operations in the correct, logical order.
 
-| | |
+| Property | Value |
 |---|---|
-| **Live UI** | https://thorodin103-data-cleaning.hf.space/ui |
-| **HF Repository** | https://huggingface.co/spaces/thorodin103/Data-cleaning/tree/main |
-| **API Base** | https://thorodin103-data-cleaning.hf.space |
-| **Validate** | https://thorodin103-data-cleaning.hf.space/validate |
-| **API Docs** | https://thorodin103-data-cleaning.hf.space/docs |
+| **Environment Name** | `data-cleaning-openenv` |
+| **Tasks** | 4 (Easy, Medium, Hard, Expert) |
+| **Operations** | 9 (dedup, fill, dtype fix, outlier removal, rename, validate, finish) |
+| **Scoring** | Weighted multi-component, strictly in `(0, 1)` |
+| **API** | OpenEnv-compliant REST via FastAPI |
+| **Framework** | Python 3.10, FastAPI, Pandas, NumPy |
+| **Inference** | OpenAI-compatible LLM client |
+| **Deployed at** | `https://thorodin103-data-cleaning-openenv.hf.space` |
+
+> ⚠️ **Score Constraint**: The Scaler platform rejects scores of exactly `0.0` or `1.0`. All scoring paths in this codebase clamp strictly to `(0.0001, 0.9999)`.
+
+---
+
+## 📁 Project Structure
+
+```
+CleanifyAI/
+│
+├── inference.py                  # 🤖 LLM agent — emits [START]/[STEP]/[END] stdout lines
+├── environment.py                # 🏋️ Core OpenEnv environment & reward computation
+├── models.py                     # 📦 Pydantic models: Action, Observation, Reward, StepResult
+├── main.py                       # 🌐 FastAPI server with all REST endpoints
+├── Dockerfile                    # 🐳 Python 3.10-slim container, port 7860
+├── openenv.yaml                  # 📄 OpenEnv spec manifest
+├── pyproject.toml                # 📦 Python dependency config
+├── uv.lock                       # 🔒 Locked dependency versions
+│
+├── datasets/
+│   ├── task_metadata.json        # ⚙️ Per-task config (steps, operations, scoring weights)
+│   ├── easy/
+│   │   ├── dirty.csv             # 🗑️ Employee dataset with duplicates + bad column names
+│   │   └── gold.csv              # ✅ Gold standard cleaned version
+│   ├── medium/
+│   │   ├── dirty.csv             # 🗑️ Customer dataset with missing values + wrong dtypes
+│   │   └── gold.csv              # ✅ Gold standard
+│   ├── hard/
+│   │   ├── dirty.csv             # 🗑️ Orders dataset requiring full pipeline
+│   │   └── gold.csv              # ✅ Gold standard
+│   └── expert/
+│       ├── dirty.csv             # 🗑️ Sales dataset — strict operation order required
+│       └── gold.csv              # ✅ Gold standard
+│
+├── static/
+│   └── index.html                # 🖥️ Web UI for interactive exploration
+│
+└── server/
+    └── app.py                    # 🔧 Server initialization module
+```
 
 ---
 
-## 🌍 Why This Environment Exists
+## 🚀 Setup & Installation
 
-Data engineers and analysts spend **up to 80% of their time cleaning data** before it can be used. Despite being one of the most universal tasks in the real world, no existing OpenEnv benchmark captures it.
+### Prerequisites
 
-This environment fills that gap. An AI agent receives a dirty dataset and must apply a sequence of cleaning operations to match a gold-standard output. What makes it non-trivial:
+- Python 3.10+
+- Docker (for containerized deployment)
+- A Hugging Face account (`HF_TOKEN`)
+- An OpenAI-compatible API endpoint and model
+
+---
+
+### Local Development
+
+**1. Clone the repository**
+```bash
+git clone https://github.com/ReverseCoder1/CleanifyAI.git
+cd CleanifyAI
+```
+
+**2. Install dependencies**
+```bash
+pip install fastapi==0.104.1 uvicorn==0.24.0 pydantic==2.5.0 \
+            pandas==2.1.3 numpy==1.26.2 openai>=2.7.2 \
+            pyyaml==6.0.1 python-dotenv==1.0.0
+```
+
+**3. Create a `.env` file**
+```env
+API_BASE_URL=https://api.openai.com/v1
+MODEL_NAME=gpt-4o-mini
+HF_TOKEN=your_hugging_face_token_here
+```
+
+**4. Start the FastAPI server**
+```bash
+uvicorn main:app --host 0.0.0.0 --port 7860 --reload
+```
+
+- **API:** http://localhost:7860
+- **Swagger UI:** http://localhost:7860/docs
+
+---
+
+### Docker Deployment
+
+```bash
+# Build
+docker build -t cleanify-ai .
+
+# Run
+docker run -p 7860:7860 \
+  -e HF_TOKEN=your_token \
+  -e MODEL_NAME=gpt-4o-mini \
+  -e API_BASE_URL=https://api.openai.com/v1 \
+  cleanify-ai
+```
+
+---
+
+### Run the Inference Agent
+
+```bash
+python inference.py
+```
 
-- **Order matters.** Filling missing values before fixing data types produces wrong results — the reward function knows this and penalizes it.
-- **Partial progress is rewarded.** Every action shifts the score, giving RL agents a dense learning signal rather than sparse end-of-episode feedback.
-- **Four difficulty tiers.** From a 3-step deduplication task to a full expert-level sales pipeline requiring case normalization, outlier removal, and schema validation — in the right sequence.
-- **Fully live.** The environment runs on Hugging Face Spaces, passes `openenv validate`, and exposes a REST API any agent can call against right now.
+Runs the LLM agent across all 3 hackathon tasks and streams hackathon-spec log lines to stdout.
 
 ---
 
 ## 🎯 Tasks
 
-| Task ID | Difficulty | Max Steps | Dataset | What the Agent Must Do |
+Four progressively complex tasks. The hackathon evaluates **easy**, **medium**, and **hard**. Expert is available for extended benchmarking.
+
+| Task ID | Difficulty | Max Steps | Key Operations | Scoring |
 |---|---|---|---|---|
-| `easy_dedup_rename` | 🟢 Easy | 10 | Employee records | Remove duplicate rows + rename columns to snake_case |
-| `medium_missing_dtype` | 🟡 Medium | 15 | Customer records | Fill missing values (mean/mode) + fix wrong data types |
-| `hard_full_pipeline` | 🔴 Hard | 20 | Orders data | Full pipeline: dedup → fill → fix types → remove outliers → validate schema |
-| `expert_sales_pipeline` | ⚫ Expert | 25 | Sales transactions | Expert pipeline with case standardization + all of the above, in strict order |
+| `easy_dedup_rename` | ⭐ Easy | 10 | `remove_duplicates`, `rename_columns` | dup 50% + schema 50% |
+| `medium_missing_dtype` | ⭐⭐ Medium | 15 | `fill_missing_*`, `fix_dtype` | missing 50% + dtype 50% |
+| `hard_full_pipeline` | ⭐⭐⭐ Hard | 20 | Full pipeline | 20% × 5 components |
+| `expert_sales_pipeline` | ⭐⭐⭐⭐ Expert | 25 | All 9 ops in strict order | Weighted (schema 25%) |
 
 ---
 
-### Task 1 — Easy: Deduplicate & Rename (`easy_dedup_rename`)
+### ⭐ Easy — `easy_dedup_rename`
+
+**Dataset:** Employee records (`emp_id`, `emp_name`, `dept`, `salary`, `age`)
 
-The agent receives an employee dataset with duplicate rows and column names like `EMP ID`, `DEP T`, `SAL ARY`. It must remove the duplicates and rename all columns to `snake_case`.
+**Dirty conditions:**
+- Duplicate rows
+- Column names with spaces and inconsistent casing (`EMP ID`, `DEP T`, `SAL ARY`)
 
-**Dirty dataset sample:**
+**Optimal sequence:**
 ```
-EMP ID | EMP NAME | DEP T   | SAL ARY | AGE
-101    | Alice    | HR      | 50000   | 28
-102    | Bob      | IT      | 60000   | 35
-102    | Bob      | IT      | 60000   | 35   ← duplicate
-103    | Charlie  | IT      | 55000   | 29
-103    | Charlie  | IT      | 55000   | 29   ← duplicate
+remove_duplicates → rename_columns → finish
 ```
 
-**Scoring:**
-- `duplicate_score` (0.5) — how close row count is to gold
-- `schema_score` (0.5) — proportion of column names matching gold
-
-**Optimal actions:** `remove_duplicates` → `rename_columns` → `finish` (3 steps, score = 0.99)
+**Scoring:** `duplicate_score × 0.5 + schema_score × 0.5`
 
 ---
 
-### Task 2 — Medium: Missing Values & Types (`medium_missing_dtype`)
+### ⭐⭐ Medium — `medium_missing_dtype`
 
-The agent receives a customer dataset where numeric columns like `age`, `purchases`, and `salary` contain missing values and are stored as the wrong type (strings instead of numbers).
+**Dataset:** Customer records (`customer_id`, `age`, `salary`, `gender`, `purchases`, `region`, `joined_date`)
 
-**Issues present:**
-- `age` column: 2 missing values, stored as `object` dtype
-- `purchases` column: 3 missing values
-- `salary` column: stored as string, needs numeric conversion
+**Dirty conditions:**
+- NaN values in `age`, `salary`, `gender`, `region`
+- `salary` stored as `object` instead of `float`
 
-**Scoring:**
-- `missing_score` (0.5) — proportion of missing values correctly filled
-- `dtype_score` (0.5) — proportion of columns with correct data types
+**Optimal sequence:**
+```
+fill_missing_mean  (numeric columns)
+fill_missing_mode  (categorical columns)
+fix_dtype          → finish
+```
 
-**Key challenge:** The agent must fix types *before* filling missing values with mean/median — doing it backwards triggers a sequence penalty.
+**Scoring:** `missing_score × 0.5 + dtype_score × 0.5`
 
 ---
 
-### Task 3 — Hard: Full Pipeline (`hard_full_pipeline`)
+### ⭐⭐⭐ Hard — `hard_full_pipeline`
 
-The agent receives an orders dataset with all classes of data quality issues simultaneously. Must execute the full cleaning pipeline in the correct sequence.
+**Dataset:** Orders (`order_id`, `product`, `quantity`, `price`, `customer_id`, `status`, `order_date`, `rating`)
 
-**Issues present:**
-- Duplicate order IDs
-- Missing values in `quantity`, `product`, and `rating` columns
-- `quantity` and `price` stored as wrong types
-- Extreme outliers (e.g., `quantity=999`, `price=99999`)
-- Column names not matching gold schema
+**Dirty conditions:**
+- Duplicate order entries
+- Missing `quantity` and `price` values
+- `quantity` stored as object type
+- Extreme price outliers
 
-**Scoring:** All 5 components weighted equally at 0.2 each:
-`duplicate_score + missing_score + dtype_score + outlier_score + schema_score`
+**Optimal sequence:**
+```
+remove_duplicates → fill_missing_* → fix_dtype → remove_outliers → validate_schema → finish
+```
 
-**Why it's hard:** The agent must not only apply all 5 operations but apply them in the correct order. Doing `fill_missing` before `remove_duplicates` incurs a -0.08 penalty. Doing `remove_outliers` before `fix_dtype` incurs another. Penalties compound.
+**Scoring:** `duplicate × 0.2 + missing × 0.2 + dtype × 0.2 + outlier × 0.2 + schema × 0.2`
 
 ---
 
-### Task 4 — Expert: Sales Pipeline (`expert_sales_pipeline`)
+### ⭐⭐⭐⭐ Expert — `expert_sales_pipeline`
+
+**Dataset:** Sales transactions — highest complexity, penalises out-of-order operations heavily.
+
+**Optimal sequence (strictly enforced):**
+```
+remove_duplicates → rename_columns → fill_missing_mode → fix_dtype → remove_outliers → validate_schema → finish
+```
+
+**Scoring:** `duplicate × 0.15 + missing × 0.20 + dtype × 0.20 + outlier × 0.20 + schema × 0.25`
 
-The hardest task. A sales transaction dataset with messy region names (`north`, `EAST`, `South` — all meaning the same thing), missing sales reps and commission values, mixed column naming conventions, and outlier transactions.
+---
 
-**Issues present:**
-- Duplicate transactions
-- Mixed-case region names requiring standardization
-- Missing `SALES REP` and `COMMISSION %` values
-- Inconsistent column naming (`Transaction_ID`, `SALES REP`, `Sale Amount` — all need snake_case)
-- Outlier transactions in `Sale Amount` and `Units Sold`
+## 🔧 Operations Reference
 
-**Scoring:**
-- `duplicate_score` (0.15), `missing_score` (0.20), `dtype_score` (0.20), `outlier_score` (0.20), `schema_score` (0.25)
+All operations are invoked via JSON actions sent to `POST /step/{task_id}`.
 
-**Total max steps: 25** — the most complex episode in the environment.
+### `remove_duplicates`
+```json
+{"operation": "remove_duplicates", "parameters": {}}
+```
+Drops exact duplicate rows using `pandas.drop_duplicates()`. Resets the index after removal.
+- Optional parameter: `"subset": ["col1", "col2"]` — deduplicate on specific columns only
 
 ---
 
-## 👁️ Observation Space
+### `fill_missing_mean`
+```json
+{"operation": "fill_missing_mean", "parameters": {}}
+```
+Fills NaN values in numeric columns with the column mean. Skips non-numeric columns to avoid type errors.
+- Optional parameter: `"column": "col_name"` — target a single column
 
-At every step, the agent receives a structured observation describing the current state of the dataset:
+---
 
+### `fill_missing_mode`
 ```json
-{
-  "task_id":              "easy_dedup_rename",
-  "step":                 1,
-  "dataset_info": {
-    "total_rows":         8,
-    "total_columns":      5,
-    "has_duplicates":     true,
-    "has_missing":        false
-  },
-  "columns":              ["EMP ID", "EMP NAME", "DEP T", "SAL ARY", "AGE"],
-  "shape":                [8, 5],
-  "missing_values":       {"EMP ID": 0, "EMP NAME": 0, "DEP T": 0, "SAL ARY": 0, "AGE": 0},
-  "dtypes":               {"EMP ID": "int64", "EMP NAME": "object", "DEP T": "object", "SAL ARY": "int64", "AGE": "int64"},
-  "duplicate_count":      2,
-  "sample_rows": [
-    {"EMP ID": 101, "EMP NAME": "Alice", "DEP T": "HR", "SAL ARY": 50000, "AGE": 28},
-    {"EMP ID": 102, "EMP NAME": "Bob",   "DEP T": "IT", "SAL ARY": 60000, "AGE": 35},
-    {"EMP ID": 102, "EMP NAME": "Bob",   "DEP T": "IT", "SAL ARY": 60000, "AGE": 35}
-  ],
-  "available_operations": ["remove_duplicates", "rename_columns", "finish"],
-  "task_description":     "Remove duplicate rows and rename columns to snake_case in an employee dataset.",
-  "message":              "Environment reset. Start cleaning!"
-}
+{"operation": "fill_missing_mode", "parameters": {}}
 ```
+Fills NaN values with the most frequent value (mode). Works for both numeric and categorical columns.
+- Optional parameter: `"column": "col_name"`
 
-**What's hidden from the agent:** the gold-standard dataset. The agent only sees the dirty data and its own progress metrics.
+---
+
+### `fill_missing_median`
+```json
+{"operation": "fill_missing_median", "parameters": {}}
+```
+Fills NaN values in numeric columns with the column median. More robust to outliers than mean.
+- Optional parameter: `"column": "col_name"`
 
 ---
 
-## ⚡ Action Space
+### `fix_dtype`
+```json
+{"operation": "fix_dtype", "parameters": {"dtype": "auto"}}
+```
+Attempts to convert columns to the most appropriate type.
+- `"dtype": "auto"` — tries `int` then `float`, skips if conversion fails
+- `"dtype": "int"` — convert to integer
+- `"dtype": "float"` — convert to float
+- `"dtype": "str"` — convert to string
+- Optional parameter: `"column": "col_name"`
 
-Actions are JSON objects with an `operation` and optional `parameters`:
+---
 
+### `remove_outliers`
 ```json
-{
-  "operation": "fill_missing",
-  "parameters": {
-    "column":   "age",
-    "strategy": "mean"
-  }
-}
+{"operation": "remove_outliers", "parameters": {"method": "iqr"}}
 ```
+Removes rows where numeric values fall outside the outlier fence.
+- `"method": "iqr"` — IQR method: removes values outside `[Q1 − 1.5×IQR, Q3 + 1.5×IQR]`
+- `"method": "zscore"` — Z-score method: removes values beyond ±3σ
+- Optional parameter: `"column": "col_name"` — target a single numeric column
 
-| Operation | Parameters | Description |
-|---|---|---|
-| `remove_duplicates` | `subset` (optional list of columns) | Drop duplicate rows |
-| `fill_missing` | `column` (optional), `strategy`: `mean`/`median`/`mode`/`ffill` | Fill NaN values |
-| `fix_dtype` | `column` (optional), `dtype`: `int`/`float`/`str`/`auto` | Cast column types |
-| `remove_outliers` | `column` (optional), `method`: `iqr`/`zscore` | Remove statistical outliers |
-| `rename_columns` | `mapping` (optional dict, auto snake_case if omitted) | Rename column headers |
-| `validate_schema` | — | Check columns against gold standard, returns feedback |
-| `finish` | — | End the episode and lock in the final score |
+---
+
+### `rename_columns`
+```json
+{"operation": "rename_columns", "parameters": {}}
+```
+Auto-renames all columns to `snake_case` (lowercase, spaces → underscores).
+- Optional parameter: `"mapping": {"Old Name": "new_name"}` — explicit rename map
 
 ---
 
-## 🏆 Reward Function
+### `validate_schema`
+```json
+{"operation": "validate_schema", "parameters": {}}
+```
+Compares current column names against the gold dataset schema.
+- Returns missing columns (in gold but not current)
+- Returns extra columns (in current but not in gold)
+- Returns a success message if schemas match perfectly
 
-Rewards are computed **after every action** — dense signal at every step, not just at episode end.
+---
 
-### Components
+### `finish`
+```json
+{"operation": "finish", "parameters": {}}
+```
+Signals the agent is done. Triggers final reward computation and ends the episode immediately. **Always call this when cleaning is complete.**
 
-| Component | Formula | Weight (hard task) |
-|---|---|---|
-| `duplicate_score` | `min(1, gold_rows / curr_rows)` | 0.20 |
-| `missing_score` | `filled_so_far / total_needed` | 0.20 |
-| `dtype_score` | `matching_dtypes / total_columns` | 0.20 |
-| `outlier_score` | `1 − outlier_rows / total_rows` | 0.20 |
-| `schema_score` | `matching_cols / gold_cols` | 0.20 |
-| `penalty` | sequence + step violations (subtracted) | — |
+---
 
-**Total reward = weighted component sum − penalties, clamped to [0.0, 1.0]**
+## 📊 Reward & Scoring System
 
-### The Sequence-Penalty Mechanic
+Reward is computed after every step and returned as a `Reward` object. The total is a weighted sum of components minus penalties, **clamped strictly to `(0.0001, 0.9999)`**.
 
-This is the environment's core design innovation. The optimal cleaning sequence is:
+### Score Components
 
+| Component | What It Measures | How It's Calculated |
+|---|---|---|
+| `duplicate_score` | Row count vs gold dataset | Proportional to excess/deficit rows |
+| `missing_score` | Missing values filled vs gold | Fraction of needed fills completed |
+| `dtype_score` | Column types match gold | Matched columns ÷ total columns |
+| `outlier_score` | Numeric values within 3σ of gold mean | Per-column average, then mean across columns |
+| `schema_score` | Column names match gold schema | Matched column names ÷ gold column count |
+| `penalty` | Step efficiency + operation order | See sequence penalty below |
+
+---
+
+### Sequence Penalty
+
+The optimal operation order is:
 ```
-1. remove_duplicates   → clean redundant data first
-2. fix_dtype           → establish correct column types
-3. fill_missing        → impute based on correct types
-4. remove_outliers     → after type-correct distributions
-5. validate_schema     → final check
+remove_duplicates → fix_dtype → fill_missing_* → remove_outliers → validate_schema
 ```
 
-Violations are penalized:
+Penalties for deviations:
 
 | Violation | Penalty |
 |---|---|
-| Out-of-order operation (e.g., `fill_missing` before `fix_dtype`) | −0.08 |
-| Repeated identical operation back-to-back | −0.02 |
-| Exceeding 80% of the step budget | −0.05 |
-| Total penalty cap | 0.25 |
+| Out-of-order operation | −0.08 |
+| Repeated operation (non-fill/outlier) | −0.02 |
+| Unknown operation | −0.01 |
+| Using >80% of allowed steps | −0.05 |
+| **Maximum total penalty** | **−0.25** |
+
+---
 
-**Why this matters for agent training:** An agent that randomly applies operations will peak early then watch its score decay as penalties accumulate. This forces the agent to learn the *why* behind the sequence, not just the *what*.
+### Score Clamping (Critical)
 
-From the baseline run on the hard task — the agent peaks at **0.885** on step 5 then degrades to **0.664** by step 20 by looping between `remove_outliers` and `fix_dtype` in a penalty-accumulating cycle. This is a real learning signal.
+The Scaler grader rejects scores of exactly `0.0` or `1.0`. The following clamping is enforced at every level:
 
----
+```python
+# environment.py — _compute_reward()
+def _sc(v):
+    return round(max(0.0001, min(0.9999, float(v))), 4)
+
+# Applied to ALL Reward fields: total, duplicate_score, missing_score, etc.
+return Reward(
+    total=_sc(total),
+    duplicate_score=_sc(dup_score),
+    ...
+)
+```
+
+```python
+# inference.py — every printed reward
+def _clamp(v: float) -> float:
+    return max(0.01, min(0.99, float(v)))
 
-## 📊 Baseline Scores
+# [STEP] and [END] lines both use _clamp() before formatting
+```
 
-Baseline agent: **GPT-4o-mini** via OpenAI API, temperature 0.1.
+---
 
-| Task | Difficulty | Final Score | Steps Used | Notes |
-|---|---|---|---|---|
-| `easy_dedup_rename` | 🟢 Easy | **0.99** | 3 / 10 | Near-perfect — follows optimal sequence |
-| `medium_missing_dtype` | 🟡 Medium | **0.70** | 15 / 15 | Hits step limit, oscillates on dtype/fill |
-| `hard_full_pipeline` | 🔴 Hard | **0.6636** | 20 / 20 | Peaks at 0.885 then degrades from looping |
-| `expert_sales_pipeline` | ⚫ Expert | **~0.55** | ~20 / 25 | Case normalization is the main challenge |
-| **Average** | — | **~0.75** | — | Significant room for better agents |
+## 🌐 API Reference
 
-The gap between easy (0.99) and hard (0.66) demonstrates genuine difficulty scaling. The hard task's reward degradation curve is directly caused by sequence violations — a smarter agent that plans its sequence upfront would score 0.88+.
+**Base URL:** `https://thorodin103-data-cleaning-openenv.hf.space`
+
+| Method | Endpoint | Description |
+|---|---|---|
+| `POST` | `/reset` | Reset environment (body: `{"task_id": "..."}`) |
+| `POST` | `/reset/{task_id}` | Reset specific task environment |
+| `POST` | `/step` | Take action (body: `{"task_id": "...", "operation": "...", "parameters": {}}`) |
+| `POST` | `/step/{task_id}` | Take action in specific task |
+| `GET` | `/state` | Get current environment state |
+| `GET` | `/state/{task_id}` | Get state for specific task |
+| `GET` | `/tasks` | List all tasks with full metadata |
+| `GET` | `/validate` | Run OpenEnv spec validation across all tasks |
+| `GET` | `/health` | Health check |
+| `GET` | `/docs` | Interactive Swagger UI |
+| `POST` | `/leaderboard/submit` | Submit a score entry |
+| `GET` | `/leaderboard` | Get current leaderboard rankings |
 
 ---
 
-## 🔌 API Reference
+### Example: Reset a task
+```bash
+curl -X POST https://thorodin103-data-cleaning-openenv.hf.space/reset/easy_dedup_rename
+```
+```json
+{
+  "observation": {
+    "task_id": "easy_dedup_rename",
+    "step": 0,
+    "columns": ["EMP ID", "EMP NAME", "DEP T", "SAL ARY", "AGE"],
+    "duplicate_count": 5,
+    "missing_values": {"EMP ID": 0, "EMP NAME": 0, ...},
+    "message": "Environment reset. Start cleaning!"
+  },
+  "reward": {"total": 0.0001},
+  "done": false
+}
+```
 
-The environment runs as a live REST API. All endpoints are accessible now:
+---
 
+### Example: Take a step
+```bash
+curl -X POST https://thorodin103-data-cleaning-openenv.hf.space/step/easy_dedup_rename \
+  -H "Content-Type: application/json" \
+  -d '{"operation": "remove_duplicates", "parameters": {}}'
 ```
-Base URL: https://thorodin103-data-cleaning.hf.space
+```json
+{
+  "observation": {"step": 1, "duplicate_count": 0, "message": "Removed 5 duplicate rows. Rows: 20 -> 15"},
+  "reward": {"total": 0.4821, "duplicate_score": 0.9999, "schema_score": 0.0001},
+  "done": false
+}
 ```
 
-| Method | Endpoint | Description |
-|---|---|---|
-| `GET` | `/health` | Health check — returns `{"status": "ok"}` |
-| `GET` | `/tasks` | List all 4 tasks with metadata |
-| `POST` | `/reset/{task_id}` | Reset environment, returns initial observation |
-| `POST` | `/step/{task_id}` | Submit action, returns observation + reward + done |
-| `GET` | `/state/{task_id}` | Current internal state (for debugging) |
-| `GET` | `/validate` | OpenEnv compliance check — all 4 tasks pass |
-| `GET` | `/leaderboard` | View agent rankings |
-| `GET` | `/docs` | Interactive Swagger UI |
-| `GET` | `/ui` | Live browser demo |
+---
 
-**Live validate response (confirmed passing):**
+### Example: Validate the environment
+```bash
+curl https://thorodin103-data-cleaning-openenv.hf.space/validate
+```
 ```json
 {
   "openenv_valid": true,
   "tasks": {
-    "easy_dedup_rename":     {"status": "passed", "reset": "ok", "step": "ok", "state": "ok"},
-    "medium_missing_dtype":  {"status": "passed", "reset": "ok", "step": "ok", "state": "ok"},
-    "hard_full_pipeline":    {"status": "passed", "reset": "ok", "step": "ok", "state": "ok"},
-    "expert_sales_pipeline": {"status": "passed", "reset": "ok", "step": "ok", "state": "ok"}
+    "easy_dedup_rename":    {"status": "passed"},
+    "medium_missing_dtype": {"status": "passed"},
+    "hard_full_pipeline":   {"status": "passed"},
+    "expert_sales_pipeline":{"status": "passed"}
   }
 }
 ```
 
 ---
 
-## 🚀 Setup & Usage
-
-### Option 1 — Use the live API (no setup needed)
+## 🤖 Inference Script
 
-```python
-import requests
+`inference.py` is the hackathon submission entry point. It runs an LLM agent across all tasks and emits structured stdout lines that the platform parser reads.
 
-BASE = "https://thorodin103-data-cleaning.hf.space"
+### Required Stdout Format
 
-# Reset the hard task
-obs = requests.post(f"{BASE}/reset/hard_full_pipeline").json()
-print(obs["observation"]["duplicate_count"])  # → 3
+> The format below is **mandatory**. The platform parser reads these exact line types.
 
-# Take an action
-result = requests.post(f"{BASE}/step/hard_full_pipeline", json={
-    "operation": "remove_duplicates",
-    "parameters": {}
-}).json()
+```
+[START] task=<task_name> env=<benchmark> model=<model_name>
+[STEP]  step=<n> action=<action_str> reward=<0.00> done=<true|false> error=<msg|null>
+[END]   success=<true|false> steps=<n> score=<0.00> rewards=<r1,r2,...,rn>
+```
 
-print(result["reward"]["total"])          # → 0.6955
-print(result["reward"]["duplicate_score"]) # → 1.0
-print(result["done"])                      # → False
+**Rules:**
+- One `[START]` line at episode begin
+- One `[STEP]` line per step, immediately after `env.step()` returns
+- One `[END]` line after episode end — **always emitted, even on exception** (via `finally` block)
+- `reward` and `rewards` formatted to **2 decimal places**
+- `done` and `success` are lowercase: `true` or `false`
+- `score=` field in `[END]` is **mandatory** — its absence causes Task Validation failure
+- `error` is the raw error string, or `null` if none
 
-# Get state
-state = requests.get(f"{BASE}/state/hard_full_pipeline").json()
+**Example output:**
+```
+[START] task=easy_dedup_rename env=data-cleaning-openenv model=gpt-4o-mini
+[STEP] step=1 action=remove_duplicates reward=0.48 done=false error=null
+[STEP] step=2 action=rename_columns reward=0.96 done=false error=null
+[STEP] step=3 action=finish reward=0.96 done=true error=null
+[END] success=true steps=3 score=0.96 rewards=0.48,0.96,0.96
 ```
 
-### Option 2 — Run locally with Docker
+---
 
-```bash
-git clone https://huggingface.co/spaces/thorodin103/Data-cleaning
-cd Data-cleaning
+### Agent Loop
 
-docker build -t data-cleaning-openenv .
-docker run -p 7860:7860 data-cleaning-openenv
+For each task the agent follows this loop:
 
-# Environment now live at http://localhost:7860
-# UI at http://localhost:7860/ui
-```
+1. Call `env.reset()` to initialise the episode
+2. Build a prompt from the observation (shape, columns, missing values, dtypes, sample rows)
+3. Send prompt to LLM via OpenAI-compatible client
+4. Parse the JSON response into an `Action`
+5. Call `env.step(action)` and record the reward
+6. Emit a `[STEP]` line
+7. Repeat until `done=true` or `MAX_STEPS` (20) reached
+8. Compute `score = average(rewards)`, clamped to `(0, 1)`
+9. Emit `[END]` line via `finally` block
 
-### Option 3 — Run locally without Docker
+---
 
-```bash
-pip install fastapi uvicorn pydantic pandas numpy openai python-dotenv
+### Environment Variables
 
-uvicorn main:app --host 0.0.0.0 --port 7860 --reload
+| Variable | Default | Description |
+|---|---|---|
+| `API_BASE_URL` | `https://api.openai.com/v1` | OpenAI-compatible API endpoint |
+| `MODEL_NAME` | `gpt-4o-mini` | Model identifier |
+| `HF_TOKEN` | *(required)* | Hugging Face / API key |
+
+---
+
+## 📦 Data Models
+
+### `Action`
+```json
+{
+  "operation": "remove_duplicates",
+  "parameters": {}
+}
 ```
+- `operation` — one of the 9 valid operations
+- `parameters` — operation-specific options (`column`, `strategy`, `method`, `dtype`, `mapping`, `subset`)
 
-### Option 4 — Run the baseline inference script
+---
 
-```bash
-export OPENAI_API_KEY=your_key_here
-export MODEL_NAME=gpt-4o-mini
-export API_BASE_URL=https://api.openai.com/v1
-export HF_TOKEN=your_hf_token
+### `Observation`
+```json
+{
+  "task_id": "easy_dedup_rename",
+  "step": 1,
+  "dataset_info": {"total_rows": 15, "has_duplicates": false, "has_missing": false},
+  "columns": ["emp_id", "emp_name", "dept", "salary", "age"],
+  "shape": [15, 5],
+  "missing_values": {"emp_id": 0, "emp_name": 0},
+  "dtypes": {"emp_id": "int64", "emp_name": "object"},
+  "duplicate_count": 0,
+  "sample_rows": [{"emp_id": 101, "emp_name": "Alice", ...}],
+  "available_operations": ["remove_duplicates", "rename_columns", "finish"],
+  "task_description": "Clean an employee dataset by...",
+  "message": "Removed 5 duplicate rows."
+}
+```
 
-python inference.py
-# Runs all 3 core tasks, prints [START] / [STEP] / [END] trace
-# Saves results to baseline_results.json
+---
+
+### `Reward`
+```json
+{
+  "total": 0.4821,
+  "duplicate_score": 0.9999,
+  "missing_score": 0.0001,
+  "dtype_score": 0.0001,
+  "outlier_score": 0.0001,
+  "schema_score": 0.0001,
+  "penalty": 0.0
+}
 ```
+All values are clamped to `(0.0001, 0.9999)`.
 
 ---
 
-## 💻 Programmatic Usage (Python)
+### `StepResult`
+```json
+{
+  "observation": { ... },
+  "reward": { ... },
+  "done": false,
+  "info": {
+    "step": 1,
+    "operation": "remove_duplicates",
+    "reward_history": [0.4821]
+  }
+}
+```
 
-```python
-from environment import DataCleaningEnv
-from models import Action
+---
 
-# Initialize any task
-env = DataCleaningEnv(task_id="hard_full_pipeline")
+## 🗃️ Datasets
 
-# Reset — returns StepResult with initial observation
-result = env.reset()
-obs = result.observation
-print(f"Dirty dataset: {obs.shape} with {obs.duplicate_count} duplicates")
-# → Dirty dataset: [20, 8] with 3 duplicates
+Each task has a paired `dirty.csv` and `gold.csv`. The dirty file is loaded at reset; the gold file is used as the scoring reference throughout the episode.
 
-# Optimal sequence for the hard task
-actions = [
-    Action(operation="remove_duplicates", parameters={}),
-    Action(operation="fix_dtype",         parameters={"dtype": "auto"}),
-    Action(operation="fill_missing",      parameters={"strategy": "mean"}),
-    Action(operation="remove_outliers",   parameters={"method": "iqr"}),
-    Action(operation="validate_schema",   parameters={}),
-    Action(operation="finish",            parameters={}),
-]
+### Easy — Employee Dataset
+| Property | Value |
+|---|---|
+| Dirty columns | `EMP ID`, `EMP NAME`, `DEP T`, `SAL ARY`, `AGE` |
+| Gold columns | `emp_id`, `emp_name`, `dept`, `salary`, `age` |
+| Issues | Duplicate rows, space-separated column names |
+| Rows | ~20 dirty → ~15 gold after dedup |
 
-for action in actions:
-    result = env.step(action)
-    print(f"{action.operation:20s} → reward: {result.reward.total:.4f}")
+### Medium — Customer Dataset
+| Property | Value |
+|---|---|
+| Columns | `customer_id`, `age`, `salary`, `gender`, `purchases`, `region`, `joined_date` |
+| Issues | NaN in `age`, `salary`, `gender`, `region`; `salary` as `object` instead of `float` |
+| Rows | ~30, no duplicates |
 
-# → remove_duplicates    → reward: 0.6955
-# → fix_dtype            → reward: 0.8235
-# → fill_missing         → reward: 0.8852 (no penalty — correct order)
-# → remove_outliers      → reward: 0.9800
-# → validate_schema      → reward: 0.9800
-# → finish               → reward: 0.9800
+### Hard — Orders Dataset
+| Property | Value |
+|---|---|
+| Columns | `order_id`, `product`, `quantity`, `price`, `customer_id`, `status`, `order_date`, `rating` |
+| Issues | Duplicate orders, missing `quantity`/`price`, wrong dtypes, price outliers |
+| Rows | ~50 dirty, full pipeline required |
 
-# Full state inspection
-state = env.state()
-print(state["reward_history"])
-# → [0.6955, 0.8235, 0.8852, 0.9800, 0.9800, 0.9800]
-```
+### Expert — Sales Dataset
+| Property | Value |
+|---|---|
+| Issues | All of the above plus column naming problems |
+| Unique challenge | Operations must be applied in strict optimal order — out-of-order is penalised −0.08 per violation |
 
 ---
 
-## 🧪 OpenEnv Spec Compliance
+## 🛠️ Troubleshooting
 
-All four required interface methods are implemented:
+### ❌ Phase 2 Task Validation: "score out of range"
 
-| Method | Signature | Returns |
-|---|---|---|
-| `reset()` | `env.reset()` | `StepResult` (obs + reward + done + info) |
-| `step(action)` | `env.step(Action)` | `StepResult` |
-| `state()` | `env.state()` | `Dict` with full internal state |
-| *(validation)* | `GET /validate` | `{"openenv_valid": true, ...}` |
+The Scaler platform rejects any score that is exactly `0.0` or `1.0`.
 
-All models are strict Pydantic v2:
+- **`environment.py`** — all `Reward` fields must go through `_sc()` clamping at return
+- **`inference.py`** — `[END]` line must include `score=` field; all rewards via `_clamp()`
+- **`inference.py`** — fallback/exception reward must be `0.01`, not `0.0`
+- **Format** — use `:.2f` (per spec), not `:.4f`
 
-```python
-class Action(BaseModel):
-    operation:  str
-    parameters: Dict[str, Any] = {}
-
-class Observation(BaseModel):
-    task_id, step, dataset_info, columns, shape,
-    missing_values, dtypes, duplicate_count,
-    sample_rows, available_operations,
-    task_description, message
+---
 
-class Reward(BaseModel):
-    total, duplicate_score, missing_score,
-    dtype_score, outlier_score, schema_score, penalty
+### ❌ Output Parsing failure
 
-class StepResult(BaseModel):
-    observation: Observation
-    reward:      Reward
-    done:        bool
-    info:        Dict
-```
+- Ensure `[START]`, `[STEP]`, `[END]` lines use `flush=True`
+- No newlines within a single log line
+- `done` and `success` must be lowercase `true`/`false`
+- `[END]` must include the `score=` field — this is the most common cause of Task Validation failure
 
 ---
 
-## 📁 Project Structure
+### ❌ Environment not initialized error
 
-```
-Data-cleaning/
-├── main.py                  # FastAPI server — all REST endpoints
-├── environment.py           # DataCleaningEnv — reset/step/state + all ops
-├── models.py                # Pydantic models — Action/Observation/Reward/StepResult
-├── inference.py             # Baseline LLM agent — runs all tasks, outputs traces
-├── openenv.yaml             # OpenEnv metadata — tasks, spaces, API config
-├── Dockerfile               # Single-stage Python 3.10 container, port 7860
-├── README.md                # This file
-├── baseline_results.json    # Pre-run baseline scores (gpt-4o-mini)
-└── datasets/
-    ├── task_metadata.json   # Task configs, allowed ops, scoring weights
-    ├── easy/
-    │   ├── dirty.csv        # Employee dataset with duplicates + bad column names
-    │   └── gold.csv         # Ground truth
-    ├── medium/
-    │   ├── dirty.csv        # Customer dataset with missing values + wrong types
-    │   └── gold.csv
-    ├── hard/
-    │   ├── dirty.csv        # Orders dataset with all issue types
-    │   └── gold.csv
-    └── expert/
-        ├── dirty.csv        # Sales data with case normalization + full pipeline
-        └── gold.csv
-```
+- Always call `POST /reset/{task_id}` before `POST /step/{task_id}`
+- Each `task_id` has its own independent environment instance
 
 ---
 
-## 🔬 Research Applications
+### ❌ LLM returns invalid JSON
 
-This environment can be used to study:
+`parse_action()` handles these cases automatically:
+- Strips markdown code fences (` ```json ` and ` ``` `)
+- Falls back to regex `{...}` extraction
+- Default fallback: `{"operation": "finish", "parameters": {}}`
 
-- **Sequence learning in RL** — Can agents learn optimal operation ordering from reward signals alone?
-- **Dense vs. sparse rewards** — Compare agent performance with/without the sequence penalties disabled
-- **Tool use planning** — Does the agent build a plan before acting, or does it react greedily?
-- **Generalization** — Train on easy/medium tasks, evaluate zero-shot on expert
-- **LLM agent benchmarking** — Evaluate frontier models on a deterministic, math-graded task with no LLM-judge subjectivity
+If the model consistently fails, try increasing `MAX_TOKENS` in `inference.py`.
 
 ---
 
-## 🔗 Links
+## 📈 Baseline Scores
 
-| Resource | URL |
+Baseline agent: **gpt-4o-mini** (from `openenv.yaml`)
+
+| Task | Score |
 |---|---|
-| 🚀 Live Demo (UI) | https://thorodin103-data-cleaning.hf.space/ui |
-| 🤗 HuggingFace Space | https://huggingface.co/spaces/thorodin103/Data-cleaning/tree/main |
-| ✅ OpenEnv Validate | https://thorodin103-data-cleaning.hf.space/validate |
-| 📖 API Docs (Swagger) | https://thorodin103-data-cleaning.hf.space/docs |
-| 📋 Task List | https://thorodin103-data-cleaning.hf.space/tasks |
-| 🏅 Leaderboard | https://thorodin103-data-cleaning.hf.space/leaderboard |
+| `easy_dedup_rename` | **0.9900** |
+| `medium_missing_dtype` | **0.7000** |
+| `hard_full_pipeline` | **0.6636** |
+| **Average** | **0.7845** |
 
 ---
 
-## 📜 License
+## 📄 License
 
-MIT — free for research and commercial use.
+MIT License — free to use, modify, and distribute.
 
 ---
 
-*Built for the OpenEnv Hackathon. Powered by FastAPI + Pandas + Pydantic + Hugging Face Spaces.*
+<div align="center">
+
+Built for the **Scaler × OpenEnv Hackathon**
+
+🔗 [GitHub](https://github.com/ReverseCoder1/CleanifyAI) · [HuggingFace Space](https://huggingface.co/spaces/cleanify-ai/Data-cleaning) · [Live API Docs](https://thorodin103-data-cleaning-openenv.hf.space/docs)
+
+*CleanifyAI — making data clean, one step at a time.*
+
+</div>