Principle:Cohere ai Cohere python Stream Aggregation
| Field | Value |
|---|---|
| Source Repo | Cohere Python SDK |
| Source Doc | Cohere Chat API |
| Domains | Streaming, Data_Aggregation, Chat_API |
| Last Updated | 2026-02-15 14:00 GMT |
Overview
A pattern for collecting incremental stream events into a complete response with final metadata and usage statistics.
Description
Stream Aggregation is the process of combining incremental stream events into a coherent final result. During streaming, text arrives as content-delta events that must be concatenated to form the complete response. The final message-end event provides critical metadata: the finish reason (COMPLETE, MAX_TOKENS, TOOL_CALL), token usage statistics, and billing information. Proper aggregation ensures that streaming consumers can reconstruct the equivalent of a non-streaming response while still benefiting from incremental delivery.
Usage
Use this principle at the end of every streaming chat interaction. After iterating through content-delta events, process the message-end event to obtain finish_reason and usage data. The finish_reason determines whether the conversation is complete or requires further interaction (e.g., tool execution).
Key finish reasons and their meanings:
- COMPLETE: Generation finished naturally
- MAX_TOKENS: Generation stopped due to token limit
- TOOL_CALL: Model is requesting a tool call; the client must execute the tool and continue the conversation
Theoretical Basis
Stream aggregation follows the observer pattern where incremental events are accumulated into a final state. The message-end event serves as a terminal signal, analogous to EOF in stream processing. The delta-based approach minimizes bandwidth by transmitting only changes rather than the complete state at each step.
The aggregation process can be summarized as:
- Initialize an empty accumulator for the response text
- For each content-delta event, append the text fragment to the accumulator
- On message-end, extract finish_reason and usage from the delta
- The accumulated text plus the final metadata form the complete response