""" server/app.py ============= FastAPI server for the Interactive SQL Query Repair environment. Endpoints --------- GET /health — liveness probe POST /reset — start a new episode POST /step — take one action GET /state — current episode state GET /tasks — list all available tasks GET /grader — score the current (or last) episode """ from __future__ import annotations import sys import os from fastapi import Body from typing import Optional # Allow imports from project root regardless of working directory sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from typing import Annotated, Union from fastapi import FastAPI, HTTPException from fastapi.responses import JSONResponse from pydantic import BaseModel, Field from app.data_loader import get_all_tasks, get_tasks_by_difficulty, task_count from app.env import SQLRepairEnv from app.models import ( AskClarificationAction, Difficulty, EnvState, GraderResult, HealthResponse, Observation, ResetRequest, RunPartialAction, StepResult, SubmitQueryAction, TaskListResponse, TaskSummary, ) # --------------------------------------------------------------------------- # App setup # --------------------------------------------------------------------------- app = FastAPI( title="Interactive SQL Query Repair Environment", description=( "An OpenEnv-compatible RL environment where an agent fixes broken SQL " "queries through multi-turn interaction: running partial queries, asking " "schema clarifications, and submitting final repairs." ), version="1.0.0", ) # One global environment instance per server process. # For concurrent multi-agent evaluation, run multiple server processes. _env = SQLRepairEnv() # --------------------------------------------------------------------------- # Action discriminator model # --------------------------------------------------------------------------- class StepRequest(BaseModel): """ Wrapper that discriminates between the three action types. The 'type' field routes to the correct action model. """ type: str query: str | None = None question: str | None = None def to_action(self) -> Union[SubmitQueryAction, RunPartialAction, AskClarificationAction]: if self.type == "submit_query": if not self.query: raise ValueError("submit_query action requires 'query' field") return SubmitQueryAction(query=self.query) elif self.type == "run_partial": if not self.query: raise ValueError("run_partial action requires 'query' field") return RunPartialAction(query=self.query) elif self.type == "ask_clarification": if not self.question: raise ValueError("ask_clarification action requires 'question' field") return AskClarificationAction(question=self.question) else: raise ValueError( f"Unknown action type '{self.type}'. " f"Must be one of: submit_query, run_partial, ask_clarification" ) # --------------------------------------------------------------------------- # Endpoints # --------------------------------------------------------------------------- @app.get("/health", response_model=HealthResponse, tags=["meta"]) def health() -> HealthResponse: """Liveness probe — always returns 200 if the server is running.""" return HealthResponse(status="ok") @app.get("/tasks", response_model=TaskListResponse, tags=["meta"]) def list_tasks() -> TaskListResponse: """ List all available tasks across all difficulty levels. Use the task 'id' field in POST /reset to start a specific episode. """ summaries = [ TaskSummary( id=t.id, difficulty=t.difficulty, intent=t.intent, error_type=t.error_type, min_turns_expected=t.min_turns_expected, ) for t in get_all_tasks() ] return TaskListResponse(tasks=summaries) @app.post("/reset", response_model=Observation, tags=["env"]) def reset(req: Optional[ResetRequest] = Body(default=None)) -> Observation: try: task_id = req.task_id if req and req.task_id else "easy_001" difficulty = req.difficulty if req and req.difficulty else "easy" obs = _env.reset(task_id=task_id, difficulty=difficulty) return obs except KeyError as e: raise HTTPException(status_code=404, detail=str(e)) except ValueError as e: raise HTTPException(status_code=422, detail=str(e)) except RuntimeError as e: raise HTTPException(status_code=500, detail=str(e)) @app.post("/step", response_model=StepResult, tags=["env"]) def step(req: StepRequest) -> StepResult: """ Take one action in the current episode. Body (one of three shapes) -------------------------- Submit query (ends episode): { "type": "submit_query", "query": "SELECT ..." } Run partial query (test without finalising): { "type": "run_partial", "query": "SELECT ..." } Ask clarification: { "type": "ask_clarification", "question": "what is the join key?" } Returns StepResult with observation, reward, done flag, and diagnostics. Call GET /grader after done=true to get the final score. """ try: action = req.to_action() except ValueError as e: raise HTTPException(status_code=422, detail=str(e)) try: result = _env.step(action) return result except RuntimeError as e: raise HTTPException(status_code=400, detail=str(e)) @app.get("/state", response_model=EnvState, tags=["env"]) def state() -> EnvState: """Return the current episode state (safe to call at any time).""" return _env.state() @app.get("/grader", response_model=GraderResult, tags=["eval"]) def grader() -> GraderResult: """ Compute and return the grader score for the current (or most recent) episode. Score formula ------------- final = 0.60 × correctness + 0.25 × turn_efficiency + 0.15 × clarification_quality All sub-scores are in [0.0, 1.0]. Can be called mid-episode to see a partial score. """ return _env.grade() # --------------------------------------------------------------------------- # Error handlers # --------------------------------------------------------------------------- @app.exception_handler(Exception) async def generic_exception_handler(request, exc): return JSONResponse( status_code=500, content={"detail": f"Internal server error: {str(exc)}"}, ) import uvicorn def main(): uvicorn.run("server.app:app", host="0.0.0.0", port=7860) # --------------------------------------------------------------------------- # Entry point (for direct python execution) # --------------------------------------------------------------------------- if __name__ == "__main__": import uvicorn uvicorn.run("server.app:app", host="0.0.0.0", port=7860, reload=False)