# smaoui-me/self-correcting-text-to-sql architecture

> Architecture diagram of the GitHub repository smaoui-me/self-correcting-text-to-sql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smaoui-me/self-correcting-text-to-sql
- Repository: https://github.com/smaoui-me/self-correcting-text-to-sql

## Overview

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: [`src/agent/graph.py`](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/graph.py) (LangGraph workflow), [`main.py`](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/main.py) (CLI entry), [`src/database.py`](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/database.py) (SQLite boundary), [`src/agent/edges.py`](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/edges.py) (Retry routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Query runtime"]
  node_cli["CLI entry<br/>[main.py]"]
  node_db_boundary["SQLite boundary<br/>[database.py]"]
  node_workflow["LangGraph workflow<br/>[graph.py]"]
  node_state["Request state<br/>[state.py]"]
  node_generation["SQL generation<br/>[nodes.py]"]
  node_execution["SQL execution<br/>[nodes.py]"]
  node_routing["Retry routing<br/>[edges.py]"]
  node_correction["SQL correction<br/>[nodes.py]"]
  node_formatting["Answer formatting<br/>[nodes.py]"]
  node_failure["Failure response<br/>[nodes.py]"]
end

subgraph group_model["Model integration"]
  node_settings["Settings and model factory<br/>[config.py]"]
  node_paced_model["Paced model<br/>[providers.py]"]
end

subgraph group_evaluation["Evaluation and reporting"]
  node_benchmark["Benchmark runner"]
  node_case_evaluation["Result scoring<br/>[evaluation.py]"]
  node_question_bank["Question bank<br/>[question_bank.json]"]
  node_saved_results["Saved run records"]
  node_reporting["Results report<br/>[report_results.py]"]
end

subgraph group_observability["Call telemetry"]
  node_observed_call["Observed model calls<br/>[telemetry.py]"]
end

node_user(("CLI user"))
node_sqlite[("Chinook SQLite")]
node_model_service["Configured model endpoint"]

node_user -->|"asks"| node_cli
node_cli -->|"loads configuration"| node_settings
node_cli -->|"opens database"| node_db_boundary
node_cli -->|"builds and streams"| node_workflow
node_cli -->|"initializes request"| node_state
node_cli -->|"reads schema"| node_db_boundary
node_settings -->|"creates wrapper"| node_paced_model
node_paced_model -.->|"sends model requests"| node_model_service
node_workflow -->|"dispatches"| node_generation
node_workflow -->|"dispatches"| node_execution
node_workflow -->|"dispatches"| node_correction
node_workflow -->|"dispatches"| node_formatting
node_workflow -->|"dispatches"| node_failure
node_workflow -->|"routes by state"| node_routing
node_generation -->|"records model call"| node_observed_call
node_correction -->|"records model call"| node_observed_call
node_formatting -->|"records model call"| node_observed_call
node_observed_call -->|"invokes"| node_paced_model
node_execution -->|"executes SQL"| node_db_boundary
node_db_boundary -->|"reads schema and rows"| node_sqlite
node_routing -->|"retries failures"| node_correction
node_routing -->|"routes success"| node_formatting
node_routing -->|"routes terminal error"| node_failure
node_correction -->|"re-executes SQL"| node_execution
node_benchmark -->|"loads cases"| node_question_bank
node_benchmark -->|"scores runs"| node_case_evaluation
node_case_evaluation -->|"executes reference SQL"| node_db_boundary
node_case_evaluation -->|"invokes query workflow"| node_workflow
node_benchmark -->|"saves run records"| node_saved_results
node_reporting -->|"reads records"| node_saved_results
node_reporting -->|"summarizes metrics"| node_case_evaluation

click node_cli "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/main.py"
click node_settings "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/config.py"
click node_db_boundary "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/database.py"
click node_workflow "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/graph.py"
click node_state "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/state.py"
click node_generation "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py"
click node_execution "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py"
click node_routing "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/edges.py"
click node_correction "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py"
click node_formatting "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py"
click node_failure "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py"
click node_observed_call "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/telemetry.py"
click node_paced_model "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/providers.py"
click node_benchmark "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/scripts/benchmark_robustness.py"
click node_case_evaluation "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/evaluation.py"
click node_question_bank "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/benchmarks/question_bank.json"
click node_reporting "https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/scripts/report_results.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_db_boundary,node_workflow,node_state,node_generation,node_execution,node_routing,node_correction,node_formatting,node_failure,node_user toneBlue
class node_settings,node_paced_model,node_sqlite toneAmber
class node_benchmark,node_case_evaluation,node_question_bank,node_saved_results,node_reporting toneMint
class node_observed_call toneRose
class node_model_service toneIndigo
```

## Components

### Query runtime

- [CLI entry](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/main.py): `main.py`
- [SQLite boundary](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/database.py): `src/database.py`
- [LangGraph workflow](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/graph.py): `src/agent/graph.py`
- [Request state](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/state.py): `src/agent/state.py`
- [SQL generation](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py): `src/agent/nodes.py`
- [SQL execution](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py): `src/agent/nodes.py`
- [Retry routing](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/edges.py): `src/agent/edges.py`
- [SQL correction](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py): `src/agent/nodes.py`
- [Answer formatting](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py): `src/agent/nodes.py`
- [Failure response](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/agent/nodes.py): `src/agent/nodes.py`

### Model integration

- [Settings and model factory](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/config.py): `src/config.py`
- [Paced model](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/providers.py): `src/providers.py`

### Evaluation and reporting

- [Benchmark runner](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/scripts/benchmark_robustness.py): `scripts/benchmark_robustness.py`
- [Result scoring](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/evaluation.py): `src/evaluation.py`
- [Question bank](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/benchmarks/question_bank.json): `benchmarks/question_bank.json`
- **Saved run records**
- [Results report](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/scripts/report_results.py): `scripts/report_results.py`

### Call telemetry

- [Observed model calls](https://github.com/smaoui-me/self-correcting-text-to-sql/blob/main/src/telemetry.py): `src/telemetry.py`

### Other components

- **CLI user**
- **Chinook SQLite**
- **Configured model endpoint**

## Connections

- 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