Fix server entrypoint packaging and align environment docs

README.md

@@ -1,6 +1,6 @@
 ---
 title: SQL Correction RL Environment
-emoji: 🛢️
+emoji: "🛠️"
 colorFrom: blue
 colorTo: indigo
 sdk: docker
@@ -12,15 +12,16 @@ tags:
 # 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.
+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.
+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
@@ -34,7 +35,7 @@ learning across the full trajectory rather than sparse end-of-episode rewards.
 |--------------------|-----------------|----------------------------------------------------------|
 | `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)|
+| `schema_context`   | string or null  | Table and column definitions when a task includes them   |
 | `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            |
@@ -42,9 +43,9 @@ learning across the full trajectory rather than sparse end-of-episode rewards.
 
 ## Action Space
 
-| Field              | Type   | Description                        |
-|--------------------|--------|------------------------------------|
-| `corrected_query`  | string | The agent's corrected SQL query    |
+| Field              | Type   | Description                     |
+|--------------------|--------|---------------------------------|
+| `corrected_query`  | string | The agent's corrected SQL query |
 
 ---
 
@@ -52,9 +53,9 @@ learning across the full trajectory rather than sparse end-of-episode rewards.
 
 | 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. |
+| `easy`   | Easy       | 5         | Fix a single syntax error (for example `FORM` -> `FROM`). Hint provided. |
+| `medium` | Medium     | 5         | Fix multiple errors including missing keywords and wrong clauses. No hint. |
+| `hard`   | Hard       | 4         | Fix complex multi-join queries with subtle errors and wrong clause ordering. Schema provided, no hint. |
 
 ---
 
@@ -64,11 +65,11 @@ learning across the full trajectory rather than sparse end-of-episode rewards.
 |-------|-----------|
 | `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.4` | Most keywords correct and token overlap is high |
+| `0.2` | Basic `SELECT ... FROM ...` structure present |
 | `0.0` | Query still incorrect |
 
-Episodes terminate when reward = 1.0 (success) or max_steps is reached.
+Episodes terminate when reward = 1.0 (success) or max steps is reached.
 
 ---
 
@@ -125,11 +126,11 @@ 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 |
+| 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 correction |
+| hard   | Qwen/Qwen2.5-72B | ~0.38     | Complex multi-join, schema-guided |
 
 *Run `inference.py` against the live Space to reproduce these scores.*
 

openenv.yaml

@@ -23,7 +23,7 @@ observation_space:
     schema_context:
       type: string
       nullable: true
-      description: Table and column definitions (provided on hard tasks only)
+      description: Table and column definitions when a task includes schema context
     error_hint:
       type: string
       nullable: true
@@ -73,4 +73,4 @@ tasks:
 endpoints:
   reset: POST /reset
   step:  POST /step
-  state: GET  /state
+  state: POST /state

pyproject.toml

@@ -20,4 +20,4 @@ build-backend = "hatchling.build"
 packages = ["sql_env"]
 
 [project.scripts]
-server = "server.app:main"
+server = "sql_env.server:main"

server.py

@@ -1,111 +1,9 @@
-"""
-server.py — FastAPI HTTP wrapper for SQLCorrectionEnv
-Exposes the OpenEnv-required endpoints: /reset, /step, /state
-"""
+"""Compatibility wrapper for local `python server.py` runs."""
 
-import os
-from contextlib import asynccontextmanager
-from typing import Optional
+from sql_env.server import app, main
 
-from fastapi import FastAPI, HTTPException
-from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel
+__all__ = ["app", "main"]
 
-from sql_env import SQLCorrectionEnv, SQLAction
 
-
-# ── Request / Response schemas ────────────────────────────────
-
-class ResetRequest(BaseModel):
-    difficulty: Optional[str] = "easy"
-    task_name: Optional[str] = None
-    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.task_name or 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.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"],
-    }
+if __name__ == "__main__":
+    main()

server/app.py

@@ -1,8 +0,0 @@
-from server import app
-import uvicorn
-
-def main():
-    uvicorn.run(app, host="0.0.0.0", port=7860)
-
-if __name__ == "__main__":
-    main()

sql_env/models.py

@@ -35,4 +35,4 @@ class StepResult(BaseModel):
     observation: SQLObservation
     reward: float
     done: bool
-    info: Dict[str, Any] = {}
+    info: Dict[str, Any] = Field(default_factory=dict)

sql_env/server.py

@@ -0,0 +1,116 @@
+"""
+FastAPI HTTP wrapper for SQLCorrectionEnv.
+
+Exposes the OpenEnv-required endpoints: /reset, /step, /state.
+"""
+
+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 SQLAction, SQLCorrectionEnv
+
+
+class ResetRequest(BaseModel):
+    difficulty: Optional[str] = "easy"
+    task_name: Optional[str] = None
+    task_index: Optional[int] = None
+
+
+class StepRequest(BaseModel):
+    corrected_query: str
+
+
+env: Optional[SQLCorrectionEnv] = None
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    global env
+    env = SQLCorrectionEnv(difficulty="easy")
+    yield
+    if env is not None:
+        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=["*"],
+)
+
+
+@app.post("/reset")
+async def reset(request: ResetRequest = ResetRequest()):
+    """Reset the environment and return the initial observation."""
+    global env
+    difficulty = request.task_name or 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 and return the new observation, reward, done flag, and 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 exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@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"],
+    }
+
+
+def main():
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=7860)
+
+
+if __name__ == "__main__":
+    main()