soprano-sdk 0.2.12__tar.gz → 0.2.14__tar.gz

{soprano_sdk-0.2.12 → soprano_sdk-0.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soprano-sdk
-Version: 0.2.12
+Version: 0.2.14
 Summary: YAML-driven workflow engine with AI agent integration for building conversational SOPs
 Author: Arvind Thangamani
 License: MIT
@@ -21,6 +21,7 @@ Requires-Dist: langchain-openai>=1.0.3
 Requires-Dist: langchain>=1.0.7
 Requires-Dist: langfuse>=3.10.1
 Requires-Dist: langgraph==1.0.2
+Requires-Dist: litellm>=1.81.1
 Requires-Dist: openai>=1.92.1
 Requires-Dist: pydantic-ai>=1.22.0
 Requires-Dist: pydantic>=2.0.0

{soprano_sdk-0.2.12 → soprano_sdk-0.2.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "soprano-sdk"
-version = "0.2.12"
+version = "0.2.14"
 description = "YAML-driven workflow engine with AI agent integration for building conversational SOPs"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -30,6 +30,7 @@ dependencies = [
     "langchain-openai>=1.0.3",
     "langfuse>=3.10.1",
     "langgraph==1.0.2",
+    "litellm>=1.81.1",
     "openai>=1.92.1",
     "pydantic>=2.0.0",
     "pydantic-ai>=1.22.0",

{soprano_sdk-0.2.12 → soprano_sdk-0.2.14}/soprano_sdk/agents/adaptor.py

@@ -53,6 +53,9 @@ class CrewAIAgentAdapter(AgentAdapter):
             if agent_response := getattr(result, 'raw', None) :
                 return agent_response
             
+            if isinstance(agent_response, dict):
+                return agent_response
+            
             return str(result)
         except Exception as e:
             raise RuntimeError(f"CrewAI agent invocation failed: {e}")

{soprano_sdk-0.2.12 → soprano_sdk-0.2.14}/soprano_sdk/core/engine.py

@@ -56,7 +56,8 @@ class WorkflowEngine:
 
             logger.info(
                 f"Workflow loaded: {self.workflow_name} v{self.workflow_version} "
-                f"({len(self.steps)} steps, {len(self.outcomes)} outcomes)"
+                f"({len(self.steps)} steps, {len(self.outcomes)} outcomes, "
+                f"{len(self.collector_node_field_map)} collector nodes)"
             )
 
         except Exception as e:
@@ -202,6 +203,7 @@ class WorkflowEngine:
     def load_steps(self):
         prepared_steps: list = []
         mfa_redirects: Dict[str, str] = {}
+        self.collector_node_field_map: Dict[str, str] = {}  # Map of node_id -> field
 
         for step in self.config['steps']:
             step_id = step['id']
@@ -228,6 +230,14 @@ class WorkflowEngine:
 
             prepared_steps.append(step)
 
+        # Build collector node -> field map
+        for step in prepared_steps:
+            if step.get('action') == 'collect_input':
+                node_id = step.get('id')
+                field = step.get('field')
+                if node_id and field:
+                    self.collector_node_field_map[node_id] = field
+
         for step in prepared_steps:
             if step['id'] in self.mfa_validator_steps: # MFA Validator
                 continue

{soprano_sdk-0.2.12 → soprano_sdk-0.2.14}/soprano_sdk/nodes/collect_input.py

@@ -196,17 +196,6 @@ class CollectInputStrategy(ActionStrategy):
         if context_value is None:
             return
 
-        # Check if this node has already executed - if so, don't overwrite the collected value
-        execution_order = state.get(WorkflowKeys.NODE_EXECUTION_ORDER, [])
-        if self.step_id in execution_order:
-            logger.info(f"Skipping context value for '{self.field}' - node '{self.step_id}' already executed")
-            span.add_event("context.value_skipped", {
-                "field": self.field,
-                "reason": "node_already_executed",
-                "existing_value": str(state.get(self.field))
-            })
-            return
-
         logger.info(f"Using context value for '{self.field}': {context_value}")
         state[self.field] = context_value
         span.add_event("context.value_used", {"field": self.field, "value": str(context_value)})
@@ -505,7 +494,7 @@ class CollectInputStrategy(ActionStrategy):
     def _handle_structured_output_transition(self, state: Dict[str, Any], conversation: List, agent_response: Any) -> Dict[str, Any]:
 
         try:
-            agent_response = json.loads(agent_response)
+            agent_response = json.loads(agent_response) if isinstance(agent_response, str) else agent_response
         except (json.JSONDecodeError, TypeError, ValueError):
             pass
 

{soprano_sdk-0.2.12 → soprano_sdk-0.2.14}/soprano_sdk/tools.py

@@ -83,26 +83,35 @@ class WorkflowTool:
             callback_handler = CallbackHandler()
             config = {"configurable": {"thread_id": thread_id}, "callbacks": [callback_handler]}
 
-            span.add_event("context.updated", {"fields": list(initial_context.keys())})
-
             state = self.graph.get_state(config)
 
-            # Update engine context on both resume and fresh start
-            # Note: collect_input nodes will check NODE_EXECUTION_ORDER to avoid
-            # overwriting already-collected values
-            self.engine.update_context(initial_context)
-
+            # Intelligently update context based on workflow state
             if state.next:
+                # Workflow is resuming - only update fields that haven't been collected yet
                 span.set_attribute("workflow.resumed", True)
                 logger.info(f"[WorkflowTool] Resuming interrupted workflow {self.name} (thread: {thread_id})")
+
+                filtered_context = self._filter_already_collected_fields(state.values, initial_context)
+                self.engine.update_context(filtered_context)
+
+                span.add_event("context.updated", {
+                    "fields": list(filtered_context.keys()),
+                    "filtered_out": list(set(initial_context.keys()) - set(filtered_context.keys()))
+                })
+
                 result = self.graph.invoke(
-                    Command(resume=user_message or "", update=initial_context),
+                    Command(resume=user_message or "", update=filtered_context),
                     config=config
                 )
 
             else:
+                # Fresh start - update all fields from initial_context
                 span.set_attribute("workflow.resumed", False)
                 logger.info(f"[WorkflowTool] Starting fresh workflow {self.name} (thread: {thread_id})")
+
+                self.engine.update_context(initial_context)
+                span.add_event("context.updated", {"fields": list(initial_context.keys())})
+
                 result = self.graph.invoke(initial_context, config=config)
             
             final_state = self.graph.get_state(config)
@@ -129,6 +138,51 @@ class WorkflowTool:
             span.set_attribute("workflow.status", "completed")
             return self.engine.get_outcome_message(result)
 
+    def _filter_already_collected_fields(
+        self,
+        current_state: Dict[str, Any],
+        initial_context: Optional[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """
+        Filter initial_context to exclude fields that have already been collected.
+
+        Args:
+            current_state: Current workflow state
+            initial_context: Context to filter
+
+        Returns:
+            Filtered context with only uncollected fields
+        """
+        if not initial_context:
+            return {}
+
+        from .core.constants import WorkflowKeys
+
+        execution_order = current_state.get(WorkflowKeys.NODE_EXECUTION_ORDER, [])
+
+        node_to_field_map = self.engine.collector_node_field_map
+
+        # Determine which fields have already been collected
+        collected_fields = set()
+        for executed_node_id in execution_order:
+            if executed_node_id in node_to_field_map:
+                collected_fields.add(node_to_field_map[executed_node_id])
+
+        # Filter initial_context to exclude already-collected fields
+        filtered_context = {
+            field: value
+            for field, value in initial_context.items()
+            if field not in collected_fields
+        }
+
+        if collected_fields:
+            logger.info(
+                f"[WorkflowTool] Filtered out already-collected fields: {collected_fields}. "
+                f"Updating context with: {list(filtered_context.keys())}"
+            )
+
+        return filtered_context
+
     def resume(
         self,
         thread_id: str,

{soprano_sdk-0.2.12 → soprano_sdk-0.2.14}/tests/test_collect_input_refactor.py

@@ -184,42 +184,8 @@ class TestCollectInputStrategyRefactor:
         assert conversation[0]["role"] == "assistant"
         assert conversation[0]["content"] == "Hello! What's your name?"
 
-    def test_context_value_not_overwritten_when_node_already_executed(self):
-        """Test that context values don't overwrite already-collected field values on resume"""
-        step_config = {
-            "id": "collect_customer_id",
-            "field": "customer_id",
-            "agent": {"name": "test_agent"}
-        }
-        engine_context = MagicMock()
-        engine_context.get_config_value.return_value = "history_based"
-        # Mock context value (from initial_context on resume)
-        engine_context.get_context_value.return_value = "CTX_12345"
-
-        strategy = CollectInputStrategy(step_config, engine_context)
-
-        # Simulate state where this node has already executed and collected a value
-        state = {
-            "customer_id": "COLLECTED_67890",  # Already collected value
-            WorkflowKeys.NODE_EXECUTION_ORDER: ["collect_customer_id"]  # Node already executed
-        }
-
-        span = MagicMock()
-
-        # Call _apply_context_value
-        strategy._apply_context_value(state, span)
-
-        # Verify the collected value was NOT overwritten
-        assert state["customer_id"] == "COLLECTED_67890"
-        # Verify the context.value_skipped event was logged
-        span.add_event.assert_called_once()
-        event_call = span.add_event.call_args
-        assert event_call[0][0] == "context.value_skipped"
-        assert event_call[0][1]["field"] == "customer_id"
-        assert event_call[0][1]["reason"] == "node_already_executed"
-
-    def test_context_value_applied_when_node_not_yet_executed(self):
-        """Test that context values ARE applied when node hasn't executed yet"""
+    def test_context_value_applied_from_engine_context(self):
+        """Test that context values are applied from engine context"""
         step_config = {
             "id": "collect_customer_id",
             "field": "customer_id",
@@ -232,10 +198,8 @@ class TestCollectInputStrategyRefactor:
 
         strategy = CollectInputStrategy(step_config, engine_context)
 
-        # Simulate state where this node has NOT executed yet
-        state = {
-            WorkflowKeys.NODE_EXECUTION_ORDER: []  # Empty - node not executed
-        }
+        # Simulate state
+        state = {}
 
         span = MagicMock()
 

soprano_sdk-0.2.12/examples/ASYNC_FUNCTIONS_README.md

@@ -1,414 +0,0 @@
-# Async Function Examples - Complete Guide
-
-This directory contains complete examples of how to use `call_async_function` with the interrupt/resume pattern in Soprano SDK workflows.
-
-## Files
-
-- **`payment_async_workflow.yaml`** - Complete workflow YAML demonstrating async functions
-- **`payment_async_functions.py`** - Python implementation of async functions
-- **`test_payment_async.py`** - Comprehensive test examples
-- **`ASYNC_FUNCTIONS_README.md`** - This file
-
-## What is an Async Function?
-
-An async function allows your workflow to pause while waiting for an external system to complete processing. This is useful for:
-
-- **Payment verification** - Wait for payment gateway to verify
-- **Identity verification** - Wait for KYC/identity checks
-- **Background jobs** - Wait for long-running computations
-- **External APIs** - Wait for third-party service responses
-- **Manual approvals** - Wait for human review
-
-## How It Works
-
-### Two-Phase Execution Pattern
-
-#### Phase 1: Initial Call (Interrupt)
-```python
-def verify_payment(state: Dict[str, Any]) -> Dict[str, Any]:
-    # Initiate async operation
-    job_id = start_external_verification(state["payment_amount"])
-
-    # Return "pending" to pause workflow
-    return {
-        "status": "pending",
-        "job_id": job_id,
-        "webhook_url": f"https://api.example.com/webhook/{job_id}",
-        "estimated_time": "5-10 seconds"
-    }
-```
-
-When you return `{"status": "pending", ...}`:
-1. Workflow calls `interrupt()` with the pending metadata
-2. Workflow pauses execution
-3. External system processes asynchronously
-4. Workflow state is persisted
-
-#### Phase 2: Resume (Complete)
-```python
-# External system completes and calls your webhook
-@app.post("/webhook/payment/{job_id}")
-async def payment_webhook(job_id: str, result: Dict):
-    # Get workflow config for this job
-    config = get_workflow_config(job_id)
-
-    # Resume workflow with result
-    graph.update_state(config, Command(resume=result))
-```
-
-When you resume with `Command(resume=result)`:
-1. The `interrupt()` call returns with `result`
-2. Result is stored in the `output` field
-3. Workflow evaluates `transitions` based on result
-4. Workflow continues to next step
-
-## Quick Start
-
-### 1. Define in Workflow YAML
-
-```yaml
-steps:
-  - id: verify_payment
-    action: call_async_function
-    function: "payment_async_functions.verify_payment"
-    output: verification_result
-    transitions:
-      - condition: "verified"
-        ref: "status"
-        next: approved
-      - condition: "rejected"
-        ref: "status"
-        next: rejected
-```
-
-### 2. Implement Async Function
-
-```python
-def verify_payment(state: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Returns pending status to pause workflow.
-    External system will later resume with final result.
-    """
-    payment_amount = state.get("payment_amount")
-    job_id = f"pay_{uuid.uuid4().hex[:8]}"
-
-    # Call external API to start verification
-    payment_gateway.verify_async(
-        amount=payment_amount,
-        callback_url=f"https://your-api.com/webhook/{job_id}"
-    )
-
-    # Return pending to interrupt workflow
-    return {
-        "status": "pending",
-        "job_id": job_id,
-        "webhook_url": f"https://your-api.com/webhook/{job_id}"
-    }
-```
-
-### 3. Create Webhook Handler
-
-```python
-from langgraph.types import Command
-
-@app.post("/webhook/payment/{job_id}")
-async def payment_webhook(job_id: str, result: Dict):
-    """
-    Receives callback from external payment gateway.
-    Resumes the workflow with the result.
-    """
-    # Retrieve workflow config from database
-    config = db.get_workflow_config(job_id)
-
-    # Resume workflow with result
-    # The result will be:
-    # 1. Returned by interrupt()
-    # 2. Stored in the output field
-    # 3. Used for transition routing
-    graph.update_state(config, Command(resume=result))
-
-    return {"status": "resumed"}
-```
-
-## Checking Pending Status
-
-### Method 1: Check Function Return Value
-```python
-result = verify_payment(state)
-
-# Check if function wants to pause
-if result.get("status") == "pending":
-    print("Function is pending")
-    print(f"Job ID: {result['job_id']}")
-    print(f"Webhook: {result['webhook_url']}")
-```
-
-### Method 2: Check Workflow State
-```python
-# After workflow execution
-if state[WorkflowKeys.STATUS] == f"{step_id}_pending":
-    print("Workflow is pending")
-
-# Or use the strategy method
-if strategy._is_async_pending(state):
-    print("Async operation is pending")
-```
-
-### Method 3: Check Stored Pending Metadata
-```python
-# Pending metadata is stored in state
-pending_key = f"_async_pending_{step_id}"
-if pending_key in state:
-    metadata = state[pending_key]
-    print(f"Pending: {metadata}")
-```
-
-## Accessing Interrupt and Resume Data
-
-### Accessing the Three Interrupt Values
-
-When `interrupt()` is called, it receives:
-```python
-{
-    "type": "async",           # Always "async" for async functions
-    "step_id": "verify_payment", # The step ID
-    "pending": {                # Metadata from your function
-        "status": "pending",
-        "job_id": "pay_123",
-        "webhook_url": "...",
-        # ... any other data you returned
-    }
-}
-```
-
-Access these values:
-```python
-# During workflow execution
-with patch('soprano_sdk.nodes.async_function.interrupt') as mock_interrupt:
-    strategy.execute(state)
-
-    interrupt_args = mock_interrupt.call_args[0][0]
-
-    print(interrupt_args["type"])      # "async"
-    print(interrupt_args["step_id"])   # "verify_payment"
-    print(interrupt_args["pending"])   # Your pending metadata
-```
-
-### Accessing Resume Data
-
-When you resume with `Command(resume=result)`, the result is:
-1. Returned by the `interrupt()` call
-2. Stored in the `output` field
-3. Used for transition routing
-
-```python
-# Resume with this data
-async_result = {
-    "job_id": "pay_123",
-    "status": "verified",
-    "verification_id": "VRF_789",
-    "amount_verified": 100.00,
-    "verified_at": "2026-01-12T10:30:00Z"
-}
-
-graph.update_state(config, Command(resume=async_result))
-
-# After resume, access via output field
-verification_result = state["verification_result"]
-print(verification_result["status"])           # "verified"
-print(verification_result["verification_id"])  # "VRF_789"
-print(verification_result["amount_verified"]) # 100.00
-```
-
-### Accessing Nested Resume Data with 'ref'
-
-Use `ref` in transitions to check nested fields:
-```yaml
-transitions:
-  - condition: "approved"
-    ref: "result.status"  # Checks nested field
-    next: success
-```
-
-Access nested data:
-```python
-async_result = {
-    "result": {
-        "status": "approved",
-        "verification": {
-            "score": 95,
-            "details": "All checks passed"
-        }
-    }
-}
-
-# After resume
-result = state["verification_data"]
-print(result["result"]["status"])                    # "approved"
-print(result["result"]["verification"]["score"])     # 95
-print(result["result"]["verification"]["details"])   # "All checks passed"
-```
-
-## Complete Example: Two-Phase Execution
-
-### Phase 1: Initial Call
-```python
-# Execute workflow
-state = {"payment_amount": 100.00}
-result = workflow.execute(state)
-
-# Workflow interrupts with pending
-print(state[WorkflowKeys.STATUS])  # "verify_payment_pending"
-print(state["_async_pending_verify_payment"])  # Pending metadata
-```
-
-### External Processing
-```python
-# External payment gateway processes
-# (This happens outside your workflow)
-time.sleep(5)  # Simulate processing
-payment_gateway.verify(job_id="pay_123")
-```
-
-### Phase 2: Resume
-```python
-# Payment gateway calls your webhook
-result = {
-    "status": "verified",
-    "verification_id": "VRF_789",
-    "amount_verified": 100.00
-}
-
-# Resume workflow
-graph.update_state(config, Command(resume=result))
-
-# Workflow completes
-print(state[WorkflowKeys.STATUS])        # "verify_payment_approved"
-print(state["verification_result"])      # Full result data
-```
-
-## Synchronous Completion (No Pending)
-
-If your function can complete immediately, just return the result directly:
-
-```python
-def verify_payment_sync(state: Dict[str, Any]) -> Dict[str, Any]:
-    """Completes immediately without pending."""
-    return {
-        "status": "verified",
-        "verification_id": "VRF_INSTANT",
-        "amount_verified": state["payment_amount"]
-    }
-```
-
-When you DON'T return `{"status": "pending"}`:
-- No workflow interrupt
-- Result immediately available
-- Transitions evaluated right away
-- Workflow continues to next step
-
-## Running the Examples
-
-### 1. View Function Implementation
-```bash
-cat examples/payment_async_functions.py
-```
-
-### 2. Run Demo Script
-```bash
-python3 examples/payment_async_functions.py
-```
-
-### 3. Run Tests (requires dependencies)
-```bash
-cd ..
-python -m pytest tests/test_async_function.py -v
-```
-
-### 4. Run Test Examples
-```bash
-python3 examples/test_payment_async.py
-```
-
-## Key Concepts Summary
-
-| Concept | Description |
-|---------|-------------|
-| **Pending Status** | Return `{"status": "pending", ...}` to pause workflow |
-| **Interrupt** | Workflow calls `interrupt()` with pending metadata |
-| **Resume** | Call `Command(resume=result)` to continue workflow |
-| **Output Field** | Resume result is stored in the configured output field |
-| **Transitions** | Use result fields to route to next step |
-| **State Keys** | Pending data stored at `_async_pending_{step_id}` |
-| **Status Key** | Workflow status becomes `{step_id}_pending` |
-
-## Common Patterns
-
-### Pattern 1: External API Call
-```python
-def call_external_api(state):
-    job_id = external_api.start_job(state["data"])
-    return {"status": "pending", "job_id": job_id}
-```
-
-### Pattern 2: Manual Review
-```python
-def request_manual_review(state):
-    review_id = create_review_task(state)
-    return {
-        "status": "pending",
-        "review_id": review_id,
-        "webhook_url": f"/webhook/review/{review_id}"
-    }
-```
-
-### Pattern 3: Polling (Not Recommended)
-```python
-# DON'T DO THIS - Use webhooks instead
-def check_status(state):
-    if job_complete(state["job_id"]):
-        return {"status": "complete"}
-    return {"status": "pending"}  # Will keep checking
-```
-
-## Best Practices
-
-1. **Always use webhooks** - Don't poll for completion
-2. **Include job_id** - Track operations across systems
-3. **Store webhook URL** - Document where to send results
-4. **Add timeout handling** - What if webhook never arrives?
-5. **Include error cases** - Handle failures in transitions
-6. **Log everything** - Track async operation lifecycle
-7. **Persist state** - Use workflow persistence for reliability
-
-## Troubleshooting
-
-### Workflow Not Resuming
-- Verify webhook URL is correct
-- Check external system is calling webhook
-- Confirm `Command(resume=result)` is being called
-- Verify config matches original workflow
-
-### Wrong Transition
-- Check `ref` field matches result structure
-- Verify `condition` matches exact value
-- Use nested refs for complex data: `ref: "result.status"`
-
-### Missing Data
-- Confirm resume result includes all needed fields
-- Check output field name matches workflow YAML
-- Verify data structure matches expectations
-
-## Additional Resources
-
-- Main async function implementation: `soprano_sdk/nodes/async_function.py`
-- Workflow engine: `soprano_sdk/core/engine.py`
-- Test suite: `tests/test_async_function.py`
-- LangGraph Command docs: https://langchain-ai.github.io/langgraph/
-
-## Need Help?
-
-Check the test files for comprehensive examples:
-- `tests/test_async_function.py` - Unit tests
-- `examples/test_payment_async.py` - Practical examples
-- `examples/payment_async_functions.py` - Implementation patterns