README.md

---
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.