OPEN THE RUST GATES

Signed-off-by: salmonik <raisersoft@proton.me>

1 files changed, 95 insertions, 64 deletions

diff --git a/README.md b/README.md
index e9cf127..9b1fea9 100644
--- a/README.md
+++ b/README.md
@@ -1,92 +1,123 @@
-# Senator Sperma
+# Senator Sperma (Rust)
 
-A Discord bot with music playback, TTS, web search, and utility commands.
+A Discord bot rebuilt in Rust from the original Python implementation. Music
+playback via songbird, AI chat via OpenRouter or anything OpenAI compatible (ollama.cpp and such), TTS, web/file search
+scheduled jobs, per-server triggers, QR codes, media conversion, and misc utilities.
 
-Requires Python 3.14.
+Built on poise 0.6 + serenity 0.12 + songbird 0.6, with async SQLite (sqlx 0.9)
+for persistence.
 
 ## Setup
 
-### 1. Clone & Create Virtual Environment
+### 1. Clone
 
 ```bash
 git clone https://codeberg.org/salmonik/senator-sperma
 cd senator-sperma
-python -m venv .venv
-source .venv/bin/activate  # Linux/macOS
-# or .venv\Scripts\activate  # Windows
 ```
 
-### 2. Install Dependencies
+### 2. System Dependencies
 
-```bash
-pip install -r requirements.txt
-```
+The following binaries must be available on `PATH`:
+
+- `ffmpeg` — audio decoding/encoding for playback, conversion, and compression
+- `qalc` (Qalculate) — used by `/math` to evaluate expressions
+- `yt-dlp` (optional) — used by `/download`
 
-You also need `ffmpeg` and `zbar` library and installed system-wide
+Unlike the Python version, QR encode/decode is handled by the pure-Rust
+`qrcode`/`rxing` crates — no `zbar` system library required.
 
-### 3. Create .env File
+### 3. Build
 
-Create a `.env` file in the project root:
+Requires a recent Rust toolchain (edition 2024).
 
 ```bash
-cp .env.example .env
+cargo build --release
 ```
 
-Edit `.env` with your credentials:
+### 4. Configure Environment
 
-```env
-# Required
-TOKEN=your_discord_bot_token
+Create a `.env` in the project root
+look at `.env.example` on what to put there
 
-# Optional - Bot Configuration
-STATUS_CHANNEL_ID=123456789012345678  # Channel for startup message
-ASSISTANT_KEYWORD=jarvis  # Keyword to trigger AI assistant
+On launch, missing variables are reported via tracing (`error!` for required,
+`warn!` for optional with defaults). The database and schema migrations are
+created automatically on first run.
 
-# Optional - File Server (for music /search commands)
-COPYPARTY_URL=http://localhost:8080
-COPYPARTY_PASSWORD=your_password
-
-# Optional - AI commands
-OPENROUTER_API_KEY=
-```
-
-### 6. Run the Bot
+### 5. Run
 
 ```bash
-python main.py
+cargo run --release
 ```
 
-## Configuration
-
-All settings are optional - defaults are provided if not set.
-
-| Variable | Description | Default |
-|---------|-------------|---------|
-| `TOKEN` | Discord bot token | (required) |
-| `STATUS_CHANNEL_ID` | Channel for startup message | none |
-| `ASSISTANT_KEYWORD` | Keyword to trigger AI assistant | `jarvis` |
-| `COPYPARTY_URL` | File server base URL | `http://localhost:8080` |
-| `COPYPARTY_PASSWORD` | File server password | none |
-| `OPENROUTER_API_KEY` | AI API key (for /senator command) | none |
-
 ## Commands
 
-### Music
-- `/play` - Play music from file server or an internet audio stream
-- `/stop` - Stop playback
-- `/join` - Join voice channel
-- `/loop` - Loop current track
-
-### Utility
-- `/search` - Search files on server
-- `/web` - DuckDuckGo search
-- `/download` - Download video/audio
-- `/tts` - Text to speech
-- `/qr_koduj` / `qr_dekoduj` - QR encode/decode
-- `/kompresja` - Compress images
-- `/konwersja` - Convert audio/video
-
-## Dependencies
-
-- `ffmpeg` - System-wide audio processing
-- `py-cord` - Discord library (due to instable nature of discord's voice features, py-cord has to be installed directly from git)
+Slash commands are autoregistered globally on startup. Some are registered
+under their original Polish verb names to match the UI expected by existing
+servers.
+
+### AI
+- `/senator` — chat with the OpenRouter model
+
+### Music (songbird)
+- `/grajcuj` — play from Copyparty search, a direct URL, or an uploaded file
+- `/stop` — stop playback and leave voice
+- `/join` — join the caller's voice channel
+
+### TTS
+- `/tts` — Google Translate TTS (Polish), sent as a file or played in voice
+
+### Search & Web
+- `/web` — DuckDuckGo HTML scrape (soon to use 4get)
+- `/search` — search Copyparty and return a direct download URL
+- `/download` — fetch media from any yt-dlp-supported URL
+
+### Media Tools
+- `/compress` (alias `kompresja`) — compress a media attachment to low quality
+- `/convert` (alias `konwersja`) — convert media between formats
+
+### Utilities
+- `/upload` — push Discord attachments into Copyparty
+- `/say` — repeat the given text as the bot
+- `/math` — evaluate an ASCII math expression through `qalc`
+- `/qr generowanie` / `/qr dekodowanie` — QR encode / decode
+
+### Triggers
+- `/trigger create` — new trigger group
+- `/trigger add` — add keywords/responses to a group
+- `/trigger remove` — remove a keyword/response
+- `/trigger delete` — delete a group
+- `/trigger list` — list a group's keywords and responses
+- `/trigger help` — usage info
+
+### Cron
+- `/cron dodaj_audio` — schedule audio playback
+- `/cron dodaj_wiadomość` — schedule a periodic message
+- `/cron pokaż` — list all cron jobs
+- `/cron usuń` — remove a cron job
+- `/cron pauza` — pause a job
+- `/cron wznów` — resume a job
+
+### Message Context Menu
+- "Wyślij załączniki" (right-click message) — upload attachments to Copyparty
+- "kompresja" (right-click message) — compress all attachments
+
+## Architecture
+
+The runtime is organised around a shared `Data` struct (poise `user_data`)
+that holds the DB pool, HTTP client, Copyparty client, voice manager, the
+in-memory trigger cache, autocomplete cache, and per-guild music track handles.
+
+- `src/main.rs` — boot: tracing, dotenvy, Config, DB pool, framework, cron task
+- `src/config.rs` — env-driven `Config` + variable validation
+- `src/commands/` — one module per command group
+- `src/copyparty/` — Copyparty search/upload client
+- `src/openrouter/` — OpenRouter chat client
+- `src/database/` — sqlx pool, migrations, query helpers (6 tables)
+- `src/voice/` — `VoiceManager`, mp3 → songbird input
+- `src/events/` — `handle_ready`, voice-state, message (trigger matching)
+- `src/tasks/` — 30s cron scheduler poll loop
+- `src/lang.rs` — user-facing Polish strings
+
+All temporary files go through `crate::config::TEMP_PATH`
+(`/tmp/senator_sperma`).