| --- |
| title: Trace RAG |
| emoji: 🌖 |
| colorFrom: red |
| colorTo: red |
| sdk: gradio |
| sdk_version: 5.9.1 |
| python_version: '3.11' |
| app_file: app.py |
| pinned: false |
| --- |
| |
| # Text-to-SQL Trace RAG — Prototype (Gradio / HF Spaces) |
|
|
| A minimal prototype of **reasoning-trace RAG** applied to retail BI queries. |
|
|
| Instead of retrieving documents/facts, this retrieves **verified past |
| question → SQL → reasoning examples** and uses them as few-shot patterns |
| to guide new SQL generation. Built for repeat-shaped BI questions |
| ("total X by Y for period Z", "top N by metric", "compare A vs B"). |
|
|
| Runs as a **Gradio app** — deploys directly on HuggingFace Spaces' |
| free Gradio SDK. (Docker Spaces are no longer free on HF, so this |
| version drops the Dockerfile entirely.) |
|
|
| ## How it works |
|
|
| 1. `TRACE_LIBRARY` holds verified past questions with their correct SQL |
| and the reasoning steps that produced it. |
| 2. Each question is embedded with `sentence-transformers` and indexed in |
| FAISS. |
| 3. A new question is embedded, FAISS retrieves the most structurally |
| similar past example(s). |
| 4. Those examples are inserted into the prompt as exemplars — the model |
| (via Groq) reuses the query-building *pattern*, not just column names. |
| 5. The generated SQL runs against a DuckDB table and returns real results. |
| 6. A second tab lets you manually confirm a generated query was correct |
| and add it back into the trace library — this is how the library |
| compounds over time. |
|
|
| This is the same retrieve → augment → generate mechanism as normal RAG. |
| The only difference is what gets indexed: solved query patterns instead |
| of documents. |
|
|
| ## Files |
|
|
| - `app.py` — Gradio app (toy DuckDB table + FAISS index + Groq generation |
| + UI to grow the trace library) |
| - `requirements.txt` — pinned dependencies (includes `gradio`) |
| - `README.md` — this file |
|
|
| ## Run locally |
|
|
| ```bash |
| pip install -r requirements.txt --break-system-packages |
| export GROQ_API_KEY=your_key_here |
| python app.py |
| ``` |
|
|
| Opens at `http://127.0.0.1:7860`. |
|
|
| ## Deploy on HuggingFace Spaces (free, no Docker) |
|
|
| 1. Create a new Space → SDK: **Gradio** (not Docker). |
| 2. Upload `app.py` and `requirements.txt` to the Space repo (matches |
| your usual HF Spaces deployment pattern). |
| 3. Go to **Settings → Repository secrets** on the Space and add: |
| - `GROQ_API_KEY` = your Groq key |
| 4. Space builds automatically and launches `app.py`. |
|
|
| No Dockerfile needed — Spaces installs `requirements.txt` and runs |
| `app.py` directly on the Gradio SDK runtime. |
|
|
| ## Making this real (not a toy) |
|
|
| 1. **Replace the toy `sales` table** in `app.py` with a real extract of |
| your actual schema (or connect DuckDB to your real source instead of |
| the in-memory `CREATE TABLE` block). |
| 2. **Replace `TRACE_LIBRARY`** with your team's actual most-common BI |
| question shapes. Hand-verify the correct SQL for each entry before |
| adding it — a wrong example teaches the model a wrong pattern, which |
| is worse than no example at all. |
| 3. **Use the "Add verified example" tab** as the feedback loop: after a |
| generated query is confirmed correct, add it there so future similar |
| questions benefit. Note the library currently resets on app |
| restart (it's in-memory) — for a persistent version, write |
| `TRACE_LIBRARY` to a small JSON file or SQLite table on add, and load |
| it on startup, instead of keeping it as a plain Python list. |
| 4. **Don't force-fit this everywhere.** This pattern only earns its |
| complexity on repeat-shaped analytical/diagnostic questions. For |
| fact-lookup use cases (order status, policy answers — e.g. Reem), |
| plain document RAG is the right tool; this adds nothing there. |
|
|
| ## Caveats |
|
|
| - The trace library needs *coverage of distinct question shapes*, not |
| raw volume — a few dozen verified examples covering your real question |
| patterns will outperform hundreds of near-duplicates. |
| - Never auto-add unverified traces to the library; incorrect examples |
| compound into worse output over time, not just missing info. |
| - In-memory `TRACE_LIBRARY` resets every time the Space restarts/sleeps |
| on the free tier — fine for a prototype demo, not for production use. |
