Project Introduction

Relevant source files

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

• README.md
• bot.py
• requirements.txt
• .env.example
• Dockerfile

The Telegram Summary Bot is a Python-based worker application that processes Telegram chat messages to generate concise summaries. It operates as a local, dependency-light service that does not require external AI API keys for its core summarization functionality. The bot provides users with tools to summarize specific text inputs or a history of recent messages within a chat.

Sources: README.md:1-12, bot.py:1-5

System Architecture

The bot follows a long-polling architecture to interact with the Telegram Bot API. It maintains an internal memory of recent messages using a deque-based buffer for each chat. The application is designed to run as a single-instance background worker.

Core Components

• Long Polling Loop: The poll_updates function continuously requests new messages from the Telegram API.
• Message Processor: The process_message function routes commands and stores incoming text messages.
• Local Summarizer: A rule-based text processor that extracts the leading sentences from provided or stored text.
• API Wrapper: The telegram_api function handles authenticated HTTPS requests to Telegram.

Sources: bot.py:44-123, README.md:106-107

Message Processing Flow

This diagram illustrates how an incoming update is received and handled by the bot logic.

Technical Implementation

Data Structures

The bot utilizes a global chat_messages dictionary to store message history. This dictionary maps chat IDs to collections.deque objects. These deques have a maxlen attribute defined by the MAX_STORED_MESSAGES environment variable to prevent memory exhaustion.

Sources: bot.py:32-33, bot.py:22

Summarization Logic

The summarize_text function performs extractive summarization without external dependencies. It cleans the input string, splits it into sentences based on punctuation (periods, exclamation marks, and question marks), and returns the first $N$ sentences, where $N$ is defined by SUMMARY_SENTENCES.

def summarize_text(text: str) -> str:
    cleaned = " ".join(text.split())
    if not cleaned:
        return "No text found to summarize."

    sentences = [
        sentence.strip()
        for sentence in cleaned.replace("!", ".").replace("?", ".").split(".")
        if sentence.strip()
    ]
    if not sentences:
        return cleaned[:1000]

    summary = ". ".join(sentences[:SUMMARY_SENTENCES])
    return f"{summary}."

Sources: bot.py:73-89

Configuration

The bot uses environment variables for configuration. These are loaded from a .env file using the python-dotenv library.

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	Yes	None	Authentication token from @BotFather
LOG_LEVEL	No	INFO	Python logging severity level
POLL_TIMEOUT	No	30	Seconds to wait for Telegram long-polling
MAX_STORED_MESSAGES	No	100	Messages kept in memory per chat
SUMMARY_SENTENCES	No	5	Sentence count in generated summaries

Sources: README.md:38-44, bot.py:20-29

Command Interface

The bot interacts with users through standard Telegram commands.

Command	Action
/start	Returns a health check and basic status message.
/help	Displays available commands and usage tips.
/summary <text>	Summarizes the specific text following the command.
/summary	Concatenates and summarizes the messages stored in the current chat's buffer.

Sources: bot.py:92-114, README.md:7-10

Deployment and Lifecycle

The bot supports multiple deployment methods, including local execution, Docker containers, and systemd services.

Shutdown Handling

The application implements signal handlers for SIGINT and SIGTERM. When these signals are received, the handle_shutdown function sets the running flag to False, allowing the polling loop to terminate gracefully after its current iteration.

Dependencies

Key dependencies listed in requirements.txt include:

• urllib3: Used for making HTTP requests to the Telegram API.
• python-dotenv: Used for environment variable management.
• Flask: Included for potential MiniApp control panel integration.

Sources: requirements.txt:1-6

The Telegram Summary Bot provides a self-contained solution for chat overview within the Telegram ecosystem, emphasizing ease of deployment and local processing over complex AI integrations.