📋 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

| Variable | Description | Default | | ------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ | | WHATSAPP_HOST | WhatsApp Web API URL | http://localhost:3000 | | WHATSAPP_BASIC_AUTH_USER | WhatsApp API user | admin | | WHATSAPP_BASIC_AUTH_PASSWORD | WhatsApp API password | admin | | VOYAGE_API_KEY | Voyage AI key | – | | DB_URI | PostgreSQL URI | postgresql+asyncpg://user:password@localhost:5432/postgres | | LOG_LEVEL | Log level (DEBUG, INFO, ERROR) | INFO | | ANTHROPIC_API_KEY | Anthropic API key. You need to have a real anthropic key here, starts with sk-.... | – | | LOGFIRE_TOKEN | Logfire monitoring key, You need to have a real logfire key here | – | | DM_AUTOREPLY_ENABLED | Enable auto-reply for direct messages | False | | DM_AUTOREPLY_MESSAGE | Message to send as auto-reply | Hello, I am not designed to answer to personal messages. |

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