Six ready-to-run Telegram bots in one repo - voice summaries, tasks, image generation, booking, alerts and health reports. One docker compose service per bot.
Quick start · The bots · How it works · Русский
| Bot | What it does | Stack | Example |
|---|---|---|---|
| 🎙 voice-summarizer | Voice message in, structured summary out; "story" sessions with a named speaker | Python, Groq Whisper, OpenRouter | [voice 2 min] → "Key points: delivery moves to Friday; budget unchanged" |
| ✅ taskflow | Task manager: projects, deadlines, invites, recurring tasks, voice input, AI task analysis | Python, PostgreSQL, whisper.cpp, OpenRouter | [voice] "invoice by Thursday, high priority" → task with deadline |
| 🍌 banana-studio | Generate, edit and restyle images with Nano Banana; daily limits, tiers, admin panel | Python, aiohttp, kie.ai | "corgi astronaut, film still" → image + ratio buttons |
| 💅 salon-booking | AI receptionist that books appointments by text or voice | Python, SQLite, OpenRouter | "manicure with Maria tomorrow at 2?" → collects name/phone, books |
| 🛡 air-alert-radar | Air-threat alerts for your area from several public sources, de-duplicated and ranked by distance | Python (stdlib only) | 🔴 "UAV - your district" with map / mute buttons |
| ❤️ health-monitor | Morning health score from a Mi Band export, analysed by Claude | Python, Gadgetbridge, Anthropic API | "Overall: 78% - Good. Sleep 7h10, resting HR 58..." |
Note
Most bots speak Russian (prompts, buttons, replies). The code and configuration are in English; translating a bot means editing its prompts and string constants.
Every bot here started as a tool somebody actually used. They are small enough to read in an evening, wired the same
way (.env → docker compose), and free of secrets and personal IDs - a practical starting point for your own bot
instead of another "hello world" tutorial.
- 🐳 One command per bot - a Compose service and
.env.examplefor each - 🔐 No inbound ports - every bot uses long polling; nothing listens on your server
- 🧩 Independent - run one bot or all six; each folder works on its own
- 🧠 LLM-ready - OpenRouter, Groq Whisper, kie.ai, Anthropic wired through env vars
- 🗄 Real storage - SQLite per bot, PostgreSQL for TaskFlow (schema applied automatically)
Requirements: Docker with Compose v2.24+ and a bot token from @BotFather per bot.
git clone https://github.com/meshoklv/botarium && cd botarium
cp bots/voice-summarizer/.env.example bots/voice-summarizer/.env # add your keys
docker compose up -d --build voice-summarizerSwap voice-summarizer for any service name: taskflow, banana-studio, salon-booking,
air-alert-radar, health-monitor. Without Docker, each bot's README has a plain python bot.py path.
Warning
Tested here: Python bots import cleanly with their pinned dependencies, air-alert-radar geo/threat classification was exercised offline. Not tested: the Docker images and
Compose file (no Docker on the build host), and nothing was run against the live Telegram API.
flowchart LR
U([You in Telegram]) <-->|long polling| B[bot container]
B --> S[(SQLite / Postgres)]
B -->|speech| G[Groq Whisper / whisper.cpp]
B -->|text, images| L[OpenRouter / kie.ai / Anthropic]
Each bot is a small standalone program that polls Telegram, keeps its state in a local database volume, and calls
the AI providers you configure. docker-compose.yml simply builds bots/<name> into one service each.
Every bot reads its own bots/<name>/.env (see the .env.example next to it). Common variables:
| Variable | Used by | Meaning |
|---|---|---|
TELEGRAM_BOT_TOKEN |
all but air-alert-radar, health-monitor | token from @BotFather |
OUTER_API_KEY / OPENROUTER_API_KEY |
voice, salon, taskflow | OpenRouter key |
GROQ_API_KEY |
voice, salon | Whisper speech-to-text |
KIE_API_KEY |
banana-studio | image generation |
ADMIN_USER_ID / CHAT_ID / ADMIN_ID |
banana, health, radar | your numeric Telegram id |
ALLOWED_USER_IDS |
voice-summarizer | restrict the bot to listed users |
- Bots only make outbound connections; Compose publishes no ports.
- Keep
.envfiles out of git (they are in.gitignore). Never paste tokens into issues. voice-summarizer,salon-bookingare open to anyone who finds the bot and spend your API quota - useALLOWED_USER_IDSor revoke the token if abused.health-monitorsends health data to the Anthropic API;air-alert-radarrelies on unofficial sources.
PRs and issues are welcome - see CONTRIBUTING.md.
Made by @meshoklv
