Uploaded support files

templates/report_styles.css

@@ -0,0 +1,6 @@
+body { font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif; padding: 24px; line-height: 1.5; }
+h1,h2,h3 { margin-top: 1.2em; }
+code, pre { background: #f6f8fa; padding: 2px 4px; border-radius: 4px; }
+table { border-collapse: collapse; width: 100%; }
+th, td { border: 1px solid #ddd; padding: 8px; }
+th { background: #fafafa; }

templates/report_template.md

@@ -0,0 +1,26 @@
+# Insight Report
+
+**User Query**: {{ user_query }}
+
+**Plan**: {{ plan.steps }}  
+**Rationale**: {{ plan.rationale }}
+
+{% if sql_preview %}
+## SQL Preview
+{{ sql_preview }}
+{% endif %}
+
+{% if predict_preview %}
+## Predictions Preview
+{{ predict_preview }}
+{% endif %}
+
+{% if explain_images.global_bar %}
+## Global Feature Importance (SHAP)
+<img src="{{ explain_images.global_bar }}" style="max-width: 100%;" />
+{% endif %}
+
+{% if explain_images.beeswarm %}
+## SHAP Beeswarm
+<img src="{{ explain_images.beeswarm }}" style="max-width: 100%;" />
+{% endif %}

tools/explain_tool.py

@@ -0,0 +1,44 @@
+import os
+import io
+import shap
+import base64
+import pandas as pd
+from huggingface_hub import hf_hub_download
+from ..utils.config import AppConfig
+from ..utils.tracing import Tracer
+
+class ExplainTool:
+    def __init__(self, cfg: AppConfig, tracer: Tracer):
+        self.cfg = cfg
+        self.tracer = tracer
+        self._model = None
+
+    def _ensure_model(self):
+        if self._model is None:
+            import joblib
+            path = hf_hub_download(repo_id=self.cfg.hf_model_repo, filename="model.pkl", token=os.getenv("HF_TOKEN"))
+            self._model = joblib.load(path)
+
+    def _to_data_uri(self, fig) -> str:
+        buf = io.BytesIO()
+        fig.savefig(buf, format="png", bbox_inches="tight")
+        buf.seek(0)
+        return "data:image/png;base64," + base64.b64encode(buf.read()).decode()
+
+    def run(self, df: pd.DataFrame):
+        self._ensure_model()
+        # Use a small sample for speed on CPU Spaces
+        sample = df.sample(min(len(df), 500), random_state=42)
+        explainer = shap.Explainer(self._model, sample, feature_names=list(sample.columns))
+        shap_values = explainer(sample)
+
+        # Global summary plot
+        fig1 = shap.plots.bar(shap_values, show=False)
+        img1 = self._to_data_uri(fig1)
+
+        # Beeswarm (optional)
+        fig2 = shap.plots.beeswarm(shap_values, show=False)
+        img2 = self._to_data_uri(fig2)
+
+        self.tracer.trace_event("explain", {"rows": len(sample)})
+        return {"global_bar": img1, "beeswarm": img2}

tools/predict_tool.py

@@ -0,0 +1,32 @@
+import os
+import pandas as pd
+import joblib
+from huggingface_hub import hf_hub_download
+from ..utils.config import AppConfig
+from ..utils.tracing import Tracer
+
+class PredictTool:
+    def __init__(self, cfg: AppConfig, tracer: Tracer):
+        self.cfg = cfg
+        self.tracer = tracer
+        self._model = None
+        self._feature_meta = None
+
+    def _ensure_loaded(self):
+        if self._model is None:
+            path = hf_hub_download(repo_id=self.cfg.hf_model_repo, filename="model.pkl", token=os.getenv("HF_TOKEN"))
+            self._model = joblib.load(path)
+            meta = hf_hub_download(repo_id=self.cfg.hf_model_repo, filename="feature_metadata.json", token=os.getenv("HF_TOKEN"))
+            import json
+            with open(meta, "r") as f:
+                self._feature_meta = json.load(f)
+
+    def run(self, df: pd.DataFrame) -> pd.DataFrame:
+        self._ensure_loaded()
+        use_cols = self._feature_meta.get("feature_order", list(df.columns))
+        X = df[use_cols].copy()
+        preds = self._model.predict_proba(X)[:, 1] if hasattr(self._model, "predict_proba") else self._model.predict(X)
+        out = df.copy()
+        out[self._feature_meta.get("prediction_column", "prediction")] = preds
+        self.tracer.trace_event("predict", {"rows": len(out)})
+        return out

tools/report_tool.py

@@ -0,0 +1,25 @@
+import os
+from jinja2 import Environment, FileSystemLoader
+import pandas as pd
+from ..utils.tracing import Tracer
+
+class ReportTool:
+    def __init__(self, cfg, tracer: Tracer):
+        self.cfg = cfg
+        self.tracer = tracer
+        self.env = Environment(loader=FileSystemLoader("templates"))
+
+    def render_and_save(self, user_query: str, sql_preview: pd.DataFrame | None, predict_preview: pd.DataFrame | None, explain_images: dict, plan: dict):
+        tmpl = self.env.get_template("report_template.md")
+        html = tmpl.render(
+            user_query=user_query,
+            plan=plan,
+            sql_preview=sql_preview.to_markdown(index=False) if sql_preview is not None else "",
+            predict_preview=predict_preview.to_markdown(index=False) if predict_preview is not None else "",
+            explain_images=explain_images,
+        )
+        out_path = f"report_{pd.Timestamp.utcnow().strftime('%Y%m%d_%H%M%S')}.html"
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write("<link rel=\"stylesheet\" href=\"templates/report_styles.css\">\n" + html)
+        self.tracer.trace_event("report", {"path": out_path})
+        return out_path

tools/sql_tool.py

@@ -0,0 +1,49 @@
+import os
+import re
+import pandas as pd
+from typing import Optional
+from ..utils.config import AppConfig
+from ..utils.tracing import Tracer
+
+class SQLTool:
+    def __init__(self, cfg: AppConfig, tracer: Tracer):
+        self.cfg = cfg
+        self.tracer = tracer
+        self.backend = cfg.sql_backend  # "bigquery" or "motherduck"
+        if self.backend == "bigquery":
+            from google.cloud import bigquery
+            from google.oauth2 import service_account
+            key_json = os.getenv("GCP_SERVICE_ACCOUNT_JSON")
+            if not key_json:
+                raise RuntimeError("Missing GCP_SERVICE_ACCOUNT_JSON secret")
+            creds = service_account.Credentials.from_service_account_info(
+                eval(key_json) if key_json.strip().startswith("{") else {}
+            )
+            self.client = bigquery.Client(credentials=creds, project=cfg.gcp_project)
+        elif self.backend == "motherduck":
+            import duckdb
+            token = self.cfg.motherduck_token or os.getenv("MOTHERDUCK_TOKEN")
+            db_name = self.cfg.motherduck_db or "default"
+            self.client = duckdb.connect(f"md:/{db_name}?motherduck_token={token}")
+        else:
+            raise RuntimeError("Unknown SQL backend")
+
+    def _nl_to_sql(self, message: str) -> str:
+        # Minimal NL2SQL heuristic; replace with your own mapping or LLM prompt.
+        # Expect users to include table names. Example: "avg revenue by month from dataset.sales"
+        m = message.lower()
+        if "avg" in m and " by " in m:
+            return "-- Example template; edit me\nSELECT DATE_TRUNC(month, date_col) AS month, AVG(metric) AS avg_metric FROM dataset.table GROUP BY 1 ORDER BY 1;"
+        # fallback: pass-through if user typed SQL explicitly
+        if re.match(r"^\s*select ", m):
+            return message
+        return "SELECT * FROM dataset.table LIMIT 100;"
+
+    def run(self, message: str) -> pd.DataFrame:
+        sql = self._nl_to_sql(message)
+        self.tracer.trace_event("sql_query", {"sql": sql, "backend": self.backend})
+        if self.backend == "bigquery":
+            df = self.client.query(sql).to_dataframe()
+        else:
+            df = self.client.execute(sql).fetch_df()
+        return df

utils/config.py

@@ -0,0 +1,21 @@
+import os
+from dataclasses import dataclass
+
+@dataclass
+class AppConfig:
+    hf_model_repo: str
+    sql_backend: str # "bigquery" or "motherduck"
+    gcp_project: str | None = None
+    motherduck_db: str | None = None
+    motherduck_token: str | None = None
+
+
+@classmethod
+def from_env(cls):
+    return cls(
+        hf_model_repo=os.getenv("HF_MODEL_REPO", "your-username/your-private-tabular-model"),
+        sql_backend=os.getenv("SQL_BACKEND", "motherduck"),
+        gcp_project=os.getenv("GCP_PROJECT"),
+        motherduck_db=os.getenv("MOTHERDUCK_DB", "default"),
+        motherduck_token=os.getenv("MOTHERDUCK_TOKEN")
+)

utils/tracing.py

@@ -0,0 +1,30 @@
+import os
+import json
+from typing import Optional
+
+class Tracer:
+    def __init__(self, client=None, trace_url: Optional[str] = None):
+        self.client = client
+        self.trace_url = trace_url
+
+    @classmethod
+    def from_env(cls):
+        try:
+            from langfuse import Langfuse
+            pk = os.getenv("LANGFUSE_PUBLIC_KEY")
+            sk = os.getenv("LANGFUSE_SECRET_KEY")
+            host = os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com")
+            if pk and sk:
+                client = Langfuse(public_key=pk, secret_key=sk, host=host)
+                session = client.trace("tabular-agentic-xai")
+                return cls(client=session, trace_url=session.get_url() if hasattr(session, "get_url") else None)
+        except Exception:
+            pass
+        return cls()
+
+    def trace_event(self, name: str, payload: dict):
+        if self.client:
+            try:
+                self.client.event(name=name, input=json.dumps(payload))
+            except Exception:
+                pass