Hierarchical & Direct Processing

Relevant source files

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

• src/features/summary/optimization/hierarchical-processor.ts
• src/features/summary/optimization/types.ts
• README.md
• tests/summary-optimization/basic-infrastructure.test.ts
• tests/summary-optimization/context-optimizer.test.ts
• src/index.ts

The Optimized Summary System employs two primary processing strategies to handle Telegram chat histories: Direct Processing and Hierarchical Processing. These strategies allow the bot to manage varying message volumes while respecting AI model context limits and maintaining summary quality. The system selects the strategy dynamically based on message counts and estimated token usage.

Sources: README.md:14-22, src/features/summary/optimization/types.ts:9-10

Processing Strategy Selection

The system evaluates incoming summary requests to determine the most efficient processing path. This selection relies on pre-defined thresholds for message counts and token estimates.

Strategy Types

• Direct Processing: Processes all messages in a single AI request. The system uses this for small datasets that fit comfortably within the model's context window.
• Parallel Processing: Uses Durable Objects to fetch and process batches concurrently to improve speed for medium-sized datasets.
• Hierarchical Processing: Implements a multi-stage pipeline for large datasets that exceed single-request context limits. It generates intermediate summaries before producing a final aggregate.

Sources: src/features/summary/optimization/types.ts:9-10, tests/summary-optimization/basic-infrastructure.test.ts:98-102

Selection Logic

The OptimizedStrategySelector determines the strategy based on the following criteria:

• If message count is below SUMMARY_OPT_MIN_MESSAGES_THRESHOLD, it selects Direct.
• If message volume is moderate but token counts are below SUMMARY_OPT_CHUNK_SIZE_THRESHOLD, it selects Parallel.
• If token counts exceed SUMMARY_OPT_CHUNK_SIZE_THRESHOLD, it selects Hierarchical.

Sources: tests/summary-optimization/basic-infrastructure.test.ts:79-102, README.md:38-46

Direct Processing

Direct processing serves as the baseline strategy for standard chat volumes. The DirectProcessor interface handles messages without partitioning or multi-stage aggregation.

Key Characteristics

• Single Request: Sends the entire message block to the AI provider in one call.
• Low Overhead: Avoids the complexity of chunking or intermediate JSON parsing.
• Context Fitting: Validates that the estimated tokens for the message set do not exceed SUMMARY_OPT_MAX_TOKENS_PER_REQUEST.

Sources: src/features/summary/optimization/types.ts:145-147, tests/summary-optimization/basic-infrastructure.test.ts:100

Hierarchical Processing Architecture

The HierarchicalProcessor handles large message volumes by breaking them into manageable parts. It uses a three-stage pipeline to aggregate information without losing per-user context.

Stage 1: Preprocessing Chunks

The processor splits messages into optimal chunks using the ContextOptimizer. For each chunk, it requests a personal summary for every user in that specific timeframe. The AI must return these summaries in a strict JSON format.

Sources: src/features/summary/optimization/hierarchical-processor.ts:32-75, src/features/summary/optimization/hierarchical-processor.ts:133-145

Stage 2: Per-User Aggregation

The system collects all per-user summaries from all chunks. It maps these summaries to a Map<string, AggregatedUserSummary>, concatenating different summary parts for the same user and summing their total message counts.

Sources: src/features/summary/optimization/hierarchical-processor.ts:178-204, src/features/summary/optimization/types.ts:223-228

Stage 3: Final Summarization

The processor creates "synthetic" messages from the aggregated user data. These synthetic messages serve as the input for the final AI request, which generates the comprehensive chat report.

Sources: src/features/summary/optimization/hierarchical-processor.ts:213-233

Technical Components

Component	File Path	Responsibility
HierarchicalProcessor	hierarchical-processor.ts	Orchestrates the three-stage processing pipeline.
ContextOptimizer	context-optimizer.test.ts	Estimates tokens and creates optimal message chunks.
OptimizedStrategySelector	basic-infrastructure.test.ts	Logic for choosing Direct vs. Hierarchical strategies.
MessageAggregatorDO	types.ts	Durable Object for aggregating messages from parallel workers.
MessageFetcherDO	types.ts	Durable Object for concurrent message retrieval.

Sources: src/features/summary/optimization/hierarchical-processor.ts:19, src/features/summary/optimization/types.ts:160-195, tests/summary-optimization/basic-infrastructure.test.ts:79

Configuration Parameters

The behavior of Direct and Hierarchical processing is governed by environment variables defined in the optimization configuration.

Variable	Type	Default	Description
SUMMARY_OPT_ENABLED	Boolean	true	Enables the optimized summary system.
SUMMARY_OPT_HIERARCHICAL_ENABLED	Boolean	true	Enables multi-stage processing for large data.
SUMMARY_OPT_MIN_MESSAGES_THRESHOLD	Number	100	Minimum messages to consider Parallel/Hierarchical.
SUMMARY_OPT_CHUNK_SIZE_THRESHOLD	Number	80000	Token limit before triggering Hierarchical mode.
SUMMARY_OPT_TOKEN_ESTIMATION_FACTOR	Number	4	Multiplier for estimating tokens from text length.

Sources: README.md:38-46, tests/summary-optimization/basic-infrastructure.test.ts:40-55

Data Structures

User Summary Interfaces

The hierarchical processor uses specialized structures to maintain data integrity across chunks:

export interface UserSummary {
  username: string;
  messageCount: number;
  summary: string;
}

export interface ChunkUserSummaries {
  chunkIndex: number;
  userSummaries: UserSummary[];
}

Sources: src/features/summary/optimization/types.ts:213-221

Aggregated User Data

Aggregation combines data into a consolidated view of each participant's contribution:

export interface AggregatedUserSummary {
  username: string;
  totalMessageCount: number;
  aggregatedSummary: string;
  chunkContributions: number[]; // Indices of chunks where user appeared
}

Sources: src/features/summary/optimization/types.ts:223-228

Summary

Hierarchical & Direct Processing provides a scalable architecture for chat summarization. Direct Processing handles standard workloads efficiently, while Hierarchical Processing overcomes token limits by using a per-user JSON preprocessing stage followed by final aggregation. This dual-strategy approach ensures that the bot remains functional and accurate regardless of chat activity levels.

Sources: src/features/summary/optimization/hierarchical-processor.ts:13-17, README.md:27-36