soprano-sdk 0.2.5__tar.gz → 0.2.7__tar.gz

{soprano_sdk-0.2.5 → soprano_sdk-0.2.7}/PKG-INFO

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

{soprano_sdk-0.2.5 → soprano_sdk-0.2.7}/pyproject.toml

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

{soprano_sdk-0.2.5 → soprano_sdk-0.2.7}/soprano_sdk/authenticators/mfa.py

@@ -10,6 +10,7 @@ class MFAChallenge(TypedDict):
 class MFAState(TypedDict):
     challengeType: Literal['OTP', 'dob']
     post_payload: dict[str, str]
+    post_headers: NotRequired[dict[str, str]]
     otpValue: NotRequired[str]
     status: Literal['IN_PROGRESS', 'COMPLETED', 'ERRORED', 'FAILED'] | None
     message: str
@@ -35,6 +36,10 @@ def enforce_mfa_if_required(state: dict, mfa_config: Optional[MFAConfig] = None)
     _mfa : MFAState = state['_mfa']
     if _mfa['status'] == 'COMPLETED':
         return True
+
+    # Use custom headers if provided, otherwise empty dict
+    headers = _mfa.get('post_headers', {})
+
     generate_token_response = requests.post(
         build_path(
             base_url=mfa_config.generate_token_base_url,
@@ -42,7 +47,7 @@ def enforce_mfa_if_required(state: dict, mfa_config: Optional[MFAConfig] = None)
         ),
         json=_mfa['post_payload'],
         timeout=mfa_config.api_timeout,
-        headers={"Authorization": f"Bearer {state['bearer_token']}"}
+        headers=headers
     )
     _, error = get_response(generate_token_response)
 
@@ -65,6 +70,9 @@ def mfa_validate_user_input(mfa_config: Optional[MFAConfig] = None, **state: dic
     if not state[input_field_name]:
         return False
 
+    # Use custom headers if provided, otherwise empty dict
+    headers = _mfa.get('post_headers', {})
+
     post_payload = _mfa['post_payload']
     challenge_field_name = f"{_mfa['challengeType'].lower()}Challenge"
     post_payload.update({challenge_field_name: {"value": state[input_field_name]}})
@@ -75,7 +83,7 @@ def mfa_validate_user_input(mfa_config: Optional[MFAConfig] = None, **state: dic
         ),
         json=post_payload,
         timeout=mfa_config.api_timeout,
-        headers={"Authorization": f"Bearer {state['bearer_token']}"}
+        headers=headers
     )
     _mfa['retry_count'] += 1
     response, error = get_response(validate_token_response)
@@ -95,7 +103,7 @@ def mfa_validate_user_input(mfa_config: Optional[MFAConfig] = None, **state: dic
             ),
             json=post_payload,
             timeout=mfa_config.api_timeout,
-            headers={"Authorization": f"Bearer {state['bearer_token']}"}
+            headers=headers
         )
         if authorize.status_code == 204:
             _mfa['status'] = 'COMPLETED'
@@ -146,25 +154,47 @@ class MFANodeConfig:
                 model=model_name,
                 initial_message="{{_mfa.message}}",
                 instructions="""
-                    You are an authentication value extractor. Your job is to identify and extract MFA codes from user input.
+                    You are an authentication value extractor. Your job is to identify and extract MFA codes from user input, or detect if the user wants to cancel the authentication flow.
 
                     **Task:**
-                    - Read the user's message
-                    - 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
+                    - Read the user's message carefully
+                    - First, check if the user wants to cancel, stop, or exit the authentication process
+                    - If they want to cancel, output: MFA_CANCELLED:
+                    - Otherwise, extract ONLY the OTP/MFA code value and output in the format shown below
+
+                    **Cancellation Detection:**
+                    If the user expresses any intent to cancel, stop, exit, abort, or quit the authentication process, respond with: MFA_CANCELLED
+
+                    Examples of cancellation phrases:
+                    * "cancel" → MFA_CANCELLED:
+                    * "I want to stop" → MFA_CANCELLED:
+                    * "exit" → MFA_CANCELLED:
+                    * "nevermind" → MFA_CANCELLED:
+                    * "I don't want to continue" → MFA_CANCELLED:
+                    * "stop this" → MFA_CANCELLED:
+                    * "forget it" → MFA_CANCELLED:
+                    * "abort" → MFA_CANCELLED:
+                    * "quit" → MFA_CANCELLED:
+
+                    **OTP Capture Examples:**
+                    * "1234" → MFA_CAPTURED:1234
+                    * "2345e" → MFA_CAPTURED:2345e
+                    * "the code is 567890" → MFA_CAPTURED:567890
+                    * "my otp is 123456" → MFA_CAPTURED:123456
 
                     **Output Format:**
-                    MFA_CAPTURED:<input_field_name>
+                    - For OTP/MFA codes: MFA_CAPTURED:<otp_value>
+                    - For cancellation: MFA_CANCELLED:
 
             """),
             transitions=[
                 dict(
                     pattern="MFA_CAPTURED:",
                     next=next_node
+                ),
+                dict(
+                    pattern="MFA_CANCELLED:",
+                    next="mfa_cancelled"
                 )
             ]
         )

{soprano_sdk-0.2.5 → soprano_sdk-0.2.7}/soprano_sdk/core/constants.py

@@ -114,6 +114,10 @@ class MFAConfig(BaseSettings):
         default=30,
         description="API request timeout in seconds"
     )
+    mfa_cancelled_message: str = Field(
+        default="Authentication has been cancelled.",
+        description="Message to display when user cancels MFA authentication"
+    )
 
     model_config = SettingsConfigDict(
         case_sensitive=False,

{soprano_sdk-0.2.5 → soprano_sdk-0.2.7}/soprano_sdk/core/engine.py

@@ -39,8 +39,7 @@ class WorkflowEngine:
             self.step_map = {step['id']: step for step in self.steps}
             self.mfa_config = (mfa_config or MFAConfig()) if self.mfa_validator_steps else None
             self.data_fields = self.load_data()
-
-            self.outcomes = self.config['outcomes']
+            self.outcomes = self.load_outcomes()
             self.metadata = self.config.get('metadata', {})
 
             self.StateType = create_state_model(self.data_fields)
@@ -260,6 +259,20 @@ class WorkflowEngine:
             )
         return data
 
+    def load_outcomes(self):
+        outcomes: list = self.config['outcomes']
+
+        if self.mfa_config:
+            mfa_cancelled_outcome = {
+                'id': 'mfa_cancelled',
+                'type': 'failure',
+                'message': self.mfa_config.mfa_cancelled_message
+            }
+            outcomes.append(mfa_cancelled_outcome)
+            logger.info(f"Auto-generated 'mfa_cancelled' outcome with message: {self.mfa_config.mfa_cancelled_message}")
+
+        return outcomes
+
 
 def load_workflow(yaml_path: str, checkpointer=None, config=None, mfa_config: Optional[MFAConfig] = None) -> Tuple[CompiledStateGraph, WorkflowEngine]:
     """

{soprano_sdk-0.2.5 → soprano_sdk-0.2.7}/soprano_sdk/nodes/call_function.py

@@ -39,11 +39,17 @@ class CallFunctionStrategy(ActionStrategy):
         if 'mfa' in self.step_config:
             state['_mfa'] = state.get('_mfa', {})
             state['_mfa']['post_payload'] = dict(transactionId=str(uuid.uuid4()))
+            state['_mfa']['post_headers'] = {}
             state['_mfa_config'] = self.engine_context.mfa_config
             template_loader = self.engine_context.get_config_value("template_loader", Environment())
             for k, v in self.step_config['mfa']['payload'].items():
                 state['_mfa']['post_payload'][k] = compile_values(template_loader, state, v)
 
+            # Process headers if provided
+            if 'headers' in self.step_config['mfa']:
+                for k, v in self.step_config['mfa']['headers'].items():
+                    state['_mfa']['post_headers'][k] = compile_values(template_loader, state, v)
+
     def execute(self, state: Dict[str, Any]) -> Dict[str, Any]:
         from ..utils.tracing import trace_node_execution
         

{soprano_sdk-0.2.5 → soprano_sdk-0.2.7}/tests/test_mfa_scenarios.py

@@ -416,3 +416,384 @@ def test_mfa_comprehensive_flow():
 
     print("\n✅ TEST PASSED: Comprehensive flow validation successful")
     print("=" * 80)
+
+
+def test_mfa_default_max_attempts():
+    """
+    Test Case 8: Verify default max_attempts value
+
+    Validates that:
+    - MFA collector nodes use default max_attempts value of 3 when not specified
+    """
+    print("\n" + "=" * 80)
+    print("TEST 8: MFA Default Max Attempts")
+    print("=" * 80)
+
+    yaml_path = os.path.join(get_examples_dir(), "concert_ticket_booking.yaml")
+    graph, engine = load_workflow(yaml_path)
+
+    print("\nScenario: MFA config does not specify max_attempts")
+    print("Expected: Default value of 3 should be used")
+
+    # Get MFA validate nodes
+    mfa_validate_nodes = [s for s in engine.list_steps() if '_mfa_validate' in s]
+    print(f"\nMFA validate nodes: {mfa_validate_nodes}")
+
+    for node_id in mfa_validate_nodes:
+        node_info = engine.get_step_info(node_id)
+        max_attempts = node_info.get('max_attempts', 'NOT_SET')
+        print(f"\n{node_id}")
+        print(f"  max_attempts: {max_attempts}")
+
+        assert max_attempts == 3, \
+            f"Expected default max_attempts=3, got {max_attempts}"
+        print("  ✅ Correctly uses default max_attempts=3")
+
+    print("\n✅ TEST PASSED: Default max_attempts value verified")
+    print("=" * 80)
+
+
+def test_mfa_custom_max_attempts():
+    """
+    Test Case 9: Verify custom max_attempts configuration
+
+    Validates that:
+    - Custom max_attempts value from MFA config is applied to collector node
+    """
+    print("\n" + "=" * 80)
+    print("TEST 9: MFA Custom Max Attempts")
+    print("=" * 80)
+
+    # Create a temporary YAML with custom max_attempts
+    import tempfile
+
+    yaml_path = os.path.join(get_examples_dir(), "concert_ticket_booking.yaml")
+
+    with open(yaml_path, 'r') as f:
+        yaml_content = f.read()
+
+    # Add max_attempts to first MFA config
+    modified_yaml = yaml_content.replace(
+        """    mfa:
+      model: gpt-4o-mini
+      type: REST
+      payload:
+        transactionType: CONCERT_TICKET_PAYMENT""",
+        """    mfa:
+      model: gpt-4o-mini
+      type: REST
+      max_attempts: 5
+      payload:
+        transactionType: CONCERT_TICKET_PAYMENT"""
+    )
+
+    # Write to temporary file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+        temp_yaml_path = f.name
+        f.write(modified_yaml)
+
+    try:
+        graph, engine = load_workflow(temp_yaml_path)
+
+        print("\nScenario: MFA config specifies max_attempts: 5")
+
+        # Find the process_payment MFA validate node
+        process_payment_validate = 'process_payment_mfa_validate'
+        assert process_payment_validate in engine.list_steps(), \
+            f"Expected {process_payment_validate} node to exist"
+
+        node_info = engine.get_step_info(process_payment_validate)
+        max_attempts = node_info.get('max_attempts')
+
+        print(f"\nNode: {process_payment_validate}")
+        print(f"  max_attempts: {max_attempts}")
+
+        assert max_attempts == 5, \
+            f"Expected custom max_attempts=5, got {max_attempts}"
+        print("  ✅ Correctly uses custom max_attempts=5")
+
+        print("\n✅ TEST PASSED: Custom max_attempts value applied correctly")
+        print("=" * 80)
+    finally:
+        # Clean up temporary file
+        os.unlink(temp_yaml_path)
+
+
+def test_mfa_custom_error_message():
+    """
+    Test Case 10: Verify custom on_max_attempts_reached message
+
+    Validates that:
+    - Custom error message from MFA config is applied to collector node
+    """
+    print("\n" + "=" * 80)
+    print("TEST 10: MFA Custom Error Message")
+    print("=" * 80)
+
+    # Create a temporary YAML with custom error message
+    import tempfile
+
+    yaml_path = os.path.join(get_examples_dir(), "concert_ticket_booking.yaml")
+
+    with open(yaml_path, 'r') as f:
+        yaml_content = f.read()
+
+    custom_error = "You have exceeded the maximum MFA attempts for payment verification. Your transaction has been blocked for security. Please contact support at 1-800-TICKETS."
+
+    # Add on_max_attempts_reached to first MFA config
+    modified_yaml = yaml_content.replace(
+        """    mfa:
+      model: gpt-4o-mini
+      type: REST
+      payload:
+        transactionType: CONCERT_TICKET_PAYMENT""",
+        f"""    mfa:
+      model: gpt-4o-mini
+      type: REST
+      on_max_attempts_reached: "{custom_error}"
+      payload:
+        transactionType: CONCERT_TICKET_PAYMENT"""
+    )
+
+    # Write to temporary file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+        temp_yaml_path = f.name
+        f.write(modified_yaml)
+
+    try:
+        graph, engine = load_workflow(temp_yaml_path)
+
+        print("\nScenario: MFA config specifies custom on_max_attempts_reached message")
+
+        # Find the process_payment MFA validate node
+        process_payment_validate = 'process_payment_mfa_validate'
+        assert process_payment_validate in engine.list_steps(), \
+            f"Expected {process_payment_validate} node to exist"
+
+        node_info = engine.get_step_info(process_payment_validate)
+        error_message = node_info.get('on_max_attempts_reached')
+
+        print(f"\nNode: {process_payment_validate}")
+        print(f"  on_max_attempts_reached: {error_message}")
+
+        assert error_message == custom_error, \
+            f"Expected custom error message, got {error_message}"
+        print("  ✅ Correctly uses custom error message")
+
+        print("\n✅ TEST PASSED: Custom error message applied correctly")
+        print("=" * 80)
+    finally:
+        # Clean up temporary file
+        os.unlink(temp_yaml_path)
+
+
+def test_mfa_custom_max_attempts_and_error():
+    """
+    Test Case 11: Verify both custom max_attempts and on_max_attempts_reached together
+
+    Validates that:
+    - Both custom max_attempts and error message can be configured together
+    - Both values are correctly applied to the MFA collector node
+    """
+    print("\n" + "=" * 80)
+    print("TEST 11: MFA Custom Max Attempts and Error Message Together")
+    print("=" * 80)
+
+    # Create a temporary YAML with both custom values
+    import tempfile
+
+    yaml_path = os.path.join(get_examples_dir(), "concert_ticket_booking.yaml")
+
+    with open(yaml_path, 'r') as f:
+        yaml_content = f.read()
+
+    custom_error = "Maximum verification attempts exceeded. Account locked."
+    custom_max_attempts = 2
+
+    # Add both fields to MFA config
+    modified_yaml = yaml_content.replace(
+        """    mfa:
+      model: gpt-4o-mini
+      type: REST
+      payload:
+        transactionType: CONCERT_TICKET_PAYMENT""",
+        f"""    mfa:
+      model: gpt-4o-mini
+      type: REST
+      max_attempts: {custom_max_attempts}
+      on_max_attempts_reached: "{custom_error}"
+      payload:
+        transactionType: CONCERT_TICKET_PAYMENT"""
+    )
+
+    # Write to temporary file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+        temp_yaml_path = f.name
+        f.write(modified_yaml)
+
+    try:
+        graph, engine = load_workflow(temp_yaml_path)
+
+        print(f"\nScenario: MFA config specifies max_attempts: {custom_max_attempts} and custom error")
+
+        # Find the process_payment MFA validate node
+        process_payment_validate = 'process_payment_mfa_validate'
+        assert process_payment_validate in engine.list_steps(), \
+            f"Expected {process_payment_validate} node to exist"
+
+        node_info = engine.get_step_info(process_payment_validate)
+        max_attempts = node_info.get('max_attempts')
+        error_message = node_info.get('on_max_attempts_reached')
+
+        print(f"\nNode: {process_payment_validate}")
+        print(f"  max_attempts: {max_attempts}")
+        print(f"  on_max_attempts_reached: {error_message}")
+
+        assert max_attempts == custom_max_attempts, \
+            f"Expected max_attempts={custom_max_attempts}, got {max_attempts}"
+        print(f"  ✅ Correctly uses custom max_attempts={custom_max_attempts}")
+
+        assert error_message == custom_error, \
+            f"Expected custom error message, got {error_message}"
+        print("  ✅ Correctly uses custom error message")
+
+        print("\n✅ TEST PASSED: Both custom values applied correctly")
+        print("=" * 80)
+    finally:
+        # Clean up temporary file
+        os.unlink(temp_yaml_path)
+
+
+def test_mfa_custom_headers_with_jinja():
+    """
+    Test Case 12: Verify custom headers with Jinja template rendering
+
+    Validates that:
+    - Custom headers can be specified in MFA config
+    - Jinja templates in header values are correctly rendered with state data
+    - Headers are stored in the MFA state as post_headers
+    """
+    print("\n" + "=" * 80)
+    print("TEST 12: MFA Custom Headers with Jinja Template Rendering")
+    print("=" * 80)
+
+    # Create a temporary YAML with custom headers
+    import tempfile
+
+    yaml_path = os.path.join(get_examples_dir(), "concert_ticket_booking.yaml")
+
+    with open(yaml_path, 'r') as f:
+        yaml_content = f.read()
+
+    # Add headers to first MFA config
+    modified_yaml = yaml_content.replace(
+        """    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:""",
+        """    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}}"
+      headers:
+        Authorization: "Bearer {{bearer_token}}"
+        X-Customer-Name: "{{customer_name}}"
+        X-Concert-Name: "{{concert_name}}"
+        X-Request-Id: "payment-{{booking_reference}}"
+    transitions:"""
+    )
+
+    # Write to temporary file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+        temp_yaml_path = f.name
+        f.write(modified_yaml)
+
+    try:
+        graph, engine = load_workflow(temp_yaml_path)
+
+        print("\nScenario: MFA config includes custom headers with Jinja templates")
+
+        # Initialize state with test data
+        state = {
+            'bearer_token': 'test-token-12345',
+            'customer_name': 'John Doe',
+            'concert_name': 'Rock Concert 2026',
+            'booking_reference': 'BK-001',
+            'seat_preference': 'VIP',
+            'ticket_quantity': 2
+        }
+
+        # Find the process_payment step
+        process_payment_step = 'process_payment'
+        assert process_payment_step in engine.list_steps(), \
+            f"Expected {process_payment_step} step to exist"
+
+        # Check the MFA start node - this is where the MFA config is stored
+        process_payment_mfa_start = 'process_payment_mfa_start'
+        assert process_payment_mfa_start in engine.list_steps(), \
+            f"Expected {process_payment_mfa_start} node to exist"
+
+        mfa_start_info = engine.get_step_info(process_payment_mfa_start)
+
+        # Verify headers are defined in MFA config
+        assert 'mfa' in mfa_start_info, "MFA start node should have MFA configuration"
+        assert 'headers' in mfa_start_info['mfa'], "MFA config should have headers"
+
+        headers_config = mfa_start_info['mfa']['headers']
+        print("\nHeaders defined in MFA config:")
+        for key, value in headers_config.items():
+            print(f"  {key}: {value}")
+
+        # Verify header templates
+        assert headers_config['Authorization'] == "Bearer {{bearer_token}}", \
+            "Authorization header should have bearer_token template"
+        assert headers_config['X-Customer-Name'] == "{{customer_name}}", \
+            "X-Customer-Name header should have customer_name template"
+        assert headers_config['X-Concert-Name'] == "{{concert_name}}", \
+            "X-Concert-Name header should have concert_name template"
+        assert headers_config['X-Request-Id'] == "payment-{{booking_reference}}", \
+            "X-Request-Id header should have booking_reference template"
+
+        print("\n✅ Headers configuration verified")
+
+        # Test that headers would be rendered correctly (simulation)
+        from jinja2 import Environment
+        template_loader = Environment()
+
+        expected_rendered_headers = {
+            'Authorization': 'Bearer test-token-12345',
+            'X-Customer-Name': 'John Doe',
+            'X-Concert-Name': 'Rock Concert 2026',
+            'X-Request-Id': 'payment-BK-001'
+        }
+
+        print("\nExpected rendered headers:")
+        for key, value in expected_rendered_headers.items():
+            print(f"  {key}: {value}")
+
+        # Verify template rendering logic
+        for key, template_str in headers_config.items():
+            rendered = template_loader.from_string(template_str).render(state)
+            expected = expected_rendered_headers[key]
+            assert rendered == expected, \
+                f"Header {key} rendering mismatch: expected '{expected}', got '{rendered}'"
+            print(f"  ✅ {key} renders correctly")
+
+        print("\n✅ TEST PASSED: Custom headers with Jinja templates work correctly")
+        print("=" * 80)
+    finally:
+        # Clean up temporary file
+        os.unlink(temp_yaml_path)