Add PatternPairAggregator

[markbackman]

Please describe the changes in your PR. If it is addressing an issue, please reference that as well.

Extends the BaseTextAggregator with one that's aimed at:

• Removing text from the LLM output before it is provided to the TTS service
• Includes a handler to provide the content between the pattern pair, so that the content can be used to do things, like change voices, which I show in a demo

[codecov]

Codecov Report

Attention: Patch coverage is 94.66667% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/pipecat/utils/text/pattern_pair_aggregator.py	94.66%	4 Missing ⚠️

Files with missing lines	Coverage Δ
src/pipecat/utils/text/pattern_pair_aggregator.py	94.66% <94.66%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[filipi87]

Nit: should we change to "Multiple voices Bot" or anything like this.

[filipi87]

When I first looked at the example, I thought,: Why aren’t we using function calling for this ? 😅

But after reading the description, it made total sense.

That makes me wonder if we could improve the example name, maybe something like 35-multiple-voices-bot or another name that clearly indicates the bot will automatically play multiple characters with different voices.

[markbackman]

The benefit of using this approach is that function calls are slow, adding noticeable latency to the response. With this approach, the LLM can output many encoded instructions in a single turn. Also, the applications extend beyond just voice switching. You can now encode any information into the LLM response and just parse it out. Two other common cases I've heard are DTMF codes and thinking tokens.

[filipi87]

Yep, I think it makes a lot of sense. 👍

[filipi87]

Maybe leave the description more complete:

Added foundational example 35-voice-switching.py showing how to use the new
PatternPairAggregator to make the bot automatically play multiple characters with different voices.

[markbackman]

I'm taking a chance to educate a bit:

- Added foundational example `35-voice-switching.py` showing how to use the new
  `PatternPairAggregator`. This example shows how to encode information for the
  LLM to instruct TTS voice changes, but this can be used to encode any
  information into the LLM response, which you want to parse and use in other
  parts of your application.

I'll make this clear in docs too.

[filipi87]

This is a nice one.

[filipi87]

I guess we should pass the text_aggregator when creating the CartesiaTTSService, because otherwise, it feels like we are modifying a private variable.

[markbackman]

Totally! Clearly the late night was getting to me.

[markbackman]

I've updated to:

tts = CartesiaTTSService(
    api_key=os.getenv("CARTESIA_API_KEY"),
    voice_id=VOICE_IDS["narrator"],
    text_aggregator=pattern_aggregator,
)

[markbackman]

Thanks for the quick review @filipi87! This should be ready again.

[filipi87]

Pretty cool. 🚀

[aconchillo]

I think this is fine since the processor executing this code is actually the TTS. In general, we would want to use frames. Maybe it's worth adding a comment about this.

[markbackman]

This needs to execute very quickly, so the method is the best way to go, I think. Even with the method, sometimes it's not fast enough.

[aconchillo]

Maybe this could have gone to utils.string. The function signature would allow passing the set of pairs (start_tag, end_tag, remove_match).

[markbackman]

Happy to move it if you feel strongly. I don't really have a preference.