PigPig: Advanced Multi-modal LLM Discord Bot

English | 繁體中文

Introduction

PigPig is a powerful, multi-modal Discord bot powered by Large Language Models (LLMs). It's designed to interact with users through natural language, combining advanced AI capabilities with practical, fun features to enrich any Discord community.

Invite PigPig to your server!

📄 Legal Documents

To ensure user rights and service transparency, please refer to the following documents:

• Terms of Service: TERMS_OF_SERVICE.md
• Privacy Policy: PRIVACY_POLICY.md
• Support Email: [email protected]
• Support Server: https://discord.gg/BvP64mqKzR

🌟 Key Features

• 🧠 AI-Powered Conversations: Utilizes advanced LLMs for natural language understanding and generation.
• 🖼️ Multi-modal Capabilities: Supports visual question answering (VQA) and AI image generation.
• 🎵 Music Playback: Plays music from YouTube, SoundCloud and Spotify links with seeking, audio effects (nightcore, 8D, karaoke ...), synced lyrics, personal and server playlists, a DJ role with vote skipping, 24/7 mode and a song request channel.
• 🧠 Intelligent Channel Memory: Permanently stores and intelligently retrieves conversation history with semantic search to provide enhanced context for responses.
• 🔄 Auto-Update System: Automatically checks for and applies GitHub updates with secure backups and rollback functionality.
• 🍽️ Practical Tools: Set reminders, get restaurant recommendations, perform calculations, and more.

📸 Feature Showcase

🚀 Getting Started

System Requirements

• Essential Dependencies:

  • Python 3.11+
  • FFmpeg (For music playback)

  FFmpeg Installation:

  • Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg

  • CentOS/RHEL: sudo yum install epel-release && sudo yum install ffmpeg

  • macOS: brew install ffmpeg

  • Windows: Download from FFmpeg Windows builds

  • Python packages listed in requirements.txt

Installation Steps

# Clone the repository
git clone https://github.com/starpig1129/discord-LLM-bot-PigPig.git

# Navigate to the project directory
cd discord-LLM-bot-PigPig

# Install required Python packages
pip install -r requirements.txt

⚙️ Configuration

Follow these steps to configure your bot instance.

Step 1: Configure .env file

Rename the .env Example file to .env and fill in the required values.

# .env

# --- Discord Bot Credentials ---
TOKEN=XXXXXXXXXXXXXXXXXXXXXXXX.XXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXX
CLIENT_ID=123456789012345678
CLIENT_SECRET_ID=XXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXX

# --- Dashboard Secret ---
# Generate with: python3 -c "import secrets; print(secrets.token_urlsafe(64))"
DASHBOARD_SECRET_KEY=<generate-a-random-64-char-secret>

# --- Bot Configuration ---
BOT_OWNER_ID=123456789012345678
BUG_REPORT_CHANNEL_ID=123456789012345678

# --- AI Model Configuration ---
MODEL_NAME=openbmb/MiniCPM-o-2_6
ANTHROPIC_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
OPENAI_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
GEMINI_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# --- Vector Database API Keys ---
VECTOR_STORE_API_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

# --- Bot Configuration File Path ---
CONFIG_ROOT="/path/to/your/config"

Variable	Description
TOKEN	(Required) Your Discord bot token from the Discord Developer Portal.
CLIENT_ID	(Required) Your bot's client ID from the Developer Portal.
CLIENT_SECRET_ID	(Required) Your bot's client secret, used for Discord OAuth2 login on the dashboard.
DASHBOARD_SECRET_KEY	(Required) A random secret for signing dashboard JWT tokens. Generate with python3 -c "import secrets; print(secrets.token_urlsafe(64))".
BOT_OWNER_ID	(Required) Your Discord User ID. Grants owner-level privileges and is required for the auto-update system.
BUG_REPORT_CHANNEL_ID	(Optional) A Discord channel ID where error messages and bug reports will be sent.
MODEL_NAME	The default local multi-modal model to use.
ANTHROPIC_API_KEY	(Optional) Your API key for Anthropic's Claude models, available on Anthropic official website.
OPENAI_API_KEY	(Optional) Your API key for OpenAI's GPT models, available on OpenAI official website.
GEMINI_API_KEY	(Optional) Your API key for Google's Gemini models, available on Google AI Studio.
VECTOR_STORE_API_KEY	(Optional) Your API key for vector databases (like Qdrant), only needed if using cloud database.
CONFIG_ROOT	(Optional) Root directory path for custom configuration files and data. Defaults to ./base_configs folder in current directory.

Step 2: Configure configs folder

The bot's default files are in the ./base_configs folder. You can edit these JSON files to customize the bot's behavior as needed. It is recommended to copy them and set the 'CONFIG_ROOT' parameter in '.env'.

Step 3: Configure Long-term Memory System

If you do not want to enable the long-term memory system, set enabled to false in base_configs/memory.yaml. To tune cache behavior, adjust procedural_cache_ttl (seconds) in base_configs/memory.yaml; larger values reduce DB reads, smaller values refresh user data more aggressively. If you use a cloud vector database (like Qdrant), set the VECTOR_STORE_API_KEY in the .env file. And ensure that the vector database URL and other parameters are correctly set in base_configs/memory.yaml. For local installation or cloud setup methods, refer to Qdrant official documentation.

Step 4: Start the Bot

Once configured, you can start the bot with the following command:

python main.py

📦 Features / Cogs Overview

The bot's functionality is divided into modules called "Cogs". Here are the key features available:

---

🧠 Memory System

• Description: Manages long-term conversation memory, enabling the bot to recall past interactions. It uses semantic search to find the most relevant context.
• Key Commands: /memory_search, /memory_stats, /memory_config
• Full Documentation

---

🎵 Music

• Description: Provides full music playback from YouTube, supporting song requests, queue management, playlists, and various playback modes, plus seeking, audio effects, synced lyrics, saved playlists and per-server settings (DJ role, 24/7, request channel).
• Key Commands: /play, /mode, /shuffle, /music, /filter, /queue, /playlist, /music_settings
• Full Documentation · Commands & Settings

---

📖 Story Manager

• Description: Facilitates interactive, collaborative storytelling using a multi-agent AI architecture to create dynamic narratives guided by user actions.
• Key Commands: /story
• Full Documentation

---

🍽️ Eat (Restaurant Recommendations)

• Description: An intelligent engine that recommends restaurants by learning a server's food preferences through user ratings and feedback.
• Key Commands: /internet_search search_type: eat
• Full Documentation

---

🖼️ Image Generation

• Description: Generates and edits images from text prompts using advanced AI models, supporting both creation and instruction-based modification.
• Key Commands: /generate_image
• Full Documentation

---

🌐 Internet Search

• Description: A versatile tool to search the web, find images, look up YouTube videos, or fetch content from a URL.
• Key Commands: /internet_search
• Full Documentation

---

⚙️ System Prompt Manager

• Description: Allows deep customization of the bot's personality and behavior on a per-server or per-channel basis using a three-tiered inheritance model.
• Key Commands: /system_prompt
• Full Documentation

---

⏰ Reminder

• Description: Allows users to set reminders for themselves or others using natural language for timing (e.g., "in 10 minutes" or a specific date).
• Key Commands: /remind
• Full Documentation

---

📅 Schedule Manager

• Description: Manages server schedules using YAML files, allowing users to upload, query, and update schedules through natural language.
• Key Commands: /upload_schedule, /query_schedule, /update_schedule
• Full Documentation

---

🔄 Update Manager

• Description: Provides a command interface to check for, initiate, and monitor the bot's automatic update process from GitHub.
• Key Commands: /update_check, /update_now
• Full Documentation

---

🛂 Channel Manager

• Description: Provides administrators with tools to control where the bot can interact, using server-wide policies and per-channel overrides.
• Key Commands: /set_server_mode, /set_channel_mode, /auto_response
• Full Documentation

---

👤 User Data

• Description: A system for storing and managing user-specific data, which can be updated manually or merged intelligently by the AI.
• Key Commands: /userdata
• Full Documentation

---

🌍 Language Manager

• Description: Manages multi-language support, allowing servers to set their preferred language for bot responses and commands.
• Key Commands: /set_language, /current_language
• Full Documentation

---

🧠 Model Management

• Description: A developer tool for the bot owner to dynamically load and unload the local AI model to manage GPU resources.
• Key Commands: /model_management
• Full Documentation

---

🧮 Math Calculator

• Description: A secure tool for evaluating a wide range of mathematical expressions using the sympy library.
• Key Commands: This is an internal tool, not a direct slash command.
• Full Documentation

---

📝 Summarizer

• Description: Uses AI to summarize channel conversations with message source attribution and customizable limits.
• Key Commands: /summarize
• Full Documentation

---

🔍 GIF Tools

• Description: Search and manage GIF content for Discord servers with intelligent matching capabilities.
• Key Commands: /search_gif
• Full Documentation

---

🤖 Bot Info

• Description: Displays detailed information about the bot including uptime, version, and system status.
• Key Commands: /botinfo
• Documentation (general documentation section)

---

📚 For Developers: Technical Documentation

The codebase is extensively documented. Below are links to the main documentation sections for developers:

Module Category	Description	Documentation Link
Core GPT Engine	Handles LLM integration, response generation, and tools.	llm/
Addons	Manages system-level features like auto-updates.	addons/
Cogs (Features)	Core bot features and commands.	cogs/
↳ Eat System	Intelligent food recommendation module.	cogs/eat/
↳ Memory System	Manages long-term conversation memory.	cogs/memory/
↳ Music System	Handles music playback and queues.	cogs/music_lib/
↳ Story System	Interactive story generation module.	cogs/story/
↳ System Prompt	Manages server and channel system prompts.	cogs/system_prompt/

License

This project is licensed under the MIT License. See the LICENSE file for details.