Skip to content

starpig1129/ai-discord-bot-PigPig

BranchesTags

Repository files navigation

PigPig: Advanced Multi-modal LLM Discord Bot

English | 繁體中文

Discord

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!

🌟 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 with queue and playlist management.
  • 🧠 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.
  • 💭 Chain of Thought Reasoning: Provides detailed, step-by-step explanations of its thought process for enhanced transparency.

📸 Feature Showcase

alt text alt text alt text alt text alt text

🚀 Getting Started

System Requirements

  • Essential Dependencies:
  • Hardware Requirements:
    • GPU (Optional): An NVIDIA GPU with at least 12GB VRAM is recommended for running local models. The bot prioritizes API services, so a GPU is not required for most features.

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
SERCET_KEY=DASHBOARD_SERCET_KEY

# --- 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
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 (Optional) Your bot's client secret, used for specific API interactions.
SERCET_KEY (Optional) A secret key for dashboard authentication.
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.
OPENAI_API_KEY (Optional) Your API key for OpenAI's GPT models.
GEMINI_API_KEY (Optional) Your API key for Google's Gemini models.

Step 2: Configure settings.json file

If a settingsExample.json file exists, rename it to settings.json. Otherwise, create it. This file controls the bot's behavior, features, and other operational parameters. Do not change the key names.

{
    "prefix": "/",
    "activity": [
        {
            "paly": "學習說話"
        }
    ],
    "ipc_server": {
        "host": "127.0.0.1",
        "port": 8000,
        "enable": false
    },
    "version": "v2.2.11",
    "mongodb": "mongodb://localhost:27017/",
    "music_temp_base": "./temp/music",
    "model_priority": ["gemini", "local", "openai", "claude"],
    "auto_update": {
        "enabled": true,
        "check_interval": 21600,
        "require_owner_confirmation": true,
        "auto_restart": true
    },
    "notification": {
        "discord_dm": true,
        "update_channel_id": null,
        "notification_mentions": []
    },
    "security": {
        "backup_enabled": true,
        "max_backups": 5,
        "verify_downloads": true,
        "protected_files": ["settings.json", ".env", "data/"]
    },
    "restart": {
        "graceful_shutdown_timeout": 30,
        "restart_command": "python bot.py",
        "pre_restart_delay": 5
    },
    "github": {
        "repository": "starpig1129/ai-discord-bot-PigPig",
        "api_url": "https://github.com/starpig1129/ai-discord-bot-PigPig/releases/latest",
        "download_url": "https://github.com/starpig1129/ai-discord-bot-PigPig/archive/"
    },
    "ffmpeg": {
        "location": "/usr/bin/ffmpeg",
        "audio_quality": "192"
    }
}

Step 3: 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.
  • Key Commands: /play, /mode, /shuffle
  • Full Documentation

📖 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

🔄 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

📚 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. gpt/
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.

About

A discord bot based on multi-modal LLM that interacts with discord through natural language

Topics

python discord discord-bot artificial-intelligence large-language-models

Resources

Readme

License

MIT license
Activity

Stars

46 stars

Watchers

2 watching

Forks

8 forks
Report repository

Releases 30

v2.6.0 Latest
Jul 24, 2025
+ 29 releases

Packages

No packages published

Languages