omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/capabilities/capability_inference_rules.py

@@ -0,0 +1,211 @@
+"""Capability inference rules for deriving tags from contract structure.
+
+This module provides deterministic pattern matching to infer capability tags
+from contract fields like intent_types and protocols. Rules are injectable
+via constructor for extensibility while providing sensible defaults.
+"""
+
+from __future__ import annotations
+
+
+class CapabilityInferenceRules:
+    """Code-driven capability inference rules with injectable patterns.
+
+    Deterministic pattern matching for inferring capability_tags from
+    contract structure. All rule mappings are injectable via constructor
+    while providing sensible defaults.
+
+    Args:
+        intent_patterns: Custom/additional intent patterns (merged with defaults).
+        protocol_tags: Custom/additional protocol tags (merged with defaults).
+        node_type_tags: Custom/additional node type tags (merged with defaults).
+
+    Example:
+        # Use defaults
+        rules = CapabilityInferenceRules()
+
+        # Override specific pattern
+        rules = CapabilityInferenceRules(
+            intent_patterns={"redis.": "redis.caching"}
+        )
+
+        # Override existing pattern
+        rules = CapabilityInferenceRules(
+            intent_patterns={"postgres.": "custom.database"}
+        )
+    """
+
+    # Default intent pattern -> capability tag mappings
+    DEFAULT_INTENT_PATTERNS: dict[str, str] = {
+        "postgres.": "postgres.storage",
+        "consul.": "consul.registration",
+        "kafka.": "kafka.messaging",
+        "vault.": "vault.secrets",
+        "valkey.": "valkey.caching",
+        "http.": "http.transport",
+    }
+
+    # Default protocol -> capability tag mappings
+    DEFAULT_PROTOCOL_TAGS: dict[str, str] = {
+        "ProtocolReducer": "state.reducer",
+        "ProtocolDatabaseAdapter": "database.adapter",
+        "ProtocolEventBus": "event.bus",
+        "ProtocolCacheAdapter": "cache.adapter",
+        "ProtocolServiceDiscovery": "service.discovery",
+    }
+
+    # Default node type -> base capability tag
+    DEFAULT_NODE_TYPE_TAGS: dict[str, str] = {
+        "effect": "node.effect",
+        "compute": "node.compute",
+        "reducer": "node.reducer",
+        "orchestrator": "node.orchestrator",
+    }
+
+    def __init__(
+        self,
+        intent_patterns: dict[str, str] | None = None,
+        protocol_tags: dict[str, str] | None = None,
+        node_type_tags: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize with optional custom rules.
+
+        Custom rules are merged with defaults. If a custom rule has the same
+        key as a default rule, the custom rule takes precedence (override).
+
+        Args:
+            intent_patterns: Custom/additional intent patterns (merged with defaults).
+            protocol_tags: Custom/additional protocol tags (merged with defaults).
+            node_type_tags: Custom/additional node type tags (merged with defaults).
+        """
+        self._intent_patterns = {
+            **self.DEFAULT_INTENT_PATTERNS,
+            **(intent_patterns or {}),
+        }
+        self._protocol_tags = {
+            **self.DEFAULT_PROTOCOL_TAGS,
+            **(protocol_tags or {}),
+        }
+        self._node_type_tags = {
+            **self.DEFAULT_NODE_TYPE_TAGS,
+            **(node_type_tags or {}),
+        }
+
+    def infer_from_intent_types(self, intent_types: list[str]) -> list[str]:
+        """Infer capability tags from intent type patterns.
+
+        Pattern matching uses first-match-wins semantics: each intent is matched
+        against patterns in iteration order, and only the FIRST matching pattern
+        is used (early exit via break). This is intentional because intents should
+        belong to a single capability category.
+
+        Example:
+            - "postgres.upsert" matches "postgres." -> "postgres.storage"
+            - "postgres.kafka.hybrid" matches "postgres." only (NOT both postgres and kafka)
+
+        Args:
+            intent_types: List of intent type strings (e.g., ["postgres.upsert", "consul.register"])
+
+        Returns:
+            Sorted list of inferred capability tags (deduplicated)
+        """
+        tags: set[str] = set()
+        for intent in intent_types:
+            if intent is None:  # Skip None values
+                continue
+            for pattern, tag in self._intent_patterns.items():
+                if intent.startswith(pattern):
+                    tags.add(tag)
+                    break
+        return sorted(tags)
+
+    def infer_from_protocols(self, protocols: list[str]) -> list[str]:
+        """Infer capability tags from protocol names.
+
+        Matching behavior:
+            - Exact match: "ProtocolReducer" matches DEFAULT_PROTOCOL_TAGS["ProtocolReducer"]
+            - Suffix match: "MyCustomProtocolReducer" also matches because it ends with "ProtocolReducer"
+            - No match: "ProtocolReducerExtended" does NOT match (doesn't end with known protocol)
+
+        This allows custom-prefixed protocol implementations to inherit base capability tags.
+
+        Warning:
+            Suffix matching can cause unexpected over-matching if your protocol name
+            accidentally ends with a known protocol name. The matching is strict:
+            the protocol name must END with the exact known protocol string.
+
+        Examples:
+            Protocols that MATCH (suffix ends with known protocol)::
+
+                "ProtocolReducer" -> matches "ProtocolReducer" (exact match)
+                "MyCustomProtocolReducer" -> matches "ProtocolReducer" (suffix match)
+                "InfraProtocolDatabaseAdapter" -> matches "ProtocolDatabaseAdapter"
+                "V2ProtocolEventBus" -> matches "ProtocolEventBus"
+
+            Protocols that DO NOT MATCH (suffix has additional characters)::
+
+                "ProtocolReducerV2" -> NO match (ends with "V2", not "ProtocolReducer")
+                "ProtocolReducerExtended" -> NO match (ends with "Extended")
+                "ProtocolReducerExtendedVersion" -> NO match (ends with "Version")
+                "MyReducer" -> NO match (must end with full "ProtocolReducer")
+                "ProtocolReducerImpl" -> NO match (ends with "Impl")
+
+        Args:
+            protocols: List of protocol class names
+
+        Returns:
+            Sorted list of inferred capability tags (deduplicated)
+        """
+        tags: set[str] = set()
+        for protocol in protocols:
+            if protocol is None:  # Skip None values
+                continue
+            # Check exact match
+            if protocol in self._protocol_tags:
+                tags.add(self._protocol_tags[protocol])
+            # Also check if protocol name ends with known suffix
+            for known_protocol, tag in self._protocol_tags.items():
+                if protocol.endswith(known_protocol):
+                    tags.add(tag)
+        return sorted(tags)
+
+    def infer_from_node_type(self, node_type: str) -> list[str]:
+        """Infer base capability tag from node type.
+
+        Args:
+            node_type: Node type string (effect, compute, reducer, orchestrator)
+
+        Returns:
+            List with single node type capability tag, or empty if unknown
+        """
+        normalized = node_type.lower().replace("_generic", "")
+        if normalized in self._node_type_tags:
+            return [self._node_type_tags[normalized]]
+        return []
+
+    def infer_all(
+        self,
+        intent_types: list[str] | None = None,
+        protocols: list[str] | None = None,
+        node_type: str | None = None,
+    ) -> list[str]:
+        """Infer all capability tags from available contract data.
+
+        Args:
+            intent_types: Optional list of intent types
+            protocols: Optional list of protocol names
+            node_type: Optional node type string
+
+        Returns:
+            Sorted, deduplicated list of all inferred capability tags
+        """
+        tags: set[str] = set()
+
+        if intent_types:
+            tags.update(self.infer_from_intent_types(intent_types))
+        if protocols:
+            tags.update(self.infer_from_protocols(protocols))
+        if node_type:
+            tags.update(self.infer_from_node_type(node_type))
+
+        return sorted(tags)

omnibase_infra/capabilities/contract_capability_extractor.py

@@ -0,0 +1,221 @@
+"""Contract capability extractor for ONEX nodes.
+
+Extracts ModelContractCapabilities from typed contract models.
+No side effects, deterministic output.
+
+OMN-1136: ContractCapabilityExtractor - Main extractor implementation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.models.capabilities import ModelContractCapabilities
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.capabilities.capability_inference_rules import (
+    CapabilityInferenceRules,
+)
+from omnibase_infra.capabilities.intent_type_extractor import IntentTypeExtractor
+
+if TYPE_CHECKING:
+    from omnibase_core.models.contracts import (
+        ModelContractBase,
+    )
+
+
+class ContractCapabilityExtractor:
+    """Extracts capabilities from typed contract models.
+
+    Responsibilities:
+    - Read capability-related fields from contract
+    - Apply inference rules to derive additional tags
+    - Union explicit + inferred capabilities
+    - Return deterministic, sorted output
+
+    This extractor is stateless and produces deterministic output
+    for the same contract input.
+
+    Args:
+        rules: Optional custom CapabilityInferenceRules instance. If not provided,
+            uses a default instance with standard rule mappings.
+
+    Example:
+        # Use default rules
+        extractor = ContractCapabilityExtractor()
+
+        # Use custom rules
+        custom_rules = CapabilityInferenceRules(
+            intent_patterns={"redis.": "redis.caching"}
+        )
+        extractor = ContractCapabilityExtractor(rules=custom_rules)
+    """
+
+    def __init__(self, rules: CapabilityInferenceRules | None = None) -> None:
+        """Initialize with optional custom inference rules.
+
+        Args:
+            rules: Custom CapabilityInferenceRules instance. If None, creates
+                a default instance with standard rule mappings.
+        """
+        self._rules = rules if rules is not None else CapabilityInferenceRules()
+        self._intent_extractor = IntentTypeExtractor()
+
+    def extract(self, contract: ModelContractBase) -> ModelContractCapabilities | None:
+        """Extract capabilities from a contract model.
+
+        Args:
+            contract: Typed contract model (Effect, Compute, Reducer, or Orchestrator)
+
+        Returns:
+            ModelContractCapabilities with extracted data, or None if contract is None
+
+        Raises:
+            Any exceptions from extraction propagate (fail-fast behavior).
+        """
+        if contract is None:
+            return None
+
+        # Extract contract type from node_type
+        contract_type = self._extract_contract_type(contract)
+
+        # Extract version
+        contract_version = self._extract_version(contract)
+
+        # Extract intent types (varies by node type)
+        intent_types = self._extract_intent_types(contract)
+
+        # Extract protocols from dependencies
+        protocols = self._extract_protocols(contract)
+
+        # Extract explicit capability tags from contract
+        explicit_tags = self._extract_explicit_tags(contract)
+
+        # Infer additional tags using rules
+        inferred_tags = self._rules.infer_all(
+            intent_types=intent_types,
+            protocols=protocols,
+            node_type=contract_type,
+        )
+
+        # Union explicit + inferred (deterministic), filtering out invalid tags
+        combined_tags = set(explicit_tags) | set(inferred_tags)
+        all_tags = sorted(tag for tag in combined_tags if self._validate_tag(tag))
+
+        return ModelContractCapabilities(
+            contract_type=contract_type,
+            contract_version=contract_version,
+            intent_types=sorted(set(intent_types)),
+            protocols=sorted(set(protocols)),
+            capability_tags=all_tags,
+        )
+
+    def _extract_contract_type(self, contract: ModelContractBase) -> str:
+        """Extract normalized contract type string.
+
+        Raises:
+            ValueError: If contract does not have node_type field.
+        """
+        node_type = getattr(contract, "node_type", None)
+        if node_type is None:
+            raise ValueError("Contract must have node_type field")
+
+        # Handle both enum and string, normalize to lowercase without _GENERIC suffix
+        type_str = node_type.value if hasattr(node_type, "value") else str(node_type)
+        return type_str.lower().replace("_generic", "")
+
+    def _extract_version(self, contract: ModelContractBase) -> ModelSemVer:
+        """Extract contract version.
+
+        Raises:
+            ValueError: If contract_version is missing or not a ModelSemVer instance.
+        """
+        version = getattr(contract, "contract_version", None)
+        if isinstance(version, ModelSemVer):
+            return version
+        raise ValueError(
+            f"Contract must have contract_version as ModelSemVer, "
+            f"got {type(version).__name__ if version is not None else 'None'}"
+        )
+
+    def _extract_intent_types(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types based on node type.
+
+        Delegates to IntentTypeExtractor which handles extraction from
+        multiple sources based on node type.
+
+        Args:
+            contract: The contract model to extract intent types from.
+
+        Returns:
+            Combined list of intent types from all applicable sources.
+        """
+        return self._intent_extractor.extract_all(contract)
+
+    def _extract_protocols(self, contract: ModelContractBase) -> list[str]:
+        """Extract protocol names from dependencies and interfaces."""
+        protocols: list[str] = []
+
+        # From protocol_interfaces field
+        if hasattr(contract, "protocol_interfaces"):
+            protocol_interfaces = contract.protocol_interfaces
+            if protocol_interfaces:
+                for proto in protocol_interfaces:
+                    if proto is not None:  # Skip None values
+                        protocols.append(proto)
+
+        # From dependencies where type is protocol
+        if hasattr(contract, "dependencies"):
+            dependencies = contract.dependencies
+            if dependencies:
+                for dep in dependencies:
+                    # Check if it's a protocol dependency using is_protocol() method
+                    if hasattr(dep, "is_protocol") and dep.is_protocol():
+                        if hasattr(dep, "name") and dep.name:
+                            protocols.append(dep.name)
+                    # Fallback: check dependency_type directly
+                    elif hasattr(dep, "dependency_type"):
+                        dep_type = dep.dependency_type
+                        type_str = (
+                            dep_type.value
+                            if hasattr(dep_type, "value")
+                            else str(dep_type)
+                        )
+                        if type_str.upper() == "PROTOCOL":
+                            if hasattr(dep, "name") and dep.name:
+                                protocols.append(dep.name)
+
+        return protocols
+
+    def _validate_tag(self, tag: str | None) -> bool:
+        """Validate a tag string.
+
+        Args:
+            tag: Tag string to validate.
+
+        Returns:
+            True if the tag is valid, False otherwise.
+            Invalid tags include: None, empty strings, whitespace-only strings.
+        """
+        if tag is None:
+            return False
+        if not isinstance(tag, str):
+            return False
+        if tag == "":
+            return False
+        if tag.strip() == "":
+            return False
+        return True
+
+    def _extract_explicit_tags(self, contract: ModelContractBase) -> list[str]:
+        """Extract explicitly declared capability tags from contract."""
+        tags: list[str] = []
+
+        # From top-level tags field (all contracts have this)
+        if hasattr(contract, "tags"):
+            contract_tags = contract.tags
+            if contract_tags:
+                for tag in contract_tags:
+                    if self._validate_tag(tag):
+                        tags.append(tag)
+
+        return tags

omnibase_infra/capabilities/intent_type_extractor.py

@@ -0,0 +1,160 @@
+"""Intent type extraction from ONEX contracts.
+
+Extracts intent types from various contract structures including
+event_type, consumed_events, published_events, and aggregation fields.
+
+OMN-1136: Intent type extraction helper for ContractCapabilityExtractor.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from omnibase_core.models.contracts import ModelContractBase
+
+
+class IntentTypeExtractor:
+    """Extracts intent types from contract models.
+
+    This class handles extraction of intent types from various contract
+    structures. Different node types expose intent information in different
+    locations:
+    - Effect nodes: event_type.primary_events
+    - Orchestrator nodes: consumed_events[].event_pattern, published_events[].event_name
+    - Reducer nodes: aggregation.aggregation_functions
+
+    This extractor is stateless and produces deterministic output.
+
+    Example:
+        extractor = IntentTypeExtractor()
+        intent_types = extractor.extract_all(contract)
+    """
+
+    def extract_all(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from all applicable sources.
+
+        Combines intent types from event_type, consumed_events,
+        published_events, and aggregation fields.
+
+        Args:
+            contract: The contract model to extract intent types from.
+
+        Returns:
+            Combined list of intent types from all applicable sources.
+        """
+        intent_types: list[str] = []
+
+        intent_types.extend(self._extract_from_event_type(contract))
+        intent_types.extend(self._extract_from_consumed_events(contract))
+        intent_types.extend(self._extract_from_published_events(contract))
+        intent_types.extend(self._extract_from_aggregation(contract))
+
+        return intent_types
+
+    def _extract_from_event_type(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from event_type.primary_events.
+
+        Used primarily by Effect nodes to declare the events they handle.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of primary event types, or empty list if not present.
+        """
+        if not hasattr(contract, "event_type"):
+            return []
+
+        event_type = contract.event_type
+        if event_type is None or not hasattr(event_type, "primary_events"):
+            return []
+
+        primary_events = event_type.primary_events
+        if not primary_events:
+            return []
+
+        return list(primary_events)
+
+    def _extract_from_consumed_events(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from consumed_events[].event_pattern.
+
+        Used by Orchestrator nodes to declare which events they subscribe to.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of event patterns from consumed events, or empty list if not present.
+        """
+        if not hasattr(contract, "consumed_events"):
+            return []
+
+        consumed_events = contract.consumed_events
+        if not consumed_events:
+            return []
+
+        intent_types: list[str] = []
+        for event in consumed_events:
+            # ModelEventSubscription has event_pattern field
+            if hasattr(event, "event_pattern") and event.event_pattern:
+                intent_types.append(event.event_pattern)
+
+        return intent_types
+
+    def _extract_from_published_events(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from published_events[].event_name.
+
+        Used by Orchestrator nodes to declare which events they publish.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of event names from published events, or empty list if not present.
+        """
+        if not hasattr(contract, "published_events"):
+            return []
+
+        published_events = contract.published_events
+        if not published_events:
+            return []
+
+        intent_types: list[str] = []
+        for event in published_events:
+            # ModelEventDescriptor has event_name field
+            if hasattr(event, "event_name") and event.event_name:
+                intent_types.append(event.event_name)
+
+        return intent_types
+
+    def _extract_from_aggregation(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from aggregation.aggregation_functions.
+
+        Used by Reducer nodes to declare aggregation patterns based on
+        the output fields of their aggregation functions.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of aggregation intent types (prefixed with 'aggregate.'),
+            or empty list if not present.
+        """
+        if not hasattr(contract, "aggregation"):
+            return []
+
+        aggregation = contract.aggregation
+        if aggregation is None or not hasattr(aggregation, "aggregation_functions"):
+            return []
+
+        agg_funcs = aggregation.aggregation_functions
+        if not agg_funcs:
+            return []
+
+        intent_types: list[str] = []
+        for func in agg_funcs:
+            if hasattr(func, "output_field") and func.output_field:
+                intent_types.append(f"aggregate.{func.output_field}")
+
+        return intent_types

omnibase_infra/cli/__init__.py

@@ -0,0 +1 @@
+"""ONEX Infrastructure CLI."""