# magic-yuantian/pv-sql architecture

> Architecture diagram of the GitHub repository magic-yuantian/pv-sql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/magic-yuantian/pv-sql
- Repository: https://github.com/magic-yuantian/pv-sql

## Overview

PV-SQL turns a natural-language question into SQL through database probing, constraint extraction, query generation, and verification with repair. Its main implementation is concentrated in `pvsql/pv_sql.py`, which uses a database environment and an injectable language model. The README also documents a batch benchmark runner. The workflow and adapter links are supported by the excerpts and README; no unsampled implementation details are assumed.

Main entry points: [`pvsql/pv_sql.py`](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py) (SQL generation), [`pvsql/db.py`](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/db.py) (Database environment), [`pvsql/llm.py`](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/llm.py) (LLM adapter), [`scripts/run_batch.py`](https://github.com/magic-yuantian/pv-sql/blob/main/scripts/run_batch.py) (Batch runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["SQL workflow"]
  node_probe["Database probing<br/>[pv_sql.py]"]
  node_constraints["Constraint extraction<br/>[pv_sql.py]"]
  node_generate["SQL generation<br/>[pv_sql.py]"]
  node_verify["Verify and repair<br/>[pv_sql.py]"]
end

subgraph group_adapters["Runtime adapters"]
  node_db_env["Database environment<br/>[db.py]"]
  node_sqlite_env["SQLite adapter<br/>[db.py]"]
  node_llm_adapter["LLM adapter<br/>[llm.py]"]
end

subgraph group_batch["Batch execution"]
  node_batch_runner["Batch runner<br/>[run_batch.py]"]
end

node_user(("Questioner"))
node_database[("SQLite database")]
node_model_service["Chat model service"]
node_sql_result["Generated SQL"]

node_user -->|"asks question"| node_probe
node_probe -->|"executes probes"| node_db_env
node_probe -->|"grounds query"| node_generate
node_user -->|"states requirements"| node_constraints
node_constraints -->|"supplies constraints"| node_generate
node_generate -->|"reads schema and samples"| node_db_env
node_generate -->|"submits SQL"| node_verify
node_verify -->|"validates and executes"| node_db_env
node_verify -->|"requests repair"| node_generate
node_verify -->|"returns SQL"| node_sql_result
node_sqlite_env -->|"queries"| node_database
node_db_env -->|"implemented by"| node_sqlite_env
node_generate -.->|"requests completion"| node_llm_adapter
node_verify -.->|"requests repair"| node_llm_adapter
node_llm_adapter -->|"sends chat request"| node_model_service
node_batch_runner -->|"runs questions"| node_probe
node_batch_runner -->|"tracks token usage"| node_llm_adapter

click node_probe "https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py"
click node_constraints "https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py"
click node_generate "https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py"
click node_verify "https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py"
click node_db_env "https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/db.py"
click node_sqlite_env "https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/db.py"
click node_llm_adapter "https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/llm.py"
click node_batch_runner "https://github.com/magic-yuantian/pv-sql/blob/main/scripts/run_batch.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_probe,node_constraints,node_generate,node_verify toneBlue
class node_db_env,node_sqlite_env,node_llm_adapter,node_database toneAmber
class node_batch_runner toneMint
class node_user,node_model_service,node_sql_result toneIndigo
```

## Components

### SQL workflow

- [Database probing](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py): `pvsql/pv_sql.py`
- [Constraint extraction](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py): `pvsql/pv_sql.py`
- [SQL generation](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py): `pvsql/pv_sql.py`
- [Verify and repair](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/pv_sql.py): `pvsql/pv_sql.py`

### Runtime adapters

- [Database environment](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/db.py): `pvsql/db.py`
- [SQLite adapter](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/db.py): `pvsql/db.py`
- [LLM adapter](https://github.com/magic-yuantian/pv-sql/blob/main/pvsql/llm.py): `pvsql/llm.py`

### Batch execution

- [Batch runner](https://github.com/magic-yuantian/pv-sql/blob/main/scripts/run_batch.py): `scripts/run_batch.py`

### Other components

- **Questioner**
- **SQLite database**
- **Chat model service**
- **Generated SQL**

## Connections

- Questioner → Database probing: asks question (evidence: `README.md`)
- Database probing → Database environment: executes probes (evidence: `pvsql/pv_sql.py`)
- Database probing → SQL generation: grounds query (evidence: `README.md`)
- Questioner → Constraint extraction: states requirements (evidence: `README.md`)
- Constraint extraction → SQL generation: supplies constraints (evidence: `pvsql/pv_sql.py`)
- SQL generation → Database environment: reads schema and samples (evidence: `pvsql/pv_sql.py`)
- SQL generation → Verify and repair: submits SQL (evidence: `README.md`)
- Verify and repair → Database environment: validates and executes (evidence: `README.md`)
- Verify and repair → SQL generation: requests repair (evidence: `README.md`)
- Verify and repair → Generated SQL: returns SQL (evidence: `pvsql/pv_sql.py`)
- SQLite adapter → SQLite database: queries (evidence: `pvsql/db.py`)
- Database environment → SQLite adapter: implemented by (evidence: `README.md`)
- SQL generation → LLM adapter: requests completion (evidence: `pvsql/pv_sql.py`)
- Verify and repair → LLM adapter: requests repair (evidence: `pvsql/pv_sql.py`)
- LLM adapter → Chat model service: sends chat request (evidence: `pvsql/llm.py`)
- Batch runner → Database probing: runs questions (evidence: `scripts/run_batch.py`)
- Batch runner → LLM adapter: tracks token usage (evidence: `scripts/run_batch.py`)