CoolFace
Apppublic

SyncShift/sql-correction-env

sourceHugging Faceupdated 5mo agoView on Hugging Face
0likes
App README

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 including column name mismatches.

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. A stagnation penalty further discourages agents from repeating the same wrong answer across steps.

Observation Space

FieldTypeDescription
task_idstringUnique identifier for the current task instance
broken_querystringThe malformed SQL query the agent must fix
schema_contextstring or nullTable and column definitions (hard tasks only)
error_hintstring or nullPlain-language hint about the error (easy tasks only)
step_numberintegerCurrent step within the episode (0 = initial)
steps_remainingintegerSteps left before the episode ends
previous_attemptstring or nullThe agent's SQL output from the previous step
feedbackstring or nullGrader feedback on the previous attempt

Action Space

FieldTypeDescription
corrected_querystringThe agent's corrected SQL query

Tasks

NameDifficultyCountMax StepsDescription
easyEasy155Fix a single keyword typo (e.g. FORM → FROM). Hint provided.
mediumMedium155Fix multiple errors including missing keywords and wrong clauses. No hint.
hardHard104Fix complex multi-join queries with subtle errors and wrong column names. Schema provided, no hint.

Reward Function

ScoreCondition
0.99Exact match after normalization (perfect fix)
0.7All correct tokens present, structure slightly off
0.4Most keywords correct and token overlap is high (≥85% keywords, ≥75% tokens)
0.3Partial keyword and structure match (≥65% keywords, ≥50% tokens)
0.2Basic SELECT ... FROM ... structure present
0.01Response is not valid SQL

A stagnation penalty of −0.1 is applied when the agent submits the same reward-equivalent answer for two or more consecutive steps, encouraging active correction rather than looping.

Episodes terminate when reward reaches 0.99 (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 '{"difficulty": "easy"}'

curl -X POST http://localhost:7860/step \
  -H "Content-Type: application/json" \
  -d '{"action": {"corrected_query": "SELECT * FROM users WHERE id = 1"}}'

curl http://localhost:7860/tasks

Run Tests

bash
pip install pytest
pytest tests/ -v

Docker

bash
docker build -t sql-correction-env .
docker run -p 7860:7860 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 all tasks
python inference.py

Baseline Scores

TaskModelAvg ScoreNotes
easyQwen/Qwen2.5-72B~0.85Single typo fix, hint provided
mediumQwen/Qwen2.5-72B~0.62Multi-error correction
hardQwen/Qwen2.5-72B~0.38Complex multi-join, schema-guided

Run `inference.py` against the live Space to reproduce these scores.

API Endpoints

MethodPathDescription
POST/resetStart new episode, returns observation
POST/stepSubmit action, returns result
POST/stateGet current episode state
GET/healthHealth check
GET/tasksList available task difficulties