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 noNOT_GIVENfields.extradict — 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:
objectBase 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_GIVENis never valid. UseNonefor inherited fields the service doesn’t support. Enforced at runtime byvalidate_complete().Delta mode (
*UpdateSettingsFrame): a sparse update. Only fields the caller wants to change are set; all others stay at the defaultNOT_GIVENand are skipped byapply_update().
- Parameters:
model – The model identifier used by the service. Set to
Nonein 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
extrafield 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
extradicts 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 withchanged["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 remainNOT_GIVEN.Keys are matched to dataclass fields by name. Keys listed in
_aliasesare translated to their canonical name first. Any remaining unrecognized keys are placed intoextra.- 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_GIVENfields).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.
- class pipecat.services.settings.ImageGenSettings(model: str | None | NotGiven = <factory>, extra: dict[str, ~typing.Any]=<factory>)[source]
Bases:
ServiceSettingsRuntime-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:
ServiceSettingsRuntime-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:
ServiceSettingsRuntime-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 supportseedshould initialize it asseed=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()onLLMUserAggregatorParamsinstead. Will be removed in 2.0.0.user_turn_completion_config –
Configuration for turn completion behavior when
filter_incomplete_user_turnsis 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.
BackendLLMWorkersets 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:
ServiceSettingsRuntime-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=Noneif 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
Languageenum or a raw string in a delta. However, the stored value (in store mode) is always a service-specific string orNone—TTSService._update_settingsconvertsLanguageenums vialanguage_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:
ServiceSettingsRuntime-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=Noneif 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
Languageenum or a raw string in a delta. However, the stored value (in store mode) is always a service-specific string orNone—STTService._update_settingsconvertsLanguageenums vialanguage_to_service_language()before writing, and__init__methods do the same at construction time.