soprano-sdk 0.1.93__py3-none-any.whl → 0.1.95__py3-none-any.whl

soprano_sdk/validation/schema.py

@@ -0,0 +1,302 @@
+WORKFLOW_SCHEMA = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["name", "description", "version", "data", "steps", "outcomes"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "description": "Workflow name"
+        },
+        "description": {
+            "type": "string",
+            "description": "Workflow description"
+        },
+        "version": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+(\\.\\d+)?$",
+            "description": "Semantic version (e.g., 1.0.0)"
+        },
+        "agent_framework": {
+            "type": "string",
+            "enum": ["langgraph", "crewai", "agno", "pydantic-ai"],
+            "default": "langgraph",
+            "description": "Agent framework to use for all agents in this workflow (default: langgraph)"
+        },
+        "data": {
+            "type": "array",
+            "description": "Data fields used in the workflow",
+            "items": {
+                "type": "object",
+                "required": ["name", "type", "description"],
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+                        "description": "Field name (must be valid Python identifier)"
+                    },
+                    "type": {
+                        "type": "string",
+                        "enum": ["text", "number", "boolean", "list", "dict", "any", "double"],
+                        "description": "Field data type"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Field description"
+                    },
+                    "default": {
+                        "description": "Default value for the field"
+                    }
+                }
+            }
+        },
+        "inputs": {
+            "type": "array",
+            "description": "Input fields required to start the workflow (list of data field names)",
+            "items": {
+                "type": "string",
+                "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+                "description": "Name of a field from the data array"
+            }
+        },
+        "steps": {
+            "type": "array",
+            "description": "Workflow steps",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "required": ["id", "action"],
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+                        "description": "Step ID (must be unique and valid Python identifier)"
+                    },
+                    "action": {
+                        "type": "string",
+                        "enum": ["collect_input_with_agent", "call_function"],
+                        "description": "Action type"
+                    },
+                    "field": {
+                        "type": "string",
+                        "description": "Field to collect (for collect_input_with_agent)"
+                    },
+                    "validator": {
+                        "type": "string",
+                        "description": "Optional data validator"
+                    },
+                    "max_attempts": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 20,
+                        "description": "Maximum attempts (for collect_input_with_agent)"
+                    },
+                    "agent": {
+                        "type": "object",
+                        "description": "Agent configuration (for collect_input_with_agent)",
+                        "required": ["name", "instructions"],
+                        "properties": {
+                            "name": {
+                                "type": "string"
+                            },
+                            "model": {
+                                "type": "string"
+                            },
+                            "description": {
+                                "type": "string"
+                            },
+                            "instructions": {
+                                "type": "string"
+                            },
+                            "tools": {
+                                "type": "array"
+                            },
+                            "base_url": {
+                                "type": "string",
+                                "format": "uri"
+                            },
+                            "api_key": {
+                                "type": "string"
+                            },
+                            "structured_output": {
+                                "type": "object",
+                                "description": "Structured output configuration",
+                                "required": ["enabled"],
+                                "properties": {
+                                    "enabled": {
+                                        "type": "boolean",
+                                        "description": "Whether to enable structured output"
+                                    },
+                                    "fields": {
+                                        "type": "array",
+                                        "description": "Field definitions for structured output",
+                                        "items": {
+                                            "type": "object",
+                                            "required": ["name", "type", "description"],
+                                            "properties": {
+                                                "name": {
+                                                    "type": "string",
+                                                    "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+                                                    "description": "Field name (must be valid Python identifier)"
+                                                },
+                                                "type": {
+                                                    "type": "string",
+                                                    "enum": ["text", "number", "boolean", "list", "dict", "double"],
+                                                    "description": "Field data type"
+                                                },
+                                                "description": {
+                                                    "type": "string",
+                                                    "description": "Field description"
+                                                },
+                                                "required": {
+                                                    "type": "boolean",
+                                                    "description": "Whether the field is required",
+                                                    "default": True
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "function": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z_][a-zA-Z0-9_.]*\\.[a-zA-Z_][a-zA-Z0-9_]*$",
+                        "description": "Function path (for call_function, format: module.function)"
+                    },
+                    "inputs": {
+                        "type": "object",
+                        "description": "Input mapping for function"
+                    },
+                    "output": {
+                        "type": "string",
+                        "description": "Output field name"
+                    },
+                    "next": {
+                        "type": "string",
+                        "description": "Next step ID (for simple routing)"
+                    },
+                    "transitions": {
+                        "type": "array",
+                        "description": "Conditional transitions",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "pattern": {
+                                    "type": "string",
+                                    "description": "Pattern to match in response (for non-structured output)"
+                                },
+                                "match": {
+                                    "description": "Value to match against a field (for structured output)"
+                                },
+                                "ref": {
+                                    "type": "string",
+                                    "description": "Field name to check when using 'match' (for structured output)"
+                                },
+                                "condition": {
+                                    "description": "Condition to evaluate (for call_function)"
+                                },
+                                "path": {
+                                    "type": "string",
+                                    "description": "Dot-notation path to the value for evaluation (optional)"
+                                },
+                                "next": {
+                                    "type": "string",
+                                    "description": "Next step or outcome ID"
+                                }
+                            },
+                            "oneOf": [
+                                {"required": ["pattern", "next"]},
+                                {"required": ["match", "next", "ref"]},
+                                {"required": ["condition", "next"]}
+                            ]
+                        }
+                    },
+                    "url": {
+                        "type": "string",
+                        "format": "uri",
+                        "description": "Webhook URL (for webhook action)"
+                    },
+                    "method": {
+                        "type": "string",
+                        "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                        "description": "HTTP method (for webhook action)"
+                    },
+                    "headers": {
+                        "type": "object",
+                        "description": "HTTP headers (for webhook action)"
+                    },
+                    "timeout": {
+                        "type": "integer",
+                        "minimum": 1,
+                        "maximum": 600,
+                        "description": "Timeout in seconds"
+                    }
+                }
+            }
+        },
+        "outcomes": {
+            "type": "array",
+            "description": "Workflow outcomes",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "required": ["id", "type", "message"],
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+                        "description": "Outcome ID (must be unique)"
+                    },
+                    "type": {
+                        "type": "string",
+                        "enum": ["success", "failure"],
+                        "description": "Outcome type"
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Outcome message (supports {field} placeholders)"
+                    }
+                }
+            }
+        },
+        "metadata": {
+            "type": "object",
+            "description": "Additional workflow metadata",
+            "properties": {
+                "author": {"type": "string"},
+                "tags": {"type": "array", "items": {"type": "string"}},
+                "documentation": {"type": "string"}
+            }
+        },
+        "tool_config": {
+            "type": "object",
+            "description": "Tool configuration for the workflow",
+            "properties": {
+                "tools": {
+                    "type": "array",
+                    "description": "List of available tools",
+                    "items": {
+                        "type": "object",
+                        "required": ["name", "description", "callable"],
+                        "properties": {
+                            "name": {
+                                "type": "string",
+                                "description": "Tool name"
+                            },
+                            "description": {
+                                "type": "string",
+                                "description": "Tool description"
+                            },
+                            "callable": {
+                                "type": "string",
+                                "pattern": "^[a-zA-Z_][a-zA-Z0-9_.]*\\.[a-zA-Z_][a-zA-Z0-9_]*$",
+                                "description": "Callable path (format: module.function)"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

soprano_sdk/validation/validator.py

@@ -0,0 +1,173 @@
+from typing import List, Set
+
+import jsonschema
+
+from .schema import WORKFLOW_SCHEMA
+
+
+class ValidationResult:
+    def __init__(self, is_valid: bool, errors: List[str] = None):
+        self.is_valid = is_valid
+        self.errors = errors or []
+
+    def __bool__(self):
+        return self.is_valid
+
+    def __str__(self):
+        if self.is_valid:
+            return "Validation passed"
+        return f"Validation failed with {len(self.errors)} error(s):\n" + "\n".join(f"  - {e}" for e in self.errors)
+
+
+class WorkflowValidator:
+    def __init__(self, config: dict):
+        self.config = config
+        self.errors: List[str] = []
+
+    def validate(self) -> ValidationResult:
+        self.errors = []
+        self._validate_schema()
+        if not self.errors:
+            self._validate_step_ids()
+            self._validate_outcome_ids()
+            self._validate_transitions()
+            self._validate_data_fields()
+            self._validate_input_fields()
+            self._validate_function_references()
+
+        return ValidationResult(is_valid=len(self.errors) == 0, errors=self.errors)
+
+    def _validate_schema(self):
+        try:
+            jsonschema.validate(instance=self.config, schema=WORKFLOW_SCHEMA)
+        except jsonschema.ValidationError as e:
+            path = " -> ".join(str(p) for p in e.path) if e.path else "root"
+            self.errors.append(f"Schema validation error at '{path}': {e.message}")
+        except jsonschema.SchemaError as e:
+            self.errors.append(f"Invalid schema definition: {e.message}")
+
+    def _validate_input_fields(self):
+        """Validate that all input field names reference valid data fields."""
+        input_fields = self.config.get('inputs', [])
+        data_fields = set([field.get('name') for field in self.config.get('data', [])])
+
+        for field_name in input_fields:
+            if field_name not in data_fields:
+                self.errors.append(f"Input field '{field_name}' is not defined in data fields")
+
+    def _validate_step_ids(self):
+        steps = self.config.get('steps', [])
+        step_ids: Set[str] = set()
+
+        for i, step in enumerate(steps):
+            step_id = step.get('id')
+            if not step_id:
+                self.errors.append(f"Step at index {i} is missing 'id' field")
+                continue
+
+            if step_id in step_ids:
+                self.errors.append(f"Duplicate step ID: '{step_id}'")
+            step_ids.add(step_id)
+
+    def _validate_outcome_ids(self):
+        outcomes = self.config.get('outcomes', [])
+        outcome_ids: Set[str] = set()
+
+        for i, outcome in enumerate(outcomes):
+            outcome_id = outcome.get('id')
+            if not outcome_id:
+                self.errors.append(f"Outcome at index {i} is missing 'id' field")
+                continue
+
+            if outcome_id in outcome_ids:
+                self.errors.append(f"Duplicate outcome ID: '{outcome_id}'")
+            outcome_ids.add(outcome_id)
+
+    def _validate_transitions(self):
+        steps = self.config.get('steps', [])
+        outcomes = self.config.get('outcomes', [])
+
+        step_ids = {step.get('id') for step in steps if step.get('id')}
+        outcome_ids = {outcome.get('id') for outcome in outcomes if outcome.get('id')}
+        valid_targets = step_ids | outcome_ids
+
+        for step in steps:
+            step_id = step.get('id', 'unknown')
+
+            next_step = step.get('next')
+            if next_step and next_step not in valid_targets:
+                self.errors.append(
+                    f"Step '{step_id}' references unknown target in 'next': '{next_step}'"
+                )
+
+            transitions = step.get('transitions', [])
+            for i, transition in enumerate(transitions):
+                next_target = transition.get('next')
+                if next_target and next_target not in valid_targets:
+                    self.errors.append(
+                        f"Step '{step_id}' transition {i} references unknown target: '{next_target}'"
+                    )
+
+    def _validate_data_fields(self):
+        data_fields = {field.get('name') for field in self.config.get('data', [])}
+        steps = self.config.get('steps', [])
+
+        for step in steps:
+            step_id = step.get('id', 'unknown')
+            action = step.get('action')
+
+            if action == 'collect_input_with_agent':
+                field = step.get('field')
+                if not field:
+                    self.errors.append(f"Step '{step_id}' is missing 'field' property")
+                elif field not in data_fields:
+                    self.errors.append(
+                        f"Step '{step_id}' references unknown field: '{field}'"
+                    )
+
+                agent = step.get('agent')
+                if not agent:
+                    self.errors.append(f"Step '{step_id}' is missing 'agent' configuration")
+                elif not agent.get('instructions'):
+                    self.errors.append(f"Step '{step_id}' agent is missing 'instructions'")
+
+            elif action == 'call_function':
+                output = step.get('output')
+                function = step.get('function')
+
+                if not function:
+                    self.errors.append(f"Step '{step_id}' is missing 'function' property")
+
+                if not output:
+                    self.errors.append(f"Step '{step_id}' is missing 'output' property")
+                elif output not in data_fields:
+                    self.errors.append(
+                        f"Step '{step_id}' output field '{output}' not defined in data fields"
+                    )
+
+    def _validate_function_references(self):
+        steps = self.config.get('steps', [])
+
+        for step in steps:
+            if step.get('action') == 'call_function':
+                step_id = step.get('id', 'unknown')
+                function_path = step.get('function', '')
+
+                if not function_path:
+                    continue  # Already caught by _validate_data_fields
+
+                if '.' not in function_path:
+                    self.errors.append(
+                        f"Step '{step_id}' function path '{function_path}' is invalid. "
+                        f"Expected format: 'module.function'"
+                    )
+
+
+def validate_workflow(config: dict) -> ValidationResult:
+    validator = WorkflowValidator(config)
+    result = validator.validate()
+
+    if not result.is_valid:
+        raise RuntimeError(str(result))
+
+    return result

{soprano_sdk-0.1.93.dist-info → soprano_sdk-0.1.95.dist-info}/METADATA

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

soprano_sdk-0.1.95.dist-info/RECORD

@@ -0,0 +1,33 @@
+soprano_sdk/__init__.py,sha256=y3c4i7Q7SAPS2Tee7V0TzWdhgMxBWfDJJ98eqD1HxGI,188
+soprano_sdk/engine.py,sha256=EFK91iTHjp72otLN6Kg-yeLye2J3CAKN0QH4FI2taL8,14838
+soprano_sdk/tools.py,sha256=A0qFEwn208GCYc-_7ZbZKR7N3HG5-6TA3Ma1RPo6YnM,8029
+soprano_sdk/agents/__init__.py,sha256=Yzbtv6iP_ABRgZo0IUjy9vDofEvLFbOjuABw758176A,636
+soprano_sdk/agents/adaptor.py,sha256=IMMgo9_KLI82i1eenOaojw7UE0jjx9vjm8mjfsodKSM,3226
+soprano_sdk/agents/factory.py,sha256=Aucfz4rZVKCXMAQtbGAqp1JR8aYwa66mokRmKkKGhYA,6699
+soprano_sdk/agents/structured_output.py,sha256=LDBWCMJFclOvcFB3OJpu37tO0Ct_M-L2PIH5MCYSjLI,3262
+soprano_sdk/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+soprano_sdk/core/constants.py,sha256=pEwW_NeHhxs7aG457uiBCs65czAapozY6r9JAegc01Y,1451
+soprano_sdk/core/engine.py,sha256=WEyqGaBasGnSqlBAkFSQIZXJb7T6OEsN-DWznIBAzNs,8341
+soprano_sdk/core/rollback_strategies.py,sha256=UZyDBRmbi4kS7D9cGJT_mzSZzfqgbUoeTnOGcW1WOc0,7798
+soprano_sdk/core/state.py,sha256=h0Uo4uCwBAGTWrmzpDbcTwH6lI97-fXU9ek0tc3p2bM,2617
+soprano_sdk/nodes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+soprano_sdk/nodes/base.py,sha256=H6wvvN3kUeXluZAt5Hf3iocO9NjTElAH4fTb2-1JKr0,2233
+soprano_sdk/nodes/call_function.py,sha256=6M9QywYpitwDsbIbOSGw0YN_lH4kRFWa5UMxIIf393M,4346
+soprano_sdk/nodes/collect_input.py,sha256=LhDsqtlBKK-uIz90QIODDoR5PZbnv4rWyj-hvTR64do,21987
+soprano_sdk/nodes/factory.py,sha256=l-Gysfgnao-o2dphhnbjjxcH3ojZanZNYN3CBH9dDbA,1624
+soprano_sdk/routing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+soprano_sdk/routing/router.py,sha256=SrNciTIXXdC9bAbbO5bX7PN9mlRbITjr4RZdNm4jEVA,3450
+soprano_sdk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+soprano_sdk/utils/data.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+soprano_sdk/utils/function.py,sha256=yqkY4MlHOenv-Q3NciiovK1lamyrGQljpy6Q41wviy8,1216
+soprano_sdk/utils/logger.py,sha256=hMYaNHt5syGOXRkglTUKzkgfSbWerix_pHQntcYyep8,157
+soprano_sdk/utils/template.py,sha256=EssXvRDWdyITVWp52weYNIwnqj9ilJaoQotWFIg4rGQ,678
+soprano_sdk/utils/tool.py,sha256=hWN826HIKmLdswLCTURLH8hWlb2WU0MB8nIUErbpB-8,1877
+soprano_sdk/utils/tracing.py,sha256=iSJlTAaiGzgBvZhLISCGAd9_7F2HRzhcIUNHuaFv_Zc,2059
+soprano_sdk/validation/__init__.py,sha256=ImChmO86jYHU90xzTttto2-LmOUOmvY_ibOQaLRz5BA,262
+soprano_sdk/validation/schema.py,sha256=uJJZRDgwzWT2W8amd_W8mUAULvDnHJhiMEl-5so1ZK0,13559
+soprano_sdk/validation/validator.py,sha256=l2P24wiCWBNTZ9-dRbgWwK48BGaR1xIdnBxzSCu0RPM,6498
+soprano_sdk-0.1.95.dist-info/METADATA,sha256=c8u9LFyCMo-p4U3A_2V0zh16dpK4BoRYBcVB0nckXIw,11269
+soprano_sdk-0.1.95.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+soprano_sdk-0.1.95.dist-info/licenses/LICENSE,sha256=A1aBauSjPNtVehOXJe3WuvdU2xvM9H8XmigFMm6665s,1073
+soprano_sdk-0.1.95.dist-info/RECORD,,

soprano_sdk-0.1.93.dist-info/RECORD

@@ -1,4 +0,0 @@
-soprano_sdk-0.1.93.dist-info/METADATA,sha256=TmMcHnMXPkO1WEYt75D3N8I3ev5TtXZJKqDTWj8zRiY,11269
-soprano_sdk-0.1.93.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-soprano_sdk-0.1.93.dist-info/licenses/LICENSE,sha256=A1aBauSjPNtVehOXJe3WuvdU2xvM9H8XmigFMm6665s,1073
-soprano_sdk-0.1.93.dist-info/RECORD,,