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

kailash/workflow/builder.py

@@ -4,10 +4,15 @@ import logging
 import uuid
 from typing import TYPE_CHECKING, Any, Optional, Union
 
-from kailash.nodes.base import Node
+from kailash.nodes.base import Node, NodeRegistry
 from kailash.sdk_exceptions import ConnectionError, WorkflowValidationError
 from kailash.workflow.contracts import ConnectionContract, get_contract_registry
 from kailash.workflow.graph import Workflow
+from kailash.workflow.validation import (
+    IssueSeverity,
+    ParameterDeclarationValidator,
+    ValidationIssue,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -37,6 +42,160 @@ class WorkflowBuilder:
         self.connection_contracts: dict[str, ConnectionContract] = {}
         self._contract_registry = get_contract_registry()
 
+        # Parameter validation support
+        self._param_validator = ParameterDeclarationValidator()
+
+    def _is_sdk_node(self, node_class: type) -> bool:
+        """Detect if node is SDK-provided vs custom implementation.
+
+        SDK nodes are registered in the NodeRegistry via @register_node decorator.
+        Custom nodes are not registered and require class reference usage.
+
+        Args:
+            node_class: The node class to check
+
+        Returns:
+            True if node is registered in SDK (can use string reference),
+            False if custom node (must use class reference)
+        """
+        if not hasattr(node_class, "__name__"):
+            return False
+
+        # Check if the node class is registered in the NodeRegistry
+        try:
+            registered_class = NodeRegistry.get(node_class.__name__)
+            # Check if it's the same class (identity check)
+            return registered_class is node_class
+        except Exception:
+            # Node not found in registry = custom node
+            return False
+
+    def _generate_intelligent_node_warning(self, node_class: type, node_id: str) -> str:
+        """Generate context-aware warnings based on node type.
+
+        Args:
+            node_class: The node class being added
+            node_id: The node ID
+
+        Returns:
+            Appropriate warning message for the node type
+        """
+        if self._is_sdk_node(node_class):
+            # SDK node using class reference - suggest string pattern
+            return (
+                f"SDK node detected. Consider using string reference for better compatibility:\n"
+                f"  CURRENT: add_node({node_class.__name__}, '{node_id}', {{...}})\n"
+                f"  PREFERRED: add_node('{node_class.__name__}', '{node_id}', {{...}})\n"
+                f"String references work for all @register_node() decorated SDK nodes."
+            )
+        else:
+            # Custom node using class reference - this is CORRECT
+            return (
+                f"✅ CUSTOM NODE USAGE CORRECT\n"
+                f"\n"
+                f"Pattern: add_node({node_class.__name__}, '{node_id}', {{...}})\n"
+                f"Status: This is the CORRECT pattern for custom nodes\n"
+                f"\n"
+                f'⚠️  IGNORE "preferred pattern" suggestions for custom nodes\n'
+                f"String references only work for @register_node() decorated SDK nodes.\n"
+                f"Custom nodes MUST use class references as shown above.\n"
+                f"\n"
+                f"📚 Guide: sdk-users/7-gold-standards/GOLD-STANDARD-custom-node-development-guide.md"
+            )
+
+    def validate_parameter_declarations(
+        self, warn_on_issues: bool = True
+    ) -> list[ValidationIssue]:
+        """Validate parameter declarations for all nodes in the workflow.
+
+        This method detects common parameter declaration issues that lead to
+        silent parameter dropping and debugging difficulties.
+
+        Args:
+            warn_on_issues: Whether to log warnings for detected issues
+
+        Returns:
+            List of ValidationIssue objects for any problems found
+        """
+        all_issues = []
+
+        for node_id, node_info in self.nodes.items():
+            try:
+                # Create a temporary instance to validate parameter declarations
+                if "instance" in node_info:
+                    # Use existing instance
+                    node_instance = node_info["instance"]
+                    workflow_params = {}  # Instance already has config
+                elif "class" in node_info:
+                    # Create temporary instance of custom node
+                    node_class = node_info["class"]
+                    node_config = node_info.get("config", {})
+                    # Create minimal instance just for parameter validation
+                    try:
+                        node_instance = node_class(**node_config)
+                        workflow_params = node_config
+                    except Exception as e:
+                        # If we can't create instance, skip detailed validation
+                        all_issues.append(
+                            ValidationIssue(
+                                severity=IssueSeverity.WARNING,
+                                category="parameter_declaration",
+                                code="PAR005",
+                                message=f"Could not validate parameters for custom node '{node_id}': {e}",
+                                suggestion="Ensure node constructor accepts provided configuration parameters",
+                                node_id=node_id,
+                            )
+                        )
+                        continue
+                else:
+                    # SDK node - validate if we can create it
+                    node_type = node_info["type"]
+                    node_config = node_info.get("config", {})
+                    try:
+                        # Try to get the class from registry
+                        node_class = NodeRegistry.get(node_type)
+                        node_instance = node_class(**node_config)
+                        workflow_params = node_config
+                    except Exception:
+                        # Skip validation for nodes we can't instantiate
+                        continue
+
+                # Validate parameter declarations
+                issues = self._param_validator.validate_node_parameters(
+                    node_instance, workflow_params
+                )
+
+                # Add node_id to issues
+                for issue in issues:
+                    issue.node_id = node_id
+                    all_issues.append(issue)
+
+                    # Log warnings if requested
+                    if warn_on_issues:
+                        if issue.severity == IssueSeverity.ERROR:
+                            logger.error(
+                                f"Parameter validation error in node '{node_id}': {issue.message}"
+                            )
+                        elif issue.severity == IssueSeverity.WARNING:
+                            logger.warning(
+                                f"Parameter validation warning in node '{node_id}': {issue.message}"
+                            )
+
+            except Exception as e:
+                # General validation error
+                all_issues.append(
+                    ValidationIssue(
+                        severity=IssueSeverity.WARNING,
+                        category="parameter_declaration",
+                        code="PAR006",
+                        message=f"Parameter validation failed for node '{node_id}': {e}",
+                        suggestion="Check node configuration and parameter declarations",
+                        node_id=node_id,
+                    )
+                )
+
+        return all_issues
+
     def add_node(self, *args, **kwargs) -> str:
         """
         Unified add_node method supporting multiple API patterns.
@@ -105,6 +264,9 @@ class WorkflowBuilder:
                 # Two strings - assume current API: add_node("NodeType", "node_id")
                 config = kwargs if kwargs else (args[2] if len(args) > 2 else {})
                 return self._add_node_current(args[0], args[1], config)
+            elif isinstance(args[1], dict):
+                # Pattern: add_node("NodeType", {config}) - treat as add_node("NodeType", None, {config})
+                return self._add_node_current(args[0], None, args[1])
             else:
                 # Invalid second argument
                 raise WorkflowValidationError(
@@ -202,10 +364,10 @@ class WorkflowBuilder:
         if node_id is None:
             node_id = f"node_{uuid.uuid4().hex[:8]}"
 
+        # Generate context-aware warning based on node type
+        warning_message = self._generate_intelligent_node_warning(node_class, node_id)
         warnings.warn(
-            f"Alternative API usage detected. Consider using preferred pattern:\n"
-            f"  CURRENT: add_node({node_class.__name__}, '{node_id}', {list(config.keys())})\n"
-            f"  PREFERRED: add_node('{node_class.__name__}', '{node_id}', {config})",
+            warning_message,
             UserWarning,
             stacklevel=3,
         )
@@ -838,6 +1000,23 @@ class WorkflowBuilder:
         if self._edge_infrastructure:
             workflow.metadata["_edge_infrastructure"] = self._edge_infrastructure
 
+        # Validate parameter declarations before building workflow
+        param_issues = self.validate_parameter_declarations(warn_on_issues=True)
+
+        # Check for critical parameter errors that should block workflow creation
+        critical_errors = [
+            issue for issue in param_issues if issue.severity == IssueSeverity.ERROR
+        ]
+        if critical_errors:
+            error_messages = [
+                f"{issue.node_id}: {issue.message}" for issue in critical_errors
+            ]
+            raise WorkflowValidationError(
+                "Cannot build workflow due to parameter declaration errors:\n"
+                + "\n".join(f"  - {msg}" for msg in error_messages)
+                + "\n\nSee: sdk-users/7-gold-standards/enterprise-parameter-passing-gold-standard.md"
+            )
+
         # Add nodes to workflow
         for node_id, node_info in self.nodes.items():
             try:

kailash/workflow/mermaid_visualizer.py

@@ -215,7 +215,9 @@ class MermaidVisualizer:
             Sanitized node ID safe for Mermaid
         """
         # Replace special characters with underscores
-        sanitized = node_id.replace("-", "_").replace(" ", "_").replace(".", "_")
+        import re
+
+        sanitized = re.sub(r"[^a-zA-Z0-9_]", "_", node_id)
         # Ensure it starts with a letter
         if sanitized and sanitized[0].isdigit():
             sanitized = f"node_{sanitized}"

kailash/workflow/templates.py

@@ -773,8 +773,8 @@ validation_result = {
 
         # Add report generation node if not exists
         if output not in workflow.nodes:
-            from kailash.examples.utils.data_paths import get_output_data_path
             from kailash.nodes.data import JSONWriterNode
+            from kailash.utils.data_paths import get_output_data_path
 
             workflow.add_node(
                 output,
@@ -814,8 +814,8 @@ validation_result = {
         """
         # Add document reader if not exists
         if document_reader not in workflow.nodes:
-            from kailash.examples.utils.data_paths import get_input_data_path
             from kailash.nodes.data import DirectoryReaderNode
+            from kailash.utils.data_paths import get_input_data_path
 
             workflow.add_node(
                 document_reader,
@@ -907,8 +907,8 @@ result = {
 
         # Add output writer if not exists
         if output not in workflow.nodes:
-            from kailash.examples.utils.data_paths import get_output_data_path
             from kailash.nodes.data import JSONWriterNode
+            from kailash.utils.data_paths import get_output_data_path
 
             workflow.add_node(
                 output,
@@ -1060,8 +1060,8 @@ validated_result = {
 
         # Add output node if not exists
         if output not in workflow.nodes:
-            from kailash.examples.utils.data_paths import get_output_data_path
             from kailash.nodes.data import JSONWriterNode
+            from kailash.utils.data_paths import get_output_data_path
 
             workflow.add_node(
                 output,
@@ -1106,8 +1106,8 @@ validated_result = {
         """
         # Add data reader if not exists
         if data_reader not in workflow.nodes:
-            from kailash.examples.utils.data_paths import get_input_data_path
             from kailash.nodes.data import CSVReaderNode
+            from kailash.utils.data_paths import get_input_data_path
 
             workflow.add_node(
                 data_reader,
@@ -1304,8 +1304,8 @@ result = {
 
         # Add data writer if not exists
         if writer not in workflow.nodes:
-            from kailash.examples.utils.data_paths import get_output_data_path
             from kailash.nodes.data import JSONWriterNode
+            from kailash.utils.data_paths import get_output_data_path
 
             workflow.add_node(
                 writer,

kailash/workflow/validation.py

@@ -116,9 +116,11 @@ See Also:
 import re
 from dataclasses import dataclass
 from enum import Enum
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from . import Workflow
+# Note: Workflow import moved to individual methods to avoid circular imports
+if TYPE_CHECKING:
+    from kailash.workflow.graph import Workflow
 
 
 class IssueSeverity(Enum):
@@ -143,6 +145,135 @@ class ValidationIssue:
     documentation_link: str | None = None
 
 
+class ParameterDeclarationValidator:
+    """Validator for node parameter declarations - detects silent parameter dropping issues.
+
+    This validator addresses the critical issue where nodes with empty get_parameters()
+    methods silently receive no workflow parameters, leading to debugging issues.
+
+    Key validations:
+    1. Empty parameter declarations (PAR001 - WARNING at build time, enforced at runtime)
+    2. Undeclared parameter access attempts (PAR002 - WARNING)
+    3. Parameter type validation issues (PAR003 - WARNING)
+    4. Missing required parameters in workflow (PAR004 - WARNING at build time, ERROR at runtime)
+
+    Usage:
+        validator = ParameterDeclarationValidator()
+        issues = validator.validate_node_parameters(node_instance, workflow_params)
+    """
+
+    validation_code = "PAR"
+
+    def validate_node_parameters(
+        self, node_instance, workflow_parameters: dict[str, Any]
+    ) -> list[ValidationIssue]:
+        """Check parameter declarations against workflow usage.
+
+        Args:
+            node_instance: Node instance to validate
+            workflow_parameters: Parameters provided by workflow
+
+        Returns:
+            List of ValidationIssue objects for any problems found
+        """
+        issues = []
+
+        try:
+            declared_params = node_instance.get_parameters()
+        except Exception as e:
+            issues.append(
+                ValidationIssue(
+                    severity=IssueSeverity.ERROR,
+                    category="parameter_declaration",
+                    code="PAR000",
+                    message=f"Node {node_instance.__class__.__name__} get_parameters() failed: {e}",
+                    suggestion="Fix get_parameters() method implementation",
+                    documentation_link="sdk-users/7-gold-standards/enterprise-parameter-passing-gold-standard.md",
+                )
+            )
+            return issues
+
+        # Critical: Empty parameter declarations (addresses gold standard issue #2)
+        # For backwards compatibility, downgrade to WARNING at build time
+        if not declared_params and workflow_parameters:
+            workflow_param_names = list(workflow_parameters.keys())
+            issues.append(
+                ValidationIssue(
+                    severity=IssueSeverity.WARNING,
+                    category="parameter_declaration",
+                    code="PAR001",
+                    message=f"Node {node_instance.__class__.__name__} declares no parameters but workflow provides {workflow_param_names}",
+                    suggestion="Add parameters to get_parameters() method - SDK only injects explicitly declared parameters",
+                    documentation_link="sdk-users/7-gold-standards/enterprise-parameter-passing-gold-standard.md#parameter-declaration-security",
+                )
+            )
+
+        # Security: Undeclared parameter access attempts
+        if declared_params and workflow_parameters:
+            undeclared = set(workflow_parameters.keys()) - set(declared_params.keys())
+            if undeclared:
+                issues.append(
+                    ValidationIssue(
+                        severity=IssueSeverity.WARNING,
+                        category="parameter_declaration",
+                        code="PAR002",
+                        message=f"Workflow parameters {list(undeclared)} not declared in get_parameters() - will be ignored by SDK",
+                        suggestion="Add missing parameters to get_parameters() or remove from workflow configuration",
+                    )
+                )
+
+        # Validation: Parameter type issues
+        if declared_params:
+            for param_name, param_def in declared_params.items():
+                if not hasattr(param_def, "type") or param_def.type is None:
+                    issues.append(
+                        ValidationIssue(
+                            severity=IssueSeverity.WARNING,
+                            category="parameter_declaration",
+                            code="PAR003",
+                            message=f"Parameter '{param_name}' missing type definition",
+                            suggestion=f"Add type field to NodeParameter: NodeParameter(name='{param_name}', type=str, ...)",
+                        )
+                    )
+
+                # Check for required parameters without defaults
+                if (
+                    getattr(param_def, "required", False)
+                    and param_name not in workflow_parameters
+                ):
+                    if getattr(param_def, "default", None) is None:
+                        # For backwards compatibility, missing required parameters are WARNING at build time
+                        # They'll still cause runtime errors when the node executes
+                        issues.append(
+                            ValidationIssue(
+                                severity=IssueSeverity.WARNING,
+                                category="parameter_declaration",
+                                code="PAR004",
+                                message=f"Required parameter '{param_name}' not provided by workflow and has no default",
+                                suggestion=f"Either provide '{param_name}' in workflow configuration or add default value",
+                            )
+                        )
+
+        return issues
+
+    def validate_workflow_node_parameters(self, workflow) -> list[ValidationIssue]:
+        """Validate parameter declarations for all nodes in a workflow.
+
+        Args:
+            workflow: Workflow instance to validate
+
+        Returns:
+            List of all parameter declaration issues across the workflow
+        """
+        all_issues = []
+
+        # This would need workflow.nodes to be iterable with node instances
+        # For now, we'll focus on the single-node validation method
+        # Implementation would depend on workflow structure
+
+        return all_issues
+
+
 class CycleLinter:
     """
     Comprehensive linter for cyclic workflows.
@@ -151,7 +282,7 @@ class CycleLinter:
     and potential problems specific to cyclic execution.
     """
 
-    def __init__(self, workflow: Workflow):
+    def __init__(self, workflow: "Workflow"):
         """
         Initialize linter with target workflow.
 

{kailash-0.8.5.dist-info → kailash-0.8.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kailash
-Version: 0.8.5
+Version: 0.8.7
 Summary: Python SDK for the Kailash container-node architecture
 Home-page: https://github.com/integrum/kailash-python-sdk
 Author: Integrum
@@ -81,6 +81,7 @@ Requires-Dist: opentelemetry-instrumentation-fastapi>=0.55b1
 Requires-Dist: seaborn>=0.13.2
 Requires-Dist: sqlparse>=0.5.3
 Requires-Dist: jsonschema>=4.24.0
+Requires-Dist: openai>=1.97.1
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=3.0; extra == "dev"
@@ -116,18 +117,18 @@ Dynamic: requires-python
 
 ---
 
-## 🔥 Latest Release: v0.8.4 (January 19, 2025)
+## 🔥 Latest Release: v0.8.5 (January 20, 2025)
 
-**A2A Google Protocol Enhancement**
+**Architecture Cleanup & Enterprise Security**
 
-- 🤖 **Advanced Agent Coordination**: A2ACoordinatorNode with Google Protocol best practices
-- 🎯 **Intelligent Task Delegation**: Context-aware task distribution with skill-based matching
-- 🔍 **Hybrid Search Capabilities**: Multi-strategy agent discovery and matching algorithms
-- 🧠 **Semantic Memory System**: Long-term memory management for agent interactions
-- 📊 **Real-time Analytics**: Streaming performance monitoring for A2A workflows
-- ✅ **Backward Compatible**: Seamless integration with existing A2A implementations
+- 🏗️ **Architecture Clarity**: Removed confusing `src/kailash/nexus` module
+- 🔒 **Connection Validation**: Enterprise-grade parameter validation with type safety
+- 🌐 **Edge Computing**: 50+ new nodes for geo-distributed infrastructure
+- 📊 **Advanced Monitoring**: AlertManager with proactive threshold monitoring
+- 🚀 **Performance**: <1ms validation overhead with intelligent caching
+- ✅ **Breaking Changes**: See [migration guide](sdk-users/6-reference/changelogs/releases/v0.8.5-2025-07-20.md)
 
-[Full Changelog](CHANGELOG.md) | [PyPI Packages](https://pypi.org/project/kailash/0.8.4/)
+[Full Changelog](sdk-users/6-reference/changelogs/releases/v0.8.5-2025-07-20.md) | [PyPI Packages](https://pypi.org/project/kailash/0.8.5/)
 
 ## 🎯 What Makes Kailash Different
 
@@ -344,7 +345,7 @@ results, run_id = runtime.execute(workflow.build())
 
 ## 🚀 Applications Built with Kailash
 
-### 1. DataFlow - Zero-Config Database Platform
+### 1. DataFlow - Zero-Config Database Platform (v0.3.1)
 ```bash
 pip install kailash-dataflow
 ```
@@ -352,8 +353,9 @@ pip install kailash-dataflow
 - **Redis caching** with enterprise-grade invalidation
 - **Automatic API generation** with OpenAPI documentation
 - **4 production examples** with complete deployment guides
+- **Latest**: v0.3.1 - Enhanced transaction support and schema management
 
-### 2. Nexus - Multi-Channel Platform
+### 2. Nexus - Multi-Channel Platform (v1.0.3)
 ```bash
 pip install kailash-nexus
 ```
@@ -361,6 +363,7 @@ pip install kailash-nexus
 - **Enterprise orchestration** with multi-tenancy
 - **Session management** with cross-channel synchronization
 - **105 tests** with comprehensive validation
+- **Latest**: v1.0.3 - Production-ready release with enhanced stability
 
 ### 3. AI Registry - Advanced RAG Platform
 ```bash
@@ -421,8 +424,8 @@ pytest tests/e2e/ --timeout=10
 
 ### For Users
 - **[SDK Users Guide](sdk-users/)**: Complete workflow development guide
-- **[Node Selection Guide](sdk-users/nodes/node-selection-guide.md)**: Smart node selection with decision trees
-- **[Enterprise Patterns](sdk-users/enterprise/)**: Production deployment patterns
+- **[Node Selection Guide](sdk-users/2-core-concepts/nodes/node-selection-guide.md)**: Smart node selection with decision trees
+- **[Enterprise Patterns](sdk-users/5-enterprise/)**: Production deployment patterns
 - **[API Documentation](https://integrum.github.io/kailash-python-sdk)**: Complete API reference
 
 ### For Contributors
@@ -431,9 +434,9 @@ pytest tests/e2e/ --timeout=10
 - **[Testing Guide](tests/README.md)**: 3-tier testing strategy
 
 ### Quick References
-- **[Cheatsheet](sdk-users/cheatsheet/)**: 53 copy-paste patterns
-- **[Common Mistakes](sdk-users/validation/common-mistakes.md)**: Error patterns and solutions
-- **[Performance Guide](sdk-users/performance/)**: Optimization patterns
+- **[Cheatsheet](sdk-users/2-core-concepts/cheatsheet/)**: 53 copy-paste patterns
+- **[Common Mistakes](sdk-users/2-core-concepts/validation/common-mistakes.md)**: Error patterns and solutions
+- **[Performance Guide](sdk-users/5-enterprise/performance/)**: Optimization patterns
 
 ## 🚢 Production Deployment