---
title: Ultimate AI & Music Bot
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: "20.10.25"
python_version: "3.11"
app_file: bot/main.py
pinned: false
---

# 🤖 Ultimate AI & Music Discord Bot

A feature-rich, multi-purpose Discord bot with cyberpunk aesthetics, AI integration, music playback, economy system, and more.

## ✨ Features

### 🎵 Music System
- Full music playback with Wavelink/Lavalink
- Queue management, filters, 24/7 mode
- Playlist support and lyrics display
- Rich music control panels with buttons

### 🤖 AI Suite
- OpenRouter & Gemini AI integration
- Auto-chat mode in dedicated channels
- Image analysis and prompt generation
- Multiple AI personalities (Wise, Sarcastic, Technical, Funny)

### 💰 Economy & Engagement
- Wallet, bank, daily rewards
- Work, gamble, rob, shop system
- XP/leveling with rank cards
- Leaderboards and inventory

### 🎮 Games & Fun
- Trivia (Gaming, Movies, Series)
- Arcade games (Mario challenge)
- Board games (Chess, Checkers, Connect 4, Othello)
- Classic games (XO, 8ball, Slots, Dice, Coinflip)

### 🛡️ Moderation & Admin
- Ban, kick, mute, warn, purge
- Slowmode, lock/unlock channels
- Server backup and restore
- Auto-moderation features

### 🌐 Multi-Language Support
- 14+ languages: Arabic, English, French, Spanish, German, etc.
- Full i18n with emoji placeholders
- Per-server language configuration

### 🎫 Community Features
- Ticket system for support
- Polls and suggestions
- Giveaways with auto-winner selection
- Verification system

### 📊 Configuration
- Per-server settings panel
- Custom channels for logs, welcome, daily messages
- DJ role, premium tiers, music autoplay
- Game news and free games alerts

## 🚀 Quick Start

### Prerequisites
- Python 3.11+
- Discord Bot Token ([Discord Developer Portal](https://discord.com/developers/applications))
- Optional: OpenRouter API key, Gemini API key

### Installation

1. **Clone the repository**
```bash
git clone <your-repo-url>
cd BOT-
```

2. **Install dependencies**
```bash
pip install -r requirements.txt
```

3. **Set up environment variables**
```bash
cp .env.example .env
```

Edit `.env` with your configuration:
```env
DISCORD_TOKEN=your_bot_token_here
PREFIX=!
OWNER_IDS=your_discord_user_id
OPENROUTER_API_KEY=your_openrouter_key
GEMINI_API_KEY=your_gemini_key
```

4. **Run the bot**
```bash
python -m bot.main
```

## 🐳 Docker Deployment

```bash
docker build -t discord-bot .
docker run -d --env-file .env discord-bot
```

## 🌐 Cloud Deployment

### HuggingFace Spaces
- Push your code to a HF Space
- Set environment variables in Space settings
- The bot will auto-start on deployment

### Render
- Connect your GitHub repository
- Use the `render.yaml` configuration
- Add environment variables in Render dashboard

## ⚙️ Configuration

### Required Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `DISCORD_TOKEN` | Your Discord bot token | `MTIz...` |
| `PREFIX` | Command prefix | `!` or `/` |
| `OWNER_IDS` | Comma-separated owner user IDs | `123456789,987654321` |

### Optional Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `OPENROUTER_API_KEY` | OpenRouter API key for AI | - |
| `GEMINI_API_KEY` | Google Gemini API key | - |
| `OPENROUTER_MODEL` | Default AI model | `meta-llama/llama-3.3-70b-instruct:free` |
| `DB_PATH` | Custom database path | `database.db` |
| `HF_TOKEN` | HuggingFace token for DB sync | - |
| `HF_DB_REPO_ID` | HuggingFace repo for cloud sync | - |
| `PORT` | Keep-alive server port | `10000` |

## 📁 Project Structure

```
BOT-/
├── bot/
│   ├── cogs/           # Bot modules (cogs)
│   │   ├── admin.py
│   │   ├── ai_suite.py
│   │   ├── media.py
│   │   ├── community.py
│   │   └── ...
│   ├── utils/          # Utility modules
│   ├── locales/        # Translation files
│   ├── main.py         # Bot entry point
│   ├── config.py       # Configuration loader
│   ├── database.py     # Database layer
│   ├── emojis.py       # Emoji system
│   ├── i18n.py         # Translations
│   └── theme.py        # Styling & colors
├── requirements.txt
├── Dockerfile
├── render.yaml
├── .env.example
└── README.md
```

## 🎮 Available Commands

Once the bot is running, use `<prefix>menu` or `/menu` to see all available commands organized by category:

- **Music**: play, pause, skip, queue, volume, filters
- **Admin**: ban, kick, mute, warn, purge, backup
- **Fun**: 8ball, trivia, meme, roll, mario
- **AI**: chat, ask_image, imagine, summarize
- **Economy**: balance, daily, work, gamble, shop
- **Utility**: serverinfo, userinfo, ping, remind
- **Configuration**: set, language, setup

## 🛡️ Security Notes

- Never share your `DISCORD_TOKEN` or API keys
- Use `.env` file for sensitive configuration
- Set `OWNER_IDS` to restrict admin commands
- The bot uses SQLite with WAL mode for data integrity

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## 📝 License

This project is provided as-is for educational and community use.

## 🆘 Support

- Open an issue on GitHub for bug reports
- Check the wiki for common problems
- Use the bot's `/help` command for usage info

---

**Developed with ❤️ by Motaz**