Hugging Face's logo

Spaces:
jericrealubit
/
ragchatbot
Sleeping

App Files Community
ragchatbot / README.md
github-actions[bot]
Deploy 9ac89cc from GitHub main
4b6ac7a
preview code
|
Raw History Blame Contribute Delete
7.58 kB
metadata 
title: Ragchatbot
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

Local Hybrid RAG & Live Search Enterprise Chatbot

A production-ready Retrieval-Augmented Generation (RAG) application built with Chainlit and LangChain. This chatbot features a dynamic dual-routing architecture: it enables secure, contextual conversations over local PDF documents using localized semantic vector searches, and seamlessly falls back to real-time internet search when no document is active.

🚀 Live Application

Try the live system deployed on my domain here: waai.au/chat

image

🏗️ Core Architecture Flow

The application handles incoming user intents and document processing through three processing paths:

  1. Site Facts Path: With no document active, a question is first answered from waai.au/llms.txt — WA AI Digital's services, prices, case studies and FAQs, generated by the website from the same data its pages are built from (fetched once and cached for six hours; override with WAAI_FACTS_URL). If those facts don't cover the question, the model says so with a sentinel and the question falls through to live search.
  2. Document RAG Path: When a PDF is supplied, raw binary pages are extracted, cleaned, and segmented into 1,000-character semantic chunks. These blocks are vectorized using a local transformer model (all-MiniLM-L6-v2) and cached in an in-memory FAISS vector index for ultra-low latency similarity parsing ($k=3$).
  3. Live Web Search Path: If no document is active in the user session memory, the application executes live Google search queries via SerpAPI. Real-time organic result snippets are injected straight into the LLM context layer.

All operations feature optimized streaming tokens over high-throughput Groq Cloud API frameworks (openai/gpt-oss-20b via ChatGroq) with a rolling conversational turn tracker preserving contextual continuity.

🛠️ Explaining the Deep Stack (Imported Tools)

To maintain transparent, professional documentation, here is exactly what every imported tool handles inside your chatpdf.py execution layer:

Core Python Modules

  • os: Handles system operational environmental calls, pulling down host credentials safely without exposing private parameters inside the repository.
  • re: Python's native Regular Expressions engine. It purges noisy extraction metadata (like layout page markings and image artifacts) from the text buffer prior to embedding.
  • logging: Silences non-critical background runtime diagnostic logging from matrix math subsystems like FAISS to keep your application output clean.

Chainlit (Asynchronous Core Framework)

  • chainlit (cl): An asynchronous python automation library for launching interactive chat interfaces. It natively manages user socket states, pushes token text blocks smoothly, and parses client-side interaction events.

LangChain Expression Language (LCEL) & Utilities

  • ChatGroq: A communication model layer mapped directly to Groq Cloud's ultra-low-latency endpoint infrastructure (openai/gpt-oss-20b).
  • PromptTemplate: Structures input formatting rules. Enforces behavioral bounds, compiling your live search strings or vector context arrays cleanly alongside active history logs before execution.
  • StrOutputParser: Extracts text strings from raw LLM object responses, filtering out performance metrics or structural tokens for clean UI presentation.
  • SerpAPIWrapper: Live Google search connector that acts as the real-time internet engine when the app runs without an active document database.

Data Ingestion & Mathematical Vectors

  • RecursiveCharacterTextSplitter: Intelligently splices long document texts by natural word bounds and paragraph breaks using a 1,000-character chunk boundary with a 200-character rolling overlap.
  • HuggingFaceEmbeddings: Manages the underlying sentence-transformers engine to convert readable text strings into 384-dimensional semantic matrix arrays.
  • FAISS: Facebook AI Similarity Search. An optimized structural calculation engine running locally in system memory to perform vector cosine similarity calculations.
  • PdfReader: An implementation from PyPDF2 that reads binary PDF files into raw string buffers.

🚀 Getting Started

1. Environmental Dependencies

Python 3.11 is recommended (matches the Dockerfile). Install all package dependencies from the pinned requirements file:

python -m venv .venv
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
# bash:               source .venv/bin/activate
pip install -r requirements.txt

2. Guarding Secrets (.env)

Copy .env.example to .env and fill in both keys:

GROQ_API_KEY=gsk_your_private_api_key_here
SERPAPI_API_KEY=your_serpapi_key_here

⚠️ Security Policy Reminder: Ensure your project's .gitignore contains a line explicitly omitting .env configurations from Git tracking layers.

🏃 Execution Workflow

Launch the live application streaming engine by target-pointing to your python solution structure:

chainlit run solutions/langchain/chatpdf.py --host 0.0.0.0 --port 8080

Once initialized, open the forwarded port interface link provided in your console logs. You can interact directly with the web search functionality, or load up an invoice, spreadsheet, or documentation guide using the attachment bar to lock down localized RAG operations.

🚢 Deployment

The live app is the Hugging Face Space jericrealubit/ragchatbot, embedded at waai.au/chat. .github/workflows/sync-to-hf.yml pushes a snapshot of main to the Space on every merge (a single commit, not the history — early commits hold PDFs the Hub would reject), and the Space rebuilds from the Dockerfile — so GitHub main is what's live; never edit the Space directly, or the next merge overwrites it. The YAML block at the top of this README is the Space's configuration.

  • The workflow needs an HF_TOKEN repository secret: a Hugging Face write token with access to the Space.
  • The app's keys (GROQ_API_KEY, SERPAPI_API_KEY) are Space secrets, set in the Space's settings, not in this repo.

📬 Contact & Collaboration

Are you an engineering hiring manager looking for a versatile Full-Stack Web Developer with practical AI implementation skills, or a business owner looking to deploy optimized, zero-overhead automated intelligence tools onto your internal systems? Let's connect!