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

{text2sql_engine-0.1.0 → text2sql_engine-0.1.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 text2sql contributors
+Copyright (c) 2026 Mehmet Kaan Durupunar
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: text2sql-engine
-Version: 0.1.0
+Version: 0.1.1
 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: stajyer14
+Author: Mehmet Kaan Durupunar
 License: MIT
+Project-URL: Homepage, https://github.com/defectGI/sqlretrieve
+Project-URL: Repository, https://github.com/defectGI/sqlretrieve
+Project-URL: Issues, https://github.com/defectGI/sqlretrieve/issues
 Keywords: text-to-sql,nl2sql,llm,sql-generation,schema-linking
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -68,7 +71,9 @@ user request
   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, plus a short explanation.
+  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
   general model for linking, a stronger SQL model for generation.
 
@@ -165,8 +170,9 @@ No magic numbers in code. Every tunable is here.
 | `temperature` | float | `0.0` | Sampling temperature. |
 | `top_p` | float | `1.0` | Nucleus-sampling cutoff. |
 | `max_tokens` | int | `1024` | Max tokens for the SQL response. |
-| `prompt_template` | string | `generation.txt` | Template file, looked up in `PROMPT_DIR`. |
+| `prompt_template` | string | `generation.txt` | Template file, looked up in `PROMPT_DIR`. In `raw` mode, defaults to `generation_raw.txt` when unset. |
 | `timeout_seconds` | float | `60` | Per-request timeout. |
+| `output_mode` | string | `structured` | `structured`: force JSON with `sql` + `explanation`, reliable parsing, best for general models. `raw`: ask for plain SQL text (no explanation), better for specialized text-to-SQL models trained to emit SQL only. |
 
 #### `[retry]` — shared by both stages
 

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

@@ -34,7 +34,9 @@ user request
   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, plus a short explanation.
+  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
   general model for linking, a stronger SQL model for generation.
 
@@ -131,8 +133,9 @@ No magic numbers in code. Every tunable is here.
 | `temperature` | float | `0.0` | Sampling temperature. |
 | `top_p` | float | `1.0` | Nucleus-sampling cutoff. |
 | `max_tokens` | int | `1024` | Max tokens for the SQL response. |
-| `prompt_template` | string | `generation.txt` | Template file, looked up in `PROMPT_DIR`. |
+| `prompt_template` | string | `generation.txt` | Template file, looked up in `PROMPT_DIR`. In `raw` mode, defaults to `generation_raw.txt` when unset. |
 | `timeout_seconds` | float | `60` | Per-request timeout. |
+| `output_mode` | string | `structured` | `structured`: force JSON with `sql` + `explanation`, reliable parsing, best for general models. `raw`: ask for plain SQL text (no explanation), better for specialized text-to-SQL models trained to emit SQL only. |
 
 #### `[retry]` — shared by both stages
 

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

@@ -6,12 +6,12 @@ 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.0"
+version = "0.1.1"
 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"
 license = { text = "MIT" }
-authors = [{ name = "stajyer14" }]
+authors = [{ name = "Mehmet Kaan Durupunar" }]
 keywords = ["text-to-sql", "nl2sql", "llm", "sql-generation", "schema-linking"]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -43,13 +43,10 @@ all = ["openai>=1.0", "anthropic>=0.34"]
 # Test toolchain.
 dev = ["pytest>=7.4"]
 
-# Replace OWNER with your GitHub username/org once the repo is pushed, then
-# uncomment. Dead links look worse than no links, so this stays commented out
-# until the repo exists.
-# [project.urls]
-# Homepage = "https://github.com/OWNER/text2sql-engine"
-# Repository = "https://github.com/OWNER/text2sql-engine"
-# Issues = "https://github.com/OWNER/text2sql-engine/issues"
+[project.urls]
+Homepage = "https://github.com/defectGI/sqlretrieve"
+Repository = "https://github.com/defectGI/sqlretrieve"
+Issues = "https://github.com/defectGI/sqlretrieve/issues"
 
 [tool.setuptools.packages.find]
 include = ["text2sql*"]

{text2sql_engine-0.1.0 → text2sql_engine-0.1.1}/tests/test_config.py

@@ -78,6 +78,41 @@ def test_missing_required_env_raises(tmp_path, monkeypatch):
     assert "SCHEMA_PATH" in str(exc.value)
 
 
+def _set_min_env(monkeypatch):
+    monkeypatch.setenv("SCHEMA_PATH", "examples/schema.yaml")
+    monkeypatch.setenv("PROMPT_DIR", "text2sql/prompts")
+    monkeypatch.setenv("LINKING_PROVIDER", "openai")
+    monkeypatch.setenv("LINKING_MODEL", "gpt-4o-mini")
+    monkeypatch.setenv("SQL_PROVIDER", "openai")
+    monkeypatch.setenv("SQL_MODEL", "gpt-4o")
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-openai")
+
+
+def test_output_mode_defaults_to_structured(tmp_path, monkeypatch):
+    _set_min_env(monkeypatch)
+    cfg = _write_config(tmp_path)  # no output_mode set
+    settings = load_settings(config_path=cfg)
+    assert settings.generation.output_mode == "structured"
+    assert settings.generation.prompt_template == "generation.txt"
+
+
+def test_raw_mode_defaults_to_raw_template(tmp_path, monkeypatch):
+    _set_min_env(monkeypatch)
+    cfg = tmp_path / "config.toml"
+    cfg.write_text('[generation]\noutput_mode = "raw"\n', encoding="utf-8")
+    settings = load_settings(config_path=cfg)
+    assert settings.generation.output_mode == "raw"
+    assert settings.generation.prompt_template == "generation_raw.txt"
+
+
+def test_invalid_output_mode_raises(tmp_path, monkeypatch):
+    _set_min_env(monkeypatch)
+    cfg = tmp_path / "config.toml"
+    cfg.write_text('[generation]\noutput_mode = "banana"\n', encoding="utf-8")
+    with pytest.raises(ConfigError):
+        load_settings(config_path=cfg)
+
+
 def test_missing_config_toml_raises(tmp_path, monkeypatch):
     monkeypatch.setenv("SCHEMA_PATH", "examples/schema.yaml")
     monkeypatch.setenv("PROMPT_DIR", "text2sql/prompts")

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

@@ -140,3 +140,30 @@ def test_empty_request_rejected(
     )
     with pytest.raises(ValueError):
         engine.run("   ")
+
+
+def test_raw_mode_returns_plain_sql(settings, schema_provider, prompts, linked_payload):
+    # Raw mode: Stage 2 returns plain SQL, no explanation.
+    settings.generation.output_mode = "raw"
+    settings.generation.prompt_template = "generation_raw.txt"
+    linking = FakeProvider([linked_payload])
+    generation = FakeProvider(["SELECT p.name FROM products p;"])
+    engine = _engine(settings, schema_provider, prompts, linking, generation)
+
+    result = engine.run("list products")
+    assert result.sql == "SELECT p.name FROM products p;"
+    assert result.explanation == ""
+    # complete() was used, not complete_json() -> no schema_name recorded.
+    assert "schema_name" not in generation.calls[0]
+
+
+def test_raw_mode_strips_markdown_fences(settings, schema_provider, prompts, linked_payload):
+    settings.generation.output_mode = "raw"
+    settings.generation.prompt_template = "generation_raw.txt"
+    fenced = "```sql\nSELECT 1;\n```"
+    linking = FakeProvider([linked_payload])
+    generation = FakeProvider([fenced])
+    engine = _engine(settings, schema_provider, prompts, linking, generation)
+
+    result = engine.run("anything")
+    assert result.sql == "SELECT 1;"

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

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

{text2sql_engine-0.1.0 → text2sql_engine-0.1.1}/text2sql/config.py

@@ -52,6 +52,9 @@ class StageSettings:
     timeout_seconds: float = 60.0
     # Used by linking only. Generation ignores it.
     max_tables: int = 8
+    # Used by generation only. "structured" forces JSON (sql + explanation).
+    # "raw" asks for plain SQL text. Linking ignores it.
+    output_mode: str = "structured"
 
 
 @dataclass
@@ -149,6 +152,7 @@ def _stage_from_toml(
             if include_max_tables
             else defaults.max_tables
         ),
+        output_mode=str(table.get("output_mode", defaults.output_mode)).lower(),
     )
 
 
@@ -226,9 +230,21 @@ def load_settings(
         default_template="linking.txt",
         include_max_tables=True,
     )
+
+    gen_tbl = toml_data.get("generation", {})
+    gen_output_mode = str(gen_tbl.get("output_mode", "structured")).lower()
+    if gen_output_mode not in ("structured", "raw"):
+        raise ConfigError(
+            f"[generation] output_mode must be 'structured' or 'raw', "
+            f"got '{gen_output_mode}'."
+        )
+    # In raw mode, default to the raw template unless the user set one.
+    gen_default_template = "generation.txt"
+    if gen_output_mode == "raw" and "prompt_template" not in gen_tbl:
+        gen_default_template = "generation_raw.txt"
     generation = _stage_from_toml(
-        toml_data.get("generation", {}),
-        default_template="generation.txt",
+        gen_tbl,
+        default_template=gen_default_template,
         include_max_tables=False,
     )
 

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

@@ -2,13 +2,22 @@
 
 Takes the reduced schema from Stage 1 and produces a SQL string, plus an
 optional short explanation, in the configured dialect.
+
+Two output modes (config: [generation] output_mode):
+
+* "structured" (default) — force JSON with "sql" and "explanation" fields.
+  Reliable parsing. Best for general chat/instruct models.
+* "raw" — ask for plain SQL text. No explanation. Better for specialized
+  text-to-SQL models that are trained to emit SQL only.
 """
 
 from __future__ import annotations
 
+import re
 from typing import Any
 
 from ..config import Settings
+from ..errors import StructuredOutputError
 from ..logging_utils import get_logger
 from ..prompts import PromptTemplates
 from ..providers.base import LLMProvider
@@ -16,6 +25,18 @@ from ..schema import Schema, schema_to_prompt
 from ..types import LinkedSchema, LLMResponse, StageMetadata, _Timer
 from .json_utils import extract_json, with_retry
 
+# Matches a ```sql ... ``` or ``` ... ``` fenced block.
+_FENCE_RE = re.compile(r"```(?:sql)?\s*(.*?)```", re.DOTALL | re.IGNORECASE)
+
+
+def _strip_sql(text: str) -> str:
+    """Return plain SQL from a raw response. Drops markdown fences if present."""
+    stripped = text.strip()
+    fence = _FENCE_RE.search(stripped)
+    if fence:
+        return fence.group(1).strip()
+    return stripped
+
 logger = get_logger("pipeline.generation")
 
 GENERATION_SCHEMA_NAME = "sql_generation"
@@ -72,7 +93,7 @@ class GenerationStage:
 
         attempts = {"n": 0}
 
-        def attempt() -> tuple[str, str, LLMResponse]:
+        def attempt_structured() -> tuple[str, str, LLMResponse]:
             attempts["n"] += 1
             response = self._provider.complete_json(
                 system=system,
@@ -87,11 +108,26 @@ class GenerationStage:
             sql = str(data.get("sql", "")).strip()
             explanation = str(data.get("explanation", "")).strip()
             if not sql:
-                from ..errors import StructuredOutputError
-
                 raise StructuredOutputError("Generation returned an empty 'sql' field.")
             return sql, explanation, response
 
+        def attempt_raw() -> tuple[str, str, LLMResponse]:
+            attempts["n"] += 1
+            response = self._provider.complete(
+                system=system,
+                user=user,
+                temperature=stage_cfg.temperature,
+                top_p=stage_cfg.top_p,
+                max_tokens=stage_cfg.max_tokens,
+            )
+            sql = _strip_sql(response.text)
+            if not sql:
+                raise StructuredOutputError("Generation returned empty SQL.")
+            # Raw mode does not produce an explanation.
+            return sql, "", response
+
+        attempt = attempt_raw if stage_cfg.output_mode == "raw" else attempt_structured
+
         with _Timer() as timer:
             sql, explanation, response = with_retry(
                 attempt,

text2sql_engine-0.1.1/text2sql/prompts/generation_raw.txt

@@ -0,0 +1,27 @@
+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.

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

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: text2sql-engine
-Version: 0.1.0
+Version: 0.1.1
 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: stajyer14
+Author: Mehmet Kaan Durupunar
 License: MIT
+Project-URL: Homepage, https://github.com/defectGI/sqlretrieve
+Project-URL: Repository, https://github.com/defectGI/sqlretrieve
+Project-URL: Issues, https://github.com/defectGI/sqlretrieve/issues
 Keywords: text-to-sql,nl2sql,llm,sql-generation,schema-linking
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -68,7 +71,9 @@ user request
   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, plus a short explanation.
+  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
   general model for linking, a stronger SQL model for generation.
 
@@ -165,8 +170,9 @@ No magic numbers in code. Every tunable is here.
 | `temperature` | float | `0.0` | Sampling temperature. |
 | `top_p` | float | `1.0` | Nucleus-sampling cutoff. |
 | `max_tokens` | int | `1024` | Max tokens for the SQL response. |
-| `prompt_template` | string | `generation.txt` | Template file, looked up in `PROMPT_DIR`. |
+| `prompt_template` | string | `generation.txt` | Template file, looked up in `PROMPT_DIR`. In `raw` mode, defaults to `generation_raw.txt` when unset. |
 | `timeout_seconds` | float | `60` | Per-request timeout. |
+| `output_mode` | string | `structured` | `structured`: force JSON with `sql` + `explanation`, reliable parsing, best for general models. `raw`: ask for plain SQL text (no explanation), better for specialized text-to-SQL models trained to emit SQL only. |
 
 #### `[retry]` — shared by both stages
 

{text2sql_engine-0.1.0 → text2sql_engine-0.1.1}/text2sql_engine.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ text2sql/pipeline/linking.py
 text2sql/pipeline/pipeline.py
 text2sql/prompts/__init__.py
 text2sql/prompts/generation.txt
+text2sql/prompts/generation_raw.txt
 text2sql/prompts/linking.txt
 text2sql/providers/__init__.py
 text2sql/providers/anthropic_provider.py