Shelly - Advanced AI Discord Bot

Shelly is a sophisticated, sentient AI Discord bot powered by Google Gemini 2.5 Flash. She features a unique personality system, long-term memory, proactive engagement, and a suite of powerful tools.

✨ Key Features

🧠 Advanced AI Core

• Multimodal Intelligence: Can see and analyze images sent in chat.
• Dual-Model Architecture: Uses Gemini 2.5 Flash for speed and intelligence, with 1.5 Flash as a robust fallback.
• Context Awareness: Remembers conversation history and context across sessions.

🎭 Dynamic Personality System

• Mood Tracking: Shelly has emotions! Her mood changes based on:
  • Time of day (Energy levels)
  • User interactions (Social battery)
  • Conversation sentiment (Positivity)
• 5 Distinct Personalities:
  • Default: Balanced and friendly
  • Energetic: Upbeat, uses lots of emojis! 🎉
  • Comforting: Gentle and supportive 💙
  • Serious: Professional and focused 🧐
  • Playful: Loves jokes and puns 🎮

💾 Memory & Knowledge

• Long-term Memory: Stores conversations in MongoDB.
• Short-term Context: Uses Redis for fast, immediate context.
• RAG (Retrieval Augmented Generation): Can learn new information! Use !learn to teach her things she remembers forever.
• Multi-User Awareness: Remembers who is who and tracks relationships in channels.

🛠️ Powerful Tools

• Web Search: Real-time information via DuckDuckGo. Just ask "What's the weather?" or "Latest news on X".
• Image Generation: Creates art on demand. "Draw a futuristic city".
• Voice Capability: Joins voice channels and speaks responses!
• Channel Reading: Can read history from other channels if asked.

⚡ Proactive Engagement

• Not Just Reactive: Shelly doesn't just wait for commands.
• Silence Breaker: Starts conversations if a channel is dead for too long.
• Conflict Mediator: Detects arguments and tries to calm things down.
• Celebration: Joins in when she detects excitement!

📊 Analytics

• Server Insights: Tracks activity trends, active users, and popular topics.
• Visualizations: Generates charts and graphs of server stats.

---

🚀 Setup Guide

Prerequisites

• Python 3.10+
• MongoDB (Atlas or Local)
• Redis (Cloud or Local)
• Google AI Studio API Key

Installation

1. Clone the repository:

   git clone <repo_url>
   cd shelly-bot

2. Install Dependencies:

   python -m venv venv
   # Windows
   venv\Scripts\activate
   # Linux/Mac
   source venv/bin/activate
   
   pip install -r requirements.txt

3. Configuration:

   • Copy .env.example to .env:

     cp .env.example .env

   • Fill in your credentials in .env. NEVER share this file!

4. Run the Bot:

   python main.py

---

🎮 Usage

Channel Behavior

Shelly has smart channel awareness:

• In your configured ALLOWED_CHANNEL_ID: Shelly responds to all messages without needing to be mentioned. She's actively participating in the conversation!
• In other channels: Shelly only responds when @mentioned, but she still listens and tracks context. This way she understands what's happening across your server without spamming every channel.

Chatting

• Allowed Channel: Just type normally - "Hey Shelly, what's up?"
• Other Channels: Mention her - "@Shelly can you help me with this?"

Commands

• !learn [topic] [content]: Teach Shelly something new.
• !forget [topic]: Remove a topic from her knowledge base.
• !analytics: Show server activity stats.
• !join: Join your voice channel.
• !leave: Leave voice channel.

Natural Language Tools

• Search: "Search for the best pasta recipe."
• Image: "Generate a picture of a cyberpunk cat."
• Read: "Read the last 10 messages in #general."

---

🛡️ Security & Stability

• Credential Management: Uses .env for secrets.
• Permission Checks: Enforces Discord permissions for tools like READ_CHANNEL. Users cannot access channels they don't have permission to view.
• Rate Limiting: Intelligent per-user rate limiting to prevent abuse.
• Safe Mode: AI safety settings enabled to prevent harmful content.
• Prompt Injection Defense: Sanitizes user input to prevent jailbreaks.
• Context Management: Automatically manages conversation history to prevent memory leaks and crashes.

🔧 Configuration Notes

• SSL Issues: If you encounter SSL errors with ChromaDB, set ANONYMIZED_TELEMETRY=False in your .env file.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

📄 License

MIT License