ai_service

Base AI service implementation.

Provides the foundation for all AI services in the Pipecat framework, including model management, settings handling, and frame processing lifecycle methods.

class pipecat.services.ai_service.AIService(settings: ServiceSettings | None = None, **kwargs)[source]

Bases: FrameProcessor

Base class for all AI services.

Provides common functionality for AI services including model management, settings handling, session properties, and frame processing lifecycle. Subclasses should implement specific AI functionality while leveraging this base infrastructure.

__init__(settings: ServiceSettings | None = None, **kwargs)[source]

Initialize the AI service.

Parameters:

  • settings – The runtime-updatable settings for the AI service.

  • **kwargs – Additional arguments passed to the parent FrameProcessor.

service_metadata_frame() → ServiceMetadataFrame | None[source]

The metadata frame this service broadcasts at start, or None.

Override to return a populated ServiceMetadataFrame (or a subtype such as STTMetadataFrame) describing this service for downstream processors, for example the user_turn_strategies an STT with server-side end-of-turn detection recommends. Return None to broadcast nothing.

Returns:

The metadata frame to broadcast, or None.

async broadcast_service_metadata()[source]

Broadcast this service’s metadata frame, if any.

async start(frame: StartFrame)[source]

Start the AI service.

Called when the service should begin processing. Subclasses should override this method to perform service-specific initialization.

Parameters:

frame – The start frame containing initialization parameters.

async stop(frame: EndFrame)[source]

Stop the AI service on a graceful end (EndFrame).

Runs in frame order, after pending frames drain. Override for graceful shutdown behavior, such as flushing in-flight work before stopping.

Parameters:

frame – The end frame.

async cancel(frame: CancelFrame)[source]

Cancel the AI service immediately (CancelFrame).

Runs at once, ahead of any queued frames, to abort active work fast (for example, stop producing audio now). Override only for that time-sensitive subset.

Parameters:

frame – The cancel frame.

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

Push a frame and broadcast service metadata once the service starts.

Parameters:

  • frame – The frame to push.

  • direction – The direction to push the frame.

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

Process frames and handle service lifecycle.

Automatically handles StartFrame, EndFrame, and CancelFrame by calling the appropriate lifecycle methods.

Parameters:

  • frame – The frame to process.

  • direction – The direction of frame processing.

async process_generator(generator: AsyncGenerator[Frame | None, None])[source]

Process frames from an async generator.

Takes an async generator that yields frames and processes each one, handling error frames specially by pushing them as errors.

Parameters:

generator – An async generator that yields Frame objects or None.