feat(llm): proxy-first fallback, env-only OpenAI client; docs: update .env.example

.env.example

@@ -1,11 +1,20 @@
-# ---- GAPGPT proxy config ----
-# If you’re using a proxy (e.g., GapGPT, Helicone, LocalAI, etc.),
-# set these two values. Otherwise, leave them blank.
+# ---- GAPGPT proxy (preferred if set) ----
+# Set these if you're using GapGPT, Helicone, LocalAI, etc.
 PROXY_API_KEY="your-proxy-token-here"
-PROXY_BASE_URL="https://api.proxy.app/v1"
+PROXY_BASE_URL="https://api.gapgpt.app/v1"
+# Optional:
+# LLM_MODEL_ID="gpt-4o-mini"
 
+# ---- Direct OpenAI fallback ----
+# Only used if PROXY_* are not defined.
+# OPENAI_API_KEY="your-openai-key-here"
+# OPENAI_BASE_URL="https://api.openai.com/v1"
+# OPENAI_MODEL_ID="gpt-4o-mini"
 
-# ---- optional direct OpenAI config (for fallback) ----
-# These will be used only if proxy variables are not set.
-#OPENAI_API_KEY="your-openai-key-here"
-#OPENAI_BASE_URL="https://api.openai.com/v1"
+# ---- Database config ----
+# DB_MODE can be "sqlite" (default) or "postgres"
+DB_MODE=sqlite
+# POSTGRES_DSN="postgresql+psycopg2://user:password@localhost:5432/demo"
+
+# ---- App meta ----
+APP_VERSION=0.1.0

.pre-commit-config.yaml

@@ -32,4 +32,4 @@ repos:
         entry: make test
         language: system
         pass_filenames: false
-        stages: [push]
+        stages: [pre-push]

README.md

@@ -1,6 +1,6 @@
 # 🧩 NL2SQL Copilot
 
-A modular **Text-to-SQL Copilot** that converts natural language questions into safe and verified SQL queries.  
+A modular **Text-to-SQL Copilot** that converts natural language questions into safe and verified SQL queries.
 Built with **FastAPI**, **LangGraph**, and **SQLAlchemy**, designed for read-only databases and evaluation on Spider/Dr.Spider benchmarks.
 
 ---
@@ -96,4 +96,3 @@ mypy .
 ## 📄 License
 
 MIT © 2025 Melika Kheirieh
-

adapters/llm/openai_provider.py

@@ -4,21 +4,55 @@ import json
 from adapters.llm.base import LLMProvider
 from openai import OpenAI
 
-# NOTE: Read keys/base URL from env. Do NOT pass base_url in constructors.
-#  - OPENAI_API_KEY   (required)
-#  - OPENAI_BASE_URL  (optional; defaults to OpenAI public)
-#  - OPENAI_MODEL_ID  (e.g., "gpt-4o-mini")
+# NOTE:
+# - Prefer proxy if PROXY_API_KEY and PROXY_BASE_URL are set.
+# - Otherwise, fallback to OPENAI_API_KEY (+ OPENAI_BASE_URL defaulting to https://api.openai.com/v1).
+# - Do NOT pass base_url/api_key in the constructor; rely on env vars.
+
+
+def _resolve_api_config() -> tuple[str, str, str]:
+    """
+    Returns (api_key, base_url, model_id) according to env.
+    Resolution order:
+      1) Proxy: PROXY_API_KEY + PROXY_BASE_URL [+ PROXY_MODEL_ID]
+      2) Direct: OPENAI_API_KEY [+ OPENAI_BASE_URL] [+ OPENAI_MODEL_ID]
+    Additionally, LLM_MODEL_ID (if set) overrides model choice.
+    """
+    # Optional global override for model id
+    override_model = os.getenv("LLM_MODEL_ID")
+
+    proxy_key = os.getenv("PROXY_API_KEY")
+    proxy_url = os.getenv("PROXY_BASE_URL")
+    if proxy_key and proxy_url:
+        model = (
+            override_model
+            or os.getenv("PROXY_MODEL_ID")
+            or os.getenv("OPENAI_MODEL_ID")
+            or "gpt-4o-mini"
+        )
+        return proxy_key, proxy_url, model
+
+    openai_key = os.getenv("OPENAI_API_KEY")
+    if not openai_key:
+        raise RuntimeError(
+            "No API credentials found. Set either PROXY_API_KEY/PROXY_BASE_URL or OPENAI_API_KEY."
+        )
+    openai_url = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
+    model = override_model or os.getenv("OPENAI_MODEL_ID") or "gpt-4o-mini"
+    return openai_key, openai_url, model
 
 
 class OpenAIProvider(LLMProvider):
     provider_id = "openai"
 
     def __init__(self) -> None:
-        self.client = OpenAI(
-            api_key=os.environ["OPENAI_API_KEY"],
-            base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
-        )
-        self.model = os.getenv("OPENAI_MODEL_ID", "gpt-4o-mini")
+        # Resolve and export to env so we don't pass into constructor.
+        api_key, base_url, model = _resolve_api_config()
+        os.environ["OPENAI_API_KEY"] = api_key
+        os.environ["OPENAI_BASE_URL"] = base_url
+        # Create client using env only
+        self.client = OpenAI()
+        self.model = model
 
     def plan(self, *, user_query, schema_preview):
         completion = self.client.chat.completions.create(
@@ -45,7 +79,7 @@ class OpenAIProvider(LLMProvider):
         self, *, user_query, schema_preview, plan_text, clarify_answers=None
     ):
         prompt = f"""
-        You are a precise SQL generator. 
+        You are a precise SQL generator.
         Return ONLY valid JSON with two keys: "sql" and "rationale".
         Do not include any markdown, backticks, or extra text.
 
@@ -72,12 +106,11 @@ class OpenAIProvider(LLMProvider):
             temperature=0,
         )
         content = completion.choices[0].message.content.strip()
-        usage = completion.usage  # ← لازم داریم
+        usage = completion.usage
         t_in = usage.prompt_tokens if usage else None
         t_out = usage.completion_tokens if usage else None
         cost = self._estimate_cost(usage) if usage else None
 
-        # Robust JSON parse (with fallback to substring)
         try:
             parsed = json.loads(content)
         except json.JSONDecodeError:
@@ -93,11 +126,9 @@ class OpenAIProvider(LLMProvider):
 
         sql = (parsed.get("sql") or "").strip()
         rationale = parsed.get("rationale") or ""
-
         if not sql:
             raise ValueError("LLM returned empty 'sql'")
 
-        # IMPORTANT: return the expected 5-tuple
         return sql, rationale, t_in, t_out, cost
 
     def repair(self, *, sql, error_msg, schema_preview):
@@ -125,6 +156,5 @@ class OpenAIProvider(LLMProvider):
         )
 
     def _estimate_cost(self, usage):
-        # Rough estimation example — can be refined with official token pricing
         total = usage.prompt_tokens + usage.completion_tokens
         return total * 0.000001

huggingface.yml

@@ -5,4 +5,4 @@ colorTo: purple
 sdk: gradio
 python_version: "3.11"
 app_file: app.py
-pinned: false
+pinned: false