feat: SQL Analytics OpenEnv environment — 10 tasks, dense rewards, RL-ready

.dockerignore

@@ -0,0 +1,43 @@
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Test files
+test_env.py
+tests/
+.pytest_cache/
+
+# Build artifacts
+*.egg-info/
+dist/
+build/
+
+# Logs
+*.log
+outputs/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Local env files
+.env
+.env.*

.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.env
+*.log
+test_output.txt
+test_err.txt
+workspace/

Dockerfile

@@ -0,0 +1,48 @@
+# ── SQL Analytics OpenEnv — Dockerfile ───────────────────────────────────────
+# Compatible with HuggingFace Spaces (Docker SDK)
+# Runtime: python:3.11-slim  |  Port: 8000  |  User: non-root (appuser)
+
+FROM python:3.11-slim
+
+LABEL maintainer="sql-analytics-env"
+LABEL version="0.1.0"
+LABEL description="SQL Analytics OpenEnv environment for RL agents"
+
+# Keeps Python from generating .pyc files + enables unbuffered stdout logging
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONIOENCODING=utf-8
+
+WORKDIR /app
+
+# Install system dependencies (build-essential needed for some pip wheels)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Install Python dependencies BEFORE copying source code ───────────────────
+# (Docker layer cache: re-run only when pyproject.toml changes, not source)
+COPY pyproject.toml ./
+RUN pip install --upgrade pip && \
+    pip install \
+        "openenv-core>=0.1.0" \
+        "fastapi>=0.110.0" \
+        "uvicorn[standard]>=0.29.0" \
+        "pydantic>=2.0.0"
+
+# ── Copy application source ───────────────────────────────────────────────────
+COPY . .
+
+# ── Health check (Docker-native, used by orchestrators) ──────────────────────
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# ── Non-root user (required by HuggingFace Spaces) ───────────────────────────
+RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 8000
+
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "1"]

README.md

@@ -0,0 +1,226 @@
+# SQL Analytics OpenEnv Environment
+
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
+![OpenEnv](https://img.shields.io/badge/OpenEnv-spec__v1-green)
+![License](https://img.shields.io/badge/License-MIT-yellow)
+![Tasks](https://img.shields.io/badge/Tasks-6%20(easy%2Fmedium%2Fhard)-orange)
+
+A real-world OpenEnv environment where an AI agent answers business-intelligence
+questions by writing SQL queries against a seeded e-commerce database.
+
+---
+
+## Overview
+
+The agent interacts with a **SQLite e-commerce database** containing:
+
+| Table        | Rows  | Description                                  |
+|--------------|-------|----------------------------------------------|
+| customers    |  100  | Registered users with US state + signup date |
+| categories   |    5  | Electronics, Clothing, Books, Food, Sports   |
+| products     |   50  | Name, category, price, stock                 |
+| orders       |  500  | Date, total amount, status (delivered/…)     |
+| order_items  | 1000+ | Per-line quantity and unit price             |
+| reviews      |  300  | 1–5 star ratings per product                 |
+
+---
+
+## Database Schema
+
+```
+customers(id, name, email, state, signup_date, last_order_date)
+categories(id, name)
+products(id, name, category_id, price, stock)
+orders(id, customer_id, order_date, total_amount, status)
+order_items(id, order_id, product_id, quantity, unit_price)
+reviews(id, product_id, customer_id, rating, review_date)
+```
+
+---
+
+## Tasks
+
+| Task ID   | Difficulty | Question                                              |
+|-----------|------------|-------------------------------------------------------|
+| task_001  | Easy       | Count customers from California                       |
+| task_002  | Easy       | Name + price of the most expensive Electronics item   |
+| task_003  | Medium     | Top 5 customers by total spend                        |
+| task_004  | Medium     | Product category with highest average rating          |
+| task_005  | Hard       | Q1-2024-only buyers (early-churn signal)              |
+| task_006  | Hard       | Monthly 2024 revenue + month-over-month growth rate   |
+
+---
+
+## Action / Observation Spaces
+
+### Action — `SQLAction`
+
+| Field | Type | Description                           |
+|-------|------|---------------------------------------|
+| `sql` | str  | SQL SELECT query (SQLite dialect)     |
+
+### Observation — `SQLObservation`
+
+| Field              | Type               | Description                              |
+|--------------------|--------------------|------------------------------------------|
+| `result`           | `list[dict] / None`| Query result rows                        |
+| `error`            | `str / None`       | SQL error message (if any)               |
+| `db_schema`        | `str / None`       | Full schema description (on reset only)  |
+| `task_description` | `str / None`       | Natural-language task question           |
+| `reward`           | `float`            | Partial-progress reward  [0.0 – 1.0]    |
+| `done`             | `bool`             | True when episode ends                   |
+| `metadata`         | `dict`             | task_id, difficulty, attempts, message   |
+
+### Reward Signal (partial progress)
+
+| Condition                            | Reward    |
+|--------------------------------------|-----------|
+| SQL syntax / write-op error          | 0.0       |
+| Valid SQL but wrong answer           | 0.1 – 0.5 |
+| Near-correct (close count / overlap) | 0.5 – 0.9 |
+| Correct answer                       | 1.0       |
+
+### Episode ends (`done=True`) when:
+1. Agent submits a correct answer (`reward >= 0.9`)
+2. Agent exhausts 10 attempts without solving
+3. `step()` called before `reset()`
+
+---
+
+## Installation
+
+### Prerequisites
+- Python 3.10+
+- pip
+- (Optional) Docker for containerized deployment
+
+### Setup
+
+```bash
+# Clone / navigate to the environment folder
+cd sql_analytics_env
+
+# Create and activate virtual environment
+python -m venv .venv
+.venv\Scripts\activate        # Windows
+# source .venv/bin/activate   # Mac/Linux
+
+# Install dependencies
+pip install openenv-core fastapi "uvicorn[standard]" pydantic "openai>=1.30.0"
+```
+
+---
+
+## Running Locally
+
+### Start the server
+
+```bash
+uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### Verify health
+
+```bash
+curl.exe http://localhost:8000/health
+# {"status": "ok", "environment": "sql_analytics_env", "version": "0.1.0"}
+```
+
+### Browse API docs
+
+Open in browser: **http://localhost:8000/docs** (Swagger UI)
+
+### Run smoke tests
+
+```bash
+python -X utf8 test_env.py
+```
+
+Expected: all `[PASS]`, Average correct reward = 1.00
+
+---
+
+## Docker
+
+```bash
+# Build
+docker build -t sql-analytics-env .
+
+# Run
+docker run -p 8000:8000 sql-analytics-env
+
+# Verify
+curl http://localhost:8000/health
+```
+
+---
+
+## Running the Baseline Agent
+
+```bash
+# Set LLM credentials
+set OPENAI_API_KEY=sk-your-key-here        # Windows CMD
+# export OPENAI_API_KEY=sk-your-key-here  # Mac/Linux / PowerShell
+
+# Optional overrides
+set MODEL_NAME=gpt-4o-mini
+set ENV_BASE_URL=http://localhost:8000
+set MAX_STEPS=8
+
+# Run inference
+python -X utf8 inference.py
+```
+
+### Expected output
+
+```
+[START] {"task_id": "task_001", "task_description": "...", "difficulty": "easy", ...}
+[STEP]  {"task_id": "task_001", "step": 1, "sql": "SELECT COUNT(*) ...", "reward": 1.0, ...}
+[END]   {"task_id": "task_001", "final_score": 1.0, "total_steps": 1, "success": true, ...}
+...
+{"summary": {"scores": {...}, "average_score": 0.95, "tasks_solved": 6, "total_tasks": 6}}
+```
+
+Runs in well under **20 minutes** on a 2 vCPU / 8 GB machine.
+
+---
+
+## HuggingFace Spaces Deployment
+
+1. Create a new Space → **Docker** SDK type
+2. Push this folder as the Space repository root
+3. HF Spaces builds from `Dockerfile` and serves on port 8000
+4. Set `ENV_BASE_URL=https://<your-space>.hf.space` in your inference runner
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `uvicorn: command not found` | Activate venv: `.venv\Scripts\activate` |
+| `Port 8000 already in use` | Use `--port 8001` |
+| `ModuleNotFoundError: openenv` | Run `pip install openenv-core` |
+| Unicode error on Windows | Always use `python -X utf8 inference.py` |
+| `curl` not working in PowerShell | Use `curl.exe` or `Invoke-WebRequest -UseBasicParsing` |
+| LLM rate limit in inference.py | Agent auto-retries with exponential backoff |
+| SQL query times out | Queries limited to 5 seconds; simplify your query |
+
+---
+
+## Pre-submission Checklist
+
+- [x] HF Space returns HTTP 200 on `/health`
+- [x] `openenv.yaml` passes `openenv validate`
+- [x] `Dockerfile` builds successfully with HEALTHCHECK
+- [x] `inference.py` in root directory
+- [x] Baseline script runs in < 20 minutes
+- [x] Structured `[START]` / `[STEP]` / `[END]` stdout logging
+- [x] 6 tasks with easy / medium / hard graders
+- [x] Partial-progress reward functions (0.0 to 1.0)
+- [x] Compatible with 2 vCPU / 8 GB deployment
+- [x] CORS enabled for cross-origin access
+- [x] Query timeout (5s) prevents hangs
+- [x] Write-operation blocking (SELECT only)
+- [x] Retry logic in inference.py for LLM failures
+- [x] `.dockerignore` excludes venv and cache files

__init__.py

@@ -0,0 +1,9 @@
+"""SQL Analytics OpenEnv environment package."""
+
+try:
+    from .models import SQLAction, SQLObservation, SQLState
+    from .client import SQLAnalyticsEnv
+except ImportError:
+    pass
+
+__all__ = ["SQLAction", "SQLObservation", "SQLState", "SQLAnalyticsEnv"]

client.py

@@ -0,0 +1,61 @@
+"""
+client.py
+---------
+Client for the SQL Analytics Environment.
+
+SQLAnalyticsEnv wraps EnvClient with the three typed models specific to
+this environment (SQLAction, SQLObservation, SQLState).  All connection
+and session management is inherited from EnvClient.
+
+Example usage
+-------------
+# Against a local server:
+    with SQLAnalyticsEnv(base_url="http://localhost:8000") as env:
+        obs = env.reset(task_id="task_003")
+        print(obs.task_description)
+
+        result_obs = env.step(
+            SQLAction(sql="SELECT name, SUM(total_amount) FROM ...")
+        )
+        print(result_obs.result, result_obs.reward)
+
+# Against a HuggingFace Space:
+    env = SQLAnalyticsEnv.from_env("your-hf-username/sql-analytics-env")
+    try:
+        obs = env.reset(task_id="task_001")
+        ...
+    finally:
+        env.close()
+
+# From a local Docker image:
+    env = SQLAnalyticsEnv.from_docker_image("sql-analytics-env:latest")
+    try:
+        obs = env.reset(task_id="task_002")
+        ...
+    finally:
+        env.close()
+"""
+
+from openenv.core.env_client import EnvClient
+
+try:
+    from .models import SQLAction, SQLObservation, SQLState
+except ImportError:
+    from models import SQLAction, SQLObservation, SQLState
+
+
+class SQLAnalyticsEnv(EnvClient[SQLAction, SQLObservation, SQLState]):
+    """
+    Typed client for the SQL Analytics OpenEnv environment.
+
+    Inherits the full EnvClient interface:
+        reset(**kwargs) -> SQLObservation
+        step(action: SQLAction) -> SQLObservation
+        state() -> SQLState
+        close()
+
+    Convenience class methods (from EnvClient):
+        SQLAnalyticsEnv.from_env(hf_repo_id)
+        SQLAnalyticsEnv.from_docker_image(image_tag)
+    """
+    pass

inference.py

@@ -0,0 +1,310 @@
+"""
+inference.py
+------------
+Baseline LLM agent for the SQL Analytics OpenEnv environment.
+
+The agent receives a natural-language business-intelligence question,
+iteratively generates SQL queries using an LLM (via OpenAI-compatible
+API), executes them in the environment, and improves based on feedback.
+
+Logging
+-------
+Every event is printed to stdout in the strictly-required format:
+
+    [START] {"task_id": ..., "task_description": ..., "difficulty": ...}
+    [STEP]  {"task_id": ..., "step": ..., "sql": ..., "reward": ...,
+             "result_rows": ..., "error": ..., "done": ...}
+    [END]   {"task_id": ..., "final_score": ..., "total_steps": ...,
+             "success": ..., "timestamp": ...}
+
+Environment variables
+---------------------
+    API_BASE_URL   Base URL for the OpenAI-compatible LLM endpoint
+                   (default: https://api.openai.com/v1)
+    MODEL_NAME     LLM model to use (default: gpt-4o-mini)
+    HF_TOKEN       HuggingFace token when connecting to HF Spaces
+    ENV_BASE_URL   URL of the running sql_analytics_env server
+                   (default: http://localhost:8000)
+    MAX_STEPS      Max LLM turns per task (default: 8)
+
+Usage
+-----
+    # Against local server started with:  uvicorn server.app:app --port 8000
+    python inference.py
+
+    # Against a HuggingFace Space:
+    ENV_BASE_URL=https://<your-space>.hf.space python inference.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+from openai import OpenAI, RateLimitError, APIConnectionError, APIStatusError
+
+# ── Environment client ────────────────────────────────────────────────────────
+# Support running inference.py both as standalone and inside the package.
+try:
+    from client import SQLAnalyticsEnv
+    from models import SQLAction
+except ImportError:
+    from sql_analytics_env.client import SQLAnalyticsEnv
+    from sql_analytics_env.models import SQLAction
+
+# ── Config ────────────────────────────────────────────────────────────────────
+
+API_BASE_URL = os.environ.get("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME   = os.environ.get("MODEL_NAME",   "gpt-4o-mini")
+ENV_BASE_URL = os.environ.get("ENV_BASE_URL", "http://localhost:8000")
+MAX_STEPS    = int(os.environ.get("MAX_STEPS", "8"))
+
+ALL_TASK_IDS = [
+    "task_001",  # easy
+    "task_002",  # easy
+    "task_003",  # medium
+    "task_004",  # medium
+    "task_005",  # hard
+    "task_006",  # hard
+    "task_007",  # easy
+    "task_008",  # easy
+    "task_009",  # medium
+    "task_010",  # medium
+]
+
+# ── Logging helpers ───────────────────────────────────────────────────────────
+
+def _emit(tag: str, payload: Dict[str, Any]) -> None:
+    """Print a structured log line to stdout (required evaluation format)."""
+    print(f"[{tag}] {json.dumps(payload, default=str)}", flush=True)
+
+
+def log_start(task_id: str, task_description: str, difficulty: str) -> None:
+    _emit("START", {
+        "task_id":          task_id,
+        "task_description": task_description,
+        "difficulty":       difficulty,
+        "timestamp":        datetime.now(timezone.utc).isoformat(),
+    })
+
+
+def log_step(
+    task_id: str,
+    step:    int,
+    sql:     str,
+    reward:  float,
+    result_rows: int,
+    error:   Optional[str],
+    done:    bool,
+) -> None:
+    _emit("STEP", {
+        "task_id":     task_id,
+        "step":        step,
+        "sql":         sql,
+        "reward":      reward,
+        "result_rows": result_rows,
+        "error":       error,
+        "done":        done,
+    })
+
+
+def log_end(
+    task_id:     str,
+    final_score: float,
+    total_steps: int,
+    success:     bool,
+) -> None:
+    _emit("END", {
+        "task_id":     task_id,
+        "final_score": final_score,
+        "total_steps": total_steps,
+        "success":     success,
+        "timestamp":   datetime.now(timezone.utc).isoformat(),
+    })
+
+
+# ── LLM helpers ───────────────────────────────────────────────────────────────
+
+_SYSTEM_PROMPT = """You are an expert SQL analyst. You will be given a business
+intelligence question about an e-commerce database and must answer it by
+writing a single SQL query.
+
+Rules:
+- Write ONLY the raw SQL query — no markdown, no explanation, no backticks.
+- The database is SQLite; use SQLite-compatible syntax.
+- Use ROUND(..., 2) for monetary values and ratings.
+- Use strftime('%m', date_column) to extract the month as a string;
+  CAST(strftime('%m', ...) AS INTEGER) for an integer.
+- When asked for growth rate you may use a self-join or a subquery
+  (SQLite does not always support window functions LAG).
+- Return only the columns asked for in the task description.
+"""
+
+def _build_user_message(
+    schema:           str,
+    task_description: str,
+    history:          List[Dict],
+) -> str:
+    """Build the user turn including schema, task, and any prior attempt feedback."""
+    lines = [
+        "DATABASE SCHEMA:",
+        schema,
+        "",
+        "TASK:",
+        task_description,
+    ]
+
+    if history:
+        lines += ["", "PREVIOUS ATTEMPTS (most recent first):"]
+        for attempt in reversed(history[-3:]):   # show last 3
+            lines.append(f"  SQL: {attempt['sql']}")
+            if attempt.get("error"):
+                lines.append(f"  Error: {attempt['error']}")
+            else:
+                rows = attempt.get("result_rows", 0)
+                reward = attempt.get("reward", 0.0)
+                msg = attempt.get("message", "")
+                lines.append(f"  Rows returned: {rows} | Reward: {reward:.2f} | Feedback: {msg}")
+        lines += ["", "Please write an improved SQL query."]
+    else:
+        lines += ["", "Write the SQL query:"]
+
+    return "\n".join(lines)
+
+
+def _extract_sql(llm_response: str) -> str:
+    """Strip markdown fences and whitespace from the LLM output."""
+    sql = llm_response.strip()
+    for fence in ("```sql", "```SQL", "```"):
+        if sql.startswith(fence):
+            sql = sql[len(fence):]
+            if "```" in sql:
+                sql = sql[: sql.index("```")]
+            break
+    return sql.strip()
+
+
+# ── Agent loop ────────────────────────────────────────────────────────────────
+
+def run_task(
+    client:  OpenAI,
+    env:     SQLAnalyticsEnv,
+    task_id: str,
+) -> float:
+    """Run one task episode. Returns the final score (0.0–1.0)."""
+    # Reset
+    obs = env.reset(task_id=task_id)
+    schema           = obs.db_schema or ""
+    task_description = obs.task_description or ""
+    difficulty       = obs.metadata.get("difficulty", "?") if obs.metadata else "?"
+
+    log_start(task_id, task_description, difficulty)
+
+    history: List[Dict] = []
+    final_score = 0.0
+    step_count  = 0
+
+    for step in range(1, MAX_STEPS + 1):
+        # Ask LLM (with retry + exponential backoff)
+        user_msg = _build_user_message(schema, task_description, history)
+        sql = ""
+        for attempt in range(1, 4):   # up to 3 retries
+            try:
+                response = client.chat.completions.create(
+                    model=MODEL_NAME,
+                    messages=[
+                        {"role": "system", "content": _SYSTEM_PROMPT},
+                        {"role": "user",   "content": user_msg},
+                    ],
+                    temperature=0.0,
+                    max_tokens=512,
+                )
+                sql = _extract_sql(response.choices[0].message.content or "")
+                break   # success
+            except RateLimitError:
+                wait = 2 ** attempt
+                print(f"[WARN] Rate limited — waiting {wait}s (attempt {attempt}/3)", file=sys.stderr)
+                time.sleep(wait)
+            except APIConnectionError as exc:
+                print(f"[WARN] Connection error on step {step}, attempt {attempt}: {exc}", file=sys.stderr)
+                time.sleep(2)
+            except APIStatusError as exc:
+                print(f"[WARN] API error {exc.status_code} on step {step}: {exc.message}", file=sys.stderr)
+                break
+            except Exception as exc:
+                print(f"[WARN] Unexpected LLM error on step {step}: {exc}", file=sys.stderr)
+                break
+
+        if not sql:
+            print(f"[WARN] No SQL generated for step {step} — skipping.", file=sys.stderr)
+            break
+
+        if not sql:
+            break
+
+        # Execute in environment
+        obs = env.step(SQLAction(sql=sql))
+
+        result_rows = len(obs.result) if obs.result else 0
+        reward      = obs.reward or 0.0
+        error       = obs.error
+        done        = obs.done
+        message     = (obs.metadata or {}).get("message", "")
+        step_count  = step
+
+        log_step(task_id, step, sql, reward, result_rows, error, done)
+
+        history.append({
+            "sql":         sql,
+            "error":       error,
+            "result_rows": result_rows,
+            "reward":      reward,
+            "message":     message,
+        })
+
+        final_score = reward
+
+        if done:
+            break
+
+    success = final_score >= 0.9
+    log_end(task_id, final_score, step_count, success)
+    return final_score
+
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def main() -> None:
+    llm_client = OpenAI(base_url=API_BASE_URL)
+    env        = SQLAnalyticsEnv(base_url=ENV_BASE_URL)
+
+    scores: Dict[str, float] = {}
+
+    try:
+        for task_id in ALL_TASK_IDS:
+            score = run_task(llm_client, env, task_id)
+            scores[task_id] = score
+    finally:
+        env.close()
+
+    # Summary
+    avg = sum(scores.values()) / len(scores) if scores else 0.0
+    print(
+        json.dumps({
+            "summary": {
+                "scores":        scores,
+                "average_score": round(avg, 4),
+                "tasks_solved":  sum(1 for s in scores.values() if s >= 0.9),
+                "total_tasks":   len(scores),
+            }
+        }),
+        flush=True,
+    )
+
+
+if __name__ == "__main__":
+    main()

models.py

@@ -0,0 +1,72 @@
+"""
+models.py
+---------
+Action / Observation / State typed models for the SQL Analytics environment.
+
+The agent submits a SQL query (SQLAction) and receives back the query
+result rows, any SQL error, the current task description, and reward
+signal (SQLObservation).  Episode metadata is tracked in SQLState.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field, field_validator
+
+try:
+    from openenv.core.env_server.interfaces import Action, Observation, State
+except ImportError:
+    from openenv.core.env_server.types import Action, Observation, State
+
+
+class SQLAction(Action):
+    """
+    A single SQL query submitted by the agent.
+
+    Example::
+
+        SQLAction(sql="SELECT COUNT(*) FROM customers WHERE state = 'CA'")
+    """
+
+    sql: str = Field(
+        ...,
+        min_length=1,
+        description="SQL SELECT query to execute against the e-commerce database.",
+        json_schema_extra={"example": "SELECT COUNT(*) FROM customers WHERE state = 'CA'"},
+    )
+
+    @field_validator("sql")
+    @classmethod
+    def strip_whitespace(cls, v: str) -> str:
+        """Strip leading/trailing whitespace from the query."""
+        return v.strip()
+
+
+class SQLObservation(Observation):
+    """
+    Result of executing a SQL query in the environment.
+
+    Fields
+    ------
+    result          : Rows returned by the query (list of dicts), None on error.
+    error           : SQL error message if the query failed, else None.
+    db_schema       : Human-readable database schema (populated on reset).
+    task_description: Natural-language question the agent must answer.
+    """
+
+    result: Optional[List[Dict[str, Any]]] = None
+    error: Optional[str] = None
+    db_schema: Optional[str] = None
+    task_description: Optional[str] = None
+
+
+class SQLState(State):
+    """Episode-level state for the SQL Analytics environment."""
+
+    task_id: str = ""
+    task_description: str = ""
+    difficulty: str = ""          # "easy" | "medium" | "hard"
+    attempts: int = 0
+    max_attempts: int = 10
+    solved: bool = False

openenv.yaml

@@ -0,0 +1,34 @@
+spec_version: 1
+version: 0.1.0
+name: sql_analytics_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+
+description: |
+  SQL Analytics environment where AI agents answer real-world
+  business-intelligence questions by writing SQL queries against
+  a seeded e-commerce database (100 customers, 50 products,
+  500 orders, 300 reviews). Ten tasks across easy/medium/hard
+  difficulty with partial-progress reward signals (0.0 - 1.0).
+
+tags:
+  - sql
+  - database
+  - business-intelligence
+  - reinforcement-learning
+  - real-world
+  - ecommerce
+
+tasks:
+  - task_001
+  - task_002
+  - task_003
+  - task_004
+  - task_005
+  - task_006
+  - task_007
+  - task_008
+  - task_009
+  - task_010

pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires      = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name        = "sql-analytics-env"
+version     = "0.1.0"
+description = "SQL Analytics OpenEnv environment — BI question-answering via SQL"
+readme      = "README.md"
+license     = {text = "MIT"}
+requires-python = ">=3.10"
+
+authors = [
+    {name = "SQL Analytics Env", email = "sql-analytics@example.com"}
+]
+
+keywords = [
+    "sql", "database", "reinforcement-learning",
+    "openenv", "business-intelligence", "ecommerce", "agent"
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+dependencies = [
+    "openenv-core>=0.1.0,<1.0.0",
+    "fastapi>=0.110.0,<1.0.0",
+    "uvicorn[standard]>=0.29.0,<1.0.0",
+    "pydantic>=2.0.0,<3.0.0",
+    "openai>=1.30.0,<3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage      = "https://huggingface.co/spaces/your-username/sql-analytics-env"
+Repository    = "https://github.com/your-username/sql-analytics-env"
+Documentation = "https://github.com/your-username/sql-analytics-env#readme"
+
+[project.scripts]
+sql-analytics-server = "server.app:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+
+[tool.pytest.ini_options]
+testpaths   = ["."]
+python_files = ["test_*.py"]

server/__init__.py

@@ -0,0 +1 @@
+# server package

server/app.py

@@ -0,0 +1,117 @@
+"""
+server/app.py
+-------------
+FastAPI application for the SQL Analytics Environment.
+
+Exposes the environment over HTTP + WebSocket endpoints that are
+consumed by EnvClient / the OpenEnv evaluation harness.
+
+Usage (development):
+    uvicorn server.app:app --reload --host 0.0.0.0 --port 8000
+
+Usage (production via Docker):
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --workers 1
+"""
+
+import time
+from fastapi import Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+try:
+    from openenv.core.env_server.http_server import create_app
+    from .sql_analytics_environment import SQLAnalyticsEnvironment
+    from ..models import SQLAction, SQLObservation
+except ImportError:
+    from openenv.core.env_server.http_server import create_app
+    from server.sql_analytics_environment import SQLAnalyticsEnvironment
+    from models import SQLAction, SQLObservation
+
+# ── Create base app ───────────────────────────────────────────────────────────
+# Pass the class (not an instance) so the HTTP server can instantiate
+# a fresh environment per WebSocket session.
+app = create_app(
+    SQLAnalyticsEnvironment,
+    SQLAction,
+    SQLObservation,
+    env_name="sql_analytics_env",
+)
+
+# ── CORS — allow all origins (needed for HuggingFace Spaces) ─────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Explicit health check (required by OpenEnv validator + hackathon) ─────────
+@app.get("/health", tags=["meta"])
+async def health():
+    """
+    Health check endpoint.
+    Returns HTTP 200 when the server is up and ready.
+    Required by OpenEnv pre-submission checks.
+    """
+    return {"status": "ok", "environment": "sql_analytics_env", "version": "0.1.0"}
+
+
+# ── Environment metadata ──────────────────────────────────────────────────────
+@app.get("/info", tags=["meta"])
+async def info():
+    """Return environment metadata for discoverability."""
+    return {
+        "name":        "sql_analytics_env",
+        "version":     "0.1.0",
+        "description": (
+            "SQL Analytics environment where AI agents answer "
+            "business-intelligence questions by writing SQL queries "
+            "against a seeded e-commerce database."
+        ),
+        "tasks": [
+            {"task_id": "task_001", "difficulty": "easy",   "topic": "Count customers by state"},
+            {"task_id": "task_002", "difficulty": "easy",   "topic": "Most expensive product in category"},
+            {"task_id": "task_003", "difficulty": "medium", "topic": "Top 5 customers by spend"},
+            {"task_id": "task_004", "difficulty": "medium", "topic": "Category with highest avg rating"},
+            {"task_id": "task_005", "difficulty": "hard",   "topic": "Q1-only buyers (churn signal)"},
+            {"task_id": "task_006", "difficulty": "hard",   "topic": "Monthly revenue + growth rate"},
+        ],
+        "action_space":      "SQLAction { sql: str }",
+        "observation_space": "SQLObservation { result, error, db_schema, task_description, reward, done }",
+        "reward_range":      [0.0, 1.0],
+        "max_steps":         10,
+    }
+
+
+# ── Request timing middleware (helps with debugging slow queries) ─────────────
+@app.middleware("http")
+async def add_process_time_header(request: Request, call_next):
+    start = time.perf_counter()
+    response = await call_next(request)
+    elapsed = round(time.perf_counter() - start, 4)
+    response.headers["X-Process-Time"] = str(elapsed)
+    return response
+
+
+# ── Global exception handler ──────────────────────────────────────────────────
+@app.exception_handler(Exception)
+async def global_exception_handler(request: Request, exc: Exception):
+    return JSONResponse(
+        status_code=500,
+        content={
+            "error": type(exc).__name__,
+            "detail": str(exc),
+            "path": str(request.url),
+        },
+    )
+
+
+def main() -> None:
+    """Entry point for direct execution."""
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+
+if __name__ == "__main__":
+    main()

server/sql_analytics_environment.py

@@ -0,0 +1,1077 @@
+"""
+sql_analytics_environment.py
+-----------------------------
+Core environment implementation for the SQL Analytics OpenEnv environment.
+
+An AI agent answers real-world business-intelligence questions by writing
+SQL queries against a seeded e-commerce SQLite database.
+
+Database schema
+---------------
+  customers(id, name, email, state, signup_date, last_order_date)
+  categories(id, name)
+  products(id, name, category_id, price, stock)
+  orders(id, customer_id, order_date, total_amount, status)
+  order_items(id, order_id, product_id, quantity, unit_price)
+  reviews(id, product_id, customer_id, rating, review_date)
+
+Six tasks (easy x2 / medium x2 / hard x2) with deterministic expected
+answers.  Rewards carry partial-progress signals so an RL agent can learn
+from near-misses.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import re
+import sqlite3
+import threading
+from datetime import datetime, timedelta
+from typing import Any, Dict, List, Optional, Tuple
+from uuid import uuid4
+
+try:
+    from openenv.core.env_server.interfaces import Environment
+    from ..models import SQLAction, SQLObservation, SQLState
+except ImportError:
+    from openenv.core.env_server.interfaces import Environment
+    from models import SQLAction, SQLObservation, SQLState
+
+# ── Logger ────────────────────────────────────────────────────────────────────
+logger = logging.getLogger("sql_analytics_env")
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+)
+
+# ── Query safety ──────────────────────────────────────────────────────────────
+_QUERY_TIMEOUT_SECONDS = 5          # max seconds per SQL query
+_BLOCKED_KEYWORDS = frozenset([     # read-only enforcement
+    "insert", "update", "delete", "drop", "create", "alter",
+    "attach", "detach", "pragma", "vacuum",
+])
+
+
+# ── Schema ─────────────────────────────────────────────────────────────────────
+
+_SCHEMA_DDL = """
+CREATE TABLE IF NOT EXISTS customers (
+    id             INTEGER PRIMARY KEY,
+    name           TEXT    NOT NULL,
+    email          TEXT    NOT NULL,
+    state          TEXT    NOT NULL,
+    signup_date    TEXT    NOT NULL,
+    last_order_date TEXT
+);
+
+CREATE TABLE IF NOT EXISTS categories (
+    id   INTEGER PRIMARY KEY,
+    name TEXT    NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS products (
+    id          INTEGER PRIMARY KEY,
+    name        TEXT    NOT NULL,
+    category_id INTEGER NOT NULL REFERENCES categories(id),
+    price       REAL    NOT NULL,
+    stock       INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS orders (
+    id           INTEGER PRIMARY KEY,
+    customer_id  INTEGER NOT NULL REFERENCES customers(id),
+    order_date   TEXT    NOT NULL,
+    total_amount REAL    NOT NULL,
+    status       TEXT    NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS order_items (
+    id         INTEGER PRIMARY KEY,
+    order_id   INTEGER NOT NULL REFERENCES orders(id),
+    product_id INTEGER NOT NULL REFERENCES products(id),
+    quantity   INTEGER NOT NULL,
+    unit_price REAL    NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS reviews (
+    id          INTEGER PRIMARY KEY,
+    product_id  INTEGER NOT NULL REFERENCES products(id),
+    customer_id INTEGER NOT NULL REFERENCES customers(id),
+    rating      INTEGER NOT NULL,
+    review_date TEXT    NOT NULL
+);
+"""
+
+# Static schema description — runtime-enriched version built after DB seed
+_SCHEMA_DESCRIPTION = """
+Database Schema (SQLite, read-only):
+=======================================================
+
+customers(id, name, email, state, signup_date, last_order_date)
+  - state          : 2-letter US state code  (e.g. 'CA', 'NY', 'TX')
+  - signup_date    : 'YYYY-MM-DD'
+  - last_order_date: 'YYYY-MM-DD' or NULL
+
+categories(id, name)
+  - name values: 'Electronics', 'Clothing', 'Books', 'Food', 'Sports'
+
+products(id, name, category_id, price, stock)
+  - category_id references categories.id
+
+orders(id, customer_id, order_date, total_amount, status)
+  - order_date  : 'YYYY-MM-DD'
+  - status      : 'delivered' | 'shipped' | 'pending' | 'cancelled'
+  - customer_id references customers.id
+
+order_items(id, order_id, product_id, quantity, unit_price)
+  - order_id   references orders.id
+  - product_id references products.id
+
+reviews(id, product_id, customer_id, rating, review_date)
+  - rating     : integer 1-5
+  - review_date: 'YYYY-MM-DD'
+  - product_id references products.id
+  - customer_id references customers.id
+""".strip()
+
+
+def _build_rich_schema(conn: sqlite3.Connection) -> str:
+    """
+    Build a rich schema description with row counts and sample data.
+    This is much more useful for an AI agent than just column names —
+    it can see what actual values look like (e.g. 'CA' not 'California').
+    """
+    conn.row_factory = sqlite3.Row
+
+    tables = [
+        ("customers",    "id, name, email, state, signup_date, last_order_date"),
+        ("categories",   "id, name"),
+        ("products",     "id, name, category_id, price, stock"),
+        ("orders",       "id, customer_id, order_date, total_amount, status"),
+        ("order_items",  "id, order_id, product_id, quantity, unit_price"),
+        ("reviews",      "id, product_id, customer_id, rating, review_date"),
+    ]
+
+    notes = {
+        "customers":   "state is 2-letter US code. signup_date/last_order_date are 'YYYY-MM-DD'.",
+        "categories":  "name is one of: 'Electronics', 'Clothing', 'Books', 'Food', 'Sports'.",
+        "products":    "category_id references categories.id. price is REAL.",
+        "orders":      "status is one of: 'delivered', 'shipped', 'pending', 'cancelled'.",
+        "order_items": "Links orders to products. unit_price is the price at time of order.",
+        "reviews":     "rating is integer 1-5. review_date is 'YYYY-MM-DD'.",
+    }
+
+    lines = [
+        "Database Schema (SQLite, read-only):",
+        "=" * 55,
+        "",
+    ]
+
+    for table, cols in tables:
+        row_count = conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+        lines.append(f"TABLE: {table}  ({row_count:,} rows)")
+        lines.append(f"  Columns : {cols}")
+        lines.append(f"  Notes   : {notes[table]}")
+
+        # Sample rows (first 3)
+        sample_rows = conn.execute(
+            f"SELECT {cols} FROM {table} LIMIT 3"
+        ).fetchall()
+        if sample_rows:
+            lines.append("  Sample  :")
+            col_names = cols.split(", ")
+            for r in sample_rows:
+                row_str = " | ".join(f"{col}={str(r[col])[:18]}" for col in col_names)
+                lines.append(f"    {row_str}")
+        lines.append("")
+
+    return "\n".join(lines).strip()
+
+
+def _educational_error(sql: str, raw_error: str) -> str:
+    """
+    Convert a raw SQLite error into a human-readable educational message
+    that helps the agent understand what went wrong and how to fix it.
+    """
+    e = raw_error.lower()
+    available_tables = "customers, categories, products, orders, order_items, reviews"
+
+    if "no such table" in e:
+        bad = raw_error.split(":")[-1].strip()
+        return (
+            f"Table '{bad}' does not exist. "
+            f"Available tables: {available_tables}. "
+            "Check your spelling and use lowercase table names."
+        )
+    if "no such column" in e:
+        return (
+            f"{raw_error}. "
+            "Check the schema for the correct column name. "
+            "Tip: use table_name.column_name to avoid ambiguity."
+        )
+    if "ambiguous column" in e:
+        bad = raw_error.split(":")[-1].strip()
+        return (
+            f"Column '{bad}' is ambiguous — it exists in multiple tables. "
+            "Qualify it with the table name, e.g. customers.id or orders.id."
+        )
+    if "syntax error" in e or "near" in e:
+        return (
+            f"SQL syntax error: {raw_error}. "
+            "Common causes: missing comma, unmatched parenthesis, "
+            "misspelled keyword, or missing FROM clause."
+        )
+    if "not unique" in e or "unique constraint" in e:
+        return f"Duplicate value error: {raw_error}. You may need DISTINCT."
+    if "no such function" in e:
+        fn = raw_error.split(":")[-1].strip()
+        return (
+            f"Function '{fn}' is not available in SQLite. "
+            "SQLite supports: COUNT, SUM, AVG, MIN, MAX, ROUND, "
+            "strftime, COALESCE, IFNULL, CAST."
+        )
+
+    return f"SQL error: {raw_error}"
+
+
+# ── Database seeding ───────────────────────────────────────────────────────────
+
+def _seed(conn: sqlite3.Connection) -> None:
+    """Populate the database with deterministic synthetic e-commerce data."""
+    rng = random.Random(42)
+
+    # ── categories ──
+    categories = ["Electronics", "Clothing", "Books", "Food", "Sports"]
+    conn.executemany(
+        "INSERT INTO categories (id, name) VALUES (?, ?)",
+        [(i + 1, n) for i, n in enumerate(categories)],
+    )
+
+    # ── products (10 per category = 50 total) ──
+    _PRODUCTS: Dict[int, List[Tuple[str, float]]] = {
+        1: [  # Electronics
+            ("iPhone 15", 999.99), ("Samsung 55\" TV", 799.99),
+            ("MacBook Pro 14\"", 2499.99), ("AirPods Pro", 249.99),
+            ("iPad Air", 599.99), ("Sony WH-1000XM5", 349.99),
+            ("Dell 27\" Monitor", 399.99), ("Mechanical Keyboard", 149.99),
+            ("Logitech MX Master", 99.99), ("USB-C Hub 7-port", 49.99),
+        ],
+        2: [  # Clothing
+            ("Running Shoes", 129.99), ("Slim Fit Jeans", 59.99),
+            ("Winter Parka", 199.99), ("Yoga Pants", 49.99),
+            ("Classic T-Shirt", 24.99), ("Formal Blazer", 299.99),
+            ("Canvas Sneakers", 89.99), ("Floral Dress", 79.99),
+            ("Zip Hoodie", 54.99), ("Board Shorts", 34.99),
+        ],
+        3: [  # Books
+            ("Python Cookbook 3e", 39.99), ("Clean Code", 44.99),
+            ("Deep Learning (Goodfellow)", 54.99), ("The Pragmatic Programmer", 49.99),
+            ("Design Patterns (GoF)", 44.99), ("Atomic Habits", 19.99),
+            ("Zero to One", 24.99), ("Sapiens", 22.99),
+            ("The Art of War", 12.99), ("Thinking Fast and Slow", 17.99),
+        ],
+        4: [  # Food
+            ("Organic Coffee 1 kg", 24.99), ("Matcha Green Tea Set", 19.99),
+            ("Whey Protein 2 kg", 49.99), ("Granola Bar 24-pack", 14.99),
+            ("Extra Virgin Olive Oil", 18.99), ("70% Dark Chocolate Box", 22.99),
+            ("Roasted Almonds 500 g", 16.99), ("Artisan Pasta 500 g", 8.99),
+            ("Craft Hot Sauce Set", 29.99), ("Raw Organic Honey", 12.99),
+        ],
+        5: [  # Sports
+            ("Yoga Mat 6mm", 49.99), ("Resistance Band Set", 29.99),
+            ("Adjustable Dumbbell 20 kg", 89.99), ("Tennis Racket Pro", 79.99),
+            ("Official Basketball", 34.99), ("Speed Jump Rope", 14.99),
+            ("Foam Roller 60cm", 24.99), ("Doorframe Pull-up Bar", 39.99),
+            ("Padded Gym Gloves", 19.99), ("40 oz Insulated Bottle", 29.99),
+        ],
+    }
+
+    products: List[Tuple] = []
+    pid = 1
+    for cat_id, items in _PRODUCTS.items():
+        for name, price in items:
+            products.append((pid, name, cat_id, price, rng.randint(0, 200)))
+            pid += 1
+    conn.executemany(
+        "INSERT INTO products (id, name, category_id, price, stock) VALUES (?,?,?,?,?)",
+        products,
+    )
+
+    # ── customers (100) ──
+    _FIRST = ["Alice", "Bob", "Carol", "David", "Eve", "Frank", "Grace",
+              "Henry", "Iris", "Jack", "Karen", "Leo", "Mary", "Nick",
+              "Olivia", "Paul", "Quinn", "Rachel", "Sam", "Tina"]
+    _LAST  = ["Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia",
+              "Miller", "Davis", "Martinez", "Wilson", "Anderson", "Taylor",
+              "Thomas", "Moore", "Jackson", "Martin", "Lee", "Perez",
+              "Thompson", "White"]
+    _STATES = (["CA"] * 20 + ["NY"] * 12 + ["TX"] * 12 + ["FL"] * 8 +
+               ["WA"] * 6 + ["IL"] * 5 + ["GA"] * 5 + ["MA"] * 5 +
+               ["CO"] * 4 + ["AZ"] * 4 + ["PA"] * 4 + ["OR"] * 3 +
+               ["NV"] * 3 + ["OH"] * 3 + ["MI"] * 3 + ["NC"] * 3)
+
+    BASE = datetime(2023, 1, 1)
+    customers: List[Tuple] = []
+    for i in range(100):
+        fn = rng.choice(_FIRST)
+        ln = rng.choice(_LAST)
+        st = rng.choice(_STATES)
+        signup = (BASE + timedelta(days=rng.randint(0, 365))).strftime("%Y-%m-%d")
+        customers.append((i + 1, f"{fn} {ln}",
+                          f"{fn.lower()}.{ln.lower()}{i}@example.com",
+                          st, signup, None))
+    conn.executemany(
+        "INSERT INTO customers (id, name, email, state, signup_date, last_order_date)"
+        " VALUES (?,?,?,?,?,?)",
+        customers,
+    )
+
+    # ── orders (500) and order_items ──
+    orders: List[Tuple] = []
+    items_rows: List[Tuple] = []
+    oid = 1
+    iid = 1
+    last_order: Dict[int, str] = {}
+    YEAR_START = datetime(2024, 1, 1)
+
+    for _ in range(500):
+        cust_id = rng.randint(1, 100)
+        odate = (YEAR_START + timedelta(days=rng.randint(0, 364))).strftime("%Y-%m-%d")
+        status = rng.choices(
+            ["delivered", "shipped", "pending", "cancelled"],
+            weights=[60, 20, 10, 10],
+        )[0]
+
+        n_items = rng.randint(1, 4)
+        chosen = rng.sample(range(1, 51), n_items)
+        total = 0.0
+        for prod_id in chosen:
+            qty = rng.randint(1, 3)
+            price = products[prod_id - 1][3]
+            total += qty * price
+            items_rows.append((iid, oid, prod_id, qty, price))
+            iid += 1
+
+        total = round(total, 2)
+        orders.append((oid, cust_id, odate, total, status))
+
+        if cust_id not in last_order or odate > last_order[cust_id]:
+            last_order[cust_id] = odate
+        oid += 1
+
+    conn.executemany(
+        "INSERT INTO orders (id, customer_id, order_date, total_amount, status)"
+        " VALUES (?,?,?,?,?)",
+        orders,
+    )
+    conn.executemany(
+        "INSERT INTO order_items (id, order_id, product_id, quantity, unit_price)"
+        " VALUES (?,?,?,?,?)",
+        items_rows,
+    )
+
+    for cid, ldate in last_order.items():
+        conn.execute(
+            "UPDATE customers SET last_order_date = ? WHERE id = ?", (ldate, cid)
+        )
+
+    # ── reviews (300) ──
+    reviews: List[Tuple] = []
+    for i in range(300):
+        prod_id = rng.randint(1, 50)
+        cust_id = rng.randint(1, 100)
+        rating = rng.choices([1, 2, 3, 4, 5], weights=[5, 10, 20, 35, 30])[0]
+        rdate = (YEAR_START + timedelta(days=rng.randint(0, 364))).strftime("%Y-%m-%d")
+        reviews.append((i + 1, prod_id, cust_id, rating, rdate))
+    conn.executemany(
+        "INSERT INTO reviews (id, product_id, customer_id, rating, review_date)"
+        " VALUES (?,?,?,?,?)",
+        reviews,
+    )
+    conn.commit()
+
+
+# ── Task definitions ───────────────────────────────────────────────────────────
+
+TASKS = [
+    # ── EASY ──────────────────────────────────────────────────────────────────
+    {
+        "task_id":    "task_001",
+        "difficulty": "easy",
+        "description": (
+            "Count the total number of customers registered in the state of "
+            "California (state = 'CA'). Return a single integer value."
+        ),
+        "hint": "Use the customers table and filter WHERE state = 'CA'.",
+    },
+    {
+        "task_id":    "task_002",
+        "difficulty": "easy",
+        "description": (
+            "Find the name and price of the most expensive product in the "
+            "'Electronics' category. Return exactly one row with columns: "
+            "name, price."
+        ),
+        "hint": (
+            "JOIN products with categories, filter WHERE categories.name = "
+            "'Electronics', ORDER BY price DESC, LIMIT 1."
+        ),
+    },
+    # ── MEDIUM ────────────────────────────────────────────────────────────────
+    {
+        "task_id":    "task_003",
+        "difficulty": "medium",
+        "description": (
+            "List the top 5 customers by total amount spent across all their "
+            "orders (any status). Return columns: name, total_spent "
+            "(rounded to 2 decimal places). Order by total_spent descending."
+        ),
+        "hint": (
+            "JOIN customers with orders. GROUP BY customer. "
+            "SUM(total_amount). ORDER BY total_spent DESC. LIMIT 5."
+        ),
+    },
+    {
+        "task_id":    "task_004",
+        "difficulty": "medium",
+        "description": (
+            "Which product category has the highest average customer rating? "
+            "Return columns: category_name, avg_rating "
+            "(rounded to 2 decimal places). Return only the top category."
+        ),
+        "hint": (
+            "JOIN reviews → products → categories. "
+            "GROUP BY category. AVG(rating). ORDER BY avg_rating DESC. LIMIT 1."
+        ),
+    },
+    # ── HARD ──────────────────────────────────────────────────────────────────
+    {
+        "task_id":    "task_005",
+        "difficulty": "hard",
+        "description": (
+            "Find all customers who placed at least one order in Q1 2024 "
+            "(January-March, i.e. order_date < '2024-04-01') but have NOT "
+            "placed any order from April 2024 onwards "
+            "(order_date >= '2024-04-01'). "
+            "Return columns: name, email. Order alphabetically by name."
+        ),
+        "hint": (
+            "Use subqueries or EXCEPT. One subquery selects customer_ids with "
+            "orders before '2024-04-01'; another selects customer_ids with "
+            "orders from '2024-04-01' onward. Take the difference."
+        ),
+    },
+    {
+        "task_id":    "task_006",
+        "difficulty": "hard",
+        "description": (
+            "Calculate monthly revenue (sum of total_amount) for each month "
+            "in 2024 using only 'delivered' orders. Then compute the "
+            "month-over-month growth rate as a percentage. "
+            "Return columns: month (integer 1-12), revenue "
+            "(rounded to 2 decimal places), growth_rate (percentage change "
+            "vs previous month rounded to 2 decimal places; NULL for the "
+            "first month). Order by month ascending. "
+            "Only include months that have at least one delivered order."
+        ),
+        "hint": (
+            "Use strftime('%m', order_date) to extract month. "
+            "Filter status = 'delivered'. For growth_rate use a self-join or "
+            "window function LAG() if SQLite version supports it."
+        ),
+    },
+
+    # ── EASY (additional) ─────────────────────────────────────────────────────
+    {
+        "task_id":    "task_007",
+        "difficulty": "easy",
+        "description": (
+            "How many products are currently out of stock (stock = 0)? "
+            "Return a single integer value."
+        ),
+        "hint": "Use the products table. Filter WHERE stock = 0. COUNT(*).",
+    },
+    {
+        "task_id":    "task_008",
+        "difficulty": "easy",
+        "description": (
+            "What is the average order value (total_amount) across ALL orders "
+            "regardless of status? Return a single value rounded to 2 decimal "
+            "places. Column name: avg_order_value."
+        ),
+        "hint": "Use the orders table. AVG(total_amount). ROUND to 2 decimal places.",
+    },
+
+    # ── MEDIUM (additional) ───────────────────────────────────────────────────
+    {
+        "task_id":    "task_009",
+        "difficulty": "medium",
+        "description": (
+            "List all products that have NEVER received any customer review. "
+            "Return columns: name, category_name. "
+            "Order by product name alphabetically."
+        ),
+        "hint": (
+            "LEFT JOIN products with reviews ON products.id = reviews.product_id. "
+            "Filter WHERE reviews.id IS NULL (no matching review). "
+            "JOIN categories to get category_name."
+        ),
+    },
+    {
+        "task_id":    "task_010",
+        "difficulty": "medium",
+        "description": (
+            "Which US state has the highest number of registered customers? "
+            "Return columns: state, customer_count. Return only the top 1 state."
+        ),
+        "hint": (
+            "Use the customers table. GROUP BY state. COUNT(*) AS customer_count. "
+            "ORDER BY customer_count DESC. LIMIT 1."
+        ),
+    },
+]
+
+
+# ── Grading helpers ────────────────────────────────────────────────────────────
+
+def _rows_to_dicts(rows: List[sqlite3.Row]) -> List[Dict[str, Any]]:
+    return [dict(r) for r in rows]
+
+
+def _lower_keys(row: Dict[str, Any]) -> Dict[str, Any]:
+    return {k.lower(): v for k, v in row.items()}
+
+
+def _find_col(row: Dict[str, Any], *hints: str) -> Optional[Any]:
+    """Return the value of the first column whose name contains any hint."""
+    for hint in hints:
+        for k, v in row.items():
+            if hint in k:
+                return v
+    return None
+
+
+def _grade_count(result: List, expected: int) -> Tuple[float, bool, str]:
+    if not result:
+        return 0.1, False, "Empty result; expected a single count row."
+    row = _lower_keys(result[0])
+    raw = next(iter(row.values()), None)
+    try:
+        got = int(raw)
+    except (TypeError, ValueError):
+        return 0.2, False, f"Cannot parse integer from first column: {raw!r}"
+
+    if got == expected:
+        return 1.0, True, f"Correct! Count = {got}."
+    diff = abs(got - expected) / max(expected, 1)
+    if diff <= 0.02:
+        return 0.8, False, f"Very close: got {got}, expected {expected}."
+    elif diff <= 0.15:
+        return 0.4, False, f"Somewhat close: got {got}, expected {expected}."
+    return 0.1, False, f"Incorrect: got {got}, expected {expected}."
+
+
+def _grade_single_row(
+    result: List, expected: Dict[str, Any]
+) -> Tuple[float, bool, str]:
+    if not result:
+        return 0.1, False, "Empty result; expected one row."
+    row = _lower_keys(result[0])
+    hits = 0
+    for key, exp_val in expected.items():
+        # Flexible column matching
+        got_val = row.get(key.lower())
+        if got_val is None:
+            for k in row:
+                if key.lower() in k or k in key.lower():
+                    got_val = row[k]
+                    break
+        if got_val is None:
+            continue
+        if isinstance(exp_val, float):
+            try:
+                if abs(float(got_val) - exp_val) / max(abs(exp_val), 0.01) < 0.01:
+                    hits += 1
+            except (TypeError, ValueError):
+                pass
+        else:
+            if str(got_val).strip().lower() == str(exp_val).strip().lower():
+                hits += 1
+    score = hits / len(expected)
+    return score, score >= 1.0, f"Matched {hits}/{len(expected)} expected fields."
+
+
+def _grade_top_n(
+    result: List,
+    expected: List[Dict],
+    name_col: str,
+    value_col: str,
+) -> Tuple[float, bool, str]:
+    if not result:
+        return 0.1, False, "Empty result; expected multiple rows."
+    n = len(expected)
+    result_low = [_lower_keys(r) for r in result]
+
+    got_names = []
+    for row in result_low:
+        v = _find_col(row, name_col, "name", "customer")
+        if v is not None:
+            got_names.append(str(v))
+
+    exp_names = [str(e[name_col]) for e in expected]
+
+    if not got_names:
+        return 0.2, False, f"Could not find '{name_col}' column in result."
+
+    # Exact order
+    if got_names[:n] == exp_names:
+        return 1.0, True, f"Perfect top-{n} in correct order."
+
+    overlap = len(set(got_names[:n]) & set(exp_names))
+    pos_matches = sum(
+        1 for i, g in enumerate(got_names[:n])
+        if i < len(exp_names) and g == exp_names[i]
+    )
+    score = 0.3 + 0.5 * (overlap / n) + 0.2 * (pos_matches / n)
+    return min(score, 0.95), False, f"Partial: {overlap}/{n} names, {pos_matches}/{n} in correct position."
+
+
+def _grade_set_match(
+    result: List,
+    expected: List[Dict],
+    col: str = "name",
+) -> Tuple[float, bool, str]:
+    result_low = [_lower_keys(r) for r in result]
+    got_set = set()
+    for row in result_low:
+        v = _find_col(row, col, "name", "customer")
+        if v is not None:
+            got_set.add(str(v).strip())
+    exp_set = {str(e[col]).strip() for e in expected}
+
+    if not exp_set and not got_set:
+        return 1.0, True, "Correct: no rows expected and none returned."
+    if not exp_set:
+        return 0.0, False, f"Expected 0 rows but got {len(got_set)}."
+    if not got_set:
+        return 0.1, False, "Empty result but expected rows."
+
+    precision = len(got_set & exp_set) / len(got_set)
+    recall    = len(got_set & exp_set) / len(exp_set)
+    f1 = 2 * precision * recall / (precision + recall) if (precision + recall) else 0.0
+    return f1, f1 >= 0.95, (
+        f"F1={f1:.2f} (precision={precision:.2f}, recall={recall:.2f}). "
+        f"Expected {len(exp_set)} rows, got {len(got_set)}."
+    )
+
+
+def _grade_monthly_revenue(
+    result: List, expected: List[Dict]
+) -> Tuple[float, bool, str]:
+    if not result or len(result) < 2:
+        return 0.1, False, f"Too few rows ({len(result)}); expected ~{len(expected)}."
+
+    result_low = [_lower_keys(r) for r in result]
+    got_months: Dict[int, float] = {}
+    for row in result_low:
+        m = _find_col(row, "month")
+        r = _find_col(row, "revenue", "amount", "total", "sum")
+        if m is not None and r is not None:
+            try:
+                got_months[int(m)] = float(r)
+            except (TypeError, ValueError):
+                pass
+
+    if not got_months:
+        return 0.2, False, "Could not extract month/revenue columns."
+
+    exp_months = {e["month"]: e["revenue"] for e in expected}
+
+    # Revenue accuracy
+    rev_scores = []
+    for mo, exp_rev in exp_months.items():
+        got_rev = got_months.get(mo)
+        if got_rev is None:
+            rev_scores.append(0.0)
+        else:
+            diff = abs(got_rev - exp_rev) / max(abs(exp_rev), 1.0)
+            rev_scores.append(max(0.0, 1.0 - diff * 5))
+
+    rev_score = sum(rev_scores) / len(rev_scores)
+
+    # Bonus: growth_rate column present
+    has_growth = any(
+        any("growth" in k or "rate" in k for k in _lower_keys(r))
+        for r in result
+    )
+    score = 0.75 * rev_score + (0.25 if has_growth else 0.0)
+    done  = score >= 0.85
+    return round(score, 4), done, (
+        f"Revenue accuracy={rev_score:.2f}, growth_rate column present={has_growth}."
+    )
+
+
+# ── Environment ────────────────────────────────────────────────────────────────
+
+class SQLAnalyticsEnvironment(Environment):
+    """
+    OpenEnv environment: SQL Analytics over an e-commerce database.
+
+    An AI agent receives a natural-language BI question and must write
+    correct SQL queries against the database to find the answer.
+
+    Interaction loop
+    ----------------
+    1. ``reset(task_id="task_001")``  →  initial SQLObservation with schema + task
+    2. ``step(SQLAction(sql="SELECT ..."))``  →  query result + partial reward
+    3. Repeat step 2 until ``observation.done == True``
+
+    Tasks (difficulty)
+    ------------------
+    task_001  easy    count customers in CA
+    task_002  easy    most expensive Electronics product
+    task_003  medium  top 5 customers by spend
+    task_004  medium  category with highest avg rating
+    task_005  hard    Q1-only buyers (churn signal)
+    task_006  hard    monthly revenue + growth rate
+    """
+
+    SUPPORTS_CONCURRENT_SESSIONS = False
+
+    def __init__(self) -> None:
+        self._conn: Optional[sqlite3.Connection] = None
+        self._state = SQLState(episode_id=str(uuid4()), step_count=0)
+        self._current_task: Optional[Dict] = None
+        self._answers: Dict[str, Any] = {}
+        self._setup()
+
+    # ── setup ──────────────────────────────────────────────────────────────
+
+    def _setup(self) -> None:
+        self._conn = sqlite3.connect(":memory:", check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.executescript(_SCHEMA_DDL)
+        _seed(self._conn)
+        # Build rich schema AFTER seeding so sample rows are available
+        self._rich_schema = _build_rich_schema(self._conn)
+        self._precompute_answers()
+
+    def _precompute_answers(self) -> None:
+        c = self._conn
+
+        # task_001
+        r = c.execute(
+            "SELECT COUNT(*) AS cnt FROM customers WHERE state = 'CA'"
+        ).fetchone()
+        self._answers["task_001"] = int(r["cnt"])
+
+        # task_002
+        r = c.execute("""
+            SELECT p.name, p.price
+            FROM products p
+            JOIN categories cat ON p.category_id = cat.id
+            WHERE cat.name = 'Electronics'
+            ORDER BY p.price DESC
+            LIMIT 1
+        """).fetchone()
+        self._answers["task_002"] = {"name": r["name"], "price": r["price"]}
+
+        # task_003
+        rows = c.execute("""
+            SELECT cu.name, ROUND(SUM(o.total_amount), 2) AS total_spent
+            FROM customers cu
+            JOIN orders o ON cu.id = o.customer_id
+            GROUP BY cu.id, cu.name
+            ORDER BY total_spent DESC
+            LIMIT 5
+        """).fetchall()
+        self._answers["task_003"] = _rows_to_dicts(rows)
+
+        # task_004
+        r = c.execute("""
+            SELECT cat.name AS category_name, ROUND(AVG(rv.rating), 2) AS avg_rating
+            FROM reviews rv
+            JOIN products p  ON rv.product_id  = p.id
+            JOIN categories cat ON p.category_id = cat.id
+            GROUP BY cat.id, cat.name
+            ORDER BY avg_rating DESC
+            LIMIT 1
+        """).fetchone()
+        self._answers["task_004"] = {
+            "category_name": r["category_name"],
+            "avg_rating": r["avg_rating"],
+        }
+
+        # task_005
+        rows = c.execute("""
+            SELECT DISTINCT cu.name, cu.email
+            FROM customers cu
+            WHERE cu.id IN (
+                SELECT customer_id FROM orders
+                WHERE order_date >= '2024-01-01' AND order_date < '2024-04-01'
+            )
+            AND cu.id NOT IN (
+                SELECT customer_id FROM orders
+                WHERE order_date >= '2024-04-01'
+            )
+            ORDER BY cu.name
+        """).fetchall()
+        self._answers["task_005"] = _rows_to_dicts(rows)
+
+        # task_006
+        rows = c.execute("""
+            SELECT CAST(strftime('%m', order_date) AS INTEGER) AS month,
+                   ROUND(SUM(total_amount), 2) AS revenue
+            FROM orders
+            WHERE status = 'delivered'
+              AND order_date BETWEEN '2024-01-01' AND '2024-12-31'
+            GROUP BY month
+            ORDER BY month
+        """).fetchall()
+        monthly: List[Dict] = _rows_to_dicts(rows)
+        for i, m in enumerate(monthly):
+            if i == 0:
+                m["growth_rate"] = None
+            else:
+                prev = monthly[i - 1]["revenue"]
+                m["growth_rate"] = (
+                    round((m["revenue"] - prev) / prev * 100, 2)
+                    if prev else None
+                )
+        self._answers["task_006"] = monthly
+
+        # task_007 — out of stock count
+        r = c.execute("SELECT COUNT(*) AS cnt FROM products WHERE stock = 0").fetchone()
+        self._answers["task_007"] = int(r["cnt"])
+
+        # task_008 — average order value
+        r = c.execute(
+            "SELECT ROUND(AVG(total_amount), 2) AS avg_order_value FROM orders"
+        ).fetchone()
+        self._answers["task_008"] = {"avg_order_value": r["avg_order_value"]}
+
+        # task_009 — products never reviewed
+        rows = c.execute("""
+            SELECT p.name, cat.name AS category_name
+            FROM products p
+            JOIN categories cat ON p.category_id = cat.id
+            LEFT JOIN reviews rv ON p.id = rv.product_id
+            WHERE rv.id IS NULL
+            ORDER BY p.name
+        """).fetchall()
+        self._answers["task_009"] = _rows_to_dicts(rows)
+
+        # task_010 — state with most customers
+        r = c.execute("""
+            SELECT state, COUNT(*) AS customer_count
+            FROM customers
+            GROUP BY state
+            ORDER BY customer_count DESC
+            LIMIT 1
+        """).fetchone()
+        self._answers["task_010"] = {"state": r["state"], "customer_count": r["customer_count"]}
+
+    # ── OpenEnv API ────────────────────────────────────────────────────────
+
+    def reset(
+        self,
+        seed: Optional[int] = None,
+        episode_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> SQLObservation:
+        """Start a new episode for the given task_id (default: task_001)."""
+        task_id = task_id or "task_001"
+        task_def = next(
+            (t for t in TASKS if t["task_id"] == task_id), TASKS[0]
+        )
+
+        self._current_task = task_def
+        self._state = SQLState(
+            episode_id=episode_id or str(uuid4()),
+            step_count=0,
+            task_id=task_def["task_id"],
+            task_description=task_def["description"],
+            difficulty=task_def["difficulty"],
+            attempts=0,
+            max_attempts=10,
+            solved=False,
+        )
+
+        return SQLObservation(
+            done=False,
+            reward=0.0,
+            result=None,
+            error=None,
+            db_schema=self._rich_schema,   # ← rich schema with samples
+            task_description=task_def["description"],
+            metadata={
+                "task_id":    task_def["task_id"],
+                "difficulty": task_def["difficulty"],
+                "hint":       task_def["hint"],
+                "max_steps":  10,
+                "message": (
+                    "Environment ready. Submit a SQL query via SQLAction(sql=...) "
+                    "to answer the task. Tip: solving in fewer steps earns an "
+                    "efficiency bonus on top of your base reward."
+                ),
+            },
+        )
+
+    def step(
+        self,
+        action: SQLAction,
+        timeout_s: Optional[float] = None,
+        **kwargs: Any,
+    ) -> SQLObservation:
+        """Execute the agent's SQL query and return a graded observation."""
+        if self._current_task is None:
+            return SQLObservation(
+                done=True,
+                reward=0.0,
+                error="No task loaded. Call reset(task_id=...) first.",
+                metadata={"message": "Call reset() before step()."},
+            )
+
+        self._state.step_count += 1
+        self._state.attempts += 1
+
+        # Execute SQL (read-only, with safety checks + timeout)
+        sql = (action.sql or "").strip()
+        result: Optional[List] = None
+        error: Optional[str] = None
+
+        # Block write operations
+        sql_lower = sql.lower()
+        blocked = [kw for kw in _BLOCKED_KEYWORDS if re.search(r'\b' + kw + r'\b', sql_lower)]
+        if blocked:
+            error = f"Write operations are not allowed: {blocked}. Only SELECT queries are permitted."
+            logger.warning("Blocked SQL keyword(s) %s in episode=%s", blocked, self._state.episode_id)
+        elif not sql:
+            error = "Empty SQL query submitted."
+        else:
+            # Run query in a thread with a timeout
+            _result_box: List = []
+            _error_box:  List = []
+
+            def _run_query():
+                try:
+                    cur = self._conn.execute(sql)
+                    rows = cur.fetchall()
+                    _result_box.append(_rows_to_dicts(rows))
+                except Exception as exc:
+                    _error_box.append(str(exc))
+
+            t = threading.Thread(target=_run_query, daemon=True)
+            t.start()
+            t.join(timeout=_QUERY_TIMEOUT_SECONDS)
+
+            if t.is_alive():
+                error = f"Query timed out after {_QUERY_TIMEOUT_SECONDS}s."
+                logger.warning("Query timeout in episode=%s | sql=%s", self._state.episode_id, sql[:80])
+            elif _error_box:
+                # Convert raw error → educational message
+                error = _educational_error(sql, _error_box[0])
+            else:
+                result = _result_box[0] if _result_box else []
+
+        logger.info(
+            "step | episode=%s | task=%s | attempt=%d | rows=%s | reward_pending | error=%s",
+            self._state.episode_id,
+            self._state.task_id,
+            self._state.attempts,
+            len(result) if result is not None else "N/A",
+            error,
+        )
+
+        # Grade
+        reward, done, message = self._grade(result, error)
+
+        # ── Efficiency bonus ────────────────────────────────────────────────
+        # Reward agents that solve correctly in fewer steps.
+        # Solving in 1 step → reward stays 1.0 (no penalty)
+        # Solving in 5 steps → base * 0.92
+        # Solving in 10 steps → base * 0.82
+        # Only applied when the task is actually solved (base reward = 1.0)
+        if done and reward >= 0.9:
+            efficiency = max(0.82, 1.0 - (self._state.attempts - 1) * 0.02)
+            reward = round(reward * efficiency, 4)
+            if self._state.attempts == 1:
+                message += " [+efficiency bonus: solved in 1 step!]"
+            elif efficiency < 1.0:
+                message += f" [efficiency={efficiency:.2f}: solved in {self._state.attempts} steps]"
+
+        if done:
+            self._state.solved = reward >= 0.82   # still counts as solved after bonus
+
+        # Enforce max-attempts cap
+        if self._state.attempts >= self._state.max_attempts and not done:
+            done = True
+            message += f" [Max attempts ({self._state.max_attempts}) reached.]"
+
+        return SQLObservation(
+            done=done,
+            reward=reward,
+            result=result,
+            error=error,
+            db_schema=self._rich_schema,
+            task_description=self._current_task["description"],
+            metadata={
+                "task_id":    self._current_task["task_id"],
+                "difficulty": self._current_task["difficulty"],
+                "attempts":   self._state.attempts,
+                "max_attempts": self._state.max_attempts,
+                "steps_remaining": max(0, self._state.max_attempts - self._state.attempts),
+                "message":    message,
+            },
+        )
+
+    @property
+    def state(self) -> SQLState:
+        return self._state
+
+    # ── Grading dispatch ───────────────────────────────────────────────────
+
+    def _grade(
+        self,
+        result: Optional[List],
+        error: Optional[str],
+    ) -> Tuple[float, bool, str]:
+        task_id = self._current_task["task_id"]
+
+        if error:
+            # Return 0.0 but keep done=False so agent can retry
+            return 0.0, False, error
+        if result is None:
+            return 0.0, False, "No result returned."
+
+        if task_id == "task_001":
+            return _grade_count(result, self._answers["task_001"])
+        elif task_id == "task_002":
+            return _grade_single_row(result, self._answers["task_002"])
+        elif task_id == "task_003":
+            return _grade_top_n(
+                result, self._answers["task_003"],
+                name_col="name", value_col="total_spent",
+            )
+        elif task_id == "task_004":
+            return _grade_single_row(result, self._answers["task_004"])
+        elif task_id == "task_005":
+            return _grade_set_match(
+                result, self._answers["task_005"], col="name"
+            )
+        elif task_id == "task_006":
+            return _grade_monthly_revenue(result, self._answers["task_006"])
+        elif task_id == "task_007":
+            return _grade_count(result, self._answers["task_007"])
+        elif task_id == "task_008":
+            return _grade_single_row(result, self._answers["task_008"])
+        elif task_id == "task_009":
+            return _grade_set_match(
+                result, self._answers["task_009"], col="name"
+            )
+        elif task_id == "task_010":
+            return _grade_single_row(result, self._answers["task_010"])
+
+        return 0.0, False, f"Unknown task_id: {task_id}"

skills/rl-gym-auditor/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: rl-gym-auditor
+description: >
+  Use this skill to audit and score any Reinforcement Learning gym or OpenEnv-style environment.
+  Trigger whenever the user asks to audit, review, evaluate, check, score, or improve an RL gym,
+  OpenEnv environment, AI training environment, reward function, or RL observation design.
+  Also trigger when the user asks questions like "is my RL env good?", "how do I improve my gym?",
+  "what's wrong with my reward function?", "is this environment hackathon-ready?", or
+  "how does my OpenEnv compare to best practices?". If any Python file contains reset()/step()/state()
+  methods or reward-related grading functions, this skill should be used.
+---
+
+# RL Gym Auditor
+
+You are an expert RL environment designer. Your job is to audit a Reinforcement Learning gym
+(typically an OpenEnv-style environment) and produce a detailed quality report with scores,
+PASS/WARN/FAIL verdicts, and concrete improvement suggestions.
+
+## Step 1 — Locate the Environment Files
+
+Search the project directory for the environment implementation. Look for:
+- Files named `*environment*.py`, `*env*.py`, `gym*.py`
+- Files containing `def reset(`, `def step(`, `def state(`
+- Files containing reward-related words: `reward`, `_grade`, `score`
+- Spec files: `openenv.yaml`, `openenv.yml`
+- Model/type files: `models.py`, `types.py`
+
+Read the main environment file fully. Also read any models/types file and the spec file.
+
+## Step 2 — Audit Across 5 Categories
+
+Evaluate each category and assign a score from 0-10. Be honest and precise. A WARN means
+"works but could be better", FAIL means "missing or broken". Every verdict MUST use the exact
+label `[PASS]`, `[WARN]`, or `[FAIL]` — this consistency is what makes scores comparable.
+
+---
+
+### Category 1: Reward Signal Quality (weight: 30%)
+
+This is the most important category because reward quality directly determines whether RL
+training will converge. A sparse reward (0 until solved, then 1) gives the agent no gradient
+to follow. A dense reward (partial credit at every step) enables learning from near-misses.
+
+| Criterion | PASS condition | Score impact |
+|-----------|---------------|-------------|
+| **Reward range** | All rewards are in [0.0, 1.0] | -3 if outside range |
+| **Dense rewards** | Agent gets meaningful signal at every step, not just 0/1 | -4 if binary only |
+| **Partial credit** | Wrong-but-close answers score higher than completely wrong | -3 if no gradient |
+| **Error handling** | Errors give 0.0 but don't end the episode (agent can retry) | -2 if errors terminate |
+| **Efficiency bonus** | Faster solutions score higher than slow ones | -1 if missing |
+| **Grader diversity** | Different task types use different grading logic | -1 if one-size-fits-all |
+
+---
+
+### Category 2: Task Coverage (weight: 25%)
+
+| Criterion | PASS condition |
+|-----------|---------------|
+| **Minimum tasks** | At least 3 tasks present |
+| **Difficulty curve** | Tasks span easy, medium, AND hard |
+| **Pattern diversity** | Tasks require different skills (COUNT vs JOIN vs subquery, etc.) |
+| **Deterministic answers** | Every task has a fixed correct answer (no random expected output) |
+| **Clear descriptions** | Each task has a human-readable natural language description |
+| **Spec file complete** | openenv.yaml (or equivalent) lists ALL implemented tasks. FAIL if tasks exist in code but not in spec. |
+
+---
+
+### Category 3: Observation Quality (weight: 20%)
+
+The observation is what the agent *sees*. Garbage in = garbage out for RL.
+
+| Criterion | PASS condition |
+|-----------|---------------|
+| **Schema in observation** | Agent sees table/field names at reset AND at every step |
+| **Sample data** | Agent sees a few real rows (not just column names) |
+| **Error messages** | Errors are educational ("Table X not found, available: ...") not raw tracebacks |
+| **Progress signal** | `steps_remaining` or `attempts` exposed in metadata |
+| **Task description** | Natural language question is in the observation |
+
+---
+
+### Category 4: Safety & Isolation (weight: 15%)
+
+| Criterion | PASS condition |
+|-----------|---------------|
+| **Read-only enforcement** | Write operations are blocked using regex word-boundary matching (`re.search(r'\b' + kw + r'\b', ...)`) not naive `.split()` |
+| **Query timeout** | Long-running queries are killed after N seconds |
+| **Deterministic seeding** | Random seed is fixed (e.g. `random.Random(42)`) |
+| **No global state leaks** | Each `reset()` produces a clean episode |
+| **Input validation** | Empty/null/invalid actions are handled gracefully |
+
+---
+
+### Category 5: API Compliance (weight: 10%)
+
+| Criterion | PASS condition |
+|-----------|---------------|
+| **reset() exists** | Returns initial observation with schema + task |
+| **step() exists** | Accepts action, returns observation with reward + done |
+| **state() exists** | Returns current episode state (attempts, task_id, solved) |
+| **Typed models** | Action, Observation, State use typed classes (Pydantic or dataclass) |
+| **/health endpoint** | HTTP server exposes GET /health returning {"status": "ok"} |
+| **Spec file valid** | openenv.yaml present with name, port, and ALL tasks listed |
+
+---
+
+## Step 3 — Calculate Scores
+
+For each category, count how many criteria PASS, WARN, or FAIL.
+
+Score formula per category:
+- Each criterion is worth `10 / num_criteria` points
+- PASS = full points
+- WARN = half points
+- FAIL = 0 points
+
+Overall RL Gym Quality Score = weighted average:
+```
+overall = (reward * 0.30) + (tasks * 0.25) + (obs * 0.20) + (safety * 0.15) + (api * 0.10)
+```
+
+Grade thresholds:
+- 9.0-10.0 -> **A** — Production-ready, hackathon-winning quality
+- 7.5-8.9  -> **B** — Good, minor improvements recommended
+- 6.0-7.4  -> **C** — Acceptable, several gaps to address
+- 4.0-5.9  -> **D** — Needs significant work
+- Below 4.0 -> **F** — Fundamental issues, major rework needed
+
+---
+
+## Step 4 — Print the Audit Report
+
+Use this EXACT format for the output. Always show the weighted score breakdown and always
+include the TOP 3 IMPROVEMENTS section at the end.
+
+```
+============================================================
+  RL GYM AUDIT REPORT
+  Environment: <name>
+  Audited: <datetime>
+============================================================
+
+CATEGORY 1: REWARD SIGNAL QUALITY        [X.X / 10]
+------------------------------------------------------------
+  [PASS] Reward range bounded 0.0-1.0
+  [PASS] Dense rewards — partial credit at every step
+  [WARN] Efficiency bonus present but floor too high (0.82)
+  [FAIL] No grader diversity — all tasks use same grading fn
+  ...
+  Suggestions:
+    - <specific, actionable suggestion with code reference>
+
+CATEGORY 2: TASK COVERAGE                [X.X / 10]
+------------------------------------------------------------
+  ...
+
+CATEGORY 3: OBSERVATION QUALITY          [X.X / 10]
+------------------------------------------------------------
+  ...
+
+CATEGORY 4: SAFETY & ISOLATION           [X.X / 10]
+------------------------------------------------------------
+  ...
+
+CATEGORY 5: API COMPLIANCE               [X.X / 10]
+------------------------------------------------------------
+  ...
+
+============================================================
+  SCORE BREAKDOWN
+============================================================
+  Category 1 — Reward Signal Quality  (30%):  X.X / 10  ->  X.XX
+  Category 2 — Task Coverage          (25%):  X.X / 10  ->  X.XX
+  Category 3 — Observation Quality    (20%):  X.X / 10  ->  X.XX
+  Category 4 — Safety & Isolation     (15%):  X.X / 10  ->  X.XX
+  Category 5 — API Compliance         (10%):  X.X / 10  ->  X.XX
+
+============================================================
+  OVERALL RL GYM QUALITY SCORE: X.X / 10   Grade: X
+============================================================
+
+TOP 3 IMPROVEMENTS (highest impact first):
+  1. [CATEGORY] Specific actionable improvement
+  2. [CATEGORY] Specific actionable improvement
+  3. [CATEGORY] Specific actionable improvement
+============================================================
+```
+
+## Important Notes
+
+- Be honest. A score of 6/10 is not bad feedback — it's useful feedback.
+- Read the actual code, don't guess. If something is ambiguous, note it as WARN with "could not verify".
+- Focus on what matters for RL training quality, not code style.
+- Every PASS/WARN/FAIL must have a 1-line explanation after the label.
+- Suggestions must be specific: not "improve reward function" but "In `_grade_count()`, add a partial score of 0.4 when the result is within 15% of expected."
+- The spec file (openenv.yaml) listing ALL tasks is a FAIL, not a WARN, if tasks are missing from the list but implemented in code.
+- Read-only enforcement using `.split()` instead of regex is a WARN because it's bypassable.

test_env.py

@@ -0,0 +1,218 @@
+"""
+test_env.py  —  Smoke test for SQL Analytics OpenEnv environment
+"""
+import sys, os
+sys.stdout.reconfigure(encoding="utf-8") if hasattr(sys.stdout, "reconfigure") else None
+sys.path.insert(0, os.path.dirname(__file__))
+
+from models import SQLAction
+from server.sql_analytics_environment import SQLAnalyticsEnvironment, TASKS
+
+PASS = "[PASS]"
+FAIL = "[FAIL]"
+
+# ── Correct SQL answers for all 10 tasks ──────────────────────────────────────
+CORRECT_SQL = {
+    "task_001": "SELECT COUNT(*) FROM customers WHERE state = 'CA'",
+    "task_002": """
+        SELECT p.name, p.price FROM products p
+        JOIN categories c ON p.category_id = c.id
+        WHERE c.name = 'Electronics' ORDER BY p.price DESC LIMIT 1
+    """,
+    "task_003": """
+        SELECT c.name, ROUND(SUM(o.total_amount), 2) AS total_spent
+        FROM customers c JOIN orders o ON c.id = o.customer_id
+        GROUP BY c.id, c.name ORDER BY total_spent DESC LIMIT 5
+    """,
+    "task_004": """
+        SELECT cat.name AS category_name, ROUND(AVG(r.rating), 2) AS avg_rating
+        FROM reviews r JOIN products p ON r.product_id = p.id
+        JOIN categories cat ON p.category_id = cat.id
+        GROUP BY cat.id, cat.name ORDER BY avg_rating DESC LIMIT 1
+    """,
+    "task_005": """
+        SELECT DISTINCT c.name, c.email FROM customers c
+        WHERE c.id IN (SELECT customer_id FROM orders WHERE order_date < '2024-04-01')
+        AND c.id NOT IN (SELECT customer_id FROM orders WHERE order_date >= '2024-04-01')
+        ORDER BY c.name
+    """,
+    "task_006": """
+        SELECT CAST(strftime('%m', order_date) AS INTEGER) AS month,
+               ROUND(SUM(total_amount), 2) AS revenue, NULL AS growth_rate
+        FROM orders WHERE status = 'delivered'
+        AND order_date BETWEEN '2024-01-01' AND '2024-12-31'
+        GROUP BY month ORDER BY month
+    """,
+    "task_007": "SELECT COUNT(*) FROM products WHERE stock = 0",
+    "task_008": "SELECT ROUND(AVG(total_amount), 2) AS avg_order_value FROM orders",
+    "task_009": """
+        SELECT p.name, cat.name AS category_name
+        FROM products p JOIN categories cat ON p.category_id = cat.id
+        LEFT JOIN reviews rv ON p.id = rv.product_id
+        WHERE rv.id IS NULL ORDER BY p.name
+    """,
+    "task_010": """
+        SELECT state, COUNT(*) AS customer_count FROM customers
+        GROUP BY state ORDER BY customer_count DESC LIMIT 1
+    """,
+}
+
+WRONG_SQL = {
+    "task_001": "SELECT COUNT(*) FROM customers WHERE state = 'TX'",
+    "task_002": "INVALID SQL !!!",
+    "task_003": "SELECT name FROM customers LIMIT 5",
+    "task_004": "SELECT 'Electronics', 5.0",
+    "task_005": "SELECT name, email FROM customers LIMIT 2",
+    "task_006": "SELECT 1 AS month, 100.0 AS revenue",
+    "task_007": "SELECT COUNT(*) FROM products WHERE stock > 100",
+    "task_008": "SELECT ROUND(AVG(total_amount), 2) AS avg FROM orders WHERE status='delivered'",
+    "task_009": "SELECT name FROM products LIMIT 3",
+    "task_010": "SELECT state FROM customers LIMIT 1",
+}
+
+
+def separator(title):
+    print(f"\n{'='*60}")
+    print(f"  {title}")
+    print('='*60)
+
+
+def run_test(env, task_id, sql, label):
+    env.reset(task_id=task_id)
+    obs = env.step(SQLAction(sql=sql))
+    icon = PASS if (label == "CORRECT" and obs.reward >= 0.8) or \
+                   (label == "WRONG"   and obs.reward < 0.5) else FAIL
+    result_count = len(obs.result) if obs.result else 0
+    print(
+        f"  {icon} [{label:7s}] reward={obs.reward:.4f}  "
+        f"rows={result_count:3d}  done={str(obs.done):5s}  "
+        f"| {(obs.metadata or {}).get('message','')[:55]}"
+    )
+    return obs.reward
+
+
+def main():
+    print("\n" + "="*60)
+    print("  SQL Analytics OpenEnv — Full Smoke Test (10 tasks)")
+    print("="*60)
+
+    env = SQLAnalyticsEnvironment()
+    print(f"\n  {PASS} Environment instantiated (SQLite DB seeded)")
+
+    # ── 1. Rich Schema ────────────────────────────────────────────────────
+    separator("1. Rich Schema (sample data included)")
+    obs = env.reset(task_id="task_001")
+    assert obs.db_schema, "Schema should be populated on reset"
+    assert "Sample" in obs.db_schema, "Rich schema should include sample data"
+    assert "rows)" in obs.db_schema, "Rich schema should include row counts"
+    print(f"  {PASS} reset() returns RICH schema with sample data + row counts")
+    print(f"\n  Schema preview (first 15 lines):\n")
+    for line in (obs.db_schema or "").splitlines()[:15]:
+        print(f"    {line}")
+
+    # ── 2. All 10 tasks — correct SQL ─────────────────────────────────────
+    separator("2. Correct SQL — all 10 tasks (expect reward >= 0.8)")
+    correct_scores = []
+    for task in TASKS:
+        tid = task["task_id"]
+        score = run_test(env, tid, CORRECT_SQL[tid], "CORRECT")
+        correct_scores.append(score)
+
+    # ── 3. All 10 tasks — wrong SQL ───────────────────────────────────────
+    separator("3. Wrong SQL — all 10 tasks (expect reward < 0.5)")
+    wrong_scores = []
+    for task in TASKS:
+        tid = task["task_id"]
+        score = run_test(env, tid, WRONG_SQL[tid], "WRONG")
+        wrong_scores.append(score)
+
+    # ── 4. Efficiency bonus ───────────────────────────────────────────────
+    separator("4. Efficiency Bonus (solve in 1 step vs 5 steps)")
+    env.reset(task_id="task_001")
+    obs1 = env.step(SQLAction(sql=CORRECT_SQL["task_001"]))  # solve in 1 step
+    print(f"  Solved in 1 step   → reward={obs1.reward:.4f}")
+
+    env.reset(task_id="task_001")
+    for _ in range(4):
+        env.step(SQLAction(sql="SELECT 1"))                  # 4 wrong attempts
+    obs5 = env.step(SQLAction(sql=CORRECT_SQL["task_001"])) # solve on 5th step
+    print(f"  Solved in 5 steps  → reward={obs5.reward:.4f}")
+    assert obs1.reward > obs5.reward, "1-step solve should have higher reward than 5-step"
+    print(f"  {PASS} Efficiency bonus working: {obs1.reward:.4f} > {obs5.reward:.4f}")
+
+    # ── 5. Educational error messages ─────────────────────────────────────
+    separator("5. Educational Error Messages")
+    env.reset(task_id="task_001")
+
+    bad_table = env.step(SQLAction(sql="SELECT * FROM orderz"))
+    print(f"  Bad table name  : {bad_table.error[:65]}")
+    assert "Available tables" in (bad_table.error or ""), "Should mention available tables"
+    print(f"  {PASS} Bad table → educational message with available tables")
+
+    bad_col = env.step(SQLAction(sql="SELECT nonexistent_col FROM customers"))
+    print(f"  Bad column name : {bad_col.error[:65]}")
+    print(f"  {PASS} Bad column → educational error message")
+
+    syntax_err = env.step(SQLAction(sql="SELECT FROM customers WHERE"))
+    print(f"  Syntax error    : {syntax_err.error[:65]}")
+    assert "syntax" in (syntax_err.error or "").lower()
+    print(f"  {PASS} Syntax error → educational message")
+
+    # ── 6. New task verification (007–010) ────────────────────────────────
+    separator("6. New Tasks (007-010) correct answers")
+    for tid in ["task_007", "task_008", "task_009", "task_010"]:
+        env.reset(task_id=tid)
+        obs = env.step(SQLAction(sql=CORRECT_SQL[tid]))
+        icon = PASS if obs.reward >= 0.8 else FAIL
+        print(f"  {icon} {tid}  reward={obs.reward:.4f}  done={obs.done}")
+
+    # ── 7. Steps remaining in metadata ───────────────────────────────────
+    separator("7. steps_remaining in metadata")
+    env.reset(task_id="task_002")
+    for i in range(3):
+        obs = env.step(SQLAction(sql="SELECT 1"))
+    remaining = (obs.metadata or {}).get("steps_remaining", -1)
+    assert remaining == 7, f"Expected 7 steps remaining after 3 steps, got {remaining}"
+    print(f"  {PASS} steps_remaining={remaining} correctly tracked")
+
+    # ── 8. State tracking ────────────────────────────────────────────────
+    separator("8. State Tracking")
+    env.reset(task_id="task_003")
+    for i in range(3):
+        env.step(SQLAction(sql="SELECT 1"))
+    s = env.state
+    assert s.attempts == 3
+    assert s.step_count == 3
+    print(f"  {PASS} step_count={s.step_count}  attempts={s.attempts}  task_id={s.task_id}")
+
+    # ── 9. Max attempts cap ───────────────────────────────────────────────
+    separator("9. Max Attempts Cap (10 steps → done=True)")
+    env.reset(task_id="task_002")
+    last_obs = None
+    for _ in range(11):
+        last_obs = env.step(SQLAction(sql="SELECT 1"))
+        if last_obs.done:
+            break
+    assert last_obs.done
+    print(f"  {PASS} done=True after {env.state.attempts} attempts")
+
+    # ── Summary ───────────────────────────────────────────────────────────
+    separator("Summary")
+    avg_correct = sum(correct_scores) / len(correct_scores)
+    avg_wrong   = sum(wrong_scores)   / len(wrong_scores)
+    all_pass    = avg_correct >= 0.8 and avg_wrong < 0.5
+
+    print(f"  Tasks total          : {len(TASKS)}")
+    print(f"  Avg reward (correct) : {avg_correct:.4f}")
+    print(f"  Avg reward (wrong)   : {avg_wrong:.4f}")
+    print()
+    icon = PASS if all_pass else FAIL
+    print(f"  {icon} Overall: {'PASSED' if all_pass else 'FAILED'}")
+    print()
+
+    if not all_pass:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()