DEV Community: Ramprakash Munugapati

I thought Text-to-SQL was just a translation layer. I was completely wrong. 🤯

Ramprakash Munugapati — Sat, 10 Oct 2026 14:52:30 +0000

A few weeks ago, if you'd asked me how a system like "Ask your database a question in English" actually worked, I would have given you an answer that was confident, simple, and completely wrong:

"It just converts human words into code, like Google Translate but for SQL."

I genuinely thought the entire hurdle was translation. I was wrong in about six different ways. As a developer diving deeper into data products, sitting down to actually pull this engine apart was a massive reality check.

If you are a software engineer, data professional, or a Product Manager wondering why your team's new NLQ feature keeps throwing bizarre data errors, here is exactly how the engine works under the hood.

🛠️ The Terminology Matrix

Before pulling the engine apart, we need to separate three terms that often get lazy, interchangeable definitions:

NLP (Natural Language Processing): The entire broad toolbox. Anything a computer does with human language—summarization, sentiment analysis, speech-to-text—lives here.
NLU (Natural Language Understanding): The cognitive middle layer. This handles the critical question: "What does this sentence actually mean?"
NLQ (Natural Language Query): A highly specific application. Taking a question in plain English and turning it into an executable database query (usually SQL).

Roughly speaking: NLP is the toolbox. NLQ is the specific machine you build with it.

🗺️ The 6-Step Pipeline Nobody Tells You About

When a user types: "Which movies did Nolan direct after 2010?", the system doesn't just leap to a SELECT statement. It executes a rigorous, multi-step pipeline where every single stage can fail independently:

Intent Classification: What kind of response does the user expect? "Which movies" tells the system they want a string array or a list of entities—not a row count, and not a boolean True/False.
Entity Recognition: Identifying the literal nouns and variables. Here, it extracts Nolan (Person) and 2010 (Year).
Relation Extraction: Defining how those entities interact. The word "direct" maps the entity Nolan to the entity movies through a specific relationship: DIRECTED.
Functional Filtering: Translating human prepositions into mathematical operators. The word "after" isn't database data; it's a hidden operator hiding inside a preposition (year > 2010).
Schema Linking: Mapping those abstract concepts to your actual, physical database tables and columns.
SQL Generation: Assembling the structured intents, entities, relations, filters, and schema paths into a clean, syntactic query string.

🕸️ The Hidden Engine: Schema Linking & Path Costs

The hardest part of this entire pipeline is a concept I completely overlooked before: Schema Linking.

How does the machine know that the word "Nolan" belongs in directors.name instead of actors.name or movies.title?

It models the entire problem as a network graph.

Every word in your natural language prompt becomes a node.
Every table, column, and relational operator in your database schema becomes a node.
The system then draws connections (edges) between them, weighting those edges based on semantic probability.

For the word "Nolan":

An edge to directors.name is cheap (the structural context says "directed").
An edge to actors.name is expensive (Nolan isn't acting in this context).
An edge to movies.title is prohibitively expensive (it's a person's name, not a film title).

The system then runs a shortest-path algorithm (like Dijkstra’s) to find the "cheapest" cumulative path through the entire graph. The cheapest path wins and becomes the chosen interpretation.

The best part? "Confidence" isn't a vague sentiment—it's literal math.

If two distinct graph paths have highly competitive, close costs, the system identifies structural ambiguity. Instead of recklessly guessing, a well-engineered NLQ system uses that mathematical uncertainty to trigger a user prompt: "Did you mean...?"

📑 The Day-One Reference Table

If you are trying to parse complex human sentences into structured logic, map them against this matrix. Once you can fill this out for any query, the engineering pattern clicks:

Concept	The Question It Answers	Practical Example
Intent	What am I returning to the user interface?	`FIND_MOVIE`
Entity	What specific variables did the user name?	`Nolan`, `2010`
Relation	How are those variables structurally linked?	`DIRECTED`
Filter	What logical or mathematical constraints apply?	`year > 2010`
Table/Column	Where does this data physically live?	`movies`, `directors.name`

🤖 Enter LLMs: Changing the Architecture

The explicit, graph-based pipeline described above is the classic deterministic approach. Then, Large Language Models completely disrupted the architecture.

Today, you can feed an LLM your database schema alongside a raw human question, and it will output working SQL instantly. No manual graph building, no custom intent classifiers, and no explicit schema linking. Those edge weights are already natively baked into the model's billions of parameters.

But this speed introduces massive architectural trade-offs:

Attribute	Classic Pipeline	LLM Direct Translation
Time to Deployment	Days to weeks of manual configuration	Minutes of prompt engineering
Paraphrase Handling	Rigid; only handles anticipated phrasing	Exceptional; handles natural variance
Debugging	Fully transparent; inspect every single node	Opaque; black-box generation
Schema Hallucination	Zero chance; operates in a closed set	High risk; invents columns out of thin air
Confidence Scoring	Exact mathematical path cost	Unreliable or non-existent

The defining issue is Schema Hallucination. A classic pipeline physically cannot query a column that doesn't exist because it's bound to a closed schema graph. An LLM possesses an open vocabulary and will happily write movies.actor_name even if that column was never created in your database.

🏗️ The Modern Blueprint: Hybrid Architectures

Because of this, production-grade enterprise systems rarely rely on pure LLM generation. Instead, they use a Hybrid Architecture:

They leverage the LLM for its flexible, deeply nuanced understanding of human phrasing.
They pipe that output into a deterministic validation engine that cross-checks the SQL against the real database schema.
If an error or hallucination is caught, it feeds the programmatic error back to the LLM for an instantaneous self-correction retry loop.

Speed from the LLM. Guardrails and safety from the classic pipeline.

💡 The Core Takeaway

If you build, manage, or buy data products, remember this single rule:

Keyword search matches strings. NLQ matches meaning.

Search simply crawls documents looking for literal character matches. NLQ figures out the underlying human intent and dynamically engineers a structural program to solve it.

Once you understand that distinction, every technical challenge—from prepositions acting as hidden operators ("best" meaning ORDER BY DESC LIMIT 1) to handling structural ambiguity—suddenly makes complete sense.

Building a Deterministic Spec-Driven Development (SDD) Agent for GitHub Copilot

Ramprakash Munugapati — Thu, 08 Oct 2026 14:23:40 +0000

We are living in an era where AI can write code in fractions of a second. But if you maintain high-stakes enterprise applications, you know the quiet nightmare that comes with it: subtle regressions, broken configurations, and silently passing suites with empty assertions.

The core architectural flaw of most AI tooling setups is simple: We are letting the LLM generate the implementation AND grade its own work.

To fix this, I spent the last few weeks building a local Spec-Driven Development (SDD) Agent designed to serve as a strict, non-negotiable supervisor for GitHub Copilot across both VS Code and IntelliJ IDEA.

The philosophy is straightforward: Let Copilot do the creative drafting, but decouple the state machine and verification pipeline entirely into an un-bypassable local engine.

The Dual-System Architecture

The codebase splits responsibilities clearly across three primary boundaries:

The Native Prompts: A thin .github/copilot-instructions.md layer guiding requirement collection and path-scoped implementations inside the IDE.
The Command Line Engine: A deterministic Python application (sdd_agent.py) managing task compilation, directed graphs, and approvals.
The Local Status Dashboard: A vanilla HTML/JS portal bound strictly to a loopback address (localhost:8080) providing continuous log buffering.

[ Phase 1: DISCOVERY ]
AI discovers & drafts Spec, Plan, Tasks
│
▼
[ Cryptographic Gate ]
Human signs off via Python CLI (SHA-256)
│
▼
[ Phase 2: IMPLEMENTATION ]
AI writes code via Test-First workflow
│
▼
[ Phase 3: VERIFICATION ]
Python Engine executes Gradle / Checkstyle / JaCoCo

Enforcing a Cryptographic Contract (SHA-256)

To stop an AI agent from shifting the goalposts mid-way through writing code, the Python CLI introduces deterministic fingerprinting. When a human reviews and approves the initial specification, the system captures a unique hash of that document state.

Spec Approval: Binds the SPEC.md fingerprint.
Plan Approval: Binds the SPEC.md + PLAN.md fingerprints.
Task Approval: Binds the SPEC.md + PLAN.md + TASKS.json fingerprints.

If the AI tweaks a requirement line or alters a task definition during implementation, the signature changes instantly. The validation engine immediately trips, changes the workspace state to STALE, and freezes the pipeline until a human manually clears it.

The Hard Validation Gates

When you execute python sdd_agent.py verify, the core engine skips the "vibe checks" and processes cold static and dynamic parameters:

Cycle Detection: Parses the TASKS.json file into a directed graph to explicitly trace dependencies and catch circular paths before spawning tasks.
Style Adherence: Forcing standard Java 21 Gradle modules through active Checkstyle passes. Any style deviation fails the gate.
The Coverage Floor: Rather than scanning human-readable HTML strings or relying on loose proxy numbers, the engine parses raw XML test evidence. It pulls data straight from the <counter type="LINE"> elements inside jacocoTestReport.xml. If the line metric reads 79.9% against an inclusive 80% floor, the execution fails outright.

Verification != Functional Completeness

As engineers, we know that hitting a 100% mechanical check pass does not guarantee that business logic parameters are actually solved. However, removing human error from the build safety loop allows us to spend our energy looking at the final human acceptance evaluation rather than fighting basic regressions.

The complete architectural setup, bootstrap files, and templates are open-source and ready for exploration.

📖 Deep-Dive Mechanics on Medium: https://medium.com
💻 Open-Source Repository on GitHub: https://github.com

I would love to get your feedback on this state-machine structure. How are you enforcing verification loops on your own local AI configurations?

🤖 2. The Reddit Plan (Targeted Subreddits)

Reddit communities have zero tolerance for self-promotion or marketing fluff. To get upvoted, your post must focus on architectural choices, challenges, and source patterns.

Recommended Communities:

• r/java (Focus strictly on the Java 21/Gradle layout, Checkstyle validation, and raw JaCoCo parsing).
• r/AIEngineering or r/LocalLLaMA (Focus on the local execution model, SHA-256 validation, and eliminating external cloud dependencies).