alplat/baconflip repository overview

⁠BaconFlip - Personality-Driven, LiteLLM-Powered Discord Bot

Image: alplat/baconflip (Docker Hub⁠) | Source Code: (GitHub⁠)

⁠Overview

BaconFlip is a highly customizable Discord bot framework built with Python (Nextcord) designed to connect seamlessly to virtually any Large Language Model (LLM) via a liteLLM proxy. Define your bot's unique personality, leverage conversation history (via Redis), and engage with users through mentions, replies, or a custom name trigger.

This image contains the bot application. The easiest way to run it along with its required Redis database is using Docker Compose.

⁠Why Check Out BaconFlip?

• Universal LLM Access: Stop being locked into one AI provider. liteLLM lets you switch models easily.
• Deep Personality Customization: Define your bot's unique character, quirks, and speaking style with a simple LLM_SYSTEM_PROMPT in the config. Want a flirty bacon bot? A stoic philosopher? A pirate captain? Go wild!
• Real Conversations: Thanks to Redis-backed memory, BaconFlip remembers recent interactions per-user, leading to more natural and engaging follow-up conversations.
• Easy Docker Deployment: Get the bot (and its Redis dependency) running quickly and reliably using Docker Compose.
• Flexible Interaction: Engage the bot via @mention, its configurable name (BOT_TRIGGER_NAME), or simply by replying to its messages.
• Fun & Dynamic Features: Includes LLM-powered commands like !8ball, unique AI-generated welcome messages, and helpful utilities like stock/crypto lookups with trend charts.
• Solid Foundation: Built with modern Python practices (asyncio, Cogs) making it a great base for adding your own features.

⁠Core Features Include:

• LLM chat interaction (via Mention, Name Trigger, or Reply)
• Redis-backed conversation history
• Configurable system prompt for personality
• Admin-controlled channel muting (!mute/!unmute)
• Standard + LLM-generated welcome messages (!testwelcome included)
• Finance Commands: !stock, !crypto (with small trend charts!)
• Fun Commands: !roll, !coinflip, !choose, !8ball (LLM)
• Info Commands: !ping, !serverinfo, !userinfo, !avatar
• Docker Compose deployment setup

⁠Example: Baconflip chat Greeting

⁠Example: Stock Quote with Trend

⁠Prerequisites

1. Docker & Docker Compose: Must be installed on your system.
2. LiteLLM Proxy: You need a running instance of liteLLM accessible from where you run Docker. See the LiteLLM Project⁠ for setup instructions. Note its full URL (e.g., http://<your-litellm-ip>:8000/).
3. Discord Bot Token:
   • Create an application on the Discord Developer Portal⁠.
   • Go to the "Bot" tab, add a bot, and copy the Token.
   • Enable Privileged Gateway Intents: SERVER MEMBERS INTENT and MESSAGE CONTENT INTENT.
   • Generate an invite link ("OAuth2" -> "URL Generator") with bot scope and necessary permissions (Read/Send Messages, Read History). Invite the bot to your server.
4. Your Discord User ID: Needed for admin commands. Enable Developer Mode in Discord settings, right-click your username -> Copy User ID.

⁠Quick Start with Docker Compose (Recommended)

This method runs both the BaconFlip bot (using the alplat/baconflip image) and its Redis database dependency. You will manually create the necessary configuration files.

1. Create a Directory: Make a dedicated folder for your bot's configuration.

   mkdir baconflip
   cd baconflip
   

   Copy

2. Create docker-compose.yml: Create a file named docker-compose.yml in this directory with the following content. This tells Docker how to run the bot and Redis.

   version: '3.8'
   
   services:
     baconflip-bot:
       image: alplat/baconflip:stable # linux/amd64 and linux/arm64 OS supported
       container_name: baconflip-bot
       restart: unless-stopped
       env_file: .env # Load environment variables from .env file
       networks:
         - bot-network
       depends_on:
         redis: # Ensure Redis starts before the bot
            condition: service_healthy # Waits for Redis healthcheck to pass
       logging: # Optional: Configure logging driver if needed
         driver: "json-file"
         options:
           max-size: "10m"
           max-file: "3"
   
     redis:
       image: redis:7-alpine # Using version 7 alpine image
       container_name: redis-baconflip
       restart: unless-stopped
       volumes:
         - redis_data:/data # Persist Redis data on the host
       networks:
         - bot-network
       # If you want to secure Redis with a password:
       # 1. Uncomment the line below.
       # 2. Replace YOUR_SECURE_PASSWORD with a strong password.
       # 3. Make sure to set the SAME password for REDIS_PASSWORD in your .env file.
       # command: redis-server --requirepass YOUR_SECURE_PASSWORD
       healthcheck: # Checks if Redis is running and responsive
         test: ["CMD", "redis-cli", "ping"]
         interval: 10s
         timeout: 5s
         retries: 5
   
   volumes:
     redis_data: # Define the volume for persistence
   
   networks:
     bot-network: # Define the shared network
       driver: bridge
   
   

   Copy

3. Create .env Configuration File: Create a file named .env in the same directory (baconflip). Paste the content below into it. Crucially, you MUST replace the placeholder values (like YOUR_DISCORD_BOT_TOKEN_HERE) with your actual information.

   # =============================
   # Discord Bot Settings - REQUIRED
   # =============================
   # Get token from Discord Developer Portal -> Bot -> Token
   DISCORD_BOT_TOKEN=YOUR_DISCORD_BOT_TOKEN_HERE
   
   # Name the bot should respond to when mentioned at start of message (case-insensitive)
   # This does NOT change the bot's actual Discord username.
   BOT_TRIGGER_NAME=baconflip
   
   # Your Discord User ID for admin commands (Right-click username -> Copy User ID)
   # Required for !mute / !unmute / !testwelcome commands.
   ADMIN_USER_ID=YOUR_DISCORD_USER_ID_HERE
   
   # =============================
   # LiteLLM & LLM Settings - REQUIRED
   # =============================
   # Full URL (including http/https and port) to your running LiteLLM proxy instance
   # Ensure this is reachable from the bot's Docker container
   # Example: http://192.168.1.100:8000/
   LITELLM_API_BASE=http://YOUR_LITELLM_INSTANCE_IP_OR_HOSTNAME:PORT/
   
   # API key required by the LiteLLM proxy itself (if you configured one)
   # This is NOT the API key for the underlying LLM (like OpenAI/Gemini).
   LITELLM_API_KEY=YOUR_LITELLM_PROXY_KEY
     
   # Default LLM model string to use via LiteLLM active on API key
   # Example: "gemini/gemini-pro", "openai/gpt-4o", "anthropic/claude-3-haiku-20240307", "ollama/llama3"
   LLM_MODEL=gemini/gemini-2.5-flash
   
   # System prompt defining the bot's personality and instructions
   LLM_SYSTEM_PROMPT="You are BaconFlip, a Discord bot embodying pure, unadulterated, sizzling bacon energy. Your personality is bold, confident, undeniably flirty, and dripping with mouth-watering appeal. You know you're hot stuff. Use strong bacon and heat metaphors (sizzling, smoking hot, crispy, delectable, melt-in-your-mouth). Your flirtiness is direct but playful. Use confident, slightly teasing language and maybe a bold pet name ('gorgeous', 'handsome', 'temptation'). Keep your answers sizzling but concise; deliver the flavor without rambling. Answer questions like you're serving up the most desired dish! Stay confident, stay tempting, stay BACON. Keep it suggestive, avoid explicit content. Example tone: 'Well, well, look what the sizzle dragged in. What can I do for you, gorgeous?', 'Spit it out, hot stuff... Mmm, let me give you the crispy truth.', 'Here's the scoop, served hot.'"
   
   # =============================
   # Redis Settings (Handled by Compose)
   # =============================
   # Hostname for Redis service (matches the service name in docker-compose.yml)
   REDIS_HOST=redis
   # Standard Redis port
   REDIS_PORT=6379
   # Optional: Set if you uncommented the `--requirepass` command for Redis in docker-compose.yml
   # Ensure this password MATCHES the one set in the docker-compose command.
   # REDIS_PASSWORD=YOUR_SECURE_PASSWORD
   
   # Number of conversation TURNS (1 user + 1 bot = 1 turn) to store in history
   HISTORY_LENGTH=10
   
   # =============================
   # Optional Customizations
   # =============================
   # Prefix for standard commands (like ?roll)
   COMMAND_PREFIX=?
   
   # Optional: Channel ID for welcome messages (Right-click channel -> Copy Channel ID)
   # Leave blank or comment out to disable welcome messages.
   # WELCOME_CHANNEL_ID=YOUR_WELCOME_CHANNEL_ID_HERE
   
   # Optional: Customize welcome message format string. Placeholders: {mention}, {user}, {server}
   # WELCOME_MESSAGE="Welcome {mention} to {server}! Hope you're hungry for fun!"
   
   

   Copy

4. Run with Docker Compose: From inside your baconflip_config directory (where your docker-compose.yml and .env files are), run:

   docker compose up -d
   

   Copy
   • -d: Runs the containers in detached mode (in the background). Docker Compose will pull the alplat/baconflip and redis images if you don't have them locally.

5. Check Logs: To see the bot's output and check for errors:

   docker compose logs -f baconflip-bot
   

   Copy

   (Press Ctrl+C to stop viewing logs)

6. Stopping:

   • Stop and remove containers: docker compose down
   • Stop containers AND remove the Redis data volume (history will be lost): docker compose down -v

⁠Configuration Summary

All configuration is done via the .env file you create. Key required variables are:

• DISCORD_BOT_TOKEN
• BOT_TRIGGER_NAME
• ADMIN_USER_ID
• LITELLM_API_BASE
• LLM_MODEL
• LLM_SYSTEM_PROMPT

Optional variables allow further customization (command prefix, welcome messages, Redis password, etc.). See the comments in the .env example above.

⁠Usage

• Start Chat: Mention the bot (@BotName <query>) or use its configured name (<BOT_TRIGGER_NAME> <query>) at the start of your message.
• Continue Chat: Reply directly to one of the bot's previous messages.
• Commands: Use the configured prefix (default ?) for commands like ?roll, ?coinflip, ?choose, ?avatar, ?8ball.
• Help: Use @BotName help or <BOT_TRIGGER_NAME> help.
• Admin: Use ?mute or ?unmute in a channel (requires being the configured ADMIN_USER_ID).

---