Python Worker Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• bot.py
• README.md
• requirements.txt
• .env.example (referenced via README)
• Dockerfile (referenced via README)

The Python Worker Architecture defines a lightweight, long-running background service that interacts with the Telegram Bot API. It operates as a stateless consumer that retrieves messages via long polling and processes them locally to provide text summarization features.

This architecture is optimized for deployment on platforms that support background workers, such as Render, Railway, or VPS environments using systemd. It avoids heavy external AI dependencies by utilizing a local extractive summarization logic.
Sources: README.md:5-10, bot.py:1-5

Core Components

The worker consists of several integrated modules that handle communication, state management, and text processing.

Long Polling Engine

The worker uses a continuous loop to fetch updates from the Telegram API. It maintains an offset to track processed messages and utilizes a configurable POLL_TIMEOUT to manage connection duration.
Sources: bot.py:122-136

Message Processor

The processor evaluates incoming updates and routes them based on command prefixes. It distinguishes between service commands (/start, /help), summarization requests (/summary), and standard chat messages.
Sources: bot.py:97-120

In-Memory State Management

The system stores recent chat history in a chat_messages dictionary. It uses collections.deque with a fixed MAX_STORED_MESSAGES limit to ensure thread-safe, memory-efficient message rotation per chat ID.
Sources: bot.py:32-34

The diagram shows the data flow from the Telegram API through the internal processing logic and back to the user.
Sources: bot.py:97-136

Data Flow and API Interaction

The worker communicates with Telegram using the urllib3 library. It wraps all requests in a telegram_api function that handles JSON encoding, headers, and error validation.

Sequence of Operation

1. Request Updates: The worker sends a getUpdates request with the current offset.
2. Filter Messages: It extracts message or edited_message objects from the response.
3. Action Determination:
   • If a message contains text but no command, it is appended to the chat's deque.
   • If a message contains /summary, the worker triggers the summarization logic.
4. Response: The worker sends a sendMessage request containing the summary or help text.

The sequence diagram illustrates the polling cycle and the conditional logic for message handling.
Sources: bot.py:122-136, bot.py:44-59

Summarization Logic

The summarizer uses a local extractive method. It cleans the input text and splits it into sentences based on punctuation marks (periods, exclamation points, and question marks). It then selects the first SUMMARY_SENTENCES to form the output.

Step	Action	Logic
1	Cleaning	Joins split text to remove extra whitespace.
2	Segmentation	Splits text using !, ?, and . as delimiters.
3	Extraction	Selects sentences up to the SUMMARY_SENTENCES limit.
4	Formatting	Reconstructs sentences into a single string with a trailing period.

Sources: bot.py:68-83

Configuration and Environment

The worker's behavior is governed by environment variables loaded via python-dotenv.

Variable	Type	Default	Description
TELEGRAM_BOT_TOKEN	String	None	Required API token from BotFather.
LOG_LEVEL	String	INFO	Python logging severity level.
POLL_TIMEOUT	Integer	30	Long-poll duration in seconds.
MAX_STORED_MESSAGES	Integer	100	History limit per chat.
SUMMARY_SENTENCES	Integer	5	Length of the generated summary.

Sources: bot.py:20-25, README.md:37-43

Deployment Architecture

The worker is designed to run as a single instance per bot token to prevent conflicts in long polling.

Execution Modes

1. Local/Standalone: Running python bot.py within a virtual environment.
2. Containerized: Using the provided Dockerfile to build an image and running with --restart unless-stopped.
3. System Service: Managed via systemd on a VPS with Restart=always to ensure high availability.
   Sources: README.md:14-35, README.md:54-73

Dependency Profile

The architecture maintains a minimal footprint by using standard libraries and select external packages.

• urllib3: For HTTP communication.
• python-dotenv: For configuration management.
• telebot: Listed in requirements but primary logic in bot.py uses raw urllib3 calls.
  Sources: requirements.txt:1-6

Summary

The Python Worker Architecture provides a robust, self-contained system for Telegram bot operations. By leveraging in-memory deques and local string manipulation, it delivers chat summarization features without the latency or cost of external AI APIs. The design ensures compatibility with modern containerized and process-managed deployment workflows.
Sources: bot.py:140-145, README.md:47-51