Upload folder using huggingface_hub

README.md

@@ -1,13 +1,19 @@
 ---
-title: Rag Document Qa
-emoji: 🌖
-colorFrom: blue
-colorTo: yellow
+title: Document Question Answering (RAG)
+emoji: 📚
+colorFrom: indigo
+colorTo: pink
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
+python_version: "3.11"
 app_file: app.py
 pinned: false
+license: mit
+short_description: Retrieval-augmented question answering over a small doc set
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Document Question Answering (RAG) - live demo
+
+Ask a question about a small documentation set. The system retrieves the most
+relevant passages and answers from them, citing the source file for each fact.
+
+- Code: https://github.com/delcenjo/rag-document-assistant

app.py

@@ -0,0 +1,59 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "src"))
+
+import gradio as gr
+from ragassistant import generator
+from ragassistant.rag import RAGPipeline
+
+DEMO_MODEL = "claude-haiku-4-5-20251001"
+MAX_QUESTION_CHARS = 300
+
+_pipeline = None
+
+
+def get_pipeline():
+    global _pipeline
+    if _pipeline is None:
+        _pipeline = RAGPipeline()
+    return _pipeline
+
+
+def answer(question):
+    question = (question or "").strip()
+    if not question:
+        return "Ask a question about the product documentation."
+    if len(question) > MAX_QUESTION_CHARS:
+        return f"Please keep the question under {MAX_QUESTION_CHARS} characters."
+    if not os.getenv("ANTHROPIC_API_KEY"):
+        return "This demo is not configured yet (the API key is missing)."
+    try:
+        pipeline = get_pipeline()
+        contexts = pipeline.retriever.retrieve(question)
+        return generator.generate_answer(question, contexts, model=DEMO_MODEL)
+    except Exception:
+        return "The service is busy or unavailable right now. Please try again in a moment."
+
+
+demo = gr.Interface(
+    fn=answer,
+    inputs=gr.Textbox(lines=2, label="Ask a question about the product documentation",
+                      placeholder="What is the refund policy?"),
+    outputs=gr.Textbox(lines=8, label="Answer (with sources)"),
+    title="Document Question Answering (RAG)",
+    description=(
+        "Ask a question about a small documentation set (overview, pricing, API, "
+        "security, FAQ). The system retrieves the most relevant passages and answers "
+        "from them, citing the source file for each fact."
+    ),
+    article="Code: https://github.com/delcenjo/rag-document-assistant",
+    examples=[
+        ["What is the refund policy?"],
+        ["How do I authenticate with the API?"],
+        ["Where is the data stored?"],
+    ],
+)
+
+if __name__ == "__main__":
+    demo.launch(ssr_mode=False)

requirements.txt

@@ -0,0 +1,3 @@
+sentence-transformers
+anthropic
+numpy

src/ragassistant/__init__.py

@@ -0,0 +1,3 @@
+"""Retrieval-augmented question answering over a document corpus."""
+
+__version__ = "1.0.0"

src/ragassistant/cli.py

@@ -0,0 +1,35 @@
+import argparse
+import os
+
+from dotenv import load_dotenv
+
+from .config import TOP_K
+from .generator import generate_answer
+from .retriever import Retriever
+
+
+def main():
+    load_dotenv()
+    parser = argparse.ArgumentParser(description="Ask questions about the indexed corpus")
+    parser.add_argument("question", nargs="?", help="question to ask")
+    parser.add_argument("--top-k", type=int, default=TOP_K)
+    parser.add_argument("--show-context", action="store_true", help="print retrieved chunks")
+    args = parser.parse_args()
+
+    question = args.question or input("Question: ")
+    contexts = Retriever().retrieve(question, args.top_k)
+
+    if args.show_context or not os.getenv("ANTHROPIC_API_KEY"):
+        print("\nRetrieved context:")
+        for chunk, score in contexts:
+            print(f"  [{chunk['source']}] score={score:.3f}")
+
+    if os.getenv("ANTHROPIC_API_KEY"):
+        print("\nAnswer:")
+        print(generate_answer(question, contexts))
+    else:
+        print("\nSet ANTHROPIC_API_KEY (see .env.example) to generate a written answer.")
+
+
+if __name__ == "__main__":
+    main()

src/ragassistant/config.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+CORPUS_DIR = PROJECT_ROOT / "data" / "corpus"
+STORAGE_DIR = PROJECT_ROOT / "storage"
+INDEX_PATH = STORAGE_DIR / "index.npz"
+META_PATH = STORAGE_DIR / "chunks.json"
+
+EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+CHAT_MODEL = "claude-sonnet-4-6"
+
+CHUNK_SIZE = 600
+CHUNK_OVERLAP = 100
+TOP_K = 4

src/ragassistant/documents.py

@@ -0,0 +1,30 @@
+from .config import CHUNK_OVERLAP, CHUNK_SIZE
+
+
+def load_documents(corpus_dir):
+    documents = []
+    for path in sorted(corpus_dir.glob("*.md")):
+        documents.append({"source": path.name, "text": path.read_text(encoding="utf-8")})
+    return documents
+
+
+def chunk_text(text, chunk_size=CHUNK_SIZE, overlap=CHUNK_OVERLAP):
+    paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
+    chunks, current = [], ""
+    for paragraph in paragraphs:
+        if current and len(current) + len(paragraph) + 1 > chunk_size:
+            chunks.append(current)
+            current = (current[-overlap:] + " " + paragraph) if overlap else paragraph
+        else:
+            current = f"{current}\n{paragraph}".strip() if current else paragraph
+    if current:
+        chunks.append(current)
+    return chunks
+
+
+def build_chunks(documents, chunk_size=CHUNK_SIZE, overlap=CHUNK_OVERLAP):
+    chunks = []
+    for document in documents:
+        for i, text in enumerate(chunk_text(document["text"], chunk_size, overlap)):
+            chunks.append({"id": f"{document['source']}#{i}", "source": document["source"], "text": text})
+    return chunks

src/ragassistant/embeddings.py

@@ -0,0 +1,19 @@
+from functools import lru_cache
+
+import numpy as np
+
+from .config import EMBEDDING_MODEL
+
+
+@lru_cache(maxsize=1)
+def _model():
+    from sentence_transformers import SentenceTransformer
+
+    return SentenceTransformer(EMBEDDING_MODEL)
+
+
+def embed(texts):
+    vectors = _model().encode(
+        list(texts), normalize_embeddings=True, convert_to_numpy=True
+    )
+    return np.asarray(vectors, dtype=np.float32)

src/ragassistant/evaluate.py

@@ -0,0 +1,31 @@
+from .config import TOP_K
+from .retriever import Retriever
+
+EVAL_SET = [
+    {"question": "How much does the Pro plan cost?", "source": "pricing.md"},
+    {"question": "What encryption is used for data at rest?", "source": "security.md"},
+    {"question": "What is the API rate limit on the Free plan?", "source": "api.md"},
+    {"question": "How can I export my notes?", "source": "faq.md"},
+    {"question": "Does Nimbus Notes work offline?", "source": "faq.md"},
+    {"question": "Which platforms are supported?", "source": "overview.md"},
+    {"question": "How do I cancel my subscription?", "source": "pricing.md"},
+    {"question": "Is Nimbus Notes SOC 2 compliant?", "source": "security.md"},
+]
+
+
+def main():
+    retriever = Retriever()
+    hits = 0
+    for item in EVAL_SET:
+        results = retriever.retrieve(item["question"], TOP_K)
+        sources = [chunk["source"] for chunk, _ in results]
+        hit = item["source"] in sources
+        hits += hit
+        print(f"[{'ok  ' if hit else 'MISS'}] {item['question']}  ->  {sources}")
+    recall = hits / len(EVAL_SET)
+    print(f"\nRetrieval recall@{TOP_K}: {recall:.2f} ({hits}/{len(EVAL_SET)})")
+    return recall
+
+
+if __name__ == "__main__":
+    main()

src/ragassistant/generator.py

@@ -0,0 +1,25 @@
+from .config import CHAT_MODEL
+
+SYSTEM_PROMPT = (
+    "You answer questions using only the provided context. "
+    "If the answer is not contained in the context, say you don't know. "
+    "Cite the source filename in square brackets after each fact you use."
+)
+
+
+def build_prompt(question, contexts):
+    context_block = "\n\n".join(f"[{chunk['source']}]\n{chunk['text']}" for chunk, _ in contexts)
+    return f"Context:\n{context_block}\n\nQuestion: {question}"
+
+
+def generate_answer(question, contexts, model=CHAT_MODEL):
+    import anthropic
+
+    client = anthropic.Anthropic()
+    message = client.messages.create(
+        model=model,
+        max_tokens=512,
+        system=SYSTEM_PROMPT,
+        messages=[{"role": "user", "content": build_prompt(question, contexts)}],
+    )
+    return message.content[0].text

src/ragassistant/ingest.py

@@ -0,0 +1,16 @@
+from .config import CORPUS_DIR, INDEX_PATH, META_PATH
+from .documents import build_chunks, load_documents
+from .embeddings import embed
+from .vector_store import VectorStore
+
+
+def main():
+    documents = load_documents(CORPUS_DIR)
+    chunks = build_chunks(documents)
+    vectors = embed([chunk["text"] for chunk in chunks])
+    VectorStore(vectors, chunks).save(INDEX_PATH, META_PATH)
+    print(f"Indexed {len(chunks)} chunks from {len(documents)} documents -> {INDEX_PATH}")
+
+
+if __name__ == "__main__":
+    main()

src/ragassistant/rag.py

@@ -0,0 +1,12 @@
+from .config import TOP_K
+from .generator import generate_answer
+from .retriever import Retriever
+
+
+class RAGPipeline:
+    def __init__(self):
+        self.retriever = Retriever()
+
+    def answer(self, question, top_k=TOP_K):
+        contexts = self.retriever.retrieve(question, top_k)
+        return generate_answer(question, contexts), contexts

src/ragassistant/retriever.py

@@ -0,0 +1,12 @@
+from .config import INDEX_PATH, META_PATH, TOP_K
+from .embeddings import embed
+from .vector_store import VectorStore
+
+
+class Retriever:
+    def __init__(self):
+        self.store = VectorStore.load(INDEX_PATH, META_PATH)
+
+    def retrieve(self, query, top_k=TOP_K):
+        query_vector = embed([query])[0]
+        return self.store.search(query_vector, top_k)

src/ragassistant/vector_store.py

@@ -0,0 +1,27 @@
+import json
+
+import numpy as np
+
+
+class VectorStore:
+    """In-memory cosine-similarity store backed by normalized embeddings."""
+
+    def __init__(self, vectors=None, chunks=None):
+        self.vectors = vectors
+        self.chunks = chunks or []
+
+    def search(self, query_vector, top_k):
+        scores = self.vectors @ query_vector
+        order = np.argsort(scores)[::-1][:top_k]
+        return [(self.chunks[i], float(scores[i])) for i in order]
+
+    def save(self, index_path, meta_path):
+        index_path.parent.mkdir(parents=True, exist_ok=True)
+        np.savez_compressed(index_path, vectors=self.vectors)
+        meta_path.write_text(json.dumps(self.chunks, indent=2))
+
+    @classmethod
+    def load(cls, index_path, meta_path):
+        vectors = np.load(index_path)["vectors"]
+        chunks = json.loads(meta_path.read_text())
+        return cls(vectors, chunks)

storage/chunks.json

@@ -0,0 +1,52 @@
+[
+  {
+    "id": "api.md#0",
+    "source": "api.md",
+    "text": "# Nimbus Notes \u2014 Developer API\nNimbus Notes exposes a REST API for automating notes and notebooks.\n## Authentication\nAll requests are sent to `https://api.nimbusnotes.com/v1` and authenticated with\nan API key passed as a Bearer token in the `Authorization` header. API keys are\ncreated in Settings under Developer.\n## Endpoints\n- `/notes` \u2014 create, read, update and delete notes.\n- `/notebooks` \u2014 manage notebooks.\n- `/search` \u2014 full-text search across the workspace.\nResponses are JSON and lists use cursor-based pagination.\n## Rate limits"
+  },
+  {
+    "id": "api.md#1",
+    "source": "api.md",
+    "text": "earch across the workspace.\nResponses are JSON and lists use cursor-based pagination.\n## Rate limits - Free plan: 60 requests per minute.\n- Pro and Team plans: 600 requests per minute.\n## Webhooks and SDKs\nWebhooks can notify your server of events such as `note.created` and\n`note.updated`. Official SDKs are available for Python and JavaScript."
+  },
+  {
+    "id": "faq.md#0",
+    "source": "faq.md",
+    "text": "# Nimbus Notes \u2014 Frequently Asked Questions\n## How do I export my notes?\nNotes can be exported from Settings > Export in Markdown, PDF or HTML format,\neither individually or per notebook.\n## Can I use Nimbus Notes offline?\nYes. The desktop and mobile apps cache your notes locally and synchronise\nautomatically the next time you are online. The web app requires a connection.\n## How do I cancel my subscription?\nGo to Settings > Billing > Cancel subscription. You keep access to paid features\nuntil the end of the current billing period, after which the account reverts to\nthe Free plan."
+  },
+  {
+    "id": "faq.md#1",
+    "source": "faq.md",
+    "text": "tures\nuntil the end of the current billing period, after which the account reverts to\nthe Free plan. ## How do I delete my account?\nSettings > Account > Delete account. Your data is permanently purged 30 days\nafter deletion.\n## Which languages are supported?\nThe interface is available in 12 languages, including English, Spanish, French,\nGerman and Japanese."
+  },
+  {
+    "id": "overview.md#0",
+    "source": "overview.md",
+    "text": "# Nimbus Notes \u2014 Product Overview\nNimbus Notes is a cloud-based note-taking application for individuals and teams.\nIt combines rich-text and Markdown editing with real-time collaboration, so\nseveral people can edit the same note at once.\n## Key features\n- Rich-text and Markdown editing with live preview.\n- Real-time collaboration and inline comments.\n- Offline mode on desktop and mobile, with automatic sync once back online.\n- Full-text search across all notebooks.\n- Organisation through notebooks, tags and nested pages.\n- Cross-platform clients for web, Windows, macOS, Linux, iOS and Android."
+  },
+  {
+    "id": "overview.md#1",
+    "source": "overview.md",
+    "text": "ks, tags and nested pages.\n- Cross-platform clients for web, Windows, macOS, Linux, iOS and Android. ## Availability\nNimbus Notes launched in 2019 and is available in 12 interface languages. The\nservice is offered as a hosted SaaS product; an on-premise deployment is\navailable on the Enterprise plan."
+  },
+  {
+    "id": "pricing.md#0",
+    "source": "pricing.md",
+    "text": "# Nimbus Notes \u2014 Pricing\nNimbus Notes offers four plans. All paid plans include a 14-day free trial of\nPro features, and annual billing saves roughly two months compared to monthly.\n## Free\n- Up to 3 notebooks and 1 GB of storage.\n- Core editing and search.\n- Community support only.\n## Pro \u2014 $8 per month (or $80 per year)\n- Unlimited notebooks and 50 GB of storage.\n- 30 days of version history.\n- Optional end-to-end encryption.\n- Priority email support.\n## Team \u2014 $15 per user per month"
+  },
+  {
+    "id": "pricing.md#1",
+    "source": "pricing.md",
+    "text": "istory.\n- Optional end-to-end encryption.\n- Priority email support.\n## Team \u2014 $15 per user per month - Everything in Pro, plus shared workspaces and admin controls.\n- 200 GB of storage per user.\n- Single sign-on (SSO).\n## Enterprise \u2014 custom pricing\n- SAML SSO, audit logs and a dedicated account manager.\n- Optional on-premise deployment.\nSubscriptions can be cancelled at any time from Settings; access continues until\nthe end of the current billing period."
+  },
+  {
+    "id": "security.md#0",
+    "source": "security.md",
+    "text": "# Nimbus Notes \u2014 Security\nSecurity is handled in line with industry best practice and audited by external\nparties.\n## Encryption\n- Data is encrypted in transit with TLS 1.3.\n- Data is encrypted at rest with AES-256.\n- Optional end-to-end encryption is available on Pro and higher plans.\n## Compliance and access control\n- SOC 2 Type II certified and GDPR compliant.\n- Two-factor authentication via TOTP authenticator apps.\n- Data is stored in data centres located in the EU and the US, selectable per\n  workspace.\n## Reliability"
+  },
+  {
+    "id": "security.md#1",
+    "source": "security.md",
+    "text": "a is stored in data centres located in the EU and the US, selectable per\n  workspace.\n## Reliability - Encrypted backups run daily and are retained for 30 days.\n- The platform is penetration-tested annually by an independent firm."
+  }
+]

storage/index.npz

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