How worldbank/whatsapp-rag-example works
Project type and purpose
• This is a backend-centric RAG (Retrieval-Augmented Generation) Chatbot application.
• Users interact via WhatsApp (Twilio WhatsApp Messaging API).
• Under the hood it uses FastAPI to expose endpoints, LangChain to build LLM chains, a vector store for document retrieval, and PostgreSQL for conversation logging.
File structure
• Top-level scripts:
• main.py – FastAPI application and Twilio webhook handler
• basic_chain.py, rag_chain.py, ensemble.py – LangChain chains / prompt logic
• local_loader.py, remote_loader.py – document ingestion pipelines
• splitter.py – document chunking
• vector_store.py – embedding and vector-DB management
• memory.py – session/memory management
• models.py – SQLAlchemy ORM definitions for Postgres logging
• utils.py – shared helpers
• Folders:
• data/ – WHO PDF documents used as knowledge base
• examples/ – sample files for testing
• Config and dependencies: requirements.txt, .env (credentials), .gitignore.
README for additional insights
• External services: OpenAI API or HuggingFace LLMs; Twilio WhatsApp; PostgreSQL; Ngrok for local tunneling.
• Workflow steps: document loading → splitting → vector DB creation → memory setup → LLM chain creation → API exposure → Twilio integration.
Main components and interactions
a. Components
• WhatsApp User (Client)
• Twilio WhatsApp API (Webhook + Messaging service)
• FastAPI Server (main.py)
• Document Ingestion Pipeline
– Loader modules (local_loader.py, remote_loader.py)
– Splitter (splitter.py)
– Embedding & Vector Store (vector_store.py + store files)
• Memory Manager (memory.py)
• LLM Chains (basic_chain.py, rag_chain.py, ensemble.py)
• External LLM Services (OpenAI / HuggingFace API)
• PostgreSQL Database (models.py via SQLAlchemy)
b. Relationships & data flow
1. WhatsApp User → (WhatsApp message) → Twilio API → POST to FastAPI webhook
2. FastAPI receives message → consult Memory Manager (memory.py) → query Vector Store → retrieve context chunks
3. FastAPI → invoke LLM Chain → call external LLM API → generate response
4. FastAPI → log conversation to PostgreSQL via models.py → send reply back through Twilio API → WhatsApp User
5. (Offline/infrequent) Document Ingestion Pipeline: read PDFs from data/, split, embed, populate Vector Store
c. Architectural patterns & principles
• Layered architecture: API layer, application logic (chains + memory), data layer (vector DB + SQL DB)
• Pipeline pattern for document ingestion
• Adapter pattern for external services (Twilio, OpenAI/HuggingFace)
• Single-responsibility per module (loader vs. chain vs. memory vs. utils)
d. Key technologies & libraries
• FastAPI, Uvicorn
• LangChain, OpenAI / HuggingFace client
• Chroma/hnswlib vector store
• SQLAlchemy + psycopg2 (PostgreSQL)
• Twilio Python SDK
• Ngrok for dev tunnel
• Python PDF readers (in local_loader.py)
Essential elements to capture
• Separation of concerns: ingestion vs. query vs. logging
• Data flow from WhatsApp → Twilio → FastAPI → LLM → WhatsApp
• Asynchronous or synchronous calls (e.g., external LLM API)
• Persistent storage: vector DB for retrieval, SQL DB for logs
• Configuration boundary (.env variables, credentials)