""" app/models.py ============= All Pydantic models for the Interactive SQL Query Repair environment. These types are shared across env.py, grader.py, and the API server. """ from __future__ import annotations from enum import Enum from typing import Dict, List, Optional, Union from pydantic import BaseModel, Field, field_validator # --------------------------------------------------------------------------- # Enums # --------------------------------------------------------------------------- class Difficulty(str, Enum): easy = "easy" medium = "medium" hard = "hard" class ActionType(str, Enum): submit_query = "submit_query" run_partial = "run_partial" ask_clarification = "ask_clarification" class ErrorType(str, Enum): syntax = "syntax" logic = "logic" join = "join" subquery = "subquery" ambiguous = "ambiguous" # --------------------------------------------------------------------------- # Dataset schema (what lives in easy.json / medium.json / hard.json) # --------------------------------------------------------------------------- class SchemaInfo(BaseModel): """Human-readable table definitions shown to the agent.""" tables: List[str] = Field( ..., description="Each entry is a table signature, e.g. 'users(id, name, age)'", examples=[["users(id, name, email, age)", "orders(id, user_id, amount, created_at)"]], ) class Task(BaseModel): """One repair task loaded from the dataset JSON files.""" model_config = {"populate_by_name": True} id: str difficulty: Difficulty schema: SchemaInfo = Field(..., alias="schema") intent: str = Field(..., description="Plain-English goal for the query") broken_query: str = Field(..., description="The query the agent must fix") correct_query: str = Field(..., description="Reference solution (never shown to agent)") error_type: ErrorType min_turns_expected: int = Field(..., ge=1) clarification_answers: Dict[str, str] = Field( default_factory=dict, description="Keyword→answer map for ask_clarification actions", ) @field_validator("min_turns_expected") @classmethod def turns_match_difficulty(cls, v: int, info) -> int: difficulty = info.data.get("difficulty") limits = { Difficulty.easy: (1, 2), Difficulty.medium: (2, 4), Difficulty.hard: (4, 8), } if difficulty in limits: lo, hi = limits[difficulty] if not (lo <= v <= hi): raise ValueError( f"min_turns_expected={v} is out of range [{lo},{hi}] for difficulty={difficulty}" ) return v # --------------------------------------------------------------------------- # Observation (what the agent sees each turn) # --------------------------------------------------------------------------- class Observation(BaseModel): """ Returned by reset() and every step(). The agent never sees actual result rows — only error messages or execution status strings. """ task_id: str difficulty: Difficulty intent: str schema_hint: str = Field(..., description="Compact schema string, e.g. 'users(id,name,age)'") broken_query: str = Field(..., description="The original broken query (unchanged across turns)") turn: int = Field(..., ge=0) max_turns: int error_message: Optional[str] = Field( None, description="Last execution error string; null on the very first turn", ) clarification_response: Optional[str] = Field( None, description="Answer to the last ask_clarification action; null otherwise", ) last_action_type: Optional[ActionType] = Field( None, description="Which action type was taken on the previous turn", ) # --------------------------------------------------------------------------- # Actions (what the agent can do each turn) # --------------------------------------------------------------------------- class SubmitQueryAction(BaseModel): type: ActionType = Field(ActionType.submit_query, frozen=True) query: str = Field(..., description="The agent's final repaired SQL query") class RunPartialAction(BaseModel): type: ActionType = Field(ActionType.run_partial, frozen=True) query: str = Field(..., description="A query the agent wants to test without finalising") class AskClarificationAction(BaseModel): type: ActionType = Field(ActionType.ask_clarification, frozen=True) question: str = Field(..., description="A natural-language question about the schema or intent") # Union type accepted by POST /step Action = Union[SubmitQueryAction, RunPartialAction, AskClarificationAction] # --------------------------------------------------------------------------- # Step result # --------------------------------------------------------------------------- class StepResult(BaseModel): observation: Observation reward: float = Field(..., ge=-1.0, le=1.0) done: bool info: StepInfo class StepInfo(BaseModel): """Extra diagnostics attached to every step result.""" feedback: str = Field(..., description="Human-readable feedback string") rows_correct: Optional[float] = Field( None, description="Jaccard similarity of result rows vs expected rows; only set on submit_query", ) action_type: ActionType turn: int cumulative_reward: float # --------------------------------------------------------------------------- # State (GET /state) # --------------------------------------------------------------------------- class EnvState(BaseModel): task_id: str difficulty: Difficulty turn: int max_turns: int total_reward: float done: bool solved: bool # --------------------------------------------------------------------------- # Grader output (GET /grader) # --------------------------------------------------------------------------- class GraderResult(BaseModel): """ Final evaluation score for a completed episode. score = 0.60 * correctness + 0.25 * turn_efficiency + 0.15 * clarification_quality All sub-scores and the final score are in [0.0, 1.0]. """ score: float = Field(..., ge=0.0, le=1.0) correctness: float = Field(..., ge=0.0, le=1.0) turn_efficiency: float = Field(..., ge=0.0, le=1.0) clarification_quality: float = Field(..., ge=0.0, le=1.0) turns_used: int max_turns: int solved: bool detail: str = Field(..., description="Short human-readable breakdown") # --------------------------------------------------------------------------- # API-level helpers # --------------------------------------------------------------------------- class ResetRequest(BaseModel): task_id: str = "easy_001" difficulty: Difficulty = Difficulty.easy class TaskSummary(BaseModel): id: str difficulty: Difficulty intent: str error_type: ErrorType min_turns_expected: int class TaskListResponse(BaseModel): tasks: List[TaskSummary] class HealthResponse(BaseModel): status: str = "ok"