pybyultima / BotHub

Local-first desktop app for managing many Telegram bots.

• Core: FastAPI + aiogram 3.x + SQLAlchemy 2.0 (sqlite/aiosqlite). Owns Telegram long-polling for every registered bot.
• Local SDK (bothub_sdk): user-written bot scripts connect to the Core via WebSocket; they never talk to Telegram directly.
• Middleware pipeline (runs Core-side before each update reaches user code): CrossBan → ZeroDowntime buffer → HumanHandoff → A/B testing → plugin fan-out → SDK emit.
• Frontend: React 18 + React Flow + zustand; packaged with Tauri for desktop.

Quick start (Windows / PowerShell)

python -m venv .venv
. .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt -r requirements-dev.txt
pip install -e .\sdk
alembic upgrade head
.\scripts\dev_backend.ps1

Frontend in another terminal:

.\scripts\dev_frontend.ps1

Example user bot (after pip install -e ./sdk):

python -m bothub_sdk.examples.minimal_bot --bot-id bot_123 --token <real-token>

Optional toy plugin server (for plugin pipeline manual smoke tests):

python -m scripts.toy_plugin --port 9100 --action block

REST surface

Route	Purpose
GET /api/bots	list registered bots + derived status
POST /api/bots/add	register a new bot token
POST /api/bots/{id}/start / /stop	control polling
DELETE /api/bots/{id}	unregister a bot
POST /api/buffer/flush	manually replay MessageBuffer rows
GET /api/bans, POST /api/bans/add, DELETE /api/bans/{user_id}	global cross-bot ban list
GET /api/handoff, POST /api/handoff/toggle, POST /api/handoff/send	human takeover of a chat
GET /api/ab_tests, POST /api/ab_tests/create, DELETE /api/ab_tests/{id}	A/B splits
GET /api/plugins, POST /api/plugins, DELETE /api/plugins/{id}	plugin registry
POST /api/licenses/bind, POST /api/licenses/unbind	bind a plugin to a bot

WebSocket surface

Path	Direction	Payload
/ws/sdk/{bot_id}	Core ↔ user SDK	UpdateEnvelope (live + replay), Ack, Error, Ping/Pong
/ws/ui_status	Core → UI	routing, bot_state, buffer, blocked events
/ws/ui_handoff/{bot_id}	Core → UI	per-user message events (Telegram → operator)

Tests

. .\.venv\Scripts\Activate.ps1
pytest backend/tests

Tauri packaging (M7)

See frontend/src-tauri/README.md for instructions on building the bothub-core sidecar executable with PyInstaller and bundling it via npm run tauri build.

License

MIT