Skip to content

Commit 4a79ecb

Browse files
JuliaEdomclaude
andcommitted
refactor: NLSQL_M_SCHEMA / NLSQL_DAC env reads → PipelineConfig fields
Closes Kimi audit 2026-05-25 P1.5 (`generate_sql.py:40-49`: `import os` inside the node + runtime `os.environ.get(...)` reads — hurts testability and surprises eval drivers that don't propagate env on subprocess fan-out). Changes: - `PipelineConfig` gains `use_m_schema: bool` and `use_dac_prompt: bool` with the same defaults the env-read produced (both False) plus docstrings pointing at the legacy env path - `make_generate_sql_node` accepts the flags via keyword params; the in-node `import os` + `os.environ.get(...)` calls are gone - `build_pipeline` threads the new config fields to `make_generate_sql_node` - `api/main.py::_make_singletons` reads `NLSQL_M_SCHEMA` / `NLSQL_DAC` once at boot and translates them into the typed flags — preserving the documented FastAPI / Streamlit env-toggle UX - `scripts/run_helallao_voting.py` (the only documented eval driver that sets these envs) reads them once when building its own `PipelineConfig` - `tests/agent/nodes/test_generate_sql_flags.py`: 7 unit tests covering default behaviour, each flag in isolation, both flags combined, and a factory-shared-mutable-default regression guard Gates: ruff check ✓ · ruff format --check ✓ · mypy strict ✓ · 344 tests pass (was 337, +7 new). No env-toggle behaviour change for documented workflows; node-internal testability improved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 03ad6ae commit 4a79ecb

5 files changed

Lines changed: 162 additions & 11 deletions

File tree

‎scripts/run_helallao_voting.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,8 @@ def main() -> int:
9797
)
9898
idx = SchemaIndex(persist_dir="chroma_data", embedder=emb)
9999

100+
import os
101+
100102
cfg = PipelineConfig(
101103
sql_provider=sql_provider,
102104
explain_provider=sql_provider,
@@ -107,6 +109,8 @@ def main() -> int:
107109
cross_db_fewshot=True,
108110
verify_retry_on_empty=False,
109111
enable_grounded_critique=False,
112+
use_m_schema=os.environ.get("NLSQL_M_SCHEMA") == "1",
113+
use_dac_prompt=os.environ.get("NLSQL_DAC") == "1",
110114
)
111115
pipeline = build_pipeline(cfg)
112116

‎src/nl_sql/agent/graph.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,17 @@ class PipelineConfig:
129129
"""When True, run a cheap post-execution row-shape critique before
130130
deterministic formatting and route one failed critique to `repair_once`.
131131
"""
132+
use_m_schema: bool = False
133+
"""When True, render the schema block as M-Schema (XiYan-SQL compact
134+
one-line-per-column with inline samples + trailing FK pairs block) instead
135+
of the default verbose card layout. Replaces the legacy `NLSQL_M_SCHEMA=1`
136+
env toggle; `api/main.py` reads the env once at boot and threads it here so
137+
individual nodes no longer touch `os.environ` at runtime."""
138+
use_dac_prompt: bool = False
139+
"""When True, use the CHASE-SQL divide-and-conquer prompt
140+
(`generate_sql_dac.txt`) which decomposes multi-clause questions into
141+
sub-questions before composing SQL. Replaces the legacy `NLSQL_DAC=1`
142+
env toggle; `api/main.py` reads the env once at boot and threads it here."""
132143

133144

134145
@dataclass(slots=True)
@@ -172,6 +183,8 @@ def build_pipeline(config: PipelineConfig) -> CompiledStateGraph[Any, Any, Any,
172183
config.sql_provider,
173184
sort_schema_block=config.sort_schema_block,
174185
temperature=config.sql_temperature,
186+
use_m_schema=config.use_m_schema,
187+
use_dac_prompt=config.use_dac_prompt,
175188
),
176189
"validate": make_validate_node(),
177190
"repair_once": make_repair_once_node(

‎src/nl_sql/agent/nodes/generate_sql.py‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,27 +27,26 @@ def make_generate_sql_node(
2727
max_tokens: int = 1024,
2828
temperature: float = 0.0,
2929
sort_schema_block: bool = False,
30+
use_m_schema: bool = False,
31+
use_dac_prompt: bool = False,
3032
) -> Callable[[PipelineState], PipelineState]:
3133
def node(state: PipelineState) -> PipelineState:
3234
question = state.get("question", "")
3335
dialect = state.get("dialect", "sqlite")
3436
context = state.get("context")
3537
plan_raw = (state.get("plan") or "").strip()
3638
plan_block = plan_raw if plan_raw else "(no plan — generate SQL directly from question)"
37-
# Experimental: M-Schema serialization (XiYan-SQL style) — compact
38-
# one-line-per-column with inline samples + trailing FK pairs block.
39-
# Toggle via env NLSQL_M_SCHEMA=1 to A/B against verbose card layout.
40-
import os
41-
42-
if os.environ.get("NLSQL_M_SCHEMA") == "1":
39+
# Schema rendering: M-Schema (XiYan-SQL compact) vs verbose card layout.
40+
# Driven by `PipelineConfig.use_m_schema`; api/main.py bootstraps the
41+
# flag from `NLSQL_M_SCHEMA=1` env so existing eval scripts keep working.
42+
if use_m_schema:
4343
schema_text = render_m_schema(context)
4444
else:
4545
schema_text = render_schema_block(context, sort_alphabetically=sort_schema_block)
46-
# Experimental: CHASE-SQL divide-and-conquer prompt — decompose
47-
# multi-clause questions into sub-questions before composing SQL.
48-
# Toggle via env NLSQL_DAC=1. Targeted at residue retry layer for
49-
# the challenging tier (multi-part conditional questions).
50-
prompt_name = "generate_sql_dac" if os.environ.get("NLSQL_DAC") == "1" else "generate_sql"
46+
# CHASE-SQL divide-and-conquer prompt — decomposes multi-clause questions
47+
# into sub-questions before composing SQL. Driven by
48+
# `PipelineConfig.use_dac_prompt`; api/main.py bootstraps from `NLSQL_DAC=1`.
49+
prompt_name = "generate_sql_dac" if use_dac_prompt else "generate_sql"
5150
prompt = load_prompt(
5251
prompt_name,
5352
dialect=dialect,

‎src/nl_sql/api/main.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,8 +225,12 @@ def _build_pipeline_components(
225225
def _make_singletons() -> tuple[Any, DatabaseRegistry, SchemaIndex, LLMProvider]:
226226
"""Lazy: build the pipeline only when the first /ask hits — keeps /healthz
227227
fast and avoids touching Chroma when the API is used for status probes."""
228+
import os
229+
228230
settings = get_settings()
229231
registry, schema_index, sql_provider, explain_provider = _build_pipeline_components(settings)
232+
# Eval-script env toggles bootstrap into PipelineConfig once at boot;
233+
# individual nodes never read os.environ at runtime (see graph.py docstrings).
230234
config = PipelineConfig(
231235
sql_provider=sql_provider,
232236
explain_provider=explain_provider,
@@ -236,6 +240,8 @@ def _make_singletons() -> tuple[Any, DatabaseRegistry, SchemaIndex, LLMProvider]
236240
sort_schema_block=True,
237241
cross_db_fewshot=True,
238242
verify_retry_on_empty=True,
243+
use_m_schema=os.environ.get("NLSQL_M_SCHEMA") == "1",
244+
use_dac_prompt=os.environ.get("NLSQL_DAC") == "1",
239245
)
240246
pipeline = build_pipeline(config)
241247
return pipeline, registry, schema_index, sql_provider
Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
"""Unit tests for `make_generate_sql_node` PipelineConfig flag plumbing.
2+
3+
Closes Kimi audit 2026-05-25 P1.5: NLSQL_M_SCHEMA / NLSQL_DAC moved off
4+
`os.environ` reads inside the node into typed `PipelineConfig` fields. The
5+
tests assert the node respects the flags directly instead of monkey-patching
6+
the environment.
7+
"""
8+
9+
from __future__ import annotations
10+
11+
from dataclasses import dataclass, field
12+
13+
import pytest
14+
15+
from nl_sql.agent.nodes.generate_sql import make_generate_sql_node
16+
from nl_sql.agent.state import PipelineState
17+
from nl_sql.llm.providers.base import GenerateRequest, GenerateResponse
18+
from nl_sql.schema_index.indexer import SchemaQueryHit
19+
from nl_sql.schema_index.retriever import ContextBundle
20+
21+
22+
@dataclass(slots=True)
23+
class _RecordingProvider:
24+
name: str = "fake"
25+
model: str = "fake-1"
26+
prompts: list[str] = field(default_factory=list)
27+
response: str = '{"sql": "SELECT 1", "rationale": "stub", "confidence": 0.9, "tables_used": []}'
28+
29+
def generate(self, req: GenerateRequest) -> GenerateResponse:
30+
self.prompts.append(req.prompt)
31+
return GenerateResponse(text=self.response, model=self.model)
32+
33+
34+
def _stub_context() -> ContextBundle:
35+
hit = SchemaQueryHit(
36+
chunk_id="customers-overview",
37+
table_name="customers",
38+
db_id="demo",
39+
text="Table customers(id INTEGER, name TEXT)",
40+
distance=0.1,
41+
metadata={
42+
"table_name": "customers",
43+
"columns": "id,name",
44+
"primary_key": "id",
45+
"samples": "[{'id': 1, 'name': 'Alice'}]",
46+
},
47+
)
48+
return ContextBundle(
49+
db_id="demo",
50+
question="How many customers?",
51+
schema_hits=[hit],
52+
fk_neighbours=[],
53+
fewshots=[],
54+
)
55+
56+
57+
def _state(question: str = "How many customers?") -> PipelineState:
58+
return {
59+
"question": question,
60+
"dialect": "sqlite",
61+
"context": _stub_context(),
62+
"plan": "",
63+
"trace": [],
64+
}
65+
66+
67+
def _run_with_flags(use_m_schema: bool, use_dac_prompt: bool) -> str:
68+
provider = _RecordingProvider()
69+
node = make_generate_sql_node(
70+
provider, use_m_schema=use_m_schema, use_dac_prompt=use_dac_prompt
71+
)
72+
node(_state())
73+
return provider.prompts[0]
74+
75+
76+
def test_default_uses_plain_template_and_default_schema_render() -> None:
77+
prompt = _run_with_flags(use_m_schema=False, use_dac_prompt=False)
78+
# Default `generate_sql.txt` is plain — DAC variant injects a Decompose
79+
# / sub-question instruction. Verify default does not have it.
80+
assert "Decompose" not in prompt
81+
assert "sub-question" not in prompt.lower()
82+
83+
84+
def test_use_dac_prompt_switches_template() -> None:
85+
prompt = _run_with_flags(use_m_schema=False, use_dac_prompt=True)
86+
# `generate_sql_dac.txt` instructs the model to decompose multi-clause
87+
# questions before composing SQL — at least one of these keywords must
88+
# be present in the DAC variant but absent in the default.
89+
assert "Decompose" in prompt or "sub-question" in prompt.lower(), (
90+
f"Expected DAC prompt markers in selected template, got: {prompt[:400]}"
91+
)
92+
93+
94+
def test_use_m_schema_changes_schema_rendering() -> None:
95+
default_prompt = _run_with_flags(use_m_schema=False, use_dac_prompt=False)
96+
mschema_prompt = _run_with_flags(use_m_schema=True, use_dac_prompt=False)
97+
# M-Schema renderer emits a `# Columns` / `# Foreign keys` block; the
98+
# default verbose renderer dumps raw `hit.text`. We only need to assert
99+
# the rendered schema portion of the prompt differs between flags, since
100+
# the prompt template / question / fewshot are identical.
101+
assert default_prompt != mschema_prompt, (
102+
"use_m_schema=True must change the rendered schema block in the prompt"
103+
)
104+
105+
106+
@pytest.mark.parametrize(
107+
("use_m_schema", "use_dac_prompt"),
108+
[(True, True), (True, False), (False, True), (False, False)],
109+
)
110+
def test_flags_do_not_leak_across_node_factory_calls(
111+
use_m_schema: bool,
112+
use_dac_prompt: bool,
113+
) -> None:
114+
"""Regression guard: each `make_generate_sql_node` call captures its own
115+
flags; flipping flags on a later call must not retroactively affect a
116+
previously-built node (catches accidental shared mutable default).
117+
"""
118+
provider_a = _RecordingProvider()
119+
node_a = make_generate_sql_node(
120+
provider_a, use_m_schema=use_m_schema, use_dac_prompt=use_dac_prompt
121+
)
122+
provider_b = _RecordingProvider()
123+
_ = make_generate_sql_node(
124+
provider_b, use_m_schema=not use_m_schema, use_dac_prompt=not use_dac_prompt
125+
)
126+
node_a(_state())
127+
prompt = provider_a.prompts[0]
128+
expected_dac = "Decompose" in prompt or "sub-question" in prompt.lower()
129+
assert expected_dac is use_dac_prompt

0 commit comments

Comments
 (0)