jonkmatsumo/text2sql

How jonkmatsumo/text2sql works

Text2SQL turns a natural-language question into guarded SQL, executes it against a configured query-target database, and returns results through the agent service. Its documented agent workflow clarifies or retrieves context, plans and generates SQL, validates it, executes it, and synthesizes a response; the MCP server supplies retrieval and execution tools. Separate operator interfaces, ingestion, semantic caching, and trace observability support the product. The index and excerpts establish some wiring, while several documented capabilities have unsampled implementations; those relationships are shown only when documented or marked unverified.

Main entry points: app.py Agent API · database.py DAL Factory · graph.py Agent Graph · tools MCP Tools

Components 24

User Experience

Operator UI ui/src/App.tsx
UI API src/ui_api_gateway/app.py

Agent Workflow

Agent API src/agent_service/app.py
Agent Graph src/agent/graph.py
Query Stages src/agent/nodes
LLM Client src/agent/llm_client.py
Replay Bundles src/agent/replay_bundle.py

MCP and Retrieval

MCP Server src/mcp_server/main.py
MCP Tools src/mcp_server/tools
Schema RAG src/mcp_server/services/rag/engine.py
ANN Index src/ingestion/vector_indexes
Query Canonicalizer src/mcp_server/services/canonicalization/spacy_pipeline.py
Semantic Cache src/mcp_server/services/cache/service.py
Schema Ingestion src/ingestion/sync_engine.py

Data Access

SQL Guardrails src/common/policy/sql_policy.py
DAL Factory src/dal/database.py
Database Adapters src/dal
Control Plane src/dal/postgres
Query Target

Operations

OTEL Worker src/otel_worker/app.py
Trace Storage src/otel_worker/storage
Agent Telemetry src/agent/telemetry.py

Other components

Questioner
Operator

Connections 21

Questioner → Agent API: submits question README.md
Agent API → Agent Graph: runs graph src/agent_service/app.py
Agent Graph → Query Stages: dispatches stages README.md
Agent Graph → LLM Client: uses model
Agent API → Replay Bundles: records replays src/agent_service/app.py
Query Stages → MCP Server: calls tools README.md
MCP Server → MCP Tools: registers tools src/mcp_server/main.py
MCP Tools → DAL Factory: executes queries README.md
MCP Tools → SQL Guardrails: enforces policy README.md
Schema RAG → ANN Index: searches index src/mcp_server/services/rag/engine.py
Schema RAG → Schema Ingestion: loads schema src/mcp_server/services/rag/engine.py
Schema Ingestion → ANN Index: builds index
Query Canonicalizer → Semantic Cache: canonicalizes cache keys
DAL Factory → Database Adapters: initializes provider src/dal/database.py
Database Adapters → Query Target: queries data README.md
DAL Factory → Control Plane: stores metadata README.md
Operator → Operator UI: operates system README.md
Operator UI → UI API: requests APIs
UI API → DAL Factory: configures data access src/ui_api_gateway/app.py
Agent API → Agent Telemetry: emits telemetry src/agent_service/app.py
OTEL Worker → Trace Storage: persists traces src/otel_worker/app.py

Drawn by GitDiagram on November 12, 2026 from the repository's file tree, README and source files. Read as Markdown ·