service_switcher

Service switcher for switching between different services at runtime, with different switching strategies.

class pipecat.pipeline.service_switcher.ServiceSwitcherStrategy(services: list[FrameProcessor])[source]

Bases: BaseObject

Base class for service switching strategies.

Note

Strategy classes are instantiated internally by ServiceSwitcher. Developers should pass the strategy class (not an instance) to ServiceSwitcher.

Event handlers available:

  • on_service_switched: Called when the active service changes.

Example:

@strategy.event_handler("on_service_switched")
async def on_service_switched(strategy, service):
    ...
__init__(services: list[FrameProcessor])[source]

Initialize the service switcher strategy with a list of services.

Note

This is called internally by ServiceSwitcher. Do not instantiate directly.

Parameters:

services – List of frame processors to switch between.

property services: list[FrameProcessor]

Return the list of available services.

property active_service: FrameProcessor

Return the currently active service.

property usable_services: list[FrameProcessor]

Return the services that can still be given work, in order.

async handle_frame(frame: ServiceSwitcherFrame, direction: FrameDirection) → FrameProcessor | None[source]

Handle a frame that controls service switching.

The base implementation returns None for all frames. Subclasses override this to implement specific switching behaviors.

Parameters:
  • frame – The frame to handle.

  • direction – The direction of the frame (upstream or downstream).

Returns:

The newly active service if a switch occurred, or None otherwise.

async handle_error(error: ErrorFrame) → FrameProcessor | None[source]

Handle an error from the active service.

Called by ServiceSwitcher for every non-fatal ErrorFrame the active service pushes upstream, whether or not the service can carry on from it. Subclasses override this to decide which errors are worth switching away from: error.processor.is_usable tells a service that is finished apart from one having a bad moment, and a subclass is free to switch on either.

Parameters:

error – The error frame pushed by the active service.

Returns:

The newly active service if a switch occurred, or None otherwise.

class pipecat.pipeline.service_switcher.ServiceSwitcherStrategyManual(services: list[FrameProcessor])[source]

Bases: ServiceSwitcherStrategy

A strategy for switching between services manually.

This strategy allows the user to manually select which service is active. The initial active service is the first one in the list.

Example:

stt_switcher = ServiceSwitcher(
    services=[stt_1, stt_2],
    strategy_type=ServiceSwitcherStrategyManual
)
async handle_frame(frame: ServiceSwitcherFrame, direction: FrameDirection) → FrameProcessor | None[source]

Handle a frame that controls service switching.

Parameters:
  • frame – The frame to handle.

  • direction – The direction of the frame (upstream or downstream).

Returns:

The newly active service if a switch occurred, or None otherwise.

class pipecat.pipeline.service_switcher.ServiceSwitcherStrategyFailover(services: list[FrameProcessor])[source]

Bases: ServiceSwitcherStrategyManual

A strategy that automatically switches to a backup service on failure.

This strategy switches when the active service reports an error that leaves it unable to do its job (is_usable=False), moving to the next service in the list that can still do its own. Errors the service can carry on from are left alone, so a provider hiccup doesn’t cost a failover. Recovery and fallback policies are left to application code via the on_service_switched event.

Event handlers available:

  • on_service_switched: Called when the active service changes.

Example:

switcher = ServiceSwitcher(
    services=[primary_stt, backup_stt],
    strategy_type=ServiceSwitcherStrategyFailover,
)

@switcher.strategy.event_handler("on_service_switched")
async def on_switched(strategy, service):
    # App decides when/how to recover the failed service
    ...
async handle_error(error: ErrorFrame) → FrameProcessor | None[source]

Handle an error from the active service by failing over.

Only an error that leaves the service unable to do its job is worth a failover; anything it can carry on from is ignored. When one does, switches to the next service in the list that can still do its job, wrapping around from the end. The failed service stays in the list and can be switched back to once it has been brought back with set_usable().

Parameters:

error – The error frame pushed by the active service.

Returns:

The newly active service if a switch occurred, or None if the error didn’t warrant one or no other service can be given work.

class pipecat.pipeline.service_switcher.ServiceSwitcher(services: list[~pipecat.processors.frame_processor.FrameProcessor], strategy_type: type[~pipecat.pipeline.service_switcher.StrategyType] = <class 'pipecat.pipeline.service_switcher.ServiceSwitcherStrategyManual'>)[source]

Bases: ParallelPipeline, Generic[StrategyType]

Parallel pipeline that routes frames to one active service at a time.

Wraps each service in a pair of filters that gate frame flow based on which service is currently active. Switching is controlled by ServiceSwitcherFrame frames and delegated to a pluggable ServiceSwitcherStrategy.

Two kinds of frame are exceptions to the gating. A settings update (ServiceUpdateSettingsFrame) addressed to a member service (service=) reaches it whether or not it is active, and one marked reach_inactive_services reaches every member, so whichever service becomes active later is already configured. Any other settings update applies to the active service alone. And a ServiceMetadataFrame from a service outside the switcher reaches every member, so a member that reads another service’s metadata has it when it becomes active. It travels on once, from the active member, as it would through that service alone.

Example:

switcher = ServiceSwitcher(services=[stt_1, stt_2])
__init__(services: list[~pipecat.processors.frame_processor.FrameProcessor], strategy_type: type[~pipecat.pipeline.service_switcher.StrategyType] = <class 'pipecat.pipeline.service_switcher.ServiceSwitcherStrategyManual'>)[source]

Initialize the service switcher with a list of services and a switching strategy.

Parameters:
  • services – List of frame processors to switch between.

  • strategy_type – The strategy class to use for switching between services. Defaults to ServiceSwitcherStrategyManual.

async set_usable(is_usable: bool)[source]

Ignore an attempt to set this switcher’s usability directly.

A switcher has no usability of its own to set: what it reports is a reading of its services. Bring an individual service back with its own set_usable(), which brings the switcher back with it.

Parameters:

is_usable – Whether the switcher can be given work. Ignored.

property strategy: StrategyType

Return the active switching strategy.

property services: list[FrameProcessor]

Return the list of available services.

property is_usable: bool

Whether any of the switched services can still be given work.

A switcher is only as dead as its last service: it can keep doing its job by moving work to a different one, so it reports itself unusable only once none of them can do theirs. This is a reading of the services rather than a state of its own, so bringing a service back with set_usable() brings the switcher back too, and calling that on the switcher itself does nothing. The switcher raises on_usable_changed for itself as the reading moves, so watching it is enough to hear about the services it holds.

Returns:

True while at least one service can be given work.

async push_frame(frame: Frame, direction: FrameDirection = FrameDirection.DOWNSTREAM)[source]

Push a frame out of the service switcher.

Suppresses ServiceSwitcherRequestMetadataFrame targeting the active service (since it has already been handled) and ServiceMetadataFrame from inactive services so only the active service’s metadata reaches downstream processors. One case this happens is with StartFrame since all the filters let it pass, and StartFrame causes the service to generate ServiceMetadataFrame.

Also suppresses the copies of a ServiceUpdateSettingsFrame or of another service’s ServiceMetadataFrame handed to the inactive services, so that the frame the rest of the pipeline sees is the one travelling the active service’s branch.

Non-fatal ErrorFrame instances from the services being switched between are answered for here rather than travelling on, since the rest of the pipeline deals with the switcher and not with what it holds. Errors from a service the switcher isn’t using stop here outright. Every error from the active service is forwarded to the strategy via handle_error, which decides whether it warrants a switch; a successful switch absorbs it, the switcher having gone on doing its job. An error that leaves the active service unable to do its job with no switch to be made is reported against the switcher, so that the rest of the pipeline judges it by what the switcher has left rather than by the one service that failed. Every other error travels upstream as usual.

async process_frame(frame: Frame, direction: FrameDirection)[source]

Process a frame, handling frames which affect service switching.

Parameters:
  • frame – The frame to process.

  • direction – The direction of the frame (upstream or downstream).