dv-pipecat-flows 0.0.0.dev1644__tar.gz → 0.0.0.dev2087__tar.gz

dv_pipecat_flows-0.0.0.dev2087/.claude/skills/loki-logs/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: loki-logs
+description: Fetch and analyze pipecat application logs from Loki by call ID or call SID. Use when debugging call issues, investigating errors, or analyzing bot behavior for a specific call. Accepts a call_id (UUID) or call_sid (numeric string like 3341710001) and optional environment (staging/production).
+argument-hint: <call_id|call_sid> [staging|production]
+allowed-tools: Bash(curl *), Bash(jq *)
+---
+
+# Loki Logs Fetcher
+
+Fetch logs from Loki for a specific pipecat call and analyze them.
+
+## Parameters
+
+- `$0` — **call_id or call_sid** (required): Either a UUID (e.g. `f3df923e-d535-4eff-a3c8-fefbae0e73bf`) or a numeric call SID string (e.g. `3341710001`)
+- `$1` — **environment** (optional): `production` (default) or `staging`
+
+## Instructions
+
+When invoked, follow these steps:
+
+### 1. Parse arguments
+
+```
+IDENTIFIER = $0
+ENV = $1 (default: "production")
+```
+
+If `ENV` is `prod`, normalize it to `production`.
+If `IDENTIFIER` is missing, ask the user for it.
+
+Detect the identifier type:
+- **UUID format** (contains hyphens, hex chars, e.g. `f3df923e-d535-...`): This is a `call_id`
+- **Numeric string** (digits only, e.g. `3341710001`): This is a `call_sid`
+
+Both work the same way in the Loki query — they are used as a substring match (`|=`) against the log lines.
+
+### 2. Fetch logs from Loki
+
+Use the Loki HTTP API at `http://35.154.72.110:3100` to query logs.
+
+The LogQL query to use:
+
+```
+{application="pipecat", environment="<ENV>"} |= `<IDENTIFIER>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+Execute this curl command (default time range: last 24 hours):
+
+**Timezone note:** If the user provides a specific time or time range, treat it as **IST (Asia/Kolkata, UTC+5:30)**. Convert to UTC epoch before querying Loki.
+
+```bash
+# Calculate timestamps (nanoseconds) — default: last 24 hours
+END=$(date +%s)000000000
+START=$(( $(date +%s) - 86400 ))000000000
+
+curl -s "http://35.154.72.110:3100/loki/api/v1/query_range" \
+  --data-urlencode "query={application=\"pipecat\", environment=\"<ENV>\"} |= \`<IDENTIFIER>\` | json | level=~\"(?i)DEBUG|INFO|WARNING|ERROR|FATAL\" | line_format \`{{.message}}\`" \
+  --data-urlencode "start=$START" \
+  --data-urlencode "end=$END" \
+  --data-urlencode "limit=5000" \
+  --data-urlencode "direction=forward" | jq .
+```
+
+If the result set is empty and the environment was `production`, suggest trying `staging` (and vice versa).
+
+If the result set is empty for both, try expanding the time range to 48 hours.
+
+### 3. Parse and display the logs
+
+Extract the log lines from the Loki JSON response. The response structure is:
+
+```json
+{
+  "data": {
+    "result": [
+      {
+        "values": [
+          ["<timestamp_ns>", "<log_line>"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+Display the logs in chronological order (earliest first). Show:
+- Timestamp (human-readable)
+- Log level (if parseable)
+- Message content
+
+### 4. Analyze the logs
+
+After displaying the logs, provide a brief analysis:
+
+1. **Call timeline**: What happened during this call? (connected, greeted, conversation flow, ended)
+2. **Errors/warnings**: Highlight any ERROR or WARNING level logs
+3. **Tool calls**: List any function/tool calls made during the call
+4. **TTS/STT activity**: Note any speech-related events
+5. **Call outcome**: How did the call end? (normal hangup, error, transfer, timeout)
+6. **Anomalies**: Flag anything unusual (long silences, repeated errors, unexpected state transitions)
+
+### 5. Grafana link
+
+Always provide a clickable Grafana Explore link for the user to view the logs in the browser:
+
+```
+http://35.154.72.110:3000/explore?schemaVersion=1&panes=%7B%221f1%22%3A%7B%22datasource%22%3A%22eeey6hiactdz4c%22%2C%22queries%22%3A%5B%7B%22datasource%22%3A%7B%22type%22%3A%22loki%22%2C%22uid%22%3A%22eeey6hiactdz4c%22%7D%2C%22direction%22%3A%22backward%22%2C%22editorMode%22%3A%22code%22%2C%22expr%22%3A%22%7Bapplication%3D%5C%22pipecat%5C%22%2C+environment%3D%5C%22<ENV>%5C%22%7D+%7C%3D+%60<IDENTIFIER>%60+%7C+json+%7C+level%3D%7E%5C%22%28%3Fi%29DEBUG%7CINFO%7CWARNING%7CERROR%7C+FATAL%5C%22+%7C+line_format+%60%7B%7B.message%7D%7D%60%22%2C%22queryType%22%3A%22range%22%2C%22refId%22%3A%22A%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22now-6h%22%2C%22to%22%3A%22now%22%7D%2C%22compact%22%3Afalse%7D%7D&orgId=1
+```
+
+Replace `<ENV>` and `<IDENTIFIER>` in the URL with the actual values (URL-encoded where needed).
+
+## Troubleshooting
+
+- If curl times out, the Loki instance may be under heavy load — retry with a shorter time range or lower limit.
+- If you get no results, confirm the call_id is correct and try the other environment.
+- For very old calls (>48h), increase the time range or ask the user for an approximate time window.
+- All user-provided times are in **IST (UTC+5:30)** — convert to UTC epoch before querying.
+
+## Reference
+
+For LogQL query syntax and more filtering options, see [query-reference.md](query-reference.md).

dv_pipecat_flows-0.0.0.dev2087/.claude/skills/loki-logs/query-reference.md

@@ -0,0 +1,113 @@
+# LogQL Query Reference for Pipecat Logs
+
+## Base Query Pattern
+
+```logql
+{application="pipecat", environment="<env>"} |= `<call_id>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+## Common Variations
+
+### Filter by log level
+
+**Errors only:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)ERROR|FATAL" | line_format `{{.message}}`
+```
+
+**Warnings and above:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)WARNING|ERROR|FATAL" | line_format `{{.message}}`
+```
+
+### Filter by keyword
+
+**LLM-related logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | level=~"(?i)DEBUG|INFO|WARNING|ERROR|FATAL" | line_format `{{.message}}` |= "LLM"
+```
+
+**TTS-related logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |= "TTS"
+```
+
+**Tool/function call logs:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |~ "function|tool_call|generic_function"
+```
+
+**VAD/speech detection:**
+```logql
+{application="pipecat", environment="staging"} |= `<call_id>` | json | line_format `{{.message}}` |~ "VAD|speaking|speech|silence|idle"
+```
+
+### Search across all calls in an environment
+
+**Recent errors (no call_id filter):**
+```logql
+{application="pipecat", environment="staging"} | json | level=~"(?i)ERROR|FATAL" | line_format `{{.message}}`
+```
+
+**By pod name:**
+```logql
+{application="pipecat", environment="staging", pod=~"pipecat-.*"} | json | line_format `{{.message}}`
+```
+
+## Loki API Endpoints
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /loki/api/v1/query_range` | Query logs over a time range |
+| `GET /loki/api/v1/query` | Query logs at a single point in time |
+| `GET /loki/api/v1/labels` | List all label names |
+| `GET /loki/api/v1/label/<name>/values` | List values for a label |
+| `GET /loki/api/v1/tail` | Stream logs via WebSocket |
+
+### API Parameters for query_range
+
+| Parameter | Description | Example |
+|-----------|-------------|---------|
+| `query` | LogQL query string | `{application="pipecat"}` |
+| `start` | Start timestamp (nanoseconds or RFC3339) | `1609459200000000000` |
+| `end` | End timestamp (nanoseconds or RFC3339) | `1609545600000000000` |
+| `limit` | Max entries to return | `5000` |
+| `direction` | Sort order: `forward` or `backward` | `forward` |
+| `step` | Query resolution step (for metrics) | `60s` |
+
+## Response Structure
+
+```json
+{
+  "status": "success",
+  "data": {
+    "resultType": "streams",
+    "result": [
+      {
+        "stream": {
+          "application": "pipecat",
+          "environment": "staging",
+          "level": "INFO"
+        },
+        "values": [
+          ["1700000000000000000", "log message here"],
+          ["1700000001000000000", "another log message"]
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Environment Values
+
+| Environment | Label Value | Description |
+|-------------|-------------|-------------|
+| Staging | `staging` | Test/staging environment |
+| Production | `production` | Live production environment |
+
+## Infrastructure
+
+- **Loki endpoint**: `http://35.154.72.110:3100`
+- **Grafana UI**: `http://35.154.72.110:3000`
+- **Loki datasource UID**: `eeey6hiactdz4c`

dv_pipecat_flows-0.0.0.dev2087/.python-version

@@ -0,0 +1 @@
+3.12.0

{dv_pipecat_flows-0.0.0.dev1644 → dv_pipecat_flows-0.0.0.dev2087}/AGENTS.md

@@ -135,6 +135,27 @@ Example `call_config`:
   - Flow tools fetch it via `s.get("bot_logger")` (e.g., `ringg-bot/utils/flow_tools/query_kb.py:28`). Prefer `bot_logger` when available, otherwise fall back to the global `logger`.
 - Environment knobs for the custom logger (see `logger_config.py`): `ENVIRONMENT`, `LOGGER_NAME`, `GRAFANA_HOST` (enables Loki sink), and `LOG_DIRECTORY` (file sink path). In development, logs also go to console; in production, they rotate to `pipecat.log` and optionally ship to Loki.
 - Interop: standard `logging` may appear in isolated places (e.g., Sphinx docs or third‑party adapters), but do not add `logging.getLogger(...)` or `basicConfig` in application modules. Stick to Loguru and the provided config.
+
+### Message formatting — Loguru is **not** stdlib logging
+
+Common gotcha: stdlib `logging.info("x=%s", val)` does printf-style lazy interpolation. Loguru does **not** — it ignores positional `args` and prints the format string verbatim. Use one of these instead:
+
+```python
+# Preferred: f-string (eager interpolation, simplest)
+logger.info(f"call started call_id={call_id} agent={agent_id}")
+
+# Or: Loguru's brace syntax with positional/keyword args
+logger.info("call started call_id={} agent={}", call_id, agent_id)
+logger.info("call started call_id={cid}", cid=call_id)
+
+# WRONG — leaks raw "%s" into logs because Loguru does not consume *args
+logger.info("call started call_id=%s agent=%s", call_id, agent_id)
+```
+
+If a log line shows up in Loki/console as `... call_id=%s ...` instead of the actual value, this is the cause — convert to f-string or `{}` style.
+
+Bound context (via `logger.bind(call_id=...)`) is passed through `extra=` and is independent of the message format — it works the same regardless of which interpolation style you pick.
+
 - Retry & timeout knobs live in `utils/pipeline.py` (idle handlers, hold detector) and `utils/stay_on_line_processor.py`. Update both place and config schema when adjusting thresholds.
 
 ## Working Guidelines for LLM Instructions

{dv_pipecat_flows-0.0.0.dev1644/src/dv_pipecat_flows.egg-info → dv_pipecat_flows-0.0.0.dev2087}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.0.dev1644
+Version: 0.0.0.dev2087
 Summary: Conversation Flow management for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Source, https://github.com/pipecat-ai/pipecat-flows
@@ -18,6 +18,9 @@ License-File: LICENSE
 Requires-Dist: dv-pipecat-ai>=0.0.85.dev0
 Requires-Dist: loguru~=0.7.2
 Requires-Dist: docstring_parser~=0.16
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
 Dynamic: license-file
 
 <h1><div align="center">
@@ -148,7 +151,6 @@ Run specific test:
 ```bash
 uv run pytest tests/test_state.py -k test_initialization
 ```
-
 Run with coverage report:
 
 ```bash
@@ -306,3 +308,5 @@ We aim to review all contributions promptly and provide constructive feedback to
 
 ➡️ [Reach us on X](https://x.com/pipecat_ai)
 
+
+

{dv_pipecat_flows-0.0.0.dev1644 → dv_pipecat_flows-0.0.0.dev2087}/README.md

@@ -126,7 +126,6 @@ Run specific test:
 ```bash
 uv run pytest tests/test_state.py -k test_initialization
 ```
-
 Run with coverage report:
 
 ```bash
@@ -284,3 +283,5 @@ We aim to review all contributions promptly and provide constructive feedback to
 
 ➡️ [Reach us on X](https://x.com/pipecat_ai)
 
+
+

dv_pipecat_flows-0.0.0.dev2087/engine_primitives_plan.md

@@ -0,0 +1,128 @@
+# Engine Primitives — Unified Implementation Plan
+
+> Branch target: `feat/engine-primitives` in `dv-pipecat-flows`. Lands four primitives together: **auto_transition**, **condition_evaluator**, **router_mode_llm**, **llm_override + tool_choice**.
+>
+> Companion: [../new_calling_agent_backend/deterministic_agents_plan.md](../new_calling_agent_backend/deterministic_agents_plan.md) §6 Phase 1.
+
+## 1. Shared touchpoints — edit once, not four times
+
+| Touchpoint | File / line | Contributors | Unified shape & ordering |
+|---|---|---|---|
+| **`_set_node` dispatch block** | `manager.py:1012` | auto_transition, condition_evaluator, router_mode_llm | Introduce a single **dispatch pipeline** between `pre_actions` execution (1065) and `LLMRunFrame` emission (1165). Sequence: (a) `pre_actions` run; (b) `_apply_node_overrides` (now also handles `llm_override`); (c) `_process_data_extraction`; (d) **`_maybe_route_pure_code(node_id, node_config)`** which short-circuits if condition / auto-transition / router fires; (e) only if no short-circuit, continue to tools+context+`LLMRunFrame`. Single early-return point; each primitive contributes one helper. |
+| **`NodeConfig` TypedDict** | `types.py:357` | all four | One PR adds `auto_transition`, `llm_mode`, `llm_override`, `router_branches`, `router_extract`, `router_unclear_node`, `router_max_unclear`, `router_exhausted_node`, `suppress_llm_text`, `forced_route_at_end_of_turn`, `tool_choice`, `conditions`, `router_default_next`. Plus supporting types (`AutoTransitionBranches`, `LLMOverride`, `RouterBranch`, `ExtractSpec`, `Condition`, `Rule`). All `NotRequired`; legacy nodes unaffected. |
+| **`_apply_node_overrides`** | `manager.py:912` | llm_override (primary), router_mode_llm (consumer) | Add LLM-switch block mirroring the TTS pattern: snapshot active LLM in `node_runtime["_llm_restore"]`, queue `ManuallySwitchServiceFrame`. Router-mode reads the *already-resolved* `active_llm` rather than re-resolving — single resolution path. |
+| **`format_functions` signature** | `adapters.py:77, 225, 418` | llm_override (tool_choice), router_mode_llm | New optional kwarg `tool_choice`. Each subclass returns a `(tools, native_tool_choice)` tuple. Router-mode reuses this when it chooses tool-shaped structured output (Anthropic / Bedrock-Claude); JSON-schema providers (OpenAI / Gemini) take the `response_format` path inside `run_router_completion`. |
+| **`LLMSetToolsFrame` emission** | `manager.py:1277` | llm_override, router_mode_llm | Accept `tool_choice=...` kwarg; one emission site, consumed by aggregator. |
+| **Idle-processor bracket** | `manager.py:1043 / 1176` | auto_transition, condition_evaluator | Both short-circuit paths re-emit `StartUserIdleProcessorFrame` before recursing so the recursive `_set_node` re-establishes the bracket cleanly. Encoded once in `_short_circuit_to(next_id)` helper. |
+| **State + tool-result snapshot** | `FlowManager.__init__` | auto_transition (`_last_action_result`), condition_evaluator (`_pending_function_results`), router_mode_llm (`state["_router_attempts"]`) | All three live on `FlowManager`. Add a dedicated `self._primitive_state` namespace (dict) to keep them grouped and easy to clear on `cancel()`. |
+| **Frame interruption observer** | manager.py (`UserInterruptedFrame` handler) | auto_transition (cancel pending), router_mode_llm (abort in-flight completion) | One observer extension sets cancellation flags consumed by both primitives. |
+| **`flow_validator.py` (NEW)** | new file | all four | Single validator pass: rejects `post_actions` + `auto_transition`; `respond_immediately` + `auto_transition`; cycle without `router_max_unclear`; reserved extraction keys; `llm_override` with unknown provider; `tool_choice` with unsupported provider (warn, don't fail). |
+
+---
+
+## 2. Implementation order (4 PRs on the branch, merged in sequence)
+
+1. **Foundation (PR-1).** `types.py` additions + `flow_validator.py` skeleton + `exceptions.py` (`RouterParseError`, `RouterProviderError`). No behavior change. *Justification:* every later PR imports these; landing types first means PR-2/3/4 are pure feature wiring with no rebase pain.
+2. **Adapter plumbing (PR-2).** `format_functions(..., tool_choice=...)` across all four adapters + `LLMSetToolsFrame` kwarg + `_apply_node_overrides` LLM-switch block. *Justification:* this is purely additive infrastructure; router-mode (PR-4) depends on it; auto-transition and condition-evaluator do not — so we can land and unit-test in isolation.
+3. **Pure-code dispatchers (PR-3).** `condition_evaluator.py` module + `auto_transition` block + the unified `_maybe_route_pure_code` dispatcher in `_set_node`. *Justification:* both are LLM-free and verifiable with mocked frame queues; they exercise the new dispatch pipeline before we add the heavier router-mode path.
+4. **Router-mode LLM (PR-4).** Per-adapter `run_router_completion` + `_run_router_node` + `RouterModeGuard` hook + unclear-loop state machine. *Justification:* heaviest, touches network + provider quirks; landing last means it inherits a stable dispatch contract and adapter shape.
+
+Phase 1 of `../new_calling_agent_backend/deterministic_agents_plan.md` §6 maps to PR-1 + PR-2; Phase 2 picks up after PR-3.
+
+---
+
+## 3. Per-file diff outline
+
+| File | Change | ~LOC | Contributors |
+|---|---|---|---|
+| `src/pipecat_flows/types.py` | Add `AutoTransitionBranches`, `LLMOverride`, `RouterBranch`, `ExtractSpec`, `Rule`, `Condition`, extend `NodeConfig` with 12 new optional keys. | +110 | all four |
+| `src/pipecat_flows/exceptions.py` | Add `RouterParseError`, `RouterProviderError`, `AutoTransitionDepthError`. | +20 | router, auto |
+| `src/pipecat_flows/manager.py` | (a) `__init__` adds `_last_action_result`, `_pending_auto_transition_cancelled`, `_auto_transition_depth`, `_primitive_state`. (b) `_apply_node_overrides` LLM-switch block + restore-on-teardown. (c) New `_maybe_route_pure_code`, `_short_circuit_to`, `_await_pre_actions_complete`, `_resolve_auto_transition_target`, `_resolve_llm_from_switcher`, `_run_router_node`, `_handle_router_unclear`, `_parse_router_response`. (d) `_set_node` rewires dispatch sequence; only ~8 lines added inline (the rest are helper calls). (e) Interruption observer extension. | +280 / −12 | all four |
+| `src/pipecat_flows/actions.py` | `_handle_function_action` (line 353) writes `flow_manager._last_action_result` (success/failure/value). Wrap existing try/except. | +25 | auto_transition |
+| `src/pipecat_flows/adapters.py` | `format_functions` gets `tool_choice` kwarg in base + 3 subclasses; each returns `(tools, native_tool_choice)`. Add `run_router_completion` + `format_router_call` to each subclass (OpenAI JSON-schema, Anthropic tool-forced, Gemini `response_schema`, Bedrock dual-path). | +220 | llm_override, router |
+| `src/pipecat_flows/data_extractor.py` | No changes (router-mode writes directly into `state`, sharing the same flat namespace contract). | 0 | — |
+| `src/pipecat_flows/__init__.py` | Re-export new public types + `evaluate_conditions`. | +8 | all four |
+
+---
+
+## 4. New files
+
+- `src/pipecat_flows/condition_evaluator.py` — pure-function rule evaluator + variable resolver (no I/O, no manager refs).
+- `src/pipecat_flows/flow_validator.py` — static graph validator invoked once at `FlowManager.__init__`; enforces primitive-combination rules and reserved keys.
+- `src/pipecat_flows/router_mode.py` — schema builder, prompt builder, response parser, unclear-loop bookkeeping (keeps `manager.py` from ballooning further).
+- `src/pipecat_flows/processors/router_mode_guard.py` — `FrameProcessor` subclass dropping `LLMTextFrame` etc. when `current_node_config.suppress_llm_text` is true. Owned by flows because the policy is per-node.
+- `tests/conftest_primitives.py` — shared fixtures: `make_flow_manager(nodes, state=…, llm=FakeLLM())`, fake `LLMSwitcher`, fake adapter, frame-queue sink.
+
+---
+
+## 5. Test strategy
+
+```
+tests/
+  conftest_primitives.py                 # shared fixtures
+  unit/
+    test_types_validation.py             # NodeConfig keys, flow_validator rules
+    test_condition_evaluator.py          # ~60 parametrised op cases (PR-3)
+    test_auto_transition_unit.py         # str/branches, timeout, cancel, depth cap
+    test_router_parser.py                # JSON, type coercion, unknown branch
+    test_adapters_tool_choice.py         # per-provider native shape snapshots
+    test_adapters_router_completion.py   # mocked HTTP per provider
+    test_apply_node_overrides_llm.py     # switcher snapshot/restore
+  integration/
+    test_dispatch_pipeline.py            # _set_node short-circuit ordering
+    test_auto_transition_pipeline.py     # Speak→Speak, no LLMRunFrame, barge-in
+    test_condition_node_routing.py       # state + tool-output routing
+    test_router_flow.py                  # 3 malformed → exhausted; provider timeout
+    test_router_mode_guard.py            # text-frame suppression per-node
+    test_primitive_combinations.py       # router → condition → auto chain
+  fixtures/
+    monica_flow.json                     # §7 below
+    mocked_provider_payloads/            # snapshot baselines
+```
+
+**Minimal FlowManager for unit tests** — `make_flow_manager(nodes, state=None, llm=None)` in `conftest_primitives.py`:
+
+```python
+def make_flow_manager(nodes, state=None, llm=None):
+    task = FakePipelineTask()                # records queued frames
+    llm = llm or FakeLLM()                   # implements register_function + active_llm
+    fm = FlowManager(task=task, llm=llm,
+                     flow_config={"initial_node": next(iter(nodes)), "nodes": nodes})
+    if state: fm.state.update(state)
+    return fm, task
+```
+
+Backend smoke test lives at `../new_calling_agent_backend/tests/test_flow_lowering_primitives.py`: asserts `flow_lowering.py` emits the new keys (`auto_transition`, `llm_mode`, `conditions`, `llm_override`, `tool_choice`) only for the right node types.
+
+---
+
+## 6. Top 5 risks
+
+1. **Interruption races at the dispatch boundary.** Barge-in landing between `pre_actions` finishing and the short-circuit `_set_node` call could leave a half-updated `_current_node` and a stalled idle bracket. *Mitigation:* `_pending_auto_transition_cancelled` flag + `_ongoing_actions_finished_event.set()` in the interruption observer; integration test covers it.
+2. **Provider feature gaps for structured output.** Bedrock-Llama/Titan don't support JSON-schema or forced tool_use; Gemini's `response_schema` has stricter subset of JSON-schema than OpenAI. *Mitigation:* per-adapter fallback ladder (native schema → tool-forced → prompt-engineered + validate-retry-once); validator warns at startup if `llm_override` selects a provider lacking router support.
+3. **Dispatch ordering regressions.** Six things now happen between `pre_actions` and `LLMRunFrame`. Moving them silently breaks legacy generative nodes. *Mitigation:* `test_dispatch_pipeline.py` asserts exact frame-queue ordering on a vanilla LLM node; CI gate on this test.
+4. **LLM-switch mid-generation.** `ManuallySwitchServiceFrame` on a node entry while previous node's response is still streaming corrupts the aggregator. *Mitigation:* defer override switch until `is_generating` is false; if router/auto short-circuit fired (no streaming), apply immediately. Add `test_apply_node_overrides_llm.py::test_switch_waits_for_generation_complete`.
+5. **Auto-transition / router cycles.** Misconfigured graphs (A→A via auto, or router whose unclear_node loops back) can pin the call. *Mitigation:* `_auto_transition_depth` cap of 16, existing `_max_node_transitions` guard, and `flow_validator` rejects self-loops without a `router_max_unclear` counter; loud `FlowError` on exhaustion.
+
+---
+
+## 7. Cred Monica integration end-to-end check
+
+Once all four primitives land, scripted graph `tests/fixtures/monica_flow.json` (~14 Speak + 11 Hindi mirrors + 3 routers + 2 End — per `../new_calling_agent_backend/deterministic_agents_plan.md` §9.2) is the golden integration. Minimum verification driver `tests/integration/test_monica_e2e.py`:
+
+1. **Greeting → terminal (happy path "agrees to pay")** — drives `greeting` (Speak with `auto_transition: classify_intent`), feeds a fake user turn "yes I'll pay", asserts `classify_intent` router (llm_mode=router, Haiku via `llm_override`) returns `{branch: "agrees_to_pay"}`, asserts `say_agrees` Speak fires with `auto_transition: end_success`. **No `LLMRunFrame` emitted across the whole 3-node chain.**
+2. **Sensitive-reason branch** — drives `classify_intent` → `ask_reason` → `classify_reason` (router with extract) → `say_sensitive` → `end_success`. Assert extracted `reason_category="sensitive"` is in `state`.
+3. **Unclear loop exhaustion** — feed two consecutive garbled replies to `classify_intent` with `router_max_unclear: 2`; assert traversal lands on `end_default` (exhausted_next).
+4. **Hindi language switch** — `classify_intent` returns `{branch: "wants_hindi"}` + `extracted.language="hi"`; assert `ask_hindi_confirm` → `route_hindi_yesno` → `greeting_hi` chain executes with `overrides.tts.language="hi"` applied through `_apply_node_overrides`.
+5. **Latency assertion** — using `FakePipelineTask`'s recorded timestamps, assert greeting → classify_intent → terminal Speak completes in < 100ms wall-clock with mocked LLM (the real bot target is < 0.9s; this checks the engine adds no extra hops). Pre-render is out of scope for this PR (Phase 3 in plan §6).
+6. **Backward-compat regression** — re-run existing `tests/test_manager.py` and `tests/test_actions.py` unchanged; all green.
+
+If all six pass, the engine side of §9 is shippable and the backend can begin Phase 2 (`flow_lowering.py` emitting these keys, already prototyped in the backend repo's `agent/commons/flow_lowering.py`).
+
+Relevant absolute paths:
+- `src/pipecat_flows/manager.py`
+- `src/pipecat_flows/types.py`
+- `src/pipecat_flows/adapters.py`
+- `src/pipecat_flows/actions.py`
+- `../new_calling_agent_backend/deterministic_agents_plan.md` §9
+- `../new_calling_agent_backend/agent/commons/flow_lowering.py`

dv_pipecat_flows-0.0.0.dev2087/evals/kb/.gitignore

@@ -0,0 +1,2 @@
+# Eval-api job records — generated run output, regenerated per run.
+runs/