kailash 0.8.4__py3-none-any.whl → 0.8.5__py3-none-any.whl

kailash/runtime/validation/suggestion_engine.py

@@ -0,0 +1,212 @@
+"""
+Suggestion engine for generating actionable guidance from validation errors.
+
+Provides specific, actionable suggestions for fixing connection validation
+errors based on error category, node type, and connection context.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from .connection_context import ConnectionContext
+from .error_categorizer import ErrorCategory
+
+
+@dataclass
+class ValidationSuggestion:
+    """Actionable suggestion for fixing a validation error."""
+
+    message: str
+    """Human-readable suggestion message"""
+
+    code_example: Optional[str] = None
+    """Code example showing how to fix the issue"""
+
+    documentation_link: Optional[str] = None
+    """Link to relevant documentation"""
+
+    alternative_approaches: Optional[List[str]] = None
+    """List of alternative approaches to consider"""
+
+
+class ValidationSuggestionEngine:
+    """Generates actionable suggestions for connection validation errors."""
+
+    def __init__(self):
+        self._suggestion_templates = self._initialize_suggestion_templates()
+
+    def generate_suggestion(
+        self,
+        error_category: ErrorCategory,
+        node_type: str,
+        connection_context: ConnectionContext,
+        original_error: str,
+    ) -> Optional[ValidationSuggestion]:
+        """Generate actionable suggestion for a validation error.
+
+        Args:
+            error_category: Categorized error type
+            node_type: Type of target node (e.g., 'CSVWriterNode')
+            connection_context: Context about the failing connection
+            original_error: Original error message
+
+        Returns:
+            ValidationSuggestion with actionable guidance, or None if no suggestion available
+        """
+        # Get base suggestion template for error category
+        template = self._suggestion_templates.get(error_category)
+        if not template:
+            return None
+
+        # Customize suggestion based on node type and context
+        return self._customize_suggestion(
+            template, node_type, connection_context, original_error
+        )
+
+    def _initialize_suggestion_templates(self) -> Dict[ErrorCategory, Dict]:
+        """Initialize suggestion templates for each error category."""
+        return {
+            ErrorCategory.TYPE_MISMATCH: {
+                "message": "The parameter type doesn't match what the node expects. Check the data types being passed through the connection.",
+                "code_template": '# Check the output type from source node\n# Expected: {expected_type}\n# Got: {actual_type}\nworkflow.add_connection("{source}", "{source_port}", "{target}", "{target_port}")',
+                "doc_link": "sdk-users/validation/common-mistakes.md#type-mismatch",
+                "alternatives": [
+                    "Add a data transformation node between source and target",
+                    "Check if you're connecting to the correct output port",
+                    "Verify the source node produces the expected data type",
+                ],
+            },
+            ErrorCategory.MISSING_PARAMETER: {
+                "message": "A required parameter is missing. Make sure all required parameters are provided via connections or node configuration.",
+                "code_template": '# Add the missing parameter connection:\nworkflow.add_connection("{source}", "{source_port}", "{target}", "{missing_param}")\n\n# Or provide it directly in node configuration:\nworkflow.add_node("{node_type}", "{target}", {{"{missing_param}": "value"}})',
+                "doc_link": "sdk-users/validation/common-mistakes.md#missing-parameters",
+                "alternatives": [
+                    "Provide the parameter directly in node configuration",
+                    "Create a PythonCodeNode to generate the required parameter",
+                    "Check if another node output can provide this parameter",
+                ],
+            },
+            ErrorCategory.CONSTRAINT_VIOLATION: {
+                "message": "The parameter value violates validation constraints. Check the parameter requirements for this node type.",
+                "code_template": '# Ensure parameter meets requirements:\n# {constraint_details}\nworkflow.add_connection("{source}", "{source_port}", "{target}", "{target_port}")\n\n# Or add validation in source node:\nworkflow.add_node("PythonCodeNode", "validator", {{"code": "result = max(0, input_value)"}})',
+                "doc_link": "sdk-users/nodes/node-selection-guide.md#parameter-validation",
+                "alternatives": [
+                    "Add data validation/transformation before the target node",
+                    "Check the node documentation for parameter requirements",
+                    "Use a different node that accepts your data format",
+                ],
+            },
+            ErrorCategory.SECURITY_VIOLATION: {
+                "message": "Potential security issue detected in parameter value. This could indicate SQL injection, script injection, or other security vulnerabilities.",
+                "code_template": '# Use parameterized/sanitized approach:\n# For SQL operations:\nworkflow.add_node("SQLDatabaseNode", "safe_query", {{\n    "query": "SELECT * FROM table WHERE id = $1",\n    "params": ["user_input"]\n}})\n\n# For user input, add validation:\nworkflow.add_node("PythonCodeNode", "sanitizer", {{"code": "result = sanitize_input(user_data)"}})',
+                "doc_link": "sdk-users/enterprise/security-patterns.md#input-validation",
+                "alternatives": [
+                    "Use parameterized queries instead of string concatenation",
+                    "Add input sanitization/validation nodes",
+                    "Review the data source for potential security issues",
+                    "Use whitelisting instead of blacklisting for allowed values",
+                ],
+            },
+            ErrorCategory.UNKNOWN: {
+                "message": "An unexpected validation error occurred. Check the error details and node documentation.",
+                "code_template": '# General troubleshooting:\n# 1. Check node documentation for parameter requirements\n# 2. Verify data types and formats\n# 3. Test with simpler data first\nworkflow.add_connection("{source}", "{source_port}", "{target}", "{target_port}")',
+                "doc_link": "sdk-users/developer/05-troubleshooting.md",
+                "alternatives": [
+                    "Check the node documentation for specific requirements",
+                    "Test with simplified data to isolate the issue",
+                    "Add debug logging to inspect the data flow",
+                    "Review similar examples in the documentation",
+                ],
+            },
+        }
+
+    def _customize_suggestion(
+        self,
+        template: Dict,
+        node_type: str,
+        connection_context: ConnectionContext,
+        original_error: str,
+    ) -> ValidationSuggestion:
+        """Customize suggestion template with specific context."""
+        # Extract context information
+        source = connection_context.source_node
+        source_port = connection_context.source_port or "result"
+        target = connection_context.target_node
+        target_port = connection_context.target_port
+
+        # Customize code example
+        code_example = template["code_template"].format(
+            source=source,
+            source_port=source_port,
+            target=target,
+            target_port=target_port,
+            node_type=node_type,
+            expected_type="<check_node_docs>",
+            actual_type="<check_source_output>",
+            missing_param=target_port,
+            constraint_details="See node documentation for valid ranges/formats",
+        )
+
+        # Add node-specific customizations
+        message = template["message"]
+        if (
+            "DataFlow" in node_type
+            or node_type.endswith("CreateNode")
+            or node_type.endswith("UpdateNode")
+        ):
+            message += " For DataFlow nodes, ensure the data matches your model schema."
+
+        if "SQL" in node_type or "Database" in node_type:
+            message += " For database nodes, verify connection strings and SQL syntax."
+
+        if "LLM" in node_type or "Agent" in node_type:
+            message += " For AI nodes, check prompt formatting and model parameters."
+
+        return ValidationSuggestion(
+            message=message,
+            code_example=code_example,
+            documentation_link=template["doc_link"],
+            alternative_approaches=template["alternatives"],
+        )
+
+    def get_dataflow_specific_suggestion(
+        self, error_category: ErrorCategory, connection_context: ConnectionContext
+    ) -> Optional[str]:
+        """Get DataFlow-specific suggestions for common issues."""
+        dataflow_suggestions = {
+            ErrorCategory.TYPE_MISMATCH: (
+                "For DataFlow models, ensure the connected data matches your model field types. "
+                "Check your @db.model class definition for expected types."
+            ),
+            ErrorCategory.SECURITY_VIOLATION: (
+                "DataFlow automatically sanitizes SQL parameters, but connection-level validation "
+                "caught a potential issue. Review the data source for SQL injection attempts."
+            ),
+            ErrorCategory.MISSING_PARAMETER: (
+                "DataFlow nodes require all model fields to be provided. Check your model definition "
+                "and ensure all required fields have connections or default values."
+            ),
+        }
+        return dataflow_suggestions.get(error_category)
+
+    def get_common_connection_patterns(self, node_type: str) -> List[str]:
+        """Get common connection patterns for specific node types."""
+        patterns = {
+            "CSVReaderNode": [
+                "workflow.add_connection('reader', 'data', 'processor', 'input_data')",
+                "workflow.add_connection('reader', 'metadata.rows', 'counter', 'count')",
+            ],
+            "HTTPRequestNode": [
+                "workflow.add_connection('api', 'response.data', 'processor', 'json_data')",
+                "workflow.add_connection('api', 'status_code', 'checker', 'status')",
+            ],
+            "LLMAgentNode": [
+                "workflow.add_connection('input', 'text', 'llm', 'prompt')",
+                "workflow.add_connection('llm', 'result', 'output', 'analysis')",
+            ],
+            "SQLDatabaseNode": [
+                "workflow.add_connection('data', 'records', 'db', 'data')",
+                "workflow.add_connection('config', 'table_name', 'db', 'table')",
+            ],
+        }
+        return patterns.get(node_type, [])

kailash/testing/fixtures.py

@@ -183,8 +183,8 @@ class AsyncWorkflowFixtures:
                 f"mysql://{user}:{password}@localhost:{actual_port}/{database}"
             )
 
-            # Wait for MySQL to be ready (takes longer than PostgreSQL)
-            await asyncio.sleep(10)
+            # Wait for MySQL to be ready (shorter wait for tests)
+            await asyncio.sleep(0.1)
 
             return DatabaseFixture(
                 container=container,

kailash/workflow/builder.py

@@ -2,10 +2,11 @@
 
 import logging
 import uuid
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 from kailash.nodes.base import Node
 from kailash.sdk_exceptions import ConnectionError, WorkflowValidationError
+from kailash.workflow.contracts import ConnectionContract, get_contract_registry
 from kailash.workflow.graph import Workflow
 
 logger = logging.getLogger(__name__)
@@ -14,8 +15,12 @@ logger = logging.getLogger(__name__)
 class WorkflowBuilder:
     """Builder pattern for creating Workflow instances."""
 
-    def __init__(self):
-        """Initialize an empty workflow builder."""
+    def __init__(self, edge_config: dict[str, Any] | None = None):
+        """Initialize an empty workflow builder.
+
+        Args:
+            edge_config: Optional edge infrastructure configuration
+        """
         self.nodes: dict[str, dict[str, Any]] = {}
         self.connections: list[dict[str, str]] = []
         self._metadata: dict[str, Any] = {}
@@ -23,6 +28,15 @@ class WorkflowBuilder:
         self.workflow_parameters: dict[str, Any] = {}
         self.parameter_mappings: dict[str, dict[str, str]] = {}
 
+        # Edge infrastructure support
+        self.edge_config = edge_config
+        self._has_edge_nodes = False
+        self._edge_infrastructure = None
+
+        # Connection contracts support
+        self.connection_contracts: dict[str, ConnectionContract] = {}
+        self._contract_registry = get_contract_registry()
+
     def add_node(self, *args, **kwargs) -> str:
         """
         Unified add_node method supporting multiple API patterns.
@@ -287,8 +301,52 @@ class WorkflowBuilder:
             )
 
         logger.info(f"Added node '{node_id}' of type '{type_name}'")
+
+        # Detect edge nodes
+        if self._is_edge_node(type_name):
+            self._has_edge_nodes = True
+            logger.debug(f"Detected edge node: {type_name}")
+
         return node_id
 
+    def _is_edge_node(self, node_type: str) -> bool:
+        """Check if a node type is an edge node.
+
+        Args:
+            node_type: The node type to check
+
+        Returns:
+            True if the node is an edge node
+        """
+        # Use the same logic as EdgeInfrastructure if available
+        if self._edge_infrastructure:
+            return self._edge_infrastructure.is_edge_node(node_type)
+
+        # Otherwise use local logic
+        # Check exact matches and subclasses
+        edge_prefixes = ["Edge", "edge"]
+        edge_suffixes = [
+            "EdgeNode",
+            "EdgeDataNode",
+            "EdgeStateMachine",
+            "EdgeCacheNode",
+        ]
+
+        # Exact match
+        if node_type in edge_suffixes:
+            return True
+
+        # Check if it starts with Edge/edge
+        for prefix in edge_prefixes:
+            if node_type.startswith(prefix):
+                return True
+
+        # Check if it ends with EdgeNode (for custom edge nodes)
+        if node_type.endswith("EdgeNode"):
+            return True
+
+        return False
+
     # Fluent API methods for backward compatibility
     def add_node_fluent(
         self, node_id: str, node_class_or_type: Any, **config
@@ -539,6 +597,142 @@ class WorkflowBuilder:
         self._metadata.update(kwargs)
         return self
 
+    def add_typed_connection(
+        self,
+        from_node: str,
+        from_output: str,
+        to_node: str,
+        to_input: str,
+        contract: Union[str, ConnectionContract],
+        validate_immediately: bool = False,
+    ) -> "WorkflowBuilder":
+        """
+        Add a typed connection with contract validation.
+
+        This is the new contract-based connection method that enforces
+        validation contracts on data flowing between nodes.
+
+        Args:
+            from_node: Source node ID
+            from_output: Output field from source
+            to_node: Target node ID
+            to_input: Input field on target
+            contract: Contract name (string) or ConnectionContract instance
+            validate_immediately: Whether to validate contract definitions now
+
+        Returns:
+            Self for chaining
+
+        Raises:
+            WorkflowValidationError: If contract is invalid or nodes don't exist
+            ConnectionError: If connection setup fails
+
+        Example:
+            # Using predefined contract
+            workflow.add_typed_connection(
+                "csv_reader", "data", "processor", "input_data",
+                contract="string_data"
+            )
+
+            # Using custom contract
+            custom_contract = ConnectionContract(
+                name="user_data_flow",
+                source_schema={"type": "object", "properties": {"id": {"type": "string"}}},
+                target_schema={"type": "object", "properties": {"id": {"type": "string"}}},
+                security_policies=[SecurityPolicy.NO_PII]
+            )
+            workflow.add_typed_connection(
+                "user_source", "user", "user_processor", "user_data",
+                contract=custom_contract
+            )
+        """
+        # Resolve contract
+        if isinstance(contract, str):
+            contract_obj = self._contract_registry.get(contract)
+            if not contract_obj:
+                available_contracts = self._contract_registry.list_contracts()
+                raise WorkflowValidationError(
+                    f"Contract '{contract}' not found. Available contracts: {available_contracts}"
+                )
+            contract = contract_obj
+
+        # Add the standard connection first
+        self.add_connection(from_node, from_output, to_node, to_input)
+
+        # Store the contract for this connection
+        connection_id = f"{from_node}.{from_output} → {to_node}.{to_input}"
+        self.connection_contracts[connection_id] = contract
+
+        # Immediate validation if requested
+        if validate_immediately:
+            # Validate that contract schemas are valid
+            try:
+                if contract.source_schema:
+                    from jsonschema import Draft7Validator
+
+                    Draft7Validator.check_schema(contract.source_schema)
+                if contract.target_schema:
+                    Draft7Validator.check_schema(contract.target_schema)
+            except Exception as e:
+                raise WorkflowValidationError(
+                    f"Invalid contract schema for connection {connection_id}: {e}"
+                )
+
+        logger.info(
+            f"Added typed connection '{connection_id}' with contract '{contract.name}'"
+        )
+
+        return self
+
+    def get_connection_contract(
+        self, connection_id: str
+    ) -> Optional[ConnectionContract]:
+        """
+        Get the contract for a specific connection.
+
+        Args:
+            connection_id: Connection identifier in format "from.output → to.input"
+
+        Returns:
+            ConnectionContract if found, None otherwise
+        """
+        return self.connection_contracts.get(connection_id)
+
+    def list_connection_contracts(self) -> dict[str, str]:
+        """
+        List all connection contracts in this workflow.
+
+        Returns:
+            Dict mapping connection IDs to contract names
+        """
+        return {
+            conn_id: contract.name
+            for conn_id, contract in self.connection_contracts.items()
+        }
+
+    def validate_all_contracts(self) -> tuple[bool, list[str]]:
+        """
+        Validate all connection contracts in the workflow.
+
+        Returns:
+            Tuple of (all_valid, list_of_errors)
+        """
+        errors = []
+
+        for connection_id, contract in self.connection_contracts.items():
+            try:
+                # Validate contract schemas
+                if contract.source_schema:
+                    from jsonschema import Draft7Validator
+
+                    Draft7Validator.check_schema(contract.source_schema)
+                if contract.target_schema:
+                    Draft7Validator.check_schema(contract.target_schema)
+            except Exception as e:
+                errors.append(f"Contract '{contract.name}' for {connection_id}: {e}")
+
+        return len(errors) == 0, errors
+
     def add_workflow_inputs(
         self, input_node_id: str, input_mappings: dict
     ) -> "WorkflowBuilder":
@@ -623,6 +817,13 @@ class WorkflowBuilder:
         version = metadata.pop("version", "1.0.0")
         author = metadata.pop("author", "")
 
+        # Initialize edge infrastructure if needed
+        if self._has_edge_nodes and not self._edge_infrastructure:
+            from kailash.workflow.edge_infrastructure import EdgeInfrastructure
+
+            self._edge_infrastructure = EdgeInfrastructure(self.edge_config)
+            logger.info("Initialized edge infrastructure for workflow")
+
         # Create workflow
         workflow = Workflow(
             workflow_id=workflow_id,
@@ -633,6 +834,10 @@ class WorkflowBuilder:
             metadata=metadata,
         )
 
+        # Store edge infrastructure reference in workflow metadata if present
+        if self._edge_infrastructure:
+            workflow.metadata["_edge_infrastructure"] = self._edge_infrastructure
+
         # Add nodes to workflow
         for node_id, node_info in self.nodes.items():
             try:
@@ -645,6 +850,16 @@ class WorkflowBuilder:
                     # Node class was provided
                     node_class = node_info["class"]
                     node_config = node_info.get("config", {})
+
+                    # Inject edge infrastructure if this is an edge node
+                    if self._edge_infrastructure and self._is_edge_node(
+                        node_class.__name__
+                    ):
+                        node_config["_edge_infrastructure"] = self._edge_infrastructure
+                        logger.debug(
+                            f"Injected edge infrastructure into {node_class.__name__}"
+                        )
+
                     workflow.add_node(
                         node_id=node_id, node_or_type=node_class, **node_config
                     )
@@ -652,6 +867,12 @@ class WorkflowBuilder:
                     # String node type
                     node_type = node_info["type"]
                     node_config = node_info.get("config", {})
+
+                    # Inject edge infrastructure if this is an edge node
+                    if self._edge_infrastructure and self._is_edge_node(node_type):
+                        node_config["_edge_infrastructure"] = self._edge_infrastructure
+                        logger.debug(f"Injected edge infrastructure into {node_type}")
+
                     workflow.add_node(
                         node_id=node_id, node_or_type=node_type, **node_config
                     )
@@ -711,9 +932,13 @@ class WorkflowBuilder:
                                             self.workflow_parameters[workflow_param]
                                         )
 
-        # Store workflow parameters in metadata for runtime reference
+        # Store workflow parameters and contracts in metadata for runtime reference
         workflow.metadata["workflow_parameters"] = self.workflow_parameters
         workflow.metadata["parameter_mappings"] = self.parameter_mappings
+        workflow.metadata["connection_contracts"] = {
+            conn_id: contract.to_dict()
+            for conn_id, contract in self.connection_contracts.items()
+        }
 
         logger.info(
             f"Built workflow '{workflow_id}' with "
@@ -789,6 +1014,7 @@ class WorkflowBuilder:
         self._metadata = {}
         self.workflow_parameters = {}
         self.parameter_mappings = {}
+        self.connection_contracts = {}
         return self
 
     @classmethod