Skip to content
meshoklvPublic

About

A collection of 6 ready-to-run Telegram bots (voice summaries, tasks, image gen, booking, alerts) with one-command Docker Compose.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

Botarium - a collection of Telegram bots

Botarium

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.

CI License Python Docker PRs welcome

Quick start · The bots · How it works · Русский


The bots

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.

Why

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.

Features

  • 🐳 One command per bot - a Compose service and .env.example for 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)

Quick start

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-summarizer

Swap 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.

How it works

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]
Loading

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.

Configuration

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

Security

  • Bots only make outbound connections; Compose publishes no ports.
  • Keep .env files out of git (they are in .gitignore). Never paste tokens into issues.
  • voice-summarizer, salon-booking are open to anyone who finds the bot and spend your API quota - use ALLOWED_USER_IDS or revoke the token if abused.
  • health-monitor sends health data to the Anthropic API; air-alert-radar relies on unofficial sources.

Contributing

PRs and issues are welcome - see CONTRIBUTING.md.

License

MIT


Made by @meshoklv

About

A collection of 6 ready-to-run Telegram bots (voice summaries, tasks, image gen, booking, alerts) with one-command Docker Compose.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages