soprano-sdk 0.2.7__tar.gz → 0.2.9__tar.gz

{soprano_sdk-0.2.7 → soprano_sdk-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soprano-sdk
-Version: 0.2.7
+Version: 0.2.9
 Summary: YAML-driven workflow engine with AI agent integration for building conversational SOPs
 Author: Arvind Thangamani
 License: MIT

soprano_sdk-0.2.9/examples/ASYNC_FUNCTIONS_README.md

@@ -0,0 +1,414 @@
+# 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