text2sql-engine 0.1.1__tar.gz → 0.2.0__tar.gz

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: text2sql-engine
-Version: 0.1.1
+Version: 0.2.0
 Summary: Schema-agnostic, config-driven Text-to-SQL library (2-stage LLM pipeline). Produces a SQL string; never connects to or executes against a database.
 Author: Mehmet Kaan Durupunar
 License: MIT
@@ -70,8 +70,9 @@ user request
   reduces the schema to the relevant part and returns structured JSON. Output is
   forced via `response_format` (OpenAI) or tool-calling (Anthropic), with
   strict-JSON parsing and retry as a fallback.
-- **Stage 2 (generation)** takes the request and that reduced subset. It writes
-  SQL in the target dialect. Two output modes (config `output_mode`):
+- **Stage 2 (generation)** takes the request, that reduced subset, and Stage 1's
+  reasoning (rationale, chosen joins, column reasons). It follows that logic and
+  writes SQL in the target dialect. Two output modes (config `output_mode`):
   `structured` forces JSON with `sql` + `explanation`; `raw` asks for plain SQL
   text, for specialized text-to-SQL models.
 - The two stages can use **different providers and models**. For example a cheap

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/README.md

@@ -33,8 +33,9 @@ user request
   reduces the schema to the relevant part and returns structured JSON. Output is
   forced via `response_format` (OpenAI) or tool-calling (Anthropic), with
   strict-JSON parsing and retry as a fallback.
-- **Stage 2 (generation)** takes the request and that reduced subset. It writes
-  SQL in the target dialect. Two output modes (config `output_mode`):
+- **Stage 2 (generation)** takes the request, that reduced subset, and Stage 1's
+  reasoning (rationale, chosen joins, column reasons). It follows that logic and
+  writes SQL in the target dialect. Two output modes (config `output_mode`):
   `structured` forces JSON with `sql` + `explanation`; `raw` asks for plain SQL
   text, for specialized text-to-SQL models.
 - The two stages can use **different providers and models**. For example a cheap

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 # Distribution name on PyPI. The IMPORT name stays `text2sql`:
 #     pip install text2sql-engine   ->   import text2sql
 name = "text2sql-engine"
-version = "0.1.1"
+version = "0.2.0"
 description = "Schema-agnostic, config-driven Text-to-SQL library (2-stage LLM pipeline). Produces a SQL string; never connects to or executes against a database."
 readme = "README.md"
 requires-python = ">=3.11"

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/tests/test_pipeline.py

@@ -59,6 +59,21 @@ def test_stage2_receives_only_linked_tables(
     assert "Table: customers" not in stage2_user_prompt
 
 
+def test_stage2_prompt_carries_linking_reasoning(
+    settings, schema_provider, prompts, linked_payload, generation_payload
+):
+    # Stage 1's rationale and joins must reach the Stage 2 prompt so the SQL
+    # model follows the linking logic instead of guessing.
+    linking = FakeProvider([linked_payload])
+    generation = FakeProvider([generation_payload])
+    engine = _engine(settings, schema_provider, prompts, linking, generation)
+    engine.run("top products")
+
+    stage2_user_prompt = generation.calls[0]["user"]
+    assert "rank by units sold" in stage2_user_prompt  # from the rationale
+    assert "order_items.product_id = products.id" in stage2_user_prompt  # a join
+
+
 def test_hallucinated_names_are_dropped(
     settings, schema_provider, prompts, generation_payload
 ):

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/tests/test_prompts.py

@@ -29,7 +29,14 @@ def test_packaged_fallback_when_no_directory():
 def test_render_substitutes_placeholders():
     tmpl = PromptTemplates().load("generation.txt")
     system, user = tmpl.render(
-        linked_schema="X", request="Y", dialect="postgres", entities="a", filters="b"
+        linked_schema="X",
+        request="Y",
+        dialect="postgres",
+        entities="a",
+        filters="b",
+        columns="c",
+        joins="d",
+        rationale="e",
     )
     assert "postgres" in system
     assert "Y" in user

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/text2sql/__init__.py

@@ -37,7 +37,7 @@ from .types import (
     TokenUsage,
 )
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 __all__ = [
     "Text2SQL",

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/text2sql/pipeline/generation.py

@@ -82,6 +82,19 @@ class GenerationStage:
         reduced_schema = full_schema.subset(linked.tables)
         reduced_text = schema_to_prompt(reduced_schema) if reduced_schema.tables else "(none)"
 
+        # Forward Stage 1's reasoning to Stage 2. The linking model already
+        # worked out the logic (ranges, joins, which column means what); the SQL
+        # model should follow it instead of guessing.
+        columns_text = "\n".join(
+            f"- {c.table}.{c.column}" + (f" — {c.reason}" if c.reason else "")
+            for c in linked.columns
+        ) or "(none)"
+        joins_text = "\n".join(
+            f"- {j.left_table}.{j.left_column} = {j.right_table}.{j.right_column}"
+            for j in linked.joins
+        ) or "(none)"
+        rationale_text = linked.rationale.strip() or "(none)"
+
         template = self._prompts.load(stage_cfg.prompt_template)
         system, user = template.render(
             linked_schema=reduced_text,
@@ -89,6 +102,9 @@ class GenerationStage:
             dialect=self._settings.general.sql_dialect,
             entities=", ".join(linked.entities) or "(none)",
             filters="; ".join(linked.filters) or "(none)",
+            columns=columns_text,
+            joins=joins_text,
+            rationale=rationale_text,
         )
 
         attempts = {"n": 0}

text2sql_engine-0.2.0/text2sql/prompts/generation.txt

@@ -0,0 +1,42 @@
+SYSTEM:
+You are an expert SQL generator. You get a user request, a reduced schema (only
+the relevant tables/columns/joins picked by an upstream linking step), and that
+step's analysis. Produce one correct SQL query in the target dialect.
+
+Rules:
+- Use only the tables and columns in the reduced schema.
+- Follow the linking analysis. It already worked out the logic; do not ignore it.
+- Respect the intended comparison semantics from the analysis and filter hints.
+  If a value should be matched by a numeric range or an exact compare, implement
+  it that way. Do not fall back to substring/text (LIKE) matching unless that is
+  clearly what is meant.
+- Use the suggested joins to connect tables. Prefer explicit JOINs.
+- Write idiomatic SQL for the target dialect: {dialect}.
+- Do not run the query. Only produce it.
+- Return the answer strictly as the requested JSON object with two fields:
+  "sql" (the query) and "explanation" (one or two sentences).
+
+USER:
+Target SQL dialect: {dialect}
+
+Reduced schema (relevant subset):
+--------------------------------
+{linked_schema}
+--------------------------------
+
+Linking analysis (reasoning from the previous step — follow this logic):
+{rationale}
+
+Relevant columns:
+{columns}
+
+Suggested joins:
+{joins}
+
+Detected entities: {entities}
+Filter hints: {filters}
+
+User request:
+"{request}"
+
+Write the SQL query that answers the request.

text2sql_engine-0.2.0/text2sql/prompts/generation_raw.txt

@@ -0,0 +1,41 @@
+SYSTEM:
+You are an expert SQL generator. You get a user request, a reduced schema (only
+the relevant tables/columns/joins picked by an upstream linking step), and that
+step's analysis. Produce one correct SQL query in the target dialect.
+
+Rules:
+- Use only the tables and columns in the reduced schema.
+- Follow the linking analysis. It already worked out the logic; do not ignore it.
+- Respect the intended comparison semantics from the analysis and filter hints.
+  If a value should be matched by a numeric range or an exact compare, implement
+  it that way. Do not fall back to substring/text (LIKE) matching unless that is
+  clearly what is meant.
+- Use the suggested joins to connect tables. Prefer explicit JOINs.
+- Write idiomatic SQL for the target dialect: {dialect}.
+- Do not run the query. Only produce it.
+- Output ONLY the SQL query. No explanation, no comment, no markdown fences.
+
+USER:
+Target SQL dialect: {dialect}
+
+Reduced schema (relevant subset):
+--------------------------------
+{linked_schema}
+--------------------------------
+
+Linking analysis (reasoning from the previous step — follow this logic):
+{rationale}
+
+Relevant columns:
+{columns}
+
+Suggested joins:
+{joins}
+
+Detected entities: {entities}
+Filter hints: {filters}
+
+User request:
+"{request}"
+
+Write the SQL query that answers the request.

{text2sql_engine-0.1.1 → text2sql_engine-0.2.0}/text2sql_engine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: text2sql-engine
-Version: 0.1.1
+Version: 0.2.0
 Summary: Schema-agnostic, config-driven Text-to-SQL library (2-stage LLM pipeline). Produces a SQL string; never connects to or executes against a database.
 Author: Mehmet Kaan Durupunar
 License: MIT
@@ -70,8 +70,9 @@ user request
   reduces the schema to the relevant part and returns structured JSON. Output is
   forced via `response_format` (OpenAI) or tool-calling (Anthropic), with
   strict-JSON parsing and retry as a fallback.
-- **Stage 2 (generation)** takes the request and that reduced subset. It writes
-  SQL in the target dialect. Two output modes (config `output_mode`):
+- **Stage 2 (generation)** takes the request, that reduced subset, and Stage 1's
+  reasoning (rationale, chosen joins, column reasons). It follows that logic and
+  writes SQL in the target dialect. Two output modes (config `output_mode`):
   `structured` forces JSON with `sql` + `explanation`; `raw` asks for plain SQL
   text, for specialized text-to-SQL models.
 - The two stages can use **different providers and models**. For example a cheap

text2sql_engine-0.1.1/text2sql/prompts/generation.txt

@@ -1,28 +0,0 @@
-SYSTEM:
-You are an expert SQL generator. You get a user request and a reduced schema
-(only the relevant tables/columns/joins picked by an upstream linking step).
-Produce one correct SQL query in the target dialect.
-
-Rules:
-- Use only the tables and columns in the reduced schema.
-- Write idiomatic SQL for the target dialect: {dialect}.
-- Prefer explicit JOINs using the given relations.
-- Do not run the query. Only produce it.
-- Return the answer strictly as the requested JSON object with two fields:
-  "sql" (the query) and "explanation" (one or two sentences).
-
-USER:
-Target SQL dialect: {dialect}
-
-Reduced schema (relevant subset):
---------------------------------
-{linked_schema}
---------------------------------
-
-Detected entities: {entities}
-Filter hints: {filters}
-
-User request:
-"{request}"
-
-Write the SQL query that answers the request.

text2sql_engine-0.1.1/text2sql/prompts/generation_raw.txt

@@ -1,27 +0,0 @@
-SYSTEM:
-You are an expert SQL generator. You get a user request and a reduced schema
-(only the relevant tables/columns/joins picked by an upstream linking step).
-Produce one correct SQL query in the target dialect.
-
-Rules:
-- Use only the tables and columns in the reduced schema.
-- Write idiomatic SQL for the target dialect: {dialect}.
-- Prefer explicit JOINs using the given relations.
-- Do not run the query. Only produce it.
-- Output ONLY the SQL query. No explanation, no comment, no markdown fences.
-
-USER:
-Target SQL dialect: {dialect}
-
-Reduced schema (relevant subset):
---------------------------------
-{linked_schema}
---------------------------------
-
-Detected entities: {entities}
-Filter hints: {filters}
-
-User request:
-"{request}"
-
-Write the SQL query that answers the request.