dv-pipecat-flows 0.0.23.dev4__tar.gz → 0.0.23.dev6__tar.gz

{dv_pipecat_flows-0.0.23.dev4/src/dv_pipecat_flows.egg-info → dv_pipecat_flows-0.0.23.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.23.dev4
+Version: 0.0.23.dev6
 Summary: Conversation Flow management for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Source, https://github.com/pipecat-ai/pipecat-flows
@@ -309,3 +309,4 @@ 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.23.dev4 → dv_pipecat_flows-0.0.23.dev6}/README.md

@@ -284,3 +284,4 @@ 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.23.dev4 → dv_pipecat_flows-0.0.23.dev6/src/dv_pipecat_flows.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-flows
-Version: 0.0.23.dev4
+Version: 0.0.23.dev6
 Summary: Conversation Flow management for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Source, https://github.com/pipecat-ai/pipecat-flows
@@ -309,3 +309,4 @@ 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.23.dev4 → dv_pipecat_flows-0.0.23.dev6}/src/pipecat_flows/actions.py

@@ -73,7 +73,7 @@ _EXTRACT_VAR_RE = re.compile(
 )
 
 
-def _substitute_extract_vars(text: str, state: dict) -> str:
+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
@@ -483,7 +483,7 @@ class ActionManager:
         # 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)
+        text = substitute_extract_vars(text, state)
 
         await self._maybe_switch_tts_service_for_action(action)
 

{dv_pipecat_flows-0.0.23.dev4 → dv_pipecat_flows-0.0.23.dev6}/src/pipecat_flows/manager.py

@@ -71,7 +71,7 @@ from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
 from pipecat.services.llm_service import FunctionCallParams
 from pipecat.transports.base_transport import BaseTransport
 
-from pipecat_flows.actions import ActionError, ActionManager
+from pipecat_flows.actions import ActionError, ActionManager, substitute_extract_vars
 from pipecat_flows.adapters import create_adapter
 from pipecat_flows.condition_evaluator import evaluate_conditions
 from pipecat_flows.exceptions import (
@@ -120,34 +120,139 @@ else:
     LLMService = Any
 
 
-def extract_conversation_messages(messages: List[dict]) -> List[dict]:
-    """Keep only the conversational turns from a context's messages.
+def _paired_transition_call_ids(
+    messages: List[dict], transition_names: Set[str]
+) -> Set[str]:
+    """IDs of transition tool calls that have BOTH a call and a matching result.
 
-    Returns user/assistant messages carrying real spoken text and drops
-    everything else: system prompts, tool results (``role`` = ``tool``/
-    ``function``), and assistant messages that are only tool calls. Handles both
-    string content and provider content-part lists (e.g. Anthropic), keeping
-    only ``text`` parts and dropping ``tool_use``/``tool_result`` blocks. Used by
-    the RESET_WITH_CONVERSATION strategy to carry a clean transcript across a
-    node transition without the previous node's system prompt or tool logs.
+    Pairing is the whole point. Every provider rejects a dangling half: an
+    assistant ``tool_use``/``tool_calls`` entry with no result, or a result whose
+    call was filtered away, is a hard 400. Rather than emit and then repair, we
+    resolve the pairs up front and only keep ids that are complete on both sides
+    — so a transition still in flight when the context is rebuilt is simply left
+    out instead of corrupting the whole request.
     """
+    call_ids: Set[str] = set()
+    for message in messages:
+        if not isinstance(message, dict) or message.get("role") != "assistant":
+            continue
+        # OpenAI shape: {"tool_calls": [{"id", "function": {"name"}}]}
+        for tool_call in message.get("tool_calls") or []:
+            if not isinstance(tool_call, dict):
+                continue
+            name = (tool_call.get("function") or {}).get("name")
+            if name in transition_names and tool_call.get("id"):
+                call_ids.add(tool_call["id"])
+        # Anthropic shape: content parts of type "tool_use"
+        content = message.get("content")
+        if isinstance(content, list):
+            for part in content:
+                if (
+                    isinstance(part, dict)
+                    and part.get("type") == "tool_use"
+                    and part.get("name") in transition_names
+                    and part.get("id")
+                ):
+                    call_ids.add(part["id"])
+
+    result_ids: Set[str] = set()
+    for message in messages:
+        if not isinstance(message, dict):
+            continue
+        # OpenAI shape: a dedicated {"role": "tool", "tool_call_id": ...} message
+        if message.get("role") == "tool" and message.get("tool_call_id") in call_ids:
+            result_ids.add(message["tool_call_id"])
+        # Anthropic shape: "tool_result" parts ride inside a *user* message
+        content = message.get("content")
+        if isinstance(content, list):
+            for part in content:
+                if (
+                    isinstance(part, dict)
+                    and part.get("type") == "tool_result"
+                    and part.get("tool_use_id") in call_ids
+                ):
+                    result_ids.add(part["tool_use_id"])
+
+    return call_ids & result_ids
+
+
+def extract_conversation_messages(
+    messages: List[dict], transition_names: Optional[Set[str]] = None
+) -> List[dict]:
+    """Keep the conversational turns, plus the transition tool calls.
+
+    Returns user/assistant messages carrying real spoken text, and — when
+    ``transition_names`` is supplied — the ``tool_use``/``tool_result`` pairs for
+    the flow's transition functions. Everything else is dropped: system prompts,
+    and the tool traffic of KB lookups / API tools / widgets (a single ``query_kb``
+    result runs ~8 KB, and the node's own system prompt is the real cost anyway).
+
+    Keeping the transition call is not cosmetic. Without it the carried transcript
+    ends on the user turn that triggered the hop, which is indistinguishable from a
+    fresh message nobody has handled — so the target node re-routes on it and the
+    source node sends it straight back. That is the A->B->A ping-pong. The
+    preserved call tells the target it was routed here, by whom, and (via the
+    required ``transition_reason`` arg) why.
+
+    Handles both string content and provider content-part lists (Anthropic).
+    Used by the RESET_WITH_CONVERSATION strategy.
+    """
+    transition_names = transition_names or set()
+    keep_ids = _paired_transition_call_ids(messages, transition_names)
+
     kept: List[dict] = []
     for message in messages:
-        if not isinstance(message, dict) or message.get("role") not in ("user", "assistant"):
+        if not isinstance(message, dict):
+            continue
+        role = message.get("role")
+        if role not in ("user", "assistant", "tool"):
             continue
         content = message.get("content")
+
+        # OpenAI tool result — keep only if its call survived.
+        if role == "tool":
+            if message.get("tool_call_id") in keep_ids:
+                kept.append(message)
+            continue
+
+        # Provider content-part list (Anthropic): text + surviving tool blocks.
         if isinstance(content, list):
-            text_parts = [
+            parts = [
                 part
                 for part in content
-                if isinstance(part, dict) and part.get("type") == "text" and part.get("text")
+                if isinstance(part, dict)
+                and (
+                    (part.get("type") == "text" and part.get("text"))
+                    or (part.get("type") == "tool_use" and part.get("id") in keep_ids)
+                    or (
+                        part.get("type") == "tool_result"
+                        and part.get("tool_use_id") in keep_ids
+                    )
+                )
             ]
-            if not text_parts:
-                continue  # e.g. a tool_use / tool_result-only turn
-            kept.append({"role": message["role"], "content": text_parts})
+            if parts:
+                kept.append({"role": role, "content": parts})
+            continue
+
+        # OpenAI assistant turn carrying tool_calls.
+        tool_calls = [
+            tool_call
+            for tool_call in (message.get("tool_calls") or [])
+            if isinstance(tool_call, dict) and tool_call.get("id") in keep_ids
+        ]
+        if tool_calls:
+            # An assistant turn may mix a KB call with a transition call; only the
+            # surviving calls come across, and their results were matched above.
+            kept.append(
+                {
+                    "role": role,
+                    "content": content if isinstance(content, str) and content.strip() else None,
+                    "tool_calls": tool_calls,
+                }
+            )
         elif isinstance(content, str) and content.strip():
-            kept.append({"role": message["role"], "content": content})
-        # else: empty content (e.g. an assistant turn that was only tool_calls) -> drop
+            kept.append({"role": role, "content": content})
+        # else: empty content and no surviving tool calls -> drop
     return kept
 
 
@@ -219,6 +324,16 @@ class FlowManager:
         # rationale + prompt_sha1 land in the transition tool-log args. Cleared
         # by _set_node after read so it can't leak into an unrelated next hop.
         self._last_router_pick: Optional[Dict[str, Any]] = None
+        # The LLM's own one-line rationale for the hop it just requested, taken
+        # from the `transition_reason` arg every transition function declares.
+        # Same lifecycle as _last_router_pick: stashed by the transition func,
+        # consumed + cleared by _set_node so it can't leak into the next hop.
+        self._last_transition_reason: Optional[str] = None
+        # Every transition function registered so far this call (populated by
+        # _register_function). RESET_WITH_CONVERSATION keeps these tool calls in
+        # the carried context and drops all other tool traffic — see
+        # extract_conversation_messages.
+        self._transition_function_names: Set[str] = set()
         self._context_aggregator = context_aggregator
         self._pending_transition: Optional[Dict[str, Any]] = None
         # Result ("success"/"failure") of the most recent function action, set
@@ -698,6 +813,14 @@ class FlowManager:
             function_start_time = time.time()
             try:
                 logger.debug(f"Function called: {name}")
+                # Every transition function declares a required `transition_reason`
+                # (see call_helper._with_transition_reason). Stash it for _set_node,
+                # which tool-logs it and turns it into the handoff breadcrumb.
+                # Not written into state — it is per-hop rationale, not a variable.
+                reason = (params.arguments or {}).get("transition_reason")
+                if isinstance(reason, str) and reason.strip():
+                    self._last_transition_reason = reason.strip()
+
                 # Flattened-router extract: copy LLM-supplied args into
                 # ``flow_manager.state`` BEFORE the transition resolves, so
                 # downstream nodes (e.g. Speak picking variant by
@@ -1041,6 +1164,13 @@ class FlowManager:
         Raises:
             FlowError: If function registration fails
         """
+        # A function that moves the flow is a transition function; everything else
+        # (KB lookups, API tools, widgets) is not. Recorded cumulatively for the
+        # whole call so RESET_WITH_CONVERSATION can tell the two apart in a context
+        # it is filtering long after the source node's tools were swapped out.
+        if transition_to or transition_callback:
+            self._transition_function_names.add(name)
+
         if name not in self._current_functions:
             try:
                 # Handle special token format (e.g. "__function__:function_name")
@@ -3414,6 +3544,8 @@ 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
+        transition_reason = self._last_transition_reason
+        self._last_transition_reason = 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
@@ -3459,9 +3591,11 @@ In all of these cases, you can provide a `name` in your new node's config for de
             }
             if router_pick:
                 transition_args.update(router_pick)
+            if transition_reason:
+                transition_args["transition_reason"] = transition_reason
             logger.info(
                 f"[node_transition] from={previous_node_id} to={node_id} "
-                f"router_pick={router_pick}"
+                f"router_pick={router_pick} reason={transition_reason!r}"
             )
             transition_call_id = await start_tracking(
                 transcript_handler=transition_transcript_handler,
@@ -4077,6 +4211,31 @@ In all of these cases, you can provide a `name` in your new node's config for de
         """Generate a conversation summary from a given context."""
         return await self._adapter.generate_summary(self._llm, summary_prompt, context)
 
+    def _resolve_extract_tokens(
+        self, messages: Optional[List[dict]]
+    ) -> Optional[List[dict]]:
+        """Substitute ``[{name}]`` extract tokens in message content from
+        ``self.state``.
+
+        Router/agent nodes write their extracted values into ``self.state`` at
+        runtime; the backend lowerer only resolves compile-time vars
+        (custom_args, api_responses), so a downstream node's role/task prompt
+        that references an extracted value would otherwise reach the LLM as a
+        literal ``[{name}]`` marker. Mirrors the Speak/tts_say pass in
+        ``actions.substitute_extract_vars``. Returns shallow copies so the
+        source NodeConfig messages stay in token form for the next entry;
+        unknown keys are left literal.
+        """
+        if not messages:
+            return messages
+        resolved: List[dict] = []
+        for message in messages:
+            content = message.get("content") if isinstance(message, dict) else None
+            if isinstance(content, str) and "[{" in content:
+                message = {**message, "content": substitute_extract_vars(content, self.state)}
+            resolved.append(message)
+        return resolved
+
     async def _update_llm_context(
         self,
         role_messages: Optional[List[dict]],
@@ -4102,6 +4261,11 @@ In all of these cases, you can provide a `name` in your new node's config for de
         try:
             messages = []
 
+            # Resolve runtime ``[{name}]`` extract tokens against self.state
+            # before the prompts enter context (see _resolve_extract_tokens).
+            role_messages = self._resolve_extract_tokens(role_messages)
+            task_messages = self._resolve_extract_tokens(task_messages)
+
             # Add role messages if provided.
             # Note that these come before any possible summary message; some
             # LLMs only support a single system instruction, and the first role
@@ -4151,7 +4315,8 @@ In all of these cases, you can provide a `name` in your new node's config for de
                 # role_messages (the new system instruction) and before task
                 # messages, mirroring the RESET_WITH_SUMMARY layout.
                 carried = extract_conversation_messages(
-                    self._context_aggregator.user()._context.get_messages()
+                    self._context_aggregator.user()._context.get_messages(),
+                    transition_names=self._transition_function_names,
                 )
                 messages.extend(carried)
                 logger.debug(f"Carried {len(carried)} conversation message(s) across transition")