From 70f3d32734067e89052b38b132b8af17cc68ae08 Mon Sep 17 00:00:00 2001
From: Paul Kompfner <paul@daily.co>
Date: Thu, 23 Apr 2026 16:40:07 -0400
Subject: [PATCH] feat(types): add assert_given for narrowing store-mode
 settings reads
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In store-mode settings objects, _NotGiven should never appear (the
invariant enforced by validate_complete). But the declared field types
still include _NotGiven because the same class doubles as delta mode,
so every field read is typed X | None | _NotGiven and pyright flags
operations that assume X | None.

assert_given is a one-line extractor that narrows away _NotGiven and
raises loudly if the invariant is violated — preferable to scattering
is_given guards that defend against something that can't occur in
practice.

    resolved_model = assert_given(self._settings.model)  # str | None
---
 src/pipecat/services/settings.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/pipecat/services/settings.py b/src/pipecat/services/settings.py
index cc8d95958..62d6dfd50 100644
--- a/src/pipecat/services/settings.py
+++ b/src/pipecat/services/settings.py
@@ -117,6 +117,31 @@ def is_given(value: _T | _NotGiven) -> TypeGuard[_T]:
     return not isinstance(value, _NotGiven)
 
 
+def assert_given(value: _T | _NotGiven) -> _T:
+    """Extract a store-mode settings field, asserting it isn't ``NOT_GIVEN``.
+
+    Intended for reads from a store-mode settings object, where
+    ``_NotGiven`` should never appear (see ``validate_complete``).  Narrows
+    away ``_NotGiven`` at the type level and raises at runtime if the
+    invariant is violated::
+
+        resolved_model = assert_given(self._settings.model)  # narrowed str | None
+
+    Args:
+        value: The store-mode field value to extract.
+
+    Returns:
+        The value, narrowed to exclude ``_NotGiven``.
+
+    Raises:
+        RuntimeError: If *value* is ``NOT_GIVEN`` (a store-mode invariant
+            violation).
+    """
+    if not is_given(value):
+        raise RuntimeError("Store-mode settings field is NOT_GIVEN (invariant violated)")
+    return value
+
+
 # ---------------------------------------------------------------------------
 # Base ServiceSettings
 # ---------------------------------------------------------------------------