Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,40 @@
+# Dockerfile
+# ─────────────────────────────────────────────
+# Data Cleaning OpenEnv — Container Setup
+# ─────────────────────────────────────────────
+
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PORT=7860
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first (for caching)
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy all project files
+COPY . .
+
+# Expose port
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/ || exit 1
+
+# Run the app
+CMD ["python", "app.py"]

README.md

@@ -1,10 +1,113 @@
----
-title: Data Cleaning Env
-emoji: 🐠
-colorFrom: purple
-colorTo: indigo
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Data Cleaning Environment — OpenEnv
+
+An OpenEnv-compliant environment where an AI agent cleans messy CSV datasets step by step.
+
+## Environment Description
+
+The agent receives a messy CSV dataset and must issue cleaning actions to fix issues like missing values, duplicates, outliers, bad column names, and inconsistent values.
+
+## Action Space
+
+| Action | Parameters | Description |
+|---|---|---|
+| `fill_missing` | column, strategy (mean/median/mode/drop) | Fill null values |
+| `drop_duplicates` | — | Remove duplicate rows |
+| `fix_dtype` | column, target_type (int/float/str) | Convert column dtype |
+| `rename_column` | old_name, new_name | Rename to snake_case |
+| `remove_outliers` | column, method (iqr/zscore) | Remove outlier rows |
+| `standardize_values` | column, mapping (JSON) | Unify inconsistent values |
+| `submit` | — | Finalize and trigger grader |
+
+## Observation Space
+
+| Field | Type | Description |
+|---|---|---|
+| `task_id` | string | Current task identifier |
+| `difficulty` | string | easy / medium / hard |
+| `step` | int | Current step number |
+| `max_steps` | int | Maximum steps allowed |
+| `dataframe` | array | Current dataset as list of dicts |
+| `columns` | array | Column names |
+| `dtypes` | object | Column dtype mapping |
+| `null_counts` | object | Null count per column |
+| `duplicate_rows` | int | Number of duplicate rows |
+| `issues` | array | Detected issues list |
+| `done` | bool | Episode over? |
+
+## Tasks
+
+### Task 1 — Easy (score: 0.0–1.0)
+Fix a 10-row employee dataset:
+- Fill missing values in `age` and `salary`
+- Convert `age` from string to integer
+
+Baseline score: **0.72**
+
+### Task 2 — Medium (score: 0.0–1.0)
+Fix a 20-row dataset:
+- Remove duplicate rows
+- Handle salary outliers (IQR method)
+- Standardize country values → `United States` or `UK`
+
+Baseline score: **0.65**
+
+### Task 3 — Hard (score: 0.0–1.0)
+Fix a 30-row dataset with all issues:
+- Fix bad column names (trailing spaces, uppercase, special chars)
+- Fill missing values, remove duplicates and outliers
+- Standardize country values
+- Fix invalid `dept_id` values (referential integrity)
+
+Baseline score: **0.48**
+
+## Reward Function
+
+| Event | Reward |
+|---|---|
+| Issue fixed | +0.10 |
+| Clean submit bonus | +0.30 |
+| Wrong/redundant action | -0.05 |
+| Destructive action | -0.10 |
+
+## Setup Instructions
+
+### Local
+```bash
+git clone https://huggingface.co/spaces/Yashwanth34567/data-cleaning-env
+cd data-cleaning-env
+pip install -r requirements.txt
+python app.py
+```
+
+### Docker
+```bash
+docker build -t data-cleaning-env .
+docker run -p 7860:7860 data-cleaning-env
+```
+
+### Environment Variables
+```bash
+API_BASE_URL=https://api-inference.huggingface.co/v1
+MODEL_NAME=mistralai/Mistral-7B-Instruct-v0.3
+OPENAI_API_KEY=your_hf_token
+HF_TOKEN=your_hf_token
+```
+
+## Run Inference
+```bash
+python inference.py
+```
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/reset` | POST | Start fresh episode |
+| `/step` | POST | Execute action |
+| `/state` | GET | Current environment state |
+| `/tasks` | GET | List all tasks |
+| `/openenv.yaml` | GET | OpenEnv spec |
+
+## Author
+
+**Yashwanth R (Yashwanth34567)** & **Mohammed Ayaan** — OpenEnv Hackathon × Scaler School of Technology

app.py

@@ -0,0 +1,297 @@
+# app.py
+# ─────────────────────────────────────────────
+# Gradio UI for Data Cleaning Environment
+# Beautiful dashboard with Playfair Display
+# ─────────────────────────────────────────────
+
+import gradio as gr
+import pandas as pd
+import json
+from environment import DataCleaningEnv
+from models import Action
+from config import TASK_EASY, TASK_MEDIUM, TASK_HARD
+
+# ── Global State ──────────────────────────────
+envs = {
+    TASK_EASY:   DataCleaningEnv(TASK_EASY),
+    TASK_MEDIUM: DataCleaningEnv(TASK_MEDIUM),
+    TASK_HARD:   DataCleaningEnv(TASK_HARD),
+}
+current_difficulty = TASK_EASY
+step_logs = {TASK_EASY: [], TASK_MEDIUM: [], TASK_HARD: []}
+
+# ── Helpers ───────────────────────────────────
+
+def get_env():
+    return envs[current_difficulty]
+
+def df_to_html(df: pd.DataFrame, null_counts: dict) -> str:
+    """Render DataFrame as styled HTML table"""
+    if df is None or len(df) == 0:
+        return "<p style='color:#64748B;font-size:13px'>No data</p>"
+
+    rows_html = ""
+    for _, row in df.iterrows():
+        cells = ""
+        for col in df.columns:
+            val = row[col]
+            is_null = val is None or (
+                isinstance(val, float) and pd.isna(val)
+            )
+            if is_null:
+                cells += f"<td style='color:#EF4444;font-style:italic;background:#FFF5F5;padding:7px 12px;border-bottom:1px solid #F1F5F9'>null</td>"
+            elif isinstance(val, (int, float)) and col in ["salary", "salary$"]:
+                if abs(float(val)) > 500000 or float(val) < 0:
+                    cells += f"<td style='color:#D97706;background:#FFFBEB;padding:7px 12px;border-bottom:1px solid #F1F5F9'>{val}</td>"
+                else:
+                    cells += f"<td style='padding:7px 12px;border-bottom:1px solid #F1F5F9;color:#1E293B'>{val}</td>"
+            else:
+                cells += f"<td style='padding:7px 12px;border-bottom:1px solid #F1F5F9;color:#1E293B'>{val}</td>"
+        rows_html += f"<tr>{cells}</tr>"
+
+    headers = "".join([
+        f"<th style='background:#F8FAFC;padding:8px 12px;text-align:left;font-size:11px;color:#64748B;font-weight:500;border-bottom:1px solid #E2E8F0'>{col}</th>"
+        for col in df.columns
+    ])
+
+    return f"""
+    <div style='background:#fff;border:1px solid #E2E8F0;border-radius:10px;overflow:hidden;font-family:DM Sans,sans-serif'>
+      <div style='padding:10px 14px;border-bottom:1px solid #E2E8F0;display:flex;justify-content:space-between;align-items:center'>
+        <span style='font-size:13px;font-weight:500;color:#1E293B'>Live dataset</span>
+        <span style='background:#EFF6FF;color:#2563EB;font-size:11px;padding:3px 10px;border-radius:20px;border:1px solid #BFDBFE'>{len(df)} rows · {len(df.columns)} cols</span>
+      </div>
+      <div style='overflow-x:auto'>
+        <table style='width:100%;border-collapse:collapse;font-size:12px;color:#1E293B'>
+          <thead><tr>{headers}</tr></thead>
+          <tbody>{rows_html}</tbody>
+        </table>
+      </div>
+    </div>
+    """
+
+def issues_to_html(issues: list) -> str:
+    """Render issues as styled pills"""
+    if not issues:
+        return "<div style='color:#10B981;font-size:13px;font-weight:500'>No issues detected!</div>"
+
+    pills = ""
+    for issue in issues:
+        if "missing" in issue:
+            color = "#FFF5F5"; text = "#B91C1C"; border = "#FECACA"
+        elif "duplicate" in issue:
+            color = "#FFFBEB"; text = "#92400E"; border = "#FDE68A"
+        elif "outlier" in issue:
+            color = "#FFFBEB"; text = "#92400E"; border = "#FDE68A"
+        elif "bad_column" in issue:
+            color = "#EFF6FF"; text = "#1D4ED8"; border = "#BFDBFE"
+        else:
+            color = "#F8FAFC"; text = "#475569"; border = "#E2E8F0"
+
+        pills += f"<div style='background:{color};color:{text};border:1px solid {border};font-size:11px;padding:5px 10px;border-radius:6px;margin-bottom:6px'>{issue}</div>"
+
+    return pills
+
+def log_to_html(logs: list) -> str:
+    """Render step log as terminal-style HTML"""
+    if not logs:
+        return "<div style='background:#0F172A;border-radius:8px;padding:12px;font-size:11px;font-family:monospace;color:#475569'>No steps yet...</div>"
+
+    lines = ""
+    for entry in logs[-10:]:
+        reward_color = "#34D399" if entry["reward"] > 0 else "#F87171"
+        lines += f"""
+        <div style='margin-bottom:6px'>
+          <span style='color:#60A5FA'>[step {entry['step']}]</span>
+          <span style='color:#E2E8F0'> {entry['action']}</span>
+          <br>
+          <span style='color:{reward_color};padding-left:12px'>{entry['reward']:+.3f} · {entry['reason'][:50]}</span>
+        </div>"""
+
+    return f"<div style='background:#0F172A;border-radius:8px;padding:12px;font-size:11px;font-family:monospace;line-height:1.7;max-height:220px;overflow-y:auto'>{lines}</div>"
+
+
+# ── Actions ───────────────────────────────────
+
+def reset_task(difficulty):
+    global current_difficulty
+    current_difficulty = difficulty
+    env = envs[difficulty]
+    obs = env.reset()
+    step_logs[difficulty] = []
+
+    df = pd.DataFrame(obs.dataframe)
+    score, _ = env.task.grade()
+
+    return (
+        df_to_html(df, obs.null_counts),
+        issues_to_html(obs.issues),
+        log_to_html([]),
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#2563EB'>0.000</div>",
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#1E293B'>0</div>",
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#EF4444'>{sum(obs.null_counts.values())}</div>",
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#F59E0B'>0</div>",
+    )
+
+
+def run_action(difficulty, action_type, column, strategy,
+               target_type, old_name, new_name, mapping_json):
+    global current_difficulty
+    current_difficulty = difficulty
+    env = envs[difficulty]
+
+    if not env._initialized:
+        env.reset()
+
+    # Build parameters
+    params = {}
+    if action_type == "fill_missing":
+        params = {"column": column, "strategy": strategy or "mean"}
+    elif action_type == "drop_duplicates":
+        params = {}
+    elif action_type == "fix_dtype":
+        params = {"column": column, "target_type": target_type or "float"}
+    elif action_type == "rename_column":
+        params = {"old_name": old_name, "new_name": new_name}
+    elif action_type == "remove_outliers":
+        params = {"column": column, "method": strategy or "iqr"}
+    elif action_type == "standardize_values":
+        try:
+            params = {"column": column, "mapping": json.loads(mapping_json)}
+        except Exception:
+            params = {"column": column, "mapping": {}}
+    elif action_type == "submit":
+        params = {}
+
+    action = Action(action_type=action_type, parameters=params)
+    result = env.step(action)
+    obs    = result.observation
+
+    # Log step
+    step_logs[difficulty].append({
+        "step":   env.step_count,
+        "action": action_type,
+        "reward": result.reward.value,
+        "reason": result.reward.reason,
+    })
+
+    df    = pd.DataFrame(obs.dataframe)
+    score, _ = env.task.grade()
+
+    return (
+        df_to_html(df, obs.null_counts),
+        issues_to_html(obs.issues),
+        log_to_html(step_logs[difficulty]),
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#2563EB'>{score:.3f}</div>",
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#1E293B'>{env.step_count}</div>",
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#EF4444'>{sum(obs.null_counts.values())}</div>",
+        f"<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:{'#10B981' if result.reward.value > 0 else '#EF4444'}'>{result.reward.value:+.3f}</div>",
+    )
+
+
+# ── UI ────────────────────────────────────────
+
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700;900&family=DM+Sans:wght@300;400;500&display=swap');
+body, .gradio-container { background: #F8FAFC !important; font-family: 'DM Sans', sans-serif !important; }
+.logo { font-family: 'Playfair Display', serif !important; }
+h1, h2, h3 { font-family: 'Playfair Display', serif !important; }
+.gr-button-primary { background: #2563EB !important; border: none !important; }
+.gr-button { border-radius: 8px !important; font-family: 'DM Sans', sans-serif !important; }
+"""
+
+with gr.Blocks(css=CSS, title="DataClean — OpenEnv") as demo:
+
+    gr.HTML("""
+    <div style='background:#fff;border-bottom:1px solid #E2E8F0;padding:16px 24px;display:flex;align-items:center;justify-content:space-between;margin-bottom:0'>
+      <div style='font-family:Playfair Display,serif;font-size:26px;font-weight:900;color:#2563EB;letter-spacing:-0.5px'>
+        Data<span style='color:#1E293B'>Clean</span>
+      </div>
+      <div style='background:#EFF6FF;color:#2563EB;font-size:12px;font-weight:500;padding:4px 14px;border-radius:20px;border:1px solid #BFDBFE'>
+        OpenEnv v1.0 · Yashwanth34567
+      </div>
+    </div>
+    """)
+
+    with gr.Row():
+
+        # ── Left Sidebar ──
+        with gr.Column(scale=1):
+            gr.HTML("<div style='font-size:11px;font-weight:500;color:#64748B;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px'>Select Task</div>")
+            difficulty = gr.Radio(
+                choices=[TASK_EASY, TASK_MEDIUM, TASK_HARD],
+                value=TASK_EASY,
+                label="",
+            )
+            reset_btn = gr.Button("Reset Task", variant="primary")
+
+            gr.HTML("<div style='font-size:11px;font-weight:500;color:#64748B;letter-spacing:0.08em;text-transform:uppercase;margin:16px 0 8px'>Issues</div>")
+            issues_display = gr.HTML()
+
+        # ── Center ──
+        with gr.Column(scale=3):
+            with gr.Row():
+                score_display  = gr.HTML("<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#2563EB'>—</div>")
+                step_display   = gr.HTML("<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#1E293B'>—</div>")
+                null_display   = gr.HTML("<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#EF4444'>—</div>")
+                reward_display = gr.HTML("<div style='font-family:Playfair Display,serif;font-size:28px;font-weight:700;color:#F59E0B'>—</div>")
+
+            gr.HTML("<div style='font-size:11px;font-weight:500;color:#64748B;letter-spacing:0.08em;text-transform:uppercase;margin:8px 0'>Live Dataset</div>")
+            table_display = gr.HTML()
+
+            gr.HTML("<div style='font-size:11px;font-weight:500;color:#64748B;letter-spacing:0.08em;text-transform:uppercase;margin:16px 0 8px'>Step Log</div>")
+            log_display = gr.HTML()
+
+        # ── Right Panel ──
+        with gr.Column(scale=1):
+            gr.HTML("<div style='font-size:11px;font-weight:500;color:#64748B;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px'>Take Action</div>")
+
+            action_type = gr.Dropdown(
+                choices=["fill_missing", "drop_duplicates", "fix_dtype",
+                         "rename_column", "remove_outliers",
+                         "standardize_values", "submit"],
+                value="fill_missing",
+                label="Action",
+            )
+            column      = gr.Textbox(label="Column", placeholder="e.g. age")
+            strategy    = gr.Textbox(label="Strategy / Method", placeholder="mean | median | mode | iqr")
+            target_type = gr.Textbox(label="Target Type", placeholder="int | float | str")
+            old_name    = gr.Textbox(label="Old Column Name", placeholder="Full Name ")
+            new_name    = gr.Textbox(label="New Column Name", placeholder="full_name")
+            mapping     = gr.Textbox(label='Mapping (JSON)', placeholder='{"USA": "United States"}')
+
+            run_btn    = gr.Button("Run Action", variant="primary")
+            submit_btn = gr.Button("Submit Task", variant="secondary")
+
+    # ── Events ───────────────────────────────
+    outputs = [
+        table_display, issues_display, log_display,
+        score_display, step_display, null_display, reward_display
+    ]
+
+    reset_btn.click(
+        fn=reset_task,
+        inputs=[difficulty],
+        outputs=outputs,
+    )
+
+    run_btn.click(
+        fn=run_action,
+        inputs=[difficulty, action_type, column, strategy,
+                target_type, old_name, new_name, mapping],
+        outputs=outputs,
+    )
+
+    submit_btn.click(
+        fn=lambda d, c, s, t, o, n, m: run_action(
+            d, "submit", c, s, t, o, n, m),
+        inputs=[difficulty, column, strategy,
+                target_type, old_name, new_name, mapping],
+        outputs=outputs,
+    )
+    
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        inbrowser=True,
+    )

config.py

@@ -0,0 +1,41 @@
+# config.py
+# ─────────────────────────────────────────────
+# Central configuration for Data Cleaning Env
+# ─────────────────────────────────────────────
+
+import os
+
+# ── Environment Metadata ──────────────────────
+ENV_NAME        = "data-cleaning-env"
+ENV_VERSION     = "1.0.0"
+ENV_DESCRIPTION = "An OpenEnv environment where an AI agent cleans messy CSV datasets"
+AUTHOR          = "Yashwanth34567"
+
+# ── Task Difficulty Levels ────────────────────
+TASK_EASY   = "easy"
+TASK_MEDIUM = "medium"
+TASK_HARD   = "hard"
+
+TASK_IDS = {
+    TASK_EASY:   "task_1_easy",
+    TASK_MEDIUM: "task_2_medium",
+    TASK_HARD:   "task_3_hard",
+}
+
+# ── Reward Values ─────────────────────────────
+REWARD_ISSUE_FIXED       =  0.10   # each real issue fixed
+REWARD_SUBMIT_BONUS      =  0.30   # bonus for clean submit
+PENALTY_WRONG_ACTION     = -0.05   # redundant / wrong action
+PENALTY_DESTRUCTIVE      = -0.10   # dropping valid data
+
+# ── Episode Settings ──────────────────────────
+MAX_STEPS = 20   # max actions per episode
+
+# ── API Settings ──────────────────────────────
+API_BASE_URL = os.getenv("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME   = os.getenv("MODEL_NAME",   "gpt-4o-mini")
+HF_TOKEN     = os.getenv("HF_TOKEN",     "")
+
+# ── Server Settings ───────────────────────────
+HOST = "0.0.0.0"
+PORT = 8000

datasets.py

@@ -0,0 +1,161 @@
+# datasets.py
+# ─────────────────────────────────────────────
+# CSV dataset generators for each difficulty
+# Easy / Medium / Hard messy datasets
+# ─────────────────────────────────────────────
+
+import pandas as pd
+import numpy as np
+import random
+
+random.seed(42)
+np.random.seed(42)
+
+# ── Task 1 — Easy ─────────────────────────────
+def generate_easy_dataset() -> pd.DataFrame:
+    """
+    10 rows, issues:
+    - Missing values in age & salary
+    - Wrong dtype (age as string)
+    """
+    data = {
+        "name":   ["Alice", "Bob", "Charlie", "Diana", "Eve",
+                   "Frank", "Grace", "Hank", "Ivy", "Jack"],
+        "age":    ["25", "30", None, "22", "28",
+                   "35", None, "40", "27", "33"],
+        "salary": [50000, 60000, None, 45000, 55000,
+                   None, 70000, 80000, None, 65000],
+        "email":  [
+            "alice@mail.com", "bob@mail.com", "charlie@mail.com",
+            "diana@mail.com", "eve@mail.com", "frank@mail.com",
+            "grace@mail.com", "hank@mail.com", "ivy@mail.com",
+            "jack@mail.com"
+        ]
+    }
+    return pd.DataFrame(data)
+
+
+# ── Task 2 — Medium ───────────────────────────
+def generate_medium_dataset() -> pd.DataFrame:
+    """
+    20 rows, issues:
+    - Duplicate rows
+    - Outliers in salary
+    - Inconsistent country values
+    """
+    data = {
+        "name": [
+            "Alice", "Bob", "Charlie", "Diana", "Eve",
+            "Frank", "Grace", "Hank", "Ivy", "Jack",
+            "Alice", "Bob", "Karen", "Leo", "Mia",
+            "Nina", "Oscar", "Paul", "Quinn", "Rita"
+        ],
+        "age": [25, 30, 35, 22, 28, 40, 27, 33, 29, 31,
+                25, 30, 26, 38, 24, 32, 36, 28, 30, 27],
+        "salary": [
+            50000, 60000, 55000, 45000, 58000,
+            62000, 48000, 70000, 999999, 65000,
+            50000, 60000, 47000, 72000, 43000,
+            -5000, 68000, 54000, 61000, 49000
+        ],
+        "country": [
+            "USA", "United States", "US", "USA", "America",
+            "UK", "United Kingdom", "UK", "USA", "US",
+            "USA", "United States", "UK", "USA", "US",
+            "USA", "UK", "United Kingdom", "USA", "US"
+        ]
+    }
+    return pd.DataFrame(data)
+
+
+# ── Task 3 — Hard ─────────────────────────────
+def generate_hard_dataset() -> tuple:
+    """
+    30 rows, issues:
+    - All of easy + medium issues
+    - Bad column names
+    - Mixed dtype columns
+    Returns (main_df, lookup_df) for referential integrity check
+    """
+    main_data = {
+        "Full Name ":  [  # trailing space in col name
+            "Alice", "Bob", "Charlie", "Diana", "Eve",
+            "Frank", "Grace", "Hank", "Ivy", "Jack",
+            "Karen", "Leo", "Mia", "Nina", "Oscar",
+            "Paul", "Quinn", "Rita", "Sam", "Tina",
+            "Uma", "Victor", "Wendy", "Xander", "Yara",
+            "Zane", "Alice", "Bob", "Charlie", "Diana"
+        ],
+        "AGE":  [  # should be lowercase
+            "25", "30", None, "22", "28",
+            "35", "27", "40", "abc", "33",
+            "26", "38", "24", "32", "36",
+            "28", "30", "27", "29", "31",
+            "25", "30", None, "22", "28",
+            "35", "25", "30", "35", "22"
+        ],
+        "salary$": [  # special char in col name
+            50000, 60000, None, 45000, 55000,
+            None, 70000, 80000, None, 65000,
+            47000, 72000, 43000, -5000, 68000,
+            54000, 61000, 49000, 999999, 58000,
+            50000, 60000, 55000, 45000, 58000,
+            62000, 50000, 60000, 55000, 45000
+        ],
+        "COUNTRY": [
+            "USA", "United States", "US", "USA", "America",
+            "UK", "United Kingdom", "UK", "USA", "US",
+            "USA", "United States", "UK", "USA", "US",
+            "USA", "UK", "United Kingdom", "USA", "US",
+            "USA", "United States", "US", "USA", "America",
+            "UK", "USA", "US", "UK", "USA"
+        ],
+        "dept_id": [
+            1, 2, 3, 1, 2, 3, 1, 2, 3, 1,
+            2, 3, 1, 2, 99, 1, 2, 3, 1, 2,  # 99 is invalid
+            3, 1, 2, 3, 1, 2, 3, 1, 2, 3
+        ]
+    }
+
+    # Lookup table for referential integrity
+    lookup_data = {
+        "dept_id":   [1, 2, 3],
+        "dept_name": ["Engineering", "Marketing", "Sales"]
+    }
+
+    return pd.DataFrame(main_data), pd.DataFrame(lookup_data)
+
+
+# ── Issue Detection ───────────────────────────
+def detect_issues(df: pd.DataFrame, task_id: str) -> list:
+    """Detect all issues in a dataframe"""
+    issues = []
+
+    # Null values
+    null_counts = df.isnull().sum()
+    for col, count in null_counts.items():
+        if count > 0:
+            issues.append(f"missing_values::{col}::{count}")
+
+    # Duplicates
+    dup_count = df.duplicated().sum()
+    if dup_count > 0:
+        issues.append(f"duplicate_rows::{dup_count}")
+
+    # Outliers (numeric columns)
+    for col in df.select_dtypes(include=[np.number]).columns:
+        Q1 = df[col].quantile(0.25)
+        Q3 = df[col].quantile(0.75)
+        IQR = Q3 - Q1
+        outliers = ((df[col] < Q1 - 1.5 * IQR) |
+                    (df[col] > Q3 + 1.5 * IQR)).sum()
+        if outliers > 0:
+            issues.append(f"outliers::{col}::{outliers}")
+
+    # Bad column names
+    for col in df.columns:
+        if col != col.strip() or col != col.lower() or \
+           any(c in col for c in ["$", "@", "#", "!"]):
+            issues.append(f"bad_column_name::{col}")
+
+    return issues

environment.py

@@ -0,0 +1,363 @@
+# environment.py
+# ─────────────────────────────────────────────
+# Core OpenEnv class — step / reset / state
+# Full OpenEnv spec compliant
+# ─────────────────────────────────────────────
+
+import pandas as pd
+import numpy as np
+from typing import Any, Dict, Optional, Tuple
+
+from config import (
+    MAX_STEPS,
+    REWARD_ISSUE_FIXED,
+    REWARD_SUBMIT_BONUS,
+    PENALTY_WRONG_ACTION,
+    PENALTY_DESTRUCTIVE,
+    TASK_EASY, TASK_MEDIUM, TASK_HARD,
+)
+from models import Observation, Action, Reward, StepResult
+from tasks import Task, get_task
+from utils import (
+    df_to_records,
+    get_null_counts,
+    get_duplicate_count,
+    detect_outliers_iqr,
+    clean_column_name,
+    standardize_column,
+    clamp,
+)
+from datasets import detect_issues
+
+
+class DataCleaningEnv:
+    """
+    OpenEnv-compliant Data Cleaning Environment.
+
+    The agent receives a messy CSV dataset and must
+    issue cleaning actions to fix it step by step.
+
+    Actions:
+        fill_missing        — fill null values
+        drop_duplicates     — remove duplicate rows
+        fix_dtype           — convert column dtype
+        rename_column       — rename a column
+        remove_outliers     — remove outlier rows
+        standardize_values  — replace values via mapping
+        submit              — finalize and trigger grader
+    """
+
+    def __init__(self, difficulty: str = TASK_EASY):
+        self.difficulty    = difficulty
+        self.task: Task    = get_task(difficulty)
+        self.step_count    = 0
+        self.total_reward  = 0.0
+        self.done          = False
+        self._prev_score   = 0.0
+        self._initialized  = False
+
+    # ── OpenEnv API ───────────────────────────
+
+    def reset(self) -> Observation:
+        """Start a fresh episode"""
+        self.task.reset()
+        self.step_count   = 0
+        self.total_reward = 0.0
+        self.done         = False
+        self._prev_score  = 0.0
+        self._initialized = True
+        return self._make_observation()
+
+    def step(self, action: Action) -> StepResult:
+        """Execute one action and return result"""
+        if not self._initialized:
+            self.reset()
+
+        if self.done:
+            obs = self._make_observation()
+            reward = Reward(value=0.0, total=self.total_reward,
+                           reason="Episode already done")
+            return StepResult(observation=obs, reward=reward,
+                            done=True, info={})
+
+        self.step_count += 1
+        reward_value, reason, info = self._execute_action(action)
+
+        # Clamp and accumulate
+        reward_value       = clamp(reward_value, -1.0, 1.0)
+        self.total_reward  = round(self.total_reward + reward_value, 4)
+
+        # Check done conditions
+        if self.step_count >= MAX_STEPS:
+            self.done = True
+            reason   += " | Max steps reached"
+
+        reward = Reward(
+            value  = round(reward_value, 4),
+            total  = self.total_reward,
+            reason = reason,
+        )
+        obs = self._make_observation()
+        obs.done = self.done
+
+        return StepResult(
+            observation = obs,
+            reward      = reward,
+            done        = self.done,
+            info        = info,
+        )
+
+    def state(self) -> Dict[str, Any]:
+        """Return current environment state as dict"""
+        if not self._initialized:
+            return {"status": "not initialized, call reset() first"}
+
+        score, details = self.task.grade()
+        return {
+            "task_id":        self.task.task_id,
+            "difficulty":     self.difficulty,
+            "step":           self.step_count,
+            "max_steps":      MAX_STEPS,
+            "total_reward":   self.total_reward,
+            "current_score":  score,
+            "done":           self.done,
+            "issues":         self.task.issues,
+            "grade_details":  details,
+            "dataframe":      df_to_records(self.task.current_df),
+            "columns":        list(self.task.current_df.columns),
+            "null_counts":    get_null_counts(self.task.current_df),
+            "duplicate_rows": get_duplicate_count(self.task.current_df),
+        }
+
+    # ── Action Executor ───────────────────────
+
+    def _execute_action(self, action: Action
+                        ) -> Tuple[float, str, Dict]:
+        """Route action to handler, return (reward, reason, info)"""
+        df   = self.task.current_df
+        p    = action.parameters
+        info = {}
+
+        try:
+            if action.action_type == "fill_missing":
+                df, reward, reason = self._fill_missing(df, p)
+
+            elif action.action_type == "drop_duplicates":
+                df, reward, reason = self._drop_duplicates(df)
+
+            elif action.action_type == "fix_dtype":
+                df, reward, reason = self._fix_dtype(df, p)
+
+            elif action.action_type == "rename_column":
+                df, reward, reason = self._rename_column(df, p)
+
+            elif action.action_type == "remove_outliers":
+                df, reward, reason = self._remove_outliers(df, p)
+
+            elif action.action_type == "standardize_values":
+                df, reward, reason = self._standardize_values(df, p)
+
+            elif action.action_type == "submit":
+                df, reward, reason, info = self._submit(df)
+
+            else:
+                reward = PENALTY_WRONG_ACTION
+                reason = f"Unknown action: {action.action_type}"
+
+        except Exception as e:
+            reward = PENALTY_WRONG_ACTION
+            reason = f"Action failed: {str(e)}"
+            info   = {"error": str(e)}
+
+        self.task.current_df = df
+        self.task.update_issues()
+        return reward, reason, info
+
+    # ── Action Handlers ───────────────────────
+
+    def _fill_missing(self, df: pd.DataFrame,
+                      params: Dict) -> Tuple[pd.DataFrame, float, str]:
+        column   = params.get("column")
+        strategy = params.get("strategy", "mean")
+
+        if column not in df.columns:
+            return df, PENALTY_WRONG_ACTION, f"Column '{column}' not found"
+
+        null_before = df[column].isnull().sum()
+        if null_before == 0:
+            return df, PENALTY_WRONG_ACTION, \
+                   f"No nulls in '{column}' — redundant action"
+
+        df = df.copy()
+        if strategy == "mean":
+            numeric = pd.to_numeric(df[column], errors="coerce")
+            df[column] = df[column].fillna(numeric.mean())
+        elif strategy == "median":
+            numeric = pd.to_numeric(df[column], errors="coerce")
+            df[column] = df[column].fillna(numeric.median())
+        elif strategy == "mode":
+            df[column].fillna(df[column].mode()[0], inplace=True)
+        elif strategy == "drop":
+            before = len(df)
+            df.dropna(subset=[column], inplace=True)
+            dropped = before - len(df)
+            if dropped > len(df) * 0.3:
+                return df, PENALTY_DESTRUCTIVE, \
+                       f"Dropped {dropped} rows — too destructive"
+        else:
+            df[column].fillna(strategy, inplace=True)
+
+        null_after = df[column].isnull().sum()
+        fixed      = null_before - null_after
+        reward     = REWARD_ISSUE_FIXED * (fixed / max(null_before, 1))
+        return df, reward, f"Filled {fixed} nulls in '{column}' via {strategy}"
+
+    def _drop_duplicates(self, df: pd.DataFrame
+                         ) -> Tuple[pd.DataFrame, float, str]:
+        dup_before = df.duplicated().sum()
+        if dup_before == 0:
+            return df, PENALTY_WRONG_ACTION, "No duplicates — redundant action"
+
+        df     = df.drop_duplicates().reset_index(drop=True)
+        reward = REWARD_ISSUE_FIXED
+        return df, reward, f"Removed {dup_before} duplicate rows"
+
+    def _fix_dtype(self, df: pd.DataFrame,
+                   params: Dict) -> Tuple[pd.DataFrame, float, str]:
+        column      = params.get("column")
+        target_type = params.get("target_type", "float")
+
+        if column not in df.columns:
+            return df, PENALTY_WRONG_ACTION, f"Column '{column}' not found"
+
+        df = df.copy()
+        try:
+            if target_type == "int":
+                df[column] = pd.to_numeric(
+                    df[column], errors="coerce").fillna(0).astype(int)
+            elif target_type == "float":
+                df[column] = pd.to_numeric(df[column], errors="coerce")
+            elif target_type == "str":
+                df[column] = df[column].astype(str)
+            elif target_type == "datetime":
+                df[column] = pd.to_datetime(df[column], errors="coerce")
+            else:
+                return df, PENALTY_WRONG_ACTION, \
+                       f"Unknown target type: {target_type}"
+        except Exception as e:
+            return df, PENALTY_WRONG_ACTION, f"Dtype fix failed: {e}"
+
+        return df, REWARD_ISSUE_FIXED, \
+               f"Converted '{column}' to {target_type}"
+
+    def _rename_column(self, df: pd.DataFrame,
+                       params: Dict) -> Tuple[pd.DataFrame, float, str]:
+        old_name = params.get("old_name")
+        new_name = params.get("new_name")
+
+        if old_name not in df.columns:
+            return df, PENALTY_WRONG_ACTION, \
+                   f"Column '{old_name}' not found"
+
+        expected = clean_column_name(old_name)
+        if new_name != expected:
+            return df, PENALTY_WRONG_ACTION, \
+                   f"Suggested name '{new_name}' — expected '{expected}'"
+
+        df = df.rename(columns={old_name: new_name})
+        return df, REWARD_ISSUE_FIXED, \
+               f"Renamed '{old_name}' to '{new_name}'"
+
+    def _remove_outliers(self, df: pd.DataFrame,
+                         params: Dict) -> Tuple[pd.DataFrame, float, str]:
+        column = params.get("column")
+        method = params.get("method", "iqr")
+
+        if column not in df.columns:
+            return df, PENALTY_WRONG_ACTION, f"Column '{column}' not found"
+
+        df = df.copy()
+        try:
+            numeric = pd.to_numeric(df[column], errors="coerce")
+            df[column] = numeric
+
+            if method == "iqr":
+                mask = detect_outliers_iqr(df, column)
+            else:
+                from utils import detect_outliers_zscore
+                mask = detect_outliers_zscore(df, column)
+
+            count = mask.sum()
+            if count == 0:
+                return df, PENALTY_WRONG_ACTION, \
+                       f"No outliers in '{column}' — redundant"
+
+            if count > len(df) * 0.4:
+                return df, PENALTY_DESTRUCTIVE, \
+                       f"Would remove {count} rows — too destructive"
+
+            df = df[~mask].reset_index(drop=True)
+            return df, REWARD_ISSUE_FIXED, \
+                   f"Removed {count} outliers from '{column}'"
+
+        except Exception as e:
+            return df, PENALTY_WRONG_ACTION, f"Outlier removal failed: {e}"
+
+    def _standardize_values(self, df: pd.DataFrame,
+                             params: Dict
+                             ) -> Tuple[pd.DataFrame, float, str]:
+        column  = params.get("column")
+        mapping = params.get("mapping", {})
+
+        if column not in df.columns:
+            return df, PENALTY_WRONG_ACTION, f"Column '{column}' not found"
+
+        if not mapping:
+            return df, PENALTY_WRONG_ACTION, "Empty mapping provided"
+
+        before = df[column].value_counts().to_dict()
+        df     = standardize_column(df, column, mapping)
+        after  = df[column].value_counts().to_dict()
+
+        changed = sum(1 for k, v in before.items()
+                      if after.get(mapping.get(k, k), 0) != v)
+        if changed == 0:
+            return df, PENALTY_WRONG_ACTION, "No values changed"
+
+        return df, REWARD_ISSUE_FIXED, \
+               f"Standardized {len(mapping)} values in '{column}'"
+
+    def _submit(self, df: pd.DataFrame
+                ) -> Tuple[pd.DataFrame, float, str, Dict]:
+        score, details = self.task.grade()
+        self.done      = True
+
+        if score >= 0.9:
+            reward = REWARD_SUBMIT_BONUS + score
+            reason = f"Excellent! Score: {score:.3f} — dataset is clean!"
+        elif score >= 0.6:
+            reward = score
+            reason = f"Good effort. Score: {score:.3f} — some issues remain"
+        else:
+            reward = score * 0.5
+            reason = f"Submitted early. Score: {score:.3f} — many issues remain"
+
+        return df, reward, reason, {"final_score": score, "details": details}
+
+    # ── Observation Builder ───────────────────
+
+    def _make_observation(self) -> Observation:
+        df = self.task.current_df
+        return Observation(
+            task_id        = self.task.task_id,
+            difficulty     = self.difficulty,
+            step           = self.step_count,
+            max_steps      = MAX_STEPS,
+            dataframe      = df_to_records(df),
+            columns        = list(df.columns),
+            dtypes         = {c: str(t) for c, t in df.dtypes.items()},
+            null_counts    = get_null_counts(df),
+            duplicate_rows = get_duplicate_count(df),
+            issues         = self.task.issues,
+            done           = self.done,
+        )

graders.py

@@ -0,0 +1,203 @@
+# graders.py
+# ─────────────────────────────────────────────
+# Grading logic for all 3 tasks
+# Returns scores between 0.0 and 1.0
+# ─────────────────────────────────────────────
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Tuple
+from utils import (
+    compute_null_score,
+    compute_duplicate_score,
+    compute_dtype_score,
+    detect_outliers_iqr,
+    has_bad_column_names,
+    clamp,
+)
+
+
+# ── Task 1 Grader — Easy ──────────────────────
+
+def grade_task1(original_df: pd.DataFrame,
+                current_df: pd.DataFrame) -> Tuple[float, Dict]:
+    """
+    Scores:
+    - 40% null values fixed
+    - 40% correct dtypes (age=int, salary=float)
+    - 20% no data loss (row count preserved)
+    """
+    details = {}
+
+    # Null score (40%)
+    null_score = compute_null_score(original_df, current_df)
+    details["null_score"] = null_score
+
+    # Dtype score (40%)
+    expected_dtypes = {"age": "int64", "salary": "float64"}
+    dtype_score = compute_dtype_score(current_df, expected_dtypes)
+    details["dtype_score"] = dtype_score
+
+    # Row preservation score (20%)
+    expected_rows = len(original_df)
+    actual_rows   = len(current_df)
+    row_score = 1.0 if actual_rows == expected_rows else \
+                clamp(actual_rows / expected_rows)
+    details["row_score"] = row_score
+
+    # Final weighted score
+    final = (
+        0.40 * null_score  +
+        0.40 * dtype_score +
+        0.20 * row_score
+    )
+    details["final"] = round(clamp(final), 4)
+    return details["final"], details
+
+
+# ── Task 2 Grader — Medium ────────────────────
+
+def grade_task2(original_df: pd.DataFrame,
+                current_df: pd.DataFrame) -> Tuple[float, Dict]:
+    """
+    Scores:
+    - 35% duplicates removed
+    - 35% outliers handled in salary
+    - 30% country values standardized
+    """
+    details = {}
+
+    # Duplicate score (35%)
+    dup_score = compute_duplicate_score(original_df, current_df)
+    details["duplicate_score"] = dup_score
+
+    # Outlier score (35%)
+    if "salary" in current_df.columns:
+        try:
+            salary_col = pd.to_numeric(current_df["salary"], errors="coerce")
+            outlier_mask    = detect_outliers_iqr(
+                current_df.assign(salary=salary_col), "salary"
+            )
+            remaining_outliers = outlier_mask.sum()
+            original_salary = pd.to_numeric(
+                original_df["salary"], errors="coerce"
+            )
+            original_outliers = detect_outliers_iqr(
+                original_df.assign(salary=original_salary), "salary"
+            ).sum()
+            if original_outliers == 0:
+                outlier_score = 1.0
+            else:
+                fixed = original_outliers - remaining_outliers
+                outlier_score = clamp(fixed / original_outliers)
+        except Exception:
+            outlier_score = 0.0
+    else:
+        outlier_score = 0.0
+    details["outlier_score"] = outlier_score
+
+    # Country standardization score (30%)
+    if "country" in current_df.columns:
+        standard_values = {"United States", "UK"}
+        unique_vals     = set(current_df["country"].dropna().unique())
+        non_standard    = unique_vals - standard_values
+        country_score   = 1.0 if not non_standard else \
+                          clamp(1 - len(non_standard) / len(unique_vals))
+    else:
+        country_score = 0.0
+    details["country_score"] = country_score
+
+    # Final weighted score
+    final = (
+        0.35 * dup_score     +
+        0.35 * outlier_score +
+        0.30 * country_score
+    )
+    details["final"] = round(clamp(final), 4)
+    return details["final"], details
+
+
+# ── Task 3 Grader — Hard ──────────────────────
+
+def grade_task3(original_df: pd.DataFrame,
+                current_df: pd.DataFrame,
+                lookup_df: pd.DataFrame) -> Tuple[float, Dict]:
+    """
+    Scores:
+    - 25% null values fixed
+    - 20% column names cleaned
+    - 20% outliers handled
+    - 20% country standardized
+    - 15% referential integrity (dept_id valid)
+    """
+    details = {}
+
+    # Null score (25%)
+    null_score = compute_null_score(original_df, current_df)
+    details["null_score"] = null_score
+
+    # Column name score (20%)
+    bad_cols = has_bad_column_names(current_df)
+    col_score = 1.0 if not bad_cols else \
+                clamp(1 - len(bad_cols) / len(current_df.columns))
+    details["column_name_score"] = col_score
+
+    # Outlier score (20%)
+    numeric_cols = current_df.select_dtypes(include=[np.number]).columns
+    salary_like  = [c for c in numeric_cols if "salary" in c.lower()]
+    if salary_like:
+        col = salary_like[0]
+        try:
+            outlier_mask = detect_outliers_iqr(current_df, col)
+            orig_col     = [c for c in original_df.columns
+                            if "salary" in c.lower()]
+            if orig_col:
+                orig_mask = detect_outliers_iqr(original_df, orig_col[0])
+                orig_count = orig_mask.sum()
+                if orig_count == 0:
+                    outlier_score = 1.0
+                else:
+                    fixed = orig_count - outlier_mask.sum()
+                    outlier_score = clamp(fixed / orig_count)
+            else:
+                outlier_score = 1.0
+        except Exception:
+            outlier_score = 0.0
+    else:
+        outlier_score = 0.0
+    details["outlier_score"] = outlier_score
+
+    # Country standardization (20%)
+    country_cols = [c for c in current_df.columns if "country" in c.lower()]
+    if country_cols:
+        standard     = {"United States", "UK"}
+        unique_vals  = set(current_df[country_cols[0]].dropna().unique())
+        non_standard = unique_vals - standard
+        country_score = 1.0 if not non_standard else \
+                        clamp(1 - len(non_standard) / len(unique_vals))
+    else:
+        country_score = 0.0
+    details["country_score"] = country_score
+
+    # Referential integrity (15%)
+    dept_cols = [c for c in current_df.columns if "dept_id" in c.lower()]
+    if dept_cols and lookup_df is not None:
+        valid_ids    = set(lookup_df["dept_id"].unique())
+        actual_ids   = set(current_df[dept_cols[0]].dropna().unique())
+        invalid      = actual_ids - valid_ids
+        ref_score    = 1.0 if not invalid else \
+                       clamp(1 - len(invalid) / len(actual_ids))
+    else:
+        ref_score = 0.0
+    details["referential_integrity_score"] = ref_score
+
+    # Final weighted score
+    final = (
+        0.25 * null_score    +
+        0.20 * col_score     +
+        0.20 * outlier_score +
+        0.20 * country_score +
+        0.15 * ref_score
+    )
+    details["final"] = round(clamp(final), 4)
+    return details["final"], details

models.py

@@ -0,0 +1,63 @@
+# models.py
+# ─────────────────────────────────────────────
+# Pydantic models for OpenEnv spec compliance
+# Observation, Action, Reward typed models
+# ─────────────────────────────────────────────
+
+from pydantic import BaseModel, Field
+from typing import Any, Dict, List, Optional
+
+# ── Observation ───────────────────────────────
+class Observation(BaseModel):
+    """What the agent sees at each step"""
+
+    task_id:         str                    = Field(..., description="Current task identifier")
+    difficulty:      str                    = Field(..., description="easy / medium / hard")
+    step:            int                    = Field(..., description="Current step number")
+    max_steps:       int                    = Field(..., description="Maximum steps allowed")
+    dataframe:       List[Dict[str, Any]]   = Field(..., description="Current data as list of row dicts")
+    columns:         List[str]              = Field(..., description="Column names")
+    dtypes:          Dict[str, str]         = Field(..., description="Column -> dtype mapping")
+    null_counts:     Dict[str, int]         = Field(..., description="Column -> null count")
+    duplicate_rows:  int                    = Field(..., description="Number of duplicate rows")
+    issues:          List[str]              = Field(..., description="List of detected issues")
+    done:            bool                   = Field(False, description="Is episode over?")
+
+# ── Action ────────────────────────────────────
+class Action(BaseModel):
+    """What the agent can do"""
+
+    action_type: str                        = Field(..., description="""
+        One of:
+        fill_missing | drop_duplicates | fix_dtype |
+        rename_column | remove_outliers |
+        standardize_values | submit
+    """)
+    parameters:  Dict[str, Any]             = Field(default_factory=dict, description="Action parameters")
+
+# ── Reward ────────────────────────────────────
+class Reward(BaseModel):
+    """Score returned after each step"""
+
+    value:    float  = Field(..., description="Reward value for this step")
+    total:    float  = Field(..., description="Cumulative reward so far")
+    reason:   str    = Field(..., description="Why this reward was given")
+
+# ── Step Result ───────────────────────────────
+class StepResult(BaseModel):
+    """Full return value of step()"""
+
+    observation: Observation
+    reward:      Reward
+    done:        bool
+    info:        Dict[str, Any] = Field(default_factory=dict)
+
+# ── Task Info ─────────────────────────────────
+class TaskInfo(BaseModel):
+    """Metadata about a task"""
+
+    task_id:     str
+    difficulty:  str
+    description: str
+    max_steps:   int
+    score:       Optional[float] = None

openenv.yaml

@@ -0,0 +1,129 @@
+# openenv.yaml
+# ─────────────────────────────────────────────
+# OpenEnv metadata specification
+# ─────────────────────────────────────────────
+
+name: data-cleaning-env
+version: 1.0.0
+description: >
+  An OpenEnv environment where an AI agent cleans messy CSV datasets.
+  The agent receives a dataset with issues like missing values, duplicates,
+  outliers, bad column names, and inconsistent values, and must fix them
+  step by step using structured actions.
+
+author: Yashwanth34567
+repository: https://huggingface.co/spaces/Yashwanth34567/data-cleaning-env
+tags:
+  - openenv
+  - data-cleaning
+  - csv
+  - real-world
+  - tabular
+
+# ── Action Space ──────────────────────────────
+actions:
+  - name: fill_missing
+    description: Fill null values in a column
+    parameters:
+      column: string
+      strategy: "mean | median | mode | drop"
+
+  - name: drop_duplicates
+    description: Remove duplicate rows
+    parameters: {}
+
+  - name: fix_dtype
+    description: Convert column to target dtype
+    parameters:
+      column: string
+      target_type: "int | float | str | datetime"
+
+  - name: rename_column
+    description: Rename a column to clean snake_case
+    parameters:
+      old_name: string
+      new_name: string
+
+  - name: remove_outliers
+    description: Remove outlier rows from a numeric column
+    parameters:
+      column: string
+      method: "iqr | zscore"
+
+  - name: standardize_values
+    description: Replace inconsistent values using a mapping
+    parameters:
+      column: string
+      mapping: object
+
+  - name: submit
+    description: Finalize episode and trigger grader
+    parameters: {}
+
+# ── Observation Space ─────────────────────────
+observation:
+  task_id: string
+  difficulty: "easy | medium | hard"
+  step: integer
+  max_steps: integer
+  dataframe: array
+  columns: array
+  dtypes: object
+  null_counts: object
+  duplicate_rows: integer
+  issues: array
+  done: boolean
+
+# ── Reward ────────────────────────────────────
+reward:
+  type: float
+  range: [-1.0, 1.0]
+  description: >
+    Partial progress rewards at each step.
+    +0.10 per issue fixed, +0.30 bonus on clean submit,
+    -0.05 for wrong/redundant actions,
+    -0.10 for destructive actions.
+
+# ── Tasks ─────────────────────────────────────
+tasks:
+  - id: task_1_easy
+    difficulty: easy
+    description: >
+      Fix a 10-row employee dataset.
+      Fill missing values in age and salary columns.
+      Convert age from string to integer dtype.
+    score_range: [0.0, 1.0]
+
+  - id: task_2_medium
+    difficulty: medium
+    description: >
+      Fix a 20-row dataset.
+      Remove duplicate rows.
+      Handle salary outliers using IQR method.
+      Standardize country values to United States or UK.
+    score_range: [0.0, 1.0]
+
+  - id: task_3_hard
+    difficulty: hard
+    description: >
+      Fix a 30-row dataset with all issues combined.
+      Fix bad column names with trailing spaces, uppercase, special chars.
+      Fill missing values, remove duplicates and outliers.
+      Standardize country values.
+      Fix invalid dept_id values for referential integrity.
+    score_range: [0.0, 1.0]
+
+# ── Environment Settings ──────────────────────
+settings:
+  max_steps: 20
+  render_mode: gradio
+  server_host: 0.0.0.0
+  server_port: 7860
+
+# ── API Endpoints ─────────────────────────────
+endpoints:
+  reset: POST /reset
+  step:  POST /step
+  state: GET  /state
+  tasks: GET  /tasks
+  spec:  GET  /openenv.yaml

requirements.txt

@@ -0,0 +1,22 @@
+# requirements.txt
+# ─────────────────────────────────────────────
+# Python dependencies for data-cleaning-env
+# ─────────────────────────────────────────────
+
+# Core
+fastapi==0.115.0
+uvicorn==0.30.6
+gradio==4.44.1
+pydantic==2.9.0
+
+# Data
+pandas==2.2.3
+numpy==1.26.4
+
+# LLM
+openai==2.30.0
+
+# Utils
+pyyaml==6.0.2
+python-multipart==0.0.9
+huggingface-hub==0.25.0

tasks.py

@@ -0,0 +1,174 @@
+# tasks.py
+# ─────────────────────────────────────────────
+# Task definitions for all 3 difficulty levels
+# Each task has a description, dataset, grader
+# ─────────────────────────────────────────────
+
+import pandas as pd
+from typing import Dict, Any, Tuple, Optional
+from config import (
+    TASK_EASY, TASK_MEDIUM, TASK_HARD, TASK_IDS, MAX_STEPS
+)
+from datasets import (
+    generate_easy_dataset,
+    generate_medium_dataset,
+    generate_hard_dataset,
+    detect_issues,
+)
+from graders import grade_task1, grade_task2, grade_task3
+from models import TaskInfo
+
+
+# ── Task Registry ─────────────────────────────
+
+TASK_REGISTRY = {
+    TASK_EASY:   {
+        "task_id":     TASK_IDS[TASK_EASY],
+        "difficulty":  TASK_EASY,
+        "description": (
+            "Fix a 10-row employee dataset: "
+            "fill missing values in 'age' and 'salary', "
+            "convert 'age' from string to integer."
+        ),
+        "max_steps":   MAX_STEPS,
+        "issues": [
+            "missing_values in age and salary columns",
+            "wrong dtype: age should be int not string",
+        ],
+        "hints": [
+            "Use fill_missing to handle null values",
+            "Use fix_dtype to convert age to int",
+            "Call submit when the dataset looks clean",
+        ],
+    },
+    TASK_MEDIUM: {
+        "task_id":     TASK_IDS[TASK_MEDIUM],
+        "difficulty":  TASK_MEDIUM,
+        "description": (
+            "Fix a 20-row dataset: "
+            "remove duplicate rows, "
+            "handle salary outliers, "
+            "standardize country values to 'United States' or 'UK'."
+        ),
+        "max_steps":   MAX_STEPS,
+        "issues": [
+            "duplicate rows present",
+            "salary column has extreme outliers",
+            "country has inconsistent values (USA, US, America, etc.)",
+        ],
+        "hints": [
+            "Use drop_duplicates first",
+            "Use remove_outliers on salary column",
+            "Use standardize_values to unify country names",
+        ],
+    },
+    TASK_HARD:   {
+        "task_id":     TASK_IDS[TASK_HARD],
+        "difficulty":  TASK_HARD,
+        "description": (
+            "Fix a 30-row dataset with all issues: "
+            "nulls, duplicates, outliers, "
+            "bad column names (trailing spaces, uppercase, special chars), "
+            "inconsistent country values, "
+            "and invalid dept_id values (referential integrity)."
+        ),
+        "max_steps":   MAX_STEPS,
+        "issues": [
+            "missing values in multiple columns",
+            "bad column names: 'Full Name ', 'AGE', 'salary$', 'COUNTRY'",
+            "salary outliers and negative values",
+            "inconsistent country values",
+            "invalid dept_id: 99 does not exist in lookup table",
+        ],
+        "hints": [
+            "Start by renaming bad column names",
+            "Then fix nulls, duplicates, and outliers",
+            "Standardize country values",
+            "Fix invalid dept_id values last",
+        ],
+    },
+}
+
+
+# ── Task Class ────────────────────────────────
+
+class Task:
+    """Represents a single task with its dataset and grader"""
+
+    def __init__(self, difficulty: str):
+        if difficulty not in TASK_REGISTRY:
+            raise ValueError(f"Unknown difficulty: {difficulty}")
+
+        self.difficulty  = difficulty
+        self.meta        = TASK_REGISTRY[difficulty]
+        self.task_id     = self.meta["task_id"]
+        self.description = self.meta["description"]
+        self.max_steps   = self.meta["max_steps"]
+        self.hints       = self.meta["hints"]
+
+        # Dataset state
+        self.original_df: Optional[pd.DataFrame] = None
+        self.current_df:  Optional[pd.DataFrame] = None
+        self.lookup_df:   Optional[pd.DataFrame] = None
+        self.issues:      list = []
+
+    def reset(self) -> pd.DataFrame:
+        """Generate a fresh dataset and return it"""
+        if self.difficulty == TASK_EASY:
+            self.original_df = generate_easy_dataset()
+
+        elif self.difficulty == TASK_MEDIUM:
+            self.original_df = generate_medium_dataset()
+
+        elif self.difficulty == TASK_HARD:
+            self.original_df, self.lookup_df = generate_hard_dataset()
+
+        self.current_df = self.original_df.copy()
+        self.issues     = detect_issues(self.current_df, self.task_id)
+        return self.current_df
+
+    def grade(self) -> Tuple[float, Dict[str, Any]]:
+        """Grade the current state of the dataset"""
+        if self.current_df is None or self.original_df is None:
+            return 0.0, {"error": "Task not initialized, call reset() first"}
+
+        if self.difficulty == TASK_EASY:
+            return grade_task1(self.original_df, self.current_df)
+
+        elif self.difficulty == TASK_MEDIUM:
+            return grade_task2(self.original_df, self.current_df)
+
+        elif self.difficulty == TASK_HARD:
+            return grade_task3(
+                self.original_df, self.current_df, self.lookup_df
+            )
+
+        return 0.0, {}
+
+    def update_issues(self):
+        """Refresh issue list based on current state"""
+        if self.current_df is not None:
+            self.issues = detect_issues(self.current_df, self.task_id)
+
+    def get_info(self) -> TaskInfo:
+        """Return TaskInfo model"""
+        score, _ = self.grade() if self.current_df is not None else (None, {})
+        return TaskInfo(
+            task_id     = self.task_id,
+            difficulty  = self.difficulty,
+            description = self.description,
+            max_steps   = self.max_steps,
+            score       = score,
+        )
+
+
+# ── Task Factory ──────────────────────────────
+
+def get_task(difficulty: str) -> Task:
+    """Create and return a Task instance"""
+    return Task(difficulty)
+
+
+def get_all_tasks() -> Dict[str, Task]:
+    """Return all tasks as a dict"""
+    return {d: Task(d) for d in [TASK_EASY, TASK_MEDIUM, TASK_HARD]}

utils.py

@@ -0,0 +1,142 @@
+# utils.py
+# ─────────────────────────────────────────────
+# Helper functions used across the project
+# ─────────────────────────────────────────────
+
+import pandas as pd
+import numpy as np
+from typing import Any, Dict, List, Tuple
+
+
+# ── DataFrame Helpers ─────────────────────────
+
+def df_to_records(df: pd.DataFrame) -> List[Dict[str, Any]]:
+    """Convert DataFrame to list of dicts (for JSON serialization)"""
+    return df.where(pd.notnull(df), None).to_dict(orient="records")
+
+
+def df_summary(df: pd.DataFrame) -> Dict[str, Any]:
+    """Return a quick summary of a DataFrame"""
+    return {
+        "shape":          list(df.shape),
+        "columns":        list(df.columns),
+        "dtypes":         {col: str(dtype) for col, dtype in df.dtypes.items()},
+        "null_counts":    df.isnull().sum().to_dict(),
+        "duplicate_rows": int(df.duplicated().sum()),
+    }
+
+
+def get_null_counts(df: pd.DataFrame) -> Dict[str, int]:
+    """Return null count per column"""
+    return {col: int(count) for col, count in df.isnull().sum().items()}
+
+
+def get_duplicate_count(df: pd.DataFrame) -> int:
+    """Return number of duplicate rows"""
+    return int(df.duplicated().sum())
+
+
+# ── Outlier Helpers ───────────────────────────
+
+def detect_outliers_iqr(df: pd.DataFrame, column: str) -> pd.Series:
+    """Return boolean mask of outliers using IQR method"""
+    Q1  = df[column].quantile(0.25)
+    Q3  = df[column].quantile(0.75)
+    IQR = Q3 - Q1
+    lower = Q1 - 1.5 * IQR
+    upper = Q3 + 1.5 * IQR
+    return (df[column] < lower) | (df[column] > upper)
+
+
+def detect_outliers_zscore(df: pd.DataFrame, column: str,
+                            threshold: float = 3.0) -> pd.Series:
+    """Return boolean mask of outliers using Z-score method"""
+    mean = df[column].mean()
+    std  = df[column].std()
+    if std == 0:
+        return pd.Series([False] * len(df))
+    return ((df[column] - mean) / std).abs() > threshold
+
+
+# ── Column Name Helpers ───────────────────────
+
+def clean_column_name(name: str) -> str:
+    """Normalize a column name to snake_case"""
+    import re
+    name = name.strip().lower()
+    name = re.sub(r"[^a-z0-9_]", "_", name)
+    name = re.sub(r"_+", "_", name)
+    return name.strip("_")
+
+
+def has_bad_column_names(df: pd.DataFrame) -> List[str]:
+    """Return list of columns with bad names"""
+    bad = []
+    for col in df.columns:
+        if col != clean_column_name(col):
+            bad.append(col)
+    return bad
+
+
+# ── Value Standardization ─────────────────────
+
+def standardize_column(df: pd.DataFrame, column: str,
+                        mapping: Dict[str, str]) -> pd.DataFrame:
+    """Replace values in a column using a mapping dict"""
+    df = df.copy()
+    df[column] = df[column].replace(mapping)
+    return df
+
+
+def get_value_counts(df: pd.DataFrame, column: str) -> Dict[str, int]:
+    """Return value counts for a column"""
+    return df[column].value_counts().to_dict()
+
+
+# ── Scoring Helpers ───────────────────────────
+
+def compute_null_score(original_df: pd.DataFrame,
+                        current_df: pd.DataFrame) -> float:
+    """Score based on how many nulls have been fixed (0.0 to 1.0)"""
+    original_nulls = original_df.isnull().sum().sum()
+    if original_nulls == 0:
+        return 1.0
+    current_nulls = current_df.isnull().sum().sum()
+    fixed = original_nulls - current_nulls
+    return round(max(0.0, fixed / original_nulls), 4)
+
+
+def compute_duplicate_score(original_df: pd.DataFrame,
+                              current_df: pd.DataFrame) -> float:
+    """Score based on how many duplicates have been removed (0.0 to 1.0)"""
+    original_dups = original_df.duplicated().sum()
+    if original_dups == 0:
+        return 1.0
+    current_dups = current_df.duplicated().sum()
+    fixed = original_dups - current_dups
+    return round(max(0.0, fixed / original_dups), 4)
+
+
+def compute_dtype_score(df: pd.DataFrame,
+                         expected: Dict[str, str]) -> float:
+    """Score based on how many columns have correct dtype"""
+    if not expected:
+        return 1.0
+    correct = sum(
+        1 for col, dtype in expected.items()
+        if col in df.columns and str(df[col].dtype) == dtype
+    )
+    return round(correct / len(expected), 4)
+
+
+# ── Misc ──────────────────────────────────────
+
+def clamp(value: float, min_val: float = 0.0,
+          max_val: float = 1.0) -> float:
+    """Clamp a float between min and max"""
+    return max(min_val, min(max_val, value))
+
+
+def format_score(score: float) -> str:
+    """Format score for display"""
+    return f"{score:.3f}"