soprano-sdk 0.2.20__tar.gz → 0.2.22__tar.gz

{soprano_sdk-0.2.20 → soprano_sdk-0.2.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soprano-sdk
-Version: 0.2.20
+Version: 0.2.22
 Summary: YAML-driven workflow engine with AI agent integration for building conversational SOPs
 Author: Arvind Thangamani
 License: MIT
@@ -54,6 +54,8 @@ A YAML-driven workflow engine with AI agent integration for building conversatio
 - **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
+- **Outcome Humanization**: LLM-powered transformation of outcome messages into natural, context-aware responses
+- **Per-Turn Localization**: Dynamic language and script switching for multi-language support
 
 ## Installation
 
@@ -364,7 +366,7 @@ Data collector and follow-up nodes can detect when user queries are unrelated to
 **Configuration:**
 ```yaml
 agent:
-  detect_out_of_scope: true  # Enabled by default
+  detect_out_of_scope: true  # Disabled by default, set to true to enable
   scope_description: "collecting order information for returns"  # Optional
 ```
 
@@ -373,6 +375,145 @@ agent:
 __OUT_OF_SCOPE_INTERRUPT__|{thread_id}|{workflow_name}|{"reason":"...","user_message":"..."}
 ```
 
+## Outcome Humanization
+
+Outcome messages can be automatically humanized using an LLM to transform template-based messages into natural, context-aware responses. This feature uses the full conversation history to generate responses that match the tone and context of the interaction.
+
+### How It Works
+
+1. **Template rendering**: The outcome message template is first rendered with state values (e.g., `{{order_id}}` → `1234`)
+2. **LLM humanization**: The rendered message is passed to an LLM along with the conversation history
+3. **Natural response**: The LLM generates a warm, conversational response while preserving all factual details
+
+### Configuration
+
+Humanization is **enabled by default**. Configure it at the workflow level:
+
+```yaml
+name: "Return Processing Workflow"
+version: "1.0"
+
+# Humanization configuration (optional - enabled by default)
+humanization_agent:
+  model: "gpt-4o"  # Override model for humanization (optional)
+  base_url: "https://custom-api.com/v1"  # Override base URL (optional)
+  instructions: |  # Custom instructions (optional)
+    You are a friendly customer service representative.
+    Rewrite the message to be warm and empathetic.
+    Always thank the customer for their patience.
+
+outcomes:
+  - id: success
+    type: success
+    message: "Return approved for order {{order_id}}. Reason: {{return_reason}}."
+
+  - id: technical_error
+    type: failure
+    humanize: false  # Disable humanization for this specific outcome
+    message: "Error code: {{error_code}}. Contact support."
+```
+
+### Example Transformation
+
+| Template Message | Humanized Response |
+|-----------------|-------------------|
+| `"Return approved for order 1234. Reason: damaged item."` | `"Great news! I've approved the return for your order #1234. I completely understand about the damaged item - that's so frustrating. You'll receive an email shortly with return instructions. Is there anything else I can help you with?"` |
+
+### Disabling Humanization
+
+**Globally** (for entire workflow):
+```yaml
+humanization_agent:
+  enabled: false
+```
+
+**Per-outcome**:
+```yaml
+outcomes:
+  - id: error_code
+    type: failure
+    humanize: false  # Keep exact message for debugging/logging
+    message: "Error: {{error_code}}"
+```
+
+### Model Configuration
+
+The humanization agent inherits the workflow's runtime `model_config`. You can override specific settings:
+
+```python
+config = {
+    "model_config": {
+        "model_name": "gpt-4o-mini",  # Base model for all agents
+        "api_key": os.getenv("OPENAI_API_KEY"),
+    }
+}
+
+# In YAML, humanization_agent.model overrides model_name for humanization only
+```
+
+## Per-Turn Localization
+
+The framework supports per-turn localization, allowing dynamic language and script switching during workflow execution. Each call to `execute()` can specify a different target language/script.
+
+### How It Works
+
+1. **Per-turn parameters**: Pass `target_language` and `target_script` to `execute()`
+2. **Instruction injection**: Localization instructions are prepended to agent system prompts
+3. **No extra LLM calls**: The same agent that generates the response handles localization
+
+### Usage
+
+**Per-turn language switching:**
+```python
+from soprano_sdk import WorkflowTool
+
+tool = WorkflowTool(
+    yaml_path="return_workflow.yaml",
+    name="return_processor",
+    description="Process returns",
+    checkpointer=checkpointer,
+    config=config
+)
+
+# Turn 1: English (no localization)
+result = tool.execute(thread_id="123", user_message="hi")
+
+# Turn 2: Switch to Tamil
+result = tool.execute(
+    thread_id="123",
+    user_message="my order id is 1234",
+    target_language="Tamil",
+    target_script="Tamil"
+)
+
+# Turn 3: Back to English (no localization params)
+result = tool.execute(thread_id="123", user_message="yes")
+```
+
+### YAML Defaults (Optional)
+
+You can set default localization in the workflow YAML. These are used when `target_language`/`target_script` are not passed to `execute()`:
+
+```yaml
+name: "Return Workflow"
+version: "1.0"
+
+localization:
+  language: "Tamil"
+  script: "Tamil"
+  instructions: |  # Optional: custom instructions
+    Use formal Tamil suitable for customer service.
+    Always be polite and respectful.
+
+# ... rest of workflow
+```
+
+### Key Points
+
+- **Localization affects**: Data collector prompts, follow-up responses, and humanized outcome messages
+- **Outcome messages require humanization**: If `humanize: false`, outcome messages stay in English (template output)
+- **Per-turn override**: Runtime parameters always override YAML defaults
+
 ## Examples
 
 See the `examples/` directory for complete workflow examples:
@@ -518,6 +659,8 @@ Contributions are welcome! Please open an issue or submit a pull request.
 - ✅ Thread ID strategies and examples
 - ✅ Follow-up node for conversational Q&A
 - ✅ Out-of-scope detection for multi-workflow routing
+- ✅ Outcome humanization with LLM
+- ✅ Per-turn localization for multi-language support
 - Additional action types (webhook, conditional branching, parallel execution)
 - More workflow examples (customer onboarding, support ticketing, approval flows)
 - Workflow testing utilities

{soprano_sdk-0.2.20 → soprano_sdk-0.2.22}/README.md

@@ -13,6 +13,8 @@ A YAML-driven workflow engine with AI agent integration for building conversatio
 - **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
+- **Outcome Humanization**: LLM-powered transformation of outcome messages into natural, context-aware responses
+- **Per-Turn Localization**: Dynamic language and script switching for multi-language support
 
 ## Installation
 
@@ -323,7 +325,7 @@ Data collector and follow-up nodes can detect when user queries are unrelated to
 **Configuration:**
 ```yaml
 agent:
-  detect_out_of_scope: true  # Enabled by default
+  detect_out_of_scope: true  # Disabled by default, set to true to enable
   scope_description: "collecting order information for returns"  # Optional
 ```
 
@@ -332,6 +334,145 @@ agent:
 __OUT_OF_SCOPE_INTERRUPT__|{thread_id}|{workflow_name}|{"reason":"...","user_message":"..."}
 ```
 
+## Outcome Humanization
+
+Outcome messages can be automatically humanized using an LLM to transform template-based messages into natural, context-aware responses. This feature uses the full conversation history to generate responses that match the tone and context of the interaction.
+
+### How It Works
+
+1. **Template rendering**: The outcome message template is first rendered with state values (e.g., `{{order_id}}` → `1234`)
+2. **LLM humanization**: The rendered message is passed to an LLM along with the conversation history
+3. **Natural response**: The LLM generates a warm, conversational response while preserving all factual details
+
+### Configuration
+
+Humanization is **enabled by default**. Configure it at the workflow level:
+
+```yaml
+name: "Return Processing Workflow"
+version: "1.0"
+
+# Humanization configuration (optional - enabled by default)
+humanization_agent:
+  model: "gpt-4o"  # Override model for humanization (optional)
+  base_url: "https://custom-api.com/v1"  # Override base URL (optional)
+  instructions: |  # Custom instructions (optional)
+    You are a friendly customer service representative.
+    Rewrite the message to be warm and empathetic.
+    Always thank the customer for their patience.
+
+outcomes:
+  - id: success
+    type: success
+    message: "Return approved for order {{order_id}}. Reason: {{return_reason}}."
+
+  - id: technical_error
+    type: failure
+    humanize: false  # Disable humanization for this specific outcome
+    message: "Error code: {{error_code}}. Contact support."
+```
+
+### Example Transformation
+
+| Template Message | Humanized Response |
+|-----------------|-------------------|
+| `"Return approved for order 1234. Reason: damaged item."` | `"Great news! I've approved the return for your order #1234. I completely understand about the damaged item - that's so frustrating. You'll receive an email shortly with return instructions. Is there anything else I can help you with?"` |
+
+### Disabling Humanization
+
+**Globally** (for entire workflow):
+```yaml
+humanization_agent:
+  enabled: false
+```
+
+**Per-outcome**:
+```yaml
+outcomes:
+  - id: error_code
+    type: failure
+    humanize: false  # Keep exact message for debugging/logging
+    message: "Error: {{error_code}}"
+```
+
+### Model Configuration
+
+The humanization agent inherits the workflow's runtime `model_config`. You can override specific settings:
+
+```python
+config = {
+    "model_config": {
+        "model_name": "gpt-4o-mini",  # Base model for all agents
+        "api_key": os.getenv("OPENAI_API_KEY"),
+    }
+}
+
+# In YAML, humanization_agent.model overrides model_name for humanization only
+```
+
+## Per-Turn Localization
+
+The framework supports per-turn localization, allowing dynamic language and script switching during workflow execution. Each call to `execute()` can specify a different target language/script.
+
+### How It Works
+
+1. **Per-turn parameters**: Pass `target_language` and `target_script` to `execute()`
+2. **Instruction injection**: Localization instructions are prepended to agent system prompts
+3. **No extra LLM calls**: The same agent that generates the response handles localization
+
+### Usage
+
+**Per-turn language switching:**
+```python
+from soprano_sdk import WorkflowTool
+
+tool = WorkflowTool(
+    yaml_path="return_workflow.yaml",
+    name="return_processor",
+    description="Process returns",
+    checkpointer=checkpointer,
+    config=config
+)
+
+# Turn 1: English (no localization)
+result = tool.execute(thread_id="123", user_message="hi")
+
+# Turn 2: Switch to Tamil
+result = tool.execute(
+    thread_id="123",
+    user_message="my order id is 1234",
+    target_language="Tamil",
+    target_script="Tamil"
+)
+
+# Turn 3: Back to English (no localization params)
+result = tool.execute(thread_id="123", user_message="yes")
+```
+
+### YAML Defaults (Optional)
+
+You can set default localization in the workflow YAML. These are used when `target_language`/`target_script` are not passed to `execute()`:
+
+```yaml
+name: "Return Workflow"
+version: "1.0"
+
+localization:
+  language: "Tamil"
+  script: "Tamil"
+  instructions: |  # Optional: custom instructions
+    Use formal Tamil suitable for customer service.
+    Always be polite and respectful.
+
+# ... rest of workflow
+```
+
+### Key Points
+
+- **Localization affects**: Data collector prompts, follow-up responses, and humanized outcome messages
+- **Outcome messages require humanization**: If `humanize: false`, outcome messages stay in English (template output)
+- **Per-turn override**: Runtime parameters always override YAML defaults
+
 ## Examples
 
 See the `examples/` directory for complete workflow examples:
@@ -477,6 +618,8 @@ Contributions are welcome! Please open an issue or submit a pull request.
 - ✅ Thread ID strategies and examples
 - ✅ Follow-up node for conversational Q&A
 - ✅ Out-of-scope detection for multi-workflow routing
+- ✅ Outcome humanization with LLM
+- ✅ Per-turn localization for multi-language support
 - Additional action types (webhook, conditional branching, parallel execution)
 - More workflow examples (customer onboarding, support ticketing, approval flows)
 - Workflow testing utilities

{soprano_sdk-0.2.20 → soprano_sdk-0.2.22}/examples/return_workflow.yaml

@@ -2,6 +2,13 @@ name: "Return Processing Workflow"
 description: "AI-powered workflow for processing customer returns"
 version: "1.0"
 
+# LLM-powered humanization for outcome messages
+humanization_agent:
+  instructions: |
+    You are a friendly customer service representative. Rewrite the message to be warm,
+    empathetic, and conversational while keeping all the important details.
+    Match the tone of the conversation history.
+
 data:
   - name: order_id
     type: text

{soprano_sdk-0.2.20 → soprano_sdk-0.2.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "soprano-sdk"
-version = "0.2.20"
+version = "0.2.22"
 description = "YAML-driven workflow engine with AI agent integration for building conversational SOPs"
 readme = "README.md"
 requires-python = ">=3.12"

{soprano_sdk-0.2.20 → soprano_sdk-0.2.22}/soprano_sdk/core/constants.py

@@ -17,6 +17,8 @@ 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):
@@ -70,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-0.2.20 → soprano_sdk-0.2.22}/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
@@ -148,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)
@@ -156,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-0.2.20 → soprano_sdk-0.2.22}/soprano_sdk/nodes/collect_input.py

@@ -122,8 +122,8 @@ 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)
+        # 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}")
@@ -348,6 +348,11 @@ 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()

{soprano_sdk-0.2.20 → soprano_sdk-0.2.22}/soprano_sdk/nodes/follow_up.py

@@ -103,7 +103,7 @@ class FollowUpStrategy(ActionStrategy):
             'closure_patterns',
             DEFAULT_CLOSURE_PATTERNS
         )
-        self.enable_out_of_scope = self.agent_config.get('detect_out_of_scope', True)
+        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')
@@ -318,6 +318,11 @@ class FollowUpStrategy(ActionStrategy):
                 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(