Deploying Python RAG chatbot stack to Hugging Face

.dockerignore

@@ -0,0 +1,6 @@
+venv/
+.venv/
+__pycache__/
+*.pyc
+.git/
+.env

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install system dependencies needed for building certain Python packages
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of your application code
+COPY . .
+
+# Force the frontend to look at the local backend inside the same container
+ENV BACKEND_URL=http://127.0.0.1:8000
+
+# Give Windows permission to execute our startup script
+RUN chmod +x start.sh
+
+# Expose the precise port that Hugging Face expects
+EXPOSE 7860
+
+# Run our orchestration script to boot both apps together
+CMD ["./start.sh"]

data/faqs.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "faq_001",
+    "category": "Refunds",
+    "question": "What is the refund window for international transactions?",
+    "answer": "International cross-border transactions can be refunded within 14 business days. However, a 2.5% currency conversion processing fee is non-refundable."
+  },
+  {
+    "id": "faq_002",
+    "category": "Security",
+    "question": "How do I reset my multi-factor authentication (MFA)?",
+    "answer": "To reset your MFA, navigate to Settings > Security > Two-Factor Authentication. If you are locked out, contact compliance-ops@fintech.com with your Employee ID."
+  },
+  {
+    "id": "faq_003",
+    "category": "Security",
+    "question": "How do I reset my account password?",
+    "answer": "To reset your account password, click 'Forgot Password' on the login page, enter your corporate email, and follow the secure verification link sent to your inbox."
+  }
+]

frontend.py

@@ -0,0 +1,162 @@
+import streamlit as st
+import requests
+import uuid
+import json
+
+# 🌐 BACKEND CONFIGURATION
+BACKEND_URL = "http://backend:8000"
+
+st.set_page_config(
+    page_title="Enterprise Multi-Tenant FAQ Bot",
+    page_icon="🤖",
+    layout="wide"
+)
+
+# 🔑 SESSION STATE INITIALIZATION
+if "session_id" not in st.session_state:
+    # Generate a unique session token for this browser tab instance
+    st.session_state.session_id = str(uuid.uuid4())
+
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+if "active_sources" not in st.session_state:
+    st.session_state.active_sources = None
+
+
+# 🗂️ SIDEBAR: Workspace Management & File Uploads
+with st.sidebar:
+    st.title("⚙️ Workspace Panel")
+    
+    # Display the current isolated session ID
+    st.info(f"**Active Session Partition:**\n`{st.session_state.session_id}`")
+    st.caption("All document uploads and chat history are securely sandboxed inside this unique session token.")
+    
+    st.markdown("---")
+    
+    # File Uploader Widget
+    st.subheader("📥 Ingest Dynamic Context")
+    uploaded_file = st.file_uploader(
+        "Upload a .txt or .pdf file to train the bot for this session:", 
+        type=["txt", "pdf"]
+    )
+    
+    if uploaded_file is not None:
+        if st.button("🚀 Process & Vectorize Document", use_container_width=True):
+            with st.spinner("Streaming chunks to NVIDIA Embedding pipeline..."):
+                try:
+                    # Prepare multipart form file payload
+                    files = {"file": (uploaded_file.name, uploaded_file.getvalue(), uploaded_file.type)}
+                    headers = {"X-Session-ID": st.session_state.session_id}
+                    
+                    # Call FastAPI dynamic ingestion endpoint
+                    response = requests.post(
+                        f"{BACKEND_URL}/api/v1/upload", 
+                        files=files, 
+                        headers=headers
+                    )
+                    
+                    if response.status_code == 200:
+                        st.success(f"✅ Context parsed! {uploaded_file.name} is now live in your workspace.")
+                    else:
+                        error_detail = response.json().get('detail', 'Unknown error')
+                        st.error(f"❌ Ingestion Failed: {error_detail}")
+                except Exception as e:
+                    st.error(f"❌ Connection error: {str(e)}")
+
+    st.markdown("---")
+    
+    # Reset/Clear Options
+    st.subheader("🧹 Workspace Cleanup")
+    if st.button("Clear Chat Window State", use_container_width=True):
+        st.session_state.messages = []
+        st.session_state.active_sources = None
+        st.rerun()
+
+    if st.button("🗑️ Wipe Global Vector DB (Admin)", use_container_width=True, type="secondary"):
+        with st.spinner("Dropping collection..."):
+            try:
+                res = requests.post(f"{BACKEND_URL}/api/v1/clear")
+                if res.status_code == 200:
+                    st.warning("💥 Global Vector Store wiped entirely.")
+                else:
+                    st.error("Failed to clear DB.")
+            except Exception as e:
+                st.error(f"Error: {e}")
+
+
+# 💬 MAIN INTERFACE: Streaming Chat Engine
+st.title("🤖 Enterprise Multi-Tenant FAQ Bot")
+st.markdown("Ask general questions, standard FAQs, or query details out of your uploaded dynamic documents.")
+
+# 📜 Render Existing Chat Log
+for message in st.session_state.messages:
+    with st.chat_message(message["role"]):
+        st.markdown(message["content"])
+
+# ⚡ Live User Interaction Loop
+if prompt := st.chat_input("Type your message here..."):
+    # Display user input inside the panel
+    with st.chat_message("user"):
+        st.markdown(prompt)
+    
+    # Store message in state history
+    st.session_state.messages.append({"role": "user", "content": prompt})
+    
+    # Build a clean conversion format payload for history matching
+    formatted_history = [
+        {"role": msg["role"], "role": "assistant" if msg["role"] == "assistant" else "user", "content": msg["content"]}
+        for msg in st.session_state.messages[:-1]
+    ]
+
+    # Setup the JSON request body
+    chat_payload = {
+        "question": prompt,
+        "history": formatted_history,
+        "session_id": st.session_state.session_id
+    }
+
+    # Stream the incoming chunks from FastAPI
+    with st.chat_message("assistant"):
+        response_placeholder = st.empty()
+        full_response = ""
+        sources_found = []
+
+        try:
+            # Open persistent stream connection to FastAPI router
+            with requests.post(f"{BACKEND_URL}/api/v1/chat", json=chat_payload, stream=True) as response:
+                if response.status_code == 500:
+                    st.error("The streaming backend pipeline returned a fatal exception.")
+                
+                for line in response.iter_lines():
+                    if line:
+                        # Decode raw byte lines from incoming NDJSON data stream
+                        decoded_line = line.decode('utf-8')
+                        chunk_data = json.loads(decoded_line)
+                        
+                        # 📦 Handle Retrieved Data Sources
+                        if chunk_data.get("type") == "sources":
+                            sources_found = chunk_data.get("content", [])
+                        
+                        # ⚡ Handle Live Text Tokens
+                        elif chunk_data.get("type") == "token":
+                            full_response += chunk_data.get("content", "")
+                            # Live redraw token progression
+                            response_placeholder.markdown(full_response + "▌")
+            
+            # Lock final markdown block state rendering without cursor character
+            response_placeholder.markdown(full_response)
+            
+            # Render Source Documents in an Accordion if present
+            if sources_found:
+                with st.expander("📚 View Retrieved Reference Sources"):
+                    for idx, src in enumerate(sources_found):
+                        src_name = src.get("metadata", {}).get("source", "Global Base FAQ")
+                        st.markdown(f"**Source [{idx+1}]:** `{src_name}`")
+                        st.caption(src.get("content", ""))
+            
+            # Save assistant milestone string state safely 
+            st.session_state.messages.append({"role": "assistant", "content": full_response})
+            
+        except Exception as conn_err:
+            st.error(f"Streaming error or dropped server connection: {str(conn_err)}")

requirements.txt

@@ -0,0 +1,12 @@
+fastapi>=0.115.0
+uvicorn>=0.31.0
+streamlit>=1.35.0
+python-multipart>=0.0.9
+langchain>=0.3.0
+langchain-openai>=0.2.0
+langchain-nvidia-ai-endpoints>=0.1.0
+chromadb>=0.5.10
+pydantic>=2.9.0
+python-dotenv>=1.0.1
+pypdf>=3.20.0
+langchain-community>=0.3.0

src/database.py

@@ -0,0 +1,144 @@
+import json
+import os
+from openai import OpenAI
+from langchain_core.documents import Document
+from langchain_core.embeddings import Embeddings
+from langchain_community.vectorstores import Chroma
+from langchain_text_splitters import RecursiveCharacterTextSplitter  
+
+class NvidiaCompatibleEmbeddings(Embeddings):
+    """
+    Custom embedding processor that bypasses LangChain's internal tokenization middleware
+    to pass raw text strings and asymmetric type configurations directly to NVIDIA NIM.
+    """
+    def __init__(self, model: str, api_key: str, base_url: str):
+        self.client = OpenAI(api_key=api_key, base_url=base_url)
+        self.model = model
+
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        """Embeds a list of documentation chunks using the 'passage' type."""
+        response = self.client.embeddings.create(
+            input=texts,
+            model=self.model,
+            extra_body={"input_type": "passage"}
+        )
+        return [item.embedding for item in response.data]
+
+    def embed_query(self, text: str) -> list[float]:
+        """Embeds a live user search query using the 'query' type."""
+        response = self.client.embeddings.create(
+            input=[text],
+            model=self.model,
+            extra_body={"input_type": "query"}
+        )
+        return response.data[0].embedding
+
+
+class VectorDBManager:
+    def __init__(self, persist_directory: str = "./chroma_db"):
+        self.embeddings = NvidiaCompatibleEmbeddings(
+            model=os.getenv("EMBEDDING_MODEL", "nvidia/llama-nemotron-embed-1b-v2"),
+            api_key=os.getenv("NVIDIA_API_KEY"),
+            base_url=os.getenv("NVIDIA_BASE_URL")
+        )
+        self.persist_directory = persist_directory
+        self.vector_store = None
+
+    def _ensure_vector_store(self):
+        """🛡️ Internal safeguard to ensure the Chroma instance is actively loaded in memory."""
+        if self.vector_store is None:
+            self.vector_store = Chroma(
+                persist_directory=self.persist_directory,
+                embedding_function=self.embeddings
+            )
+
+    def initialize_db(self, faq_filepath: str):
+        """
+        Loads incoming JSON FAQs, formats them into searchable LangChain Documents,
+        and saves them locally via ChromaDB stamped with a 'global' scope.
+        """
+        if not os.path.exists(faq_filepath):
+            raise FileNotFoundError(f"Could not find FAQ data resource file at: {faq_filepath}")
+
+        with open(faq_filepath, 'r') as f:
+            faq_data = json.load(f)
+        
+        documents = []
+        for item in faq_data:
+            page_content = f"Question: {item['question']}\nAnswer: {item['answer']}"
+            
+            # 🔑 Added session_id: "global" so these base FAQs are accessible to all users
+            metadata = {
+                "category": item["category"], 
+                "faq_id": item["id"],
+                "session_id": "global"
+            }
+            documents.append(Document(page_content=page_content, metadata=metadata))
+        
+        self.vector_store = Chroma.from_documents(
+            documents=documents,
+            embedding=self.embeddings,
+            persist_directory=self.persist_directory
+        )
+        print(f"🚀 Vector DB successfully initialized with {len(documents)} FAQs via NVIDIA Embeddings.")
+
+    def get_retriever(self, session_id: str = "default_session"):
+        """
+        Loads the localized database and converts it into a queryable retriever layer 
+        strictly filtered by the active session identity.
+        """
+        self._ensure_vector_store()
+        
+        # 🔑 MULTI-TENANCY FILTER: Look for global baseline data OR this specific user's uploads
+        meta_filter = {
+            "$or": [
+                {"session_id": "global"},
+                {"session_id": session_id}
+            ]
+        }
+        
+        return self.vector_store.as_retriever(
+            search_kwargs={
+                "k": 2,
+                "filter": meta_filter
+            }
+        )
+
+    def add_text_to_db(self, text: str, filename: str, session_id: str = "default_session"):
+        """
+        📥 Chunks raw text from dynamic frontend uploads, computes NVIDIA embeddings,
+        and appends them directly into the live database marked with the owner's session ID.
+        """
+        self._ensure_vector_store()
+
+        # 1. Break the document down into semantic pieces
+        text_splitter = RecursiveCharacterTextSplitter(chunk_size=600, chunk_overlap=60)
+        chunks = text_splitter.split_text(text)
+
+        # 2. Package raw strings into formal LangChain Document structures
+        documents = []
+        for idx, chunk in enumerate(chunks):
+            # 🔑 Stamping chunk dictionary metadata with the active session tracking ID
+            metadata = {
+                "source": filename,
+                "category": "Dynamic Upload",
+                "chunk_index": idx,
+                "session_id": session_id
+            }
+            documents.append(Document(page_content=chunk, metadata=metadata))
+
+        # 3. Stream the newly generated embeddings straight into the persistent store
+        self.vector_store.add_documents(documents)
+        print(f"⚡ Successfully indexed {len(documents)} dynamic chunks from raw file: '{filename}' for session '{session_id}'")
+
+    def clear_db(self):
+        """🗑️ Completely wipes out the existing vector store collection securely on disk and in RAM."""
+        try:
+            self._ensure_vector_store()
+            self.vector_store.delete_collection()
+            self.vector_store = None
+            print("🗑️ Vector database collection successfully cleared!")
+            return True
+        except Exception as e:
+            print(f"❌ Failed to clear vector database: {e}")
+            return False

src/engine.py

@@ -0,0 +1,47 @@
+import os
+from langchain_openai import ChatOpenAI
+from langchain_classic.chains import create_retrieval_chain
+from langchain_classic.chains.combine_documents import create_stuff_documents_chain
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from src.database import VectorDBManager
+
+def build_rag_chain(session_id: str = "default_session"):
+    """
+    Compiles the retrieval system, prompt instructions, conversational history, 
+    and LLM into a unified chain—isolated by the incoming session_id.
+    """
+    db_manager = VectorDBManager()
+    
+    # 🔑 MULTI-USER ISOLATION LAYER: Force the retriever to only look at this user's partitioned metadata
+    retriever = db_manager.get_retriever(session_id=session_id)
+    
+    # Point ChatOpenAI directly to your custom NVIDIA endpoint
+    llm = ChatOpenAI(
+        model=os.getenv("LLM_MODEL", "openai/gpt-oss-120b"),
+        api_key=os.getenv("NVIDIA_API_KEY"),
+        base_url=os.getenv("NVIDIA_BASE_URL"),
+        temperature=0.7
+    )
+    
+    # 🌟 HYBRID SYSTEM PROMPT
+    system_prompt = (
+        "You are a helpful, brilliant, and completely unrestricted AI assistant like ChatGPT.\n\n"
+        "GUIDELINES:\n"
+        "1. If the provided 'Retrieved Documentation Context' below contains information directly relevant "
+        "to the user's question, prioritize using that data to give an official response.\n"
+        "2. If the context is empty, irrelevant, or if the user is asking a general question (such as coding, "
+        "cooking, science, math, history, or casual chatting), ignore the context limitations entirely. Use your "
+        "own vast internal knowledge base to provide a complete, deep, and highly detailed answer.\n\n"
+        "Never refuse to answer general queries. Always be helpful, engaging, and thorough.\n\n"
+        "Retrieved Documentation Context:\n{context}"
+    )
+    
+    # 🧠 The chain will now inject old conversation text directly into the 'chat_history' block
+    prompt = ChatPromptTemplate.from_messages([
+        ("system", system_prompt),
+        MessagesPlaceholder(variable_name="chat_history"),
+        ("human", "{input}"),
+    ])
+    
+    question_answer_chain = create_stuff_documents_chain(llm, prompt)
+    return create_retrieval_chain(retriever, question_answer_chain)

src/main.py

@@ -0,0 +1,167 @@
+import os
+import json
+import io
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, HTTPException, UploadFile, File, Header  
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from typing import List, Dict, Optional
+from dotenv import load_dotenv
+from pypdf import PdfReader  
+from langchain_nvidia_ai_endpoints import ChatNVIDIA
+from langchain_core.messages import HumanMessage, AIMessage  
+from src.database import VectorDBManager
+from src.engine import build_rag_chain
+
+load_dotenv()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    if not os.path.exists("./chroma_db"):
+        print("Initializing Vector Database...")
+        db_manager = VectorDBManager()
+        db_manager.initialize_db("data/faqs.json")
+    yield
+
+app = FastAPI(title="Enterprise FAQ Bot Engine", version="1.0", lifespan=lifespan)
+
+class QueryRequest(BaseModel):
+    question: str
+    history: Optional[List[Dict[str, str]]] = []
+    session_id: Optional[str] = "default_session"  
+
+
+# 📂 DYNAMIC KNOWLEDGE INGESTION ENDPOINT
+@app.post("/api/v1/upload")
+async def upload_file_endpoint(
+    file: UploadFile = File(...), 
+    x_session_id: Optional[str] = Header(None)  
+):
+    """
+    Accepts standard multipart form file uploads (.txt or .pdf), extracts raw text 
+    contents in-memory, and passes them along with a unique session ID.
+    """
+    try:
+        contents = await file.read()
+        filename = file.filename.lower()
+        text_data = ""
+
+        # 📄 Process Plain Text Files
+        if filename.endswith(".txt"):
+            text_data = contents.decode("utf-8")
+
+        # 📕 Process PDF Files In-Memory
+        elif filename.endswith(".pdf"):
+            pdf_stream = io.BytesIO(contents)
+            pdf_reader = PdfReader(pdf_stream)
+            
+            extracted_pages = []
+            for page in pdf_reader.pages:
+                page_text = page.extract_text()
+                if page_text:
+                    extracted_pages.append(page_text)
+            
+            text_data = "\n".join(extracted_pages)
+            
+            if not text_data.strip():
+                raise HTTPException(
+                    status_code=400, 
+                    detail="The uploaded PDF appears to be empty or contains only non-scanned imagery (OCR required)."
+                )
+        else:
+            raise HTTPException(
+                status_code=400, 
+                detail="Unsupported file format. Please upload a valid plain text (.txt) or PDF (.pdf) document."
+            )
+        
+        db_manager = VectorDBManager()
+        target_session = x_session_id or "default_session"
+        db_manager.add_text_to_db(text_data, filename=file.filename, session_id=target_session)
+        
+        return {
+            "status": "success", 
+            "message": f"Successfully vectorized and stored {file.filename} under session context!"
+        }
+        
+    except UnicodeDecodeError:
+        raise HTTPException(
+            status_code=400, 
+            detail="File encoding error: Please ensure your text file is saved with valid UTF-8 encoding."
+        )
+    except HTTPException as http_ex:
+        raise http_ex
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Ingestion pipeline failed: {str(e)}")
+
+
+# 🗑️ ADMIN DATABASE RESET ENDPOINT
+@app.post("/api/v1/clear")
+async def clear_database_endpoint():
+    """
+    Triggers a collection wipe on the vector database.
+    """
+    db_manager = VectorDBManager()
+    if db_manager.clear_db():
+        return {"status": "success", "message": "Vector database cleared successfully."}
+    else:
+        raise HTTPException(status_code=500, detail="Failed to drop vector database collection.")
+
+
+# ⚡ LIVE STREAMING CHAT ROUTER
+@app.post("/api/v1/chat")
+async def chat_endpoint(payload: QueryRequest):
+    try:
+        search_query = payload.question
+        chat_history = []
+        
+        # Format the conversational history state if it exists
+        if payload.history and len(payload.history) > 0:
+            for msg in payload.history:
+                if msg["role"] == "user":
+                    chat_history.append(HumanMessage(content=msg["content"]))
+                elif msg["role"] == "assistant":
+                    chat_history.append(AIMessage(content=msg["content"]))
+            
+            # ✨ RESTORED & ALIGNED MEMORY CONTEXT BLOCK
+            try:
+                rephrase_llm = ChatNVIDIA(model="meta/llama-3.1-70b-instruct")
+                history_context = ""
+                for msg in payload.history:
+                    role = "User" if msg["role"] == "user" else "Assistant"
+                    history_context += f"{role}: {msg['content']}\n"
+                
+                condense_prompt = (
+                    f"Given the following chat history and a follow-up question, "
+                    f"rephrase the follow-up question into a standalone query.\n\n"
+                    f"Chat History:\n{history_context}\n"
+                    f"Follow-up Question: {payload.question}\n\n"
+                    f"Standalone Query:"
+                )
+                
+                # Execute standard LangChain invocation
+                llm_response = rephrase_llm.invoke(condense_prompt)
+                search_query = llm_response.content.strip()
+                
+            except Exception as context_error:
+                print(f"⚠️ Memory rephrasing failed: {context_error}")
+                search_query = payload.question
+
+        # Build execution pipeline tied strictly to this user's workspace partitions
+        rag_chain = build_rag_chain(session_id=payload.session_id)
+
+        async def event_generator():
+            async for chunk in rag_chain.astream({"input": search_query, "chat_history": chat_history}):
+                if "context" in chunk:
+                    sources_payload = [
+                        {"content": doc.page_content, "metadata": doc.metadata}
+                        for doc in chunk["context"]
+                    ]
+                    yield json.dumps({"type": "sources", "content": sources_payload}) + "\n"
+                
+                if "answer" in chunk:
+                    yield json.dumps({"type": "token", "content": chunk["answer"]}) + "\n"
+
+        return StreamingResponse(event_generator(), media_type="application/x-ndjson")
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Chat streaming pipeline failed: {str(e)}")

start.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# 1. Start the FastAPI backend in the background on port 8000
+echo "Starting FastAPI backend..."
+uvicorn src.main:app --host 0.0.0.0 --port 8000 &
+
+# 2. Wait a brief moment for the backend to initialize
+sleep 3
+
+# 3. Start the Streamlit frontend in the foreground on Hugging Face's required port (7860)
+echo "Starting Streamlit frontend..."
+streamlit run frontend.py --server.port 7860 --server.address 0.0.0.0 --server.enableCORS=false --server.enableXsrfProtection=false