omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/enums/enum_introspection_reason.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Introspection Reason Enumeration.
+
+Defines reason values for node introspection events, categorizing why a node
+emits an introspection event for filtering, alerting, and analytics.
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class EnumIntrospectionReason(str, Enum):
+    """
+    Reasons why a node emits an introspection event.
+
+    Used by ModelNodeIntrospectionEvent to categorize introspection
+    events for filtering, alerting, and analytics.
+
+    Values:
+        STARTUP: Node just started and is announcing presence.
+        SHUTDOWN: Node is gracefully shutting down.
+        REQUEST: Explicit request for introspection (e.g., admin query).
+        HEARTBEAT: Periodic health heartbeat.
+        HEALTH_CHANGE: Node health status changed.
+        CAPABILITY_CHANGE: Node capabilities changed at runtime.
+
+    Example:
+        >>> reason = EnumIntrospectionReason.STARTUP
+        >>> reason.is_lifecycle_event()
+        True
+        >>> str(EnumIntrospectionReason.HEARTBEAT)
+        'heartbeat'
+    """
+
+    STARTUP = "startup"
+    """Node just started and is announcing presence."""
+
+    SHUTDOWN = "shutdown"
+    """Node is gracefully shutting down."""
+
+    REQUEST = "request"
+    """Explicit request for introspection (e.g., admin query)."""
+
+    HEARTBEAT = "heartbeat"
+    """Periodic health heartbeat."""
+
+    HEALTH_CHANGE = "health_change"
+    """Node health status changed."""
+
+    CAPABILITY_CHANGE = "capability_change"
+    """Node capabilities changed at runtime."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    def is_lifecycle_event(self) -> bool:
+        """
+        Check if this reason represents a lifecycle event.
+
+        Lifecycle events indicate node startup or shutdown, which are
+        significant for registration and discovery workflows.
+
+        Returns:
+            True if the reason is a lifecycle event, False otherwise
+
+        Example:
+            >>> EnumIntrospectionReason.STARTUP.is_lifecycle_event()
+            True
+            >>> EnumIntrospectionReason.HEARTBEAT.is_lifecycle_event()
+            False
+        """
+        return self in {
+            EnumIntrospectionReason.STARTUP,
+            EnumIntrospectionReason.SHUTDOWN,
+        }
+
+    def is_health_related(self) -> bool:
+        """
+        Check if this reason is health-related.
+
+        Health-related reasons indicate the node is reporting its health
+        status, either periodically or due to a change.
+
+        Returns:
+            True if the reason is health-related, False otherwise
+
+        Example:
+            >>> EnumIntrospectionReason.HEARTBEAT.is_health_related()
+            True
+            >>> EnumIntrospectionReason.REQUEST.is_health_related()
+            False
+        """
+        return self in {
+            EnumIntrospectionReason.HEARTBEAT,
+            EnumIntrospectionReason.HEALTH_CHANGE,
+        }
+
+    def is_change_event(self) -> bool:
+        """
+        Check if this reason indicates a state change.
+
+        Change events indicate something about the node changed that
+        may require re-evaluation by the registration system.
+
+        Returns:
+            True if the reason indicates a change, False otherwise
+
+        Example:
+            >>> EnumIntrospectionReason.CAPABILITY_CHANGE.is_change_event()
+            True
+            >>> EnumIntrospectionReason.HEARTBEAT.is_change_event()
+            False
+        """
+        return self in {
+            EnumIntrospectionReason.HEALTH_CHANGE,
+            EnumIntrospectionReason.CAPABILITY_CHANGE,
+        }
+
+    @classmethod
+    def get_description(cls, reason: "EnumIntrospectionReason") -> str:
+        """
+        Get a human-readable description of the introspection reason.
+
+        Args:
+            reason: The introspection reason to describe
+
+        Returns:
+            A human-readable description of the reason
+
+        Example:
+            >>> EnumIntrospectionReason.get_description(
+            ...     EnumIntrospectionReason.STARTUP
+            ... )
+            'Node just started and is announcing presence'
+        """
+        descriptions = {
+            cls.STARTUP: "Node just started and is announcing presence",
+            cls.SHUTDOWN: "Node is gracefully shutting down",
+            cls.REQUEST: "Explicit request for introspection",
+            cls.HEARTBEAT: "Periodic health heartbeat",
+            cls.HEALTH_CHANGE: "Node health status changed",
+            cls.CAPABILITY_CHANGE: "Node capabilities changed at runtime",
+        }
+        return descriptions.get(reason, "Unknown introspection reason")
+
+
+__all__: list[str] = ["EnumIntrospectionReason"]

omnibase_infra/enums/enum_kafka_acks.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Kafka producer acknowledgment configuration enumeration.
+
+This module defines the acknowledgment policy enumeration for Kafka producers,
+with a conversion method to produce aiokafka-compatible types.
+
+The `acks` configuration controls how many partition replicas must acknowledge
+receipt before the producer considers a request complete:
+    - ALL ("all"): Wait for all in-sync replicas to acknowledge (most durable)
+    - LEADER ("1"): Wait only for the leader to acknowledge (balanced)
+    - NONE ("0"): Don't wait for any acknowledgment (fastest, least durable)
+    - ALL_REPLICAS ("-1"): Explicit numeric form of ALL (equivalent to "all")
+
+See Also:
+    - EventBusKafka: Uses this enum for producer configuration
+    - ModelKafkaEventBusConfig: Config model that stores the acks setting
+    - https://kafka.apache.org/documentation/#producerconfigs_acks
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+# Explicit mapping for aiokafka type conversion.
+# Defined at module level because str-based enums don't support ClassVar attributes
+# (attribute lookup on str enum members uses string indexing, not class attribute lookup).
+_AIOKAFKA_MAP: dict[str, int | str] = {
+    "all": "all",
+    "0": 0,
+    "1": 1,
+    "-1": -1,
+}
+
+
+class EnumKafkaAcks(str, Enum):
+    """Kafka producer acknowledgment policy.
+
+    Defines the acknowledgment behavior for Kafka producers. The aiokafka
+    library expects specific types for the `acks` parameter:
+    - "all" must be passed as a string
+    - Numeric values (0, 1, -1) must be passed as integers
+
+    Use the `to_aiokafka()` method to get the correctly-typed value for
+    passing to AIOKafkaProducer.
+
+    Attributes:
+        ALL: Wait for all in-sync replicas (string "all")
+        NONE: Fire and forget, no acknowledgment (string "0" -> int 0)
+        LEADER: Wait for leader acknowledgment only (string "1" -> int 1)
+        ALL_REPLICAS: Explicit numeric form of ALL (string "-1" -> int -1)
+
+    Note:
+        ALL ("all") and ALL_REPLICAS (-1) are semantically equivalent in Kafka.
+        ALL_REPLICAS is provided for explicit numeric configuration compatibility
+        when migrating from systems that use the numeric form.
+
+    Example:
+        >>> acks = EnumKafkaAcks.ALL
+        >>> acks.to_aiokafka()
+        'all'
+        >>> acks = EnumKafkaAcks.LEADER
+        >>> acks.to_aiokafka()
+        1
+    """
+
+    ALL = "all"
+    NONE = "0"
+    LEADER = "1"
+    ALL_REPLICAS = "-1"
+
+    def to_aiokafka(self) -> int | str:
+        """Convert to aiokafka-compatible type.
+
+        aiokafka's AIOKafkaProducer expects:
+        - The string "all" for all-replica acknowledgment
+        - Integer values (0, 1, -1) for numeric ack levels
+
+        Returns:
+            The acks value in the format expected by aiokafka:
+            - "all" (str) for ALL
+            - 0 (int) for NONE
+            - 1 (int) for LEADER
+            - -1 (int) for ALL_REPLICAS
+
+        Example:
+            >>> EnumKafkaAcks.ALL.to_aiokafka()
+            'all'
+            >>> EnumKafkaAcks.NONE.to_aiokafka()
+            0
+            >>> EnumKafkaAcks.LEADER.to_aiokafka()
+            1
+            >>> EnumKafkaAcks.ALL_REPLICAS.to_aiokafka()
+            -1
+        """
+        return _AIOKAFKA_MAP[self.value]
+
+
+__all__: list[str] = ["EnumKafkaAcks"]

omnibase_infra/enums/enum_message_category.py

@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Message Category Enumeration.
+
+Defines the fundamental message categories in ONEX event-driven architecture:
+- EVENT: Domain events representing facts that have occurred
+- COMMAND: Instructions to perform an action
+- INTENT: User intents requiring interpretation and routing
+
+IMPORTANT: PROJECTION is NOT a message category. Projections are node output types
+used for execution shape validation (see EnumNodeOutputType). Projections are
+state outputs produced by REDUCER nodes and are not routed via Kafka topics.
+
+Topic Naming Conventions:
+    - EVENT: Read from `*.events` topics (e.g., `order.events`, `user.events`)
+    - COMMAND: Read from `*.commands` topics (e.g., `order.commands`)
+    - INTENT: Read from `*.intents` topics (e.g., `checkout.intents`)
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+
+See Also:
+    EnumNodeOutputType: For node output types including PROJECTION
+"""
+
+from __future__ import annotations
+
+from enum import Enum, unique
+
+
+@unique
+class EnumMessageCategory(str, Enum):
+    """
+    Message category classification for ONEX event-driven routing.
+
+    The three fundamental message categories determine how messages are
+    processed and routed through the system:
+
+    - **EVENT**: Facts that have occurred (past tense, immutable)
+      - Published to event topics (*.events.*)
+      - Consumed by reducers and projections
+      - Example: UserCreatedEvent, OrderCompletedEvent
+
+    - **COMMAND**: Instructions to perform an action (imperative)
+      - Published to command topics (*.commands.*)
+      - Consumed by command handlers
+      - Example: CreateUserCommand, ProcessPaymentCommand
+
+    - **INTENT**: User intents requiring interpretation (declarative)
+      - Published to intent topics (*.intents.*)
+      - Consumed by orchestrators for routing decisions
+      - Example: UserWantsToCheckoutIntent, RequestPasswordResetIntent
+
+    Note:
+        PROJECTION is intentionally NOT included here. Projections are
+        node output types (see EnumNodeOutputType), not routable message
+        categories. REDUCERs produce projections as state outputs.
+
+    Maintainer Note:
+        When adding new values to this enum, you MUST update the following:
+
+        1. ``_MESSAGE_CATEGORY_TO_OUTPUT_TYPE`` mapping in
+           ``omnibase_infra/validation/execution_shape_validator.py``
+        2. ``_CATEGORY_TO_SUFFIX`` and ``_SUFFIX_TO_CATEGORY`` mappings
+           at the bottom of this file (see module-level constants)
+        3. Topic routing logic in ``topic_category_validator.py`` and
+           any pattern matching that uses category suffixes
+        4. The ``from_topic()`` method if the new category uses a
+           different topic naming convention
+
+    Attributes:
+        topic_suffix: The plural suffix used in topic names (e.g., "events")
+
+    Example:
+        >>> category = EnumMessageCategory.EVENT
+        >>> category.topic_suffix
+        'events'
+        >>> EnumMessageCategory.from_topic("onex.user.events")
+        <EnumMessageCategory.EVENT: 'event'>
+        >>> EnumMessageCategory.from_topic("dev.order.commands.v1")
+        <EnumMessageCategory.COMMAND: 'command'>
+    """
+
+    EVENT = "event"
+    """Domain events representing facts that have occurred."""
+
+    COMMAND = "command"
+    """Instructions to perform an action."""
+
+    INTENT = "intent"
+    """User intents requiring interpretation and routing."""
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    @property
+    def topic_suffix(self) -> str:
+        """
+        Get the topic suffix for this category (plural form).
+
+        The suffix is used in topic naming conventions:
+        - EVENT -> "events" (e.g., onex.user.events)
+        - COMMAND -> "commands" (e.g., onex.order.commands)
+        - INTENT -> "intents" (e.g., onex.checkout.intents)
+
+        Returns:
+            The plural suffix string for topic names
+
+        Example:
+            >>> EnumMessageCategory.EVENT.topic_suffix
+            'events'
+            >>> EnumMessageCategory.COMMAND.topic_suffix
+            'commands'
+        """
+        return _CATEGORY_TO_SUFFIX[self]
+
+    @classmethod
+    def from_topic(cls, topic: str) -> EnumMessageCategory | None:
+        """
+        Infer the message category from a topic string.
+
+        Examines the topic for category keywords (events, commands, intents)
+        as complete segments and returns the corresponding category. Handles both
+        ONEX Kafka format (onex.<domain>.<type>) and Environment-Aware format
+        (<env>.<domain>.<category>.<version>).
+
+        The matching is segment-based to prevent false positives. For example:
+        - "onex.user.events" matches EVENT (segment "events" exists)
+        - "dev.eventsource.data.v1" does NOT match ("eventsource" != "events")
+
+        Args:
+            topic: The topic string to analyze
+
+        Returns:
+            EnumMessageCategory if a category can be inferred, None otherwise
+
+        Example:
+            >>> EnumMessageCategory.from_topic("onex.user.events")
+            <EnumMessageCategory.EVENT: 'event'>
+            >>> EnumMessageCategory.from_topic("dev.order.commands.v1")
+            <EnumMessageCategory.COMMAND: 'command'>
+            >>> EnumMessageCategory.from_topic("prod.checkout.intents.v2")
+            <EnumMessageCategory.INTENT: 'intent'>
+            >>> EnumMessageCategory.from_topic("invalid.topic")
+            None
+            >>> EnumMessageCategory.from_topic("dev.eventsource.data.v1")
+            None  # No false positive: "eventsource" is not the same as "events"
+        """
+        if not topic:
+            return None
+
+        # Split topic into segments and check for exact category suffix matches.
+        # This prevents false positives where a segment merely contains the
+        # category suffix as a substring (e.g., "eventsource" containing "events").
+        segments = topic.lower().split(".")
+        for suffix, category in _SUFFIX_TO_CATEGORY.items():
+            if suffix in segments:
+                return category
+
+        return None
+
+    @classmethod
+    def from_suffix(cls, suffix: str) -> EnumMessageCategory | None:
+        """
+        Get the category from a topic suffix.
+
+        Args:
+            suffix: The suffix to look up (e.g., "events", "commands", "intents")
+
+        Returns:
+            EnumMessageCategory if the suffix is valid, None otherwise
+
+        Example:
+            >>> EnumMessageCategory.from_suffix("events")
+            <EnumMessageCategory.EVENT: 'event'>
+            >>> EnumMessageCategory.from_suffix("commands")
+            <EnumMessageCategory.COMMAND: 'command'>
+            >>> EnumMessageCategory.from_suffix("unknown")
+            None
+        """
+        return _SUFFIX_TO_CATEGORY.get(suffix.lower())
+
+    def is_event(self) -> bool:
+        """Check if this is an event category."""
+        return self == EnumMessageCategory.EVENT
+
+    def is_command(self) -> bool:
+        """Check if this is a command category."""
+        return self == EnumMessageCategory.COMMAND
+
+    def is_intent(self) -> bool:
+        """Check if this is an intent category."""
+        return self == EnumMessageCategory.INTENT
+
+
+# Module-level constant mappings for better performance (avoid dict creation per call)
+# Defined after enum class to enable proper type resolution
+_CATEGORY_TO_SUFFIX: dict[EnumMessageCategory, str] = {
+    EnumMessageCategory.EVENT: "events",
+    EnumMessageCategory.COMMAND: "commands",
+    EnumMessageCategory.INTENT: "intents",
+}
+_SUFFIX_TO_CATEGORY: dict[str, EnumMessageCategory] = {
+    "events": EnumMessageCategory.EVENT,
+    "commands": EnumMessageCategory.COMMAND,
+    "intents": EnumMessageCategory.INTENT,
+}
+
+
+__all__ = ["EnumMessageCategory"]

omnibase_infra/enums/enum_node_archetype.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Archetype Enumeration for ONEX 4-Node Architecture.
+
+Defines the canonical node archetypes for the ONEX execution shape validator.
+Each archetype corresponds to a node category in the ONEX 4-node architecture
+and has specific constraints on allowed output types and operations.
+
+Node Archetype Output Constraints (see EnumNodeOutputType for output types):
+    - EFFECT: External interactions (API calls, DB queries, file I/O).
+              Can output EVENT, COMMAND but not PROJECTION.
+    - COMPUTE: Pure data processing and business logic transformations.
+               Can output EVENT, COMMAND, INTENT. No side effects.
+    - REDUCER: State management and persistence operations.
+               Can output PROJECTION only. Cannot output EVENT.
+               Must be deterministic (no system time access).
+    - ORCHESTRATOR: Workflow coordination and step sequencing.
+                    Can output COMMAND, EVENT but not INTENT or PROJECTION.
+
+Note on Design:
+    This enum is distinct from:
+    - EnumHandlerType: Architectural role (how handler binds to system)
+    - EnumHandlerTypeCategory: Behavioral classification (side effects)
+
+    EnumNodeArchetype specifically captures the 4-node architecture for
+    execution shape validation which defines what outputs each node can produce.
+
+See Also:
+    - EnumNodeOutputType: Defines valid node output types (includes PROJECTION)
+    - EnumMessageCategory: Defines message categories for routing (excludes PROJECTION)
+    - EnumExecutionShapeViolation: Defines validation violation types
+    - EnumHandlerType: Handler architectural role (INFRA_HANDLER, NODE_HANDLER, etc.)
+    - EnumHandlerTypeCategory: Handler behavioral classification (EFFECT, COMPUTE, etc.)
+    - NODE_ARCHETYPE_EXPECTED_CATEGORIES: Maps archetypes to expected input/output types
+      (see topic_category_validator.py for the mapping and its dual-purpose documentation)
+"""
+
+from enum import Enum
+
+
+class EnumNodeArchetype(str, Enum):
+    """Node archetypes for ONEX 4-node architecture execution shape validation.
+
+    These represent the four canonical node types in the ONEX architecture.
+    Each type has specific constraints on what operations are allowed and
+    what output types can be produced (see EnumNodeOutputType).
+
+    Attributes:
+        EFFECT: External interaction nodes (API calls, DB operations).
+            Responsible for side effects and external system integration.
+            Can output: EVENT, COMMAND. Cannot output: PROJECTION.
+        COMPUTE: Pure data processing and transformation nodes.
+            No side effects, deterministic transformations.
+            Can output: EVENT, COMMAND, INTENT.
+        REDUCER: State management and persistence nodes.
+            Manages state consolidation and projections.
+            Can output: PROJECTION only. Cannot output: EVENT.
+            Must be deterministic (no system time access).
+        ORCHESTRATOR: Workflow coordination nodes.
+            Coordinates multi-step workflows and routing.
+            Can output: COMMAND, EVENT. Cannot output: INTENT, PROJECTION.
+
+    Note:
+        Output types refer to EnumNodeOutputType values. PROJECTION is a node
+        output type, not a message routing category (not in EnumMessageCategory).
+    """
+
+    EFFECT = "effect"
+    COMPUTE = "compute"
+    REDUCER = "reducer"
+    ORCHESTRATOR = "orchestrator"
+
+
+__all__ = ["EnumNodeArchetype"]