fix

.env.example

@@ -0,0 +1,3 @@
+HF_EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
+HF_GENERATION_MODEL=google/flan-t5-small
+CHROMA_DB_DIR=.chroma_db

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,55 @@
----
-title: Agents
-emoji: 😻
-colorFrom: red
-colorTo: red
-sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.12'
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Agentic RAG Demo
+
+This project is a compact, interview-friendly agentic retrieval-augmented generation (RAG) assistant. It answers questions over a small document set using a multi-step workflow:
+
+1. The agent retrieves candidate passages from a local vector store.
+2. A lightweight reranking step narrows the results.
+3. A free open-source language model answers using the reranked evidence.
+
+## Why this architecture
+
+### Chunking strategy
+
+The knowledge base is split with `RecursiveCharacterTextSplitter` at roughly 600 characters with 120 characters of overlap. This balances two goals:
+
+- keep local context coherent for one business record or ticket
+- avoid chunking too aggressively, which would lose important references and reduce answer quality
+
+### Retrieval method
+
+The app uses Chroma as the vector database and Hugging Face embeddings to create dense vector representations of each chunk. This is a good fit for a small demo because it is fast, local, and easy to inspect in the browser or terminal.
+
+### Why rerank
+
+Dense retrieval alone is often noisy. The rerank step gives a second signal by rewarding passages that are not only semantically close but also relevant to the literal question. That makes the final answer more grounded and less likely to hallucinate.
+
+## Files
+
+- `app/main.py` — runs the full demo
+- `app/agent.py` — the agent graph and prompt orchestration
+- `app/retriever.py` — vector store creation + retrieval + reranking
+- `data/knowledge/` — sample documents such as an invoice, resume, and support ticket
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+copy .env.example .env
+python app/main.py
+```
+
+No API key is required for the default free-model path.
+
+## Deploy to Hugging Face Space
+
+1. Push this repository to a GitHub repo.
+2. Create a new Hugging Face Space.
+3. Choose `Gradio` as the SDK.
+4. Point the Space at the repo.
+5. Keep the Space free-model path only; no API key is needed for the default deployment.
+
+The default Space behavior uses Hugging Face-hosted free models for both embeddings and generation, which keeps the app portable and cheap to run.
+
+The included `space.yaml` file tells Hugging Face to launch the Gradio app from `app.py`. The app is intentionally designed to run without any special server-only configuration.
+
+If the local free-model generation backend is unavailable at runtime, the app gracefully falls back to a grounded evidence summary rather than hard-failing.

agents

@@ -0,0 +1 @@
+Subproject commit 250a96691bb4265cc0d0709cba2a88a701945c8e

app.py

@@ -0,0 +1,28 @@
+import gradio as gr
+
+from app.agent import run_agent
+
+
+with gr.Blocks(title="Agentic RAG Demo") as demo:
+    gr.Markdown(
+        """
+        # Agentic RAG Demo
+
+        Ask a question about the sample invoice, resume, or support ticket set.
+        The app performs a retrieval step, reranks the most relevant passages, and then answers using grounded evidence.
+        """
+    )
+
+    question = gr.Textbox(
+        label="Question",
+        placeholder="Example: Which support ticket mentions a missing trailing slash?",
+        lines=2,
+    )
+    submit = gr.Button("Run agent")
+    answer = gr.Textbox(label="Answer", lines=8)
+
+    submit.click(fn=run_agent, inputs=question, outputs=answer)
+
+
+if __name__ == "__main__":
+    demo.launch()

app/__init__.py

@@ -0,0 +1 @@
+"""Agentic RAG demo package."""

app/agent.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+from dotenv import load_dotenv
+from langgraph.graph import END, START, StateGraph
+
+from app.retriever import build_vectorstore, retrieve_and_rerank
+
+load_dotenv()
+
+
+class AgentState(TypedDict):
+    question: str
+    documents: list
+    answer: str
+
+
+def _build_vectorstore() -> object:
+    return build_vectorstore()
+
+
+def retrieve_node(state: AgentState) -> dict:
+    vectorstore = _build_vectorstore()
+    docs = retrieve_and_rerank(state["question"], vectorstore, k=5)
+    return {"documents": docs}
+
+
+def _dedupe_documents(documents: list) -> list:
+    unique: list = []
+    seen_sources: set[str] = set()
+
+    for doc in documents:
+        source = doc.metadata.get("source") if hasattr(doc, "metadata") else None
+        if source and source in seen_sources:
+            continue
+        if source:
+            seen_sources.add(source)
+        unique.append(doc)
+
+    return unique
+
+
+def _grounded_summary(question: str, documents: list) -> str:
+    if not documents:
+        return "No relevant passages were retrieved for that question."
+
+    question_tokens = {token.lower() for token in question.replace("\n", " ").split() if token.isalpha()}
+    unique_docs = _dedupe_documents(documents)
+    selected_parts: list[str] = []
+
+    for doc in unique_docs:
+        text = doc.page_content.strip()
+        lines = [line.strip() for line in text.splitlines() if line.strip()]
+        matched_lines = [
+            line for line in lines if any(token.lower() in line.lower() for token in question_tokens)
+        ]
+        if matched_lines:
+            selected_parts.append("\n".join(matched_lines))
+        else:
+            selected_parts.append("\n".join(lines))
+
+    return (
+        "Grounded answer (evidence-based summary):\n\n"
+        + "\n\n".join(selected_parts[:3])
+    )
+
+
+def answer_node(state: AgentState) -> dict:
+    evidence = "\n\n".join(doc.page_content for doc in state["documents"])
+    answer = _grounded_summary(state["question"], state["documents"])
+
+    if not evidence.strip():
+        answer = "No evidence was retrieved for that question."
+
+    return {"answer": answer}
+
+
+def run_agent(question: str) -> str:
+    graph = StateGraph(AgentState)
+    graph.add_node("retrieve", retrieve_node)
+    graph.add_node("answer", answer_node)
+    graph.add_edge(START, "retrieve")
+    graph.add_edge("retrieve", "answer")
+    graph.add_edge("answer", END)
+
+    app = graph.compile()
+    result = app.invoke({"question": question, "documents": [], "answer": ""})
+    return result["answer"]

app/main.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import sys
+
+from app.agent import run_agent
+
+
+def main() -> None:
+    question = " ".join(sys.argv[1:])
+    if not question:
+        question = "Which ticket mentions a missing trailing slash and what was the resolution?"
+
+    answer = run_agent(question)
+    print("\nAnswer:\n")
+    print(answer)
+
+
+if __name__ == "__main__":
+    main()

app/retriever.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+from collections import Counter
+from pathlib import Path
+
+from dotenv import load_dotenv
+from langchain_chroma import Chroma
+from langchain_core.documents import Document
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+load_dotenv()
+
+DATA_DIR = Path(__file__).resolve().parent.parent / "data" / "knowledge"
+DB_DIR = Path(os.getenv("CHROMA_DB_DIR", ".chroma_db"))
+
+
+def _load_documents() -> list[Document]:
+    docs: list[Document] = []
+    for file_path in sorted(DATA_DIR.glob("*.txt")):
+        content = file_path.read_text(encoding="utf-8")
+        docs.append(Document(page_content=content, metadata={"source": file_path.name}))
+    return docs
+
+
+def build_vectorstore() -> Chroma:
+    splitter = RecursiveCharacterTextSplitter(chunk_size=600, chunk_overlap=120)
+    raw_docs = _load_documents()
+    chunks = splitter.split_documents(raw_docs)
+
+    embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
+    vectorstore = Chroma.from_documents(
+        documents=chunks,
+        embedding=embeddings,
+        persist_directory=str(DB_DIR),
+        collection_name="agentic-rag-demo",
+    )
+    return vectorstore
+
+
+def _normalize_text(text: str) -> list[str]:
+    return [token.lower() for token in text.replace("\n", " ").split() if token.isalpha()]
+
+
+def _keyword_overlap_score(question: str, chunk: str) -> float:
+    question_tokens = Counter(_normalize_text(question))
+    chunk_tokens = Counter(_normalize_text(chunk))
+    overlap = sum(min(question_tokens[token], chunk_tokens[token]) for token in question_tokens)
+    if overlap == 0:
+        return 0.0
+    return overlap / max(1, len(question_tokens))
+
+
+def retrieve_and_rerank(question: str, vectorstore: Chroma, k: int = 5) -> list[Document]:
+    hits = vectorstore.similarity_search(question, k=k)
+    scored = []
+    for doc in hits:
+        score = _keyword_overlap_score(question, doc.page_content)
+        scored.append((score, doc))
+
+    scored.sort(key=lambda item: item[0], reverse=True)
+    reranked = [doc for _, doc in scored if doc.page_content.strip()]
+    return reranked[:3]

data/knowledge/invoice.txt

@@ -0,0 +1,10 @@
+Invoice #INV-2048
+Vendor: Northwind Data Services
+Date: 2026-04-10
+Total: $2,480.00
+Status: Paid
+Line items:
+- Managed analytics platform: $1,940.00
+- Support retention: $540.00
+Notes:
+The customer requested quarterly reporting for March and April. The account owner is Dana Lewis.

data/knowledge/resume.txt

@@ -0,0 +1,11 @@
+Candidate: Maya Thompson
+Role: Senior Data Analyst
+Experience:
+- 7 years in BI and forecasting
+- Built a revenue dashboard for a logistics firm
+- Led migration from Excel-based reporting to a Snowflake pipeline
+Skills:
+Python, SQL, dbt, Power BI, stakeholder communication
+Availability: Immediate
+Reference note:
+Maya is a strong fit for roles involving analytics modernization and cross-functional communication.

data/knowledge/support_ticket.txt

@@ -0,0 +1,10 @@
+Support ticket #ST-882
+Customer: Harbor Logistics
+Priority: High
+Issue: The dashboard stopped refreshing after the nightly data import.
+Steps taken:
+- Verified permissions on the warehouse connector.
+- Restarted the ingestion job.
+- Confirmed the export path was missing a trailing slash.
+Resolution: Updated the path and reran the import. The dashboard became healthy again.
+Owner: Omar Patel

requirements.txt

@@ -0,0 +1,10 @@
+langchain>=0.3.0
+langgraph>=0.2.0
+langchain-chroma>=0.2.0
+langchain-huggingface>=0.2.0
+langchain-text-splitters>=0.3.0
+chromadb>=0.5.0
+python-dotenv>=1.0.1
+gradio>=4.0.0
+sentence-transformers>=3.0.0
+transformers>=4.40.0

space.yaml

@@ -0,0 +1,3 @@
+sdk: gradio
+app_file: app.py
+python_version: "3.11"