README.md

---
title: SQL Repair Env
emoji: 📊
colorFrom: red
colorTo: purple
sdk: docker
app_port: 8000
pinned: false
license: apache-2.0
short_description: OpenEnv SQL repair tasks with a live frontend
---

# SQL Repair OpenEnv

An OpenEnv environment for the **Meta PyTorch x Scaler hackathon** where
agents repair broken SQL queries against a small SQLite schema.

## Live Links

- GitHub: [Krishpotanwar/sql-repair-env](https://github.com/Krishpotanwar/sql-repair-env)
- Hugging Face Space: [krishpotanwar/sql-repair-env](https://huggingface.co/spaces/krishpotanwar/sql-repair-env)
- Live app: [krishpotanwar-sql-repair-env.hf.space](https://krishpotanwar-sql-repair-env.hf.space/)

## What This Repo Includes

- A FastAPI OpenEnv backend with `/health`, `/tasks`, `/reset`, `/step`, `/grader`, and `/baseline`
- `/api/*` aliases so the frontend can call the same environment through the Hugging Face Space root
- A frontend command center inspired by the `disasterman` UI shell, adapted for SQL query repair workflows
- Three deterministic SQL repair tasks with strict scoring in `(0, 1)`
- A validator-safe inference runner that always emits bounded scores even on missing-key or crash paths

## Tasks

| ID       | Difficulty | What's broken                            |
|----------|------------|------------------------------------------|
| `task_1` | easy       | SELECT list missing commas               |
| `task_2` | medium     | JOIN references columns that don't exist |
| `task_3` | hard       | Aggregate query missing GROUP BY         |

Each task gives the agent the schema, the broken query, the runtime error
(if any), and a one-line hint. The agent submits a corrected query via the
`/step` endpoint and is scored on whether the result rows match the
canonical expected rows.

## Architecture

```text
.
├── pyproject.toml         # uv project, server entry point
├── uv.lock                # uv lockfile
├── Dockerfile             # builds the FastAPI server image
├── README.md              # GitHub + HF Space landing document
├── inference.py           # AGENT — talks to the env via HTTP, calls an LLM
├── openenv.yaml           # OpenEnv metadata
├── server/
│   └── app.py             # FastAPI env server + frontend serving
├── frontend/
│   ├── src/               # Winner UI shell + SQL-specific tabs
│   └── dist/              # prebuilt frontend bundle shipped to HF
├── sql_env/
│   ├── env_core.py        # SQLite-backed env state
│   ├── tasks.py           # Task definitions
│   └── grader.py          # Strict (0, 1) score clamping
└── tests/
    └── test_smoke.py      # Pytest smoke suite
```

## Frontend

The root route `/` serves a deployed frontend command center with:

- `QUERY LAB` for reset, submit, and grader workflows
- `TASK ATLAS` for browsing the three SQL missions
- `BASELINE ARENA` for broken-query score comparisons
- `AGENT PROTOCOL` for validator and runtime notes
- `API OPS` for backend connection and endpoint visibility

In production, the frontend talks to the backend through `/api/*` aliases.
That keeps the Space root usable as both a human-facing app and an API host.

## HTTP API

| Method | Path        | Body                                      | Returns                              |
|--------|-------------|-------------------------------------------|--------------------------------------|
| GET    | `/health`   | —                                         | `{"status":"ok"}`                    |
| GET    | `/tasks`    | —                                         | task list + metadata                 |
| POST   | `/reset`    | `{"task_id":"task_1"}` (optional)         | observation                          |
| POST   | `/step`     | `{"action":{"action_type":"submit_query","query":"..."}}` | observation/reward/done |
| POST   | `/grader`   | `{"task_id":"task_1"}`                    | `{"score": float in (0,1)}`          |
| POST   | `/baseline` | `{"tasks":[...]}` (optional)              | scores for all tasks                 |

`/reset` accepts an empty body and defaults to `task_1` — required by the
OpenEnv validator.

The frontend calls the equivalent `/api/health`, `/api/tasks`, `/api/reset`,
`/api/step`, `/api/grader`, and `/api/baseline` aliases.

## Running locally

```bash
# 1. Install backend dependencies
uv sync

# 2. Build the frontend bundle used by the HF Space
cd frontend
npm ci
npm run build
cd ..

# 3. Start the env server
python -m server.app          # serves API + frontend at http://localhost:8000

# 4. Optional: frontend-only dev mode
cd frontend
npm run dev

# 5. Run the agent (in another terminal)
export HF_TOKEN=<your-groq-or-openai-key>
export API_BASE_URL=https://api.groq.com/openai/v1
export MODEL_NAME=llama-3.3-70b-versatile
ENV_URL=http://localhost:8000 uv run python inference.py
```

## Example API Flow

```bash
URL=https://krishpotanwar-sql-repair-env.hf.space

curl -s "$URL/health"
curl -s -X POST "$URL/reset" -H "Content-Type: application/json" -d '{}'
curl -s -X POST "$URL/step" \
  -H "Content-Type: application/json" \
  -d '{"action":{"action_type":"submit_query","query":"SELECT id, name, price FROM products ORDER BY id"}}'
curl -s -X POST "$URL/grader" -H "Content-Type: application/json" -d '{"task_id":"task_1"}'
curl -s -X POST "$URL/baseline" -H "Content-Type: application/json" -d '{}'
```

## Inference Output Notes

`inference.py` is designed to keep stdout validator-safe:

- Every task emits exactly one `[START]` line
- Every task emits exactly one `[END]` line with `score=` strictly in `(0, 1)`
- On missing-key or fatal fallback paths, the score falls back to `0.5000`
- Successful runs may also emit `[STEP]` progress lines

Example no-key path:

```text
[START] task_1
[END] task_1 | score=0.5000 | status=fatal_no_llm
[START] task_2
[END] task_2 | score=0.5000 | status=fatal_no_llm
[START] task_3
[END] task_3 | score=0.5000 | status=fatal_no_llm
```

## Environment variables

| Name               | Default                                  | Notes                                       |
|--------------------|------------------------------------------|---------------------------------------------|
| `API_BASE_URL`     | `https://api.groq.com/openai/v1`         | Required by OpenEnv submission checklist    |
| `MODEL_NAME`       | `llama-3.3-70b-versatile`                | Required by OpenEnv submission checklist    |
| `HF_TOKEN`         | (none — must be set in HF Space Secrets) | Required by OpenEnv submission checklist    |
| `LOCAL_IMAGE_NAME` | (unset)                                  | If set, inference.py boots a Docker image   |
| `ENV_URL`          | `http://localhost:8000`                  | Where the env server is reachable           |

## Validation

```bash
# Phase 1 — official OpenEnv validator
uvx --from openenv-core openenv validate .

# Backend smoke tests
uv run pytest tests/ -q

# Frontend lint
cd frontend && npm run lint
```

No API keys are hardcoded in this repo. The agent reads `HF_TOKEN` (with
optional `GROQ_API_KEY` and `OPENAI_API_KEY` fallbacks) at runtime only.