From cd8ed8bc5793985df2c1692072a932ceee517b95 Mon Sep 17 00:00:00 2001 From: salmonik Date: Wed, 8 Jul 2026 02:13:35 +0200 Subject: OPEN THE RUST GATES Signed-off-by: salmonik --- AGENTS.md | 70 ++++++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 42 insertions(+), 28 deletions(-) (limited to 'AGENTS.md') diff --git a/AGENTS.md b/AGENTS.md index 5f62ec3..f5a78ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,33 +1,47 @@ -# Agent Instructions for Senator Sperma +# senator-sperma-rust — Agent Guide -## Required Setup -- Requires **Python 3.14** -- System dependencies: `ffmpeg`, `zbar` library (installed system-wide) -- Bot token in `.env` file (copy from `.env.example`) +## Project Map -## Commands -- Run bot: `.venv/bin/python main.py` -- Type check: `.venv/bin/basedpyright` -- Test: `.venv/bin/pytest` +``` +src/ +├── main.rs — Entry: init tracing, dotenvy, build Config/Data, start poise+serenity +├── config.rs — Config struct (env-driven), pub const TEMP_PATH +├── error.rs — Unified Error enum + From impls, pub type Result +├── commands/ +│ ├── mod.rs — all_commands() aggregates every submodule +│ ├── ai.rs — /senator (OpenRouter chat + optional TTS) +│ ├── cron.rs — /cron group (6 subcommands) +│ ├── math.rs — /math (qalc subprocess) +│ ├── music.rs — /play (🟡 stub), /stop, /join, /loop_toggle +│ ├── qr.rs — /qr encode + decode +│ ├── trigger.rs — /trigger group (6 subcommands) +│ ├── tts.rs — /tts (Google TTS → file/vc), /log_volume +│ ├── utilities.rs — compress🟡, convert🟡, upload, search, download, say +│ └── web.rs — /web (DuckDuckGo scrape) +├── copyparty/mod.rs — CopypartyClient (search, upload) +├── database/mod.rs — DbPool, 21 query fns, 6 tables, migration +├── events/mod.rs — handle_ready, handle_voice_state_update, handle_message +├── openrouter/mod.rs — OpenRouterClient (chat, chat_with_history) +├── tasks/mod.rs — cron_scheduler_loop (30s polling, stub exec bodies) +└── voice/mod.rs — VoiceManager (connect, disconnect, get_call), mp3_to_input +``` -## Architecture -- Slash commands defined as cogs in `cogs/*.py` -- Discord API uses `discord.ApplicationContext` -- Music auto-complete queries copyparty server (`COPYPARTY_URL` config) +## Key Conventions -## Environment -- Copyparty URL for read-only access is COPYPARTY_URL -- Copyparty URL for write-only access is COPYPARTY_URL_UPLOAD -- Above should be accessed using COPYPARTY_PASSWORD as a cookie -- Channel for vclogs and alike is STATUS_CHANNEL_ID -- Trigger word for assistant is ASSISTANT_KEYWORD +- **Framework**: poise 0.6 + serenity 0.12 + songbird 0.6 +- **DB**: sqlx 0.9 async SQLite (pool stored in `Data.db_pool`) +- **Errors**: `crate::error::Error` enum with `?` propagation; use `Error::Custom(string)` for ad-hoc +- **Shared state**: `Data` struct in `main.rs` — passed as poise `user_data` +- **Commands**: each submodule exports `pub fn commands() -> Vec>` +- **Temp path**: always use `crate::config::TEMP_PATH` (resolves to `/tmp/senator_sperma`) -## Testing -- Tests in `tests/cogs/test_*.py` -- Uses pytest-asyncio with `asyncio_default_fixture_loop_scope = function` -- `conftest.py` provides fixtures for mocking Discord objects -- **Slow integration tests** marked with `@pytest.mark.slow` - - Test real-world feature usage with longer execution times - - Includes: voice session tracking, cron job execution, music playback lifecycle, downloader flow, trigger responses - - Run only fast tests: `.venv/bin/pytest -m "not slow"` - - Run only slow tests: `.venv/bin/pytest -m slow` +## Stubs to Fill (see COMPARISON.md) +- `commands/music.rs` — `/play` is placeholder +- `commands/utilities.rs` — `/compress`, `/convert`, `/download` upload part +- `tasks/mod.rs` — cron execution bodies are `info!` only, no actual action + +## Database Tables +`settings` (key/value), `voice_activity`, `cron_jobs`, `triggers`, `trigger_keywords`, `trigger_responses` + +## All Commands (26 total) +`/senator`, `/cron` (6), `/math`, `/play`, `/stop`, `/join`, `/loop_toggle`, `/qr` (2), `/trigger` (6), `/tts`, `/log_volume`, `/compress`, `/convert`, `/upload`, `/search`, `/download`, `/say`, `/web` -- cgit v1.2.3