50 lines
3.0 KiB
Markdown
50 lines
3.0 KiB
Markdown
# UMB Bot - Agent Quickstart
|
|
|
|
## Environment & Setup
|
|
- `source .venv/bin/activate` before running or testing anything
|
|
- `.env` is gitignored; API keys and tokens live there (verified read-only)
|
|
- Database: SQLite at `bot/data/umb.db`; initialized automatically on boot via `init_db()`
|
|
- **Proxy required**: bot is designed for regions with Telegram blocks (Russia/CIS). All outbound traffic (Telegram API, OpenRouter model fetch, AI requests, Whisper model download) goes through SOCKS5 proxy configured in `.env` via `PROXY_ENABLED=true` and `PROXY_URL`.
|
|
|
|
## Exact Command to Run
|
|
```bash
|
|
python main.py
|
|
```
|
|
No separate test/lint/formatter/config commands defined in repo.
|
|
|
|
## Architecture Snapshot
|
|
- **Entry**: `main.py` → `asyncio.run(main())`
|
|
- **Boot sequence**: `init_db()` → proxy setup (if enabled) → `dp.start_polling(bot)`
|
|
- **Routers** (included in order in `main.py`):
|
|
1. `moderation.py` — sticker/GIF flood detection (25 in 60s → 5min ban)
|
|
2. `layout.py` — `/start`, `/res` (en→ru layout converter in `layout_converter.py`)
|
|
3. `weather.py` — `/weather <city>` via OpenWeatherMap
|
|
4. `ai.py` — `/ai`, `/aino`, `/aiyes` (AI assistant "Astra")
|
|
5. `voice.py` — auto-transcribes all voice messages via local faster-whisper (no proxy needed)
|
|
|
|
## Voice Recognition
|
|
- **Local**: faster-whisper model `base` (~2.5 GB) auto-downloaded on first voice message to `models/faster-whisper/` (portable, next to the bot)
|
|
- **Model download**: uses `ALL_PROXY` env var + PySocks to route through SOCKS5 proxy
|
|
- **Voice files**: temporarily stored in `bot/data/voice/`, deleted after transcription
|
|
- **Flow**: download OGG from Telegram → ffmpeg to WAV → transcribe locally → post raw text to chat
|
|
- **Normalization**: capitalize first letter, trailing period, collapse whitespace
|
|
- **No proxy** used for actual transcription (fully local on CPU)
|
|
|
|
## AI Assistant "Astra" Gotchas
|
|
- **Free models**: fetched dynamically from OpenRouter API (`:free` suffix), cached 1 hour. Fallback to hardcoded list if API unavailable.
|
|
- **Paid fallback**: `routerai.ru` if all free fail (adds `⚡ Обработано через платный API` suffix)
|
|
- **Context**: Last 10 messages per user/chat stored in SQLite (`user_context` table)
|
|
- **System prompt**: brief, helpful, reply with "я потеряла мысль"/"смотри, какая птичка!" when context lost
|
|
- **Block system**: `/aino @user` blocks 24h (creator only); `/aiyes @user` unblocks
|
|
- **Rate-limit behavior**: automatically rotates models on 429 errors
|
|
|
|
## DB Tables (source of truth)
|
|
- `user_context` — messages for AI context (user_id, chat_id, text, role, timestamp)
|
|
- `ai_blocked_users` — AI bans (user_id, chat_id, blocked_by, blocked_at, expires_at)
|
|
- `sticker_bans` — sticker flood bans (user_id, chat_id, count, start_time, ban_until, ban_trigger)
|
|
|
|
## Run on change
|
|
1. Edit source
|
|
2. Restart bot (`Ctrl+C` then `python main.py`)
|
|
3. DB schema updates via `await init_db()` → `Base.metadata.create_all()` (no migrations)
|