Skip to content

Request & Response Schemas

All schemas are defined in models/schemas.py using Pydantic v2.

Request Schemas

AskRequest

Used by: POST /ask, POST /generate-sql

class AskRequest(BaseModel):
    question: str  # The natural language question
Field Type Required Description
question string ✅ Natural language question about the loan data

Example: 

{ "question": "Which PFIs have the highest average predicted default risk?" }

SQLRequest

Used by: POST /run-sql

class SQLRequest(BaseModel):
    sql: str  # A valid SQLite SQL statement
Field Type Required Description
sql string ✅ A valid SQLite SQL query to execute

Example: 

{ "sql": "SELECT COUNT(*) FROM msmeloans WHERE predicted_default = 1;" }

Response Schemas

SQLResponse

Returned by: POST /generate-sql

class SQLResponse(BaseModel):
    sql: str
Field Type Nullable Description
sql string ❌ Generated SQL string

DataResponse

Returned by: POST /run-sql

class DataResponse(BaseModel):
    data: List[Dict[str, Any]]
Field Type Nullable Description
data array[object] ❌ List of row objects; empty list if no results

NaN handling

SQLite NULL values and pandas NaN values are serialised as JSON null.

AskResponse

Returned by: POST /ask

class AskResponse(BaseModel):
    sql: str
    data: List[Dict[str, Any]]
    plotly_code: Optional[str] = None
Field Type Nullable Description
sql string ❌ The generated SQL query
data array[object] ❌ Query result rows
plotly_code string ✅ Python code to render a Plotly chart, or null

JSON Schema

The full OpenAPI schema is auto-generated by FastAPI and available at: