How aditihnayak/text-to-sql-guardrails works
This is a Text-to-SQL API: a question is matched to relevant database tables, turned into a prompt, and sent to an LLM for SQL generation. The API validates and bounds the SQL before read-only execution, then checks the result through back-translation, sanity checks, and an independently generated query before returning rows and a confidence score. Schema discovery, retrieval, generation, execution, and confidence assessment are distinct stages. The excerpts show the API pipeline and its principal calls; the frontend and some integrations were not sampled, so their connections are omitted.
Main entry points: main.py Query API · schema_filter.py Table retrieval · back_translation.py Back-translation · llm_client.py LLM client
Components 20
API orchestration
- Query API
app/main.py - Query metrics
app/metrics.py
Schema and prompting
- Schema discovery
app/schema_introspection.py - Table retrieval
app/schema_filter.py - Text embeddings
app/embeddings.py - Table descriptions
app/schema_metadata.py - Prompt construction
app/prompt_constructor.py - Example prompts
app/few_shot_examples.py
SQL generation and safety
- LLM client
app/llm_client.py - SQL guardrails
app/guardrail.py - SQL validation
app/sql_validator.py
Result verification
- Back-translation
app/back_translation.py - Result sanity
app/sanity_checker.py - Alternative queries
app/multi_query_validator.py - Confidence scoring
app/confidence_scorer.py
Database access
- Read-only execution
app/query_executor.py - Database engine
app/db.py
Other components
- Questioner
- Groq service
- PostgreSQL database
Connections 21
- Questioner → Query API: submits question
app/main.py - Query API → Schema discovery: discovers schema
app/main.py - Query API → Table retrieval: retrieves tables
app/main.py - Table retrieval → Text embeddings: embeds text
app/schema_filter.py - Table retrieval → Table descriptions: reads descriptions
app/schema_filter.py - Query API → Prompt construction: builds prompt
app/main.py - Prompt construction → Example prompts: uses examples
app/prompt_constructor.py - Query API → LLM client: generates SQL
app/main.py - LLM client → Groq service: requests generation
app/llm_client.py - Query API → SQL guardrails: checks SQL
app/main.py - SQL guardrails → SQL validation: validates SQL
app/guardrail.py - Query API → Read-only execution: executes SQL
app/main.py - Read-only execution → Database engine: opens connection
app/query_executor.py - Database engine → PostgreSQL database: connects to
- Query API → Back-translation: checks alignment
app/main.py - Back-translation → LLM client: requests translation
app/back_translation.py - Back-translation → Text embeddings: compares meaning
app/back_translation.py - Query API → Result sanity: checks rows
app/main.py - Query API → Alternative queries: builds comparison
app/main.py - Query API → Confidence scoring: scores confidence
app/main.py - Query API → Query metrics: records queries
app/main.py