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

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

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

soprano_sdk-0.2.3/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.3/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.3/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."

{soprano_sdk-0.2.1 → soprano_sdk-0.2.3}/pyproject.toml

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

{soprano_sdk-0.2.1 → soprano_sdk-0.2.3}/soprano_sdk/__init__.py

@@ -1,4 +1,5 @@
 from .core.engine import WorkflowEngine, load_workflow
+from .core.constants import MFAConfig
 from .tools import WorkflowTool
 
 __version__ = "0.1.0"
@@ -6,5 +7,6 @@ __version__ = "0.1.0"
 __all__ = [
     "WorkflowEngine",
     "load_workflow",
+    "MFAConfig",
     "WorkflowTool",
 ]

{soprano_sdk-0.2.1 → soprano_sdk-0.2.3}/soprano_sdk/authenticators/mfa.py

@@ -1,6 +1,6 @@
 import requests
-from typing import TypedDict, Literal, NotRequired
-from soprano_sdk.core.constants import MFARestAuthorizerEnv
+from typing import TypedDict, Literal, NotRequired, Optional
+from soprano_sdk.core.constants import MFAConfig
 
 
 class MFAChallenge(TypedDict):
@@ -28,15 +28,21 @@ def build_path(base_url: str, path: str):
     return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
 
 
-def enforce_mfa_if_required(state: dict):
+def enforce_mfa_if_required(state: dict, mfa_config: Optional[MFAConfig] = None):
+    if mfa_config is None:
+        mfa_config = state.get('_mfa_config') or MFAConfig()
+
     _mfa : MFAState = state['_mfa']
     if _mfa['status'] == 'COMPLETED':
         return True
     generate_token_response = requests.post(
         build_path(
-            base_url=MFARestAuthorizerEnv.GENERATE_TOKEN_BASE_URL.get_from_env(),
-            path=MFARestAuthorizerEnv.GENERATE_TOKEN_PATH.get_from_env()
-        ), json=_mfa['post_payload'], timeout=30, headers={"Authorization": f"Bearer {state['bearer_token']}"}
+            base_url=mfa_config.generate_token_base_url,
+            path=mfa_config.generate_token_path
+        ),
+        json=_mfa['post_payload'],
+        timeout=mfa_config.api_timeout,
+        headers={"Authorization": f"Bearer {state['bearer_token']}"}
     )
     _, error = get_response(generate_token_response)
 
@@ -50,7 +56,10 @@ def enforce_mfa_if_required(state: dict):
     return False
 
 
-def mfa_validate_user_input(**state: dict):
+def mfa_validate_user_input(mfa_config: Optional[MFAConfig] = None, **state: dict):
+    if mfa_config is None:
+        mfa_config = state.get('_mfa_config') or MFAConfig()
+
     _mfa : MFAState = state['_mfa']
     input_field_name = state['_active_input_field']
     if not state[input_field_name]:
@@ -61,19 +70,19 @@ def mfa_validate_user_input(**state: dict):
     post_payload.update({challenge_field_name: {"value": state[input_field_name]}})
     validate_token_response = requests.post(
         build_path(
-            base_url=MFARestAuthorizerEnv.VALIDATE_TOKEN_BASE_URL.get_from_env(),
-            path=MFARestAuthorizerEnv.VALIDATE_TOKEN_PATH.get_from_env()
-        ), json=post_payload, timeout=30, headers={"Authorization": f"Bearer {state['bearer_token']}"}
+            base_url=mfa_config.validate_token_base_url,
+            path=mfa_config.validate_token_path
+        ),
+        json=post_payload,
+        timeout=mfa_config.api_timeout,
+        headers={"Authorization": f"Bearer {state['bearer_token']}"}
     )
     _mfa['retry_count'] += 1
     response, error = get_response(validate_token_response)
     if error:
         if _mfa['retry_count'] == 1:
             _mfa['status'] = 'ERRORED'
-            _mfa['message'] = (
-                f"You Have Entered Invalid {_mfa['challengeType']}. {_mfa['message']}"
-            )
-        return False
+        return False, f"You Have Entered Invalid {_mfa['challengeType']}. {_mfa['message']}"
 
     if response and 'token' in response:
         token = response['token']
@@ -81,19 +90,19 @@ def mfa_validate_user_input(**state: dict):
 
         authorize = requests.post(
             build_path(
-                base_url=MFARestAuthorizerEnv.AUTHORIZE_TOKEN_BASE_URL.get_from_env(),
-                path=MFARestAuthorizerEnv.AUTHORIZE_TOKEN_PATH.get_from_env()
+                base_url=mfa_config.authorize_token_base_url,
+                path=mfa_config.authorize_token_path
             ),
             json=post_payload,
-            timeout=30,
+            timeout=mfa_config.api_timeout,
             headers={"Authorization": f"Bearer {state['bearer_token']}"}
         )
         if authorize.status_code == 204:
             _mfa['status'] = 'COMPLETED'
-            return True
+            return True, None
         else:
             _mfa['status'] = 'FAILED'
-            return False
+            return False, f"You Have Entered Invalid {_mfa['challengeType']}. {_mfa['message']}"
 
 
 class MFANodeConfig:
@@ -140,8 +149,12 @@ class MFANodeConfig:
                     - Extract ONLY the OTP code value
                     - Output in the exact format shown below
 
+                    Examples:
+                    * User says: "1234" → `MFA_CAPTURED:1223`
+                    * User says: "2345e" → `MFA_CAPTURED:1223e
+
                     **Output Format:**
-                    MFA_CAPTURED:
+                    MFA_CAPTURED:<input_field_name>
 
             """),
             transitions=[

soprano_sdk-0.2.3/soprano_sdk/core/constants.py

@@ -0,0 +1,114 @@
+from enum import Enum
+from typing import Optional
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class WorkflowKeys:
+    STEP_ID = '_step_id'
+    STATUS = '_status'
+    OUTCOME_ID = '_outcome_id'
+    MESSAGES = '_messages'
+    CONVERSATIONS = '_conversations'
+    STATE_HISTORY = '_state_history'
+    COLLECTOR_NODES = '_collector_nodes'
+    ATTEMPT_COUNTS = '_attempt_counts'
+    NODE_EXECUTION_ORDER = '_node_execution_order'
+    NODE_FIELD_MAP = '_node_field_map'
+    COMPUTED_FIELDS = '_computed_fields'
+    ERROR = 'error'
+
+
+class ActionType(Enum):
+    COLLECT_INPUT_WITH_AGENT = 'collect_input_with_agent'
+    CALL_FUNCTION = 'call_function'
+
+
+class DataType(Enum):
+    TEXT = 'text'
+    NUMBER = 'number'
+    DOUBLE = 'double'
+    BOOLEAN = 'boolean'
+    LIST = 'list'
+    DICT = 'dict'
+    ANY = "any"
+
+
+class OutcomeType(Enum):
+    SUCCESS = 'success'
+    FAILURE = 'failure'
+
+
+class StatusPattern:
+    COLLECTING = '{step_id}_collecting'
+    MAX_ATTEMPTS = '{step_id}_max_attempts'
+    NEXT_STEP = '{step_id}_{next_step}'
+    SUCCESS = '{step_id}_success'
+    FAILED = '{step_id}_failed'
+    INTENT_CHANGE = '{step_id}_{target_node}'
+
+
+class TransitionPattern:
+    CAPTURED = '{field}_CAPTURED:'
+    FAILED = '{field}_FAILED:'
+    INTENT_CHANGE = 'INTENT_CHANGE:'
+
+
+DEFAULT_MAX_ATTEMPTS = 3
+DEFAULT_MODEL = 'gpt-4o-mini'
+DEFAULT_TIMEOUT = 300
+
+MAX_ATTEMPTS_MESSAGE = "I'm having trouble understanding your {field}. Please contact customer service for assistance."
+WORKFLOW_COMPLETE_MESSAGE = "Workflow completed."
+
+
+class MFAConfig(BaseSettings):
+    """
+    Configuration for MFA REST API endpoints.
+
+    Values can be provided during initialization or will be automatically
+    loaded from environment variables with the same name (uppercase).
+
+    Example:
+        # Load from environment variables
+        config = MFAConfig()
+
+        # Or provide specific values
+        config = MFAConfig(
+            generate_token_base_url="https://api.example.com",
+            generate_token_path="/v1/mfa/generate"
+        )
+    """
+    generate_token_base_url: Optional[str] = Field(
+        default=None,
+        description="Base URL for the generate token endpoint"
+    )
+    generate_token_path: Optional[str] = Field(
+        default=None,
+        description="Path for the generate token endpoint"
+    )
+    validate_token_base_url: Optional[str] = Field(
+        default=None,
+        description="Base URL for the validate token endpoint"
+    )
+    validate_token_path: Optional[str] = Field(
+        default=None,
+        description="Path for the validate token endpoint"
+    )
+    authorize_token_base_url: Optional[str] = Field(
+        default=None,
+        description="Base URL for the authorize token endpoint"
+    )
+    authorize_token_path: Optional[str] = Field(
+        default=None,
+        description="Path for the authorize token endpoint"
+    )
+    api_timeout: int = Field(
+        default=30,
+        description="API request timeout in seconds"
+    )
+
+    model_config = SettingsConfigDict(
+        case_sensitive=False,
+        extra='ignore'
+    )