soprano-sdk 0.2.10__py3-none-any.whl

soprano_sdk-0.2.10.dist-info/METADATA

@@ -0,0 +1,420 @@
+Metadata-Version: 2.4
+Name: soprano-sdk
+Version: 0.2.10
+Summary: YAML-driven workflow engine with AI agent integration for building conversational SOPs
+Author: Arvind Thangamani
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,conversational,langgraph,sop,soprano,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: agno>=2.0.7
+Requires-Dist: crewai>=0.186.1
+Requires-Dist: jsonschema>=4.0.0
+Requires-Dist: langchain-community>=0.4.1
+Requires-Dist: langchain-core>=0.3.67
+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: openai>=1.92.1
+Requires-Dist: pydantic-ai>=1.22.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pytest>=9.0.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: gradio>=5.46.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Provides-Extra: persistence
+Requires-Dist: langgraph-checkpoint-mongodb>=0.2.0; extra == 'persistence'
+Requires-Dist: pymongo>=4.0.0; extra == 'persistence'
+Provides-Extra: supervisors
+Requires-Dist: crewai>=0.1.0; extra == 'supervisors'
+Requires-Dist: langchain-openai>=0.3.34; extra == 'supervisors'
+Description-Content-Type: text/markdown
+
+# Conversational SOP Framework
+
+A YAML-driven workflow engine with AI agent integration for building conversational Standard Operating Procedures (SOPs).
+
+## Features
+
+- **YAML Configuration**: Define workflows declaratively using YAML
+- **AI Agent Integration**: Built-in support for conversational data collection using OpenAI models
+- **State Management**: Powered by LangGraph for robust workflow execution
+- **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
+
+## Installation
+
+```bash
+pip install conversational-sop-framework
+```
+
+Or using uv:
+
+```bash
+uv add conversational-sop-framework
+```
+
+## Quick Start
+
+### 1. Define a Workflow in YAML
+
+```yaml
+name: "User Greeting Workflow"
+description: "Collects user information and provides a personalized greeting"
+version: "1.0"
+
+data:
+  - name: name
+    type: text
+    description: "User's name"
+  - name: age
+    type: number
+    description: "User's age in years"
+
+steps:
+  - id: get_name
+    action: collect_input_with_agent
+    field: name
+    max_attempts: 3
+    agent:
+      name: "NameCollector"
+      model: "gpt-4o-mini"
+      instructions: |
+        Your goal is to capture the user's name.
+        Start with a friendly greeting and ask for their name.
+        Once you have a clear name, respond with: 'NAME_CAPTURED: [name]'
+    transitions:
+      - pattern: "NAME_CAPTURED:"
+        next: get_age
+      - pattern: "NAME_FAILED:"
+        next: end_failed
+
+  - id: get_age
+    action: collect_input_with_agent
+    field: age
+    max_attempts: 3
+    agent:
+      name: "AgeCollector"
+      model: "gpt-4o-mini"
+      instructions: |
+        Ask for the user's age.
+        Once you have a valid age, respond with: 'AGE_CAPTURED: [age]'
+    transitions:
+      - pattern: "AGE_CAPTURED:"
+        next: end_success
+      - pattern: "AGE_FAILED:"
+        next: end_failed
+
+outcomes:
+  - id: end_success
+    type: success
+    message: "Hello {name}! You are {age} years old."
+
+  - id: end_failed
+    type: failure
+    message: "Sorry, I couldn't complete the workflow."
+```
+
+### 2. Load and Execute the Workflow
+
+```python
+from soprano_sdk import load_workflow
+from langgraph.types import Command
+import uuid
+
+# Load workflow
+graph, engine = load_workflow("greeting_workflow.yaml")
+
+# Setup execution
+thread_id = str(uuid.uuid4())
+config = {"configurable": {"thread_id": thread_id}}
+
+# Start workflow
+result = graph.invoke({}, config=config)
+
+# Interaction loop
+while True:
+    if "__interrupt__" in result and result["__interrupt__"]:
+        # Get prompt from workflow
+        prompt = result["__interrupt__"][0].value
+        print(f"Bot: {prompt}")
+
+        # Get user input
+        user_input = input("You: ")
+
+        # Resume workflow with user input
+        result = graph.invoke(Command(resume=user_input), config=config)
+    else:
+        # Workflow completed
+        message = engine.get_outcome_message(result)
+        print(f"Bot: {message}")
+        break
+```
+
+### 3. External Context Injection
+
+You can inject external context into workflows:
+
+```python
+# Pre-populate fields from external orchestrator
+result = graph.invoke({
+    "name": "Alice",
+    "age": 30
+}, config=config)
+
+# Workflow will automatically skip collection steps
+# and proceed to validation/processing
+```
+
+### 4. Persistence
+
+The library supports pluggable persistence through LangGraph's checkpointer system.
+
+#### In-Memory (Default)
+
+```python
+# No persistence - state lost when process ends
+graph, engine = load_workflow("workflow.yaml")
+```
+
+#### MongoDB Persistence
+
+```python
+from soprano_sdk import load_workflow
+from langgraph.checkpoint.mongodb import MongoDBSaver
+from pymongo import MongoClient
+
+# Setup MongoDB persistence (local)
+client = MongoClient("mongodb://localhost:27017")
+checkpointer = MongoDBSaver(client=client, db_name="workflows")
+
+# Or MongoDB Atlas (cloud)
+client = MongoClient("mongodb+srv://user:pass@cluster.mongodb.net")
+checkpointer = MongoDBSaver(client=client, db_name="workflows")
+
+# Load workflow with persistence
+graph, engine = load_workflow("workflow.yaml", checkpointer=checkpointer)
+
+# Execute with thread_id for state tracking
+config = {"configurable": {"thread_id": "user-123-return"}}
+result = graph.invoke({}, config=config)
+
+# Later, resume using same thread_id
+result = graph.invoke(Command(resume="continue"), config=config)
+```
+
+#### Thread ID Strategies
+
+Choose a thread_id strategy based on your use case:
+
+| Strategy | Thread ID Pattern | Best For |
+|----------|-------------------|----------|
+| **Entity-Based** | `f"return_{order_id}"` | One workflow per business entity |
+| **Conversation** | `str(uuid.uuid4())` | Multiple concurrent workflows |
+| **User+Workflow** | `f"{user_id}_{workflow_type}"` | One workflow type per user |
+| **Session-Based** | `session_id` | Web apps with sessions |
+
+**Examples**: See `examples/persistence/` for detailed examples of each strategy.
+
+## Workflow Actions
+
+### collect_input_with_agent
+
+Collects user input using an AI agent with conversation history.
+
+```yaml
+- id: collect_field
+  action: collect_input_with_agent
+  field: field_name
+  max_attempts: 5
+  agent:
+    name: "CollectorAgent"
+    model: "gpt-4o-mini"
+    instructions: |
+      Instructions for the agent...
+  transitions:
+    - pattern: "SUCCESS:"
+      next: next_step
+    - pattern: "FAILED:"
+      next: failure_outcome
+```
+
+### call_function
+
+Calls a Python function with workflow state.
+
+```yaml
+- id: process_data
+  action: call_function
+  function: "my_module.my_function"
+  inputs:
+    field1: "{field_name}"
+    field2: "static_value"
+  output: result_field
+  transitions:
+    - condition: true
+      next: success_step
+    - condition: false
+      next: failure_step
+```
+
+## Examples
+
+See the `examples/` directory for complete workflow examples:
+
+- `greeting_workflow.yaml` - Simple user greeting workflow
+- `return_workflow.yaml` - Customer return processing workflow
+- Function modules with business logic (`greeting_functions.py`, `return_functions.py`)
+- `persistence/` - Persistence strategy examples (entity-based, conversation-based, SQLite demo)
+
+## Running Workflows
+
+### CLI Demo
+
+```bash
+# Basic usage (in-memory)
+python scripts/workflow_demo.py examples/greeting_workflow.yaml
+
+# With MongoDB persistence (local)
+python scripts/workflow_demo.py examples/greeting_workflow.yaml --mongodb mongodb://localhost:27017
+
+# Resume existing workflow
+python scripts/workflow_demo.py examples/greeting_workflow.yaml --mongodb mongodb://localhost:27017 --thread-id abc-123
+
+# With MongoDB Atlas
+python scripts/workflow_demo.py examples/greeting_workflow.yaml --mongodb mongodb+srv://user:pass@cluster.mongodb.net
+```
+
+### Gradio UI
+
+```bash
+# Basic usage (in-memory)
+python scripts/workflow_demo_ui.py examples/greeting_workflow.yaml
+
+# With MongoDB persistence
+python scripts/workflow_demo_ui.py examples/greeting_workflow.yaml --mongodb mongodb://localhost:27017
+
+# With MongoDB Atlas
+python scripts/workflow_demo_ui.py examples/greeting_workflow.yaml --mongodb mongodb+srv://user:pass@cluster.mongodb.net
+```
+
+### Persistence Examples
+
+```bash
+cd examples/persistence
+
+# Entity-based (order ID as thread ID)
+python entity_based.py ORDER-123
+
+# Conversation-based (UUID with supervisor pattern)
+python conversation_based.py ../return_workflow.yaml --order-id ORDER-456
+
+# MongoDB demo with pause/resume
+python mongodb_demo.py
+
+# Use MongoDB Atlas
+python mongodb_demo.py --mongodb mongodb+srv://user:pass@cluster.mongodb.net
+```
+
+### Visualize Workflow
+
+```bash
+python scripts/visualize_workflow.py examples/greeting_workflow.yaml
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/dnivra26/soprano_sdk_framework.git
+cd soprano_sdk_framework
+uv sync --dev
+```
+
+### Run Tests
+
+```bash
+python tests/test_external_values.py
+```
+
+## Architecture
+
+- **soprano_sdk/**: Core library package
+  - `engine.py`: Workflow engine implementation
+  - `__init__.py`: Public API exports
+
+- **examples/**: Example workflows and persistence patterns
+  - Workflow YAML definitions
+  - Function modules with business logic
+  - `persistence/`: Different persistence strategy examples
+
+- **scripts/**: Utility tools for running and visualizing workflows
+  - `workflow_demo.py`: CLI runner with persistence support
+  - `workflow_demo_ui.py`: Gradio UI with thread management
+  - `visualize_workflow.py`: Workflow graph generator
+
+- **tests/**: Test suite
+- **legacy/**: Previous implementations (FSM, direct LangGraph)
+
+## Requirements
+
+### Core Dependencies
+
+- Python >= 3.12
+- agno >= 2.0.7
+- langgraph >= 0.6.8
+- openai >= 1.108.1
+- pyyaml >= 6.0
+
+### Optional Dependencies
+
+For MongoDB persistence:
+```bash
+# Using pip
+pip install langgraph-checkpoint-mongodb pymongo
+
+# Using uv (recommended)
+uv add langgraph-checkpoint-mongodb pymongo --optional persistence
+
+# Or install library with persistence support
+pip install conversational-sop-framework[persistence]
+```
+
+For development (includes Gradio UI and tests):
+```bash
+pip install conversational-sop-framework[dev]
+# or
+uv sync --dev
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## To Do
+
+- ✅ Database persistence (SqliteSaver, PostgresSaver supported)
+- ✅ Pluggable checkpointer system
+- ✅ Thread ID strategies and examples
+- Additional action types (webhook, conditional branching, parallel execution)
+- More workflow examples (customer onboarding, support ticketing, approval flows)
+- Workflow testing utilities
+- Metrics and monitoring hooks
+
+## Links
+
+- [GitHub Repository](https://github.com/dnivra26/soprano_sdk_framework)
+- [Issues](https://github.com/dnivra26/soprano_sdk_framework/issues)

soprano_sdk-0.2.10.dist-info/RECORD

@@ -0,0 +1,35 @@
+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=xsJbY1hZzhXbNRTAVj9M_2saU0oa7J8O9DaRGGuPf30,8832
+soprano_sdk/agents/__init__.py,sha256=Yzbtv6iP_ABRgZo0IUjy9vDofEvLFbOjuABw758176A,636
+soprano_sdk/agents/adaptor.py,sha256=Cm02YKFclrESu-Qq4CTknCgU7KaA7Z_2FspnQDkEVfU,3214
+soprano_sdk/agents/factory.py,sha256=Aucfz4rZVKCXMAQtbGAqp1JR8aYwa66mokRmKkKGhYA,6699
+soprano_sdk/agents/structured_output.py,sha256=7DSVzfMPsZAqBwI3v6XL15qG5Gh4jJ-qddcVPaa3gdc,3326
+soprano_sdk/authenticators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+soprano_sdk/authenticators/mfa.py,sha256=Vew9Nb8pIRTw9hKbEZTH3YScY-fZ_TLq4ZuCzc-wbr8,7387
+soprano_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+soprano_sdk/core/constants.py,sha256=UPXlRbF7gsOUNOV0Lm0jvgFfgZX7JrsV6n9I5csMfns,3508
+soprano_sdk/core/engine.py,sha256=vM2-nAvDc6Oam-q_BegabBT4uKVMV8DVV10SyJJPgVw,11762
+soprano_sdk/core/rollback_strategies.py,sha256=NjDTtBCZlqyDql5PSwI9SMDLK7_BNlTxbW_cq_5gV0g,7783
+soprano_sdk/core/state.py,sha256=k8ojLfWgjES3p9XWMeGU5s4UK-Xa5T8mS4VtZzTrcDw,2961
+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/call_function.py,sha256=afYBmj5Aditbkvb_7gD3CsXBEEUohcsC1_cdHfcOunE,5847
+soprano_sdk/nodes/collect_input.py,sha256=nBTLCq6nxNSO6lCV2FIbCaX6SBCZhn6-SvWm82Gl83Y,24345
+soprano_sdk/nodes/factory.py,sha256=IbBzT4FKBnYw5PuSo7uDONV3HSFtoyqjBQQtXtUY2IY,1756
+soprano_sdk/routing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+soprano_sdk/routing/router.py,sha256=Z218r4BMbmlL9282ombutAoKsIs1WHZ2d5YHnbCeet8,3698
+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
+soprano_sdk/utils/template.py,sha256=MG_B9TMx1ShpnSGo7s7TO-VfQzuFByuRNhJTvZ668kM,685
+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=SlC4sq-ueEg0p_8Uox_cgPj9S-0AEEiOOlA1Vsu0DsE,15443
+soprano_sdk/validation/validator.py,sha256=GaCvHvjwVe88Z8yatQsueiPnqtq1oo5uN75gogzpQT0,8940
+soprano_sdk-0.2.10.dist-info/METADATA,sha256=Oowx80YoqwZb11UYh8KSt4BCKrQz1qY5kwxSWIkolJ4,11298
+soprano_sdk-0.2.10.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+soprano_sdk-0.2.10.dist-info/licenses/LICENSE,sha256=A1aBauSjPNtVehOXJe3WuvdU2xvM9H8XmigFMm6665s,1073
+soprano_sdk-0.2.10.dist-info/RECORD,,

soprano_sdk-0.2.10.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

soprano_sdk-0.2.10.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arvind Thangamani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.