soprano-sdk 0.2.18__py3-none-any.whl → 0.2.20__py3-none-any.whl

soprano_sdk/agents/adaptor.py

@@ -59,7 +59,9 @@ class CrewAIAgentAdapter(AgentAdapter):
             return response
 
         # Convert to string for parsing
-        response_str = str(response)
+        response_str_raw = str(response)
+
+        response_str = response_str_raw[response_str_raw.find("{"): response_str_raw.rfind("}")+1]
 
         # Strategy 2: Try json.loads()
         try:
@@ -78,8 +80,8 @@ class CrewAIAgentAdapter(AgentAdapter):
         except (ValueError, SyntaxError, TypeError) as e:
             logger.error(f"ast.literal_eval() failed: {e}")
 
-        # No schema and all parsing failed - return as string
-        logger.error("No schema provided and parsing failed, returning raw response")
+        # All parsing failed - return as string
+        logger.error("All parsing strategies failed, returning raw response")
         return response_str
 
     def invoke(self, messages: List[Dict[str, str]]) -> Any:

soprano_sdk/agents/structured_output.py

@@ -16,15 +16,19 @@ def create_structured_output_model(
     fields: List[Dict[str, Any]],
     model_name: str = "StructuredOutput",
     needs_intent_change: bool = False,
+    enable_out_of_scope: bool = False,
 ) -> Type[BaseModel]:
     if not fields:
         raise ValueError("At least one field definition is required")
-    
+
     field_definitions = {"bot_response": (Optional[str], Field(None, description="bot response for the user query, only use this for clarification or asking for more information"))}
 
     if needs_intent_change:
         field_definitions["intent_change"] = (Optional[str], Field(None, description="node name for handling new intent"))
 
+    if enable_out_of_scope:
+        field_definitions["out_of_scope"] = (Optional[str], Field(None, description="Brief description of what the user is trying to do if their query is completely outside the scope of this workflow"))
+
     for field_def in fields:
         field_name = field_def.get("name")
         field_type = field_def.get("type")

soprano_sdk/core/constants.py

@@ -23,12 +23,14 @@ class ActionType(Enum):
     COLLECT_INPUT_WITH_AGENT = 'collect_input_with_agent'
     CALL_FUNCTION = 'call_function'
     CALL_ASYNC_FUNCTION = 'call_async_function'
+    FOLLOW_UP = 'follow_up'
 
 
 class InterruptType:
     """Interrupt type markers for workflow pauses"""
     USER_INPUT = '__WORKFLOW_INTERRUPT__'
     ASYNC = '__ASYNC_INTERRUPT__'
+    OUT_OF_SCOPE = '__OUT_OF_SCOPE_INTERRUPT__'
 
 
 class DataType(Enum):

soprano_sdk/core/engine.py

@@ -41,6 +41,7 @@ class WorkflowEngine:
             self.data_fields = self.load_data()
             self.outcomes = self.load_outcomes()
             self.metadata = self.config.get('metadata', {})
+            self.failure_message: Optional[str] = self.config.get('failure_message')
 
             self.StateType = create_state_model(self.data_fields)
 

soprano_sdk/core/state.py

@@ -1,5 +1,5 @@
 import types
-from typing import Annotated, Optional, Dict, List, Any
+from typing import Annotated, Optional, Dict, List, Any, Union
 
 from typing_extensions import TypedDict
 
@@ -46,7 +46,7 @@ def create_state_model(data_fields: List[dict]):
     fields['_node_execution_order'] = Annotated[List[str], replace]
     fields['_node_field_map'] = Annotated[Dict[str, str], replace]
     fields['_computed_fields'] = Annotated[List[str], replace]
-    fields['error'] = Annotated[Optional[Dict[str, str]], replace]
+    fields['error'] = Annotated[Union[str, Dict[str, str], None], replace]
     fields['_mfa'] = Annotated[Optional[Dict[str, str]], replace]
     fields['_mfa_config'] = Annotated[Optional[Any], replace]
     fields['mfa_input'] = Annotated[Optional[Dict[str, str]], replace]

soprano_sdk/nodes/base.py

@@ -40,7 +40,12 @@ class ActionStrategy(ABC):
             except Exception as e:
                 logger.error(f"Node {self.step_id} failed: {e}", exc_info=True)
                 self._set_status(state, WorkflowKeys.ERROR)
-                state[WorkflowKeys.ERROR] = {"error": f"Unable to complete the request: {str(e)}"}
+
+                # Use custom error message from engine context if available
+                failure_message = getattr(self.engine_context, 'failure_message', None)
+                error_message = failure_message if failure_message else f"Unable to complete the request: {str(e)}"
+
+                state[WorkflowKeys.ERROR] = error_message
                 state[WorkflowKeys.OUTCOME_ID] = WorkflowKeys.ERROR
                 return state
 

soprano_sdk/nodes/collect_input.py

@@ -25,6 +25,31 @@ from ..utils.tracing import trace_node_execution, trace_agent_invocation, add_no
 VALIDATION_ERROR_MESSAGE = "validation failed for the provided input, please enter valid input"
 INVALID_INPUT_MESSAGE = "Looks like the input is invalid. Please double-check and re-enter it."
 COLLECTION_FAILURE_MESSAGE = "I couldn't understand your response. Please try again and provide the required information."
+OUT_OF_SCOPE_PATTERN = "OUT_OF_SCOPE:"
+
+
+def _wrap_instructions_with_out_of_scope_detection(
+    instructions: str,
+    scope_description: str,
+    with_structured_output: bool
+) -> str:
+    """Append out-of-scope detection instructions. Backward compatible - works with any scope_description."""
+    return f"""{instructions}
+
+OUT-OF-SCOPE DETECTION:
+Your current task is: {scope_description}
+
+If the user's query is COMPLETELY UNRELATED to this task:
+- {"Set out_of_scope to a brief description of what the user is trying to do" if with_structured_output else "Respond with: OUT_OF_SCOPE: <brief description of user intent>"}
+- Do NOT attempt to answer or redirect the query
+- Do NOT confuse this with intent changes between collection steps
+
+Examples of out-of-scope queries:
+- Asking about completely different products/services
+- Requesting actions unrelated to the current task
+- General questions that don't fit the current workflow
+"""
+
 
 def _wrap_instructions_with_intent_detection(
         instructions: str,
@@ -97,6 +122,13 @@ class CollectInputStrategy(ActionStrategy):
         self.next_step = self.step_config.get("next", None)
         self.is_structured_output = self.agent_config.get("structured_output", {}).get("enabled", False)
 
+        # Out-of-scope detection configuration (enabled by default)
+        self.enable_out_of_scope = self.agent_config.get("detect_out_of_scope", True)
+        self.scope_description = self.agent_config.get(
+            "scope_description",
+            self.agent_config.get("description", f"collecting {self.field}")
+        )
+
         rollback_strategy_name = engine_context.get_config_value("rollback_strategy", "history_based")
         self.rollback_strategy = _create_rollback_strategy(rollback_strategy_name)
         logger.info(f"Using rollback strategy: {self.rollback_strategy.get_strategy_name()}")
@@ -168,11 +200,22 @@ class CollectInputStrategy(ActionStrategy):
             ):
                 agent_response = _get_agent_response(agent, conversation)
 
+            # Get user message for out-of-scope handling
+            user_message = next(
+                (msg['content'] for msg in reversed(conversation) if msg['role'] == 'user'),
+                ""
+            )
+
             if self.is_structured_output:
-                state = self._handle_structured_output_transition(state, conversation, agent_response)
+                state = self._handle_structured_output_transition(state, conversation, agent_response, user_message)
                 add_node_result(span, self.field, state.get(self.field), state.get(WorkflowKeys.STATUS))
                 return self._add_node_to_execution_order(state)
 
+            # Check for out-of-scope before intent change (for non-structured output)
+            if self.enable_out_of_scope and agent_response.startswith(OUT_OF_SCOPE_PATTERN):
+                span.add_event("out_of_scope.detected")
+                return self._handle_out_of_scope(agent_response, state, user_message)
+
             if agent_response.startswith(TransitionPattern.INTENT_CHANGE):
                 span.add_event("intent.change_detected")
                 return self._handle_intent_change(agent_response, state)
@@ -311,6 +354,13 @@ class CollectInputStrategy(ActionStrategy):
                 if node_id not in self.engine_context.mfa_validator_steps
             }
             instructions = _wrap_instructions_with_intent_detection(instructions, collector_nodes_for_intent_change, self.is_structured_output)
+
+        # Add out-of-scope detection instructions if enabled
+        if self.enable_out_of_scope:
+            instructions = _wrap_instructions_with_out_of_scope_detection(
+                instructions, self.scope_description, self.is_structured_output
+            )
+
         return instructions
 
     def _load_agent_tools(self, state: Dict[str, Any]) -> List:
@@ -323,18 +373,19 @@ class CollectInputStrategy(ActionStrategy):
         structured_output_config = self.agent_config.get('structured_output')
         if not structured_output_config or not structured_output_config.get('enabled'):
             return None
-        
+
         fields = structured_output_config.get('fields', [])
         if not fields:
             return None
-        
+
         validate_field_definitions(fields)
         model_name = f"{self.field.title().replace('_', '')}StructuredOutput"
-        
+
         return create_structured_output_model(
             fields=fields,
             model_name=model_name,
-            needs_intent_change=len(collector_nodes) > 0
+            needs_intent_change=len(collector_nodes) > 0,
+            enable_out_of_scope=self.enable_out_of_scope
         )
 
     def _create_agent(self, state: Dict[str, Any]) -> AgentAdapter:
@@ -399,7 +450,7 @@ class CollectInputStrategy(ActionStrategy):
             target_node = target_node_or_response.split(TransitionPattern.INTENT_CHANGE)[1].strip()
         else:
             target_node = target_node_or_response
-        
+
         logger.info(f"Intent change detected: {self.step_id} -> {target_node}")
 
         rollback_state = self._rollback_state_to_node(state, target_node)
@@ -410,6 +461,24 @@ class CollectInputStrategy(ActionStrategy):
 
         return rollback_state
 
+    def _handle_out_of_scope(self, reason: str, state: Dict[str, Any], user_message: str) -> Dict[str, Any]:
+        """Handle out-of-scope user input by signaling to parent orchestrator"""
+        if isinstance(reason, str) and OUT_OF_SCOPE_PATTERN in reason:
+            reason = reason.split(OUT_OF_SCOPE_PATTERN)[1].strip()
+
+        logger.info(f"Out-of-scope detected in step '{self.step_id}': {reason}")
+
+        # Store the out-of-scope reason and interrupt with user message
+        state['_out_of_scope_reason'] = reason
+        interrupt({
+            "type": "out_of_scope",
+            "step_id": self.step_id,
+            "reason": reason,
+            "user_message": user_message
+        })
+
+        return state
+
     def _rollback_state_to_node(
         self,
         state: Dict[str, Any],
@@ -491,13 +560,17 @@ class CollectInputStrategy(ActionStrategy):
 
         return state
 
-    def _handle_structured_output_transition(self, state: Dict[str, Any], conversation: List, agent_response: Any) -> Dict[str, Any]:
+    def _handle_structured_output_transition(self, state: Dict[str, Any], conversation: List, agent_response: Any, user_message: str = "") -> Dict[str, Any]:
 
         try:
             agent_response = json.loads(agent_response) if isinstance(agent_response, str) else agent_response
         except (json.JSONDecodeError, TypeError, ValueError):
             pass
 
+        # Check for out-of-scope first (before intent change)
+        if self.enable_out_of_scope and (out_of_scope_reason := agent_response.get("out_of_scope")):
+            return self._handle_out_of_scope(out_of_scope_reason, state, user_message)
+
         if target_node := agent_response.get("intent_change"):
             return self._handle_intent_change(target_node, state)
 

soprano_sdk/nodes/factory.py

@@ -4,6 +4,7 @@ from .base import ActionStrategy
 from .call_function import CallFunctionStrategy
 from .collect_input import CollectInputStrategy
 from .async_function import AsyncFunctionStrategy
+from .follow_up import FollowUpStrategy
 from ..core.constants import ActionType
 from ..utils.logger import logger
 
@@ -46,3 +47,4 @@ class NodeFactory:
 NodeFactory.register(ActionType.COLLECT_INPUT_WITH_AGENT.value, CollectInputStrategy)
 NodeFactory.register(ActionType.CALL_FUNCTION.value, CallFunctionStrategy)
 NodeFactory.register(ActionType.CALL_ASYNC_FUNCTION.value, AsyncFunctionStrategy)
+NodeFactory.register(ActionType.FOLLOW_UP.value, FollowUpStrategy)

soprano_sdk/nodes/follow_up.py

@@ -0,0 +1,346 @@
+"""
+Follow-up node strategy for handling conversational Q&A.
+
+This node type allows users to ask follow-up questions and receive answers
+based on the full workflow context. Unlike collect_input_with_agent where
+the agent initiates, here the user initiates by asking questions first.
+"""
+from typing import Dict, Any, List
+
+from langgraph.types import interrupt
+
+from .base import ActionStrategy
+from ..agents.factory import AgentFactory, AgentAdapter
+from ..core.constants import WorkflowKeys
+from ..core.state import initialize_state
+from ..utils.logger import logger
+from ..utils.tracing import trace_node_execution, trace_agent_invocation, add_node_result
+
+# Patterns for detecting special responses
+OUT_OF_SCOPE_PATTERN = "OUT_OF_SCOPE:"
+INTENT_CHANGE_PATTERN = "INTENT_CHANGE:"
+CLOSURE_PATTERN = "CLOSURE:"
+
+# Default patterns that indicate user is done with follow-up
+DEFAULT_CLOSURE_PATTERNS = [
+    "ok", "okay", "thank you", "thanks", "got it", "done",
+    "that's all", "no more questions", "i understand", "perfect",
+    "great", "alright", "understood"
+]
+
+
+def _build_follow_up_instructions(
+    base_instructions: str,
+    context_summary: str,
+    collector_nodes: Dict[str, str],
+    enable_out_of_scope: bool,
+    scope_description: str
+) -> str:
+    """Build complete agent instructions for follow-up node."""
+    instructions = f"""{base_instructions}
+
+{context_summary}
+
+RESPONSE GUIDELINES:
+1. Answer the user's follow-up questions using the context above
+2. Be concise and helpful
+3. Do NOT ask for new information - just answer questions about existing data
+"""
+
+    # Add intent change detection if collector nodes exist
+    if collector_nodes:
+        nodes_str = "\n".join(f"- {k}: {v}" for k, v in collector_nodes.items())
+        instructions += f"""
+INTENT CHANGE DETECTION:
+If the user wants to change or update previously collected information, respond ONLY with:
+INTENT_CHANGE: <node_name>
+
+Do NOT provide any other response when detecting intent change.
+
+Available nodes for intent change:
+{nodes_str}
+"""
+
+    # Add out-of-scope detection if enabled
+    if enable_out_of_scope:
+        instructions += f"""
+OUT-OF-SCOPE DETECTION:
+Your current task is: {scope_description}
+
+If the user's query is COMPLETELY UNRELATED to this task, respond ONLY with:
+OUT_OF_SCOPE: <brief description of what user is asking about>
+
+Do NOT attempt to answer out-of-scope questions.
+"""
+
+    return instructions
+
+
+class FollowUpStrategy(ActionStrategy):
+    """
+    Strategy for handling follow-up questions and routing based on user intent.
+
+    Key difference from CollectInputStrategy:
+    - collect_input: Agent asks first, user responds
+    - follow_up: User asks first, agent responds
+
+    Features:
+    - Multi-turn conversation with full workflow state context
+    - Closure detection (user says "ok", "thank you", etc.)
+    - Intent change detection (route to collector nodes)
+    - Transition-based routing (route to any configured node)
+    - Out-of-scope detection (signal to parent orchestrator)
+    """
+
+    def __init__(self, step_config: Dict[str, Any], engine_context: Any):
+        super().__init__(step_config, engine_context)
+        self.agent_config = step_config.get('agent', {})
+        self.transitions = self._get_transitions()
+        self.next_step = step_config.get('next')
+
+        # Follow-up specific config
+        self.closure_patterns = step_config.get(
+            'closure_patterns',
+            DEFAULT_CLOSURE_PATTERNS
+        )
+        self.enable_out_of_scope = self.agent_config.get('detect_out_of_scope', True)
+        self.scope_description = self.agent_config.get(
+            'scope_description',
+            self.agent_config.get('description', 'answering follow-up questions')
+        )
+
+    @property
+    def _conversation_key(self) -> str:
+        return f'{self.step_id}_conversation'
+
+    def pre_execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """Setup before execution - minimal for follow-up node."""
+        pass
+
+    def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """Execute the follow-up node logic."""
+        with trace_node_execution(
+            node_id=self.step_id,
+            node_type="follow_up",
+            output_field=None
+        ) as span:
+            state = initialize_state(state)
+            conversation = self._get_or_create_conversation(state)
+            is_self_loop = self._is_self_loop(state)
+
+            # Get prompt for user
+            # - First entry: No prompt, user initiates
+            # - Self-loop: Show last assistant response as prompt
+            if is_self_loop:
+                prompt = self._get_last_assistant_message(conversation)
+            else:
+                prompt = None  # User initiates on first entry
+                span.add_event("follow_up.first_entry")
+
+            # Interrupt to get user input
+            user_input = interrupt(prompt)
+            conversation.append({"role": "user", "content": user_input})
+            span.add_event("user.input_received", {"input_length": len(user_input)})
+
+            # Check for closure (user is done)
+            if self._is_closure_intent(user_input):
+                span.add_event("closure.detected")
+                return self._handle_closure(state)
+
+            # Create agent with full state context
+            agent = self._create_agent(state)
+
+            # Get agent response
+            with trace_agent_invocation(
+                agent_name=self.agent_config.get('name', self.step_id),
+                model=self.agent_config.get('model', 'default')
+            ):
+                agent_response = agent.invoke(conversation)
+                conversation.append({"role": "assistant", "content": str(agent_response)})
+
+            # Check for out-of-scope
+            if self.enable_out_of_scope and self._is_out_of_scope(agent_response):
+                span.add_event("out_of_scope.detected")
+                return self._handle_out_of_scope(agent_response, state, user_input)
+
+            # Check for intent change
+            if self._is_intent_change(agent_response):
+                span.add_event("intent_change.detected")
+                return self._handle_intent_change(agent_response, state)
+
+            # Check for explicit routing via transitions
+            if routing_target := self._check_transitions(agent_response):
+                span.add_event("transition.matched", {"target": routing_target})
+                self._set_status(state, routing_target)
+                if routing_target in self.engine_context.outcome_map:
+                    self._set_outcome(state, routing_target)
+                return state
+
+            # Default: self-loop for more Q&A
+            self._set_status(state, 'answering')
+            self._update_conversation(state, conversation)
+            add_node_result(span, None, None, state.get(WorkflowKeys.STATUS))
+
+        return state
+
+    def _is_self_loop(self, state: Dict[str, Any]) -> bool:
+        """Check if we're in a self-loop (returning after answering)."""
+        return state.get(WorkflowKeys.STATUS) == f'{self.step_id}_answering'
+
+    def _get_or_create_conversation(self, state: Dict[str, Any]) -> List[Dict[str, str]]:
+        """Get or create conversation history for this node."""
+        conversations = state.get(WorkflowKeys.CONVERSATIONS, {})
+        if self._conversation_key not in conversations:
+            conversations[self._conversation_key] = []
+            state[WorkflowKeys.CONVERSATIONS] = conversations
+        return conversations[self._conversation_key]
+
+    def _update_conversation(self, state: Dict[str, Any], conversation: List[Dict[str, str]]):
+        """Update conversation in state."""
+        state[WorkflowKeys.CONVERSATIONS][self._conversation_key] = conversation
+
+    def _get_last_assistant_message(self, conversation: List[Dict[str, str]]) -> str:
+        """Get the last assistant message from conversation."""
+        return next(
+            (msg['content'] for msg in reversed(conversation) if msg['role'] == 'assistant'),
+            None
+        )
+
+    def _is_closure_intent(self, user_input: str) -> bool:
+        """Check if user input indicates they're done with follow-up."""
+        normalized = user_input.lower().strip()
+        # Check for exact matches or patterns within the input
+        for pattern in self.closure_patterns:
+            if pattern in normalized:
+                return True
+        return False
+
+    def _handle_closure(self, state: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle user indicating they're done - proceed to next step."""
+        logger.info(f"Closure detected in follow-up node '{self.step_id}'")
+        if self.next_step:
+            self._set_status(state, self.next_step)
+            if self.next_step in self.engine_context.outcome_map:
+                self._set_outcome(state, self.next_step)
+        else:
+            self._set_status(state, 'complete')
+        state[WorkflowKeys.MESSAGES] = ["Follow-up complete."]
+        return state
+
+    def _is_out_of_scope(self, agent_response: str) -> bool:
+        """Check if agent response indicates out-of-scope query."""
+        return str(agent_response).startswith(OUT_OF_SCOPE_PATTERN)
+
+    def _handle_out_of_scope(
+        self,
+        agent_response: str,
+        state: Dict[str, Any],
+        user_message: str
+    ) -> Dict[str, Any]:
+        """Handle out-of-scope user input by signaling to parent orchestrator."""
+        reason = str(agent_response).split(OUT_OF_SCOPE_PATTERN)[1].strip()
+        logger.info(f"Out-of-scope detected in follow-up '{self.step_id}': {reason}")
+
+        state['_out_of_scope_reason'] = reason
+        interrupt({
+            "type": "out_of_scope",
+            "step_id": self.step_id,
+            "reason": reason,
+            "user_message": user_message
+        })
+        return state
+
+    def _is_intent_change(self, agent_response: str) -> bool:
+        """Check if agent response indicates intent change."""
+        return str(agent_response).startswith(INTENT_CHANGE_PATTERN)
+
+    def _handle_intent_change(self, agent_response: str, state: Dict[str, Any]) -> Dict[str, Any]:
+        """Handle intent change to another collector node."""
+        target_node = str(agent_response).split(INTENT_CHANGE_PATTERN)[1].strip()
+        logger.info(f"Intent change detected in follow-up '{self.step_id}' -> {target_node}")
+
+        # Route to the target collector node
+        self._set_status(state, target_node)
+        return state
+
+    def _check_transitions(self, agent_response: str) -> str:
+        """Check if agent response matches any transition pattern."""
+        response_str = str(agent_response)
+        for transition in self.transitions:
+            patterns = transition.get('pattern', [])
+            if isinstance(patterns, str):
+                patterns = [patterns]
+
+            for pattern in patterns:
+                if pattern in response_str:
+                    return transition.get('next')
+        return None
+
+    def _get_model_config(self) -> Dict[str, Any]:
+        """Get model configuration for the agent."""
+        model_config = self.engine_context.get_config_value('model_config')
+        if not model_config:
+            raise ValueError("Model config not found in engine context")
+
+        if model_id := self.agent_config.get("model"):
+            model_config = model_config.copy()
+            model_config["model_name"] = model_id
+
+        return model_config
+
+    def _load_agent_tools(self, state: Dict[str, Any]) -> List:
+        """Load tools for the agent."""
+        return [
+            self.engine_context.tool_repository.load(tool_name, state)
+            for tool_name in self.agent_config.get('tools', [])
+        ]
+
+    def _create_agent(self, state: Dict[str, Any]) -> AgentAdapter:
+        """Create agent with full workflow context in instructions."""
+        try:
+            model_config = self._get_model_config()
+            agent_tools = self._load_agent_tools(state)
+            collector_nodes = state.get(WorkflowKeys.COLLECTOR_NODES, {})
+
+            # Build context summary from collected fields
+            context_summary = self._build_context_summary(state)
+
+            # Build complete instructions
+            base_instructions = self.agent_config.get(
+                'instructions',
+                "You are a helpful assistant answering follow-up questions."
+            )
+            instructions = _build_follow_up_instructions(
+                base_instructions=base_instructions,
+                context_summary=context_summary,
+                collector_nodes=collector_nodes,
+                enable_out_of_scope=self.enable_out_of_scope,
+                scope_description=self.scope_description
+            )
+
+            framework = self.engine_context.get_config_value('agent_framework', 'langgraph')
+
+            return AgentFactory.create_agent(
+                framework=framework,
+                name=self.agent_config.get('name', f'{self.step_id}FollowUp'),
+                model_config=model_config,
+                tools=agent_tools,
+                system_prompt=instructions
+            )
+
+        except Exception as e:
+            raise RuntimeError(f"Failed to create agent for follow-up '{self.step_id}': {e}")
+
+    def _build_context_summary(self, state: Dict[str, Any]) -> str:
+        """Build a summary of collected workflow data for the agent."""
+        context_lines = ["Current workflow context:"]
+
+        for field in self.engine_context.data_fields:
+            field_name = field['name']
+            if field_name in state and state[field_name] is not None:
+                context_lines.append(f"- {field_name}: {state[field_name]}")
+
+        if len(context_lines) == 1:
+            context_lines.append("- (No data collected yet)")
+
+        return "\n".join(context_lines)

soprano_sdk/routing/router.py

@@ -36,6 +36,10 @@ class WorkflowRouter:
             logger.info(f"Self-loop: {self.step_id} (async pending)")
             return self.step_id
 
+        if status == f'{self.step_id}_answering':
+            logger.info(f"Self-loop: {self.step_id} (follow-up answering)")
+            return self.step_id
+
         if status == f'{self.step_id}_error' :
             logger.info(f"Error encountered in {self.step_id}, ending workflow")
             return END
@@ -77,8 +81,8 @@ class WorkflowRouter:
     def get_routing_map(self, collector_nodes: List[str]) -> Dict[str, str]:
         routing_map = {}
 
-        # Self-loop for nodes that can interrupt (agent input or async)
-        if self.action in ('collect_input_with_agent', 'call_async_function'):
+        # Self-loop for nodes that can interrupt (agent input, async, or follow-up)
+        if self.action in ('collect_input_with_agent', 'call_async_function', 'follow_up'):
             routing_map[self.step_id] = self.step_id
 
         for transition in self.transitions:

soprano_sdk/tools.py

@@ -129,6 +129,16 @@ class WorkflowTool:
                     pending_metadata = json.dumps(interrupt_value.get("pending", {}))
                     return f"{InterruptType.ASYNC}|{thread_id}|{self.name}|{pending_metadata}"
 
+                # Check if this is an out-of-scope interrupt
+                if isinstance(interrupt_value, dict) and interrupt_value.get("type") == "out_of_scope":
+                    span.set_attribute("workflow.status", "out_of_scope")
+                    span.set_attribute("out_of_scope.step_id", interrupt_value.get("step_id", ""))
+                    payload = json.dumps({
+                        "reason": interrupt_value.get("reason", "User query is out of scope"),
+                        "user_message": interrupt_value.get("user_message", "")
+                    })
+                    return f"{InterruptType.OUT_OF_SCOPE}|{thread_id}|{self.name}|{payload}"
+
                 # User input interrupt (existing behavior)
                 span.set_attribute("workflow.status", "interrupted")
                 prompt = interrupt_value
@@ -211,6 +221,14 @@ class WorkflowTool:
                 pending_metadata = json.dumps(interrupt_value.get("pending", {}))
                 return f"{InterruptType.ASYNC}|{thread_id}|{self.name}|{pending_metadata}"
 
+            # Check if this is an out-of-scope interrupt
+            if isinstance(interrupt_value, dict) and interrupt_value.get("type") == "out_of_scope":
+                payload = json.dumps({
+                    "reason": interrupt_value.get("reason", "User query is out of scope"),
+                    "user_message": interrupt_value.get("user_message", "")
+                })
+                return f"{InterruptType.OUT_OF_SCOPE}|{thread_id}|{self.name}|{payload}"
+
             # User input interrupt
             return f"{InterruptType.USER_INPUT}|{thread_id}|{self.name}|{interrupt_value}"
 

soprano_sdk/validation/schema.py

@@ -58,6 +58,10 @@ WORKFLOW_SCHEMA = {
                 "description": "Name of a field from the data array"
             }
         },
+        "failure_message":{
+            "type": "string",
+            "description": "Default message to be returned when any error occurs within the framework."
+        },
         "steps": {
             "type": "array",
             "description": "Workflow steps",

{soprano_sdk-0.2.18.dist-info → soprano_sdk-0.2.20.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soprano-sdk
-Version: 0.2.18
+Version: 0.2.20
 Summary: YAML-driven workflow engine with AI agent integration for building conversational SOPs
 Author: Arvind Thangamani
 License: MIT
@@ -51,6 +51,9 @@ A YAML-driven workflow engine with AI agent integration for building conversatio
 - **External Context Injection**: Support for pre-populated fields from external orchestrators
 - **Pattern Matching**: Flexible transition logic based on patterns and conditions
 - **Visualization**: Generate workflow graphs as images or Mermaid diagrams
+- **Follow-up Conversations**: Handle user follow-up questions with full workflow context
+- **Intent Detection**: Route users between collector nodes based on detected intent
+- **Out-of-Scope Detection**: Signal when user queries are unrelated to the current workflow
 
 ## Installation
 
@@ -268,6 +271,108 @@ Calls a Python function with workflow state.
       next: failure_step
 ```
 
+### call_async_function
+
+Calls an async function that may return a pending status, triggering an interrupt until the async operation completes.
+
+```yaml
+- id: verify_payment
+  action: call_async_function
+  function: "payments.start_verification"
+  output: verification_result
+  transitions:
+    - condition: "verified"
+      next: payment_approved
+    - condition: "failed"
+      next: payment_rejected
+```
+
+### follow_up
+
+Handles follow-up questions from users. Unlike `collect_input_with_agent` where the agent asks first, here the **user initiates** by asking questions. The agent responds using full workflow context.
+
+```yaml
+- id: handle_questions
+  action: follow_up
+  next: final_confirmation  # Where to go when user says "done"
+  closure_patterns:  # Optional: customize closure detection
+    - "ok"
+    - "thank you"
+    - "done"
+  agent:
+    name: "FollowUpAssistant"
+    model: "gpt-4o-mini"
+    description: "Answering questions about the order"
+    instructions: |
+      Help the user with any questions about their order.
+      Be concise and helpful.
+    detect_out_of_scope: true  # Signal when user asks unrelated questions
+  transitions:  # Optional: route based on patterns
+    - pattern: "ROUTE_TO_PAYMENT:"
+      next: payment_step
+```
+
+**Key features:**
+- **User initiates**: No initial prompt - waits for user to ask a question
+- **Full state context**: Agent sees all collected workflow data
+- **Closure detection**: Detects "ok", "thanks", "done" → proceeds to next step
+- **Intent change**: Routes to collector nodes when user wants to change data
+- **Out-of-scope**: Signals to parent orchestrator for unrelated queries
+
+## Interrupt Types
+
+The workflow engine uses three interrupt types to pause execution and communicate with the caller:
+
+| Type | Marker | Triggered By | Use Case |
+|------|--------|--------------|----------|
+| **USER_INPUT** | `__WORKFLOW_INTERRUPT__` | `collect_input_with_agent`, `follow_up` | Waiting for user input |
+| **ASYNC** | `__ASYNC_INTERRUPT__` | `call_async_function` | Waiting for async operation callback |
+| **OUT_OF_SCOPE** | `__OUT_OF_SCOPE_INTERRUPT__` | `collect_input_with_agent`, `follow_up` | User query unrelated to current task |
+
+### Handling Interrupts
+
+```python
+result = graph.invoke({}, config=config)
+
+if "__interrupt__" in result and result["__interrupt__"]:
+    interrupt_value = result["__interrupt__"][0].value
+
+    # Check interrupt type
+    if isinstance(interrupt_value, dict):
+        if interrupt_value.get("type") == "async":
+            # Async interrupt - wait for external callback
+            pending_metadata = interrupt_value.get("pending")
+            # ... handle async operation ...
+            result = graph.invoke(Command(resume=async_result), config=config)
+
+        elif interrupt_value.get("type") == "out_of_scope":
+            # Out-of-scope - user asking unrelated question
+            reason = interrupt_value.get("reason")
+            user_message = interrupt_value.get("user_message")
+            # ... route to different workflow or handle appropriately ...
+    else:
+        # User input interrupt - prompt is a string
+        prompt = interrupt_value
+        user_input = input(f"Bot: {prompt}\nYou: ")
+        result = graph.invoke(Command(resume=user_input), config=config)
+```
+
+### Out-of-Scope Detection
+
+Data collector and follow-up nodes can detect when user queries are unrelated to the current task. This is useful for multi-workflow systems where a supervisor agent needs to route users to different SOPs.
+
+**Configuration:**
+```yaml
+agent:
+  detect_out_of_scope: true  # Enabled by default
+  scope_description: "collecting order information for returns"  # Optional
+```
+
+**Response format:**
+```
+__OUT_OF_SCOPE_INTERRUPT__|{thread_id}|{workflow_name}|{"reason":"...","user_message":"..."}
+```
+
 ## Examples
 
 See the `examples/` directory for complete workflow examples:
@@ -411,6 +516,8 @@ Contributions are welcome! Please open an issue or submit a pull request.
 - ✅ Database persistence (SqliteSaver, PostgresSaver supported)
 - ✅ Pluggable checkpointer system
 - ✅ Thread ID strategies and examples
+- ✅ Follow-up node for conversational Q&A
+- ✅ Out-of-scope detection for multi-workflow routing
 - Additional action types (webhook, conditional branching, parallel execution)
 - More workflow examples (customer onboarding, support ticketing, approval flows)
 - Workflow testing utilities

{soprano_sdk-0.2.18.dist-info → soprano_sdk-0.2.20.dist-info}/RECORD

@@ -1,25 +1,26 @@
 soprano_sdk/__init__.py,sha256=YZVl_SwQ0C-E_5_f1AwUe_hPcbgCt8k7k4_WAHM8vjE,243
 soprano_sdk/engine.py,sha256=EFK91iTHjp72otLN6Kg-yeLye2J3CAKN0QH4FI2taL8,14838
-soprano_sdk/tools.py,sha256=dmJ0OZ7Bj3rvjBQvLzgWlYRFVtNJOyMO2jLqaS13cAc,10971
+soprano_sdk/tools.py,sha256=g2G86-PpSsnWkEmukRl0mVSj0ANk_Q39QrulFvfvA1M,12116
 soprano_sdk/agents/__init__.py,sha256=Yzbtv6iP_ABRgZo0IUjy9vDofEvLFbOjuABw758176A,636
-soprano_sdk/agents/adaptor.py,sha256=xJ3MBTU91fQxA9O7V5Xds6m8-n_NxkF0YiKGaWKLmrQ,4959
+soprano_sdk/agents/adaptor.py,sha256=5y9e2F_ZILOPrkunvv0GhjVdniAnOOTaD4j3Ig-xd3c,5041
 soprano_sdk/agents/factory.py,sha256=CvXhpvtjf_Hb4Ce8WKAa0FzyY5Jm6lssvIIfSXu7jPY,9788
-soprano_sdk/agents/structured_output.py,sha256=7DSVzfMPsZAqBwI3v6XL15qG5Gh4jJ-qddcVPaa3gdc,3326
+soprano_sdk/agents/structured_output.py,sha256=VnSRmgarbgsozQSdCr9fVSjclwi04GJ6Nz5lut9qiUk,3593
 soprano_sdk/authenticators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soprano_sdk/authenticators/mfa.py,sha256=xnur1lxbx4r_pUaNPD8vtQiNccQTjbPnqgi_vqdRZaQ,7336
 soprano_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-soprano_sdk/core/constants.py,sha256=UPXlRbF7gsOUNOV0Lm0jvgFfgZX7JrsV6n9I5csMfns,3508
-soprano_sdk/core/engine.py,sha256=HKYoqwDm541pWSWwEKHxLlL3PX90Ux_5l_-HqihgL-g,12245
+soprano_sdk/core/constants.py,sha256=SpFf2_G0-qWYWLxbom-G9vF3lsX1jzJEXI9rVyRRC7I,3584
+soprano_sdk/core/engine.py,sha256=RcUsWEyC9VljTxsv11-jTpmdO4k8lejK_5_OpHR3pS8,12330
 soprano_sdk/core/rollback_strategies.py,sha256=NjDTtBCZlqyDql5PSwI9SMDLK7_BNlTxbW_cq_5gV0g,7783
-soprano_sdk/core/state.py,sha256=k8ojLfWgjES3p9XWMeGU5s4UK-Xa5T8mS4VtZzTrcDw,2961
+soprano_sdk/core/state.py,sha256=BZWL5W9zecjNe-IFg_4zv0lSLPqRST67mN01Zi8H2mk,2976
 soprano_sdk/nodes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soprano_sdk/nodes/async_function.py,sha256=v6WujLKm8NXX2iAkJ7Gz_QIVCtWFrpC6nnPyyfuCxXs,9354
-soprano_sdk/nodes/base.py,sha256=idFyOGGPnjsASYnrOF_NIh7eFcSuJqw61EoVN_WCTaU,2360
+soprano_sdk/nodes/base.py,sha256=gjgAe5dqNk5ItOETLhwF6is7l9BJtrAouLXFOiDKA3E,2601
 soprano_sdk/nodes/call_function.py,sha256=afYBmj5Aditbkvb_7gD3CsXBEEUohcsC1_cdHfcOunE,5847
-soprano_sdk/nodes/collect_input.py,sha256=PySlghXOWDl6AYKgimY_7BnVFN7odYG656aBK_z4ACE,24617
-soprano_sdk/nodes/factory.py,sha256=IbBzT4FKBnYw5PuSo7uDONV3HSFtoyqjBQQtXtUY2IY,1756
+soprano_sdk/nodes/collect_input.py,sha256=5b_QbFQ3eIgohhchvDY_-o3Q66I5llWaqIoKkB56t5A,27744
+soprano_sdk/nodes/factory.py,sha256=i37whA0ugMSwbmWk6H798Suhq6J108a5VenuFqxCVu8,1863
+soprano_sdk/nodes/follow_up.py,sha256=UKy6OswSoMeJ0U5Basf5CAvrbFzERvmwYB-ii8JAt6U,13873
 soprano_sdk/routing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-soprano_sdk/routing/router.py,sha256=Z218r4BMbmlL9282ombutAoKsIs1WHZ2d5YHnbCeet8,3698
+soprano_sdk/routing/router.py,sha256=ECZn7NIVrVQ5l5eZr8sfVNT0MShixnQEsqh4YO6XwRs,3882
 soprano_sdk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soprano_sdk/utils/function.py,sha256=yqkY4MlHOenv-Q3NciiovK1lamyrGQljpy6Q41wviy8,1216
 soprano_sdk/utils/logger.py,sha256=hMYaNHt5syGOXRkglTUKzkgfSbWerix_pHQntcYyep8,157
@@ -27,9 +28,9 @@ soprano_sdk/utils/template.py,sha256=MG_B9TMx1ShpnSGo7s7TO-VfQzuFByuRNhJTvZ668kM
 soprano_sdk/utils/tool.py,sha256=hWN826HIKmLdswLCTURLH8hWlb2WU0MB8nIUErbpB-8,1877
 soprano_sdk/utils/tracing.py,sha256=gSHeBDLe-MbAZ9rkzpCoGFveeMdR9KLaA6tteB0IWjk,1991
 soprano_sdk/validation/__init__.py,sha256=ImChmO86jYHU90xzTttto2-LmOUOmvY_ibOQaLRz5BA,262
-soprano_sdk/validation/schema.py,sha256=eRGXXMDlJyaH0XYMOXY1azvJlJwOdbHFrHjB1yuGROg,15434
+soprano_sdk/validation/schema.py,sha256=THGjMdS9qqAiSJgWjhDZ8jwHA_WaPgjKop_8CfHeTeY,15607
 soprano_sdk/validation/validator.py,sha256=f-e2MMRL70asOIXr_0Fsd5CgGKVRiQp7AaYsHA45Km0,8792
-soprano_sdk-0.2.18.dist-info/METADATA,sha256=hr2us3VV7sfP7P74YQxTmViJ1L8jkmCLtYeOGDyvvhE,11374
-soprano_sdk-0.2.18.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-soprano_sdk-0.2.18.dist-info/licenses/LICENSE,sha256=A1aBauSjPNtVehOXJe3WuvdU2xvM9H8XmigFMm6665s,1073
-soprano_sdk-0.2.18.dist-info/RECORD,,
+soprano_sdk-0.2.20.dist-info/METADATA,sha256=q_6TFRVADa6_NV3MKKuAqVESfka8WpZT6IXOlqjNFW8,15563
+soprano_sdk-0.2.20.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+soprano_sdk-0.2.20.dist-info/licenses/LICENSE,sha256=A1aBauSjPNtVehOXJe3WuvdU2xvM9H8XmigFMm6665s,1073
+soprano_sdk-0.2.20.dist-info/RECORD,,