Repository Guidelines

Project Structure & Module Organization

yuuka/
├── main.py               # Bot entry point, cog loader, bridge initialization
├── cogs/                  # Discord command modules (general, sysinfo, gifs, etc.)
├── ai/                    # AI roleplay integration (DeepSeek API, per-channel personas)
│   └── personalities/     # Character prompt files
├── music/                 # Music playback subsystem (wavelink + yt-dlp + ffmpeg)
│   ├── player/            # Playback commands, events, queue management
│   ├── radio/             # Internet radio streaming
│   └── shared/            # Constants, shared state, utilities
├── tgbridge/              # Telegram ↔ Discord two-way message forwarding
├── twitterbridge/         # Twitter/X RSS feed → Discord webhook relay
├── rio/                   # SSH connection utilities
├── data/                  # Runtime persistence files (gitignored)
├── gifs/                  # GIF assets (gitignored)
└── credentials_test.env   # Environment variable template

Each cog is a self-contained commands.Cog subclass loaded in main.py. Bridge components run as background asyncio tasks.

Build, Test, and Development Commands

This is a personal bot with no formal build system. Run it directly:

python main.py

Copy credentials_test.env → credentials.env and fill in your tokens.
There is no test suite. Test by running the bot locally and using !-prefixed commands in a Discord server.

Coding Style & Naming Conventions

Language: Python 3.12+
Indentation: 4 spaces
Naming: snake_case for files, variables, and functions; PascalCase for classes; UPPER_CASE for constants
Cogs: One class per file in cogs/, subclassing commands.Cog, loaded via await bot.load_extension('cogs.<name>')
Music subpackage: Uses mixin-based composition — Music inherits from several command/event mixins
Async: All I/O uses async/await; bridge tasks run with asyncio.create_task()
No linter or formatter is currently configured

Testing Guidelines

No formal test framework is in place. When adding or changing features, validate manually:

Start the bot locally with a test Discord token.
Exercise each affected command in a private server.
For music/radio, test with different stream types (YouTube, direct audio URLs, radio streams).
For bridges, confirm messages flow correctly in both directions.
Check the console for unhandled exceptions — the logging level is INFO.

Commit & Pull Request Guidelines

This is a personal repository with informal conventions:

Commit messages: Short, lowercase, imperative mood (e.g., fix radio race conditions, add radio mode). No strict format is enforced.
Branches: Work directly on master or use short-lived feature branches.
PRs: Not used — the project is single-contributor.
Before committing: Ensure the bot starts without import errors and any changed cogs load successfully.

Environment & Secrets

Store secrets in credentials.env (gitignored). The template is credentials_test.env.
Required: DISCORD_TOKEN, OWNER_ID. Optional: TELEGRAM_BOT_TOKEN, TWITTER_RSS_URL, DEEPSEEK_API, and webhook URLs.
The bot is managed as a systemd service on Arch Linux and updated via git pull over SSH (the !gitpull cog handles remote updates).

3.4 KiB Raw Blame History