omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/plugins/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Compute plugin infrastructure for deterministic business logic.
+
+This module provides the foundation for in-process, deterministic computation
+that complements external effect handlers.
+
+Components:
+    - PluginComputeBase: Abstract base class with validation hooks
+
+Architecture:
+    Compute plugins perform pure computation with NO side effects:
+    - NO external I/O (network, filesystem, database)
+    - NO random number generation (unless seeded)
+    - NO current time access (unless passed in context)
+    - Deterministic: same inputs = same outputs
+    - Replayable for debugging and testing
+
+See Also:
+    - omnibase_infra.protocols.ProtocolPluginCompute for protocol definition
+"""
+
+from omnibase_infra.plugins.plugin_compute_base import PluginComputeBase
+
+__all__ = [
+    "PluginComputeBase",
+]

omnibase_infra/plugins/examples/__init__.py

@@ -0,0 +1,28 @@
+"""Example compute plugins demonstrating deterministic computation patterns.
+
+This module contains reference implementations that demonstrate best practices
+for compute plugin development.
+
+Available Examples:
+    - PluginJsonNormalizer - Deterministic JSON key sorting for comparison
+
+Usage:
+    ```python
+    from omnibase_infra.plugins.examples import PluginJsonNormalizer
+
+    plugin = PluginJsonNormalizer()
+    result = plugin.execute(
+        input_data={"json": {"z": 3, "a": 1}},
+        context={"correlation_id": "123"}
+    )
+    # result["normalized"] == {"a": 1, "z": 3}
+    ```
+"""
+
+from omnibase_infra.plugins.examples.plugin_json_normalizer import (
+    PluginJsonNormalizer,
+)
+
+__all__ = [
+    "PluginJsonNormalizer",
+]

omnibase_infra/plugins/examples/plugin_json_normalizer.py

@@ -0,0 +1,271 @@
+"""JSON normalization plugin for deterministic comparison.
+
+This plugin recursively sorts JSON object keys to enable consistent comparison
+and hashing. It demonstrates a pure, deterministic compute plugin with no side effects.
+"""
+
+from typing import TypedDict, cast
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_core.errors import OnexError
+from omnibase_infra.plugins.plugin_compute_base import PluginComputeBase
+from omnibase_infra.protocols.protocol_plugin_compute import (
+    ModelPluginContext,
+    ModelPluginInputData,
+    ModelPluginOutputData,
+)
+
+
+class JsonNormalizerInput(TypedDict, total=False):
+    """Type-safe input structure for JSON normalizer.
+
+    Fields:
+        json: The JSON-compatible data structure to normalize.
+    """
+
+    json: object
+
+
+class JsonNormalizerOutput(TypedDict):
+    """Type-safe output structure for JSON normalizer.
+
+    Fields:
+        normalized: The normalized JSON structure with recursively sorted keys.
+    """
+
+    normalized: object
+
+
+class PluginJsonNormalizer(PluginComputeBase):
+    """Normalizes JSON structures for deterministic comparison.
+
+    Attributes:
+        MAX_RECURSION_DEPTH: Maximum allowed nesting depth for JSON structures.
+            Defaults to 100 levels. Override in subclass if needed.
+    """
+
+    __slots__ = ()  # Enforce statelessness - no instance attributes
+
+    MAX_RECURSION_DEPTH: int = 100
+
+    def execute(
+        self, input_data: ModelPluginInputData, context: ModelPluginContext
+    ) -> ModelPluginOutputData:
+        """Execute JSON normalization with type-safe inputs and outputs.
+
+        Args:
+            input_data: Dictionary containing "json" key with data to normalize
+            context: Execution context containing:
+                - correlation_id: For error tracing
+                - max_recursion_depth: Optional override for MAX_RECURSION_DEPTH
+
+        Returns:
+            Dictionary with "normalized" key containing sorted JSON
+
+        Raises:
+            OnexError: For all computation failures (with proper error chaining)
+        """
+        correlation_id = context.get("correlation_id")
+
+        # Allow context to override max recursion depth for specific use cases
+        max_depth_override = context.get("max_recursion_depth")
+        if max_depth_override is not None and isinstance(max_depth_override, int):
+            effective_max_depth = max_depth_override
+        else:
+            effective_max_depth = self.MAX_RECURSION_DEPTH
+
+        try:
+            json_data = cast("object", input_data.get("json", {}))
+            normalized: object = self._sort_keys_recursively(
+                json_data, _max_depth=effective_max_depth
+            )
+            output: JsonNormalizerOutput = {"normalized": normalized}
+            return cast("ModelPluginOutputData", output)
+
+        except RecursionError as e:
+            raise OnexError(
+                message="JSON structure too deeply nested for normalization",
+                error_code=EnumCoreErrorCode.INTERNAL_ERROR,
+                correlation_id=correlation_id,
+                plugin_name=self.__class__.__name__,
+                max_recursion_depth=effective_max_depth,
+            ) from e
+
+        except Exception as e:
+            raise OnexError(
+                message=f"Unexpected error during JSON normalization: {e}",
+                error_code=EnumCoreErrorCode.INTERNAL_ERROR,
+                correlation_id=correlation_id,
+                plugin_name=self.__class__.__name__,
+                input_keys=list(input_data.keys())
+                if isinstance(input_data, dict)
+                else [],
+            ) from e
+
+    def _sort_keys_recursively(
+        self, obj: object, _depth: int = 0, _max_depth: int | None = None
+    ) -> object:
+        """Recursively sort dictionary keys with optimized performance and depth protection.
+
+        Performance Characteristics:
+            - Time Complexity: O(n * k log k) where n is total nodes, k is keys per dict
+            - Space Complexity: O(d) where d is maximum depth (recursion stack)
+            - Optimizations:
+              * Early type checking for primitives (most common case)
+              * Sorted key iteration for dicts (single pass over items)
+              * No redundant operations or object creation
+
+        Large Structure Performance:
+            For JSON with 1000+ keys, this implementation:
+            - Minimizes object creation overhead
+            - Uses sorted() efficiently (Timsort O(n log k))
+            - Avoids redundant type checks
+            - Maintains deterministic behavior
+
+        Depth Protection:
+            To prevent stack overflow on deeply nested structures, recursion depth
+            is limited to _max_depth (default: MAX_RECURSION_DEPTH = 100 levels).
+            This protects against maliciously crafted or malformed JSON that could
+            exhaust the Python call stack.
+
+        Args:
+            obj: JSON-compatible object (dict, list, or primitive)
+            _depth: Internal depth counter for recursion protection. Do not set
+                manually; this is tracked automatically during recursion.
+            _max_depth: Maximum allowed recursion depth. If None, uses
+                MAX_RECURSION_DEPTH class attribute. Can be overridden via
+                context["max_recursion_depth"] in execute().
+
+        Returns:
+            Object with recursively sorted keys (if dict), or original value
+
+        Raises:
+            RecursionError: If nesting depth exceeds maximum allowed depth.
+
+        Note:
+            - Dicts: Sorted by key name (alphabetically)
+            - Lists: Items processed recursively, order preserved
+            - Primitives: Returned unchanged (early exit for performance)
+        """
+        effective_max = (
+            _max_depth if _max_depth is not None else self.MAX_RECURSION_DEPTH
+        )
+
+        # Depth protection to prevent stack overflow on deeply nested structures
+        if _depth > effective_max:
+            raise RecursionError(
+                f"JSON structure exceeds maximum nesting depth of "
+                f"{effective_max} levels"
+            )
+
+        # Early exit for primitives (most common case in large structures)
+        # This optimization avoids isinstance checks for dict/list on every primitive
+        if not isinstance(obj, dict | list):
+            return obj
+
+        if isinstance(obj, dict):
+            return {
+                k: self._sort_keys_recursively(v, _depth + 1, _max_depth=effective_max)
+                for k, v in sorted(obj.items())
+            }
+
+        # Must be a list at this point
+        return [
+            self._sort_keys_recursively(item, _depth + 1, _max_depth=effective_max)
+            for item in obj
+        ]
+
+    def validate_input(self, input_data: ModelPluginInputData) -> None:
+        """Validate input with runtime type checking and type guards.
+
+        This method validates input structure before execution. By protocol design,
+        context is NOT available during validation - only the raw input_data.
+
+        Error Handling Contract:
+            This method raises TypeError/ValueError for validation failures.
+            These are intentionally NOT wrapped in OnexError here because:
+            1. Context (with correlation_id) is not available in validate_input
+            2. The caller (registry/executor) wraps these in OnexError with context
+            3. This follows the ONEX plugin validation hook pattern
+
+            For example, the plugin executor wraps validation errors:
+            ```
+            try:
+                plugin.validate_input(input_data)
+            except (TypeError, ValueError) as e:
+                raise OnexError(
+                    message=str(e),
+                    error_code=EnumCoreErrorCode.VALIDATION_ERROR,
+                    correlation_id=context.get("correlation_id"),
+                ) from e
+            ```
+
+        Args:
+            input_data: The input data to validate (context not available here)
+
+        Raises:
+            TypeError: If input_data is not a dict. Caller wraps in OnexError.
+            ValueError: If "json" key exists but is not JSON-compatible type.
+                Caller wraps in OnexError with correlation_id from context.
+            OnexError: If JSON structure exceeds maximum nesting depth (direct
+                raise since this is an internal error, not a validation error).
+        """
+        if not isinstance(input_data, dict):
+            raise TypeError(f"input_data must be dict, got {type(input_data).__name__}")
+
+        if "json" not in input_data:
+            return
+
+        json_data = input_data["json"]
+        if not self._is_json_compatible(json_data):
+            raise ValueError(
+                f"Input 'json' must be JSON-compatible type, got {type(json_data).__name__}"
+            )
+
+        try:
+            self._validate_json_structure(json_data)
+        except RecursionError as e:
+            raise OnexError(
+                message="JSON structure too deeply nested for validation",
+                error_code=EnumCoreErrorCode.INTERNAL_ERROR,
+                plugin_name=self.__class__.__name__,
+                max_recursion_depth=self.MAX_RECURSION_DEPTH,
+            ) from e
+
+    def _is_json_compatible(self, value: object) -> bool:
+        """Type guard to check if value is JSON-compatible."""
+        return isinstance(value, dict | list | str | int | float | bool | type(None))
+
+    def _validate_json_structure(self, obj: object, _depth: int = 0) -> None:
+        """Recursively validate JSON structure for non-JSON-compatible types.
+
+        Args:
+            obj: JSON-compatible object to validate
+            _depth: Internal depth counter for recursion protection. Do not set
+                manually; this is tracked automatically during recursion.
+
+        Raises:
+            ValueError: If non-JSON-compatible types are found
+            RecursionError: If nesting depth exceeds MAX_RECURSION_DEPTH levels
+        """
+        # Depth protection to prevent stack overflow during validation
+        if _depth > self.MAX_RECURSION_DEPTH:
+            raise RecursionError(
+                f"JSON structure exceeds maximum nesting depth of "
+                f"{self.MAX_RECURSION_DEPTH} levels"
+            )
+
+        if isinstance(obj, dict):
+            for key, value in obj.items():
+                if not self._is_json_compatible(value):
+                    raise ValueError(
+                        f"Non-JSON-compatible value in dict at key '{key}': {type(value).__name__}"
+                    )
+                self._validate_json_structure(value, _depth + 1)
+        elif isinstance(obj, list):
+            for index, item in enumerate(obj):
+                if not self._is_json_compatible(item):
+                    raise ValueError(
+                        f"Non-JSON-compatible value in list at index {index}: {type(item).__name__}"
+                    )
+                self._validate_json_structure(item, _depth + 1)

omnibase_infra/plugins/examples/plugin_json_normalizer_error_handling.py

@@ -0,0 +1,210 @@
+"""JSON normalization plugin demonstrating ONEX error handling standards.
+
+This plugin recursively sorts JSON object keys to enable consistent comparison
+and hashing. It demonstrates a pure, deterministic compute plugin with comprehensive
+error handling following ONEX standards.
+
+Error Handling:
+    This plugin demonstrates ONEX error handling standards:
+    - OnexError chaining for all exceptions
+    - Correlation ID propagation from context
+    - Never suppress errors silently
+    - Preserve full error context for debugging
+
+Example Error Scenarios:
+    1. Invalid input type (non-JSON-compatible)
+    2. Deeply nested structures causing recursion errors
+    3. Malformed input data structures
+"""
+
+from typing import cast
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_core.errors import OnexError
+from omnibase_infra.plugins.plugin_compute_base import PluginComputeBase
+from omnibase_infra.protocols.protocol_plugin_compute import (
+    ModelPluginContext,
+    ModelPluginInputData,
+    ModelPluginOutputData,
+)
+
+
+class PluginJsonNormalizerErrorHandling(PluginComputeBase):
+    """JSON normalizer with comprehensive ONEX error handling.
+
+    This is an enhanced version of PluginJsonNormalizer that demonstrates
+    proper error handling patterns following ONEX standards.
+    """
+
+    __slots__ = ()  # Enforce statelessness - no instance attributes
+
+    def execute(
+        self, input_data: ModelPluginInputData, context: ModelPluginContext
+    ) -> ModelPluginOutputData:
+        """Execute JSON normalization with comprehensive error handling.
+
+        Args:
+            input_data: Dictionary containing "json" key with data to normalize
+            context: Execution context (correlation_id, timestamps, etc.)
+
+        Returns:
+            Dictionary with "normalized" key containing sorted JSON
+
+        Raises:
+            OnexError: For all computation failures (with proper error chaining)
+
+        Error Handling Examples:
+            ```python
+            from omnibase_core.errors import OnexError
+            from uuid import uuid4
+
+            # Example 1: Recursion depth error
+            try:
+                deeply_nested = create_deeply_nested_dict(depth=1500)
+                plugin.execute({"json": deeply_nested}, {"correlation_id": uuid4()})
+            except OnexError as e:
+                assert e.model.error_code == EnumCoreErrorCode.INTERNAL_ERROR
+                assert e.model.correlation_id is not None
+                assert e.model.details["max_recursion_depth"] == 1000
+
+            # Example 2: Unexpected error
+            try:
+                plugin.execute({"json": valid_data}, {"correlation_id": uuid4()})
+            except OnexError as e:
+                assert e.model.error_code == EnumCoreErrorCode.INTERNAL_ERROR
+                assert "input_keys" in e.model.details
+            ```
+        """
+        # Extract correlation_id for error handling and tracing
+        correlation_id = context.get("correlation_id", "unknown")
+
+        try:
+            # Retrieve JSON data with safe default
+            json_data = cast("object", input_data.get("json", {}))
+
+            # Perform pure deterministic computation
+            normalized = self._sort_keys_recursively(json_data)
+
+            # Return result with correlation_id for tracing
+            return cast(
+                "ModelPluginOutputData",
+                {
+                    "normalized": normalized,
+                    "correlation_id": correlation_id,
+                },
+            )
+
+        except RecursionError as e:
+            # Handle deeply nested structures exceeding Python's recursion limit
+            raise OnexError(
+                message="JSON structure too deeply nested for normalization",
+                error_code=EnumCoreErrorCode.INTERNAL_ERROR,
+                correlation_id=correlation_id,
+                plugin_name=self.__class__.__name__,
+                max_recursion_depth=1000,  # Python's default recursion limit
+                input_depth_estimate="exceeded",
+            ) from e
+
+        except TypeError as e:
+            # Handle type errors during sorting (e.g., comparing incompatible types)
+            raise OnexError(
+                message=f"Type error during JSON normalization: {e}",
+                error_code=EnumCoreErrorCode.INTERNAL_ERROR,
+                correlation_id=correlation_id,
+                plugin_name=self.__class__.__name__,
+                input_keys=list(input_data.model_dump().keys()),
+            ) from e
+
+        except Exception as e:
+            # Catch-all for unexpected errors (should not happen in pure computation)
+            raise OnexError(
+                message=f"Unexpected error during JSON normalization: {e}",
+                error_code=EnumCoreErrorCode.INTERNAL_ERROR,
+                correlation_id=correlation_id,
+                plugin_name=self.__class__.__name__,
+                input_keys=list(input_data.model_dump().keys()),
+                exception_type=type(e).__name__,
+            ) from e
+
+    def _sort_keys_recursively(self, obj: object) -> object:
+        """Recursively sort dictionary keys.
+
+        Args:
+            obj: JSON-compatible object (dict, list, or primitive)
+
+        Returns:
+            Object with recursively sorted keys (if dict), or original value
+
+        Raises:
+            RecursionError: If nesting exceeds Python's recursion limit
+            TypeError: If comparing incompatible types during sorting
+
+        Note:
+            - Dicts: Sorted by key name (alphabetically)
+            - Lists: Items processed recursively, order preserved
+            - Primitives: Returned unchanged
+            - This method does not include explicit depth protection unlike
+              the main PluginJsonNormalizer. It relies on Python's default
+              recursion limit for simplicity in this error handling example.
+        """
+        if isinstance(obj, dict):
+            # Sort keys and recursively process values
+            # May raise TypeError if keys are incomparable
+            return {k: self._sort_keys_recursively(v) for k, v in sorted(obj.items())}
+
+        if isinstance(obj, list):
+            # Recursively process list items, preserve order
+            # May raise RecursionError if deeply nested
+            return [self._sort_keys_recursively(item) for item in obj]
+
+        # Primitive values (str, int, float, bool, None) returned unchanged
+        return obj
+
+    def validate_input(self, input_data: ModelPluginInputData) -> None:
+        """Validate that input contains JSON-compatible data.
+
+        Args:
+            input_data: The input data to validate
+
+        Raises:
+            ValueError: If "json" key exists but is not JSON-compatible type.
+                Caller should wrap in OnexError with correlation_id.
+
+        Error Handling:
+            This method raises ValueError for invalid input types. The caller
+            (node/executor) is responsible for catching and wrapping in OnexError.
+
+        Example Caller Wrapping:
+            ```python
+            from omnibase_core.errors import OnexError
+            from omnibase_core.enums import EnumCoreErrorCode
+
+            correlation_id = context.get("correlation_id", "unknown")
+
+            try:
+                plugin.validate_input(input_data)
+            except ValueError as e:
+                raise OnexError(
+                    message=f"Input validation failed: {e}",
+                    error_code=EnumCoreErrorCode.INVALID_INPUT,
+                    correlation_id=correlation_id,
+                    plugin_name="PluginJsonNormalizerErrorHandling",
+                    expected_types=["dict", "list", "str", "int", "float", "bool", "None"],
+                    actual_type=type(input_data.get("json")).__name__,
+                ) from e
+            ```
+
+        Note:
+            Missing "json" key is valid - plugin returns empty normalized dict.
+        """
+        json_data = input_data.get("json")
+        if json_data is not None:
+            # Ensure it's a JSON-compatible type
+            if not isinstance(
+                json_data, dict | list | str | int | float | bool | type(None)
+            ):
+                raise ValueError(
+                    f"Input 'json' must be JSON-compatible type "
+                    f"(dict, list, str, int, float, bool, None), "
+                    f"got {type(json_data).__name__}"
+                )

omnibase_infra/plugins/models/__init__.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pydantic models for compute plugins.
+
+This module exports the core data models used by compute plugins:
+- ModelPluginInputData: Base input data model for plugins
+- ModelPluginContext: Execution context model for plugins
+- ModelPluginOutputData: Base output data model for plugins
+
+These models replace TypedDict definitions to conform to ONEX coding standards.
+"""
+
+from omnibase_infra.plugins.models.model_plugin_context import ModelPluginContext
+from omnibase_infra.plugins.models.model_plugin_input_data import ModelPluginInputData
+from omnibase_infra.plugins.models.model_plugin_output_data import ModelPluginOutputData
+
+__all__ = [
+    "ModelPluginContext",
+    "ModelPluginInputData",
+    "ModelPluginOutputData",
+]

omnibase_infra/plugins/models/model_plugin_context.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pydantic model for plugin execution context.
+
+This module provides the ModelPluginContext Pydantic BaseModel that replaces
+the former PluginContext TypedDict definition.
+
+Design Notes:
+    - Uses ConfigDict(extra="allow") to support arbitrary fields
+    - Supports dict-like access via __getitem__ for flexible API usage
+    - Can be instantiated from dicts using model_validate()
+    - Follows ONEX naming convention: Model<Name>
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+from omnibase_infra.mixins import MixinDictLikeAccessors
+
+
+class ModelPluginContext(MixinDictLikeAccessors, BaseModel):
+    """Base Pydantic model for plugin execution context.
+
+    This model replaces PluginContext TypedDict and provides structured
+    context for plugin execution including correlation IDs and metadata.
+
+    Common Fields:
+        correlation_id: UUID for distributed tracing
+        execution_timestamp: When execution started (ISO format string)
+        plugin_config: Plugin-specific configuration parameters
+        metadata: Additional metadata for observability
+        random_seed: Seed for deterministic randomness (optional)
+
+    Configuration:
+        - extra="allow": Accepts arbitrary additional fields
+        - frozen=False: Allows mutation (though plugins should not mutate)
+        - populate_by_name=True: Allows field access by alias
+
+    Example:
+        ```python
+        context = ModelPluginContext(
+            correlation_id="test-uuid-123",
+            execution_timestamp="2025-01-15T12:00:00Z",
+            plugin_config={"max_depth": 10},
+        )
+
+        # Access with get (dict-like)
+        corr_id = context.get("correlation_id", "unknown")
+        ```
+
+    Note:
+        All fields are optional (extra="allow"). Plugins should document
+        which context fields they require.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        frozen=False,
+        populate_by_name=True,
+        from_attributes=True,  # pytest-xdist compatibility
+    )
+
+    # Common context fields - all optional with defaults
+    # Note: execution_timestamp uses str for ISO format timestamps
+    # Integer epoch timestamps should be converted to ISO strings
+    # Using empty string/dict defaults to reduce union count while maintaining optionality
+    correlation_id: str = ""
+    execution_timestamp: str = ""
+    random_seed: int | None = None  # Must stay nullable - 0 is a valid seed
+    plugin_config: dict[str, JsonType] = Field(default_factory=dict)
+    metadata: dict[str, JsonType] = Field(default_factory=dict)
+
+
+__all__: list[str] = ["ModelPluginContext"]