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

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

@@ -17,18 +17,22 @@ class WorkflowKeys:
     NODE_FIELD_MAP = '_node_field_map'
     COMPUTED_FIELDS = '_computed_fields'
     ERROR = 'error'
+    TARGET_LANGUAGE = '_target_language'
+    TARGET_SCRIPT = '_target_script'
 
 
 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):
@@ -68,6 +72,47 @@ DEFAULT_TIMEOUT = 300
 MAX_ATTEMPTS_MESSAGE = "I'm having trouble understanding your {field}. Please contact customer service for assistance."
 WORKFLOW_COMPLETE_MESSAGE = "Workflow completed."
 
+# Humanization defaults
+DEFAULT_HUMANIZATION_ENABLED = True
+DEFAULT_HUMANIZATION_SYSTEM_PROMPT = """You are a helpful assistant that transforms template-based messages into natural, conversational responses.
+
+Your task:
+1. Take the reference message provided and rewrite it naturally
+2. Maintain ALL factual information and important details from the reference
+3. Use the conversation history for context and tone matching
+4. Be warm, professional, and helpful
+5. Keep the response concise but complete
+
+Reference message to humanize:
+{reference_message}
+
+Respond with ONLY the humanized message. Do not add explanations or meta-commentary."""
+
+
+class HumanizationKeys:
+    """Keys for humanization agent configuration"""
+    ENABLED = 'enabled'
+    MODEL = 'model'
+    BASE_URL = 'base_url'
+    INSTRUCTIONS = 'instructions'
+
+
+# Localization defaults
+DEFAULT_LOCALIZATION_INSTRUCTIONS = """LANGUAGE REQUIREMENT:
+You MUST respond in {language} using {script} script.
+- All your responses must be in {language}
+- Use the {script} writing system
+- Maintain the same meaning and tone as you would in English
+- Do not mix languages unless quoting the user
+"""
+
+
+class LocalizationKeys:
+    """Keys for localization configuration"""
+    LANGUAGE = 'language'
+    SCRIPT = 'script'
+    INSTRUCTIONS = 'instructions'
+
 
 class MFAConfig(BaseSettings):
     """

soprano_sdk/core/engine.py

@@ -1,4 +1,4 @@
-from typing import Optional, Dict, Any, Tuple
+from typing import Optional, Dict, Any, Tuple, List
 
 import yaml
 from jinja2 import Environment
@@ -7,7 +7,16 @@ from langgraph.constants import START
 from langgraph.graph import StateGraph
 from langgraph.graph.state import CompiledStateGraph
 
-from .constants import WorkflowKeys, MFAConfig
+from .constants import (
+    WorkflowKeys,
+    MFAConfig,
+    DEFAULT_HUMANIZATION_ENABLED,
+    DEFAULT_HUMANIZATION_SYSTEM_PROMPT,
+    HumanizationKeys,
+    DEFAULT_LOCALIZATION_INSTRUCTIONS,
+    LocalizationKeys
+)
+from ..agents.factory import AgentFactory
 from .state import create_state_model
 from ..nodes.factory import NodeFactory
 from ..routing.router import WorkflowRouter
@@ -41,6 +50,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)
 
@@ -147,6 +157,167 @@ class WorkflowEngine:
         except Exception as e:
             raise RuntimeError(f"Failed to build workflow graph: {e}")
 
+    def _aggregate_conversation_history(self, state: Dict[str, Any]) -> List[Dict[str, str]]:
+        """Aggregate all conversations from collector nodes in execution order."""
+        conversations = state.get(WorkflowKeys.CONVERSATIONS, {})
+        node_order = state.get(WorkflowKeys.NODE_EXECUTION_ORDER, [])
+        node_field_map = state.get(WorkflowKeys.NODE_FIELD_MAP, {})
+
+        aggregated = []
+        for node_id in node_order:
+            field = node_field_map.get(node_id)
+            if field:
+                conv_key = f"{field}_conversation"
+                if conv_messages := conversations.get(conv_key):
+                    aggregated.extend(conv_messages)
+
+        return aggregated
+
+    def _get_humanization_config(self) -> Dict[str, Any]:
+        """Get humanization agent configuration from workflow config."""
+        return self.config.get('humanization_agent', {})
+
+    def _should_humanize_outcome(self, outcome: Dict[str, Any]) -> bool:
+        """Determine if an outcome should be humanized."""
+        # Check workflow-level setting (default: enabled)
+        workflow_humanization = self._get_humanization_config()
+        workflow_enabled = workflow_humanization.get(
+            HumanizationKeys.ENABLED,
+            DEFAULT_HUMANIZATION_ENABLED
+        )
+
+        if not workflow_enabled:
+            return False
+
+        # Check per-outcome setting (default: True, inherit from workflow)
+        return outcome.get('humanize', True)
+
+    def _get_humanization_model_config(self) -> Optional[Dict[str, Any]]:
+        """Get model config for humanization, with overrides applied."""
+        model_config = self.get_config_value('model_config')
+        if not model_config:
+            return None
+
+        humanization_config = self._get_humanization_config()
+        model_config = model_config.copy()  # Don't mutate original
+
+        # Apply overrides from humanization_agent config
+        if model := humanization_config.get(HumanizationKeys.MODEL):
+            model_config['model_name'] = model
+        if base_url := humanization_config.get(HumanizationKeys.BASE_URL):
+            model_config['base_url'] = base_url
+
+        return model_config
+
+    def _get_localization_config(self) -> Dict[str, Any]:
+        """Get localization configuration from workflow config."""
+        return self.config.get('localization', {})
+
+    def get_localization_instructions(self, state: Dict[str, Any]) -> str:
+        """Get localization instructions based on state (per-turn) or YAML defaults.
+
+        Args:
+            state: Current workflow state containing per-turn language/script values
+
+        Returns:
+            Localization instructions string to prepend to agent prompts, or empty string if no localization
+        """
+        # First check state for per-turn values
+        language = state.get(WorkflowKeys.TARGET_LANGUAGE)
+        script = state.get(WorkflowKeys.TARGET_SCRIPT)
+
+        # Fall back to YAML defaults if not in state
+        yaml_config = self._get_localization_config()
+        if not language:
+            language = yaml_config.get(LocalizationKeys.LANGUAGE)
+        if not script:
+            script = yaml_config.get(LocalizationKeys.SCRIPT)
+
+        # No localization if neither specified
+        if not language and not script:
+            return ""
+
+        # Use custom instructions if provided in YAML
+        custom_instructions = yaml_config.get(LocalizationKeys.INSTRUCTIONS)
+        if custom_instructions:
+            return custom_instructions.format(
+                language=language or "the target language",
+                script=script or "the appropriate script"
+            )
+
+        return DEFAULT_LOCALIZATION_INSTRUCTIONS.format(
+            language=language or "the target language",
+            script=script or "the appropriate script"
+        )
+
+    def _humanize_message(self, reference_message: str, state: Dict[str, Any]) -> str:
+        """Use LLM to humanize the reference message using conversation context."""
+        try:
+            model_config = self._get_humanization_model_config()
+            if not model_config:
+                logger.warning("No model_config found, skipping humanization")
+                return reference_message
+
+            humanization_config = self._get_humanization_config()
+
+            # Build system prompt
+            custom_instructions = humanization_config.get(HumanizationKeys.INSTRUCTIONS)
+            if custom_instructions:
+                system_prompt = f"{custom_instructions}\n\nReference message to humanize:\n{reference_message}"
+            else:
+                system_prompt = DEFAULT_HUMANIZATION_SYSTEM_PROMPT.format(
+                    reference_message=reference_message
+                )
+
+            # Inject localization instructions if specified
+            localization_instructions = self.get_localization_instructions(state)
+            if localization_instructions:
+                system_prompt = f"{localization_instructions}\n\n{system_prompt}"
+
+            # Aggregate conversation history
+            conversation_history = self._aggregate_conversation_history(state)
+
+            # Create agent for humanization
+            framework = self.get_config_value('agent_framework', 'langgraph')
+            agent = AgentFactory.create_agent(
+                framework=framework,
+                name="HumanizationAgent",
+                model_config=model_config,
+                tools=[],
+                system_prompt=system_prompt,
+                structured_output_model=None
+            )
+
+            # Invoke agent with conversation history
+            if conversation_history:
+                messages = conversation_history + [
+                    {"role": "user", "content": "Please humanize the reference message based on our conversation."}
+                ]
+            else:
+                messages = [
+                    {"role": "user", "content": "Please humanize the reference message."}
+                ]
+
+            humanized_response = agent.invoke(messages)
+
+            # Handle different response types
+            if isinstance(humanized_response, dict):
+                humanized_message = humanized_response.get('content', str(humanized_response))
+            else:
+                humanized_message = str(humanized_response)
+
+            # Validate we got a meaningful response
+            if not humanized_message or humanized_message.strip() == '':
+                logger.warning("Humanization returned empty response, using original message")
+                return reference_message
+
+            logger.info(f"Message humanized successfully: {humanized_message[:100]}...")
+            return humanized_message
+
+        except Exception as e:
+            logger.warning(f"Humanization failed, using original message: {e}")
+            return reference_message
+
     def get_outcome_message(self, state: Dict[str, Any]) -> str:
         outcome_id = state.get(WorkflowKeys.OUTCOME_ID)
         step_id = state.get(WorkflowKeys.STEP_ID)
@@ -155,9 +326,16 @@ class WorkflowEngine:
         if outcome and 'message' in outcome:
             message = outcome['message']
             template_loader = self.get_config_value("template_loader", Environment())
-            message = template_loader.from_string(message).render(state)
-            logger.info(f"Outcome message generated in step {step_id}: {message}")
-            return message
+            rendered_message = template_loader.from_string(message).render(state)
+
+            # Apply humanization if enabled for this outcome
+            if self._should_humanize_outcome(outcome):
+                final_message = self._humanize_message(rendered_message, state)
+            else:
+                final_message = rendered_message
+
+            logger.info(f"Outcome message generated in step {step_id}: {final_message}")
+            return final_message
 
         if error := state.get("error"):
             logger.info(f"Outcome error found in step {step_id}: {error}")

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 (disabled by default)
+        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", 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)
@@ -305,12 +348,24 @@ class CollectInputStrategy(ActionStrategy):
 
         instructions = self._render_template_string(instructions, state)
 
+        # 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}"
+
         if collector_nodes:
             collector_nodes_for_intent_change = {
                 node_id: node_desc for node_id, node_desc in collector_nodes.items()
                 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 +378,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 +455,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 +466,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 +565,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)