Niko is a warm, café-themed Discord bot built on discord.py 2.7+ and Python 3.10+. Powered by any OpenAI-compatible API, he holds natural conversations, remembers each user’s history, and adapts his personality based on a favorability score. With 76 slash commands spanning 20+ cog groups and full support for English, German, and Spanish, Niko brings a cozy lo-fi aesthetic and production-grade tooling to any community — all from an instance you host yourself.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/developer51709/Niko/llms.txt
Use this file to discover all available pages before exploring further.
Niko is entirely self-hosted. There is no shared cloud service — you run your own copy of the bot, keeping full control of your data, your API keys, and your configuration.
Feature Areas
🧠 AI & Chat
OpenAI-compatible conversational AI with per-user memory, favorability scoring, trilingual auto-detection (EN / DE / ES), and
/imagine image generation.💰 Economy
A premium economy system with PIL wallet cards, an 8-tier job ladder, 5-tier bank vaults with compound interest, a shop, weekly lottery, 15+ achievements, and full transaction history.
🛡️ Moderation
Kick, ban, mute, tempmute, warn, purge, slowmode, lock — plus an AutoMod dashboard with anti-spam, anti-link, bad-word filters, mass-mention protection, and external-app raid defence.
🎵 Music
Lavalink / wavelink audio with YouTube, Spotify, and direct-URL support, three-state loop, queue shuffle, volume control, a live now-playing card, and Last.fm autoplay top-up.
🎉 Community
Giveaways with join requirements, persistent ticket system, live polls, suggestions board, starboard, tags, birthday announcements, highlights, reminders, and social-media feed notifiers.
⭐ Leveling
Per-message XP with configurable multiplier and cooldown, role rewards at custom thresholds, guild-level toggles, announcement channels, and an interactive
!levelpanel management UI.🎰 Casino
Blackjack, Slots, and Roulette — each rendered with PIL image cards and fully integrated with the economy system, configurable cooldowns, and per-server balance stakes.
🎊 Fun
Roleplay actions (hug, pat, boop), memes, animal images, AFK mode, message snipe, and a variety of lighthearted commands to keep your community entertained.
Architecture
Niko uses discord.py’s Cog system to split functionality into self-contained, independently loadable modules. A Cog is a Python class that groups related commands, event listeners, and background tasks. Every Cog lives undersrc/cogs/ in its own subdirectory and is discovered and loaded automatically at startup by src/bot.py — the single entry point for the entire application.
The entry point (src/bot.py) is responsible for:
- Loading environment variables from
src/.env - Configuring gateway intents (message content, presences, members, moderation)
- Instantiating
commands.AutoShardedBotwith a dynamic prefix resolver - Registering a slash-command blacklist gate via
bot.tree.interaction_check - Triggering cog discovery and slash-command global sync on
on_ready
| Cog | Responsibility |
|---|---|
admin | Admin tools, prefix management |
ai | AI chat, memory, favorability, image generation |
automod | AutoMod dashboard, raid protection |
casino | Blackjack, Slots, Roulette, mini-games |
economy | Balance, jobs, bank, shop, lottery, achievements |
fun | Roleplay, memes, animals, AFK, snipe |
giveaway | CV2 giveaway setup with join requirements |
help | Dynamic help system |
info | Serverinfo, userinfo, avatar |
leveling | XP, levels, leaderboard, level panel |
logging | Event logger (join/leave/edit/delete) |
moderation | Kick, ban, warn, mute, purge, mod-log |
music | Lavalink/wavelink music player |
notifier | Social media feed subscriptions |
onboarding | Verification, captcha, role assignment |
social | Polls, suggestions, starboard, tags, highlights |
system | Error handler, AI debugging reporter |
tickets | Persistent ticket system |
utility | Reminders, birthdays, translate, define |
voicemaster | Dynamic voice channel creation |
donations | Donation commands and payment integration |
legal | Legal information and compliance commands |
Data Storage
Niko persists all state as flat files inside thedata/ directory — no external database server required. Structured relational data (giveaways) uses an embedded SQLite database via aiosqlite, while everything else is stored as JSON.
| File / Path | Contents |
|---|---|
data/database.db | Giveaway entries and winners (SQLite) |
data/levels.json | Per-guild, per-user XP and level records |
data/level_config.json | Per-guild leveling settings (toggle, channel, multiplier) |
data/mod_config.json | Per-guild moderation and AutoMod configuration |
data/warnings.json | Per-user warning records with moderator attribution |
data/ticket_config.json | Per-guild ticket panel and support-role settings |
data/reminders.json | Scheduled personal DM reminders |
data/tags.json | Per-guild custom text tag snippets |
data/birthdays.json | User birthday registrations |
data/highlights.json | Per-user keyword notification subscriptions |
data/polls.json | Active and archived poll data |
data/suggestions.json | Suggestion submissions and admin review state |
data/starboard.json | Starboard channel config and mirrored message IDs |
data/economy_data/ | Per-user economy profiles (one JSON file per user) |
UI System
All user-facing responses are built with discord.ui.LayoutView — discord.py’s Components v2 API — rather than plain embeds. This enables richer, more interactive layouts:- Containers — scoped visual panels with configurable colour accents matched to the context (economy gold, moderation red, music purple, etc.)
- Text displays — structured text sections and separator lines for clean information hierarchy
- Media galleries — inline image rendering for PIL-generated cards (wallet, leaderboard, casino results, now-playing)
- Action rows with buttons — persistent interactive controls for music playback, ticket management, giveaway entry, and paginator navigation
- Paginated views — a shared
PaginatedViewutility (src/utils/paginator.py) used across leaderboards, command lists, and queue displays to page through long result sets without cluttering a channel
Technology Stack
| Technology | Role |
|---|---|
| Python 3.10+ | Runtime language |
| discord.py 2.7+ | Discord gateway, slash commands, Components v2 UI |
| wavelink | Lavalink client for high-quality audio streaming |
| OpenAI-compatible API | Conversational AI, image generation (/imagine) |
| Flask | Static web server for the public landing page and dashboard |
| Pillow | Server-side PIL image card rendering (economy, casino, music) |
| aiosqlite | Async SQLite driver for giveaway data |
| deep-translator | Automatic language translation for trilingual responses |
| spotipy | Spotify metadata resolution for music playback |
| python-dotenv | Environment variable loading from src/.env |
| langdetect | Automatic language detection for i18n routing |