🎵 MikuBot — Discord AI Chatbot

A Hatsune Miku-themed Discord AI chatbot powered by Groq — with smart model routing, memory, TTS, and a web dashboard.

---

✨ Features

• 🤖 Smart Model Routing — Automatically picks the best AI model based on your message:
  • Llama 4 Scout → Quick replies
  • GPT OSS 120B → Deep reasoning & code
  • Kimi K2 → Long conversations (10+ messages)
• 🧠 Persistent Memory — Miku remembers facts about each user via [remember:key=value] tags
• 🎭 Emotion-aware GIFs — Detects mood from responses and sends matching Hatsune Miku GIFs via Giphy
• 🔊 Text-to-Speech — Supports ElevenLabs, Groq PlayAI (English & Arabic)
• 👁️ Vision Support — Send images and Miku will analyze them
• 📊 XP & Levelling System — Users earn XP from chatting
• 🌐 Web Dashboard — Manage system prompt, models, memory, and activity status via browser
• 💾 Dual Database — SQLite for local hosting, Supabase for cloud deployment

---

🛠️ Tech Stack

Component	Technology
Bot Framework	discord.py
Web Dashboard	Quart (async Flask)
AI Backend	Groq API
Database	aiosqlite / Supabase
TTS	ElevenLabs / Groq PlayAI
GIFs	Giphy API

---

🚀 Setup

1. Clone the repo

git clone https://github.com/M5Develop/MikuBot-Discord.git
cd MikuBot-Discord

2. Install dependencies

pip install -r requirements.txt

3. Configure environment

cp .env.example .env

Then fill in your keys in .env.

4. Run

python main.py

The bot will start and the dashboard will be available at http://localhost:8000/dashboard

---

🔑 Environment Variables

Variable	Required	Description
DISCORD_TOKEN	✅	Your Discord bot token
GROQ_API_KEY	✅	Groq API key (free at console.groq.com)
GIPHY_API_KEY	⚠️ Optional	For animated Miku GIF responses
ELEVENLABS_API_KEY	⚠️ Optional	For ElevenLabs TTS
ELEVENLABS_VOICE_ID	⚠️ Optional	ElevenLabs voice ID
SUPABASE_URL	⚠️ Optional	Supabase URL (cloud mode)
SUPABASE_KEY	⚠️ Optional	Supabase anon key (cloud mode)

Note: If SUPABASE_URL and SUPABASE_KEY are not set, the bot automatically uses local SQLite — no setup needed!

---

💬 How to Use

Mention the bot or DM it to start a conversation:

@MikuBot Hey, what's the difference between a stack and a queue?
@MikuBot [attach image] What's in this image?

Dashboard Controls

• Update Miku's personality/system prompt
• Switch AI models manually or set to auto-routing
• Enable/disable TTS and choose voice engine
• View top fans (XP leaderboard)
• Browse and delete user memories
• Clear chat history per user

---

🗂️ Project Structure

MikuBot-Discord/
├── main.py              # Entry point — bot + Quart dashboard
├── database.py          # MikuMemory class (SQLite + Supabase)
├── requirements.txt
├── .env.example
├── cogs/
│   ├── ai_chat.py       # Core AI chat, routing, TTS, GIFs, memory
│   ├── levelling.py     # XP system
│   └── voice.py         # Voice channel features
└── templates/
    ├── dashboard.html
    └── layout.html

---

🧠 Memory System

Miku can remember facts mid-conversation. Just say something like:

"My favorite color is teal"

And Miku will internally tag [remember:favorite_color=teal] and recall it in future messages.

Memories can be viewed and deleted from the dashboard.

---

🏠 Self-Hosting

Works great on:

• Your own PC / Linux server
• Railway
• Koyeb
• Render

---

📄 License

MIT — free to use, modify, and build on.

---

Made with 💙 by M5Develop | HuggingFace