How clemsau/telegram-gpt works
This is a self-hosted Telegram chatbot bot written in Python. It acts as an integration service between:
• Telegram Bot API (receives updates/messages, sends replies)
• OpenAI API (ChatGPT / GPT-3.5) (generates responses; likely also Whisper or similar for voice if implemented via OpenAI)
• Optional local runtime concerns (env config, containerization)
File structure analysis → map files to architectural components
Top-level:
• Dockerfile → container packaging/runtime
• pyproject.toml, requirements.txt → dependency management/build metadata
• assets/demo.gif → documentation asset
• src/ → application code
src/ (core runtime):
• bot.py → likely the entrypoint that:
• initializes Telegram bot client
• wires handlers
• starts polling or webhook loop
• handlers.py → Telegram update/message handlers:
• text messages
• mentions logic (toggle “answer on mentions”)
• voice messages handling
• streaming output orchestration (edit message / send partials)
• openai_utils.py → OpenAI integration layer:
• building prompts/messages
• calling chat completion endpoints
• streaming token handling
• voice transcription if present
• config.py → configuration:
• reads TELEGRAM_TOKEN, OPENAI_API_KEY, ALLOWED_USERS
• mention-toggle flag (if configurable)
• entity.py → domain objects / DTOs:
• message/session structures, request/response objects, maybe conversation state
• src/.env.example → environment template
• src/__init__.py → package marker
This is effectively a small layered architecture:
• Presentation/Integration: Telegram handlers (bot.py, handlers.py)
• Service layer: OpenAI client utilities (openai_utils.py)
• Config & domain: (config.py, entity.py)
From README features:
• “GPT-3.5 chatbot” → OpenAI chat completions
• “Handle voice messages” → voice pipeline: Telegram voice → file download → transcription → prompt → response
• “Message streaming” → streaming responses from OpenAI → streamed back to Telegram (message edits or multiple sends)
• “Toggleable answer on mentions” → group chat gating logic
• “ALLOWED_USERS” → authorization guard before OpenAI calls (cost control)
Deployment notes:
• runs as a low-resource long-running process
• can run bare metal or in Docker (so include runtime boundary)
Telegram Client Surface
• “Telegram Users / Group Chats” (actors)
• “Telegram Bot API” (external system)
Bot Runtime (this repo)
• “bot.py (Runner/Dispatcher)”
• “handlers.py (Update Handlers)”
• “config.py (Env Config + Access Control)”
• “entity.py (Conversation/Message Models)”
• “openai_utils.py (OpenAI Client + Streaming + Transcription)”
OpenAI
• “OpenAI Chat Completions API”
• (If voice is done via OpenAI) “OpenAI Transcription API”
Infrastructure / Ops (optional but recommended)
• “Docker Container” (if deployed via Dockerfile)
• “Environment Variables / .env” (configuration source)
Streaming response flow (feature-critical)
Same as above, but step (7) becomes a stream:
• OpenAI → openai_utils.py: “token stream / chunks”
• openai_utils.py → handlers.py: “on_chunk callbacks / generator”
• handlers.py → Telegram Bot API: “editMessageText (progressive)”
A note: Telegram has rate limits; handler likely batches edits.
Chat mention gating
A decision diamond in handlers.py:
• If “answer-on-mentions enabled” and chat is group:
• only proceed if bot is mentioned or replied-to
Else ignore.
Architectural patterns / principles actually present
Call these out visually (small labels near components):
• Event-driven dispatcher: Telegram updates trigger handler functions
• Integration-layer separation: OpenAI calls isolated in openai_utils.py
• Configuration via environment: config.py sourcing .env / env vars
• Guardrails: ALLOWED_USERS authorization before expensive API calls
• Streaming pipeline: generator/callback-based chunk propagation to Telegram edits
Technologies that matter
• Python app (likely python-telegram-bot or similar, depending on requirements.txt)
• OpenAI API (Chat Completions; maybe Transcriptions)
• Docker runtime (optional boundary)
• Env vars .env