umb/AGENTS.md

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

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)