omnibase_infra 0.2.8__py3-none-any.whl → 0.2.9__py3-none-any.whl

omnibase_infra/services/contract_publisher/sources/source_filesystem.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Contract Source.
+
+Discovers contracts from a directory tree by globbing for contract.yaml files.
+This is the primary source for local development and CI/CD environments.
+
+Discovery Pattern:
+    Globs for **/contract.yaml under the configured root directory.
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from omnibase_infra.services.contract_publisher.errors import (
+    ContractSourceNotConfiguredError,
+)
+from omnibase_infra.services.contract_publisher.sources.model_discovered import (
+    ModelDiscoveredContract,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SourceContractFilesystem:
+    """Filesystem-based contract source.
+
+    Recursively scans a directory for contract.yaml files and returns
+    them as ModelDiscoveredContract instances.
+
+    Discovery:
+        Uses Path.glob("**/contract.yaml") to find all contract files
+        under the root directory.
+
+    Error Handling:
+        - If root doesn't exist: Raises ContractSourceNotConfiguredError
+        - If root is not a directory: Raises ContractSourceNotConfiguredError
+        - If file read fails: Logs warning, skips file, continues
+
+    Attributes:
+        _root: Root directory for discovery
+
+    Example:
+        >>> source = SourceContractFilesystem(Path("/app/contracts"))
+        >>> contracts = await source.discover_contracts()
+        >>> for contract in contracts:
+        ...     print(f"Found: {contract.ref}")
+
+    .. versionadded:: 0.3.0
+    """
+
+    __slots__ = ("_root",)
+
+    def __init__(self, root: Path) -> None:
+        """Initialize filesystem source.
+
+        Args:
+            root: Root directory for contract discovery
+        """
+        self._root = root
+
+    @property
+    def source_type(self) -> str:
+        """Return source type identifier.
+
+        Returns:
+            "filesystem"
+        """
+        return "filesystem"
+
+    @property
+    def source_description(self) -> str:
+        """Return human-readable source description.
+
+        Returns:
+            Description including the root path
+        """
+        return f"filesystem: {self._root}"
+
+    @property
+    def root(self) -> Path:
+        """Return the root directory.
+
+        Returns:
+            Root directory Path
+        """
+        return self._root
+
+    async def discover_contracts(self) -> list[ModelDiscoveredContract]:
+        """Discover all contracts from the filesystem.
+
+        Globs for **/contract.yaml under the root directory and reads
+        each file's contents.
+
+        Returns:
+            List of discovered contracts with origin="filesystem"
+
+        Raises:
+            ContractSourceNotConfiguredError: If the filesystem root does not
+                exist or is not a directory. This indicates a configuration
+                problem that should be fixed rather than silently ignored.
+
+        Note:
+            Individual file read failures are logged and skipped.
+
+        Note:
+            This method is ``async`` for protocol consistency with
+            :class:`ProtocolContractPublisherSource`. The underlying file I/O
+            is synchronous, which is acceptable for this use case as contract
+            discovery is an infrequent startup operation.
+        """
+        if not self._root.exists():
+            logger.warning(
+                "Filesystem source root does not exist: %s",
+                self._root,
+            )
+            raise ContractSourceNotConfiguredError(
+                mode="filesystem",
+                missing_field="filesystem_root",
+                message=f"Filesystem root does not exist: {self._root}",
+            )
+
+        if not self._root.is_dir():
+            logger.warning(
+                "Filesystem source root is not a directory: %s",
+                self._root,
+            )
+            raise ContractSourceNotConfiguredError(
+                mode="filesystem",
+                missing_field="filesystem_root",
+                message=f"Filesystem root is not a directory: {self._root}",
+            )
+
+        contracts: list[ModelDiscoveredContract] = []
+
+        # Glob for contract.yaml files
+        for contract_path in self._root.glob("**/contract.yaml"):
+            try:
+                text = contract_path.read_text(encoding="utf-8")
+                contract = ModelDiscoveredContract(
+                    origin="filesystem",
+                    ref=contract_path,
+                    text=text,
+                )
+                contracts.append(contract)
+
+                logger.debug(
+                    "Discovered contract: %s",
+                    contract_path,
+                )
+
+            except (OSError, UnicodeDecodeError) as e:
+                logger.warning(
+                    "Failed to read contract file %s: %s",
+                    contract_path,
+                    e,
+                )
+                # Continue with other files
+
+        logger.info(
+            "Filesystem discovery complete: found %d contracts in %s",
+            len(contracts),
+            self._root,
+        )
+
+        return contracts
+
+
+__all__ = ["SourceContractFilesystem"]

omnibase_infra/services/contract_publisher/sources/source_package.py

@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Package Resource Contract Source.
+
+Discovers contracts from installed Python package resources using
+importlib.resources. This is the primary source for containerized
+deployments where contracts ship with the wheel.
+
+Discovery Pattern:
+    Traverses package resources looking for contract.yaml files.
+
+.. versionadded:: 0.3.0
+    Created as part of OMN-1752 (ContractPublisher extraction).
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import resources
+from importlib.resources.abc import Traversable
+
+from omnibase_infra.services.contract_publisher.errors import (
+    ContractSourceNotConfiguredError,
+)
+from omnibase_infra.services.contract_publisher.sources.model_discovered import (
+    ModelDiscoveredContract,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SourceContractPackage:
+    """Package resource-based contract source.
+
+    Discovers contracts from installed Python package resources using
+    importlib.resources API. Recursively traverses the package looking
+    for contract.yaml files.
+
+    Requirements:
+        - The package must be installed (importable)
+        - Contract files must be named "contract.yaml"
+        - Package must include resources (MANIFEST.in or package_data)
+
+    Attributes:
+        _package_module: Fully qualified module name (e.g., "myapp.contracts")
+
+    Example:
+        >>> source = SourceContractPackage("myapp.contracts.handlers")
+        >>> contracts = await source.discover_contracts()
+        >>> for contract in contracts:
+        ...     print(f"Found: {contract.ref}")
+
+    .. versionadded:: 0.3.0
+    """
+
+    __slots__ = ("_package_module",)
+
+    def __init__(self, package_module: str) -> None:
+        """Initialize package source.
+
+        Args:
+            package_module: Fully qualified module name for contract discovery
+                           (e.g., "myapp.contracts" or "myapp.contracts.handlers")
+        """
+        self._package_module = package_module
+
+    @property
+    def source_type(self) -> str:
+        """Return source type identifier.
+
+        Returns:
+            "package"
+        """
+        return "package"
+
+    @property
+    def source_description(self) -> str:
+        """Return human-readable source description.
+
+        Returns:
+            Description including the package module
+        """
+        return f"package: {self._package_module}"
+
+    @property
+    def package_module(self) -> str:
+        """Return the package module name.
+
+        Returns:
+            Package module name
+        """
+        return self._package_module
+
+    async def discover_contracts(self) -> list[ModelDiscoveredContract]:
+        """Discover all contracts from the package.
+
+        Uses importlib.resources to traverse the package and find
+        contract.yaml files.
+
+        Returns:
+            List of discovered contracts with origin="package"
+
+        Raises:
+            ContractSourceNotConfiguredError: If the package is not found
+                (not installed) or is invalid for resource discovery.
+
+        Note:
+            Individual resource read failures during traversal are logged
+            and skipped, but the discovery continues.
+
+        Note:
+            This method is ``async`` for protocol consistency with
+            :class:`ProtocolContractPublisherSource`. The underlying package
+            resource traversal is synchronous, which is acceptable for this
+            use case as contract discovery is an infrequent startup operation.
+        """
+        contracts: list[ModelDiscoveredContract] = []
+
+        try:
+            # Get the package root as a Traversable
+            package_root = resources.files(self._package_module)
+
+            # Recursively discover contracts
+            self._discover_recursive(package_root, "", contracts)
+
+        except ModuleNotFoundError:
+            logger.warning(
+                "Package not found: %s",
+                self._package_module,
+            )
+            raise ContractSourceNotConfiguredError(
+                mode="package",
+                missing_field="package_module",
+                message=f"Package not found: {self._package_module}",
+            )
+
+        except TypeError as e:
+            # resources.files() can raise TypeError for invalid packages
+            logger.warning(
+                "Invalid package for resource discovery: %s - %s",
+                self._package_module,
+                e,
+            )
+            raise ContractSourceNotConfiguredError(
+                mode="package",
+                missing_field="package_module",
+                message=f"Invalid package for resource discovery: {self._package_module} - {e}",
+            )
+
+        logger.info(
+            "Package discovery complete: found %d contracts in %s",
+            len(contracts),
+            self._package_module,
+        )
+
+        return contracts
+
+    def _discover_recursive(
+        self,
+        traversable: Traversable,
+        path_prefix: str,
+        contracts: list[ModelDiscoveredContract],
+    ) -> None:
+        """Recursively discover contracts from a Traversable.
+
+        Args:
+            traversable: Current package resource to traverse
+            path_prefix: Path prefix for building resource paths
+            contracts: List to append discovered contracts to
+        """
+        try:
+            # Check if this is a directory
+            if not traversable.is_dir():
+                return
+
+            # Iterate children
+            for child in traversable.iterdir():
+                child_name = child.name
+                child_path = (
+                    f"{path_prefix}/{child_name}" if path_prefix else child_name
+                )
+
+                if child.is_file() and child_name == "contract.yaml":
+                    # Found a contract file
+                    try:
+                        text = child.read_text(encoding="utf-8")
+                        resource_path = f"{self._package_module}:{child_path}"
+
+                        contract = ModelDiscoveredContract(
+                            origin="package",
+                            ref=resource_path,
+                            text=text,
+                        )
+                        contracts.append(contract)
+
+                        logger.debug(
+                            "Discovered contract: %s",
+                            resource_path,
+                        )
+
+                    except OSError as e:
+                        logger.warning(
+                            "Failed to read package resource %s: %s",
+                            child_path,
+                            e,
+                        )
+
+                elif child.is_dir():
+                    # Recurse into subdirectory
+                    self._discover_recursive(child, child_path, contracts)
+
+        except OSError as e:
+            logger.warning(
+                "Error traversing package %s at %s: %s",
+                self._package_module,
+                path_prefix,
+                e,
+            )
+
+
+__all__ = ["SourceContractPackage"]

omnibase_infra/services/observability/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Observability services for agent telemetry and monitoring.
+
+This module provides infrastructure for collecting, processing, and persisting
+agent observability data including actions, routing decisions, and performance
+metrics.
+
+Submodules:
+    - agent_actions: Consumer and writer for agent action events
+
+Example:
+    >>> from omnibase_infra.services.observability import (
+    ...     AgentActionsConsumer,
+    ...     ConfigAgentActionsConsumer,
+    ...     WriterAgentActionsPostgres,
+    ... )
+    >>>
+    >>> config = ConfigAgentActionsConsumer(
+    ...     kafka_bootstrap_servers="localhost:9092",
+    ...     postgres_dsn="postgresql://postgres:secret@localhost:5432/omninode_bridge",
+    ... )
+    >>> consumer = AgentActionsConsumer(config)
+    >>>
+    >>> # Run consumer
+    >>> await consumer.start()
+    >>> await consumer.run()
+"""
+
+from omnibase_infra.services.observability.agent_actions import (
+    AgentActionsConsumer,
+    ConfigAgentActionsConsumer,
+    WriterAgentActionsPostgres,
+)
+
+__all__ = [
+    "AgentActionsConsumer",
+    "ConfigAgentActionsConsumer",
+    "WriterAgentActionsPostgres",
+]

omnibase_infra/services/observability/agent_actions/__init__.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Agent actions observability consumer and writer.
+
+This module provides infrastructure for consuming agent action events from
+Kafka and persisting them to PostgreSQL for observability and analytics.
+
+Moved from omniclaude as part of OMN-1743 layer-correction cleanup.
+
+Components:
+    - AgentActionsConsumer: Async Kafka consumer with per-partition offset tracking
+    - ConfigAgentActionsConsumer: Configuration for the consumer
+    - WriterAgentActionsPostgres: PostgreSQL writer for observability events
+
+Topics consumed:
+    - agent-actions
+    - agent-routing-decisions
+    - agent-transformation-events
+    - router-performance-metrics
+    - agent-detection-failures
+    - agent-execution-logs
+
+Example:
+    >>> from omnibase_infra.services.observability.agent_actions import (
+    ...     AgentActionsConsumer,
+    ...     ConfigAgentActionsConsumer,
+    ...     WriterAgentActionsPostgres,
+    ... )
+    >>>
+    >>> config = ConfigAgentActionsConsumer(
+    ...     kafka_bootstrap_servers="localhost:9092",
+    ...     postgres_dsn="postgresql://postgres:secret@localhost:5432/omninode_bridge",
+    ... )
+    >>> consumer = AgentActionsConsumer(config)
+    >>>
+    >>> # Run consumer
+    >>> await consumer.start()
+    >>> await consumer.run()
+
+    # Or run as module:
+    # python -m omnibase_infra.services.observability.agent_actions.consumer
+"""
+
+from omnibase_infra.services.observability.agent_actions.config import (
+    ConfigAgentActionsConsumer,
+)
+from omnibase_infra.services.observability.agent_actions.consumer import (
+    AgentActionsConsumer,
+    ConsumerMetrics,
+    EnumHealthStatus,
+    mask_dsn_password,
+)
+from omnibase_infra.services.observability.agent_actions.writer_postgres import (
+    WriterAgentActionsPostgres,
+)
+
+__all__ = [
+    "AgentActionsConsumer",
+    "ConfigAgentActionsConsumer",
+    "ConsumerMetrics",
+    "EnumHealthStatus",
+    "WriterAgentActionsPostgres",
+    "mask_dsn_password",
+]