soprano-sdk 0.2.1__tar.gz → 0.2.2__tar.gz

{soprano_sdk-0.2.1 → soprano_sdk-0.2.2}/PKG-INFO

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

soprano_sdk-0.2.2/examples/concert_booking/README.md

@@ -0,0 +1,108 @@
+# Concert Ticket Booking - MFA Example
+
+This example demonstrates a concert ticket booking workflow with Multi-Factor Authentication (MFA) protection on critical operations.
+
+## Overview
+
+The workflow allows users to book concert tickets through a conversational interface with the following features:
+
+- **Customer name collection**
+- **Concert selection**
+- **Seat preference selection** (VIP, Premium, General)
+- **Ticket quantity selection**
+- **Seat availability checking**
+- **Payment processing** (MFA-protected)
+- **Booking confirmation** (MFA-protected)
+- **Booking modification** (with loop-back to MFA)
+
+## MFA-Protected Steps
+
+Two critical operations are protected with MFA:
+
+1. **`process_payment`** - Payment transaction processing
+2. **`send_confirmation`** - Sending booking confirmation
+
+## Key Features for MFA Testing
+
+### 1. Forward MFA Flow
+Regular workflow progression through MFA-protected steps:
+```
+collect_seat_preference → check_seat_availability → process_payment (MFA) → send_confirmation (MFA)
+```
+
+### 2. Loop Back Scenario
+User can modify booking AFTER completion, which loops back through MFA:
+```
+ask_modification_needed → collect_seat_preference → ... → process_payment (MFA)
+```
+
+This tests that steps AFTER MFA-protected nodes can correctly reference them.
+
+### 3. Multiple MFA Steps
+Sequential MFA-protected operations:
+```
+process_payment (MFA) → send_confirmation (MFA)
+```
+
+### 4. Alternative Paths
+When seats are unavailable, alternative paths also go through MFA:
+```
+offer_alternative_seats → check_seat_availability → process_payment (MFA)
+```
+
+## Files
+
+- **`concert_ticket_booking.yaml`** - Workflow definition with MFA configuration
+- **`booking_helpers.py`** - Helper functions for workflow logic
+- **`README.md`** - This file
+
+## MFA Configuration Example
+
+```yaml
+- id: process_payment
+  description: Process payment transaction with MFA
+  action: call_function
+  function: booking_helpers.process_payment
+  output: payment_status
+  mfa:
+    model: gpt-4o-mini
+    type: REST
+    payload:
+      transactionType: CONCERT_TICKET_PAYMENT
+      businessKey:
+        customerName: "{{customer_name}}"
+        concertName: "{{concert_name}}"
+        seatPreference: "{{seat_preference}}"
+        ticketQuantity: "{{ticket_quantity}}"
+```
+
+## Testing
+
+Run the comprehensive MFA test suite:
+
+```bash
+python tests/test_mfa_scenarios.py
+```
+
+The test suite includes:
+
+1. **MFA Node Creation** - Verifies MFA nodes are properly inserted
+2. **Previous Step Redirection** - Tests forward flow through MFA
+3. **Loop Back Redirection** - Tests backward references to MFA steps (critical)
+4. **Multiple MFA Steps** - Tests sequential MFA operations
+5. **MFA Data Fields** - Validates data schema updates
+6. **Alternative Paths** - Tests multiple paths to MFA steps
+7. **Comprehensive Flow** - End-to-end validation
+
+## Pricing
+
+- **VIP**: ₹5,000 per ticket
+- **Premium**: ₹3,000 per ticket
+- **General**: ₹1,500 per ticket
+
+## Notes
+
+- Maximum 8 tickets per booking
+- Seat availability is simulated (80% success rate)
+- Payment processing is simulated (90% success rate)
+- Confirmation sending is simulated (95% success rate)

soprano_sdk-0.2.2/examples/concert_booking/TEST_RESULTS.md

@@ -0,0 +1,179 @@
+# MFA Test Results - Concert Ticket Booking
+
+## Test Execution Summary
+
+**Date**: 2026-01-05
+**Test Suite**: `tests/test_mfa_scenarios.py`
+**Status**: ✅ **ALL TESTS PASSED** (7/7)
+
+## Test Cases
+
+### ✅ Test 1: MFA Node Creation
+**Status**: PASSED
+**Purpose**: Verify MFA nodes are properly created and injected into the workflow
+
+**Validations**:
+- MFA start nodes are inserted before MFA-protected steps
+- MFA validate nodes are created for user input collection
+- Original steps remain intact after MFA injection
+- 2 MFA-protected steps → 4 MFA nodes created (2 per protected step)
+
+---
+
+### ✅ Test 2: Previous Step Redirection (Forward Flow)
+**Status**: PASSED
+**Purpose**: Verify steps BEFORE MFA-protected steps redirect correctly
+
+**Validations**:
+- `check_seat_availability` → `process_payment` becomes `check_seat_availability` → `process_payment_mfa_start`
+- `process_payment` → `send_confirmation` becomes `process_payment` → `send_confirmation_mfa_start`
+- All forward transitions to MFA-protected steps go through MFA authentication
+
+---
+
+### ✅ Test 3: Loop Back Redirection (CRITICAL BUG FIX TEST)
+**Status**: PASSED
+**Purpose**: Verify steps AFTER MFA-protected steps that loop back redirect correctly
+
+**Critical Scenario**:
+```
+User Flow:
+1. Complete booking (goes through MFA for payment & confirmation)
+2. Request modification (ask_modification_needed step)
+3. Change seat preference (loops back to collect_seat_preference)
+4. Re-process payment (must go through MFA again)
+```
+
+**Validations**:
+- `ask_modification_needed` comes AFTER MFA-protected steps
+- Loop back to `collect_seat_preference` is preserved
+- Path from `collect_seat_preference` eventually reaches `process_payment_mfa_start`
+- No MFA bypass - modification requires re-authentication
+
+**This test validates the fix implemented in** `soprano_sdk/core/engine.py:202-246`
+
+---
+
+### ✅ Test 4: Multiple MFA Steps in Sequence
+**Status**: PASSED
+**Purpose**: Verify multiple consecutive MFA-protected steps work correctly
+
+**Scenario**:
+```
+process_payment (MFA) → send_confirmation (MFA)
+```
+
+**Validations**:
+- Each MFA step has independent start and validate nodes
+- Flow between MFA steps is preserved
+- Both MFA processes execute sequentially without interference
+
+---
+
+### ✅ Test 5: MFA Data Fields Creation
+**Status**: PASSED
+**Purpose**: Verify MFA-specific data fields are automatically created
+
+**Validations**:
+- Data fields for MFA validate nodes are added to workflow schema
+- Field names match the MFA validate node field names
+- Data schema properly includes MFA authentication fields
+
+---
+
+### ✅ Test 6: Alternative Paths to MFA Steps
+**Status**: PASSED
+**Purpose**: Verify alternative/conditional paths to MFA steps are redirected
+
+**Scenario**:
+```
+offer_alternative_seats → check_seat_availability → process_payment (MFA)
+```
+
+**Validations**:
+- Alternative path (when seats unavailable) also goes through MFA
+- Multiple entry points to MFA-protected steps all redirect correctly
+- No bypass routes exist for MFA-protected operations
+
+---
+
+### ✅ Test 7: Comprehensive MFA Flow Validation
+**Status**: PASSED
+**Purpose**: End-to-end validation of entire workflow structure
+
+**Validations**:
+- All 15 workflow steps validated
+- No step directly references MFA-protected steps (all go through MFA start)
+- No MFA bypass violations found
+- Complete workflow integrity maintained
+
+**Workflow Statistics**:
+- Total steps: 15
+- MFA-protected steps: 2
+- MFA nodes created: 4
+- Regular steps: 11
+
+---
+
+## Technical Details
+
+### MFA Implementation
+The framework automatically injects MFA authentication nodes for steps marked with `mfa` configuration:
+
+```yaml
+- id: process_payment
+  action: call_function
+  function: booking_helpers.process_payment
+  mfa:
+    model: gpt-4o-mini
+    type: REST
+    payload:
+      transactionType: CONCERT_TICKET_PAYMENT
+```
+
+### Node Injection Pattern
+For each MFA-protected step `X`, the framework creates:
+1. `X_mfa_start` - Initiates MFA authentication flow
+2. `X_mfa_validate` - Collects and validates user authentication input
+3. Original step `X` - Executes only after successful MFA
+
+### Bug Fix Validation
+The critical test (Test 3) validates the fix in `core/engine.py` where:
+- **Before**: Only steps BEFORE MFA-protected steps were updated
+- **After**: ALL steps (both before AND after) that reference MFA-protected steps are updated
+
+This ensures loop-back scenarios (like booking modifications) cannot bypass MFA authentication.
+
+---
+
+## Running the Tests
+
+```bash
+# Using pytest (recommended)
+cd /path/to/soprano_sdk
+uv run pytest tests/test_mfa_scenarios.py -v
+
+# Using direct Python execution
+cd /path/to/soprano_sdk
+uv run python tests/test_mfa_scenarios.py
+```
+
+## Dependencies
+
+The tests require:
+- `pytest` for test execution
+- Environment variables for MFA endpoints (set via pytest fixtures)
+- Concert booking workflow YAML and helper functions
+
+---
+
+## Conclusion
+
+All comprehensive MFA test cases pass successfully, validating:
+1. Correct MFA node creation and injection
+2. Proper redirection of all paths (forward and backward)
+3. Support for multiple consecutive MFA steps
+4. Automatic data field management
+5. Complete workflow integrity with no MFA bypass routes
+
+The implementation correctly handles both forward flows and loop-back scenarios, ensuring that MFA protection cannot be circumvented through any workflow path.

soprano_sdk-0.2.2/examples/concert_booking/__init__.py

@@ -0,0 +1,6 @@
+"""
+Concert Ticket Booking Example
+
+This example demonstrates MFA (Multi-Factor Authentication) functionality
+in a concert ticket booking workflow.
+"""

soprano_sdk-0.2.2/examples/concert_booking/booking_helpers.py

@@ -0,0 +1,88 @@
+"""
+Helper functions for concert ticket booking workflow
+"""
+import random
+import uuid
+
+
+def initialize_prices(state):
+    """Initialize ticket prices"""
+    return {
+        'vip_price': 5000,
+        'premium_price': 3000,
+        'general_price': 1500
+    }
+
+
+def check_availability(state):
+    """Check if requested seats are available"""
+    seat_preference = state.get('seat_preference')
+    ticket_quantity = state.get('ticket_quantity', 1)
+
+    # Simulate availability check - 80% chance of success
+    available = random.random() > 0.2
+
+    print(f"Checking availability: {ticket_quantity} x {seat_preference} seats")
+    print(f"Result: {'Available' if available else 'Not Available'}")
+
+    return available
+
+
+def process_payment(state):
+    """Process payment for tickets"""
+    customer_name = state.get('customer_name')
+    concert_name = state.get('concert_name')
+    seat_preference = state.get('seat_preference')
+    ticket_quantity = state.get('ticket_quantity', 1)
+
+    # Calculate total amount
+    vip_price = state.get('vip_price', 5000)
+    premium_price = state.get('premium_price', 3000)
+    general_price = state.get('general_price', 1500)
+
+    prices = {
+        'VIP': vip_price,
+        'Premium': premium_price,
+        'General': general_price
+    }
+
+    price_per_ticket = prices.get(seat_preference, general_price)
+    total_amount = price_per_ticket * ticket_quantity
+
+    # Simulate payment processing - 90% success rate
+    payment_success = random.random() > 0.1
+
+    print(f"Processing payment for {customer_name}")
+    print(f"Concert: {concert_name}")
+    print(f"Tickets: {ticket_quantity} x {seat_preference}")
+    print(f"Total: ₹{total_amount}")
+    print(f"Payment Status: {'Success' if payment_success else 'Failed'}")
+
+    # Generate booking reference on success
+    if payment_success:
+        state['booking_reference'] = f"BK{uuid.uuid4().hex[:8].upper()}"
+
+    return payment_success
+
+
+def send_confirmation(state):
+    """Send booking confirmation"""
+    customer_name = state.get('customer_name')
+    booking_reference = state.get('booking_reference')
+    concert_name = state.get('concert_name')
+
+    # Simulate sending confirmation - 95% success rate
+    confirmation_sent = random.random() > 0.05
+
+    print(f"Sending confirmation to {customer_name}")
+    print(f"Booking Reference: {booking_reference}")
+    print(f"Concert: {concert_name}")
+    print(f"Status: {'Sent' if confirmation_sent else 'Failed'}")
+
+    return confirmation_sent
+
+
+def handle_payment_failure(state):
+    """Handle payment failure"""
+    print("Payment failed. Cleaning up...")
+    return False

soprano_sdk-0.2.2/examples/concert_booking/concert_ticket_booking.yaml

@@ -0,0 +1,244 @@
+name: Concert Ticket Booking
+description: Manages concert ticket booking with seat selection, payment processing, and confirmation
+version: '1.0.0'
+
+data:
+  - name: bearer_token
+    type: text
+    description: User authentication bearer token for MFA
+  - name: customer_name
+    type: text
+    description: Customer's full name
+  - name: concert_name
+    type: text
+    description: Name of the concert to book
+  - name: seat_preference
+    type: text
+    description: Preferred seating section (VIP, Premium, General)
+  - name: ticket_quantity
+    type: number
+    description: Number of tickets to book
+  - name: seat_available
+    type: boolean
+    description: Whether requested seats are available
+  - name: payment_status
+    type: boolean
+    description: Payment transaction status
+  - name: confirmation_sent
+    type: boolean
+    description: Whether confirmation email was sent
+  - name: modification_requested
+    type: boolean
+    description: Whether customer wants to modify booking
+  - name: booking_reference
+    type: text
+    description: Unique booking reference number
+  - name: vip_price
+    type: number
+    description: VIP ticket price
+  - name: premium_price
+    type: number
+    description: Premium ticket price
+  - name: general_price
+    type: number
+    description: General ticket price
+
+steps:
+  - id: initialize_pricing
+    description: Initialize ticket pricing
+    action: call_function
+    function: booking_helpers.initialize_prices
+    output: vip_price
+    next: collect_customer_name
+
+  - id: collect_customer_name
+    description: Collect customer name
+    action: collect_input_with_agent
+    field: customer_name
+    max_attempts: 3
+    agent:
+      name: Customer Name Collector
+      model: gpt-4o-mini
+      initial_message: "Welcome to Concert Ticket Booking! Please provide your full name."
+      instructions: >
+        Extract the customer's full name from their message.
+        Return: NAME_CAPTURED: [customer_name] or INVALID_INPUT:
+    transitions:
+      - next: collect_concert_details
+        pattern: "NAME_CAPTURED:"
+      - next: booking_cancelled
+        pattern: "INVALID_INPUT:"
+
+  - id: collect_concert_details
+    description: Collect concert and seat preferences
+    action: collect_input_with_agent
+    field: concert_name
+    max_attempts: 3
+    agent:
+      name: Concert Details Collector
+      model: gpt-4o-mini
+      initial_message: "Hi {{customer_name}}! Which concert would you like to attend? Please specify the concert name."
+      instructions: >
+        Extract concert name from the user's message.
+        Return: CONCERT_CAPTURED: [concert_name] or CANCEL_REQUEST:
+    transitions:
+      - next: collect_seat_preference
+        pattern: "CONCERT_CAPTURED:"
+      - next: booking_cancelled
+        pattern: "CANCEL_REQUEST:"
+
+  - id: collect_seat_preference
+    description: Collect seating preference
+    action: collect_input_with_agent
+    field: seat_preference
+    max_attempts: 3
+    agent:
+      name: Seat Preference Collector
+      model: gpt-4o-mini
+      initial_message: >
+        Please choose your seating preference for {{concert_name}}:
+        - VIP (₹{{vip_price}})
+        - Premium (₹{{premium_price}})
+        - General (₹{{general_price}})
+      instructions: >
+        Identify seating preference (VIP, Premium, or General).
+        Return: SEAT_CAPTURED: [seat_preference] or CANCEL_REQUEST:
+    transitions:
+      - next: collect_ticket_quantity
+        pattern: "SEAT_CAPTURED:"
+      - next: booking_cancelled
+        pattern: "CANCEL_REQUEST:"
+
+  - id: collect_ticket_quantity
+    description: Collect number of tickets
+    action: collect_input_with_agent
+    field: ticket_quantity
+    max_attempts: 3
+    agent:
+      name: Ticket Quantity Collector
+      model: gpt-4o-mini
+      initial_message: "How many {{seat_preference}} tickets would you like to book? (Maximum 8 per booking)"
+      instructions: >
+        Extract the number of tickets (1-8).
+        Return: QUANTITY_CAPTURED: [ticket_quantity] or INVALID_QUANTITY:
+    transitions:
+      - next: check_seat_availability
+        pattern: "QUANTITY_CAPTURED:"
+      - next: booking_cancelled
+        pattern: "INVALID_QUANTITY:"
+
+  - id: check_seat_availability
+    description: Check if requested seats are available
+    action: call_function
+    function: booking_helpers.check_availability
+    output: seat_available
+    transitions:
+      - next: process_payment
+        condition: true
+      - next: offer_alternative_seats
+        condition: false
+
+  - id: offer_alternative_seats
+    description: Offer alternative seat options
+    action: collect_input_with_agent
+    field: seat_preference
+    max_attempts: 3
+    agent:
+      name: Alternative Seat Offer
+      model: gpt-4o-mini
+      initial_message: >
+        Sorry {{customer_name}}, {{seat_preference}} seats are not available for {{concert_name}}.
+        Would you like to try a different section?
+      instructions: >
+        Ask if user wants alternative seats.
+        Return: ALTERNATIVE_ACCEPTED: [new_preference] or BOOKING_DECLINED:
+    transitions:
+      - next: check_seat_availability
+        pattern: "ALTERNATIVE_ACCEPTED:"
+      - next: booking_cancelled
+        pattern: "BOOKING_DECLINED:"
+
+  # MFA-PROTECTED STEP: Payment processing requires authentication
+  - id: process_payment
+    description: Process payment transaction with MFA
+    action: call_function
+    function: booking_helpers.process_payment
+    output: payment_status
+    mfa:
+      model: gpt-4o-mini
+      type: REST
+      payload:
+        transactionType: CONCERT_TICKET_PAYMENT
+        businessKey:
+          customerName: "{{customer_name}}"
+          concertName: "{{concert_name}}"
+          seatPreference: "{{seat_preference}}"
+          ticketQuantity: "{{ticket_quantity}}"
+    transitions:
+      - next: send_confirmation
+        condition: true
+      - next: payment_failed
+        condition: false
+
+  # MFA-PROTECTED STEP: Sending confirmation requires authentication
+  - id: send_confirmation
+    description: Send booking confirmation with MFA
+    action: call_function
+    function: booking_helpers.send_confirmation
+    output: confirmation_sent
+    mfa:
+      model: gpt-4o-mini
+      type: REST
+      payload:
+        transactionType: SEND_TICKET_CONFIRMATION
+        businessKey:
+          bookingReference: "{{booking_reference}}"
+          customerName: "{{customer_name}}"
+    next: ask_modification_needed
+
+  - id: ask_modification_needed
+    description: Ask if customer wants to modify booking
+    action: collect_input_with_agent
+    field: modification_requested
+    max_attempts: 3
+    agent:
+      name: Modification Request Collector
+      model: gpt-4o-mini
+      initial_message: >
+        Booking confirmed for {{concert_name}}, {{customer_name}}!
+        Reference: {{booking_reference}}
+        Seats: {{ticket_quantity}} x {{seat_preference}}
+
+        Would you like to modify your booking details? (Yes/No)
+      instructions: >
+        Determine if user wants to modify the booking.
+        Return: MODIFICATION_REQUESTED: or NO_MODIFICATION:
+    transitions:
+      - next: collect_seat_preference
+        pattern: "MODIFICATION_REQUESTED:"
+      - next: booking_success
+        pattern: "NO_MODIFICATION:"
+
+  - id: payment_failed
+    description: Handle payment failure
+    action: call_function
+    function: booking_helpers.handle_payment_failure
+    output: payment_status
+    next: booking_failed
+
+outcomes:
+  - id: booking_success
+    type: success
+    message: "Thank you {{customer_name}}! Your {{ticket_quantity}} {{seat_preference}} tickets for {{concert_name}} have been confirmed. Booking reference: {{booking_reference}}"
+
+  - id: booking_cancelled
+    type: failure
+    message: "Booking cancelled. Feel free to start a new booking anytime!"
+
+  - id: booking_failed
+    type: failure
+    message: "We couldn't complete your booking. Please try again or contact support."
+
+  - id: payment_failed
+    type: failure
+    message: "Payment failed. Please check your payment method and try again."