dv-pipecat-flows 0.0.22.dev1900__tar.gz → 0.0.22.dev2100__tar.gz

{dv_pipecat_flows-0.0.22.dev1900/src/dv_pipecat_flows.egg-info → dv_pipecat_flows-0.0.22.dev2100}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.22.dev1900
+Version: 0.0.22.dev2100
 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.22.dev1900 → dv_pipecat_flows-0.0.22.dev2100}/engine_primitives_plan.md

@@ -48,7 +48,7 @@ Phase 1 of `../new_calling_agent_backend/deterministic_agents_plan.md` §6 maps
 ## 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/flow_validator.py` — static graph validator (skeleton; rule bodies + wiring land in PR-2/3/4). Intended to be invoked once from `FlowManager.initialize()`; will enforce primitive-combination rules and reserved keys. Not yet called at runtime.
 - `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.

{dv_pipecat_flows-0.0.22.dev1900 → dv_pipecat_flows-0.0.22.dev2100/src/dv_pipecat_flows.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.22.dev1900
+Version: 0.0.22.dev2100
 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.22.dev1900 → dv_pipecat_flows-0.0.22.dev2100}/src/pipecat_flows/actions.py

@@ -46,6 +46,16 @@ if TYPE_CHECKING:
     from pipecat_flows.manager import FlowManager
 
 
+# Deadlock backstop for the "wait until ongoing actions finish" condition-wait.
+# Normally `_ongoing_actions_finished_event` is set when the trailing action's
+# frame (e.g. BotStoppedSpeakingFrame) arrives downstream. But a barge-in can
+# flush that frame while the count stays >0, so the event is never set and the
+# wait hangs forever (no `except` can rescue a never-returning await). This cap
+# is generous on purpose — it must exceed any realistic TTS/function duration
+# so it never truncates legitimate audio, only breaks a genuine hang.
+ONGOING_ACTIONS_WAIT_TIMEOUT_S = 60.0
+
+
 @dataclass
 class FunctionActionFrame(ControlFrame):
     """Frame containing a function action to be executed.
@@ -364,7 +374,19 @@ class ActionManager:
             pass
 
         if needs_wait:
-            await self._ongoing_actions_finished_event.wait()
+            try:
+                await asyncio.wait_for(
+                    self._ongoing_actions_finished_event.wait(),
+                    timeout=ONGOING_ACTIONS_WAIT_TIMEOUT_S,
+                )
+            except asyncio.TimeoutError:
+                logger.warning(
+                    "Timed out after %ss waiting for ongoing actions to finish "
+                    "(previous=%s); the finished-event was never set — continuing "
+                    "to avoid a permanent hang.",
+                    ONGOING_ACTIONS_WAIT_TIMEOUT_S,
+                    previous_action_type,
+                )
 
     async def _handle_tts_action(self, action: dict) -> None:
         """Built-in handler for TTS actions.

{dv_pipecat_flows-0.0.22.dev1900 → dv_pipecat_flows-0.0.22.dev2100}/src/pipecat_flows/flow_validator.py

@@ -6,8 +6,14 @@
 
 """Static validation of FlowConfigs that use the engine-primitive fields.
 
-Invoked once at ``FlowManager.__init__`` (before any node is set) so that
-misconfigured graphs fail loudly at startup instead of mid-call. Rules cover
+NOTE: This module is a SKELETON and is NOT yet wired in. ``validate_flow_config``
+is not called from ``FlowManager`` today and every rule body is a stub — there
+is currently no active static validation at startup. The intended design is to
+invoke it once from ``FlowManager.initialize()`` (before any node is set) so
+that misconfigured graphs fail loudly at startup instead of mid-call, raising
+``FlowInitializationError`` when ``result.errors`` is non-empty. That wiring,
+and the rule bodies, land in PR-2/3/4 alongside the primitives they guard.
+Until then, do not rely on this for any safety guarantee. Planned rules cover
 the combinatorics of the four primitives we add together:
 
   * auto_transition + post_actions (conflicting lifecycle)

{dv_pipecat_flows-0.0.22.dev1900 → dv_pipecat_flows-0.0.22.dev2100}/src/pipecat_flows/manager.py

@@ -185,7 +185,17 @@ class FlowManager:
         self._last_router_pick: Optional[Dict[str, Any]] = None
         self._context_aggregator = context_aggregator
         self._pending_transition: Optional[Dict[str, Any]] = None
-        self._pending_function_results: Dict[str, Dict[str, Any]] = {}  # Store function results for extraction
+        # Result ("success"/"failure") of the most recent function action, set
+        # by ActionManager and read by the dict-`auto_transition` resolver.
+        # Initialised to None and reset on node entry so a node with a
+        # success/failure dict that runs no function action this turn can't
+        # read a stale result from a previous node.
+        self._last_action_result: Optional[str] = None
+        # Strong references to detached fire-and-forget observability tasks.
+        # asyncio only holds weak refs to running tasks, so without this set a
+        # publish task can be GC'd mid-flight before its inner wait_for
+        # completes. Tasks discard themselves on completion (add_done_callback).
+        self._bg_tasks: set[asyncio.Task] = set()
         self._context_strategy = context_strategy or ContextStrategyConfig(
             strategy=ContextStrategy.APPEND
         )
@@ -331,10 +341,13 @@ class FlowManager:
                 logger.warning(f"observability publish '{label}' failed: {exc!r}")
 
         task = asyncio.create_task(_wrapped())
-        # Suppress "Task exception was never retrieved" — `_wrapped` swallows
-        # the exception itself, but `create_task` still wants the result
-        # acknowledged. A no-op callback is enough.
-        task.add_done_callback(lambda _t: None)
+        # Retain a strong reference so the loop's weak-ref bookkeeping can't GC
+        # this task before `_wrapped` finishes; the callback both discards the
+        # reference and acknowledges the result (suppressing the "Task
+        # exception was never retrieved" warning, though `_wrapped` already
+        # swallows it).
+        self._bg_tasks.add(task)
+        task.add_done_callback(self._bg_tasks.discard)
 
     @property
     def transport(self) -> Optional[BaseTransport]:
@@ -682,10 +695,6 @@ class FlowManager:
                     f"{'Transition-only function called for' if is_transition_only_function else 'Function handler completed for'} {name}"
                 )
 
-                # Store function result for potential extraction
-                if result and not is_transition_only_function:
-                    self._pending_function_results[name] = result
-
                 # Determine if this is an edge function
                 is_edge_function = (
                     bool(next_node) or bool(transition_to) or bool(transition_callback)
@@ -1039,10 +1048,12 @@ In all of these cases, you can provide a `name` in your new node's config for de
                 default_next=default_next,
             )
 
-        # Case 2: Action node with success/failure dict.
+        # Case 2: Action node with success/failure dict. `_last_action_result`
+        # is reset to None on node entry and set by this node's own function
+        # action; None (no action ran) and "success" both take the success
+        # branch — only an explicit "failure" routes to the failure target.
         if isinstance(auto_transition, dict):
-            result = getattr(self, "_last_action_result", "success")
-            key = "failure" if result == "failure" else "success"
+            key = "failure" if self._last_action_result == "failure" else "success"
             return auto_transition.get(key) or auto_transition.get("success")
 
         # Case 1: bare string (Speak / single-target Action).
@@ -1403,7 +1414,11 @@ In all of these cases, you can provide a `name` in your new node's config for de
         # override=Gemini) isn't supported by this path yet.
         llm_service = self.state.get("interrupt_classifier_llm_service") or self._llm
         if isinstance(llm_service, LLMSwitcher):
-            llm_service = llm_service.active_service
+            # LLMSwitcher exposes the live service via the `active_llm`
+            # property (it proxies `self.strategy.active_service`). The
+            # switcher itself has no `active_service` attribute — reading it
+            # raises AttributeError. See pipecat/pipeline/llm_switcher.py.
+            llm_service = llm_service.active_llm
 
         valid_ids: List[str] = [RESPEAK_BRANCH_ID]
         for r_id, brs in branches_by_source.items():
@@ -1450,6 +1465,16 @@ In all of these cases, you can provide a `name` in your new node's config for de
             )
             return (natural_next or speak_id, [], False)
 
+        # Allow-list extracted keys to the declared extract-spec names before
+        # merging into shared `state`. The strict JSON schema constrains keys,
+        # but every adapter falls back to schema-less json_object mode on
+        # providers that reject strict schemas — on that path the model's keys
+        # are unbounded. `state` is the same flat dict that holds live runtime
+        # objects/secrets (task, tts_service_map, integration_credentials, ...
+        # merged from flow_dependencies), so an unfiltered merge lets a
+        # hallucinated reserved key clobber them.
+        allowed_keys = {k for m in extract_by_source.values() for k in (m or {})}
+        extracted = {k: v for k, v in extracted.items() if k in allowed_keys}
         if extracted:
             self.state.update(extracted)
             # Mirror the normal-router behavior: surface what the classifier
@@ -1683,7 +1708,11 @@ In all of these cases, you can provide a `name` in your new node's config for de
         # override; otherwise the main LLM.
         llm_service = self._llm
         if isinstance(llm_service, LLMSwitcher):
-            llm_service = llm_service.active_service
+            # LLMSwitcher exposes the live service via the `active_llm`
+            # property (it proxies `self.strategy.active_service`). The
+            # switcher itself has no `active_service` attribute — reading it
+            # raises AttributeError. See pipecat/pipeline/llm_switcher.py.
+            llm_service = llm_service.active_llm
 
         raw = await self._adapter.run_router_completion(
             llm_service=llm_service,
@@ -1737,6 +1766,13 @@ In all of these cases, you can provide a `name` in your new node's config for de
         # source for extraction, and applying it would let stray values
         # overwrite legitimate prior extractions. The re-prompt loop will
         # capture the right reply on the next turn.
+        # Allow-list to the declared `router_extract` names before merging —
+        # the schema-less adapter fallback (see `parse_router_response`) can
+        # emit arbitrary keys, and `state` holds live runtime objects/secrets
+        # (task, tts_service_map, integration_credentials, ...) that a stray
+        # reserved key would otherwise overwrite.
+        allowed_keys = set((node_config.get("router_extract") or {}).keys())
+        extracted = {k: v for k, v in extracted.items() if k in allowed_keys}
         if extracted and branch_id != UNCLEAR_BRANCH_ID:
             self.state.update(extracted)
             logger.debug(
@@ -2014,6 +2050,20 @@ In all of these cases, you can provide a `name` in your new node's config for de
                     config_key = f"{provider}_{model}"
                     target_service = llm_service_map.get(config_key)
                     if target_service:
+                        # Snapshot the baseline (un-overridden) LLM the first
+                        # time we override, so we can switch back when a later
+                        # node has no llm_override. The baseline is whatever was
+                        # active before any override fired.
+                        if previous_llm is None and "llm_baseline" not in self._previous_overrides:
+                            baseline = None
+                            active = self._llm
+                            if isinstance(active, LLMSwitcher):
+                                active = active.active_llm
+                            for key, svc in llm_service_map.items():
+                                if svc is active:
+                                    baseline = key
+                                    break
+                            self._previous_overrides["llm_baseline"] = baseline
                         await task.queue_frames(
                             [ManuallySwitchServiceFrame(service=target_service)]
                         )
@@ -2028,6 +2078,30 @@ In all of these cases, you can provide a `name` in your new node's config for de
                     logger.warning(
                         f"Incomplete LLM override config for node {node_id}: {current_llm}"
                     )
+            elif not current_llm and previous_llm and task and llm_service_map:
+                # Exiting an llm_override node into one without an override:
+                # restore the snapshotted baseline LLM. Without this the cheap
+                # router model stays pinned for every subsequent generative
+                # node (contract: "the previous LLM is restored on exit").
+                baseline_key = self._previous_overrides.get("llm_baseline")
+                baseline_service = (
+                    llm_service_map.get(baseline_key) if baseline_key else None
+                )
+                if baseline_service:
+                    await task.queue_frames(
+                        [ManuallySwitchServiceFrame(service=baseline_service)]
+                    )
+                    logger.debug(
+                        f"Restored baseline LLM '{baseline_key}' on exit from "
+                        f"override node (now at {node_id})"
+                    )
+                else:
+                    logger.warning(
+                        f"Could not restore baseline LLM on exit from override "
+                        f"node {node_id}: baseline key '{baseline_key}' not in "
+                        f"llm_service_map"
+                    )
+                self._previous_overrides.pop("llm_baseline", None)
             self._previous_overrides["llm"] = current_llm
 
         # Future: Handle other overrides (VAD, STT) here
@@ -2075,22 +2149,69 @@ In all of these cases, you can provide a `name` in your new node's config for de
         previous_node_id = self._current_node
         router_pick = self._last_router_pick
         self._last_router_pick = None
+        # In v2 deterministic lowering, ``FlowConfig.nodes`` is keyed by
+        # ``node.name`` (see calling/flow_builder_v2.py:214), and
+        # ``self._current_node`` stores that same dict key — so
+        # ``previous_node_id`` IS the previous node's name. No lookup
+        # against ``self._nodes`` needed. Backend's
+        # ``tools/helper.py:build_tool_call_log_response`` matches these
+        # against ``AgentVersionNode.name → label`` to populate
+        # source_node_label / target_node_label for the FE pill.
         transition_tool_name = f"transition_to_{node_id}"
-        transition_args: Dict[str, Any] = {
-            "from_node_id": previous_node_id,
-            "to_node_id": node_id,
-        }
-        if router_pick:
-            transition_args.update(router_pick)
-        transition_call_id = await start_tracking(
-            transcript_handler=getattr(self, "_transcript_handler", None),
-            tool_name=transition_tool_name,
-            args=transition_args,
-            tool_phase="on_call",
-            tool_type="transition",
-            current_node=previous_node_id,
-            logger=logger,
-        )
+        transition_call_id: Optional[str] = None
+        # Skip the initial node entry — it's not a transition (no prior
+        # node) and the FE pill would render as "Unknown → X" with no
+        # useful information. Also skip in static-flow init paths where
+        # the engine briefly _set_nodes the same node twice during setup.
+        # Log atomically (start + complete back-to-back at the TOP of
+        # _set_node) so each entry always has executed_at set. Earlier
+        # design held the start_tracking call open until the bottom of
+        # _set_node, but in deep auto_transition chains (Speak→Router→
+        # Speak→End) the outer _set_node calls often never reach their
+        # complete_tracking because End's hangup tears down the call
+        # mid-chain — leaving stub entries with null status/latency/
+        # executed_at. Atomic logging makes every transition self-
+        # contained: zero risk of half-baked entries shipping to history.
+        if previous_node_id is not None and previous_node_id != node_id:
+            transition_args: Dict[str, Any] = {
+                "from_node_id": previous_node_id,
+                "to_node_id": node_id,
+                # FE pill key aliases consumed by CallTranscriptViewer.
+                "source_node": previous_node_id,
+                "target_node": node_id,
+            }
+            if router_pick:
+                transition_args.update(router_pick)
+            logger.info(
+                f"[node_transition] from={previous_node_id} to={node_id} "
+                f"router_pick={router_pick}"
+            )
+            transition_call_id = await start_tracking(
+                transcript_handler=getattr(self, "_transcript_handler", None),
+                tool_name=transition_tool_name,
+                args=transition_args,
+                tool_phase="on_call",
+                # `node_transition` matches the FE's filter in
+                # components/call-details/CallTranscriptViewer.tsx so this
+                # renders as a NodeTransitionDivider pill rather than a
+                # generic tool pill.
+                tool_type="node_transition",
+                current_node=previous_node_id,
+                logger=logger,
+            )
+            # Atomic completion right after start — see comment above.
+            await complete_tracking(
+                transcript_handler=getattr(self, "_transcript_handler", None),
+                function_call_id=transition_call_id,
+                tool_name=transition_tool_name,
+                function_start_time=transition_start_time,
+                response_data={
+                    "to_node_id": node_id,
+                    "from_node_id": previous_node_id,
+                },
+                status_code=200,
+                logger=logger,
+            )
 
         try:
             # Clear any pending transition state when starting a new node
@@ -2154,6 +2275,12 @@ In all of these cases, you can provide a `name` in your new node's config for de
             # Reset leaked action counts from interrupted actions in previous node
             self._action_manager.reset_ongoing_actions()
 
+            # Reset the per-node action result so a success/failure
+            # `auto_transition` dict can't route on the PREVIOUS node's result
+            # if this node runs no function action this turn. A function
+            # pre-action below overwrites this before the resolver reads it.
+            self._last_action_result = None
+
             # Clear any deferred post-actions from previous node
             self._action_manager.clear_deferred_post_actions()
 
@@ -2391,12 +2518,29 @@ In all of these cases, you can provide a `name` in your new node's config for de
                     router_target = node_config.get("router_exhausted_next")
                 if router_target:
                     await self._short_circuit_to(router_target)
-                else:
-                    logger.error(
-                        f"Router-mode node {node_id} returned no target and no "
-                        f"router_exhausted_next configured; staying on current node"
-                    )
-                return
+                    return
+                # No branch target AND no router_exhausted_next resolved
+                # (reachable from a single misconfigured node: a branch with an
+                # unset `next`, the unclear cap hit with no router_exhausted_next,
+                # or under-cap with neither reprompt nor router_unclear_next).
+                # Silently returning would strand the call: `suppress_llm_text`
+                # is latched on this node so RouterModeGuard gates the generative
+                # LLM, and the StopUserIdleProcessorFrame queued at entry is
+                # never matched by a StartUserIdleProcessorFrame below — idle
+                # recovery is disabled too → permanent dead-air with no escape.
+                # Fail loudly instead: clear the suppression latch, re-enable
+                # idle recovery so teardown isn't wedged, then raise.
+                logger.error(
+                    f"Router-mode node {node_id} returned no target and no "
+                    f"router_exhausted_next configured; failing the transition "
+                    f"to avoid permanent dead-air"
+                )
+                self._current_node = None  # release is_suppressing_llm_text() latch
+                await self._task.queue_frame(StartUserIdleProcessorFrame())
+                raise FlowError(
+                    f"Router-mode node {node_id} has no resolvable target and no "
+                    f"router_exhausted_next; this is a flow misconfiguration"
+                )
 
             # Register functions and prepare tools
             tools: List[FlowsFunctionSchema | FlowsDirectFunctionWrapper] = []
@@ -2508,19 +2652,10 @@ In all of these cases, you can provide a `name` in your new node's config for de
 
             # node_entered observer is now emitted at the *top* of _set_node
             # so short-circuit paths (auto_transition / router-mode) get it too.
-
-            await complete_tracking(
-                transcript_handler=getattr(self, "_transcript_handler", None),
-                function_call_id=transition_call_id,
-                tool_name=transition_tool_name,
-                function_start_time=transition_start_time,
-                response_data={
-                    "to_node_id": node_id,
-                    "to_node_label": node_config.get("label"),
-                },
-                status_code=200,
-                logger=logger,
-            )
+            # Transition tool-log is also emitted atomically at the top of
+            # _set_node (right after `previous_node_id` capture) — no
+            # complete_tracking needed here, deferred completion was
+            # unreliable for outer nodes when the call ended mid-chain.
 
         except Exception as e:
             # If setup crashed inside an uninterruptible node, the guard is
@@ -2532,19 +2667,6 @@ In all of these cases, you can provide a `name` in your new node's config for de
             except Exception:
                 pass
             logger.error(f"Error setting node {node_id}: {str(e)}")
-            try:
-                await complete_tracking(
-                    transcript_handler=getattr(self, "_transcript_handler", None),
-                    function_call_id=transition_call_id,
-                    tool_name=transition_tool_name,
-                    function_start_time=transition_start_time,
-                    response_data=None,
-                    status_code=500,
-                    error_details={"error": str(e), "type": type(e).__name__},
-                    logger=logger,
-                )
-            except Exception as track_exc:
-                logger.warning(f"complete_tracking failed for {transition_tool_name}: {track_exc!r}")
             raise FlowError(f"Failed to set node {node_id}: {str(e)}") from e
 
     def _schedule_deferred_post_actions(self, post_actions: List[ActionConfig]) -> None: