Deploy RAG app with Groq LFS

.gitattributes

@@ -0,0 +1 @@
+*.faiss filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,12 @@
+# Data
+data/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.env
+
+# IDE
+.vscode/
+.idea/

README.md

@@ -0,0 +1,36 @@
+---
+title: SQL Books RAG
+emoji: 📚
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: "6.6.0"
+app_file: app.py
+pinned: false
+---
+
+# 📚 SQL Books RAG
+
+A Retrieval-Augmented Generation (RAG) system that answers SQL questions using content from 5 SQL textbooks.
+
+## How It Works
+
+1. **Retrieval** – Your question is embedded using `all-MiniLM-L6-v2` and matched against a FAISS index of ~500-word chunks extracted from the books.
+2. **Generation** – The top-5 most relevant chunks are fed as context to `Llama 3.1-8B` via the Groq API to produce a detailed, grounded answer.
+
+## Data Sources
+
+| Book | Author |
+|------|--------|
+| Practical SQL: A Beginner's Guide to Storytelling with Data | Anthony DeBarros |
+| SQL for Data Scientists | Renee M. Teate |
+| SQL for Data Analysis | Cathy Tanimura |
+| The Art of SQL | Stéphane Faroult |
+| Learning SQL: Generate, Manipulate, and Retrieve Data | Alan Beaulieu |
+
+## Tech Stack
+
+- **Embeddings**: `sentence-transformers/all-MiniLM-L6-v2`
+- **Vector Store**: FAISS (IndexFlatL2)
+- **LLM**: `Llama 3.1-8B-Instant` via Groq API (free tier)
+- **UI**: Gradio

app.py

@@ -0,0 +1,176 @@
+"""
+app.py - SQL Books RAG application powered by Gradio.
+Retrieves relevant chunks from a FAISS index and generates answers
+using Llama 3 via the Groq API (free tier).
+"""
+
+import json
+import os
+
+import faiss
+import gradio as gr
+import numpy as np
+import requests
+from sentence_transformers import SentenceTransformer
+
+# -- Configuration -------------------------------------------------------------
+INDEX_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "faiss_index")
+EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+GEN_MODEL = "llama-3.1-8b-instant"
+API_URL = "https://api.groq.com/openai/v1/chat/completions"
+GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
+TOP_K = 5
+
+# -- Load resources once at startup --------------------------------------------
+print("Loading embedding model ...")
+embedder = SentenceTransformer(EMBED_MODEL)
+
+print("Loading FAISS index ...")
+index = faiss.read_index(os.path.join(INDEX_DIR, "index.faiss"))
+
+print("Loading chunk metadata ...")
+with open(os.path.join(INDEX_DIR, "chunks.json"), "r", encoding="utf-8") as f:
+    chunks = json.load(f)
+
+print(f"Ready: {index.ntotal} vectors, {len(chunks)} chunks")
+print(f"LLM: {GEN_MODEL} via Groq API")
+print("App ready.")
+
+
+# -- RAG pipeline ---------------------------------------------------------------
+def retrieve(query: str, top_k: int = TOP_K):
+    """Embed the query and retrieve the top-k most similar chunks."""
+    query_vec = embedder.encode([query]).astype("float32")
+    distances, indices = index.search(query_vec, top_k)
+    results = []
+    for dist, idx in zip(distances[0], indices[0]):
+        if idx < len(chunks):
+            results.append({
+                "text": chunks[idx]["text"],
+                "source": chunks[idx]["source"],
+                "distance": float(dist),
+            })
+    return results
+
+
+def generate_answer(query: str, context_chunks: list) -> str:
+    """Build a prompt from retrieved context and generate an answer via Groq API."""
+    context = "\n\n".join(
+        f"[Source: {c['source']}]\n{c['text'][:800]}" for c in context_chunks
+    )
+
+    system_message = (
+        "You are a helpful SQL tutor. Answer the user's question using ONLY the "
+        "provided context from SQL textbooks. Give clear, detailed explanations with "
+        "examples where appropriate. If the context doesn't contain enough information, "
+        "say so honestly. Format your answer using markdown."
+    )
+
+    user_message = (
+        f"## Context from SQL Textbooks\n\n{context}\n\n"
+        f"---\n\n## Question\n{query}"
+    )
+
+    headers = {
+        "Authorization": f"Bearer {GROQ_API_KEY}",
+        "Content-Type": "application/json",
+    }
+    payload = {
+        "model": GEN_MODEL,
+        "messages": [
+            {"role": "system", "content": system_message},
+            {"role": "user", "content": user_message},
+        ],
+        "max_tokens": 1024,
+        "temperature": 0.3,
+    }
+
+    try:
+        response = requests.post(API_URL, headers=headers, json=payload, timeout=60)
+        response.raise_for_status()
+        result = response.json()
+        return result["choices"][0]["message"]["content"].strip()
+    except requests.exceptions.HTTPError:
+        return f"⚠️ API error ({response.status_code}): {response.text}"
+    except Exception as e:
+        return f"⚠️ Generation error: {e}"
+
+
+def rag_query(question: str):
+    """Full RAG pipeline: retrieve, generate, format output."""
+    if not question.strip():
+        return "Please enter a question.", ""
+
+    # Retrieve
+    retrieved = retrieve(question)
+
+    # Generate
+    answer = generate_answer(question, retrieved)
+
+    # Format sources
+    sources_text = "\n\n---\n\n".join(
+        f"**Source {i+1}** - *{r['source']}*\n\n{r['text'][:500]}{'...' if len(r['text']) > 500 else ''}"
+        for i, r in enumerate(retrieved)
+    )
+
+    return answer, sources_text
+
+
+# -- Gradio UI ------------------------------------------------------------------
+DESCRIPTION = """
+# 📚 SQL Books RAG
+
+Ask any question about SQL and get answers grounded in content from **5 SQL textbooks**:
+
+- *Practical SQL: A Beginner's Guide to Storytelling with Data*
+- *SQL for Data Scientists* (Renee M. Teate)
+- *SQL for Data Analysis: Advanced Techniques for Transforming Data into Insights*
+- *The Art of SQL*
+- *Learning SQL: Generate, Manipulate, and Retrieve Data*
+
+Powered by **FAISS** retrieval + **Llama 3.1** generation.
+"""
+
+EXAMPLES = [
+    "What is a JOIN in SQL?",
+    "Explain the difference between INNER JOIN and LEFT JOIN",
+    "How do window functions work in SQL?",
+    "What is a subquery and when should I use one?",
+    "How do I use GROUP BY with HAVING?",
+    "What are common table expressions (CTEs)?",
+]
+
+my_theme = gr.themes.Soft(
+    primary_hue="indigo",
+    secondary_hue="blue",
+)
+
+with gr.Blocks(title="SQL Books RAG", theme=my_theme) as demo:
+    gr.Markdown(DESCRIPTION)
+
+    with gr.Row():
+        with gr.Column(scale=3):
+            question = gr.Textbox(
+                label="Your SQL Question",
+                placeholder="e.g. What is a JOIN in SQL?",
+                lines=2,
+            )
+            submit_btn = gr.Button("Ask", variant="primary", size="lg")
+        with gr.Column(scale=1):
+            gr.Markdown("### Try these examples")
+            for ex in EXAMPLES:
+                gr.Button(ex, size="sm").click(
+                    fn=lambda e=ex: e, outputs=question
+                )
+
+    answer_box = gr.Markdown(label="Answer")
+
+    with gr.Accordion("Retrieved Source Chunks", open=False):
+        sources_box = gr.Markdown()
+
+    submit_btn.click(fn=rag_query, inputs=question, outputs=[answer_box, sources_box])
+    question.submit(fn=rag_query, inputs=question, outputs=[answer_box, sources_box])
+
+
+if __name__ == "__main__":
+    demo.launch()

build_index.py

@@ -0,0 +1,99 @@
+"""
+build_index.py — Extract text from SQL PDFs, chunk it, embed it, and save a FAISS index.
+Run this once locally before deploying to Hugging Face.
+"""
+
+import json
+import os
+import fitz  # PyMuPDF
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+# ── Configuration ──────────────────────────────────────────────────────────────
+DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
+INDEX_DIR = os.path.join(os.path.dirname(__file__), "faiss_index")
+CHUNK_SIZE = 500       # approximate tokens (≈words for English)
+CHUNK_OVERLAP = 50     # overlap between consecutive chunks
+EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+
+
+# ── PDF Extraction ─────────────────────────────────────────────────────────────
+def extract_text_from_pdf(pdf_path: str) -> str:
+    """Extract all text from a PDF using PyMuPDF."""
+    doc = fitz.open(pdf_path)
+    text = ""
+    for page in doc:
+        text += page.get_text()
+    doc.close()
+    return text
+
+
+# ── Chunking ───────────────────────────────────────────────────────────────────
+def chunk_text(text: str, source: str, chunk_size: int = CHUNK_SIZE, overlap: int = CHUNK_OVERLAP):
+    """Split text into overlapping word-level chunks with metadata."""
+    words = text.split()
+    chunks = []
+    start = 0
+    while start < len(words):
+        end = start + chunk_size
+        chunk_words = words[start:end]
+        chunk_text_str = " ".join(chunk_words)
+        # Skip very short chunks (< 30 words)
+        if len(chunk_words) >= 30:
+            chunks.append({
+                "text": chunk_text_str,
+                "source": source,
+                "chunk_id": len(chunks),
+            })
+        start += chunk_size - overlap
+    return chunks
+
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+def main():
+    os.makedirs(INDEX_DIR, exist_ok=True)
+
+    # 1. Extract & chunk all PDFs
+    all_chunks = []
+    pdf_files = [f for f in os.listdir(DATA_DIR) if f.lower().endswith(".pdf")]
+    print(f"Found {len(pdf_files)} PDFs in {DATA_DIR}")
+
+    for pdf_file in sorted(pdf_files):
+        pdf_path = os.path.join(DATA_DIR, pdf_file)
+        print(f"  Processing: {pdf_file} ...", end=" ", flush=True)
+        text = extract_text_from_pdf(pdf_path)
+        chunks = chunk_text(text, source=pdf_file)
+        all_chunks.extend(chunks)
+        print(f"{len(chunks)} chunks")
+
+    print(f"\nTotal chunks: {len(all_chunks)}")
+
+    # 2. Generate embeddings
+    print(f"\nLoading embedding model: {EMBED_MODEL}")
+    model = SentenceTransformer(EMBED_MODEL)
+
+    texts = [c["text"] for c in all_chunks]
+    print("Generating embeddings ...")
+    embeddings = model.encode(texts, show_progress_bar=True, batch_size=64)
+    embeddings = np.array(embeddings).astype("float32")
+    print(f"Embeddings shape: {embeddings.shape}")
+
+    # 3. Build FAISS index
+    import faiss
+
+    dimension = embeddings.shape[1]
+    index = faiss.IndexFlatL2(dimension)
+    index.add(embeddings)
+    print(f"FAISS index size: {index.ntotal} vectors, dimension {dimension}")
+
+    # 4. Save
+    faiss.write_index(index, os.path.join(INDEX_DIR, "index.faiss"))
+    with open(os.path.join(INDEX_DIR, "chunks.json"), "w", encoding="utf-8") as f:
+        json.dump(all_chunks, f, ensure_ascii=False, indent=2)
+
+    print(f"\n[OK] Index saved to {INDEX_DIR}/index.faiss")
+    print(f"[OK] Chunks saved to {INDEX_DIR}/chunks.json")
+
+
+if __name__ == "__main__":
+    main()

faiss_index/index.faiss

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1e6a7d0dcfbcb0f0a0a266ae938ef77e79b9b067dcb3752e36d85739055183e9
+size 1826349

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=6.0.0
+sentence-transformers
+faiss-cpu
+pymupdf
+requests