Text2SQL Agent
A fully local Text2SQL pipeline: a locally-hosted LLM, local vector search, and local embeddings all run on-prem, so schema and data never leave the machine — built for teams that can't send either off premises.
Problem
Turning a natural-language question into accurate SQL against a real database schema, without ever sending that schema or the underlying data to an external LLM API.
Flow
A five-stage pipeline that narrows a full database schema down to exactly what's relevant before a locally-hosted LLM ever sees it.
- 01A 4-channel hybrid schema search — semantic (Qdrant + a Turkish BERT embedding model), lexical n-gram TF-IDF, a hand-built Turkish synonym/keyword index, and search over real column values — merges results by source-priority ranking.
- 02Schema pruning builds a compact pool (primary/foreign keys + the top relevant columns per table) instead of ever sending the full schema, keeping prompt size bounded regardless of database size.
- 03A DFS-based path finder proposes valid JOIN chains from a precomputed foreign-key graph, constraining the model to real join paths.
- 04A locally-hosted LLM (llama.cpp, GGUF, temperature 0) generates the SQL.
- 05The query executes against PostgreSQL, with a bounded retry loop (max 3 attempts) on syntax errors.
Technologies
Notable decisions
No agent framework, by design
Built without LangChain or LlamaIndex as an explicit constraint — full control over every step of schema search, pruning, and generation, with no framework overhead or black-box retrieval behavior to work around.
Schema pruning instead of full-schema prompting
Rather than sending the whole schema on every request, a compact, ranked pool of tables and columns is built per query — keeping token usage bounded even on large, many-table databases.
DFS join-path finder over a precomputed FK graph
JOIN chains are proposed from real foreign-key relationships instead of being freely generated by the model, which keeps generated SQL structurally valid against the actual schema.
Result
A fully local pipeline — the LLM, embeddings, and vector search all run on-prem — with schema pruning that keeps token usage bounded even on large, many-table schemas. ~95% accuracy on simple queries, ~85% on medium-complexity queries.