dv-pipecat-flows 0.0.0.dev2766__tar.gz → 0.0.0.dev2810__tar.gz

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2810}/AGENTS.md

@@ -125,6 +125,23 @@ Example `call_config`:
 - `tests/test_manager.py`, `tests/test_actions.py`, etc., cover FlowManager and ActionManager edge cases (context resets, action ordering, function registration). Extend these tests when adding new features.
 - Logging: see the dedicated section below for Loguru usage and the custom logger configuration.
 
+## Metrics & Observability
+
+- **SDK**: `ringg-telemetry` (metrics-only facade over OpenTelemetry). Initialised once per process in the FastAPI lifespan — `ringg-bot/server.py` — gated on `ENABLE_METRICS`. Export path is OTLP/gRPC → the in-cluster `otel-gateway` → **Google Managed Prometheus**. Tracing is a *separate* stack (Langfuse, `ringg-bot/utils/tracing.py`); the two are unrelated.
+- **Declare instruments in one place**: the registry block near the bottom of `ringg-bot/utils/metrics_collector.py`. Module-level handles (`ringg_metrics.histogram/counter/gauge`), created at import, resolved lazily. Keep the cardinality justification in a comment next to each — the `labels=(...)` tuple is a hard allowlist, and the SDK **silently drops** any label not in it.
+- **Record from a lazily-importing, swallow-all helper** when the call site is on a per-turn hot path — see `_record_redis_latency` in `ringg-bot/ringg_processors/llm_cache.py` and `_record_router_metrics` in `ringg-bot/utils/language_detection.py`. Telemetry must never raise into a live call, and the import must not drag the metrics stack into eval scripts.
+- **Names**: the SDK prefixes everything with `ringg.` and GMP rewrites it for PromQL — `ringg.language.router.duration` + `unit="s"` becomes `ringg_language_router_duration_seconds_{bucket,count,sum}`; a counter with `unit="1"` becomes `..._total`. A non-standard unit gets appended as a suffix, so use `"1"` even for money (put "USD" in the description).
+- **Dashboards as code**: `k8s/monitoring/dashboards/` — one JSON per dashboard plus a README with the `gcloud monitoring dashboards create/update` commands and the assigned resource ids.
+- **Tests**: `ringg_telemetry.testing.install_test_provider()` / `uninstall_test_provider()` route handles to an in-memory reader. See `ringg-bot/tests/test_metrics_bridge.py` and `tests/test_language_router_metrics.py`.
+
+## Data Residency
+
+- Some regions forbid their call data leaving regional storage. The single definition of that rule is `is_data_residency_restricted(region)` in `ringg-bot/utils/artifact_store.py` (currently `{"ksa"}`). **Consult it before any new write to the long-lived artifact bucket** — `RUNTIME_CONFIG_BUCKET` is US-located.
+- Restricted regions **skip** the write entirely: there is no fallback bucket and no re-routing. Applies to the runtime-config snapshot, the tool-call snapshot and the language-router samples (`utils/generic_functions/cleanup.py`, `utils/language_sample_store.py`). The data still reaches the region's own backend via the `call_completion` POST, and transcripts/recordings still go to the regional bucket via `utils/transcript._get_gcs_bucket`.
+- `region` is a **per-call** value (`RunConfig.region`, set by the backend), not a pod env var. On the two artifact uploaders it is keyword-only and *required* precisely so a new call site cannot become a violation by omission.
+- Skipping the upload must not skip local cleanup: `LOCAL_STORAGE_DIR` is the pod's `/tmp` and the pod outlives thousands of calls, so anything buffered on disk still has to be unlinked on the skip path.
+- Where feasible, gate at *capture* time too, not just upload time — e.g. `bot.py` passes `collect_samples=not is_data_residency_restricted(_region)` so raw user utterances are never written to `/tmp` for a restricted call.
+
 ## Logging
 
 - We use Loguru for all application logging. Do not use the Python `logging` module in app code; always `from loguru import logger`.

{dv_pipecat_flows-0.0.0.dev2766/src/dv_pipecat_flows.egg-info → dv_pipecat_flows-0.0.0.dev2810}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.0.dev2766
+Version: 0.0.0.dev2810
 Summary: Conversation Flow management for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Source, https://github.com/pipecat-ai/pipecat-flows

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2810/src/dv_pipecat_flows.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.0.dev2766
+Version: 0.0.0.dev2810
 Summary: Conversation Flow management for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Source, https://github.com/pipecat-ai/pipecat-flows

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2810}/src/dv_pipecat_flows.egg-info/scm_file_list.json

@@ -211,6 +211,8 @@
     "k8s/livekit/values-prod.yaml",
     "k8s/livekit/values-stage.yaml",
     "k8s/livekit/values.yaml",
+    "k8s/monitoring/dashboards/README.md",
+    "k8s/monitoring/dashboards/ringg-language-router.json",
     "pipecat-flows.png",
     "pipecat_upgrade.md",
     "pyproject.toml",
@@ -357,8 +359,10 @@
     "ringg-bot/test_bot.py",
     "ringg-bot/tests/__init__.py",
     "ringg-bot/tests/conftest.py",
+    "ringg-bot/tests/test_abandoned_call_report.py",
     "ringg-bot/tests/test_action_call_variables.py",
     "ringg-bot/tests/test_app_metrics.py",
+    "ringg-bot/tests/test_artifact_store.py",
     "ringg-bot/tests/test_asterisk_ami_client.py",
     "ringg-bot/tests/test_asterisk_ari_transfer_message.py",
     "ringg-bot/tests/test_asterisk_v1_transfer_numbers.py",
@@ -380,6 +384,7 @@
     "ringg-bot/tests/test_end_call_schema.py",
     "ringg-bot/tests/test_env_config_asterisk_ami.py",
     "ringg-bot/tests/test_execute_plan.py",
+    "ringg-bot/tests/test_find_button_api_config.py",
     "ringg-bot/tests/test_flow_query_kb.py",
     "ringg-bot/tests/test_gcs_fetch.py",
     "ringg-bot/tests/test_http_client_diagnostics.py",
@@ -391,6 +396,7 @@
     "ringg-bot/tests/test_job_reporting.py",
     "ringg-bot/tests/test_kb_planner.py",
     "ringg-bot/tests/test_language_map.py",
+    "ringg-bot/tests/test_language_router_metrics.py",
     "ringg-bot/tests/test_language_sample_store.py",
     "ringg-bot/tests/test_language_steering.py",
     "ringg-bot/tests/test_llm_cache.py",
@@ -410,12 +416,15 @@
     "ringg-bot/tests/test_on_call_sdk_context.py",
     "ringg-bot/tests/test_ozonetel_inbound.py",
     "ringg-bot/tests/test_ozonetel_transfer.py",
+    "ringg-bot/tests/test_rag_filter_operators.py",
+    "ringg-bot/tests/test_rag_filter_property_names.py",
     "ringg-bot/tests/test_realtime_external_tts.py",
     "ringg-bot/tests/test_recording_flush.py",
     "ringg-bot/tests/test_recording_stereo.py",
     "ringg-bot/tests/test_regression_monitor_sync.py",
     "ringg-bot/tests/test_replay_kb_flag.py",
     "ringg-bot/tests/test_runtime_config_language_normalization.py",
+    "ringg-bot/tests/test_runtime_config_upload.py",
     "ringg-bot/tests/test_sdk_executor_flatten.py",
     "ringg-bot/tests/test_sdk_tool_schema.py",
     "ringg-bot/tests/test_send_blocks_calendar.py",
@@ -547,6 +556,7 @@
     "ringg-bot/utils/tts.py",
     "ringg-bot/utils/twilio_async_client.py",
     "ringg-bot/utils/warning_messages.py",
+    "ringg-bot/utils/widget_transcript.py",
     "ringg-bot/utils/word_timestamp_logger.py",
     "ringg-bot/voice_services/asterisk/asterisk_service.py",
     "ringg-bot/voice_services/asterisk/router.py",
@@ -625,6 +635,7 @@
     "tests/test_condition_evaluator.py",
     "tests/test_context_strategies.py",
     "tests/test_credentials_resolver.py",
+    "tests/test_deployment_scaling_chart.py",
     "tests/test_end_call_inactivity.py",
     "tests/test_end_call_interruptible.py",
     "tests/test_end_call_provider_dispatch.py",
@@ -639,10 +650,9 @@
     "tests/test_openai_realtime_transcript_filter.py",
     "tests/test_response_formatters.py",
     "tests/test_router_extract_schema.py",
-    "tests/test_router_mode_guard.py",
     "tests/test_router_no_unclear.py",
+    "tests/test_router_wait_idle.py",
     "tests/test_tts_split_cache.py",
-    "tests/test_user_turn_observer.py",
     "tests/test_voicemail_detector.py",
     "uv.lock"
   ]

dv_pipecat_flows-0.0.0.dev2810/src/dv_pipecat_flows.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.0.0.dev0",
+  "distance": 2810,
+  "node": "gc326546704e7e1a6ee5805d1a16c7803d01dd4ae",
+  "dirty": false,
+  "branch": "dv-stage",
+  "node_date": "2026-08-12"
+}

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2810}/src/pipecat_flows/manager.py

@@ -1872,6 +1872,24 @@ In all of these cases, you can provide a `name` in your new node's config for de
             label="jump",
         )
 
+    def _last_context_role(self) -> Optional[str]:
+        """Role of the last message in the live LLM context, or None when no
+        context aggregator / empty context. Used by the router wait gate to
+        tell a real committed user turn apart from system-generated context
+        pushes (e.g. the idle warning's LLM-path append)."""
+        if not self._context_aggregator:
+            return None
+        ctx = self._context_aggregator.user()._context
+        messages = (
+            ctx.get_messages() if hasattr(ctx, "get_messages") else getattr(ctx, "messages", [])
+        )
+        if not messages:
+            return None
+        last = messages[-1]
+        if isinstance(last, dict):
+            return last.get("role")
+        return getattr(last, "role", None)
+
     async def _run_router_node(
         self, node_id: str, node_config: Dict[str, Any]
     ) -> Optional[str]:
@@ -1905,10 +1923,19 @@ In all of these cases, you can provide a `name` in your new node's config for de
         # `_run_router_node` captures a fresh entry_ts — the next iteration
         # correctly waits for a NEW user reply instead of reclassifying the
         # stale one that triggered the previous UNCLEAR.
+        #
+        # Silence handling is delegated to the user-idle processor: we re-arm
+        # it for the duration of the wait (it was stopped at `_set_node`
+        # entry) and block until the user actually replies. If they never do,
+        # the idle processor's warning → end stages fire and end the call —
+        # the router never classifies stale silence. The idle warning's
+        # fixed-phrase TTSSpeakFrame passes RouterModeGuard; its LLM-path
+        # fallback (realtime/chat-only/unsupported languages) is dropped by
+        # the guard, so that warning is silent but the end stage still ends
+        # the call.
         observer = self._user_turn_observer
 
-        timeout_s = float(node_config.get("router_wait_for_user_timeout", 15.0))
-        if observer is not None and timeout_s > 0:
+        if observer is not None:
             entry_ts = time.monotonic()
             if observer.last_user_stopped_ts >= entry_ts:
                 logger.debug(
@@ -1929,28 +1956,41 @@ In all of these cases, you can provide a `name` in your new node's config for de
                     )
                 else:
                     logger.debug(
-                        f"Router '{node_id}': waiting up to {timeout_s}s for "
-                        f"UserStoppedSpeakingFrame"
+                        f"Router '{node_id}': waiting for "
+                        f"UserStoppedSpeakingFrame (idle processor armed)"
                     )
+                    await self._task.queue_frame(StartUserIdleProcessorFrame())
                     try:
-                        await asyncio.wait_for(
-                            observer.event.wait(), timeout=timeout_s
-                        )
-                        logger.debug(
-                            f"Router '{node_id}': user reply received after "
-                            f"{time.monotonic() - entry_ts:.2f}s"
-                        )
-                    except asyncio.TimeoutError:
-                        # User stayed silent. Don't raise — let the router
-                        # LLM classify whatever context is available; it
-                        # will most likely return UNCLEAR, which the
-                        # existing pick_branch_target machinery routes to
-                        # reprompt or exhausted_node.
-                        logger.info(
-                            f"Router '{node_id}': no user reply within "
-                            f"{timeout_s}s; proceeding (will likely route "
-                            f"to unclear/exhausted)"
+                        while True:
+                            await observer.event.wait()
+                            # The observer fires on EVERY OpenAILLMContextFrame,
+                            # and with idle armed there IS a competing source:
+                            # the idle warning's LLM path (chat-only sessions,
+                            # realtime LLMs) appends its prompt with
+                            # run_llm=True, which makes the user aggregator push
+                            # a context frame with NO new user turn. Accept the
+                            # wake only when the last context message is the
+                            # user's; otherwise keep waiting for the real reply
+                            # (or for idle end-stage to end the call).
+                            role = self._last_context_role()
+                            if role is None or role == "user":
+                                break
+                            logger.debug(
+                                f"Router '{node_id}': ignoring context push "
+                                f"with last role '{role}' (idle warning, not a "
+                                f"user reply); still waiting"
+                            )
+                            observer.event.clear()
+                    finally:
+                        # Restore the "idle stopped while the node is
+                        # processing" invariant for the classifier call.
+                        await self._task.queue_frame(
+                            StopUserIdleProcessorFrame()
                         )
+                    logger.debug(
+                        f"Router '{node_id}': user reply received after "
+                        f"{time.monotonic() - entry_ts:.2f}s"
+                    )
 
         branches = node_config.get("router_branches") or []
         extract = node_config.get("router_extract") or {}

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2810}/src/pipecat_flows/processors/router_mode_guard.py

@@ -48,7 +48,6 @@ from typing import Callable, Tuple, Type
 
 from pipecat.frames.frames import (
     Frame,
-    LLMContextFrame,
     LLMMessagesFrame,
     LLMRunFrame,
     LLMTextFrame,
@@ -64,16 +63,6 @@ logger = logging.getLogger(__name__)
 # race-free fix for the spurious-bot-text problem.
 _TRIGGER_FRAME_TYPES: Tuple[Type[Frame], ...] = (
     OpenAILLMContextFrame,
-    # Universal context frame. `LLMContextFrame` and `OpenAILLMContextFrame` are
-    # SIBLINGS (both extend Frame directly), so matching one does NOT match the
-    # other — both must be listed. The pipeline picks between them from a single
-    # switch in the bot: `context = LLMContext() if (_use_responses or
-    # _use_universal_for_google) else OpenAILLMContext()`. Omitting this one let
-    # the LLM fire during router-mode nodes on every Responses-API agent
-    # (gpt-5.4-mini/nano are forced onto Responses regardless of the
-    # `use_responses_api` toggle) and every google/gemma agent — the bot spoke
-    # spurious freeform text instead of routing silently.
-    LLMContextFrame,
     LLMMessagesFrame,
     LLMRunFrame,
 )

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2810}/src/pipecat_flows/processors/user_turn_observer.py

@@ -1,5 +1,4 @@
-"""Observer that timestamps the user-turn-committed context frame
-(:class:`OpenAILLMContextFrame` **or** :class:`LLMContextFrame`) so router-mode
+"""Observer that timestamps :class:`OpenAILLMContextFrame` so router-mode
 nodes can detect "user turn is now committed to context" without reaching
 into the user context aggregator's private state.
 
@@ -8,27 +7,22 @@ Why an observer, not a FrameProcessor:
     public ``PipelineTask.add_observer`` API.
   * We only need a passive timestamp + an ``asyncio.Event`` — no frame routing.
 
-Why a context frame and not ``UserStoppedSpeakingFrame``:
+Why ``OpenAILLMContextFrame`` and not ``UserStoppedSpeakingFrame``:
   * ``UserStoppedSpeakingFrame`` is raw VAD — it fires the instant the mic
     detects silence, BEFORE the STT final lands and BEFORE the user-context
     aggregator appends the turn. Router gates that release on this signal
     classify against an empty/stale context.
-  * The context frame is pushed by ``LLMUserContextAggregator``
+  * ``OpenAILLMContextFrame`` is pushed by ``LLMUserContextAggregator``
     (``llm_response._process_aggregation``) only AFTER the final transcript
     is appended to the LLM context. It is the canonical "user turn is now
     in the context the router will read" event.
   * Router-mode never queues ``LLMRunFrame`` for the router node itself, so
-    the only context frame produced during a router invocation comes from
-    the aggregator's turn-complete path — no competing source.
-
-BOTH context-frame flavours must be matched (see
-``_USER_TURN_COMMITTED_FRAME_TYPES``): the aggregator emits
-``LLMContextFrame`` on the Responses-API / google / gemma paths and
-``OpenAILLMContextFrame`` on the Chat Completions path.
+    the only ``OpenAILLMContextFrame`` produced during a router invocation
+    comes from the aggregator's turn-complete path — no competing source.
 
 State exposed:
   * ``last_user_context_pushed_ts``: monotonic time of the latest
-    user-turn context frame (user turn committed to context).
+    ``OpenAILLMContextFrame`` (user turn committed to context).
   * ``last_user_stopped_ts``: backwards-compatible alias kept in sync with
     ``last_user_context_pushed_ts`` so existing callers keep working.
   * ``event``: ``asyncio.Event`` set on every such frame; the consumer is
@@ -44,41 +38,26 @@ from typing import List, Tuple
 
 from pipecat.frames.frames import (
     InterimTranscriptionFrame,
-    LLMContextFrame,
     TranscriptionFrame,
     UserStartedSpeakingFrame,
 )
 from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContextFrame
 from pipecat.observers.base_observer import BaseObserver, FramePushed
 
-# Both context-frame flavours mean the same thing here: "the user's turn is now
-# committed to the context the router will read". Which one the aggregator emits
-# is decided by one switch in the bot:
-#
-#     context = LLMContext() if (_use_responses or _use_universal_for_google)
-#               else OpenAILLMContext()
-#
-# They are SIBLINGS (both extend Frame directly, neither subclasses the other),
-# so matching one does NOT match the other. Keying on only OpenAILLMContextFrame
-# left every Responses-API / google / gemma agent's router waiting the full
-# ``router_wait_for_user_timeout`` (15s) after the caller had already replied.
-_USER_TURN_COMMITTED_FRAME_TYPES = (OpenAILLMContextFrame, LLMContextFrame)
-
 # Bound the per-call transcript log so a very long call can't grow it without
 # limit; far more than any single Collect dictation needs.
 _MAX_TRANSCRIPT_LOG = 256
 
 
 class UserTurnObserver(BaseObserver):
-    """Tracks the timestamp of the most recent user-turn context frame.
+    """Tracks the timestamp of the most recent ``OpenAILLMContextFrame``.
 
     Router-mode uses this to (a) detect a user reply already committed to
     context BEFORE the router was entered (barge-in during the preceding
     Speak's TTS) and (b) await the NEXT user reply when none is available.
 
-    The observer is keyed on the context frame (either flavour, see
-    ``_USER_TURN_COMMITTED_FRAME_TYPES``) rather than the raw VAD
-    ``UserStoppedSpeakingFrame`` because only the former guarantees the
+    The observer is keyed on ``OpenAILLMContextFrame`` rather than the raw
+    VAD ``UserStoppedSpeakingFrame`` because only the former guarantees the
     user's transcript has been appended to the LLM context the router reads.
     """
 
@@ -114,7 +93,7 @@ class UserTurnObserver(BaseObserver):
 
     @property
     def event(self) -> asyncio.Event:
-        """The asyncio.Event set on each user-turn context frame.
+        """The asyncio.Event set on each ``OpenAILLMContextFrame``.
 
         Callers MUST ``.clear()`` before awaiting if they want to wait for the
         NEXT frame (vs. immediately returning on a stale set state).
@@ -122,7 +101,7 @@ class UserTurnObserver(BaseObserver):
         return self._event
 
     async def on_push_frame(self, data: FramePushed) -> None:
-        if isinstance(data.frame, _USER_TURN_COMMITTED_FRAME_TYPES):
+        if isinstance(data.frame, OpenAILLMContextFrame):
             now = time.monotonic()
             self.last_user_context_pushed_ts = now
             self.last_user_stopped_ts = now

dv_pipecat_flows-0.0.0.dev2766/src/dv_pipecat_flows.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.0.0.dev0",
-  "distance": 2766,
-  "node": "g2f9ead0f53048f6c04d0647e37cff236bd770e14",
-  "dirty": false,
-  "branch": "dv-stage",
-  "node_date": "2026-08-08"
-}