Context Optimization Engine

Relevant source files

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

• src/features/summary/optimization/config.ts
• src/features/summary/optimization/hierarchical-processor.ts
• tests/summary-optimization/context-optimizer.test.ts
• tests/summary-optimization/basic-infrastructure.test.ts
• README.md
• tests/integration/optimized-summary.test.ts

The Context Optimization Engine manages Large Language Model (LLM) context windows for the Telegram History Bot. It ensures large message volumes fit within model token limits while maintaining high summary quality. The engine dynamically selects processing strategies based on message count and estimated token usage.

Architecture and Components

The engine consists of three primary modules that coordinate token estimation, message pruning, and multi-stage processing.

Context Optimizer

The ContextOptimizer estimates token usage and reduces message sets to fit specific budgets. It uses a tokenEstimationFactor (default 4) to approximate tokens from character counts, specifically optimized for Russian text. If a message set exceeds limits, the optimizer prunes content by removing short messages first or applying smart temporal sampling.

Sources: src/features/summary/optimization/config.ts:25, tests/summary-optimization/context-optimizer.test.ts:168-180

Hierarchical Processor

The HierarchicalProcessor handles datasets that exceed single-request context limits. It implements a three-stage pipeline:

1. Preprocessing: Splits messages into chunks and generates per-user JSON summaries for each chunk.
2. Aggregation: Consolidates per-user summaries from all chunks into a unified structure.
3. Final Summary: Generates the comprehensive result from the aggregated user data.

Sources: src/features/summary/optimization/hierarchical-processor.ts:32-60

Strategy Selector

The OptimizedStrategySelector determines the processing mode based on input metrics.

Strategy	Condition	Description
Direct	< 1000 messages	Sends all messages in a single AI request.
Parallel	> 1000 messages	Uses workers to fetch and process batches concurrently.
Hierarchical	> 80,000 tokens	Uses multi-stage chunking and aggregation.

Sources: src/features/summary/optimization/config.ts:10-30, tests/summary-optimization/basic-infrastructure.test.ts:98-112

Data Flow and Strategy Selection

The engine follows a specific sequence to process chat history.

Configuration Management

The engine loads configuration from environment variables and clamps values to specific model presets.

Model Limit Presets

The engine detects limits based on SUMMARY_MODEL.

• gpt-4.1-nano: 1,000,000 context tokens / 32,000 output tokens.
• gpt-5-nano: 400,000 context tokens / 128,000 output tokens.
• Generic: 200,000 context tokens / 8,000 output tokens.

Sources: src/features/summary/optimization/config.ts:38-60

Environment Variables

Variable	Default	Range
SUMMARY_OPT_MAX_WORKERS	5	1 - 20
SUMMARY_OPT_MAX_TOKENS_PER_REQUEST	120,000	1000 - Model Context
SUMMARY_OPT_TOKEN_ESTIMATION_FACTOR	4	1 - 10
SUMMARY_OPT_CHUNK_SIZE_THRESHOLD	80,000	> 1000
SUMMARY_OPT_MAX_PREPROCESSING_CHUNKS	10	1 - 50

Sources: src/features/summary/optimization/config.ts:100-200

Hierarchical Processing Logic

When hierarchical processing is active, the engine performs structured JSON preprocessing to avoid losing user-specific context.

Preprocessing JSON Format

During the hierarchical phase, the engine enforces a strict JSON schema for intermediate results:

{
  "chunkIndex": 0,
  "userSummaries": [
    { "username": "user1", "messageCount": 15, "summary": "Discussed API limits" }
  ]
}

Sources: src/features/summary/optimization/hierarchical-processor.ts:300-315

Error Handling and Fallback

The system maintains a seamless fallback to legacy summarization. If the OptimizedSummaryController throws an error or fails configuration validation, the summariseChat function catches the exception and invokes summariseChatLegacy.

Sources: README.md:65, tests/integration/optimized-summary.test.ts:150-170

The Context Optimization Engine provides a robust framework for handling Telegram's 7-day message history. It balances performance through parallel processing and depth through hierarchical aggregation. By dynamically adjusting to LLM context limits, it maintains stability even during high-volume chat activity.