pattern_pair_aggregator

Pattern pair aggregator for processing structured content in streaming text.

This module provides an aggregator that identifies and processes content between pattern pairs (like XML tags or custom delimiters) in streaming text, with support for custom handlers and configurable actions for when a pattern is found.

class pipecat.utils.text.pattern_pair_aggregator.MatchAction(*values)

Bases: Enum

Actions to take when a pattern pair is matched.

Parameters:

• REMOVE – The text along with its delimiters will be removed from the streaming text. Sentence aggregation will continue on as if this text did not exist.

• KEEP – The delimiters will be removed, but the content between them will be kept. Sentence aggregation will continue on with the internal text included.

• AGGREGATE – The delimiters will be removed and the content between will be treated as a separate aggregation. Any text before the start of the pattern will be returned early, whether or not a complete sentence was found. Then the pattern will be returned. Then the aggregation will continue on sentence matching after the closing delimiter is found. The content between the delimiters is not aggregated by sentence. It is aggregated as one single block of text.

REMOVE = 'remove'

KEEP = 'keep'

AGGREGATE = 'aggregate'

class pipecat.utils.text.pattern_pair_aggregator.PatternMatch(content: str, type: str, full_match: str)

Bases: Aggregation

Represents a matched pattern pair with its content.

A PatternMatch object is created when a complete pattern pair is found in the text. It contains information about which pattern was matched, the full matched text (including start and end patterns), and the content between the patterns.

__init__(content: str, type: str, full_match: str)

Initialize a pattern match.

Parameters:

• type – The type of the matched pattern pair. It should be representative of the content type (e.g., ‘sentence’, ‘code’, ‘speaker’, ‘custom’).

• full_match – The complete text including start and end patterns.

• content – The text content between the start and end patterns.

class pipecat.utils.text.pattern_pair_aggregator.PatternPairAggregator(**kwargs)

Bases: SimpleTextAggregator

Aggregator that identifies and processes content between pattern pairs.

This aggregator buffers text until it can identify complete pattern pairs (defined by start and end patterns), processes the content between these patterns using registered handlers. By default, its aggregation method returns text at sentence boundaries, and remove the content found between any matched patterns. However, matched patterns can also be configured to returned as a separate aggregation object containing the content between their start and end patterns or left in, so that only the delimiters are removed and a callback can be triggered.

This aggregator is particularly useful for processing structured content in streaming text, such as XML tags, markdown formatting, or custom delimiters.

The aggregator ensures that patterns spanning multiple text chunks are correctly identified.

__init__(**kwargs)

Initialize the pattern pair aggregator.

Creates an empty aggregator with no patterns or handlers registered. Text buffering and pattern detection will begin when text is aggregated.

Parameters:

**kwargs – Additional arguments passed to SimpleTextAggregator (e.g. aggregation_type).

property text: Aggregation

Get the currently aggregated text.

Returns:

The text that has been accumulated in the buffer.

add_pattern(type: str, start_pattern: str, end_pattern: str, action: MatchAction = MatchAction.REMOVE) → PatternPairAggregator

Add a pattern pair to detect in the text.

Registers a new pattern pair with a unique identifier. The aggregator will look for text that starts with the start pattern and ends with the end pattern, and treat the content between them as a match.

Parameters:

• type – Identifier for this pattern pair. Should be unique and ideally descriptive. (e.g., ‘code’, ‘speaker’, ‘custom’). type can not be ‘sentence’ or ‘word’ as those are reserved for the default behavior.

• start_pattern – Pattern that marks the beginning of content.

• end_pattern – Pattern that marks the end of content.

• action –

  What to do when a complete pattern is matched.

  • MatchAction.REMOVE: Remove the matched pattern from the text.

  • MatchAction.KEEP: Keep the matched pattern in the text and treat it as normal text. This allows you to register handlers for the pattern without affecting the aggregation logic.

  • MatchAction.AGGREGATE: Return the matched pattern as a separate aggregation object.

Returns:

Self for method chaining.

on_pattern_match(type: str, handler: Callable[[PatternMatch], Awaitable[None]]) → PatternPairAggregator

Register a handler for when a pattern pair is matched.

The handler will be called whenever a complete match for the specified type is found in the text.

Parameters:

• type – The type of the pattern pair to trigger the handler.

• handler – Async function to call when pattern is matched. The function should accept a PatternMatch object.

Returns:

Self for method chaining.

async aggregate(text: str) → AsyncIterator[PatternMatch]

Aggregate text and process pattern pairs.

Processes the input text character-by-character, handles pattern pairs, and uses the parent’s lookahead logic for sentence detection when no patterns are active.

In TOKEN mode, pattern detection still works but non-pattern text is yielded as TOKEN aggregations instead of waiting for sentence boundaries.

Parameters:

text – Text to aggregate.

Yields:

PatternMatch objects as patterns complete or sentences are detected.

async handle_interruption()

Handle interruptions by clearing the buffer and pattern state.

Called when an interruption occurs in the processing pipeline, to reset the state and discard any partially aggregated text.

async reset()

Clear the internally aggregated text.

Resets the aggregator to its initial state, discarding any buffered text and clearing pattern tracking state.