Upload 4 files

Dockerfile

@@ -0,0 +1,48 @@
+# AutoDataLab — Hugging Face Spaces (Docker SDK)
+# Runs the FastAPI / OpenEnv server on port 7860.
+#
+# This is the SUBMISSION entrypoint — it exposes the OpenEnv HTTP API:
+#   POST /reset    POST /step    GET /state    GET /health
+#
+# For the interactive Gradio demo, run locally:  python app.py
+#
+# Secrets (set in HF Space Settings → Repository secrets):
+#   GROQ_API_KEY    optional — only needed if running inference from the Space
+#   HF_TOKEN        optional — same as above
+#
+# Build context: repository root
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# System deps
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy project files
+COPY data_cleaning_env /app/data_cleaning_env
+COPY inference.py validate_submission.py app.py /app/
+
+# Install env package + extras (openai = LLM client + python-docx)
+RUN pip install --no-cache-dir \
+    -e "/app/data_cleaning_env[openai]" \
+    gradio>=4.0.0 \
+    matplotlib>=3.7.0
+
+# Non-root user (HF Spaces requirement)
+RUN useradd -m appuser && chown -R appuser /app
+USER appuser
+
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+EXPOSE 7860
+
+# Health check hits the FastAPI /health endpoint
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD curl -fsS http://127.0.0.1:7860/health || exit 1
+
+# Run the FastAPI server — exposes /reset /step /state for OpenEnv validators
+CMD ["python", "-m", "uvicorn", "data_cleaning_env.server.app:app", \
+     "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,396 @@
 ---
-title: Autodatalab Env
-emoji: 💻
-colorFrom: purple
-colorTo: purple
+title: AutoDataLab Data Cleaning Env
+emoji: 🛒
+colorFrom: blue
+colorTo: indigo
 sdk: docker
 pinned: false
-short_description: An OpenEnv based Data Laboratory
+tags:
+  - openenv
+  - data-cleaning
+  - ecommerce
+  - reinforcement-learning
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# AutoDataLab — E-Commerce Data Analyst Environment
+
+A **hackathon-ready** [OpenEnv](https://github.com/meta-pytorch/OpenEnv) environment that simulates a real e-commerce data analyst workflow.
+
+Clean order-level data, compute business metrics, and declare insightful charts — all scored deterministically against a ground-truth CSV.
+
+---
+
+## What Is This?
+
+Data teams spend a huge fraction of their time on:
+
+- Deduplication
+- Missing value handling
+- Outlier detection and removal
+- Derived columns and rollups
+- Visualization declarations
+
+This environment turns that daily workflow into a **step / reset / state** RL-style API with **deterministic graders** and **dense reward shaping**.
+
+---
+
+## Example Dataset
+
+Columns: `OrderID`, `CustomerID`, `Age`, `Product`, `Category`, `Price`, `Quantity`, `OrderDate`
+
+| OrderID | CustomerID | Age       | Product | Category    | Price     | Quantity | OrderDate  |            |
+|---------|------------|-----------|---------|-------------|-----------|----------|------------|------------|
+| 101     | C001       | 25        | Shoes   | Fashion     | 2000      | 1        | 2023-01-01 |            |
+| 101     | C001       | 25        | Shoes   | Fashion     | 2000      | 1        | 2023-01-01 | ← duplicate |
+| 102     | C002       | *(empty)* | Laptop  | Electronics | 60000     | 1        | 2023-01-02 | ← missing age |
+| 103     | C003       | 200       | T-shirt | Fashion     | 500       | 2        | 2023-01-03 | ← outlier age |
+| 104     | C004       | 30        | Phone   | Electronics | *(empty)* | 1        | 2023-01-04 | ← missing price |
+
+---
+
+## Tasks
+
+| Task | Difficulty | Analyst Goal |
+|------|------------|--------------|
+| `easy` | 🟢 Easy | **Data Cleaning** — dedupe, remove bogus Age outliers, impute Age and Price (mean). 450-row dataset. |
+| `medium` | 🟡 Medium | **Business Metrics** — pre-cleaned data given; run `compute_metrics` → category-level revenue table. |
+| `medium_plus` | 🟠 Medium+ | **Full KPIs** — run `compute_kpis` → `Metric / Value` table with TotalRevenue + AvgOrderValue. |
+| `hard` | 🔴 Hard | **Cleaning + Insight** — full cleaning as in `easy`, then `derive_revenue`, then two declared plots. |
+| `expert` | 🟣 Expert | **Full Pipeline** — cleaning + revenue derivation + both plots (higher step cap). |
+
+Grading uses **cell-wise equality** (with float tolerance for imputed values) vs `tasks/<task>/ground_truth.csv`, weighted with plot correctness when `metadata.json` lists `expected_plots`.
+
+---
+
+## Action Space
+
+`DataCleaningAction` fields:
+
+| Field | Meaning |
+|-------|---------|
+| `action_type` | `remove_duplicates`, `fill_missing`, `drop_column`, `normalize`, `remove_outliers`, `derive_revenue`, `compute_metrics`, `compute_kpis`, `plot`, `export_csv`, `submit`, `noop` |
+| `column` | Target column for column-wise ops |
+| `method` | `mean` / `median` / `mode` — for `fill_missing` |
+| `z_threshold` | Cutoff for robust outlier removal (modified z-score on `log1p` values) |
+| `x`, `y`, `plot_type` | `scatter` / `bar` / `histogram` — for `plot` |
+
+- **`derive_revenue`** adds `Revenue = Price × Quantity`
+- **`compute_metrics`** produces category-level aggregates
+- **`compute_kpis`** computes TotalRevenue + AvgOrderValue
+- **`submit`** finalises the episode; `terminal_grader_score` in `[0, 1]` is returned
+
+---
+
+## Observation Space
+
+`DataCleaningObservation` includes:
+
+| Field | Description |
+|-------|-------------|
+| `preview` | First rows of the working dataframe |
+| `issues` | Heuristic tags (`duplicates`, `missing_values`, …) |
+| `task_name`, `task_difficulty` | Task metadata |
+| `instruction` | Human-readable task description |
+| `history` | Serialised actions taken so far |
+| `reward`, `reward_breakdown` | Immediate, cumulative, and terminal grader score |
+| `terminal_grader_score` | Final score when `done=True` |
+
+---
+
+## Reward Design
+
+**Shaping rewards** — applied at each step:
+
+- Small positive reward for productive actions (rows removed, nulls filled, etc.)
+- Penalties for `noop`, destructive `drop_column`, and repeated identical actions
+
+**Terminal reward** — applied on `submit` (or when `max_steps` is hit):
+
+- `terminal_grader_score` in `[0, 1]` is added to the final step's reward
+- This ensures the last transition carries the primary learning signal
+
+---
+
+## Gradio Web UI
+
+An interactive demo is included at `app.py`:
+
+```bash
+pip install -e "./data_cleaning_env[openai]"
+pip install gradio matplotlib
+
+python app.py           # opens http://127.0.0.1:7861
+python app.py --share   # public Gradio link
+```
+
+**Features:**
+
+- Live **data preview** — table updates after each action
+- **Issue detector** panel — duplicates, missing values, outliers
+- **Manual action form** — dropdowns + fields → JSON preview
+- **Oracle step / Run full oracle** buttons
+- **Score badge** on submit
+- **Plot gallery** — renders charts inline when plot actions are taken
+- **Download Word report** (`.docx`) button
+- Task selector with pipeline hints (dark mode compatible)
+
+---
+
+## Setup
+
+```bash
+cd data_cleaning_env
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Validate the OpenEnv layout:
+
+```bash
+openenv validate --verbose
+```
+
+---
+
+## Run the FastAPI Server
+
+```bash
+cd data_cleaning_env
+uvicorn server.app:app --host 0.0.0.0 --port 7860
+```
+
+- Web UI: `/web`
+- API docs: `/docs`
+- Health check: `/health`
+
+---
+
+## Baseline Inference (Reproducible Scores)
+
+### Oracle (no API key — deterministic 1.0 on all tasks)
+
+```bash
+cd data_cleaning_env
+
+python baseline_inference.py --oracle
+
+python baseline_inference.py --oracle --tasks easy,medium,medium_plus,hard,expert
+```
+
+### Word Reports
+
+Install `python-docx`:
+
+```bash
+pip install -e ".[report]"
+# or
+pip install -e ".[openai]"
+```
+
+By default, reports are written to `./reports/` (`session_report.docx` plus per-task episode reports).
+
+Override with `--report-dir DIR` or `AUTODATALAB_REPORT_DIR`. Disable with `--no-report`.
+
+---
+
+## LLM Baseline
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY=sk-...
+# optional: OPENAI_BASE_URL, MODEL_NAME (default: gpt-4o-mini)
+
+python baseline_inference.py --provider openai
+```
+
+### Groq
+
+```bash
+export GROQ_API_KEY=gsk_...
+
+export OPENAI_BASE_URL=https://api.groq.com/openai/v1
+export MODEL_NAME=llama-3.1-8b-instant
+
+python baseline_inference.py --provider groq
+```
+
+### Google Gemini
+
+```bash
+export GEMINI_API_KEY=...   # from Google AI Studio
+
+# optional: GEMINI_MODEL=gemini-1.5-flash (default)
+
+python baseline_inference.py --provider gemini
+```
+
+### Auto Provider Detection
+
+`LLM_PROVIDER=auto` (or unset) checks keys in this order: `OPENAI_API_KEY` → `GROQ_API_KEY` → `GEMINI_API_KEY`.
+
+> **Tip:** if `OPENAI_API_KEY` looks like a Groq key (`gsk_`) and `GEMINI_API_KEY` is also set, Gemini is used automatically. Use `--provider groq` or `--provider gemini` to force a specific backend.
+
+### Tips for Faster LLM Runs
+
+- Use `--tasks easy` (or `easy,medium`) for quick single-task checks
+- Pass `--no-report` to skip Word export overhead
+- Use `--provider groq` with `llama-3.1-8b-instant` for the fastest completions
+- Set `LLM_JSON_MODE=0` if JSON mode causes extra round-trips on your backend
+- Lower `--llm-retry-delay` only if you are not hitting 429 rate limits
+
+---
+
+## Baseline Scores (Oracle)
+
+| Task | Terminal Grader |
+|------|:---------------:|
+| easy | **1.0** |
+| medium | **1.0** |
+| hard | **1.0** |
+| **mean** | **1.0** |
+
+---
+
+## Docker (Local)
+
+From the repository root:
+
+```bash
+docker build -t autodatalab-openenv .
+docker run --rm -p 7860:7860 autodatalab-openenv
+```
+
+---
+
+## Hugging Face Spaces
+
+1. Push this repo to a **Docker** Space on Hugging Face.
+2. Use the root **`Dockerfile`** (build context = repo root).
+3. The server listens on **`PORT`** (default `7860`; matches `openenv.yaml`).
+4. Tag the Space with **`openenv`** (see `data_cleaning_env/README.md` frontmatter).
+5. Health check: `GET /health` should return **200**.
+
+Or push directly from `data_cleaning_env/`:
+
+```bash
+openenv push
+```
+
+*(requires `huggingface-cli` login)*
+
+---
+
+## Submission / Course Alignment
+
+This repo follows the OpenEnv environment pattern from [**Building RL Environments with OpenEnv**](https://github.com/raun/openenv-course).
+
+**Root `inference.py`** — required entry point for hackathons:
+
+| Variable | Role |
+|----------|------|
+| `API_BASE_URL` | OpenAI-compatible base URL |
+| `MODEL_NAME` | Model ID |
+| `HF_TOKEN` | API key (mapped to `OPENAI_API_KEY`) |
+
+Copy **`.env.example`** to `.env` and fill values. Run `--oracle` to validate without an API key.
+
+**Pre-flight checks:**
+
+```bash
+pip install -e ./data_cleaning_env
+pip install -e "./data_cleaning_env[dev]"   # optional: pytest
+
+python validate_submission.py
+```
+
+This runs `openenv validate`, `pytest`, grader checks on easy / medium / hard, and `python inference.py --oracle`. Add `--docker` to also run `docker build`.
+
+---
+
+## Project Layout
+
+```
+.
+├── data_cleaning_env/        # OpenEnv package (models, server, client, tasks, openenv.yaml)
+├── app.py                    # Gradio Web UI
+├── Dockerfile                # HF Spaces / container entrypoint
+├── inference.py              # Root inference script (delegates to baseline_inference.py)
+├── validate_submission.py    # Pre-submission checks
+└── .env.example              # Template for API_BASE_URL, MODEL_NAME, HF_TOKEN
+```
+
+---
+
+---
+
+## Submission Checklist
+
+Use this before pasting your HF Spaces URL.
+
+### Step 1 — Set environment variables
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `API_BASE_URL` | Yes | OpenAI-compatible base URL (e.g. Groq, OpenAI) |
+| `MODEL_NAME` | Yes | Model ID (e.g. `llama-3.1-8b-instant`) |
+| `HF_TOKEN` | Yes | Your API key (mapped to `OPENAI_API_KEY`) |
+
+### Step 2 — Run the validator
+
+```bash
+python validate_submission.py
+```
+
+This automatically checks all of the following:
+
+| Check | What it validates |
+|-------|------------------|
+| `openenv validate` | `openenv.yaml` spec, typed models, endpoint layout |
+| `pytest` | Unit tests pass |
+| Grader identity check | `easy`, `medium`, `hard` graders return scores in `[0.0, 1.0]` |
+| Oracle inference | `inference.py --oracle` completes without error and produces scores |
+| Docker build *(optional)* | `python validate_submission.py --docker` |
+
+### Step 3 — Deploy to HF Spaces
+
+```bash
+# From data_cleaning_env/
+openenv push --repo-id your-username/my-env
+```
+
+Or push the repo to a **Docker** Space manually (see Hugging Face Spaces section above).
+
+### Step 4 — Verify the live Space
+
+```bash
+# Must return HTTP 200
+curl https://your-username-my-env.hf.space/health
+
+# Must accept reset()
+curl -X POST https://your-username-my-env.hf.space/reset \
+     -H "Content-Type: application/json" \
+     -d '{"task": "easy"}'
+```
+
+### Step 5 — Final pre-submit check
+
+- [ ] `inference.py` is in the **root directory**
+- [ ] `API_BASE_URL`, `MODEL_NAME`, `HF_TOKEN` are defined in your environment / Space secrets
+- [ ] All LLM calls go through the **OpenAI Python client** (`from openai import OpenAI`)
+- [ ] Oracle inference finishes in **< 20 minutes** on 2 vCPU / 8 GB RAM
+- [ ] `python validate_submission.py` exits with code **0**
+- [ ] HF Space URL returns **200** and responds to **`POST /reset`**
+- [ ] At least **3 tasks** are registered in `openenv.yaml` with working graders
+
+---
+
+## License
+
+Environment scaffold includes Meta/OpenEnv BSD-style headers; see files inside `data_cleaning_env/`.

inference.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Root inference entrypoint (hackathon / HF submission).
+
+Required environment variables (see also ``.env.example``):
+  API_BASE_URL   OpenAI-compatible API base URL (e.g. Groq or OpenAI).
+  MODEL_NAME     Chat model id for the OpenAI client.
+  HF_TOKEN       API key passed to the OpenAI client (``OPENAI_API_KEY`` is set from this).
+
+Word reports: by default writes under ``./reports`` (override with ``--report-dir`` or
+``AUTODATALAB_REPORT_DIR``; disable with ``--no-report``). Requires ``python-docx``
+(``pip install -e "./data_cleaning_env[openai]"`` or ``[report]``).
+
+All LLM calls use the ``openai`` Python package (``OpenAI`` client) against ``API_BASE_URL``.
+
+Designed to finish within typical contest limits (e.g. <20 minutes) on modest hardware (e.g. 2 vCPU / 8GB RAM).
+
+Course context: `Building RL Environments with OpenEnv <https://github.com/raun/openenv-course>`_.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def _apply_submission_env() -> None:
+    """Map submission variable names onto what ``baseline_inference`` / OpenAI client expect."""
+    token = (os.environ.get("HF_TOKEN") or "").strip().strip('"').strip("'")
+    if token and not (os.environ.get("OPENAI_API_KEY") or "").strip():
+        os.environ["OPENAI_API_KEY"] = token
+    base = (os.environ.get("API_BASE_URL") or "").strip().rstrip("/")
+    if base:
+        os.environ["OPENAI_BASE_URL"] = base
+        os.environ.setdefault("API_BASE_URL", base)
+    model = (os.environ.get("MODEL_NAME") or "").strip()
+    if model:
+        os.environ["MODEL_NAME"] = model
+
+
+def main() -> None:
+    _apply_submission_env()
+    repo = Path(__file__).resolve().parent
+    if str(repo) not in sys.path:
+        sys.path.insert(0, str(repo))
+
+    from data_cleaning_env.baseline_inference import main as baseline_main
+
+    baseline_main()
+
+
+if __name__ == "__main__":
+    main()

validate_submission.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""
+Pre-submission checks: OpenEnv layout, unit tests, oracle inference, grader scores in [0,1].
+
+Run from repository root (after ``pip install -e data_cleaning_env`` or ``pip install -e ./data_cleaning_env``):
+
+  python validate_submission.py
+
+Optional:
+
+  python validate_submission.py --docker    # also ``docker build`` (requires Docker)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+ENV_DIR = ROOT / "data_cleaning_env"
+
+
+def _openenv_cli() -> str | None:
+    """Resolve ``openenv`` executable (same venv as this script, then PATH)."""
+    sibling = Path(sys.executable).resolve().parent / "openenv"
+    if sibling.is_file():
+        return str(sibling)
+    return shutil.which("openenv")
+
+
+def run(cmd: list[str], *, cwd: Path | None = None) -> int:
+    print(f"$ {' '.join(cmd)}", flush=True)
+    return subprocess.call(cmd, cwd=cwd or ROOT)
+
+
+def check_graders_three_tasks() -> int:
+    """Run bundled easy/medium/hard graders; scores must be in [0, 1]."""
+    import pandas as pd
+
+    sys.path.insert(0, str(ROOT))
+    from data_cleaning_env.graders import grade_task
+
+    for name in ("easy", "medium", "hard"):
+        tdir = ENV_DIR / "tasks" / name
+        gt = pd.read_csv(tdir / "ground_truth.csv")
+        with open(tdir / "metadata.json", encoding="utf-8") as f:
+            meta = json.load(f)
+        # Build a synthetic perfect plot action matching the first expected plot (if any)
+        plot_action = None
+        expected = meta.get("expected_plots")
+        if expected:
+            ep = expected[0]
+            plot_action = {
+                "plot_type": ep.get("type", "scatter"),
+                "x": ep.get("x", "OrderDate"),
+                "y": ep.get("y", "Revenue"),
+            }
+        s = grade_task(gt, gt, meta, plot_action, None)
+        if s is None:
+            print(f"FAIL: grader returned None for task={name}", file=sys.stderr)
+            return 1
+        if not (0.0 <= float(s) <= 1.0):
+            print(f"FAIL: task={name} score {s} not in [0,1]", file=sys.stderr)
+            return 1
+        print(f"ok: task={name} identity grader score={s:.4f}", flush=True)
+    return 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Pre-submission validation")
+    ap.add_argument(
+        "--docker",
+        action="store_true",
+        help="Run docker build from repo root (requires Docker daemon)",
+    )
+    args = ap.parse_args()
+    code = 0
+
+    if not ENV_DIR.is_dir():
+        print(f"Missing {ENV_DIR}", file=sys.stderr)
+        return 1
+
+    oe = _openenv_cli()
+    if not oe:
+        print(
+            "openenv CLI not found. Install with: pip install 'openenv-core[core]'",
+            file=sys.stderr,
+        )
+        return 1
+
+    r = run([oe, "validate", "--verbose", str(ENV_DIR)])
+    code |= r
+    if r != 0:
+        return code
+
+    r = run([sys.executable, "-m", "pytest", "tests/", "-q"], cwd=ENV_DIR)
+    code |= r
+    if r != 0:
+        return code
+
+    r = check_graders_three_tasks()
+    code |= r
+    if r != 0:
+        return code
+
+    r = run([sys.executable, str(ROOT / "inference.py"), "--oracle", "--no-report"])
+    code |= r
+    if r != 0:
+        return code
+
+    if args.docker:
+        r = run(
+            [
+                "docker",
+                "build",
+                "-t",
+                "autodatalab-openenv",
+                "-f",
+                str(ROOT / "Dockerfile"),
+                str(ROOT),
+            ]
+        )
+        code |= r
+
+    if code == 0:
+        print("validate_submission: all checks passed.", flush=True)
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())