README.md

metadata

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

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.