soprano-sdk 0.2.19__py3-none-any.whl → 0.2.21__py3-none-any.whl

soprano_sdk/nodes/follow_up.py

@@ -0,0 +1,351 @@
+"""
+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', False)
+        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
+            )
+
+            # Inject localization instructions at the start (per-turn)
+            localization_instructions = self.engine_context.get_localization_instructions(state)
+            if localization_instructions:
+                instructions = f"{localization_instructions}\n\n{instructions}"
+
+            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

@@ -10,7 +10,7 @@ from .utils.logger import logger
 from langfuse.langchain import CallbackHandler
 
 from .core.engine import load_workflow
-from .core.constants import MFAConfig, InterruptType
+from .core.constants import MFAConfig, InterruptType, WorkflowKeys
 
 
 class WorkflowTool:
@@ -54,7 +54,9 @@ class WorkflowTool:
         self,
         thread_id: Optional[str] = None,
         user_message: Optional[str] = None,
-        initial_context: Optional[Dict[str, Any]] = None
+        initial_context: Optional[Dict[str, Any]] = None,
+        target_language: Optional[str] = None,
+        target_script: Optional[str] = None
     ) -> str:
         """Execute the workflow with automatic state detection
 
@@ -65,16 +67,25 @@ class WorkflowTool:
             thread_id: Thread ID for state tracking
             user_message: User's message (used for resume if workflow is interrupted)
             initial_context: Context to inject for fresh starts (e.g., {"order_id": "123"})
+            target_language: Target language for this turn (e.g., "Tamil", "Hindi")
+            target_script: Target script for this turn (e.g., "Tamil", "Devanagari")
 
         Returns:
             Final outcome message or interrupt prompt
         """
         from langgraph.types import Command
         from soprano_sdk.utils.tracing import trace_workflow_execution
-        
+
         if thread_id is None:
             thread_id = str(uuid.uuid4())
-        
+
+        # Build localization state for this turn
+        localization_state = {}
+        if target_language:
+            localization_state[WorkflowKeys.TARGET_LANGUAGE] = target_language
+        if target_script:
+            localization_state[WorkflowKeys.TARGET_SCRIPT] = target_script
+
         with trace_workflow_execution(
             workflow_name=self.engine.workflow_name,
             thread_id=thread_id,
@@ -99,8 +110,10 @@ class WorkflowTool:
                     "filtered_out": list(set(initial_context.keys()) - set(filtered_context.keys()))
                 })
 
+                # Merge localization state with filtered context
+                update_state = {**filtered_context, **localization_state}
                 result = self.graph.invoke(
-                    Command(resume=user_message or "", update=filtered_context),
+                    Command(resume=user_message or "", update=update_state),
                     config=config
                 )
 
@@ -112,7 +125,9 @@ class WorkflowTool:
                 self.engine.update_context(initial_context)
                 span.add_event("context.updated", {"fields": list(initial_context.keys())})
 
-                result = self.graph.invoke(initial_context, config=config)
+                # Merge localization state with initial context
+                invoke_state = {**(initial_context or {}), **localization_state}
+                result = self.graph.invoke(invoke_state, config=config)
             
             final_state = self.graph.get_state(config)
             if not final_state.next and self.checkpointer:
@@ -129,6 +144,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
@@ -186,21 +211,35 @@ class WorkflowTool:
     def resume(
         self,
         thread_id: str,
-        resume_value: Union[str, Dict[str, Any]]
+        resume_value: Union[str, Dict[str, Any]],
+        target_language: Optional[str] = None,
+        target_script: Optional[str] = None
     ) -> str:
         """Resume an interrupted workflow with user input or async result
 
         Args:
             thread_id: Thread ID of the interrupted workflow
             resume_value: User's response (str) or async operation result (dict)
+            target_language: Target language for this turn (e.g., "Tamil", "Hindi")
+            target_script: Target script for this turn (e.g., "Tamil", "Devanagari")
 
         Returns:
             Either another interrupt prompt/async metadata or final outcome message
         """
         from langgraph.types import Command
 
+        # Build localization state for this turn
+        localization_state = {}
+        if target_language:
+            localization_state[WorkflowKeys.TARGET_LANGUAGE] = target_language
+        if target_script:
+            localization_state[WorkflowKeys.TARGET_SCRIPT] = target_script
+
         config = {"configurable": {"thread_id": thread_id}}
-        result = self.graph.invoke(Command(resume=resume_value), config=config)
+        if localization_state:
+            result = self.graph.invoke(Command(resume=resume_value, update=localization_state), config=config)
+        else:
+            result = self.graph.invoke(Command(resume=resume_value), config=config)
 
         # Check if workflow needs more input or has another async operation
         if "__interrupt__" in result and result["__interrupt__"]:
@@ -211,6 +250,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

@@ -22,6 +22,48 @@ WORKFLOW_SCHEMA = {
             "default": "langgraph",
             "description": "Agent framework to use for all agents in this workflow (default: langgraph)"
         },
+        "humanization_agent": {
+            "type": "object",
+            "description": "Configuration for LLM-powered message humanization (enabled by default)",
+            "properties": {
+                "enabled": {
+                    "type": "boolean",
+                    "default": True,
+                    "description": "Whether to enable LLM humanization for outcome messages (default: true)"
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Model to use for humanization (overrides model_config.model_name)"
+                },
+                "base_url": {
+                    "type": "string",
+                    "format": "uri",
+                    "description": "Base URL for humanization model (overrides model_config.base_url)"
+                },
+                "instructions": {
+                    "type": "string",
+                    "description": "Custom system prompt for the humanization agent"
+                }
+            }
+        },
+        "localization": {
+            "type": "object",
+            "description": "Default localization configuration (can be overridden per-turn via execute() parameters)",
+            "properties": {
+                "language": {
+                    "type": "string",
+                    "description": "Default target language (e.g., Tamil, Hindi, Spanish)"
+                },
+                "script": {
+                    "type": "string",
+                    "description": "Default target script/writing system (e.g., Tamil, Devanagari, Latin)"
+                },
+                "instructions": {
+                    "type": "string",
+                    "description": "Custom instructions for language/script requirements"
+                }
+            }
+        },
         "data": {
             "type": "array",
             "description": "Data fields used in the workflow",
@@ -58,6 +100,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",
@@ -286,6 +332,11 @@ WORKFLOW_SCHEMA = {
                     "message": {
                         "type": "string",
                         "description": "Outcome message (supports {field} placeholders)"
+                    },
+                    "humanize": {
+                        "type": "boolean",
+                        "default": True,
+                        "description": "Whether to apply LLM humanization to this outcome's message (default: true)"
                     }
                 }
             }