📱 WhatsApp Group Summary Bot

AI-powered WhatsApp bot that joins any group, tracks conversations, and generates intelligent summaries.

---

Features

• 🤖 Automated group chat responses (when mentioned)
• 📝 Smart LLM-based conversation summaries
• 📚 Knowledge base integration for context-aware answers
• 📂 Persistent message history with PostgreSQL + pgvector
• 🔗 Support for multiple message types (text, media, links)
• 👥 Group management & customizable settings
• 🔕 Opt-out feature: Users can opt-out of being tagged in summaries/answers via DM.
• ⚡ REST API with Swagger docs (localhost:8000/docs)

---

🐳 Docker Compose Configurations

This project includes multiple Docker Compose files for different environments:

File	Purpose	Usage
docker-compose.yml	Default/Development. Builds the application from source code.	docker compose up -d
docker-compose.prod.yml	Production. Uses pre-built images from GHCR. Recommended for deployment.	docker compose -f docker-compose.prod.yml up -d
docker-compose.local-run.yml	Local Execution. For running the app on host while services run in Docker.	docker compose -f docker-compose.local-run.yml up -d
docker-compose.base.yml	Base Configuration. Contains shared service definitions.	❌ Do not use directly

---

📋 Prerequisites

• 🐳 Docker and Docker Compose
• 🐍 Python 3.13+
• 🗄️ PostgreSQL with pgvector extension
• 🔑 Voyage AI API key
• 📲 WhatsApp account for the bot

Quick Start

1. Clone & Configure

git clone https://github.com/YOUR_USER/wa_llm.git cd wa_llm

2. Create .env file

• Copy .env.example to .env and fill in required values.

cp .env.example .env

Environment Variables

3. Starting the Services

Option A: Development (Build from source)

docker compose up -d

Option B: Production (Use pre-built images)

docker compose -f docker-compose.prod.yml up -d

4. Connect your device

1. Open http://localhost:3000
2. Scan the QR code with your WhatsApp mobile app.
3. Invite the bot device to any target groups you want to summarize.
4. Restart service: docker compose restart wa_llm-web-server

5. Activating the Bot for a Group

1. open pgAdmin or any other posgreSQL admin tool

2. connect using

   Parameter	Value
   Host	localhost
   Port	5432
   Database	postgres
   Username	user
   Password	password

3. run the following update statement:

       UPDATE public."group"
       SET managed = true
       WHERE group_name = 'Your Group Name';
   

4. Restart the service: docker compose restart wa_llm-web-server

6. API usage

Swagger docs available at: http://localhost:8000/docs

Key Endpoints

• /load_new_kbtopic (POST) Loads a new knowledge base topic, prepares content for summarization.
• /trigger_summarize_and_send_to_groups (POST) Generates & dispatches summaries, Sends summaries to all managed groups

7. Opt-Out Feature

Users can control whether they are tagged in bot-generated messages (summaries, answers) by sending Direct Messages (DMs) to the bot:

Command	Description
opt-out	Opt-out of being tagged. Your name will be displayed as text instead of a mention.
opt-in	Opt-in to being tagged (default).
status	Check your current opt-out status.

Note: This only affects messages generated by the bot. It does not prevent other users from tagging you manually.

---

🚀 Production Deployment

To deploy in a production environment using the optimized configuration:

1. Create Production Environment File: Copy .env.example to .env.prod and configure your production secrets.

   cp .env.example .env.prod
   

2. Start Services:

   docker compose -f docker-compose.prod.yml up -d
   

This configuration includes:

• Automatic restart policies (restart: always)

---

Developing

Setup

Install dependencies using uv:

uv sync --all-extras --dev

Development Commands

The project uses Poe the Poet for task automation with parallel execution:

# Run all checks (format, then parallel lint/typecheck/test)
uv run poe check

# Individual tasks
uv run poe format     # Format code with ruff
uv run poe lint       # Lint code with ruff
uv run poe typecheck  # Type check with pyright
uv run poe test       # Run tests with pytest

# List all available tasks
uv run poe

The check command runs formatting first, then executes linting, type checking, and testing in parallel for faster execution.

Key Files

• Main application: app/main.py
• WhatsApp client: src/whatsapp/client.py
• Message handler: src/handler/__init__.py
• Database models: src/models/

---

Architecture

The project consists of several key components:

• FastAPI backend for webhook handling
• WhatsApp Web API client for message interaction
• PostgreSQL database with vector storage for knowledge base
• AI-powered message processing and response generation

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

License

LICENCE