dv-pipecat-flows 0.0.22.dev2000__tar.gz → 0.0.22.dev2200__tar.gz

{dv_pipecat_flows-0.0.22.dev2000/src/dv_pipecat_flows.egg-info → dv_pipecat_flows-0.0.22.dev2200}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.22.dev2000
+Version: 0.0.22.dev2200
 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.dev2000 → dv_pipecat_flows-0.0.22.dev2200}/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.dev2000 → dv_pipecat_flows-0.0.22.dev2200/src/dv_pipecat_flows.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.22.dev2000
+Version: 0.0.22.dev2200
 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.dev2000 → dv_pipecat_flows-0.0.22.dev2200}/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.dev2000 → dv_pipecat_flows-0.0.22.dev2200}/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.dev2000 → dv_pipecat_flows-0.0.22.dev2200}/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]:
@@ -609,6 +622,7 @@ class FlowManager:
         handler: Optional[Callable | FlowsDirectFunctionWrapper],
         transition_to: Optional[str],
         transition_callback: Optional[Callable] = None,
+        state_update_keys: Optional[List[str]] = None,
     ) -> Callable:
         """Create a transition function for the given name and handler.
 
@@ -617,6 +631,14 @@ class FlowManager:
             handler: Optional function to process data.
             transition_to: Optional node to transition to (static flows).
             transition_callback: Optional callback for dynamic transitions.
+            state_update_keys: Optional list of argument names — when the
+                LLM calls this function, the named keys from
+                ``params.arguments`` are copied into ``flow_manager.state``
+                before the transition resolves. Used by backend wiring to
+                flatten ``agent_node → llm_router`` transitions and still
+                propagate the router's ``router_extract`` variables (e.g.
+                ``language``) into state, preserving parity with
+                ``_run_router_node``'s ``state.update(extracted)``.
 
         Returns:
             Async function that handles the tool invocation.
@@ -639,6 +661,26 @@ class FlowManager:
             function_start_time = time.time()
             try:
                 logger.debug(f"Function called: {name}")
+                # Flattened-router extract: copy LLM-supplied args into
+                # ``flow_manager.state`` BEFORE the transition resolves, so
+                # downstream nodes (e.g. Speak picking variant by
+                # ``state["language"]``) see the new values on their first
+                # ``_set_node`` after the transition. Mirrors the
+                # ``state.update(extracted)`` that ``_run_router_node`` does
+                # on the non-flattened path.
+                if state_update_keys and params.arguments:
+                    extract_update = {
+                        key: params.arguments[key]
+                        for key in state_update_keys
+                        if key in params.arguments
+                    }
+                    if extract_update:
+                        self.state.update(extract_update)
+                        logger.debug(
+                            f"[FLATTENED_ROUTER_EXTRACT] state.update keys="
+                            f"{list(extract_update.keys())} function={name}"
+                        )
+
                 function_call_id = await start_tracking(
                     transcript_handler=self._transcript_handler,
                     tool_name=name,
@@ -682,10 +724,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)
@@ -892,6 +930,7 @@ class FlowManager:
         handler: Optional[Callable | FlowsDirectFunctionWrapper],
         transition_to: Optional[str] = None,
         transition_callback: Optional[Callable] = None,
+        state_update_keys: Optional[List[str]] = None,
     ) -> None:
         """Register a function with the LLM if not already registered.
 
@@ -915,7 +954,11 @@ class FlowManager:
 
                 # Create transition function
                 transition_func = await self._create_transition_func(
-                    name, handler, transition_to, transition_callback
+                    name,
+                    handler,
+                    transition_to,
+                    transition_callback,
+                    state_update_keys=state_update_keys,
                 )
 
                 # Register function with LLM (or LLMSwitcher).
@@ -1039,10 +1082,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 +1448,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 +1499,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 +1742,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 +1800,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 +2084,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 +2112,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
@@ -2201,6 +2309,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()
 
@@ -2242,8 +2356,26 @@ In all of these cases, you can provide a `name` in your new node's config for de
                     isinstance(a, dict) and a.get("type") == "tts_say"
                     for a in pre_actions
                 ):
+                    # ``Event.wait()`` that's never set hangs forever — a bare
+                    # ``await`` here was a transition-deadlock vector when the
+                    # ``BotStoppedSpeakingFrame`` never reaches ActionManager
+                    # (cancelled pipeline, dropped frame, abruptly closed
+                    # transport). Mirror ``actions.py:_maybe_wait_for_ongoing_
+                    # actions_to_finish``'s 60s ``wait_for`` backstop so the
+                    # node still transitions instead of permanently parking.
+                    from pipecat_flows.actions import ONGOING_ACTIONS_WAIT_TIMEOUT_S
                     try:
-                        await self._action_manager._ongoing_actions_finished_event.wait()
+                        await asyncio.wait_for(
+                            self._action_manager._ongoing_actions_finished_event.wait(),
+                            timeout=ONGOING_ACTIONS_WAIT_TIMEOUT_S,
+                        )
+                    except asyncio.TimeoutError:
+                        logger.warning(
+                            f"audio-wait on '{node_id}' timed out after "
+                            f"{ONGOING_ACTIONS_WAIT_TIMEOUT_S}s — "
+                            f"BotStoppedSpeakingFrame never arrived; continuing "
+                            f"with short-circuit to avoid a permanent hang"
+                        )
                     except Exception as wait_exc:
                         logger.warning(
                             f"audio-wait on '{node_id}' failed ({wait_exc!r}); "
@@ -2438,12 +2570,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] = []
@@ -2461,6 +2610,7 @@ In all of these cases, you can provide a `name` in your new node's config for de
                     handler=schema.handler,
                     transition_to=schema.transition_to,
                     transition_callback=schema.transition_callback,
+                    state_update_keys=schema.state_update_keys,
                 )
 
             async def register_direct_function(func):

{dv_pipecat_flows-0.0.22.dev2000 → dv_pipecat_flows-0.0.22.dev2200}/src/pipecat_flows/types.py

@@ -273,6 +273,12 @@ class FlowsFunctionSchema:
     handler: Optional[FunctionHandler] = None
     transition_to: Optional[str] = None
     transition_callback: Optional[Callable] = None
+    # When the LLM calls this function, copy these keys from
+    # ``params.arguments`` into ``flow_manager.state`` BEFORE the transition
+    # resolves. Used by backend wiring to flatten ``agent_node → llm_router``
+    # transitions and still propagate the router's ``router_extract``
+    # variables (e.g. ``language``) into state. Empty/None = no-op.
+    state_update_keys: Optional[List[str]] = None
 
     def __post_init__(self):
         """Validate the schema configuration.