How riishi-01/text2sql-agent works
Olist NL2SQL accepts natural-language questions through a CLI or agent workflow, builds a dataset-aware prompt, generates SQL with an LLM, validates it, and either refuses or runs it read-only against PostgreSQL. A separate FastAPI endpoint accepts SQL directly and executes restricted SELECT queries. The evaluation harness is a major product capability: it runs curated cases, grades SQL across rubric dimensions, resumes runs with checkpoints, and reports results. Evaluation wiring is summarized from the README; its runner implementation was not sampled.
Main entry points: graph.py Agent Workflow · eval_runner.py Eval Runner · query.py Query Route · main.py CLI
Components 21
NL2SQL Agent
- CLI
agent/main.py - Agent Workflow
agent/graph.py - Prompt Builder
agent/prompts/builder.py - Schema Metadata
agent/schema/loader.py - SQL Validator
agent/validator/sql_validator.py
Query API
- FastAPI App
api/app.py - Query Route
api/routes/query.py - Query Models
api/models.py - Health Route
api/routes/health.py
Database Access
- Read-only DB Access
agent/db/connection.py
Evaluation Harness
- Curated Cases
evals/cases.yaml - Eval Runner
evals/scripts/eval_runner.py - Rubric Grader
evals/scripts/rubric.py - Run Checkpoints
evals/scripts/checkpoint_manager.py - Report Generator
evals/scripts/report_generator.py - Reference Results
evals/results/baseline
Other components
- Questioner
- OpenAI LLM
- PostgreSQL
- SQL and Results
- API Client
Connections 23
- Questioner → CLI: asks question
- CLI → Agent Workflow: runs agent
- Agent Workflow → Prompt Builder: builds prompt
- Prompt Builder → Schema Metadata: gets dataset date
- Schema Metadata → PostgreSQL: reads metadata and date
- Agent Workflow → OpenAI LLM: requests SQL
- OpenAI LLM → Agent Workflow: returns SQL
- Agent Workflow → SQL Validator: validates SQL
- Agent Workflow → Read-only DB Access: executes valid SQL
- Read-only DB Access → PostgreSQL: queries safely
- Agent Workflow → SQL and Results: returns outcome
- CLI → SQL and Results: displays outcome
- API Client → FastAPI App: sends request
- FastAPI App → Query Route: dispatches route
- Query Route → Query Models: uses request and response
- Query Route → PostgreSQL: executes restricted SELECT
- Query Route → API Client: returns rows or error
- Curated Cases → Eval Runner: provides cases
- Eval Runner → Agent Workflow: runs agent
- Eval Runner → Rubric Grader: grades results
- Eval Runner → Run Checkpoints: saves progress
- Eval Runner → Report Generator: provides run results
- Report Generator → Reference Results: writes reports