Metadata-Version: 2.4
Name: ember-discord-bot
Version: 1.3.0
Summary: A modular Discord bot framework for The Aakhri Station
Author-email: The Aakhri Station <contact@aakhristation.com>
License: Unlicense
Project-URL: Homepage, https://github.com/The-Aakhri-Station/Ember-staging
Project-URL: Documentation, https://github.com/The-Aakhri-Station/Ember-staging#readme
Project-URL: Repository, https://github.com/The-Aakhri-Station/Ember-staging.git
Project-URL: Issues, https://github.com/The-Aakhri-Station/Ember-staging/issues
Keywords: discord,discord-bot,discord.py,moderation,community,ai
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: License :: Public Domain
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: discord.py>=2.3.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pytz>=2024.1
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: emoji>=2.9.0
Requires-Dist: nltk>=3.8.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: chat-exporter>=2.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: openai>=1.12.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: dateparser>=1.2.0
Requires-Dist: b2sdk>=1.24.0
Requires-Dist: schedule>=1.2.0
Provides-Extra: dev
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: black>=24.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: safety>=3.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Provides-Extra: testing
Requires-Dist: pytest>=8.0.0; extra == "testing"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "testing"
Provides-Extra: docs
Requires-Dist: sphinx>=7.2.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Requires-Dist: furo>=2024.1.29; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.25.0; extra == "docs"
Provides-Extra: genai
Requires-Dist: groq>=0.4.0; extra == "genai"
Requires-Dist: openai>=1.12.0; extra == "genai"
Requires-Dist: transformers>=4.38.0; extra == "genai"
Provides-Extra: rpc
Dynamic: license-file

<h1 align="center">
  <br>
  🔥 Ember
  <br>
</h1>

<h4 align="center">Modular. Modern. Production-ready Discord bot framework.</h4>

<p align="center">
  <a href="https://www.python.org/downloads/">
    <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white">
  </a>
  <a href="https://github.com/Rapptz/discord.py/">
    <img src="https://img.shields.io/badge/discord.py-2.4%2B-5865F2?logo=discord&logoColor=white" alt="discord.py">
  </a>
  <a href="http://unlicense.org/">
    <img src="https://img.shields.io/badge/license-Unlicense-green" alt="Unlicense">
  </a>
  <a href="https://github.com/astral-sh/ruff">
    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
  </a>
</p>

<p align="center">
  <a href="https://github.com/guardiansofspartax/Ember/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/guardiansofspartax/Ember/ci.yml?label=CI" alt="CI">
  </a>
  <a href="https://github.com/psf/black">
    <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style: Black">
  </a>
  <a href="http://makeapullrequest.com">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
  </a>
  <a href="https://github.com/pre-commit/pre-commit">
    <img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white" alt="pre-commit">
  </a>
</p>

<p align="center">
  <a href="#overview">Overview</a>
  •
  <a href="#cogs">Cogs</a>
  •
  <a href="#quick-start">Quick Start</a>
  •
  <a href="#docker">Docker</a>
  •
  <a href="#plugins">Extras</a>
  •
  <a href="#development">Development</a>
  •
  <a href="#credits">Credits</a>
</p>

---

## Overview

Ember is a fully modular Discord bot built on [discord.py](https://github.com/Rapptz/discord.py) 2.4+ and [Components V2](https://discordpy.readthedocs.io/en/stable/interactions/api.html). Every feature is a self-contained cog — enable or disable anything without touching the core. It ships with a real permissions framework, per-guild config, a central modlog, and a service-layer architecture that keeps business logic testable and clean.

> Inspired by [Red-DiscordBot](https://github.com/Cog-Creators/Red-DiscordBot)'s battle-tested patterns, built clean from scratch with modern Python and async-first design.

**The default cog set includes:**

- Moderation (warn, mute, ban, kick, modlog with case cards)
- Community tools (birthdays, AFK, booster roles, welcome messages, activity roles)
- Utility (temp voice channels, thread cleaner, custom commands, channel management)
- Fun (game pings, emoji stealer, general commands)
- Economy (bank, credits)
- Integrations (Twitch streams, GitHub→Discord, DuckDNS, backups)

**Extra plugins** (privacy-sensitive features, shipped separately in [Ember-extras](../Ember-extras)):

- [Confessions](../Ember-extras/confessions) — anonymous confession system with replies and mod tools
- [ShadowChat](../Ember-extras/shadowchat) — anonymous gender-matched chat roulette with DM relay

---

## Cogs

<details>
<summary><strong>admin</strong> — Bot management and configuration</summary>

| Cog | Description |
|-----|-------------|
| `cleanup` | Bulk message deletion and channel pruning |
| `cog_manager` | Load, unload, and reload cogs at runtime |
| `dev` | Developer utilities and debug commands |
| `downloader` | Install cogs from external repositories |
| `permissions_mgr` | Fine-grained per-guild permission overrides |
| `settings` | Bot-wide and per-guild configuration panel |

</details>

<details>
<summary><strong>community</strong> — Engagement and social features</summary>

| Cog | Description |
|-----|-------------|
| `activity_roles` | Auto-assign roles based on game activity |
| `afk` | AFK status with auto-mention suppression |
| `birthday` | Birthday tracking, announcements, and role assignment |
| `booster_roles` | Custom colour roles for server boosters |
| `promoter` | Self-promotion channel with cooldown management |
| `welcome` | Configurable welcome embeds and DMs for new members |

</details>

<details>
<summary><strong>mod</strong> — Moderation and logging</summary>

| Cog | Description |
|-----|-------------|
| `moderation` | Warn, mute, kick, ban, softban with case tracking |
| `modlog` | Central moderation log with sequential case cards |
| `bot_logging` | Audit log mirroring and event logging |
| `branding` | Server branding enforcement and asset management |
| `filter` | Word/phrase filter with configurable actions |
| `reports` | User report system with staff escalation |

</details>

<details>
<summary><strong>utility</strong> — Quality-of-life tools</summary>

| Cog | Description |
|-----|-------------|
| `channels` | Channel lock/unlock and management shortcuts |
| `customcom` | Custom slash commands with variable substitution |
| `dragme` | Move users between voice channels |
| `feedback` | Structured feedback collection with staff routing |
| `multi_lounge` | Multiple persistent lounge channels |
| `nick` | Server-wide nickname management |
| `rolementions` | Temporarily mentionable role toggle |
| `status` | Rotating bot status messages |
| `tempvc` | Dynamic temporary voice channel creation |
| `thread_cleaner` | Auto-archive or delete inactive threads |

</details>

<details>
<summary><strong>fun</strong> — Entertainment</summary>

| Cog | Description |
|-----|-------------|
| `emoji_stealer` | Steal and add emojis from other servers |
| `game_ping` | Game-activity-based role ping system |
| `general` | Miscellaneous fun commands |
| `ping` | Latency check with gateway and API round-trip |

</details>

<details>
<summary><strong>economy</strong> — Virtual currency</summary>

| Cog | Description |
|-----|-------------|
| `bank` | Virtual bank with credits, transfers, and leaderboard |

</details>

<details>
<summary><strong>integrations</strong> — External service connectors</summary>

| Cog | Description |
|-----|-------------|
| `backups` | Automated database backups to Backblaze B2 |
| `duckdns` | DuckDNS IP updater for dynamic DNS |
| `reconnect` | Auto-reconnect watchdog for gateway drops |
| `streams` | Twitch live-stream alerts |

</details>

---

## Quick Start

### Prerequisites

- Python 3.11 or higher
- A Discord bot token — create one at the [Developer Portal](https://discord.com/developers/applications)
- Enable **Message Content**, **Server Members**, and **Presence** intents

### Install

```bash
git clone https://github.com/guardiansofspartax/Ember.git
cd Ember
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

Edit `.env` — at minimum, set `BOT_TOKEN`:

```env
BOT_TOKEN=your_discord_bot_token_here

# Optional but recommended
OWNER_IDS=111111111111111111
GUILD_ID=123456789012345678        # dev guild for instant slash command sync
EMBER_DB_BACKEND=sqlite            # sqlite | postgres | mongo
```

### Run

```bash
python main.py          # load all cogs
python main.py birthday # load one cog (dev/debug)
```

On first start, slash commands sync to your dev guild instantly. Global sync takes up to one hour.

---

## Docker

```bash
# Production
docker compose --profile production up -d

# Development (code mounted, auto-reload)
docker compose --profile development up
```

See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for full Docker, PM2, and systemd deployment guides.

---

## Plugins

Privacy-sensitive cogs live in the separate [Ember-extras](../Ember-extras) repository so the core stays clean and auditable.

Install a plugin:

```bash
# Clone extras next to Ember
git clone https://github.com/guardiansofspartax/Ember-extras.git ../Ember-extras

# Symlink (or copy) the plugin into cogs/
ln -s ../../Ember-extras/confessions cogs/community/confessions
```

Then restart the bot — Ember's auto-loader will pick it up.

---

## Development

```bash
make install        # create venv + install all deps
make pre-commit     # install git hooks

make lint           # ruff + black + mypy
make test           # pytest
make test-cov       # pytest with coverage report
make security       # bandit + pip-audit + safety
make dev-checks     # everything above together
```

### Adding a Cog

```
cogs/<category>/<cog_name>/
├── __init__.py    # async setup(bot)
├── cog.py         # EmberCog subclass with commands
└── service.py     # business logic (optional, recommended)
```

```python
from discord import app_commands
from core.cog import EmberCog
from core.permissions import PermissionLevel, requires

class MyCog(EmberCog):
    @app_commands.command(name="hello", description="Say hello")
    @requires(PermissionLevel.USER)
    async def hello(self, interaction: discord.Interaction) -> None:
        await self.send_success(interaction, f"Hey, {interaction.user.mention}!")

async def setup(bot):
    await bot.add_cog(MyCog(bot))
```

See [docs/COG_CONTRIBUTION.md](docs/COG_CONTRIBUTION.md) for the full guide and [docs/FRAMEWORK_API.md](docs/FRAMEWORK_API.md) for the API reference (Store, cards, errors, checks, modlog, bank, i18n, formatting).

---

## Project Structure

```
Ember/
├── cogs/                  # All bot extensions (auto-discovered)
│   ├── admin/
│   ├── community/
│   ├── economy/
│   ├── fun/
│   ├── integrations/
│   ├── mod/
│   └── utility/
├── core/                  # Framework internals
│   ├── bot.py             # EmberBot — subclasses discord.ext.commands.Bot
│   ├── cog.py             # EmberCog base class
│   ├── database.py        # Multi-backend DatabaseManager (sqlite/pg/mongo/json)
│   ├── permissions.py     # @requires() decorator + PermissionLevel enum
│   ├── modlog.py          # Central moderation logging
│   ├── rpc.py             # JSON-RPC 2.0 server (optional)
│   └── errors.py          # Exception hierarchy
├── utils/                 # Shared helpers
│   ├── cards.py           # LayoutView card builders (Components V2)
│   ├── views.py           # Reusable UI views
│   └── validators.py      # Input validation utilities
├── config/                # Environment and startup config
├── docs/                  # Guides and architecture docs
├── scripts/               # CLI utilities (ember.py, dev_utils.py)
├── test/                  # Test suite
├── main.py                # Entry point
├── Dockerfile
├── docker-compose.yml
└── .env.example
```

---

## Credits

Ember is built on the shoulders of giants:

- **[discord.py](https://github.com/Rapptz/discord.py)** by Rapptz — the async Discord library powering everything
- **[Red-DiscordBot](https://github.com/Cog-Creators/Red-DiscordBot)** by the Cog Creators team — architectural inspiration for the cog system, permissions model, and modlog design
- **[Pycord](https://github.com/Pycord-Development/pycord)** — reference for Components V2 UI patterns

---

## License

Released into the public domain under the [Unlicense](LICENSE).

---

## Support

- Issues: [GitHub Issues](https://github.com/guardiansofspartax/Ember/issues)
- Discord: [The Aakhri Station](https://discord.gg/aakhristation)
- Docs: [`docs/`](docs/)
