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

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2786}/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.dev2786}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.0.dev2766
+Version: 0.0.0.dev2786
 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.dev2786/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.dev2786
 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.dev2786}/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",
@@ -359,6 +361,7 @@
     "ringg-bot/tests/conftest.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",
@@ -391,6 +394,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 +414,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",
@@ -625,6 +632,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 +647,8 @@
     "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_tts_split_cache.py",
-    "tests/test_user_turn_observer.py",
     "tests/test_voicemail_detector.py",
     "uv.lock"
   ]

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

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

{dv_pipecat_flows-0.0.0.dev2766 → dv_pipecat_flows-0.0.0.dev2786}/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.dev2786}/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"
-}