Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,42 @@
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends git curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY . /app/env
+WORKDIR /app/env
+
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then uv sync --frozen --no-install-project --no-editable; \
+    else uv sync --no-install-project --no-editable; fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then uv sync --frozen --no-editable; \
+    else uv sync --no-editable; fi
+
+# Final image
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+COPY --from=builder /app/env/.venv /app/.venv
+COPY --from=builder /app/env /app/env
+
+ENV PATH="/app/.venv/bin:$PATH"
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+ENV ENABLE_WEB_INTERFACE=true
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,10 +1,128 @@
----
-title: Sql Tutor Env
-emoji: 🏃
-colorFrom: green
-colorTo: yellow
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: SQL Tutor Env
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+tags:
+  - openenv
+  - openenv-main
+  - rl-environment
+base_path: /web
+---
+
+# SQL Tutor Environment
+
+An **OpenEnv** reinforcement learning environment that trains LLM agents to identify and fix bugs in SQL queries.
+
+Built for the [Meta x Hugging Face x PyTorch India Hackathon 2026](https://www.scaler.com/school-of-technology/meta-pytorch-hackathon).
+
+---
+
+## Task
+
+At each episode the agent receives:
+- A **broken SQL query** with a deliberate bug
+- The **database schema** (tables and columns)
+- A **task description** of what the correct query should return
+
+The agent must either:
+1. **Submit a fix** (`submit_fix`) - provide a corrected SQL query
+2. **Request a hint** (`request_hint`) - get a progressive hint (with a small reward penalty)
+
+The episode ends when the agent submits a correct query or exhausts its 5 allowed actions.
+
+---
+
+## Reward Structure
+
+| Outcome | Reward |
+|---|---|
+| Correct fix, no hints, first try | **+1.0** |
+| Correct fix with hints / retries | **+0.1 to +0.95** (scaled down) |
+| SQL syntax error | **-0.1** |
+| Wrong query (valid SQL, wrong result) | **-0.05** |
+| Requesting a hint | **-0.1** |
+| Max steps reached without solving | **0** |
+
+---
+
+## Challenge Types (5 built-in)
+
+| ID | Bug Type |
+|---|---|
+| `wrong_aggregate` | Missing `SUM()` + `GROUP BY` |
+| `wrong_join` | `INNER JOIN` should be `LEFT JOIN` |
+| `off_by_one_filter` | Wrong comparison operator in `WHERE` |
+| `missing_having` | `WHERE` used instead of `HAVING` for aggregate filter |
+| `wrong_order_limit` | `ASC` should be `DESC` for top-N query |
+
+---
+
+## Quick Start
+
+```python
+from openenv.core import EnvClient
+from sql_tutor_env.client import SQLTutorEnv
+from sql_tutor_env.models import SQLAction
+
+# Connect to the running HF Space
+env = SQLTutorEnv(base_url="https://your-username-sql-tutor-env.hf.space")
+
+# Start an episode
+obs, state = env.reset()
+print(f"Task: {obs.task_description}")
+print(f"Broken query: {obs.broken_query}")
+
+# Submit a fix
+result = env.step(SQLAction(
+    action_type="submit_fix",
+    sql_query="SELECT customer_id, SUM(amount) AS total_amount FROM orders WHERE status = 'completed' GROUP BY customer_id ORDER BY customer_id;"
+))
+print(f"Correct: {result.observation.is_correct}, Reward: {result.reward}")
+```
+
+---
+
+## Integration with TRL / GRPOTrainer
+
+```python
+from trl import GRPOTrainer, GRPOConfig
+from sql_tutor_env.client import SQLTutorEnv
+from sql_tutor_env.models import SQLAction
+
+def rollout_func(prompts, env):
+    obs, _ = env.reset()
+    # ... build prompt from obs, call model, parse SQL, step env
+    pass
+
+env = SQLTutorEnv(base_url="https://your-space.hf.space")
+trainer = GRPOTrainer(
+    model=model,
+    config=GRPOConfig(...),
+    rollout_func=rollout_func,
+    env=env,
+)
+trainer.train()
+```
+
+---
+
+## Project Structure
+
+```
+sql_tutor_env/
+|-- __init__.py
+|-- models.py              # SQLAction, SQLObservation, SQLState
+|-- client.py              # SQLTutorEnv (EnvClient subclass)
+|-- openenv.yaml
+|-- pyproject.toml
+|-- README.md
+`-- server/
+    |-- __init__.py
+    |-- app.py             # FastAPI app via create_app()
+    |-- sql_environment.py # Core reset/step/state logic
+    |-- challenges.py      # Bank of SQL bug challenges
+    |-- requirements.txt
+    `-- Dockerfile
+```

__init__.py

@@ -0,0 +1 @@
+# sql_tutor_env

client.py

@@ -0,0 +1,65 @@
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from models import SQLAction, SQLObservation, SQLState
+
+
+class SQLTutorEnv(EnvClient[SQLAction, SQLObservation, SQLState]):
+    """
+    Client for the SQL Tutor environment.
+
+    Usage:
+        # Connect to a running HF Space
+        env = SQLTutorEnv(base_url="https://your-space.hf.space")
+
+        # Or load locally from Hub
+        env = SQLTutorEnv.from_hub("your-username/sql-tutor-env")
+
+        obs, state = env.reset()
+        result = env.step(SQLAction(action_type="submit_fix", sql_query="SELECT ..."))
+    """
+
+    def __init__(self, base_url: str, **kwargs):
+        super().__init__(base_url=base_url, **kwargs)
+
+    def _step_payload(self, action: SQLAction) -> Dict:
+        return {
+            "action_type": action.action_type,
+            "sql_query": action.sql_query,
+        }
+
+    def _parse_result(self, payload: Dict) -> StepResult[SQLObservation]:
+        obs_data = payload.get("observation", {})
+        observation = SQLObservation(
+            broken_query=obs_data.get("broken_query", ""),
+            schema_description=obs_data.get("schema_description", ""),
+            task_description=obs_data.get("task_description", ""),
+            execution_result=obs_data.get("execution_result", ""),
+            is_correct=obs_data.get("is_correct", False),
+            hint=obs_data.get("hint"),
+            steps_taken=obs_data.get("steps_taken", 0),
+            max_steps=obs_data.get("max_steps", 5),
+            hints_used=obs_data.get("hints_used", 0),
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward", 0.0),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> SQLState:
+        return SQLState(
+            challenge_id=payload.get("challenge_id", ""),
+            broken_query=payload.get("broken_query", ""),
+            correct_query=payload.get("correct_query", ""),
+            schema_sql=payload.get("schema_sql", ""),
+            schema_description=payload.get("schema_description", ""),
+            task_description=payload.get("task_description", ""),
+            hints=payload.get("hints", []),
+            steps_taken=payload.get("steps_taken", 0),
+            max_steps=payload.get("max_steps", 5),
+            hints_used=payload.get("hints_used", 0),
+            is_resolved=payload.get("is_resolved", False),
+            cumulative_reward=payload.get("cumulative_reward", 0.0),
+        )

models.py

@@ -0,0 +1,53 @@
+from typing import Optional, List
+from pydantic import Field
+from openenv.core.env_server.types import Action, Observation, State
+
+
+class SQLAction(Action):
+    action_type: str = Field(
+        ...,
+        description="Either 'submit_fix' to submit a corrected SQL query, or 'request_hint' to get a hint.",
+    )
+    sql_query: Optional[str] = Field(
+        default=None,
+        description="The corrected SQL query. Required when action_type is 'submit_fix'.",
+    )
+
+
+class SQLObservation(Observation):
+    # The broken query the agent needs to fix
+    broken_query: str = Field(..., description="The SQL query that contains a bug.")
+    schema_description: str = Field(..., description="Description of the database schema.")
+    task_description: str = Field(..., description="What the correct query should return.")
+
+    # Feedback from the last action
+    execution_result: str = Field(
+        default="", description="Output or error from executing the submitted query."
+    )
+    is_correct: bool = Field(
+        default=False, description="Whether the last submitted query was correct."
+    )
+    hint: Optional[str] = Field(
+        default=None, description="A hint, if one was requested."
+    )
+
+    # Progress info
+    steps_taken: int = Field(default=0, description="Number of actions taken so far.")
+    max_steps: int = Field(default=5, description="Maximum allowed actions.")
+    hints_used: int = Field(default=0, description="Number of hints used so far.")
+
+
+class SQLState(State):
+    challenge_id: str = ""
+    broken_query: str = ""
+    correct_query: str = ""
+    schema_sql: str = ""
+    schema_description: str = ""
+    task_description: str = ""
+    hints: List[str] = Field(default_factory=list)
+
+    steps_taken: int = 0
+    max_steps: int = 5
+    hints_used: int = 0
+    is_resolved: bool = False
+    cumulative_reward: float = 0.0

openenv.yaml

@@ -0,0 +1,6 @@
+spec_version: 1
+name: sql_tutor_env
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000

pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sql-tutor-env"
+version = "0.1.0"
+description = "An OpenEnv RL environment for training LLM agents to fix broken SQL queries."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "openenv-core>=0.2.2",
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "httpx"]
+
+[tool.hatch.build.targets.wheel]
+only-include = [
+    "__init__.py",
+    "client.py",
+    "models.py",
+    "server",
+]

server/__init__.py

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

server/app.py

@@ -0,0 +1,11 @@
+from openenv.core.env_server.http_server import create_app
+from models import SQLAction, SQLObservation
+from server.sql_environment import SQLTutorEnvironment
+
+app = create_app(
+    SQLTutorEnvironment,
+    SQLAction,
+    SQLObservation,
+    env_name="sql_tutor_env",
+    max_concurrent_envs=10,
+)

server/challenges.py

@@ -0,0 +1,209 @@
+"""
+A bank of SQL challenges. Each challenge has:
+- schema_sql: DDL + seed data to create an in-memory SQLite DB
+- schema_description: human-readable description of tables
+- task_description: what the correct query must return
+- broken_query: a query with a deliberate bug
+- correct_query: the canonical correct query
+- hints: progressive hints (easiest to most specific)
+"""
+
+CHALLENGES = [
+    {
+        "id": "wrong_aggregate",
+        "schema_sql": """
+            CREATE TABLE orders (
+                id INTEGER PRIMARY KEY,
+                customer_id INTEGER,
+                amount REAL,
+                status TEXT
+            );
+            INSERT INTO orders VALUES
+                (1, 1, 120.50, 'completed'),
+                (2, 1,  45.00, 'completed'),
+                (3, 2, 200.00, 'pending'),
+                (4, 2,  80.00, 'completed'),
+                (5, 3,  60.00, 'completed');
+        """,
+        "schema_description": (
+            "Table `orders`: id (int), customer_id (int), amount (real), status (text)."
+        ),
+        "task_description": (
+            "Find each customer's total spending on completed orders. "
+            "Return customer_id and total_amount, ordered by customer_id."
+        ),
+        "broken_query": (
+            "SELECT customer_id, amount AS total_amount "
+            "FROM orders "
+            "WHERE status = 'completed' "
+            "ORDER BY customer_id;"
+        ),
+        "correct_query": (
+            "SELECT customer_id, SUM(amount) AS total_amount "
+            "FROM orders "
+            "WHERE status = 'completed' "
+            "GROUP BY customer_id "
+            "ORDER BY customer_id;"
+        ),
+        "hints": [
+            "The query is missing an aggregation - each customer can have multiple orders.",
+            "You need to use SUM() to add up amounts, and GROUP BY to group per customer.",
+            "Add `SUM(amount) AS total_amount` and `GROUP BY customer_id` to your query.",
+        ],
+    },
+    {
+        "id": "wrong_join",
+        "schema_sql": """
+            CREATE TABLE employees (
+                id INTEGER PRIMARY KEY,
+                name TEXT,
+                department_id INTEGER
+            );
+            CREATE TABLE departments (
+                id INTEGER PRIMARY KEY,
+                name TEXT
+            );
+            INSERT INTO departments VALUES (1, 'Engineering'), (2, 'Marketing'), (3, 'HR');
+            INSERT INTO employees VALUES
+                (1, 'Alice', 1),
+                (2, 'Bob',   2),
+                (3, 'Carol', 1),
+                (4, 'Dave',  NULL);
+        """,
+        "schema_description": (
+            "Table `employees`: id, name, department_id. "
+            "Table `departments`: id, name."
+        ),
+        "task_description": (
+            "List all employees and their department name. "
+            "Include employees with no department (show NULL for their department). "
+            "Return employee name and department name."
+        ),
+        "broken_query": (
+            "SELECT e.name, d.name AS department "
+            "FROM employees e "
+            "INNER JOIN departments d ON e.department_id = d.id;"
+        ),
+        "correct_query": (
+            "SELECT e.name, d.name AS department "
+            "FROM employees e "
+            "LEFT JOIN departments d ON e.department_id = d.id;"
+        ),
+        "hints": [
+            "The result is missing some employees. Check whether all rows from `employees` appear.",
+            "INNER JOIN only returns rows with a match in both tables. Dave has no department.",
+            "Change INNER JOIN to LEFT JOIN so employees without a department are still included.",
+        ],
+    },
+    {
+        "id": "off_by_one_filter",
+        "schema_sql": """
+            CREATE TABLE products (
+                id INTEGER PRIMARY KEY,
+                name TEXT,
+                price REAL,
+                stock INTEGER
+            );
+            INSERT INTO products VALUES
+                (1, 'Widget A', 9.99,  50),
+                (2, 'Widget B', 14.99, 0),
+                (3, 'Gadget X', 49.99, 10),
+                (4, 'Gadget Y', 99.99, 0),
+                (5, 'Gizmo Z',  4.99,  200);
+        """,
+        "schema_description": (
+            "Table `products`: id, name, price (real), stock (int)."
+        ),
+        "task_description": (
+            "Find all products that are currently out of stock (stock = 0). "
+            "Return their name and price."
+        ),
+        "broken_query": (
+            "SELECT name, price FROM products WHERE stock < 0;"
+        ),
+        "correct_query": (
+            "SELECT name, price FROM products WHERE stock = 0;"
+        ),
+        "hints": [
+            "The query returns no rows, but some products have zero stock.",
+            "Check the WHERE condition - you want products where stock equals zero, not less than zero.",
+            "Change `stock < 0` to `stock = 0`.",
+        ],
+    },
+    {
+        "id": "missing_having",
+        "schema_sql": """
+            CREATE TABLE sales (
+                id INTEGER PRIMARY KEY,
+                region TEXT,
+                salesperson TEXT,
+                revenue REAL
+            );
+            INSERT INTO sales VALUES
+                (1,  'North', 'Alice', 5000),
+                (2,  'North', 'Bob',   3000),
+                (3,  'South', 'Carol', 8000),
+                (4,  'South', 'Dave',  2000),
+                (5,  'East',  'Eve',   1500),
+                (6,  'North', 'Alice', 4000),
+                (7,  'South', 'Carol', 7000);
+        """,
+        "schema_description": (
+            "Table `sales`: id, region (text), salesperson (text), revenue (real)."
+        ),
+        "task_description": (
+            "Find regions whose total revenue exceeds 10000. "
+            "Return region and total_revenue."
+        ),
+        "broken_query": (
+            "SELECT region, SUM(revenue) AS total_revenue "
+            "FROM sales "
+            "WHERE SUM(revenue) > 10000 "
+            "GROUP BY region;"
+        ),
+        "correct_query": (
+            "SELECT region, SUM(revenue) AS total_revenue "
+            "FROM sales "
+            "GROUP BY region "
+            "HAVING SUM(revenue) > 10000;"
+        ),
+        "hints": [
+            "You cannot use aggregate functions like SUM() inside a WHERE clause.",
+            "To filter on aggregated values, use HAVING instead of WHERE.",
+            "Move the condition to a HAVING clause after GROUP BY: `HAVING SUM(revenue) > 10000`.",
+        ],
+    },
+    {
+        "id": "wrong_order_limit",
+        "schema_sql": """
+            CREATE TABLE students (
+                id INTEGER PRIMARY KEY,
+                name TEXT,
+                score INTEGER
+            );
+            INSERT INTO students VALUES
+                (1, 'Alice', 88),
+                (2, 'Bob',   72),
+                (3, 'Carol', 95),
+                (4, 'Dave',  60),
+                (5, 'Eve',   91);
+        """,
+        "schema_description": (
+            "Table `students`: id, name, score (int)."
+        ),
+        "task_description": (
+            "Find the top 3 students by score. Return name and score, highest score first."
+        ),
+        "broken_query": (
+            "SELECT name, score FROM students ORDER BY score ASC LIMIT 3;"
+        ),
+        "correct_query": (
+            "SELECT name, score FROM students ORDER BY score DESC LIMIT 3;"
+        ),
+        "hints": [
+            "The query returns the lowest scores, not the highest.",
+            "Check the ORDER BY direction - ASC sorts smallest first.",
+            "Change `ORDER BY score ASC` to `ORDER BY score DESC` to get the top scores.",
+        ],
+    },
+]

server/requirements.txt

@@ -0,0 +1,3 @@
+openenv-core>=0.2.2
+fastapi>=0.104.0
+uvicorn>=0.24.0

server/sql_environment.py

@@ -0,0 +1,155 @@
+import sqlite3
+import random
+from typing import Tuple
+
+from openenv.core.env_server.types import EnvBase
+from models import SQLAction, SQLObservation, SQLState
+from server.challenges import CHALLENGES
+
+
+def _run_query(schema_sql: str, query: str) -> Tuple[bool, str]:
+    """
+    Execute query against an in-memory SQLite DB seeded with schema_sql.
+    Returns (success: bool, result_string: str).
+    """
+    try:
+        conn = sqlite3.connect(":memory:")
+        conn.executescript(schema_sql)
+        cursor = conn.execute(query)
+        rows = cursor.fetchall()
+        col_names = [desc[0] for desc in cursor.description] if cursor.description else []
+        conn.close()
+
+        if not rows:
+            return True, "(no rows returned)"
+
+        # Format as a simple text table
+        header = " | ".join(col_names)
+        sep = "-" * len(header)
+        row_lines = [" | ".join(str(v) for v in row) for row in rows]
+        return True, "\n".join([header, sep] + row_lines)
+
+    except Exception as e:
+        return False, f"ERROR: {e}"
+
+
+def _results_match(schema_sql: str, query_a: str, query_b: str) -> bool:
+    """Check whether two queries return identical result sets."""
+    try:
+        conn = sqlite3.connect(":memory:")
+        conn.executescript(schema_sql)
+
+        rows_a = set(conn.execute(query_a).fetchall())
+        rows_b = set(conn.execute(query_b).fetchall())
+        conn.close()
+        return rows_a == rows_b
+    except Exception:
+        return False
+
+
+class SQLTutorEnvironment(EnvBase[SQLAction, SQLObservation, SQLState]):
+
+    def reset(self) -> Tuple[SQLObservation, SQLState]:
+        challenge = random.choice(CHALLENGES)
+
+        state = SQLState(
+            challenge_id=challenge["id"],
+            broken_query=challenge["broken_query"],
+            correct_query=challenge["correct_query"],
+            schema_sql=challenge["schema_sql"],
+            schema_description=challenge["schema_description"],
+            task_description=challenge["task_description"],
+            hints=challenge["hints"],
+            steps_taken=0,
+            max_steps=5,
+            hints_used=0,
+            is_resolved=False,
+            cumulative_reward=0.0,
+        )
+        self._state = state
+
+        # Show the agent the broken query output so it understands what's wrong
+        _, broken_result = _run_query(state.schema_sql, state.broken_query)
+
+        observation = SQLObservation(
+            broken_query=state.broken_query,
+            schema_description=state.schema_description,
+            task_description=state.task_description,
+            execution_result=f"Current (broken) query output:\n{broken_result}",
+            is_correct=False,
+            hint=None,
+            steps_taken=0,
+            max_steps=state.max_steps,
+            hints_used=0,
+        )
+        return observation, state
+
+    def step(self, action: SQLAction) -> Tuple[SQLObservation, float, bool, SQLState]:
+        state = self._state
+        state.steps_taken += 1
+        reward = 0.0
+        done = False
+        hint = None
+
+        if action.action_type == "request_hint":
+            hint_index = min(state.hints_used, len(state.hints) - 1)
+            hint = state.hints[hint_index]
+            state.hints_used += 1
+            reward = -0.1  # small penalty for using a hint
+            execution_result = f"Current (broken) query output shown for reference."
+            _, execution_result = _run_query(state.schema_sql, state.broken_query)
+            execution_result = f"(Hint requested - no query executed)\nBroken query output:\n{execution_result}"
+            is_correct = False
+
+        elif action.action_type == "submit_fix":
+            if not action.sql_query:
+                execution_result = "ERROR: You chose 'submit_fix' but provided no sql_query."
+                is_correct = False
+                reward = -0.05
+            else:
+                success, execution_result = _run_query(state.schema_sql, action.sql_query)
+
+                if not success:
+                    is_correct = False
+                    reward = -0.1
+                else:
+                    is_correct = _results_match(
+                        state.schema_sql, action.sql_query, state.correct_query
+                    )
+                    if is_correct:
+                        # Reward decreases with hints used and steps taken
+                        base_reward = 1.0
+                        hint_penalty = 0.15 * state.hints_used
+                        step_penalty = 0.05 * max(0, state.steps_taken - 1)
+                        reward = max(0.1, base_reward - hint_penalty - step_penalty)
+                        state.is_resolved = True
+                        done = True
+                    else:
+                        reward = -0.05
+        else:
+            execution_result = f"ERROR: Unknown action_type '{action.action_type}'. Use 'submit_fix' or 'request_hint'."
+            is_correct = False
+            reward = -0.05
+
+        # End episode if max steps reached
+        if state.steps_taken >= state.max_steps and not done:
+            done = True
+
+        state.cumulative_reward += reward
+
+        observation = SQLObservation(
+            broken_query=state.broken_query,
+            schema_description=state.schema_description,
+            task_description=state.task_description,
+            execution_result=execution_result,
+            is_correct=is_correct,
+            hint=hint,
+            steps_taken=state.steps_taken,
+            max_steps=state.max_steps,
+            hints_used=state.hints_used,
+        )
+
+        return observation, reward, done, state
+
+    def get_state(self) -> SQLState:
+        return self._state