soprano-sdk 0.1.99__tar.gz

soprano_sdk-0.1.99/.github/workflows/test_build_and_publish.yaml

@@ -0,0 +1,63 @@
+name: Conversational SOP Framework CI/CD
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Test and Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run pytest
+
+  release:
+    name: Build and Publish
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

soprano_sdk-0.1.99/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.idea

soprano_sdk-0.1.99/.python-version

@@ -0,0 +1 @@
+3.12

soprano_sdk-0.1.99/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+- **Install dependencies**: `uv sync` (uses uv.lock)
+- **Run the application**: `python ui.py` (launches Gradio interface)
+- **Run core logic directly**: `python main.py` (for testing state machine)
+
+## Project Architecture
+
+This is a conversational SOP (Standard Operating Procedure) framework that implements a return processing workflow using finite state machines. The architecture consists of:
+
+### Core Components
+
+1. **State Machine (`main.py`)**:
+   - Uses `transitions` library to implement a finite state machine
+   - Defines `States` enum with 6 states: COLLECTING_ORDER_ID → CHECKING_RETURN_ELIGIBILITY → COLLECTING_RETURN_REASON → CHECKING_REASON_VALIDITY → PROCESSING_RETURN → COMPLETED
+   - `ReturnProcessor` class manages state transitions and business logic
+   - Integrates with `agno` AI agent framework using OpenAI GPT models
+
+2. **UI Layer (`ui.py`)**:
+   - Gradio-based chat interface that wraps the core state machine
+   - `run()` function serves as the main entry point for user interactions
+   - Passes conversation history and current date to the return processor
+
+### Key Dependencies
+
+- **agno**: AI agent framework for conversational interactions
+- **transitions**: State machine implementation
+- **gradio**: Web-based chat interface
+- **openai**: LLM integration (currently using gpt-5-mini)
+
+### State Flow
+
+The return processing follows this workflow:
+1. Collect order ID from user
+2. Check if order is eligible for return
+3. Collect return reason from user
+4. Validate the return reason
+5. Process the return
+6. Complete the workflow
+
+Each state has corresponding trigger methods that advance the workflow or terminate it based on business rules.
+
+### Development Notes
+
+- The main logic is partially implemented with some placeholder/test code (random number generation)
+- The AI agent in `collect_order_id()` currently has hardcoded instructions for "loan number" capture
+- State machine callbacks are configured but not all are fully implemented

soprano_sdk-0.1.99/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.

soprano_sdk-0.1.99/PKG-INFO

@@ -0,0 +1,420 @@
+Metadata-Version: 2.4
+Name: soprano-sdk
+Version: 0.1.99
+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)