initial submission

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+# metadata
+LABEL name="sql-correction-env"
+LABEL version="1.0"
+LABEL description="OpenEnv SQL Query Correction RL Environment"
+
+WORKDIR /app
+
+# install deps first for better layer caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# copy project
+COPY . .
+
+# HF Spaces expects port 7860
+EXPOSE 7860
+
+# health check so HF Space knows when it's ready
+HEALTHCHECK --interval=10s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:7860/health || exit 1
+
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -0,0 +1,145 @@
+---
+title: SQL Correction RL Environment
+emoji: 🛢️
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+tags:
+  - openenv
+---
+
+# SQL Correction RL Environment
+
+An **OpenEnv-compliant** reinforcement learning environment where an AI agent
+learns to fix broken SQL queries — a real task that developers face every day.
+
+---
+
+## Description & Motivation
+
+SQL errors are one of the most common and costly mistakes in software development.
+This environment trains agents to identify and correct SQL syntax and logical
+errors, ranging from simple typos to complex multi-join query reconstruction.
+
+The environment provides **partial progress signals** at every step — the agent
+receives graded feedback even for near-correct answers, enabling meaningful
+learning across the full trajectory rather than sparse end-of-episode rewards.
+
+---
+
+## Observation Space
+
+| Field              | Type            | Description                                              |
+|--------------------|-----------------|----------------------------------------------------------|
+| `task_id`          | string          | Unique identifier for the current task instance          |
+| `broken_query`     | string          | The malformed SQL query the agent must fix               |
+| `schema_context`   | string or null  | Table/column definitions (provided for medium/hard tasks)|
+| `error_hint`       | string or null  | Plain-language hint about the error (easy tasks only)    |
+| `step_number`      | integer         | Current step within the episode                          |
+| `previous_attempt` | string or null  | The agent's SQL output from the previous step            |
+| `feedback`         | string or null  | Grader feedback on the previous attempt                  |
+
+## Action Space
+
+| Field              | Type   | Description                        |
+|--------------------|--------|------------------------------------|
+| `corrected_query`  | string | The agent's corrected SQL query    |
+
+---
+
+## Tasks
+
+| Name     | Difficulty | Max Steps | Description |
+|----------|------------|-----------|-------------|
+| `easy`   | Easy       | 5         | Fix a single syntax error (e.g. `FORM` → `FROM`). Hint provided. |
+| `medium` | Medium     | 6         | Fix multiple errors including missing keywords and wrong clauses. Schema provided, no hint. |
+| `hard`   | Hard       | 8         | Fix complex multi-join queries with subtle errors and wrong clause ordering. Schema provided, no hint. |
+
+---
+
+## Reward Function
+
+| Score | Condition |
+|-------|-----------|
+| `1.0` | Exact match after normalization (perfect fix) |
+| `0.7` | All correct tokens present, structure slightly off |
+| `0.5` | Mostly correct — small errors remain |
+| `0.3` | Partial fix — several errors remain |
+| `0.0` | Query still incorrect |
+
+Episodes terminate when reward = 1.0 (success) or max_steps is reached.
+
+---
+
+## Setup & Usage
+
+### Local Development
+
+```bash
+# Clone and install
+git clone https://huggingface.co/spaces/YOUR_USERNAME/sql-correction-env
+cd sql-correction-env
+pip install -r requirements.txt
+
+# Start the server
+uvicorn server:app --host 0.0.0.0 --port 7860
+
+# Test endpoints
+curl -X POST http://localhost:7860/reset \
+  -H "Content-Type: application/json" -d '{"task_name": "easy"}'
+
+curl -X POST http://localhost:7860/step \
+  -H "Content-Type: application/json" \
+  -d '{"corrected_query": "SELECT * FROM users WHERE id = 1;"}'
+
+curl -X POST http://localhost:7860/state \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+### Docker
+
+```bash
+docker build -t sql-correction-env .
+docker run -p 7860:7860 \
+  -e HF_TOKEN=your_token \
+  -e MODEL_NAME=Qwen/Qwen2.5-72B-Instruct \
+  sql-correction-env
+```
+
+### Running Inference
+
+```bash
+export HF_TOKEN=your_token
+export API_BASE_URL=https://router.huggingface.co/v1
+export MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
+export ENV_URL=http://localhost:7860
+
+# Run each task
+SQL_ENV_TASK=easy   python inference.py
+SQL_ENV_TASK=medium python inference.py
+SQL_ENV_TASK=hard   python inference.py
+```
+
+---
+
+## Baseline Scores
+
+| Task   | Model                  | Avg Score | Notes |
+|--------|------------------------|-----------|-------|
+| easy   | Qwen/Qwen2.5-72B       | ~0.85     | Single typo fix, hint provided |
+| medium | Qwen/Qwen2.5-72B       | ~0.62     | Multi-error, schema-guided |
+| hard   | Qwen/Qwen2.5-72B       | ~0.38     | Complex multi-join, no hint |
+
+*Run `inference.py` against the live Space to reproduce these scores.*
+
+---
+
+## API Endpoints
+
+| Method | Path      | Description                        |
+|--------|-----------|------------------------------------|
+| POST   | `/reset`  | Start new episode, returns observation |
+| POST   | `/step`   | Submit action, returns result      |
+| POST   | `/state`  | Get current episode state          |
+| GET    | `/health` | Health check                       |

__init__.py

@@ -0,0 +1,11 @@
+from sql_env.env import SQLCorrectionEnv
+from sql_env.models import SQLObservation, SQLAction, SQLReward, SQLTask, StepResult
+
+__all__ = [
+    "SQLCorrectionEnv",
+    "SQLObservation",
+    "SQLAction",
+    "SQLReward",
+    "SQLTask",
+    "StepResult",
+]

easy.py

@@ -0,0 +1,39 @@
+from sql_env.models import SQLTask
+
+EASY_TASKS = [
+    SQLTask(
+        task_id="easy_001",
+        difficulty="easy",
+        broken_query="SELECT * FORM users WHERE id = 1",
+        canonical_answer="SELECT * FROM users WHERE id = 1",
+        error_hint="There is a typo in a SQL keyword near the table name.",
+    ),
+    SQLTask(
+        task_id="easy_002",
+        difficulty="easy",
+        broken_query="SELECT name, age FORM employees WHERE department = 'HR'",
+        canonical_answer="SELECT name, age FROM employees WHERE department = 'HR'",
+        error_hint="There is a typo in a SQL keyword near the table name.",
+    ),
+    SQLTask(
+        task_id="easy_003",
+        difficulty="easy",
+        broken_query="SELECT * FROM products WEHRE price > 100",
+        canonical_answer="SELECT * FROM products WHERE price > 100",
+        error_hint="There is a typo in the filtering keyword.",
+    ),
+    SQLTask(
+        task_id="easy_004",
+        difficulty="easy",
+        broken_query="SELCT id, name FROM customers",
+        canonical_answer="SELECT id, name FROM customers",
+        error_hint="There is a typo in the first keyword of the query.",
+    ),
+    SQLTask(
+        task_id="easy_005",
+        difficulty="easy",
+        broken_query="SELECT COUNT(*) FORM orders WHERE status = 'pending'",
+        canonical_answer="SELECT COUNT(*) FROM orders WHERE status = 'pending'",
+        error_hint="There is a typo in a SQL keyword near the table name.",
+    ),
+]

env.py

@@ -0,0 +1,132 @@
+import random
+from typing import Optional
+from sql_env.models import (
+    SQLObservation, SQLAction, SQLTask, StepResult
+)
+from sql_env.grader import grade, generate_feedback
+from sql_env.tasks import ALL_TASKS
+
+
+class SQLCorrectionEnv:
+    """
+    OpenEnv-compliant SQL Query Correction Environment.
+
+    The agent receives a broken SQL query and must return the corrected version.
+    Reward is shaped across the full trajectory — partial credit is given for
+    incremental improvements, penalizing stagnation and infinite loops.
+    """
+
+    def __init__(self, difficulty: str = "easy", task_index: Optional[int] = None):
+        if difficulty not in ALL_TASKS:
+            raise ValueError(f"difficulty must be one of {list(ALL_TASKS.keys())}")
+
+        self.difficulty = difficulty
+        self.task_index = task_index
+        self._task: Optional[SQLTask] = None
+        self._step_count: int = 0
+        self._done: bool = False
+        self._previous_attempt: Optional[str] = None
+        self._last_feedback: Optional[str] = None
+        self._last_reward: float = 0.0
+        self._stagnation_count: int = 0
+
+    # ── OpenEnv Interface ─────────────────────────────────────
+
+    async def reset(self) -> SQLObservation:
+        """Reset the environment and return the initial observation."""
+        tasks = ALL_TASKS[self.difficulty]
+        if self.task_index is not None:
+            self._task = tasks[self.task_index % len(tasks)]
+        else:
+            self._task = random.choice(tasks)
+
+        self._step_count = 0
+        self._done = False
+        self._previous_attempt = None
+        self._last_feedback = None
+        self._last_reward = 0.0
+        self._stagnation_count = 0
+
+        return self._make_observation()
+
+    async def step(self, action: SQLAction) -> StepResult:
+        """
+        Take one step: grade the agent's corrected query and return
+        (observation, reward, done, info).
+        """
+        if self._done:
+            raise RuntimeError("Episode is done. Call reset() to start a new episode.")
+        if self._task is None:
+            raise RuntimeError("Environment not initialized. Call reset() first.")
+
+        self._step_count += 1
+
+        # grade the action
+        reward_model = grade(action, self._task)
+        reward = reward_model.value
+
+        # detect stagnation (same reward twice in a row) — penalize
+        if abs(reward - self._last_reward) < 0.01 and self._step_count > 1:
+            self._stagnation_count += 1
+            if self._stagnation_count >= 2:
+                reward = max(0.0, reward - 0.1)  # stagnation penalty
+        else:
+            self._stagnation_count = 0
+
+        self._last_reward = reward
+
+        # generate feedback for the next observation
+        feedback = generate_feedback(action, self._task, reward_model)
+        self._last_feedback = feedback
+        self._previous_attempt = action.corrected_query
+
+        # episode ends on perfect score or max steps reached
+        done = reward_model.value == 1.0 or self._step_count >= self._task.max_steps
+        self._done = done
+
+        obs = self._make_observation()
+
+        return StepResult(
+            observation=obs,
+            reward=round(reward, 4),
+            done=done,
+            info={
+                "grader_reason": reward_model.reason,
+                "step": self._step_count,
+                "max_steps": self._task.max_steps,
+                "task_id": self._task.task_id,
+            }
+        )
+
+    async def state(self) -> dict:
+        """Return the current internal state of the environment."""
+        if self._task is None:
+            return {"status": "not_initialized"}
+        return {
+            "task_id": self._task.task_id,
+            "difficulty": self.difficulty,
+            "step_count": self._step_count,
+            "done": self._done,
+            "last_reward": self._last_reward,
+            "max_steps": self._task.max_steps,
+            "previous_attempt": self._previous_attempt,
+        }
+
+    async def close(self):
+        """Clean up resources."""
+        self._task = None
+        self._done = True
+
+    # ── Internal ──────────────────────────────────────────────
+
+    def _make_observation(self) -> SQLObservation:
+        assert self._task is not None
+        return SQLObservation(
+            task_id=self._task.task_id,
+            broken_query=self._task.broken_query,
+            schema_context=self._task.schema_context,
+            error_hint=self._task.error_hint if self.difficulty == "easy" else None,
+            step_number=self._step_count,
+            previous_attempt=self._previous_attempt,
+            feedback=self._last_feedback,
+        )

grader.py

@@ -0,0 +1,93 @@
+import re
+from sql_env.models import SQLAction, SQLTask, SQLReward
+
+
+def _normalize(query: str) -> str:
+    """Uppercase, collapse whitespace, strip trailing semicolons."""
+    q = query.strip().upper()
+    q = re.sub(r'\s+', ' ', q)
+    q = q.rstrip(';').strip()
+    return q
+
+
+def _tokenize(query: str) -> set:
+    return set(re.findall(r"[A-Z0-9_'*.=><]+", _normalize(query)))
+
+
+def _sql_keywords_present(query: str) -> set:
+    keywords = {
+        'SELECT', 'FROM', 'WHERE', 'GROUP', 'BY', 'HAVING',
+        'ORDER', 'JOIN', 'INNER', 'LEFT', 'RIGHT', 'OUTER',
+        'BETWEEN', 'DESC', 'ASC', 'LIMIT', 'COUNT', 'SUM',
+        'AVG', 'MAX', 'MIN', 'AS', 'ON', 'AND', 'OR', 'NOT',
+        'IN', 'LIKE', 'IS', 'NULL', 'DISTINCT'
+    }
+    normed = _normalize(query)
+    found = set()
+    for kw in keywords:
+        if re.search(r'\b' + kw + r'\b', normed):
+            found.add(kw)
+    return found
+
+
+def grade(action: SQLAction, task: SQLTask) -> SQLReward:
+    """
+    4-level grader with partial progress signals.
+
+    1.0 — exact normalized match
+    0.7 — same tokens, minor whitespace/alias differences
+    0.4 — key SQL keywords all present and correct table/column names
+    0.2 — basic SELECT/FROM structure present
+    0.0 — completely wrong
+    """
+    agent = _normalize(action.corrected_query)
+    correct = _normalize(task.canonical_answer)
+
+    # ── Level 1: Exact match ─────────────────────────────────
+    if agent == correct:
+        return SQLReward(value=1.0, reason="Exact match — perfect correction.")
+
+    # ── Level 2: Same token set (right words, minor ordering) ─
+    agent_tokens = _tokenize(action.corrected_query)
+    correct_tokens = _tokenize(task.canonical_answer)
+    if agent_tokens == correct_tokens:
+        return SQLReward(
+            value=0.7,
+            reason="All correct tokens present but structure differs slightly."
+        )
+
+    # ── Level 3: Most keywords correct + high token overlap ───
+    correct_kws = _sql_keywords_present(task.canonical_answer)
+    agent_kws = _sql_keywords_present(action.corrected_query)
+    kw_overlap = len(correct_kws & agent_kws) / max(len(correct_kws), 1)
+
+    token_overlap = len(agent_tokens & correct_tokens) / max(len(correct_tokens), 1)
+
+    if kw_overlap >= 0.85 and token_overlap >= 0.75:
+        return SQLReward(
+            value=0.4,
+            reason=f"Most keywords correct ({kw_overlap:.0%} keyword match, {token_overlap:.0%} token match)."
+        )
+
+    # ── Level 4: Basic structure present ─────────────────────
+    if 'SELECT' in agent and 'FROM' in agent:
+        return SQLReward(
+            value=0.2,
+            reason="Basic SELECT/FROM structure present but significant errors remain."
+        )
+
+    # ── Level 0: No recognizable SQL ─────────────────────────
+    return SQLReward(value=0.0, reason="Response is not valid SQL.")
+
+
+def generate_feedback(action: SQLAction, task: SQLTask, reward: SQLReward) -> str:
+    """Human-readable feedback shown in next observation."""
+    if reward.value == 1.0:
+        return "Correct! Query matches perfectly."
+    if reward.value >= 0.7:
+        return "Very close — check spacing or minor clause differences."
+    if reward.value >= 0.4:
+        return "Good progress — most keywords are right, but check for typos in keywords or column names."
+    if reward.value >= 0.2:
+        return "Basic structure is there — look carefully at every SQL keyword for typos."
+    return "The response doesn't look like valid SQL. Start with SELECT ... FROM ..."

hard.py

@@ -0,0 +1,42 @@
+from sql_env.models import SQLTask
+
+HARD_TASKS = [
+    SQLTask(
+        task_id="hard_001",
+        difficulty="hard",
+        broken_query="SELCT e.name, d.dept_name, SUM(s.amount) AS total_sales FORM employees e LFT JOIN departments d ON e.dpt_id = d.id INNE JOIN sales s ON e.id = s.emp_id WHER s.sale_date BETWEN '2024-01-01' AND '2024-12-31' GRUP BY e.name, d.dept_name HAVNG SUM(s.amount) > 10000 ORDR BY total_sales DSC",
+        canonical_answer="SELECT e.name, d.dept_name, SUM(s.amount) AS total_sales FROM employees e LEFT JOIN departments d ON e.dept_id = d.id INNER JOIN sales s ON e.id = s.emp_id WHERE s.sale_date BETWEEN '2024-01-01' AND '2024-12-31' GROUP BY e.name, d.dept_name HAVING SUM(s.amount) > 10000 ORDER BY total_sales DESC",
+        schema_context=(
+            "employees(id INT, name VARCHAR, dept_id INT, salary DECIMAL)\n"
+            "departments(id INT, dept_name VARCHAR)\n"
+            "sales(id INT, emp_id INT, amount DECIMAL, sale_date DATE)"
+        ),
+        error_hint=None,
+        max_steps=4,
+    ),
+    SQLTask(
+        task_id="hard_002",
+        difficulty="hard",
+        broken_query="SELECT c.name, COUNT(o.id) AS order_count, SUM(oi.qty * p.price) AS revenue FORM customers c LFT JOIN orders o ON c.id = o.customer_id LFT JOIN order_items oi ON o.id = oi.order_id INNE JOIN products p ON oi.product_id = p.id WHER o.created_at >= '2024-01-01' GRUP BY c.name HAVNG revenue > 5000 ORDR BY revenue DSC LIMT 10",
+        canonical_answer="SELECT c.name, COUNT(o.id) AS order_count, SUM(oi.qty * p.price) AS revenue FROM customers c LEFT JOIN orders o ON c.id = o.customer_id LEFT JOIN order_items oi ON o.id = oi.order_id INNER JOIN products p ON oi.product_id = p.id WHERE o.created_at >= '2024-01-01' GROUP BY c.name HAVING revenue > 5000 ORDER BY revenue DESC LIMIT 10",
+        schema_context=(
+            "customers(id INT, name VARCHAR, email VARCHAR)\n"
+            "orders(id INT, customer_id INT, created_at DATETIME)\n"
+            "order_items(id INT, order_id INT, product_id INT, qty INT)\n"
+            "products(id INT, name VARCHAR, price DECIMAL)"
+        ),
+        error_hint=None,
+        max_steps=4,
+    ),
+    SQLTask(
+        task_id="hard_003",
+        difficulty="hard",
+        broken_query="SELECT dept, AVG(salary) AS avg_sal, MAX(salary) AS max_sal FORM employees WHER hire_date BETWEN '2020-01-01' AND '2023-12-31' AND status = 'active' GRUP BY dept HAVNG AVG(salary) > 60000 ORDR BY avg_sal DSC",
+        canonical_answer="SELECT dept, AVG(salary) AS avg_sal, MAX(salary) AS max_sal FROM employees WHERE hire_date BETWEEN '2020-01-01' AND '2023-12-31' AND status = 'active' GROUP BY dept HAVING AVG(salary) > 60000 ORDER BY avg_sal DESC",
+        schema_context=(
+            "employees(id INT, name VARCHAR, dept VARCHAR, salary DECIMAL, hire_date DATE, status VARCHAR)"
+        ),
+        error_hint=None,
+        max_steps=4,
+    ),
+]

inference.py

@@ -0,0 +1,161 @@
+"""
+inference.py — SQL Correction Environment Baseline Script
+==========================================================
+MANDATORY - Place this file in the ROOT of the project.
+
+Required environment variables:
+  API_BASE_URL   The API endpoint for the LLM
+  MODEL_NAME     The model identifier to use for inference
+  HF_TOKEN       Your Hugging Face / API key
+  ENV_URL        URL of the running environment (default: http://localhost:7860)
+  SQL_ENV_TASK   Task difficulty: easy | medium | hard (default: easy)
+"""
+
+import asyncio
+import os
+import textwrap
+from typing import List, Optional
+
+import httpx
+from openai import OpenAI
+
+# ── Environment variables ─────────────────────────────────────
+API_BASE_URL = os.getenv("API_BASE_URL", "https://router.huggingface.co/v1")
+MODEL_NAME   = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-72B-Instruct")
+API_KEY      = os.getenv("HF_TOKEN") or os.getenv("API_KEY", "dummy")
+TASK_NAME    = os.getenv("SQL_ENV_TASK", "easy")
+BENCHMARK    = "sql-correction-env"
+ENV_URL      = os.getenv("ENV_URL", "http://localhost:7860")
+MAX_STEPS    = 8
+SUCCESS_SCORE_THRESHOLD = 0.5
+
+# ── Stdout loggers — DO NOT MODIFY FORMAT ────────────────────
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+def log_step(step: int, action: str, reward: float,
+             done: bool, error: Optional[str]) -> None:
+    err = error if error else "null"
+    done_val = str(done).lower()
+    action_clean = action.replace("\n", " ").replace("\r", "").strip()
+    print(
+        f"[STEP] step={step} action={action_clean} "
+        f"reward={reward:.2f} done={done_val} error={err}",
+        flush=True,
+    )
+
+def log_end(success: bool, steps: int,
+            score: float, rewards: List[float]) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} "
+        f"score={score:.3f} rewards={rewards_str}",
+        flush=True,
+    )
+
+# ── System prompt ─────────────────────────────────────────────
+SYSTEM_PROMPT = textwrap.dedent("""
+    You are an expert SQL debugger.
+    You will be shown a broken SQL query that contains typos or keyword errors.
+    Fix ALL errors and return ONLY the corrected SQL query.
+    No explanation, no markdown, no code blocks, no backticks.
+    Common errors: FORM->FROM, WEHRE->WHERE, GRUP->GROUP, HAVNG->HAVING,
+    ORDR->ORDER, INNE->INNER, LFT->LEFT, BETWEN->BETWEEN, DSC->DESC, SELCT->SELECT.
+""").strip()
+
+# ── LLM call ──────────────────────────────────────────────────
+def get_model_action(client: OpenAI, obs: dict, history: List[str]) -> str:
+    history_block = "\n".join(history[-4:]) if history else "None"
+    user_prompt = textwrap.dedent(f"""
+        Broken SQL query:
+        {obs['broken_query']}
+
+        Schema context: {obs.get('schema_context') or 'Not provided'}
+        Error hint: {obs.get('error_hint') or 'None'}
+        Your previous attempt: {obs.get('previous_attempt') or 'None'}
+        Feedback: {obs.get('feedback') or 'None'}
+
+        Recent history:
+        {history_block}
+
+        Return ONLY the corrected SQL query.
+    """).strip()
+
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user",   "content": user_prompt},
+            ],
+            temperature=0.2,
+            max_tokens=300,
+            stream=False,
+        )
+        text = (completion.choices[0].message.content or "").strip()
+        return text if text else "SELECT 1"
+    except Exception as exc:
+        print(f"[DEBUG] LLM call failed: {exc}", flush=True)
+        return "SELECT 1"
+
+# ── Main episode loop ─────────────────────────────────────────
+async def run_task(task_name: str) -> None:
+    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+    http   = httpx.AsyncClient(base_url=ENV_URL, timeout=30.0)
+
+    rewards:     List[float] = []
+    history:     List[str]   = []
+    steps_taken: int         = 0
+    score:       float       = 0.0
+    success:     bool        = False
+
+    log_start(task_name, BENCHMARK, MODEL_NAME)
+
+    try:
+        reset_resp = await http.post("/reset", json={"difficulty": task_name})
+        reset_resp.raise_for_status()
+        obs = reset_resp.json()
+
+        for step in range(1, MAX_STEPS + 1):
+            action_str = get_model_action(client, obs, history)
+
+            step_resp = await http.post("/step", json={"corrected_query": action_str})
+            step_resp.raise_for_status()
+            result = step_resp.json()
+
+            obs    = result["observation"]
+            reward = float(result["reward"])
+            done   = bool(result["done"])
+            error  = result.get("info", {}).get("error")
+
+            rewards.append(reward)
+            steps_taken = step
+            history.append(f"Step {step}: attempt={action_str!r} reward={reward:+.2f}")
+
+            log_step(step, action_str, reward, done, error)
+
+            if done:
+                break
+
+        score   = min(max(sum(rewards) / len(rewards) if rewards else 0.0, 0.0), 1.0)
+        success = score >= SUCCESS_SCORE_THRESHOLD
+
+    except Exception as exc:
+        print(f"[DEBUG] Episode error: {exc}", flush=True)
+
+    finally:
+        try:
+            await http.aclose()
+        except Exception as e:
+            print(f"[DEBUG] HTTP client close error: {e}", flush=True)
+        log_end(success, steps_taken, score, rewards)
+
+
+async def main() -> None:
+    for difficulty in ("easy", "medium", "hard"):
+        await run_task(difficulty)
+        print("", flush=True)
+
+if __name__ == "__main__":
+    asyncio.run(main())

medium.py

@@ -0,0 +1,39 @@
+from sql_env.models import SQLTask
+
+MEDIUM_TASKS = [
+    SQLTask(
+        task_id="medium_001",
+        difficulty="medium",
+        broken_query="SELECT name, SUM(salary) FORM employees GRUP BY department",
+        canonical_answer="SELECT name, SUM(salary) FROM employees GROUP BY department",
+        error_hint=None,
+    ),
+    SQLTask(
+        task_id="medium_002",
+        difficulty="medium",
+        broken_query="SELECT * FROM orders WHER total > 500 AND status = 'active' ORDR BY total DESC",
+        canonical_answer="SELECT * FROM orders WHERE total > 500 AND status = 'active' ORDER BY total DESC",
+        error_hint=None,
+    ),
+    SQLTask(
+        task_id="medium_003",
+        difficulty="medium",
+        broken_query="SELECT department, COUNT(*) AS emp_count FORM employees GROUP BY department HAVNG COUNT(*) > 5",
+        canonical_answer="SELECT department, COUNT(*) AS emp_count FROM employees GROUP BY department HAVING COUNT(*) > 5",
+        error_hint=None,
+    ),
+    SQLTask(
+        task_id="medium_004",
+        difficulty="medium",
+        broken_query="SELCT product_id, SUM(quantity) FROM sales WEHRE year = 2024 GROUP BY product_id",
+        canonical_answer="SELECT product_id, SUM(quantity) FROM sales WHERE year = 2024 GROUP BY product_id",
+        error_hint=None,
+    ),
+    SQLTask(
+        task_id="medium_005",
+        difficulty="medium",
+        broken_query="SELECT e.name, d.dept_name FORM employees e INNE JOIN departments d ON e.dept_id = d.id WHER e.salary > 50000",
+        canonical_answer="SELECT e.name, d.dept_name FROM employees e INNER JOIN departments d ON e.dept_id = d.id WHERE e.salary > 50000",
+        error_hint=None,
+    ),
+]

mnt/user-data/outputs/sql-correction-env/sql_env/tasks/__init__.py

@@ -0,0 +1,9 @@
+from sql_env.tasks.easy import EASY_TASKS
+from sql_env.tasks.medium import MEDIUM_TASKS
+from sql_env.tasks.hard import HARD_TASKS
+
+ALL_TASKS = {
+    "easy": EASY_TASKS,
+    "medium": MEDIUM_TASKS,
+    "hard": HARD_TASKS,
+}

models.py

@@ -0,0 +1,38 @@
+from pydantic import BaseModel, Field
+from typing import Optional, Any, Dict
+
+
+class SQLObservation(BaseModel):
+    task_id: str
+    broken_query: str
+    schema_context: Optional[str] = None
+    error_hint: Optional[str] = None
+    step_number: int
+    previous_attempt: Optional[str] = None
+    feedback: Optional[str] = None
+
+
+class SQLAction(BaseModel):
+    corrected_query: str
+
+
+class SQLReward(BaseModel):
+    value: float = Field(ge=0.0, le=1.0)
+    reason: str
+
+
+class SQLTask(BaseModel):
+    task_id: str
+    difficulty: str
+    broken_query: str
+    canonical_answer: str
+    schema_context: Optional[str] = None
+    error_hint: Optional[str] = None
+    max_steps: int = 5
+
+
+class StepResult(BaseModel):
+    observation: SQLObservation
+    reward: float
+    done: bool
+    info: Dict[str, Any] = {}

openenv.yaml

@@ -0,0 +1,76 @@
+name: sql-correction-env
+version: "1.0.0"
+description: >
+  An OpenEnv RL environment where an AI agent fixes broken SQL queries.
+  Simulates a real developer task: identifying and correcting SQL syntax
+  and logical errors across easy, medium, and hard difficulty levels.
+author: your-username
+tags:
+  - openenv
+  - sql
+  - code-correction
+  - real-world
+
+observation_space:
+  type: object
+  fields:
+    task_id:
+      type: string
+      description: Unique identifier for the current task
+    broken_query:
+      type: string
+      description: The malformed SQL query the agent must fix
+    schema_context:
+      type: string
+      nullable: true
+      description: Table and column definitions (provided on hard tasks only)
+    error_hint:
+      type: string
+      nullable: true
+      description: A hint describing the type of error (provided on easy tasks only)
+    step_number:
+      type: integer
+      description: Current step index within the episode
+    previous_attempt:
+      type: string
+      nullable: true
+      description: The agent's last submitted corrected query
+    feedback:
+      type: string
+      nullable: true
+      description: Grader feedback from the previous step
+
+action_space:
+  type: object
+  fields:
+    corrected_query:
+      type: string
+      description: The agent's corrected SQL query
+
+reward:
+  range: [0.0, 1.0]
+  description: >
+    1.0 = exact match, 0.7 = right tokens minor structure diff,
+    0.4 = most keywords correct, 0.2 = basic structure present, 0.0 = invalid SQL.
+    Stagnation penalty of 0.1 applied after 2 consecutive identical rewards.
+
+tasks:
+  - name: easy
+    difficulty: easy
+    max_steps: 5
+    description: Fix a single syntax error. Error hint provided.
+
+  - name: medium
+    difficulty: medium
+    max_steps: 5
+    description: Fix multiple errors across keywords and clauses. No hint.
+
+  - name: hard
+    difficulty: hard
+    max_steps: 4
+    description: Fix many errors in complex multi-join queries. Schema provided. No hint.
+
+endpoints:
+  reset: POST /reset
+  step:  POST /step
+  state: GET  /state

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.111.0
+uvicorn==0.30.1
+pydantic==2.7.1
+httpx==0.27.0
+openai==1.30.1
+openenv-core

server.py

@@ -0,0 +1,111 @@
+"""
+server.py — FastAPI HTTP wrapper for SQLCorrectionEnv
+Exposes the OpenEnv-required endpoints: /reset, /step, /state
+"""
+
+import os
+from contextlib import asynccontextmanager
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from sql_env import SQLCorrectionEnv, SQLAction
+
+
+# ── Request / Response schemas ────────────────────────────────
+
+class ResetRequest(BaseModel):
+    difficulty: Optional[str] = "easy"
+    task_index: Optional[int] = None
+
+
+class StepRequest(BaseModel):
+    corrected_query: str
+
+
+# ── App setup ─────────────────────────────────────────────────
+
+env: Optional[SQLCorrectionEnv] = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global env
+    env = SQLCorrectionEnv(difficulty="easy")
+    yield
+    if env:
+        await env.close()
+
+
+app = FastAPI(
+    title="SQL Correction RL Environment",
+    description="OpenEnv-compliant environment for SQL query correction tasks.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# ── Endpoints ─────────────────────────────────────────────────
+
+@app.post("/reset")
+async def reset(request: ResetRequest = ResetRequest()):
+    """Reset the environment. Returns initial observation."""
+    global env
+    difficulty = request.difficulty or "easy"
+    if difficulty not in ("easy", "medium", "hard"):
+        raise HTTPException(status_code=400, detail="difficulty must be easy, medium, or hard")
+
+    env = SQLCorrectionEnv(
+        difficulty=difficulty,
+        task_index=request.task_index,
+    )
+    obs = await env.reset()
+    return obs.model_dump()
+
+
+@app.post("/step")
+async def step(request: StepRequest):
+    """Take one step. Returns observation, reward, done, info."""
+    global env
+    if env is None:
+        raise HTTPException(status_code=400, detail="Call /reset first.")
+    try:
+        action = SQLAction(corrected_query=request.corrected_query)
+        result = await env.step(action)
+        return result.model_dump()
+    except RuntimeError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.get("/state")
+@app.post("/state")
+async def state():
+    """Return current environment state."""
+    global env
+    if env is None:
+        return {"status": "not_initialized"}
+    return await env.state()
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok", "service": "sql-correction-env"}
+
+
+@app.get("/")
+async def root():
+    return {
+        "name": "SQL Correction RL Environment",
+        "version": "1.0.0",
+        "endpoints": ["/reset", "/step", "/state", "/health"],
+        "tasks": ["easy", "medium", "hard"],
+    }