dv-pipecat-flows 0.0.0.dev2098__tar.gz → 0.0.0.dev2245__tar.gz

{dv_pipecat_flows-0.0.0.dev2098/src/dv_pipecat_flows.egg-info → dv_pipecat_flows-0.0.0.dev2245}/PKG-INFO

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

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

@@ -25,14 +25,17 @@ Actions are used to perform side effects during conversations, such as:
 
 import asyncio
 import inspect
+import re
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Callable, Dict, List, Optional
+from typing import TYPE_CHECKING, Callable, Dict, List, Optional, Tuple
 
 from loguru import logger
 from pipecat.frames.frames import (
     BotStoppedSpeakingFrame,
     ControlFrame,
     EndFrame,
+    InterruptionFrame,
+    ManuallySwitchServiceFrame,
     TTSSpeakFrame,
 )
 from pipecat.pipeline.task import PipelineTask
@@ -44,6 +47,58 @@ 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
+
+
+# Router/Agent-extracted variable token: ``[{name}]`` (distinct from custom
+# ``{{name}}`` on the FE — see VariableSelect.tsx). Resolved at TTS time from
+# ``flow_manager.state``, where ``_run_router_node`` (and the flattened
+# agent_node→llm_router path) writes the LLM's extracted args. Backend
+# lowering only substitutes compile-time vars (custom_args, api_responses);
+# anything a router extracts at runtime needs this pass to reach TTS.
+#
+# Pattern matches BOTH the FE's dominant mention form ``@[{var}]`` (the
+# ``@``-prefixed visible text inside a Tiptap mention span) AND the raw
+# ``[{var}]`` form — mirrors how ``replace_custom_variables`` handles both
+# ``@{{var}}`` and ``{{var}}`` for custom_args.
+_EXTRACT_VAR_RE = re.compile(
+    r"@?\[\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\]"
+)
+
+
+def _substitute_extract_vars(text: str, state: dict) -> str:
+    """Replace ``[{var}]`` / ``@[{var}]`` occurrences with ``state[var]``.
+
+    Supports dotted paths (``[{user.name}]``). Unknown variables (key not
+    in state, or any path segment missing) are LEFT LITERAL — the marker
+    survives so downstream debugging can spot the misconfigured extract.
+    """
+    if not text or "[{" not in text or not isinstance(state, dict):
+        return text
+
+    def _resolve(key: str):
+        cur = state
+        for seg in key.split("."):
+            if isinstance(cur, dict) and seg in cur:
+                cur = cur[seg]
+            else:
+                return None
+        return cur
+
+    def _repl(match: "re.Match[str]") -> str:
+        value = _resolve(match.group(1))
+        return str(value) if value is not None else match.group(0)
+
+    return _EXTRACT_VAR_RE.sub(_repl, text)
+
+
 @dataclass
 class FunctionActionFrame(ControlFrame):
     """Frame containing a function action to be executed.
@@ -96,6 +151,14 @@ class ActionManager:
         self._ongoing_actions_count = 0
         self._ongoing_actions_finished_event = asyncio.Event()
         self._deferred_post_actions: List[ActionConfig] = []
+        # Tracks whether an InterruptionFrame has been observed since the
+        # last action increment. The BotStoppedSpeakingFrame "interruption
+        # recovery" branch must only fire when a real interruption actually
+        # happened — otherwise a stale BotStoppedSpeakingFrame from a prior
+        # speech (e.g. cached intro completing while the first Speak node
+        # is already starting) would zero a legitimate in-flight count and
+        # release _ongoing_actions_finished_event prematurely.
+        self._seen_interruption_since_increment = False
 
         # Register built-in actions
         self._register_action("tts_say", self._handle_tts_action)
@@ -104,7 +167,12 @@ class ActionManager:
 
         # Add pipeline observation
         task.set_reached_downstream_filter(
-            (ActionFinishedFrame, FunctionActionFrame, BotStoppedSpeakingFrame)
+            (
+                ActionFinishedFrame,
+                FunctionActionFrame,
+                BotStoppedSpeakingFrame,
+                InterruptionFrame,
+            )
         )
 
         @task.event_handler("on_frame_reached_downstream")
@@ -130,11 +198,55 @@ class ActionManager:
                     )
                 self._decrement_ongoing_actions_count()
             elif isinstance(frame, BotStoppedSpeakingFrame):
-                # Execute deferred post-actions if the bot's turn is over.
-                # A BotStoppedSpeakingFrame only indicates that the bot's turn is over if there are
-                # no ongoing actions (otherwise one of those actions may have been responsible for it).
-                if self._ongoing_actions_count == 0:
+                # Two cases on this frame:
+                #
+                # 1. NATURAL COMPLETION: TTS finished generating, the trailing
+                #    ActionFinishedFrame already reached us and decremented
+                #    `_ongoing_actions_count` to 0. Run deferred post-actions
+                #    now — the original intent of this branch.
+                #
+                # 2. INTERRUPTION RECOVERY: an upstream `InterruptionFrame`
+                #    flushed the output queue, dropping the trailing
+                #    `ActionFinishedFrame` before it could reach us. The count
+                #    stays at >0 and `_ongoing_actions_finished_event` is
+                #    never set → the next `_set_node`'s
+                #    `_maybe_wait_for_ongoing_actions_to_finish` hangs forever.
+                #    Defensively reset on this frame so the engine doesn't
+                #    deadlock; skip the deferred post-actions since the action
+                #    didn't complete naturally.
+                #
+                # Recovery is gated on `_seen_interruption_since_increment`:
+                # count>0 alone is ambiguous — a stale BotStoppedSpeakingFrame
+                # from a prior speech (e.g. cached intro completing after a
+                # new Speak's increment) would otherwise zero a legitimate
+                # in-flight count and unblock the next _set_node early.
+                if (
+                    self._ongoing_actions_count > 0
+                    and self._seen_interruption_since_increment
+                ):
+                    logger.debug(
+                        f"BotStoppedSpeaking with in-flight count="
+                        f"{self._ongoing_actions_count} after InterruptionFrame; "
+                        f"resetting to release _ongoing_actions_finished_event"
+                    )
+                    self._ongoing_actions_count = 0
+                    self._ongoing_actions_finished_event.set()
+                    self._seen_interruption_since_increment = False
+                elif self._ongoing_actions_count > 0:
+                    # Stale frame from prior speech. Ignore — the real
+                    # in-flight action's ActionFinishedFrame is still coming.
+                    logger.debug(
+                        f"BotStoppedSpeaking with in-flight count="
+                        f"{self._ongoing_actions_count} but no InterruptionFrame "
+                        f"observed since last increment; treating as stale, "
+                        f"keeping counter intact"
+                    )
+                else:
                     await self._execute_deferred_post_actions()
+            elif isinstance(frame, InterruptionFrame):
+                # Mark — the very next BotStoppedSpeakingFrame is the truncated
+                # speech's stop and should trigger the recovery branch above.
+                self._seen_interruption_since_increment = True
             elif isinstance(frame, ActionFinishedFrame):
                 # Handle action finished
                 self._decrement_ongoing_actions_count()
@@ -305,32 +417,76 @@ 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.
 
         Args:
             action: Action configuration containing:
-                - text: Text to speak (required, resolved)
-                - text_raw: Raw template with {{var}} markers (optional)
-                - use_cache: Use caching for TTS audio (optional, default: False)
-
-        Caching is opt-in via dependency injection: when use_cache=True and
-        flow_manager.state['say_with_cache_handler'] is set, the handler is
-        invoked as `await handler(text=..., text_raw=...) -> bool`. Returning
+                - text: Text to speak (required when ``text_variants`` is
+                    absent; serves as the forward-compat fallback when present).
+                - text_variants: ``{iso_lang: [variant_strings, ...]}`` —
+                    multi-language Speak shape. The handler picks one variant
+                    based on ``state["language"]`` (with primary fallback) and
+                    cycles through variants via
+                    :attr:`FlowManager._variant_usage` to avoid back-to-back
+                    repeats per call.
+                - fallback_language: The Speak's primary ISO 639-1 code, used
+                    when ``state["language"]`` is missing or has no variants.
+                - voice: Per-Speak voice id override (queues a
+                    :class:`ManuallySwitchServiceFrame` before the TTS frame).
+                - language: Per-Speak language override (locale form, e.g.
+                    ``en-US``). Combined with ``voice`` to build the
+                    ``{provider}_{voice}_{language}`` lookup key against
+                    ``state["tts_service_map"]``.
+                - text_raw: Raw template with ``{{var}}`` markers (optional).
+                - use_cache: Use caching for TTS audio (optional, default: False).
+
+        Caching is opt-in via dependency injection: when ``use_cache=True`` and
+        ``flow_manager.state['say_with_cache_handler']`` is set, the handler is
+        invoked as ``await handler(text=..., text_raw=...) -> bool``. Returning
         True means the handler served the audio downstream (and pushed an
         ActionFinishedFrame downstream itself). Returning False (or raising)
         falls back to live TTS via TTSSpeakFrame.
 
+        SSML detection happens DOWNSTREAM (in the TTS service's
+        ``format_tts_text`` formatter) — this handler passes ``text`` through
+        verbatim and relies on the formatter's regex to early-return when SSML
+        tags are present.
+
         To prevent the LLM from immediately responding after TTS in pre-actions,
-        set respond_immediately=false in the node configuration.
+        set ``respond_immediately=false`` in the node configuration.
         """
-        text = action.get("text")
+        text, text_raw, chosen_lang = self._pick_tts_variant(action)
         if not text:
-            logger.error("TTS action missing 'text' field")
+            logger.error("TTS action missing 'text' / 'text_variants' field")
             return
 
+        # Runtime resolution of [{var}] / @[{var}] tokens against
+        # flow_manager.state. Backend lowering substitutes {{var}} (custom
+        # args) and ((tool.field)) (pre-call outputs) at compile time, but
+        # router/agent-extracted vars only exist at runtime — without this
+        # pass, the bot speaks literals like "@[{user_name}]" verbatim.
+        # text_raw stays unrendered so the split-cache's prefix derivation
+        # remains stable across calls.
+        state = self._flow_manager.state if isinstance(self._flow_manager.state, dict) else {}
+        text = _substitute_extract_vars(text, state)
+
+        await self._maybe_switch_tts_service_for_action(action)
+
         use_cache = action.get("use_cache", False)
         cache_handler = (
             self._flow_manager.state.get("say_with_cache_handler") if use_cache else None
@@ -343,8 +499,17 @@ class ActionManager:
             served_from_cache = False
             if cache_handler is not None:
                 try:
-                    text_raw = action.get("text_raw") or text
-                    served_from_cache = bool(await cache_handler(text=text, text_raw=text_raw))
+                    # Fall back to text when no raw template was emitted —
+                    # cache key derivation will treat the rendered text as
+                    # its own template (lower hit rate but always correct).
+                    effective_raw = text_raw or text
+                    served_from_cache = bool(
+                        await cache_handler(
+                            text=text,
+                            text_raw=effective_raw,
+                            language=chosen_lang,
+                        )
+                    )
                 except Exception as e:
                     logger.error(f"tts_say cache handler raised, falling back to live TTS: {e}")
                     served_from_cache = False
@@ -364,6 +529,150 @@ class ActionManager:
             self._decrement_ongoing_actions_count()
             logger.error(f"TTS error: {e}")
 
+    def _pick_tts_variant(
+        self, action: dict
+    ) -> Tuple[Optional[str], Optional[str], Optional[str]]:
+        """Pick a variation string from ``text_variants``.
+
+        Returns ``(text, text_raw, chosen_lang)``:
+          * ``text`` — the picked variant (rendered string), or ``action["text"]``
+            when no variants are usable.
+          * ``text_raw`` — the matching unrendered template (with ``{{var}}``
+            markers intact) from ``action["text_raw_variants"][chosen_lang][idx]``
+            when present, else ``action["text_raw"]``, else mirrors ``text``.
+            Used by the split-cache to derive the stable prefix cache key.
+          * ``chosen_lang`` — the ISO key that won, or None when the legacy
+            ``text`` fallback was taken. Threaded down to the cache_handler
+            so the cache key can be language-scoped (different scripts must
+            not share a cache slot).
+
+        Resolution order for the language key:
+            1. ``state["language"]`` (set by Router-LLM auto-injected extract).
+            2. ``action["fallback_language"]`` (the Speak's primary ISO).
+            3. First key in ``text_variants``.
+
+        Cycling state lives on :attr:`FlowManager._variant_usage` keyed by
+        ``(speak_node_id, lang)`` — every variant index is picked at most
+        once until the set has been exhausted, at which point it resets.
+        """
+        variants = action.get("text_variants")
+        if not isinstance(variants, dict) or not variants:
+            return action.get("text"), action.get("text_raw"), None
+
+        active = (self._flow_manager.state or {}).get("language") if isinstance(
+            self._flow_manager.state, dict
+        ) else None
+        fallback = action.get("fallback_language")
+        candidates: List[Optional[str]] = []
+        if isinstance(active, str) and active.strip():
+            candidates.append(active.strip().lower())
+        if isinstance(fallback, str) and fallback.strip():
+            candidates.append(fallback.strip().lower())
+        # Last resort: any language present.
+        candidates.append(next(iter(variants.keys()), None))
+
+        chosen_lang: Optional[str] = None
+        chosen_list: List[str] = []
+        for cand in candidates:
+            if not cand:
+                continue
+            lst = variants.get(cand)
+            if isinstance(lst, list) and lst:
+                chosen_lang = cand
+                chosen_list = [s for s in lst if isinstance(s, str) and s.strip()]
+                if chosen_list:
+                    break
+
+        if not chosen_list:
+            # Variants dict is malformed (all keys empty); fall back to the
+            # forward-compat `text` field if the lowerer emitted one.
+            return action.get("text"), action.get("text_raw"), None
+
+        # Look up the parallel raw-template list emitted by the backend for
+        # this language. Same length as `chosen_list` at lowering time; if
+        # absent or short, the caller falls back to chosen_list itself
+        # (cache derivation will treat the rendered text as its own
+        # template — cache MAY miss but won't garble).
+        raw_variants = action.get("text_raw_variants")
+        raw_list: List[str] = []
+        if isinstance(raw_variants, dict):
+            cand_raw = raw_variants.get(chosen_lang or "")
+            if isinstance(cand_raw, list):
+                raw_list = [s for s in cand_raw if isinstance(s, str)]
+
+        speak_id = (
+            getattr(self._flow_manager, "_current_node", None)
+            or action.get("speak_id")
+            or "__unknown_speak__"
+        )
+        usage_key = (speak_id, chosen_lang or "")
+        usage = self._flow_manager._variant_usage
+        used = usage.get(usage_key, set())
+        # Pick the smallest index not yet used; reset the set when full.
+        picked_idx = 0
+        for idx in range(len(chosen_list)):
+            if idx not in used:
+                used = set(used) | {idx}
+                if len(used) >= len(chosen_list):
+                    usage[usage_key] = set()  # cycle complete; reset for next round
+                else:
+                    usage[usage_key] = used
+                picked_idx = idx
+                break
+        else:
+            # Degenerate: usage was already saturated (race) — reset and pick 0.
+            usage[usage_key] = {0}
+            picked_idx = 0
+
+        picked_text = chosen_list[picked_idx]
+        picked_raw = (
+            raw_list[picked_idx]
+            if 0 <= picked_idx < len(raw_list)
+            else picked_text
+        )
+        return picked_text, picked_raw, chosen_lang
+
+    async def _maybe_switch_tts_service_for_action(self, action: dict) -> None:
+        """Queue a :class:`ManuallySwitchServiceFrame` when the action carries
+        an explicit ``voice`` and ``language`` override that maps to a known
+        service in ``state["tts_service_map"]``.
+
+        Silently no-ops when the action has no override, or when no matching
+        service is registered (bot author misconfiguration — logged at warning
+        level, audio plays through the active service unchanged).
+        """
+        voice = action.get("voice")
+        language = action.get("language")
+        if not voice or not language:
+            return
+        state = self._flow_manager.state or {}
+        tts_service_map = state.get("tts_service_map") or {}
+        task = state.get("task")
+        if not tts_service_map or not task:
+            return
+        # The map keys are `{provider}_{voice_id}_{locale}`; we don't know the
+        # provider from the action alone, so try every provider prefix until
+        # one matches. Cheap (typically 1–3 prefixes per agent).
+        candidate_keys = [
+            key for key in tts_service_map.keys()
+            if isinstance(key, str) and key.endswith(f"_{voice}_{language}")
+        ]
+        if not candidate_keys:
+            logger.warning(
+                f"tts_say per-action voice/language override ({voice}/{language}) "
+                f"has no matching service in tts_service_map; using active service"
+            )
+            return
+        target_service = tts_service_map.get(candidate_keys[0])
+        if target_service is None:
+            return
+        await task.queue_frames(
+            [ManuallySwitchServiceFrame(service=target_service)]
+        )
+        logger.debug(
+            f"tts_say per-action TTS switch: {candidate_keys[0]}"
+        )
+
     async def _handle_end_action(self, action: dict) -> None:
         """Built-in handler for ending the conversation.
 
@@ -416,6 +725,9 @@ class ActionManager:
         self._ongoing_actions_count += 1
         if self._ongoing_actions_count == 1:
             self._ongoing_actions_finished_event.clear()
+        # Reset the interruption flag — any prior InterruptionFrame applied to
+        # the previous speech, not this new one.
+        self._seen_interruption_since_increment = False
 
     def _decrement_ongoing_actions_count(self) -> None:
         """Decrement the count of ongoing actions and set the finished event if this was the last action."""
@@ -435,3 +747,4 @@ class ActionManager:
             )
         self._ongoing_actions_count = 0
         self._ongoing_actions_finished_event.set()
+        self._seen_interruption_since_increment = False