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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soprano-sdk
-Version: 0.2.18
+Version: 0.2.20
 Summary: YAML-driven workflow engine with AI agent integration for building conversational SOPs
 Author: Arvind Thangamani
 License: MIT
@@ -51,6 +51,9 @@ 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
 
 ## Installation
 
@@ -268,6 +271,108 @@ 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  # Enabled by default
+  scope_description: "collecting order information for returns"  # Optional
+```
+
+**Response format:**
+```
+__OUT_OF_SCOPE_INTERRUPT__|{thread_id}|{workflow_name}|{"reason":"...","user_message":"..."}
+```
+
 ## Examples
 
 See the `examples/` directory for complete workflow examples:
@@ -411,6 +516,8 @@ 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
 - Additional action types (webhook, conditional branching, parallel execution)
 - More workflow examples (customer onboarding, support ticketing, approval flows)
 - Workflow testing utilities

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

@@ -10,6 +10,9 @@ 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
 
 ## Installation
 
@@ -227,6 +230,108 @@ 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  # Enabled by default
+  scope_description: "collecting order information for returns"  # Optional
+```
+
+**Response format:**
+```
+__OUT_OF_SCOPE_INTERRUPT__|{thread_id}|{workflow_name}|{"reason":"...","user_message":"..."}
+```
+
 ## Examples
 
 See the `examples/` directory for complete workflow examples:
@@ -370,6 +475,8 @@ 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
 - 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/docs/framework_flow_diagrams.md

@@ -0,0 +1,430 @@
+# Soprano SDK Framework Flow Diagrams
+
+## 1. High-Level Architecture
+
+```mermaid
+graph TB
+    subgraph "Entry Layer"
+        WT[WorkflowTool]
+        YML[YAML Workflow Definition]
+    end
+
+    subgraph "Engine Layer"
+        WE[WorkflowEngine]
+        FR[FunctionRepository]
+        TR[ToolRepository]
+        CS[ContextStore]
+    end
+
+    subgraph "Graph Layer"
+        SG[LangGraph StateGraph]
+        CP[Checkpointer]
+        WR[WorkflowRouter]
+    end
+
+    subgraph "Node Execution Layer"
+        NF[NodeFactory]
+        CIS[CollectInputStrategy]
+        CFS[CallFunctionStrategy]
+        AFS[AsyncFunctionStrategy]
+    end
+
+    subgraph "Agent Layer"
+        AF[AgentFactory]
+        LA[LangGraph Adapter]
+        CA[CrewAI Adapter]
+        AA[Agno Adapter]
+        PA[PydanticAI Adapter]
+    end
+
+    YML --> WE
+    WT --> WE
+    WE --> FR
+    WE --> TR
+    WE --> CS
+    WE --> SG
+    SG --> CP
+    SG --> WR
+    WR --> NF
+    NF --> CIS
+    NF --> CFS
+    NF --> AFS
+    CIS --> AF
+    AF --> LA
+    AF --> CA
+    AF --> AA
+    AF --> PA
+```
+
+## 2. Workflow Execution Flow
+
+```mermaid
+flowchart TD
+    START([Start]) --> CHECK{Check State}
+
+    CHECK -->|Fresh Start| INIT[Initialize State<br/>with initial_context]
+    CHECK -->|Resuming| FILTER[Filter Already<br/>Collected Fields]
+
+    INIT --> INVOKE[graph.invoke<br/>initial_context]
+    FILTER --> RESUME[graph.invoke<br/>Command resume=value]
+
+    INVOKE --> RESULT{Check Result}
+    RESUME --> RESULT
+
+    RESULT -->|Has __interrupt__| PARSE[Parse Interrupt Value]
+    RESULT -->|No Interrupt| COMPLETE[Get Outcome Message]
+
+    PARSE --> INT_TYPE{Interrupt Type?}
+
+    INT_TYPE -->|USER_INPUT| UI_INT["__WORKFLOW_INTERRUPT__|<br/>thread_id|workflow|prompt"]
+    INT_TYPE -->|ASYNC| ASYNC_INT["__ASYNC_INTERRUPT__|<br/>thread_id|workflow|metadata"]
+    INT_TYPE -->|OUT_OF_SCOPE| OOS_INT["__OUT_OF_SCOPE_INTERRUPT__|<br/>thread_id|workflow|payload"]
+
+    UI_INT --> RETURN_INT[Return to Caller]
+    ASYNC_INT --> RETURN_INT
+    OOS_INT --> RETURN_INT
+    COMPLETE --> END_SUCCESS([Workflow Complete])
+
+    RETURN_INT --> WAIT[Wait for Resume]
+    WAIT --> CHECK
+```
+
+## 3. Node Execution Flow (CollectInputStrategy)
+
+```mermaid
+flowchart TD
+    NODE_START([Node Invoked]) --> INIT_STATE[Initialize State]
+    INIT_STATE --> CTX[Apply Context Values]
+
+    CTX --> PRE_POP{Field<br/>Pre-populated?}
+    PRE_POP -->|Yes| VALIDATE_PRE[Validate & Route]
+    PRE_POP -->|No| MAX_ATT{Max Attempts<br/>Reached?}
+
+    MAX_ATT -->|Yes| MAX_FAIL[Set max_attempts status<br/>Return error message]
+    MAX_ATT -->|No| CREATE_AGENT[Create Agent<br/>with Instructions]
+
+    CREATE_AGENT --> ENHANCE[Enhance Instructions:<br/>+ Intent Detection<br/>+ Out-of-Scope Detection]
+
+    ENHANCE --> GEN_PROMPT[Generate Prompt]
+    GEN_PROMPT --> INTERRUPT_UI[/"INTERRUPT<br/>(USER_INPUT)"/]
+
+    INTERRUPT_UI --> GET_INPUT[Get User Input]
+    GET_INPUT --> ADD_CONV[Add to Conversation]
+    ADD_CONV --> INVOKE_AGENT[Invoke Agent]
+
+    INVOKE_AGENT --> STRUCT{Structured<br/>Output?}
+
+    STRUCT -->|Yes| PARSE_STRUCT[Parse JSON Response]
+    STRUCT -->|No| CHECK_PATTERN[Check Response Pattern]
+
+    PARSE_STRUCT --> OOS_CHECK{out_of_scope<br/>set?}
+    OOS_CHECK -->|Yes| OOS_HANDLE[/"INTERRUPT<br/>(OUT_OF_SCOPE)"/]
+    OOS_CHECK -->|No| INTENT_CHECK{intent_change<br/>set?}
+
+    INTENT_CHECK -->|Yes| ROLLBACK[Rollback to<br/>Target Node]
+    INTENT_CHECK -->|No| BOT_RESP{bot_response<br/>set?}
+
+    BOT_RESP -->|Yes| SELF_LOOP[Add to conversation<br/>Self-loop]
+    BOT_RESP -->|No| MATCH_TRANS[Match Transitions]
+
+    CHECK_PATTERN --> OOS_PAT{Starts with<br/>OUT_OF_SCOPE:?}
+    OOS_PAT -->|Yes| OOS_HANDLE
+    OOS_PAT -->|No| INTENT_PAT{Starts with<br/>INTENT_CHANGE:?}
+
+    INTENT_PAT -->|Yes| ROLLBACK
+    INTENT_PAT -->|No| MATCH_TRANS
+
+    MATCH_TRANS --> TRANS_FOUND{Transition<br/>Matched?}
+    TRANS_FOUND -->|Yes| VALIDATE[Validate Input]
+    TRANS_FOUND -->|No| SELF_LOOP
+
+    VALIDATE --> VALID{Valid?}
+    VALID -->|Yes| STORE[Store Value<br/>Set Status]
+    VALID -->|No| VAL_FAIL[Validation Error<br/>Self-loop]
+
+    STORE --> ROUTE[Route to Next Step]
+    VALIDATE_PRE --> ROUTE
+    MAX_FAIL --> NODE_END([Return State])
+    ROUTE --> NODE_END
+    SELF_LOOP --> NODE_END
+    VAL_FAIL --> NODE_END
+    ROLLBACK --> NODE_END
+```
+
+## 4. Async Function Node Flow
+
+```mermaid
+flowchart TD
+    ASYNC_START([AsyncFunction Node]) --> CHECK_PENDING{Status =<br/>pending?}
+
+    CHECK_PENDING -->|Yes| HAS_META{Has Pending<br/>Metadata?}
+    HAS_META -->|Yes| ASYNC_INT[/"INTERRUPT<br/>(ASYNC)"/]
+    HAS_META -->|No| CALL_FUNC[Call Async Function]
+
+    CHECK_PENDING -->|No| CALL_FUNC
+
+    CALL_FUNC --> RESULT{Result Status?}
+
+    RESULT -->|pending| STORE_META[Store Pending Metadata]
+    RESULT -->|completed| SYNC_COMPLETE[Handle Sync Completion]
+
+    STORE_META --> SET_PENDING[Set status = pending]
+    SET_PENDING --> ASYNC_INT
+
+    ASYNC_INT --> WAIT_RESUME[Wait for External Result]
+    WAIT_RESUME --> RESUME[Resume with Result]
+    RESUME --> CLEAN_META[Clean Pending Metadata]
+    CLEAN_META --> ROUTE_RESULT[Route Based on Result]
+
+    SYNC_COMPLETE --> STORE_RESULT[Store in Output Field]
+    STORE_RESULT --> ROUTE_RESULT
+
+    ROUTE_RESULT --> CHECK_TRANS{Match<br/>Transitions?}
+    CHECK_TRANS -->|Yes| NEXT_STEP[Route to Matched Step]
+    CHECK_TRANS -->|No| SIMPLE{Has next_step?}
+
+    SIMPLE -->|Yes| NEXT_SIMPLE[Route to next_step]
+    SIMPLE -->|No| ASYNC_END([END])
+
+    NEXT_STEP --> ASYNC_END
+    NEXT_SIMPLE --> ASYNC_END
+```
+
+## 5. Routing Logic
+
+```mermaid
+flowchart TD
+    ROUTE_START([Routing Decision]) --> GET_STATUS[Get _status from State]
+    GET_STATUS --> PARSE[Parse: step_id_suffix]
+
+    PARSE --> COLLECT{suffix =<br/>collecting?}
+    COLLECT -->|Yes| SELF_LOOP[Self-Loop to Same Node]
+    COLLECT -->|No| PENDING{suffix =<br/>pending?}
+
+    PENDING -->|Yes| SELF_LOOP
+    PENDING -->|No| ERROR{suffix =<br/>error?}
+
+    ERROR -->|Yes| GO_END[Route to END]
+    ERROR -->|No| MAX{suffix =<br/>max_attempts?}
+
+    MAX -->|Yes| GO_END
+    MAX -->|No| CHECK_STEP{suffix in<br/>step_map?}
+
+    CHECK_STEP -->|Yes| ROUTE_STEP[Route to Target Step]
+    CHECK_STEP -->|No| CHECK_OUT{suffix in<br/>outcome_map?}
+
+    CHECK_OUT -->|Yes| GO_END
+    CHECK_OUT -->|No| GO_END
+
+    SELF_LOOP --> ROUTE_END([Return Route Target])
+    GO_END --> ROUTE_END
+    ROUTE_STEP --> ROUTE_END
+```
+
+## 6. Intent Change & Rollback Flow
+
+```mermaid
+flowchart TD
+    INTENT_START([Intent Change Detected]) --> EXTRACT[Extract Target Node]
+    EXTRACT --> GET_STRATEGY[Get Rollback Strategy]
+
+    GET_STRATEGY --> STRAT_TYPE{Strategy Type?}
+
+    STRAT_TYPE -->|history_based| FIND_SNAP[Find Snapshot<br/>Before Target Node]
+    STRAT_TYPE -->|dependency_based| BUILD_DEPS[Build Dependency<br/>Graph]
+
+    FIND_SNAP --> RESTORE_SNAP[Restore State<br/>from Snapshot]
+    BUILD_DEPS --> CLEAR_DEPS[Clear Target Field<br/>& Dependents]
+
+    RESTORE_SNAP --> RESTORE_CTX[Restore Context Values]
+    CLEAR_DEPS --> RESTORE_CTX
+
+    RESTORE_CTX --> SET_STATUS[Set Status:<br/>step_id_target_node]
+    SET_STATUS --> INTENT_END([Return to<br/>Target Node])
+```
+
+## 7. Agent Creation Flow
+
+```mermaid
+flowchart TD
+    AGENT_START([Create Agent]) --> GET_MODEL[Get Model Config]
+    GET_MODEL --> LOAD_TOOLS[Load Tools from<br/>ToolRepository]
+
+    LOAD_TOOLS --> GET_COLLECTORS[Get Collector Nodes<br/>for Intent Detection]
+    GET_COLLECTORS --> RENDER_INST[Render Instructions<br/>with Jinja2]
+
+    RENDER_INST --> HAS_COLLECTORS{Has Other<br/>Collectors?}
+    HAS_COLLECTORS -->|Yes| ADD_INTENT[Add Intent<br/>Detection Instructions]
+    HAS_COLLECTORS -->|No| CHECK_OOS{Out-of-Scope<br/>Enabled?}
+
+    ADD_INTENT --> CHECK_OOS
+
+    CHECK_OOS -->|Yes| ADD_OOS[Add Out-of-Scope<br/>Detection Instructions]
+    CHECK_OOS -->|No| CREATE_STRUCT{Structured<br/>Output?}
+
+    ADD_OOS --> CREATE_STRUCT
+
+    CREATE_STRUCT -->|Yes| BUILD_MODEL[Build Pydantic Model<br/>with bot_response,<br/>intent_change, out_of_scope]
+    CREATE_STRUCT -->|No| FACTORY[AgentFactory.create_agent]
+
+    BUILD_MODEL --> FACTORY
+
+    FACTORY --> FRAMEWORK{Framework?}
+
+    FRAMEWORK -->|langgraph| LG[LangGraphAgentAdapter]
+    FRAMEWORK -->|crewai| CR[CrewAIAgentAdapter]
+    FRAMEWORK -->|agno| AG[AgnoAgentAdapter]
+    FRAMEWORK -->|pydantic_ai| PA[PydanticAIAgentAdapter]
+
+    LG --> AGENT_END([Return Adapter])
+    CR --> AGENT_END
+    AG --> AGENT_END
+    PA --> AGENT_END
+```
+
+## 8. Complete Workflow Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant C as Client/Caller
+    participant WT as WorkflowTool
+    participant G as LangGraph
+    participant N as Node Strategy
+    participant A as Agent
+    participant E as External System
+
+    C->>WT: execute(thread_id, context)
+    WT->>G: invoke(initial_context)
+
+    loop For Each Node
+        G->>N: execute(state)
+
+        alt CollectInput Node
+            N->>N: Generate prompt
+            N-->>G: INTERRUPT (USER_INPUT)
+            G-->>WT: Result with __interrupt__
+            WT-->>C: __WORKFLOW_INTERRUPT__|...|prompt
+            C->>WT: resume(thread_id, user_input)
+            WT->>G: invoke(Command resume=input)
+            G->>N: continue execution
+            N->>A: invoke(conversation)
+            A-->>N: response
+
+            alt Out of Scope
+                N-->>G: INTERRUPT (OUT_OF_SCOPE)
+                G-->>WT: Result with __interrupt__
+                WT-->>C: __OUT_OF_SCOPE_INTERRUPT__|...|payload
+            else Intent Change
+                N->>N: Rollback to target
+                N-->>G: Route to target node
+            else Normal Flow
+                N->>N: Validate & Store
+                N-->>G: Route to next
+            end
+
+        else CallFunction Node
+            N->>N: Load & Execute Function
+            N-->>G: Route based on result
+
+        else AsyncFunction Node
+            N->>E: Call async function
+            E-->>N: {status: pending, ...}
+            N-->>G: INTERRUPT (ASYNC)
+            G-->>WT: Result with __interrupt__
+            WT-->>C: __ASYNC_INTERRUPT__|...|metadata
+
+            Note over C,E: External processing...
+
+            C->>WT: resume(thread_id, async_result)
+            WT->>G: invoke(Command resume=result)
+            G->>N: continue with result
+            N-->>G: Route based on result
+        end
+    end
+
+    G-->>WT: Final state (no interrupt)
+    WT->>WT: Get outcome message
+    WT-->>C: Workflow complete message
+```
+
+## 9. State Structure
+
+```mermaid
+classDiagram
+    class WorkflowState {
+        +str _status
+        +str _outcome_id
+        +List~Dict~ _messages
+        +Dict _conversations
+        +List _state_history
+        +List _node_execution_order
+        +Dict _node_field_map
+        +Dict _collector_nodes
+        +Dict _computed_fields
+        +str error
+        +Any ...user_defined_fields
+    }
+
+    class Conversation {
+        +str field_conversation
+        +List~Message~ messages
+    }
+
+    class Message {
+        +str role
+        +str content
+    }
+
+    class StateSnapshot {
+        +str snapshot_id
+        +str node_about_to_execute
+        +int execution_index
+        +str timestamp
+        +Dict state
+    }
+
+    WorkflowState "1" *-- "*" Conversation
+    Conversation "1" *-- "*" Message
+    WorkflowState "1" *-- "*" StateSnapshot
+```
+
+## 10. Interrupt Types Summary
+
+```mermaid
+graph LR
+    subgraph "USER_INPUT"
+        UI_T[Trigger: CollectInputStrategy]
+        UI_D["Data: prompt string"]
+        UI_R["Resume: user response"]
+    end
+
+    subgraph "ASYNC"
+        A_T[Trigger: AsyncFunctionStrategy]
+        A_D["Data: {type, step_id, pending}"]
+        A_R["Resume: async result"]
+    end
+
+    subgraph "OUT_OF_SCOPE"
+        O_T[Trigger: CollectInputStrategy]
+        O_D["Data: {type, step_id,<br/>reason, user_message}"]
+        O_R["Action: Escalate to<br/>parent orchestrator"]
+    end
+
+    UI_T --> UI_D --> UI_R
+    A_T --> A_D --> A_R
+    O_T --> O_D --> O_R
+```
+
+---
+
+## Usage
+
+These diagrams are written in Mermaid format. To view them:
+
+1. **GitHub/GitLab**: Markdown files with Mermaid are rendered automatically
+2. **VS Code**: Install "Markdown Preview Mermaid Support" extension
+3. **Online**: Use [Mermaid Live Editor](https://mermaid.live/)
+4. **Export to PNG/SVG**: Use mermaid-cli (`npm install -g @mermaid-js/mermaid-cli`)
+   ```bash
+   mmdc -i framework_flow_diagrams.md -o output.png
+   ```

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

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