How smaoui-me/self-correcting-text-to-sql works
Self-Correcting Text-to-SQL is a CLI application that turns a music-store question into a read-only SQLite query, repairs execution errors, and formats the result. Its principal workflow is assembled by LangGraph, with shared request state and a configurable model provider. Separate evaluation capabilities score query results against reference SQL, cover behavioral-review cases, and render saved benchmark records. The runtime wiring is supported by sampled source; benchmark and reporting internals are represented only where README capabilities and the file tree support them.
Main entry points: graph.py LangGraph workflow · main.py CLI entry · database.py SQLite boundary · edges.py Retry routing
Components 21
Query runtime
- CLI entry
main.py - SQLite boundary
src/database.py - LangGraph workflow
src/agent/graph.py - Request state
src/agent/state.py - SQL generation
src/agent/nodes.py - SQL execution
src/agent/nodes.py - Retry routing
src/agent/edges.py - SQL correction
src/agent/nodes.py - Answer formatting
src/agent/nodes.py - Failure response
src/agent/nodes.py
Model integration
- Settings and model factory
src/config.py - Paced model
src/providers.py
Evaluation and reporting
- Benchmark runner
scripts/benchmark_robustness.py - Result scoring
src/evaluation.py - Question bank
benchmarks/question_bank.json - Saved run records
- Results report
scripts/report_results.py
Call telemetry
- Observed model calls
src/telemetry.py
Other components
- CLI user
- Chinook SQLite
- Configured model endpoint
Connections 31
- CLI user → CLI entry: asks
- CLI entry → Settings and model factory: loads configuration
- CLI entry → SQLite boundary: opens database
- CLI entry → LangGraph workflow: builds and streams
- CLI entry → Request state: initializes request
- CLI entry → SQLite boundary: reads schema
- Settings and model factory → Paced model: creates wrapper
- Paced model → Configured model endpoint: sends model requests
- LangGraph workflow → SQL generation: dispatches
- LangGraph workflow → SQL execution: dispatches
- LangGraph workflow → SQL correction: dispatches
- LangGraph workflow → Answer formatting: dispatches
- LangGraph workflow → Failure response: dispatches
- LangGraph workflow → Retry routing: routes by state
- SQL generation → Observed model calls: records model call
- SQL correction → Observed model calls: records model call
- Answer formatting → Observed model calls: records model call
- Observed model calls → Paced model: invokes
- SQL execution → SQLite boundary: executes SQL
- SQLite boundary → Chinook SQLite: reads schema and rows
- Retry routing → SQL correction: retries failures
- Retry routing → Answer formatting: routes success
- Retry routing → Failure response: routes terminal error
- SQL correction → SQL execution: re-executes SQL
- Benchmark runner → Question bank: loads cases
- Benchmark runner → Result scoring: scores runs
- Result scoring → SQLite boundary: executes reference SQL
- Result scoring → LangGraph workflow: invokes query workflow
- Benchmark runner → Saved run records: saves run records
- Results report → Saved run records: reads records
- Results report → Result scoring: summarizes metrics