soprano-sdk 0.2.19__tar.gz → 0.2.21__tar.gz

{soprano_sdk-0.2.19 → soprano_sdk-0.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soprano-sdk
-Version: 0.2.19
+Version: 0.2.21
 Summary: YAML-driven workflow engine with AI agent integration for building conversational SOPs
 Author: Arvind Thangamani
 License: MIT
@@ -51,6 +51,11 @@ 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
+- **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
 
@@ -268,6 +273,247 @@ 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  # Disabled by default, set to true to enable
+  scope_description: "collecting order information for returns"  # Optional
+```
+
+**Response format:**
+```
+__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:
@@ -411,6 +657,10 @@ 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
+- ✅ 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.19 → soprano_sdk-0.2.21}/README.md

@@ -10,6 +10,11 @@ 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
+- **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
 
@@ -227,6 +232,247 @@ 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  # Disabled by default, set to true to enable
+  scope_description: "collecting order information for returns"  # Optional
+```
+
+**Response format:**
+```
+__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:
@@ -370,6 +616,10 @@ 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
+- ✅ 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