SQL Database Engineer Agent — OpenEnv Environment

🔗 Quick Links

From Round 1 → Round 2

Motivation

📊 Training Results

GRPO Training Curves — 200 Steps

Evaluation — Trained vs Random Agent (15 Scenarios)

Training Progression

Environment Overview

Action Space (15 Actions)

Round 2 — DB Engineering Actions

Round 1 — SQL Debugging Actions (backward compatible)

Observation Space

{
 "task_id": "medium_s001",
 "task_description": "E-commerce DB: 50K orders. P95 query time > 8s. Target: < 500ms.",
 "current_context": {
 "performance_score": 12.5,
 "target_score": 75.0,
 "tables": [
 {"name": "orders", "rows": 50000, "indexes": ["PRIMARY"], "size_mb": 280},
 {"name": "users", "rows": 8000, "indexes": ["PRIMARY", "email_idx"]}
 ],
 "slow_queries": [
 {"id": "q1", "sql": "SELECT * FROM orders WHERE user_id=? AND status=?", "avg_ms": 8500},
 {"id": "q2", "sql": "SELECT COUNT(*) FROM orders o JOIN users u ON o.user_id=u.id", "avg_ms": 3200}
 ],
 "improvement_history": [12.5],
 "milestones_earned": [],
 "steps_remaining": 50
 },
 "step_count": 0,
 "difficulty": "medium",
 "max_steps": 50
}

Reward Design

inspect_query / analyze_indexes → +0.05 (investigation rewarded)
create_index with improvement → +0.10 + delta_reward
Milestone: 25% improvement → +0.15 ONE-TIME bonus
Milestone: 50% improvement → +0.25 ONE-TIME bonus
Milestone: 75% improvement → +0.40 ONE-TIME bonus
submit_report (terminal) → 0.0–1.0 full score
Efficiency bonus (< 70% budget) → +0.10
Loop penalty (same action x2+) → −0.08
Hint penalty → −0.10
Backtrack penalty → −0.05
Budget exhaustion → −0.15

GRPO Reward Breakdown (Expected per action)

inspect_query / analyze_indexes → ~0.10
create_index (no table/col match) → ~0.10
create_index (partial hint match) → ~0.20–0.45
create_index (perfect hint match) → ~0.55–0.80
create_index (simulator confirms) → ~0.75–0.99
Milestones: 25%=+0.15 50%=+0.25 75%=+0.40 (cumulative)

Terminal Score Formula

perf_improvement = (final_score - baseline) / (100 - baseline)
step_efficiency = 1.0 - (steps_used / max_steps)
terminal_score = (perf_improvement * 0.60) + (step_efficiency * 0.20) + 0.10

Scenarios — 30 Tasks

Round 2: DB Engineering (15 new tasks)

Easy (15 steps, target 80+)

Medium (25–30 steps, target 72–78)

Hard (50 steps, target 65–70)

Round 1: SQL Debugging (15 original tasks — backward compatible)

Self-Improving Curriculum

Agent avg score > 0.75 → Advance to harder tier
Agent avg score < 0.30 → Drop back a tier
Ultra tier (tier 3) → Auto-generated 5-8 table scenarios, no hints

API Endpoints

Live Demo

# Reset with e-commerce scenario
curl -X POST https://junaid0600-sql-db-engineer-agent.hf.space/reset \
 -H "Content-Type: application/json" \
 -d '{"difficulty": "easy", "task_id": "easy_s001"}'
# Agent inspects slow query → sees FULL TABLE SCAN
curl -X POST https://junaid0600-sql-db-engineer-agent.hf.space/step \
 -H "Content-Type: application/json" \
 -d '{"action_type": "inspect_query", "payload": {"query_id": "q1"}}'
# Agent creates index → performance score 8.0 → 82.0
curl -X POST https://junaid0600-sql-db-engineer-agent.hf.space/step \
 -H "Content-Type: application/json" \
 -d '{"action_type": "create_index", "payload": {"table": "users", "columns": ["email"]}}'
# Agent submits report → terminal score 0.82
curl -X POST https://junaid0600-sql-db-engineer-agent.hf.space/step \
 -H "Content-Type: application/json" \
 -d '{"action_type": "submit_report", "payload": {"summary": "Added email index. Performance 8 to 82."}}'

Project Structure

sql-query-debugger/
├── .env # Environment variables
├── .env.example # Environment variables template
├── .gitignore
├── Dockerfile # Container definition
├── README.md # This file
├── blog_post.md # HF blog post (separate from README)
├── loss_curve.png # GRPO training curves ✅ evidence
├── reward_curve.png # Evaluation results ✅ evidence
├── openenv.yaml # OpenEnv metadata (v2.0.0)
├── pyproject.toml
├── requirements.txt # Pinned dependencies
├── uv.lock
├── baseline.py # Rule-based baseline agent
├── demo_app.py # Gradio demo app
├── inference.py # LLM inference agent
│
├── api/
│ ├── __init__.py
│ └── server.py # FastAPI — 11 endpoints
│
├── dataset/
│ ├── easy_cases.json # Round 1: easy SQL tasks
│ ├── easy_scenarios.json # Round 2: easy DB scenarios
│ ├── hard_cases.json # Round 1: hard SQL tasks
│ ├── hard_scenarios.json # Round 2: hard DB scenarios
│ ├── medium_cases.json # Round 1: medium SQL tasks
│ └── medium_scenarios.json # Round 2: medium DB scenarios
│
├── env/
│ ├── __init__.py
│ ├── scenarios/ # Scenario definitions
│ ├── curriculum.py # Self-improving curriculum
│ ├── db_simulator.py # DB performance simulator
│ ├── environment.py # Core: reset() step() state()
│ ├── graders.py # Deterministic graders
│ ├── models.py # Pydantic models (15 action types)
│ ├── reward.py # Dense reward + milestones
│ ├── scenario_generator.py # Dynamic scenario generation
│ └── tasks.py # Task manager (30 tasks)
│
├── sdea-trained/
│ └── eval_results.json # Evaluation results JSON
│
├── training/
│ ├── colab_notebook.py # Colab training notebook
│ ├── evaluate_agent.py # Evaluation + reward curve generator
│ ├── generate_plots.py # Fixed plot generator
│ ├── generate_training_data.py # Expert trajectory collector
│ └── train_agent.py # Unsloth + GRPO training script
│
└── tests/
 ├── __init__.py
 ├── test_environment.py # Environment tests
 ├── test_graders.py # Grader tests
 ├── test_reward.py # Reward tests
 └── test_tasks.py # Task tests

Setup & Installation

# Clone
git clone https://github.com/Mdjunaid06/sql-db-engineer-agent
cd sql-db-engineer-agent
# Install
pip install -r requirements.txt
# Configure
cp .env.example .env
# Add HF_TOKEN to .env
# Run
uvicorn api.server:app --host 0.0.0.0 --port 7860 --reload
# Verify
curl http://localhost:7860/health
# {"status":"ok","version":"2.0.0"}
# Open demo
# http://localhost:7860/demo

Validation

pytest tests/ -v # 24/24 passed
openenv validate . # [OK] Ready for multi-mode deployment

Built For