Update README.md

README.md

@@ -4,10 +4,99 @@ emoji: 🌖
 colorFrom: red
 colorTo: red
 sdk: gradio
-sdk_version: 6.25.0
-python_version: '3.12'
+sdk_version: 5.9.1
+python_version: '3.11'
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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.