omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/corpus/model_capture_config.py

@@ -0,0 +1,133 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""
+Capture configuration model for corpus capture service.
+
+.. versionadded:: 0.5.0
+    Added for CorpusCapture (OMN-1203)
+"""
+
+from collections.abc import Sequence
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums.enum_dedupe_strategy import EnumDedupeStrategy
+
+
+class ModelCaptureConfig(BaseModel):
+    """
+    Configuration for corpus capture.
+
+    Controls filtering, deduplication, and limits for captured executions.
+
+    Example:
+        >>> config = ModelCaptureConfig(
+        ...     corpus_display_name="regression-suite-v1",
+        ...     max_executions=50,
+        ...     sample_rate=0.5,
+        ...     handler_filter=("compute-handler", "effect-handler"),
+        ... )
+
+    .. versionadded:: 0.5.0
+        Added for CorpusCapture (OMN-1203)
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    corpus_display_name: str = Field(
+        ...,
+        min_length=1,
+        max_length=255,
+        description="Human-readable display name for the corpus.",
+    )
+
+    max_executions: int = Field(
+        default=50,
+        ge=1,
+        le=10000,
+        description="Maximum number of executions to capture. "
+        "Recommended max is 50 for manageable corpus sizes.",
+    )
+
+    sample_rate: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=1.0,
+        description="Probability of capturing each execution. "
+        "1.0 = capture all, 0.1 = capture 10%.",
+    )
+
+    handler_filter: tuple[str, ...] | None = Field(
+        default=None,
+        description="Whitelist of handler IDs to capture. "
+        "If None, all handlers are captured.",
+    )
+
+    time_window_start: datetime | None = Field(
+        default=None,
+        description="Start of time window for capture (inclusive). "
+        "Executions before this time are skipped.",
+    )
+
+    time_window_end: datetime | None = Field(
+        default=None,
+        description="End of time window for capture (inclusive). "
+        "Executions after this time are skipped.",
+    )
+
+    dedupe_strategy: EnumDedupeStrategy = Field(
+        default=EnumDedupeStrategy.INPUT_HASH,
+        description="Strategy for detecting duplicate executions.",
+    )
+
+    capture_timeout_ms: float = Field(
+        default=50.0,
+        ge=1.0,
+        le=5000.0,
+        description="Maximum time to wait for capture operation (ms). "
+        "If exceeded, capture is skipped and recorded as missed.",
+    )
+
+    @field_validator("handler_filter", mode="before")
+    @classmethod
+    def _convert_list_to_tuple(cls, v: Sequence[str] | None) -> tuple[str, ...] | None:
+        """Convert sequence to tuple for immutability."""
+        if v is None:
+            return None
+        return tuple(v)
+
+    def has_time_window(self) -> bool:
+        """Check if a time window filter is configured."""
+        return self.time_window_start is not None or self.time_window_end is not None
+
+    def is_in_time_window(self, timestamp: datetime) -> bool:
+        """
+        Check if a timestamp falls within the configured time window.
+
+        Args:
+            timestamp: The timestamp to check.
+
+        Returns:
+            True if within window (or no window configured).
+        """
+        if self.time_window_start is not None and timestamp < self.time_window_start:
+            return False
+        if self.time_window_end is not None and timestamp > self.time_window_end:
+            return False
+        return True
+
+    def is_handler_allowed(self, handler_id: str) -> bool:
+        """
+        Check if a handler is in the whitelist.
+
+        Args:
+            handler_id: The handler ID to check.
+
+        Returns:
+            True if allowed (or no filter configured).
+        """
+        if self.handler_filter is None:
+            return True
+        return handler_id in self.handler_filter

omnibase_infra/models/corpus/model_capture_result.py

@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""
+Capture result model for corpus capture service.
+
+.. versionadded:: 0.5.0
+    Added for CorpusCapture (OMN-1203)
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums.enum_capture_outcome import EnumCaptureOutcome
+
+
+class ModelCaptureResult(BaseModel):
+    """
+    Result of a single capture attempt.
+
+    Tracks whether an execution was captured or skipped, and why.
+
+    .. versionadded:: 0.5.0
+        Added for CorpusCapture (OMN-1203)
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    manifest_id: UUID = Field(
+        ...,
+        description="ID of the manifest that was processed.",
+    )
+
+    outcome: EnumCaptureOutcome = Field(
+        ...,
+        description="Result of the capture attempt.",
+    )
+
+    captured_at: datetime | None = Field(
+        default=None,
+        description="Timestamp when captured (None if skipped).",
+    )
+
+    dedupe_hash: str | None = Field(
+        default=None,
+        description="Hash used for deduplication (if computed).",
+    )
+
+    duration_ms: float = Field(
+        default=0.0,
+        ge=0.0,
+        description="Time taken to process the capture attempt.",
+    )
+
+    error_message: str | None = Field(
+        default=None,
+        description="Error message if capture failed.",
+    )
+
+    def __bool__(self) -> bool:
+        """
+        Return True if the execution was captured.
+
+        Warning:
+            This is non-standard Pydantic behavior. Normally ``bool(model)``
+            returns True for any model instance. This override enables
+            idiomatic ``if result:`` checks for capture success.
+        """
+        return self.outcome == EnumCaptureOutcome.CAPTURED
+
+    @property
+    def was_captured(self) -> bool:
+        """Check if the execution was captured."""
+        return self.outcome == EnumCaptureOutcome.CAPTURED
+
+    @property
+    def was_skipped(self) -> bool:
+        """Check if the execution was skipped (intentionally not captured)."""
+        return self.outcome.value.startswith("skipped_")
+
+    @property
+    def was_failed(self) -> bool:
+        """Check if the capture failed due to an error."""
+        return self.outcome == EnumCaptureOutcome.FAILED

omnibase_infra/models/discovery/__init__.py

@@ -0,0 +1,42 @@
+# Copyright 2025 OmniNode Team. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Discovery models for node introspection and capability reporting.
+
+Note:
+    ModelNodeIntrospectionEvent has been moved to omnibase_infra.models.registration.
+    Import it from there for new code.
+"""
+
+from omnibase_infra.models.discovery.model_dependency_spec import ModelDependencySpec
+from omnibase_infra.models.discovery.model_discovered_capabilities import (
+    ModelDiscoveredCapabilities,
+)
+from omnibase_infra.models.discovery.model_introspection_config import (
+    DEFAULT_HEARTBEAT_TOPIC,
+    DEFAULT_INTROSPECTION_TOPIC,
+    DEFAULT_REQUEST_INTROSPECTION_TOPIC,
+    INVALID_TOPIC_CHARS,
+    TOPIC_PATTERN,
+    VERSION_SUFFIX_PATTERN,
+    ModelIntrospectionConfig,
+)
+from omnibase_infra.models.discovery.model_introspection_performance_metrics import (
+    ModelIntrospectionPerformanceMetrics,
+)
+from omnibase_infra.models.discovery.model_introspection_task_config import (
+    ModelIntrospectionTaskConfig,
+)
+
+__all__ = [
+    "DEFAULT_HEARTBEAT_TOPIC",
+    "DEFAULT_INTROSPECTION_TOPIC",
+    "DEFAULT_REQUEST_INTROSPECTION_TOPIC",
+    "INVALID_TOPIC_CHARS",
+    "TOPIC_PATTERN",
+    "VERSION_SUFFIX_PATTERN",
+    "ModelDependencySpec",
+    "ModelDiscoveredCapabilities",
+    "ModelIntrospectionConfig",
+    "ModelIntrospectionPerformanceMetrics",
+    "ModelIntrospectionTaskConfig",
+]

omnibase_infra/models/discovery/model_dependency_spec.py

@@ -0,0 +1,319 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Dependency Specification Model.
+
+Defines the specification for declaring dependencies by capability rather than
+by concrete implementation. This enables capability-based auto-configuration
+where nodes declare what they need, not who provides it.
+
+Core Principle: "I'm interested in what you do, not what you are."
+
+Related Tickets:
+    - OMN-1135: ServiceCapabilityQuery for capability-based discovery
+    - Design: DESIGN_CAPABILITY_BASED_AUTO_CONFIGURATION.md
+
+Example:
+    >>> spec = ModelDependencySpec(
+    ...     name="storage_effect",
+    ...     type="node",
+    ...     capability="postgres.storage",
+    ...     contract_type="effect",
+    ...     intent_types=["postgres.upsert_registration"],
+    ... )
+    >>> # System auto-discovers which node provides this capability
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from omnibase_infra.enums import EnumRegistrationState, EnumSelectionStrategy
+
+
+class ModelDependencySpec(BaseModel):
+    """Dependency specification - declares what is needed, not who provides it.
+
+    This model specifies a dependency by capability attributes (capability tags,
+    intent types, protocols) rather than by concrete module paths. The runtime
+    uses ServiceCapabilityQuery to resolve these specifications to actual nodes.
+
+    Discovery Strategy (in priority order):
+        1. If capability specified -> find by capability tag
+        2. If intent_types specified -> find by intent type
+        3. If protocol specified -> find by protocol
+
+    Selection Strategy (when multiple matches):
+        - first: Return first candidate (deterministic, fast)
+        - random: Random selection (load distribution)
+        - round_robin: Cycle through candidates (even distribution)
+        - least_loaded: RESERVED FOR FUTURE USE - not yet implemented
+
+    Attributes:
+        name: Dependency name for reference in code
+        type: Dependency type (node or protocol)
+        capability: Capability tag (e.g., "consul.registration", "postgres.storage")
+        intent_types: Intent types the dependency must handle
+        protocol: Protocol the dependency must implement
+        contract_type: Filter by contract type (effect, compute, reducer, orchestrator)
+        state: Filter by registration state (default: ACTIVE)
+        selection_strategy: Strategy for selecting among multiple matches
+        fallback_module: Reserved for future - fallback module if auto-discovery fails
+        description: Human-readable description of the dependency
+
+    Example - Capability-based:
+        >>> spec = ModelDependencySpec(
+        ...     name="registry_effect",
+        ...     type="node",
+        ...     capability="consul.registration",
+        ...     contract_type="effect",
+        ... )
+
+    Example - Intent-based:
+        >>> spec = ModelDependencySpec(
+        ...     name="storage_effect",
+        ...     type="node",
+        ...     intent_types=["postgres.upsert_registration", "postgres.query"],
+        ... )
+
+    Example - Protocol-based:
+        >>> spec = ModelDependencySpec(
+        ...     name="reducer",
+        ...     type="protocol",
+        ...     protocol="ProtocolReducer",
+        ...     contract_type="reducer",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    # Identity
+    name: str = Field(
+        ...,
+        min_length=1,
+        max_length=256,
+        description="Dependency name for reference in code",
+    )
+    type: Literal["node", "protocol"] = Field(
+        ...,
+        description="Dependency type (node or protocol)",
+    )
+
+    # Capability-based discovery (choose one or combine)
+    capability: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=256,
+        description="Capability tag (e.g., 'consul.registration', 'postgres.storage')",
+    )
+    intent_types: list[str] | None = Field(
+        default=None,
+        description="Intent types the dependency must handle",
+    )
+    protocol: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=256,
+        description="Protocol the dependency must implement",
+    )
+
+    # Filters
+    contract_type: Literal["effect", "compute", "reducer", "orchestrator"] | None = (
+        Field(
+            default=None,
+            description="Filter by contract type",
+        )
+    )
+    state: EnumRegistrationState = Field(
+        default=EnumRegistrationState.ACTIVE,
+        description="Filter by registration state",
+    )
+
+    # Selection strategy (when multiple matches)
+    selection_strategy: EnumSelectionStrategy = Field(
+        default=EnumSelectionStrategy.FIRST,
+        description=(
+            "Strategy for selecting among multiple matches. "
+            "Valid values: 'first', 'random', 'round_robin'. "
+            "Note: 'least_loaded' is reserved for future use and not yet implemented."
+        ),
+    )
+
+    # Fallback (if capability not found)
+    # NOTE: Reserved for future implementation. When auto-discovery fails to find
+    # any matching nodes, this module path could be dynamically imported and
+    # instantiated as a last resort. Currently NOT used by ServiceCapabilityQuery.
+    # See: resolve_dependency() returns None when no candidates found.
+    # Future implementation would involve: importlib.import_module + class instantiation.
+    fallback_module: str | None = Field(
+        default=None,
+        description=(
+            "Reserved for future implementation. Module path to import if "
+            "auto-discovery fails (e.g., 'mypackage.adapters.FallbackAdapter'). "
+            "Currently not used by ServiceCapabilityQuery - returns None instead."
+        ),
+    )
+
+    # Documentation
+    description: str | None = Field(
+        default=None,
+        max_length=1024,
+        description="Human-readable description of the dependency",
+    )
+
+    @field_validator("intent_types", mode="before")
+    @classmethod
+    def normalize_empty_intent_types(
+        cls, v: list[str] | list[object] | None
+    ) -> list[str] | list[object] | None:
+        """Normalize empty intent_types list to None.
+
+        This ensures consistent behavior: both None and [] mean "no intent filter".
+        The has_intent_filter() method can then simply check for None.
+
+        Note:
+            With mode="before", input may be any JSON-compatible value. The type
+            hint accepts list[object] to handle unvalidated input. Pydantic will
+            validate the list contents in the "after" phase.
+
+        Args:
+            v: The intent_types value - may be list, None, or other raw input.
+
+        Returns:
+            None if v is None or empty list, otherwise the original value for
+            further validation by Pydantic.
+        """
+        if isinstance(v, list) and len(v) == 0:
+            return None
+        return v
+
+    @field_validator("selection_strategy", mode="before")
+    @classmethod
+    def normalize_selection_strategy(
+        cls, v: str | EnumSelectionStrategy
+    ) -> str | EnumSelectionStrategy:
+        """Normalize selection strategy input to handle case variations.
+
+        Accepts both string and enum input for flexibility. String inputs
+        are normalized to lowercase for case-insensitive matching.
+
+        Args:
+            v: The selection strategy value (string or enum).
+
+        Returns:
+            Normalized string (lowercase) or the original enum value.
+
+        Example:
+            >>> # These all work:
+            >>> spec = ModelDependencySpec(name="test", type="node", capability="cap",
+            ...     selection_strategy="FIRST")  # normalized to "first"
+            >>> spec = ModelDependencySpec(name="test", type="node", capability="cap",
+            ...     selection_strategy="First")  # normalized to "first"
+            >>> spec = ModelDependencySpec(name="test", type="node", capability="cap",
+            ...     selection_strategy=EnumSelectionStrategy.FIRST)  # enum preserved
+        """
+        if isinstance(v, str):
+            return v.lower()
+        return v
+
+    @field_validator("selection_strategy", mode="after")
+    @classmethod
+    def validate_selection_strategy_implemented(
+        cls, v: EnumSelectionStrategy
+    ) -> EnumSelectionStrategy:
+        """Validate that the selection strategy is implemented.
+
+        The 'least_loaded' strategy is reserved for future use and requires
+        load metrics infrastructure that is not yet available. This validator
+        provides fail-fast behavior at model creation time rather than at
+        runtime during node selection.
+
+        Args:
+            v: The selection strategy enum value to validate.
+
+        Returns:
+            The validated selection strategy enum value.
+
+        Raises:
+            ValueError: If LEAST_LOADED is specified.
+
+        Example:
+            >>> spec = ModelDependencySpec(
+            ...     name="test",
+            ...     type="node",
+            ...     capability="test.cap",
+            ...     selection_strategy="least_loaded",
+            ... )
+            ValueError: LEAST_LOADED selection strategy is not yet implemented...
+        """
+        if v == EnumSelectionStrategy.LEAST_LOADED:
+            raise ValueError(
+                "LEAST_LOADED selection strategy is not yet implemented. "
+                "Use 'first', 'random', or 'round_robin' instead."
+            )
+        return v
+
+    @model_validator(mode="after")
+    def validate_has_filter(self) -> ModelDependencySpec:
+        """Validate that at least one discovery filter is specified.
+
+        A dependency spec must have at least one of: capability, intent_types, or protocol.
+        Without any filter, the dependency cannot be resolved.
+
+        Raises:
+            ValueError: If no discovery filter is specified.
+        """
+        if not self.has_any_filter():
+            raise ValueError(
+                f"Dependency spec '{self.name}' must have at least one discovery filter: "
+                "capability, intent_types, or protocol. "
+                "Cannot resolve a dependency without any filter specified."
+            )
+        return self
+
+    def has_capability_filter(self) -> bool:
+        """Check if capability-based discovery is specified.
+
+        Returns:
+            True if capability tag is specified, False otherwise.
+        """
+        return self.capability is not None
+
+    def has_intent_filter(self) -> bool:
+        """Check if intent-based discovery is specified.
+
+        Returns:
+            True if intent_types are specified, False otherwise.
+
+        Note:
+            Empty lists are normalized to None by the normalize_empty_intent_types
+            validator, so we only need to check for None.
+        """
+        return self.intent_types is not None
+
+    def has_protocol_filter(self) -> bool:
+        """Check if protocol-based discovery is specified.
+
+        Returns:
+            True if protocol is specified, False otherwise.
+        """
+        return self.protocol is not None
+
+    def has_any_filter(self) -> bool:
+        """Check if any discovery filter is specified.
+
+        Returns:
+            True if at least one filter is specified, False otherwise.
+        """
+        return (
+            self.has_capability_filter()
+            or self.has_intent_filter()
+            or self.has_protocol_filter()
+        )
+
+
+__all__: list[str] = ["ModelDependencySpec"]

omnibase_infra/models/discovery/model_discovered_capabilities.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 OmniNode Team
+"""Model for capabilities discovered via runtime reflection."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelDiscoveredCapabilities(BaseModel):
+    """Capabilities discovered via runtime reflection.
+
+    This model represents what introspection discovers about a node at runtime,
+    as opposed to ModelNodeCapabilities which represents declared/contract capabilities.
+
+    Attributes:
+        operations: Method names matching operation keywords (execute, handle, process).
+        has_fsm: Whether the node has FSM state management.
+        method_signatures: Mapping of method names to their signature strings.
+        attributes: Additional discovered attributes (flexible JSON storage).
+
+    Example:
+        >>> caps = ModelDiscoveredCapabilities(
+        ...     operations=("execute", "query", "batch_execute"),
+        ...     has_fsm=True,
+        ...     method_signatures={"execute": "(query: str) -> list[dict]"},
+        ... )
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    operations: tuple[str, ...] = Field(
+        default=(),
+        description="Method names matching operation keywords (execute, handle, process)",
+    )
+    has_fsm: bool = Field(
+        default=False,
+        description="Whether the node has FSM state management",
+    )
+    method_signatures: dict[str, str] = Field(
+        default_factory=dict,
+        description="Mapping of method names to their signature strings",
+    )
+    attributes: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Additional discovered attributes",
+    )
+
+
+__all__ = ["ModelDiscoveredCapabilities"]