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

{soprano_sdk-0.2.19.dist-info → soprano_sdk-0.2.21.dist-info}/METADATA

@@ -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.dist-info → soprano_sdk-0.2.21.dist-info}/RECORD

@@ -1,25 +1,26 @@
 soprano_sdk/__init__.py,sha256=YZVl_SwQ0C-E_5_f1AwUe_hPcbgCt8k7k4_WAHM8vjE,243
 soprano_sdk/engine.py,sha256=EFK91iTHjp72otLN6Kg-yeLye2J3CAKN0QH4FI2taL8,14838
-soprano_sdk/tools.py,sha256=dmJ0OZ7Bj3rvjBQvLzgWlYRFVtNJOyMO2jLqaS13cAc,10971
+soprano_sdk/tools.py,sha256=D2EGT513OGjAA5h0RSy79OA34jgM30S8d49AG4JdL4M,13653
 soprano_sdk/agents/__init__.py,sha256=Yzbtv6iP_ABRgZo0IUjy9vDofEvLFbOjuABw758176A,636
 soprano_sdk/agents/adaptor.py,sha256=5y9e2F_ZILOPrkunvv0GhjVdniAnOOTaD4j3Ig-xd3c,5041
 soprano_sdk/agents/factory.py,sha256=CvXhpvtjf_Hb4Ce8WKAa0FzyY5Jm6lssvIIfSXu7jPY,9788
-soprano_sdk/agents/structured_output.py,sha256=7DSVzfMPsZAqBwI3v6XL15qG5Gh4jJ-qddcVPaa3gdc,3326
+soprano_sdk/agents/structured_output.py,sha256=VnSRmgarbgsozQSdCr9fVSjclwi04GJ6Nz5lut9qiUk,3593
 soprano_sdk/authenticators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soprano_sdk/authenticators/mfa.py,sha256=xnur1lxbx4r_pUaNPD8vtQiNccQTjbPnqgi_vqdRZaQ,7336
 soprano_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-soprano_sdk/core/constants.py,sha256=UPXlRbF7gsOUNOV0Lm0jvgFfgZX7JrsV6n9I5csMfns,3508
-soprano_sdk/core/engine.py,sha256=HKYoqwDm541pWSWwEKHxLlL3PX90Ux_5l_-HqihgL-g,12245
+soprano_sdk/core/constants.py,sha256=gByXYM7Lz7I7Sm2-tnn8alpaxuyuU_jfBmCpkigJHy4,4973
+soprano_sdk/core/engine.py,sha256=VvqV4N6mDKHmsw8NBXkegyWdwWOivjQVe1R2nv3zBTw,19704
 soprano_sdk/core/rollback_strategies.py,sha256=NjDTtBCZlqyDql5PSwI9SMDLK7_BNlTxbW_cq_5gV0g,7783
-soprano_sdk/core/state.py,sha256=k8ojLfWgjES3p9XWMeGU5s4UK-Xa5T8mS4VtZzTrcDw,2961
+soprano_sdk/core/state.py,sha256=BZWL5W9zecjNe-IFg_4zv0lSLPqRST67mN01Zi8H2mk,2976
 soprano_sdk/nodes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soprano_sdk/nodes/async_function.py,sha256=v6WujLKm8NXX2iAkJ7Gz_QIVCtWFrpC6nnPyyfuCxXs,9354
-soprano_sdk/nodes/base.py,sha256=idFyOGGPnjsASYnrOF_NIh7eFcSuJqw61EoVN_WCTaU,2360
+soprano_sdk/nodes/base.py,sha256=gjgAe5dqNk5ItOETLhwF6is7l9BJtrAouLXFOiDKA3E,2601
 soprano_sdk/nodes/call_function.py,sha256=afYBmj5Aditbkvb_7gD3CsXBEEUohcsC1_cdHfcOunE,5847
-soprano_sdk/nodes/collect_input.py,sha256=PySlghXOWDl6AYKgimY_7BnVFN7odYG656aBK_z4ACE,24617
-soprano_sdk/nodes/factory.py,sha256=IbBzT4FKBnYw5PuSo7uDONV3HSFtoyqjBQQtXtUY2IY,1756
+soprano_sdk/nodes/collect_input.py,sha256=h4fLJPvLPRz2k6l-KfyeJLOwWAr3ALjtzyRWmJgAyiQ,28021
+soprano_sdk/nodes/factory.py,sha256=i37whA0ugMSwbmWk6H798Suhq6J108a5VenuFqxCVu8,1863
+soprano_sdk/nodes/follow_up.py,sha256=iVCKCCuqgU-kkLBi4iYBa_bB7j5QI8U2KNGHpgYPmRA,14165
 soprano_sdk/routing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-soprano_sdk/routing/router.py,sha256=Z218r4BMbmlL9282ombutAoKsIs1WHZ2d5YHnbCeet8,3698
+soprano_sdk/routing/router.py,sha256=ECZn7NIVrVQ5l5eZr8sfVNT0MShixnQEsqh4YO6XwRs,3882
 soprano_sdk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 soprano_sdk/utils/function.py,sha256=yqkY4MlHOenv-Q3NciiovK1lamyrGQljpy6Q41wviy8,1216
 soprano_sdk/utils/logger.py,sha256=hMYaNHt5syGOXRkglTUKzkgfSbWerix_pHQntcYyep8,157
@@ -27,9 +28,9 @@ soprano_sdk/utils/template.py,sha256=MG_B9TMx1ShpnSGo7s7TO-VfQzuFByuRNhJTvZ668kM
 soprano_sdk/utils/tool.py,sha256=hWN826HIKmLdswLCTURLH8hWlb2WU0MB8nIUErbpB-8,1877
 soprano_sdk/utils/tracing.py,sha256=gSHeBDLe-MbAZ9rkzpCoGFveeMdR9KLaA6tteB0IWjk,1991
 soprano_sdk/validation/__init__.py,sha256=ImChmO86jYHU90xzTttto2-LmOUOmvY_ibOQaLRz5BA,262
-soprano_sdk/validation/schema.py,sha256=eRGXXMDlJyaH0XYMOXY1azvJlJwOdbHFrHjB1yuGROg,15434
+soprano_sdk/validation/schema.py,sha256=NGnxP3TKcB-cylVcdOkxYhTPBbHnbmKTG_EamfA1VdY,17682
 soprano_sdk/validation/validator.py,sha256=f-e2MMRL70asOIXr_0Fsd5CgGKVRiQp7AaYsHA45Km0,8792
-soprano_sdk-0.2.19.dist-info/METADATA,sha256=TZNLyUlHQBsw6aXwsmhz2-V5ThgE1cPNuPyhL1zeRDM,11374
-soprano_sdk-0.2.19.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-soprano_sdk-0.2.19.dist-info/licenses/LICENSE,sha256=A1aBauSjPNtVehOXJe3WuvdU2xvM9H8XmigFMm6665s,1073
-soprano_sdk-0.2.19.dist-info/RECORD,,
+soprano_sdk-0.2.21.dist-info/METADATA,sha256=YalPq6Je3QAYK_JW5cJrDnVkF9iBgqYcctM93OZXMaE,20410
+soprano_sdk-0.2.21.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+soprano_sdk-0.2.21.dist-info/licenses/LICENSE,sha256=A1aBauSjPNtVehOXJe3WuvdU2xvM9H8XmigFMm6665s,1073
+soprano_sdk-0.2.21.dist-info/RECORD,,