settings

Settings infrastructure for Pipecat AI services.

Each service type has a settings dataclass (LLMSettings, TTSSettings, STTSettings, or a service-specific subclass). The same class is used in two distinct modes:

Store mode — the service’s self._settings object that holds the full current state. Every field must have a real value; NOT_GIVEN is never valid here. Services that don’t support an inherited field should set it to None. validate_complete() (called automatically in AIService.start()) enforces this invariant.

Delta mode — a sparse update object carried by an *UpdateSettingsFrame. Only the fields the caller wants to change are set; all others remain at their default of NOT_GIVEN. apply_update() merges a delta into a store, skipping any NOT_GIVEN fields.

Key helpers:

  • NOT_GIVEN / is_given() — sentinel and check for “field not provided in this delta”.

  • apply_update(delta) — merge a delta into a store, returning changed fields.

  • from_mapping(dict) — build a delta from a plain dict (for backward compatibility with dict-based *UpdateSettingsFrame).

  • validate_complete() — assert that a store has no NOT_GIVEN fields.

  • extra dict — overflow for service-specific keys that don’t map to a declared field.

class pipecat.services.settings.ServiceSettings(model: str | None | NotGiven = <factory>, extra: dict[str, ~typing.Any]=<factory>)[source]

Bases: object

Base class for runtime-updatable service settings.

These settings capture the subset of a service’s configuration that can be changed while the pipeline is running (e.g. switching the model or changing the voice). They are not meant to capture every constructor parameter — only those that support live updates via *UpdateSettingsFrame.

Every AI service type (LLM, TTS, STT) extends this with its own fields. Each instance operates in one of two modes (see module docstring):

  • Store mode (self._settings): holds the full current state. Every field must be a real value — NOT_GIVEN is never valid. Use None for inherited fields the service doesn’t support. Enforced at runtime by validate_complete().

  • Delta mode (*UpdateSettingsFrame): a sparse update. Only fields the caller wants to change are set; all others stay at the default NOT_GIVEN and are skipped by apply_update().

Parameters:
  • model – The model identifier used by the service. Set to None in store mode if the service has no model concept.

  • extra – Overflow dict for service-specific keys that don’t map to a declared field.

given_fields() → dict[str, Any][source]

Return a dict of only the fields that are not NOT_GIVEN.

Primarily useful for delta-mode objects to inspect which fields were set. For a store-mode object this returns all declared fields (since none should be NOT_GIVEN).

Skips the extra field itself but merges its entries into the returned dict at the top level.

Returns:

Dictionary mapping field names to their provided values.

apply_update(delta: _S) → dict[str, Any][source]

Merge a delta-mode object into this store-mode object.

Only fields in delta that are given (i.e. not NOT_GIVEN) are considered. A field is “changed” if its new value differs from the current value.

The extra dicts are merged: keys present in the delta overwrite keys in the target.

Parameters:

delta – A delta-mode settings object of the same type.

Returns:

A dict mapping each changed field name to its pre-update value. Use changed.keys() for the set of names, or index with changed["field"] to inspect the old value.

Examples:

# store-mode object (all fields given)
current = TTSSettings(voice="alice", language="en")
# delta-mode object (only voice is set)
delta = TTSSettings(voice="bob")
changed = current.apply_update(delta)
# changed == {"voice": "alice"}
# current.voice == "bob", current.language == "en"
classmethod from_mapping(settings: Mapping[str, Any]) → _S[source]

Build a delta-mode settings object from a plain dictionary.

This exists for backward compatibility with code that passes plain dicts via *UpdateSettingsFrame(settings={...}). The returned object is a delta: only the keys present in settings are set; all other fields remain NOT_GIVEN.

Keys are matched to dataclass fields by name. Keys listed in _aliases are translated to their canonical name first. Any remaining unrecognized keys are placed into extra.

Parameters:

settings – A dictionary of setting names to values.

Returns:

A new delta-mode settings instance.

Examples:

delta = TTSSettings.from_mapping({"voice_id": "alice", "speed": 1.2})
# delta.voice == "alice"  (via alias)
# delta.language is NOT_GIVEN  (not in the dict)
# delta.extra == {"speed": 1.2}
validate_complete() → None[source]

Check that this is a valid store-mode object (no NOT_GIVEN fields).

Called automatically by AIService.start() to catch fields that a service forgot to initialize in its __init__. Can also be called manually after constructing a store-mode settings object.

Logs a warning for each uninitialized field. Failure to initialize all fields may or may not cause runtime issues — it depends on whether and how the service actually reads the field — but it indicates a deviation from expectations and should be fixed.

copy() → _S[source]

Return a deep copy of this settings instance.

Returns:

A new settings object with the same field values.

class pipecat.services.settings.ImageGenSettings(model: str | None | NotGiven = <factory>, extra: dict[str, ~typing.Any]=<factory>)[source]

Bases: ServiceSettings

Runtime-updatable settings for image generation services.

Used in both store and delta mode — see ServiceSettings.

Parameters:

model – Image generation model identifier.

class pipecat.services.settings.VisionSettings(model: str | None | NotGiven = <factory>, extra: dict[str, ~typing.Any]=<factory>)[source]

Bases: ServiceSettings

Runtime-updatable settings for vision services.

Used in both store and delta mode — see ServiceSettings.

Parameters:

model – Vision model identifier.

class pipecat.services.settings.LLMSettings(model: str | None | NotGiven = <factory>, extra: dict[str, Any]=<factory>, system_instruction: str | None | NotGiven = <factory>, temperature: float | None | NotGiven = <factory>, max_tokens: int | None | NotGiven = <factory>, top_p: float | None | NotGiven = <factory>, top_k: int | None | NotGiven = <factory>, frequency_penalty: float | None | NotGiven = <factory>, presence_penalty: float | None | NotGiven = <factory>, seed: int | None | NotGiven = <factory>, filter_incomplete_user_turns: bool | None | NotGiven = <factory>, user_turn_completion_config: UserTurnCompletionConfig | None | NotGiven = <factory>, use_provider_thinking_default: bool | NotGiven = <factory>)[source]

Bases: ServiceSettings

Runtime-updatable settings for LLM services.

Used in both store and delta mode — see ServiceSettings.

These fields are common across LLM providers. Not every provider supports every field; in store mode, set unsupported fields to None (e.g. a service that doesn’t support seed should initialize it as seed=None).

Parameters:
  • model – LLM model identifier.

  • system_instruction – System instruction/prompt for the model.

  • temperature – Sampling temperature.

  • max_tokens – Maximum tokens to generate.

  • top_p – Nucleus sampling probability.

  • top_k – Top-k sampling parameter.

  • frequency_penalty – Frequency penalty.

  • presence_penalty – Presence penalty.

  • seed – Random seed for reproducibility.

  • filter_incomplete_user_turns –

    Enable LLM-based turn completion detection to suppress bot responses when the user was cut off mid-thought. Set by LLMTurnCompletionUserTurnStopStrategy, which is also what waits on the resulting verdict.

    Deprecated since version 1.7.0: Use user_turn_strategies=FilterIncompleteUserTurnStrategies() on LLMUserAggregatorParams instead. Will be removed in 2.0.0.

  • user_turn_completion_config –

    Configuration for turn completion behavior when filter_incomplete_user_turns is enabled. Controls timeouts and prompts for incomplete turns.

    Deprecated since version 1.7.0: Pass the config to FilterIncompleteUserTurnStrategies(config=...) instead. Will be removed in 2.0.0.

  • use_provider_thinking_default – Whether a model with no thinking configured runs at its provider’s default. Services that otherwise send each model its lowest thinking setting, for the fastest responses, send none. BackendLLMWorker sets it on its LLM. Defaults to False.

class pipecat.services.settings.TTSSettings(model: str | None | NotGiven = <factory>, extra: dict[str, ~typing.Any]=<factory>, voice: str | None | NotGiven = <factory>, language: Language | str | None | NotGiven = <factory>)[source]

Bases: ServiceSettings

Runtime-updatable settings for TTS services.

Used in both store and delta mode — see ServiceSettings.

In store mode, set unsupported fields to None (e.g. language=None if the service doesn’t expose a language setting).

Parameters:
  • model – TTS model identifier.

  • voice – Voice identifier or name.

  • language – Language for speech synthesis. The union type reflects the input side: callers may pass a Language enum or a raw string in a delta. However, the stored value (in store mode) is always a service-specific string or None — TTSService._update_settings converts Language enums via language_to_service_language() before writing, and __init__ methods do the same at construction time.

class pipecat.services.settings.STTSettings(model: str | None | NotGiven = <factory>, extra: dict[str, ~typing.Any]=<factory>, language: Language | str | None | NotGiven = <factory>)[source]

Bases: ServiceSettings

Runtime-updatable settings for STT services.

Used in both store and delta mode — see ServiceSettings.

In store mode, set unsupported fields to None (e.g. language=None if the service auto-detects language).

Parameters:
  • model – STT model identifier.

  • language – Language for speech recognition. The union type reflects the input side: callers may pass a Language enum or a raw string in a delta. However, the stored value (in store mode) is always a service-specific string or None — STTService._update_settings converts Language enums via language_to_service_language() before writing, and __init__ methods do the same at construction time.