How eeeee-star/text2sql works
Text2SQL turns a user’s natural-language question into retrieved schema context, planned and generated SQL, validated execution, and a synthesized response. Its principal runtime spans the agent service, MCP tool server, and query-target DAL. Separate capabilities support schema/example retrieval, semantic caching, graph-aware context, tenant security, ingestion, replay, and operations. The README documents the main workflow and capabilities; source-index references support selected internal links, while unsampled implementation details are left unconnected.
Main entry points: app.py Agent API · main.py MCP server · database.py Database access · graph.py Agent graph
Components 21
Agent workflow
- Agent API
src/agent_service/app.py - Agent graph
src/agent/graph.py - LLM client
src/agent/llm_client.py - MCP client
src/agent/mcp_client/manager.py - Replay bundles
src/agent/replay_bundle.py
MCP tools and retrieval
- MCP server
src/mcp_server/main.py - SQL execution
src/mcp_server/tools/execute_sql_query.py - Schema retrieval
src/mcp_server/services/rag/engine.py - Semantic cache
src/mcp_server/services/canonicalization/spacy_pipeline.py
Data access and ingestion
- Vector indexes
src/ingestion/vector_indexes/factory.py - Schema ingestion
src/ingestion/sync_engine.py - Database access
src/dal/database.py - Query targets
src/dal/factory.py - SQL guardrails
src/dal/util/read_only.py - Control-plane stores
src/dal/postgres/semantic_cache.py
Operations and observability
- OTEL worker
src/otel_worker/app.py - Agent telemetry
src/agent/telemetry.py - Trace storage
src/otel_worker/storage/postgres.py
Operator interface
- UI API
src/ui_api_gateway/app.py - Operator UI
ui/src/api.ts
Other components
- User
Connections 20
- User → Agent API: submits query
README.md - Agent API → Agent graph: runs graph
src/agent_service/app.py - Agent graph → LLM client: generates SQL
- Agent graph → MCP client: calls tools
README.md - Agent API → Replay bundles: records or replays
src/agent_service/app.py - MCP client → MCP server: requests tools
README.md - MCP server → SQL execution: registers tools
src/mcp_server/main.py - SQL execution → Database access: executes query
src/mcp_server/tools/execute_sql_query.py - SQL execution → SQL guardrails: enforces policy
src/mcp_server/tools/execute_sql_query.py - Database access → Query targets: selects backend
src/dal/database.py - MCP server → Schema retrieval: configures retrieval
src/mcp_server/main.py - Schema retrieval → Vector indexes: searches vectors
src/mcp_server/services/rag/engine.py - Schema ingestion → Vector indexes: builds indexes
- MCP server → Semantic cache: configures canonicalization
src/mcp_server/main.py - Semantic cache → Database access: uses database
src/mcp_server/services/canonicalization/spacy_pipeline.py - Database access → Control-plane stores: persists metadata
- Operator UI → UI API: calls API
- Agent API → Agent telemetry: emits telemetry
src/agent_service/app.py - Agent telemetry → OTEL worker: exports traces
- OTEL worker → Trace storage: persists traces
src/otel_worker/app.py