dv-pipecat-flows 0.0.23.dev9__tar.gz → 0.0.23.dev11__tar.gz

{dv_pipecat_flows-0.0.23.dev9 → dv_pipecat_flows-0.0.23.dev11}/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`.
@@ -399,6 +416,7 @@ curl -X POST https://api.ringg.ai/call \
 
 - `provider_metadata.asterisk_channel_id`, `provider_metadata.asterisk_sip_provider` — set by the bridge for Asterisk calls.
 - `provider_metadata.transfer.type`, `provider_metadata.transfer.sip_domain` — may be injected from dialplan variables (`TRANSFER_TYPE`, `TRANSFER_SIP_DOMAIN`) or ARI variables for outbound calls. Agents typically do not need to set these.
+- `call_config.transfer.include_call_numbers` — when true, `dialplan_context` transfers add this call's `to_number` / `from_number` to the SIP MESSAGE body. Defaults off.
 
 ## Next Steps
 

{dv_pipecat_flows-0.0.23.dev9/src/dv_pipecat_flows.egg-info → dv_pipecat_flows-0.0.23.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.23.dev9
+Version: 0.0.23.dev11
 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.23.dev11/remote-asterisk-code/README.md

@@ -0,0 +1,9 @@
+# remote-asterisk-code/ (deprecated)
+
+This directory is a stale, unmaintained mirror of the Asterisk dialplan and
+RTP configuration. **It is not the source of truth** — do not use it to
+infer current production behavior, and do not update it to reflect new
+Asterisk-side changes.
+
+The canonical source for the deployed Asterisk/Kamailio configuration is
+the `sip-infra` repository.

{dv_pipecat_flows-0.0.23.dev9 → dv_pipecat_flows-0.0.23.dev11}/remote-asterisk-code/extensions.conf

@@ -1,3 +1,10 @@
+; ============================================================================
+; DEPRECATED — this file is a stale, unmaintained mirror and is NOT the
+; source of truth for the deployed Asterisk dialplan. Canonical source:
+; the sip-infra repo (branch: main / feat/* per active work).
+; Do not use this file to infer current production behavior.
+; ============================================================================
+
 ; /etc/asterisk/extensions.conf  (minimal)
 
 [general]

{dv_pipecat_flows-0.0.23.dev9 → dv_pipecat_flows-0.0.23.dev11}/remote-asterisk-code/rtp.conf

@@ -1,3 +1,9 @@
+; ============================================================================
+; DEPRECATED — this file is a stale, unmaintained mirror and is NOT the
+; source of truth for the deployed Asterisk RTP config. Canonical source:
+; the sip-infra repo (branch: main / feat/* per active work).
+; ============================================================================
+
 sudo cat /etc/asterisk/rtp.conf 
 ;
 ; RTP Configuration

{dv_pipecat_flows-0.0.23.dev9 → dv_pipecat_flows-0.0.23.dev11/src/dv_pipecat_flows.egg-info}/PKG-INFO

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