--- 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](https://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](https://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: ```bash 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: ```text GROQ_API_KEY=gsk_your_private_api_key_here SERPAPI_API_KEY=your_serpapi_key_here ``` - `GROQ_API_KEY` → https://console.groq.com/keys - `SERPAPI_API_KEY` → https://serpapi.com/manage-api-key (free tier: 100 searches/month). Without it, PDF RAG still works but the live-web-search path returns a disabled notice. > ⚠️ **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: ```bash 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](https://huggingface.co/spaces/jericrealubit/ragchatbot), embedded at [waai.au/chat](https://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! * **Name:** Jeric Realubit * **Role:** Full-Stack Web Developer & AI Solutions Engineer * **Location:** Perth, Western Australia (Open to local, hybrid, and global remote opportunities) * **LinkedIn:** [linkedin.com/in/jericrealubit](https://www.google.com/search?q=https://linkedin.com/in/jericrealubit) * **Mobile:** [+61 491 098 073](https://www.google.com/search?q=tel:%2B61491098073) * **GitHub:** [github.com/jericrealubit](https://www.google.com/search?q=https://github.com/jericrealubit)