🤖 SF Discord Bot

A production-grade, highly optimized, multi-purpose Discord bot built with Python & discord.py.
Featuring Dual-AI intelligence (Groq & NVIDIA NIM), Anti-Nuke defense, automated support tickets, leveling, giveaways, and dynamic voice rooms.

Key Features • Architecture • Getting Started • Configuration • Commands • Deployment • Security

---

🌟 Overview

SF Discord Bot is engineered for modern Discord communities that demand speed, reliability, and intelligence without bloat. It combines state-of-the-art Large Language Models with battle-tested server administration tools:

• ⚡ Dual AI Engine: Seamless fallback between Groq LPU (lightning-fast inference) and NVIDIA NIM (high-capacity reasoning) with automatic key pool rotation.
• 🛡️ Autonomous Moderation & Anti-Nuke: Real-time defense against mass kicks/bans, unauthorized channel tampering, toxic language, and spam floods.
• 🪶 Hyper-Optimized Resource Footprint: Designed from the ground up to operate smoothly under strict 100MB RAM limits (e.g., Discloud free/starter tiers) via proactive memory trimming (malloc_trim) and SQLite WAL optimizations.
• 🎯 Privacy & Security First: Zero hardcoded secrets, strict .env segregation, automated database backups, and sanitized logging.

---

✨ Key Features

🧠 Dual-AI Assistant

• Automatic Fallback: Primary Groq API switches to NVIDIA NIM instantaneously if rate limits or network issues occur.
• Multi-Key Pool: Distribute traffic across multiple API keys (GROQ_API_KEY, GROQ_API_KEY_2, etc.) to prevent quota exhaustion.
• Dynamic Personalities: Toggle bot behavior on the fly using /mode (default, sarcastic, teacher, developer, roast).
• Context-Aware Memory: Maintains concise conversation history per user with automatic summarization and cache purging.

🛡️ Moderation & Anti-Nuke Suite

• Anti-Nuke Safeguards: Rate-limits sensitive actions (mass channel creation/deletion, mass kicks, unauthorized bot additions).
• AutoMod Engine: Real-time filter for spam, excessive caps, malicious invites, and customizable banned words.
• Comprehensive Punishments: Slash & prefix commands for ban, kick, softban, timeout, warn, mute, and bulk purge (clear, nuke).
• Audit Logging: Detailed embeds for message edits, deletions, member joins/leaves, and mod actions.

🎫 Support Ticket System

• Interactive Ticket Panels: Users can create tickets via modern button components.
• Staff Workflow: Ticket claiming, category routing, and automatic permission overrides.
• AI-Powered Ticket First Response: Bot analyzes user query and suggests instant self-help solutions.
• HTML Transcripts: Save and archive full conversations before ticket closure.

🔊 Dynamic Temporary Voice (Join-to-Create)

• Create temporary private voice channels on demand.
• Automatic channel deletion when empty to keep server lists pristine.
• User controls for renaming, locking, and member limits.

🎁 Giveaways & Community Engagement

• Interactive Giveaways: Multi-winner support, countdown timers, button-based entries, and reroll mechanics.
• Leveling & XP System: Text and voice chat XP tracking, configurable boosts, role rewards, and /leaderboard.
• Reaction Roles & Role Panels: Interactive dropdowns and buttons supporting up to 25 roles per panel.
• Dynamic Welcome Cards: High-quality welcome visuals rendered on the fly with Pillow.

---

🏗 Architecture

📦 sf-discord-bot
 ┣ 📂 src
 ┃ ┣ 📂 handlers               # Event listeners & Command cogs
 ┃ ┃ ┣ 📜 admin_commands.py    # Administrative overrides & whitelist
 ┃ ┃ ┣ 📜 antinuke.py          # Anti-raid & anti-nuke monitors
 ┃ ┃ ┣ 📜 automod_commands.py  # Filters, banned words, spam rules
 ┃ ┃ ┣ 📜 broadcast.py         # Global announcements & DM broadcasts
 ┃ ┃ ┣ 📜 commands.py          # General utility & information commands
 ┃ ┃ ┣ 📜 dm_handler.py        # Secure password-protected DM gateway
 ┃ ┃ ┣ 📜 giveaway.py          # Giveaway management & interactive views
 ┃ ┃ ┣ 📜 level_commands.py    # XP, ranking, and leaderboard interface
 ┃ ┃ ┣ 📜 mod_commands.py      # Moderation command suite
 ┃ ┃ ┣ 📜 reaction_roles.py    # Interactive button & menu role panels
 ┃ ┃ ┣ 📜 reply_handler.py     # AI reply routing and context injection
 ┃ ┃ ┣ 📜 server_logs.py       # Audit trail for messages and events
 ┃ ┃ ┣ 📜 slash_mod.py         # Discord application command integrations
 ┃ ┃ ┣ 📜 temp_voice.py        # Join-to-create temporary voice rooms
 ┃ ┃ ┣ 📜 ticket_commands.py   # Support ticket lifecycle & transcript creation
 ┃ ┃ ┗ 📜 welcome.py           # Welcome banner generator & onboarding
 ┃ ┣ 📂 services               # Business logic, engines, & background workers
 ┃ ┃ ┣ 📜 ai_service.py        # Groq/NVIDIA unified client & fallback logic
 ┃ ┃ ┣ 📜 antinuke_service.py  # Threat detection & action throttle tracking
 ┃ ┃ ┣ 📜 automod.py           # Content inspection & regex filters
 ┃ ┃ ┣ 📜 backup.py            # Automated SQLite snapshot manager
 ┃ ┃ ┣ 📜 bot_agent.py         # Autonomous workflow executor
 ┃ ┃ ┣ 📜 cache.py             # Memory-bounded LRU caches
 ┃ ┃ ┣ 📜 context_builder.py   # AI prompt assembly with guild context
 ┃ ┃ ┣ 📜 database.py          # Asynchronous SQLite connector (aiosqlite)
 ┃ ┃ ┣ 📜 giveaway_service.py  # Giveaway persistence & timer loop
 ┃ ┃ ┣ 📜 key_pool.py          # API key rotation & health tracker
 ┃ ┃ ┣ 📜 level_service.py     # XP calculation & database operations
 ┃ ┃ ┣ 📜 nvidia_service.py    # NVIDIA NIM OpenAI-compatible client
 ┃ ┃ ┣ 📜 temp_voice_service.py# Channel lifecycle state manager
 ┃ ┃ ┗ 📜 ticket_ai.py         # Automated ticket query analyzer
 ┃ ┗ 📜 config.py              # Configuration schemas & prompt templates
 ┣ 📂 data                     # SQLite databases (Ignored by Git)
 ┣ 📂 logs                     # System logs (Ignored by Git)
 ┣ 📜 bot.py                   # Main bot entry point & memory monitor
 ┣ 📜 discloud.config          # Discloud container manifest
 ┣ 📜 requirements.txt         # Core dependencies
 ┣ 📜 SECURITY.md              # Vulnerability reporting & best practices
 ┗ 📜 .env.example             # Safe template for environment variables

---

🚀 Getting Started

Prerequisites

• Python 3.10+ installed on your system.
• A Discord Bot Token from the Discord Developer Portal.
  • Required Privileged Gateway Intents: Message Content, Server Members, and Presence.
• An API Key for AI features:
  • Free Groq API Key: console.groq.com
  • Free NVIDIA NIM API Key: build.nvidia.com

---

Installation

1. Clone the repository:

   git clone https://github.com/test-bit-sys/sf-discord-bot.git
   cd sf-discord-bot

2. Create and activate a virtual environment:

   # Windows (PowerShell)
   python -m venv .venv
   .venv\Scripts\Activate.ps1
   
   # Linux / macOS
   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set up environment variables:

   # Copy the safe example configuration
   cp .env.example .env

   Open .env in your favorite editor and configure your secrets.

5. Start the bot:

   python bot.py

---

⚙️ Configuration

Your .env file should contain only your private keys and guild settings. Never share or commit this file!

Variable	Description	Default / Example	Required
DISCORD_TOKEN	Discord Bot Token from developer portal	your_bot_token	✅
OWNER_ID	Discord User ID of the primary administrator	123456789012345678	✅
BOT_PREFIX	Prefix for standard commands	!	✅
ALLOWED_GUILD_ID	Restrict bot to a single server (leaves others)	your_server_id	❌
AI_PROVIDER	auto, groq, or nvidia	auto	❌
GROQ_API_KEY	Primary Groq API Key	gsk_...	⚡
GROQ_API_KEY_2	Backup Groq API Key for key pool rotation	gsk_...	❌
GROQ_MODEL	Target Groq model	llama-3.3-70b-versatile	❌
NVIDIA_API_KEY	Primary NVIDIA NIM API Key	nvapi-...	⚡
NVIDIA_MODEL	Target NVIDIA model	openai/gpt-oss-20b	❌
WHITELIST_PASSWORD	Password required for direct DM access	change_this_password	✅
SUPPORT_ROLE	Role name granted ticket management access	Support	❌
TICKET_CATEGORY	Discord category name for opened tickets	Tickets	❌
BOT_OWNER_NAME	Custom name displayed by the AI assistant	Developer	❌
BOT_OWNER_GITHUB	Custom GitHub username reference	test-bit-sys	❌

---

📋 Commands Overview

🤖 AI & Conversational Commands

Command	Type	Description
/ask <question>	Slash	Query the AI assistant directly.
/mode <style>	Slash	Switch personality: default, sarcastic, teacher, developer, roast.
/clearchat	Slash	Flush your conversation memory buffer.
Reply to message	Message	Replying to any bot message automatically triggers a contextual conversation.

🛡️ Moderation & Administration

Command	Type	Description
!ban / /ban @user [reason]	Both	Ban a user from the guild.
!unban <user_id>	Prefix	Unban a member by ID.
!kick / /kick @user [reason]	Both	Kick a member.
!timeout / /timeout @user <duration>	Both	Timeout a member (e.g. 10m, 1h, 1d).
!warn / !warnings @user	Prefix	Issue warnings and review user infraction history.
!clear <count> / !nuke	Prefix	Bulk delete messages or wipe and clone the channel.
!lock / !unlock	Prefix	Toggle channel read/write permissions for @everyone.
!announce #channel <message>	Prefix	Send formatted announcement embeds.
!sync	Prefix	Manually synchronize Slash commands with Discord API (Owner only).
!ram	Prefix	Inspect RAM usage and trigger memory compaction & WAL checkpoint (Owner only).

🎫 Tickets & Role Management

Command	Type	Description
/ticket or !ticket	Both	Open a support ticket modal.
!close	Prefix	Close current ticket, compile HTML transcript, and archive.
!claim	Prefix	Claim ticket as a staff member.
/rolesetup	Slash	Interactive role assignment panel wizard (up to 25 roles).
/rolepanel	Slash	Spawn interactive dropdown or button role panels.

📈 Leveling, Voice & Giveaways

Command	Type	Description
/rank [@user]	Slash	Display user card with current level, XP, and rank.
/leaderboard	Slash	Display top 10 most active community members.
/gstart / /gend / /greroll	Slash	Initialize, terminate, or redraw giveaways.
!setlevelrole <lvl> @role	Prefix	Automatically grant roles upon reaching specific levels.
!setlevelupchannel [#channel]	Prefix	Route level-up notifications to a dedicated channel.

---

☁️ Discloud Deployment

The repository includes a ready-to-use discloud.config tuned for Discloud's 100MB RAM plan:

1. Create a zip archive containing the required source files (do NOT include .env, logs/, or data/):

   # Files to package:
   bot.py
   requirements.txt
   discloud.config
   src/

2. Upload the archive via the Discloud Web Dashboard or the Discloud CLI.
3. In the Discloud Dashboard under Variables/Secrets, add your environment variables (DISCORD_TOKEN, OWNER_ID, GROQ_API_KEY, etc.).
4. Start your bot. The built-in memory watchdog will continuously enforce heap compaction to keep RAM well beneath the 100MB limit.

---

🔒 Security & Privacy

• Zero-Secret Guarantee: The repository is configured to strictly ignore .env, local SQLite files (*.db), logs, and credentials.
• Single-Guild Lock: Optional ALLOWED_GUILD_ID guarantees the bot immediately leaves unauthorized servers if invited.
• Strict DM Gateway: Users cannot interact with the bot in direct messages without entering the configured WHITELIST_PASSWORD.
• Automated Backups: Database state is automatically snapshotted on startup and on regular intervals into data/backups/.

To report security concerns, please refer to SECURITY.md.

---

📄 License

Distributed under the MIT License. See LICENSE for full details.

_{Maintained with ❤️ by test-bit-sys}