From business questions to inspectable, governed SQL.

SQLHarness translates business questions into a structured query description and SQL building blocks, then checks the resulting SQL before allowing execution. The research asks whether this structure can produce more accurate queries for a given cost than a language model generating SQL directly.

Making each query stage inspectable

A generated query can be valid SQL and still answer the wrong question. SQLHarness separates the request’s meaning, the SQL structures available for retrieval, and permission to execute. This makes a failure attributable to a stage instead of treating every wrong result as a prompt problem.

Following one request through the representation

The repository’s version 0.2 example represents “Which region has the most customers?” with a customer entity, a region attribute, a count operation grouped by region, and an argmax operation limited to one result. Directed edges connect the count to its customer target and region grouping; the output returns the region constrained by that maximum.

Retrieval uses the graph to select parameterized SQL building blocks; the assembler receives the graph, selected fragments, and database schema to propose SQL. The necessary operations here are joining customers to regions, grouping, counting, and selecting the largest group. The saved graph is an illustrative contract example, not a recorded model-generated retrieval trace. The executable fixture below separately demonstrates the resulting SQL and authority checks.

Inspect the complete graph, source spans, and schema candidates. Read the architecture contract and proposed training path.

One execution authority across interfaces

The Model Context Protocol (MCP) server and command-line evaluator call the same DatabaseAuthority. Every exposed execution tool uses these checks: database IDs resolve inside a configured root, SQL is parsed and checked against the schema and read-only policy, and allowed execution uses a read-only SQLite connection with a deadline and row cap.

Decisions include structured errors and deterministic receipt IDs for tracing. A receipt is an identifier for a decision, not a claim of immutable storage. Read-only enforcement limits database effects; it does not establish that an allowed query answers the business question correctly. Inspect the safety boundary and its limits.

What the failures changed

The five-query comparison exposed different ceilings: one parser timeout prevented assembly, and the 20-example fragment catalog contained only 58.82% of the exact SQL structures required by the held-out set. Ranking cannot recover a structure absent from the catalog. The learned ranker improved the first result but lost relevant structures farther down the list, without changing final correctness.

Those observations favor expanding the catalog and distilling the parser before further ranker tuning. Repeated teacher samples also had much less agreement on graph edges than nodes, so teacher graphs are treated as candidates to refine rather than unquestioned training labels. These are next research hypotheses, not measured improvements.

Keeping the evaluation populations separate

The 500-example preflight below checks whether reference queries can run within local limits. The five-query CLI pilot checks the direct generation path. The initial seven-train/three-held-out slice tests an early structured pipeline; the later 20-train/five-held-out comparison tests the expanded system and retrieval variants. Their scores describe different development experiments and are not pooled into one benchmark result.