hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/core/ports/observer_manager.py

@@ -0,0 +1,130 @@
+"""Observer Manager Port - Clean interface for event observation systems.
+
+This port defines the complete contract for observer managers, including
+all safety features and configuration options from the concrete implementation.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from collections.abc import Callable, Iterable
+from typing import Any, Protocol
+
+from hexdag.core.orchestration.events.events import Event
+
+# Type aliases for observer functions
+ObserverFunc = Callable[[Event], None]
+AsyncObserverFunc = Callable[[Event], Any]  # Returns awaitable
+
+
+class Observer(Protocol):
+    """Protocol for observers that monitor events."""
+
+    async def handle(self, event: Event) -> None:
+        """Handle an event (read-only, no return value)."""
+        ...
+
+
+class ObserverManagerPort(Protocol):
+    """Port interface for event observation systems.
+
+    Key Safety Guarantees:
+    - Observers must be READ-ONLY and cannot affect execution
+    - Observer failures must not crash the pipeline (fault isolation)
+    - Fire-and-forget pattern with async, non-blocking execution
+    - Event type filtering for performance optimization
+    - Configurable concurrency control and timeouts
+    - Optional weak reference support for memory management
+    """
+
+    @abstractmethod
+    def register(
+        self,
+        handler: Observer | ObserverFunc | AsyncObserverFunc,
+        *,
+        observer_id: str | None = None,
+        event_types: Iterable[type[Event]] | type[Event] | None = None,
+        timeout: float | None = None,
+        max_concurrency: int | None = None,
+        keep_alive: bool = False,
+    ) -> str:
+        """Register an observer with optional event type filtering.
+
+        Args
+        ----
+            handler: Either an Observer protocol implementation or
+                    a function (sync/async) that takes an event
+            observer_id: Optional ID for the observer
+            event_types: Event type or collection of types to observe (None = all events)
+            timeout: Optional timeout override for this observer
+            max_concurrency: Optional per-observer concurrency cap (>= 1)
+            keep_alive: Keep a strong reference even when using weak refs
+
+        Returns
+        -------
+            str: The ID of the registered observer
+        """
+        ...
+
+    @abstractmethod
+    def unregister(self, handler_id: str) -> bool:
+        """Unregister an observer by ID.
+
+        Args
+        ----
+            handler_id: The ID of the observer to unregister
+
+        Returns
+        -------
+            bool: True if observer was found and removed, False otherwise
+        """
+        ...
+
+    @abstractmethod
+    async def notify(self, event: Event) -> None:
+        """Notify all interested observers of an event.
+
+        Only observers registered for this event type will be notified.
+        Errors are handled according to the configured error handler
+        but don't affect execution.
+
+        Args
+        ----
+            event: The event to distribute to observers
+        """
+        ...
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all registered observers."""
+        ...
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close the manager and cleanup resources."""
+        ...
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """Return number of registered observers."""
+        ...
+
+    @abstractmethod
+    def __enter__(self) -> ObserverManagerPort:
+        """Context manager entry."""
+        ...
+
+    @abstractmethod
+    def __exit__(self, _exc_type: Any, _exc_val: Any, _exc_tb: Any) -> None:
+        """Context manager exit with cleanup."""
+        ...
+
+    @abstractmethod
+    async def __aenter__(self) -> ObserverManagerPort:
+        """Async context manager entry."""
+        ...
+
+    @abstractmethod
+    async def __aexit__(self, _exc_type: Any, _exc_val: Any, _exc_tb: Any) -> None:
+        """Async context manager exit with cleanup."""
+        ...

hexdag/core/ports/secret.py

@@ -0,0 +1,145 @@
+"""Port interface for secret management (KeyVault, AWS Secrets Manager, etc.)."""
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from hexdag.core.ports.healthcheck import HealthStatus
+    from hexdag.core.ports.memory import Memory
+    from hexdag.core.types import Secret
+
+
+@runtime_checkable
+class SecretPort(Protocol):
+    """Port interface for secret/credential management systems.
+
+    This port abstracts access to secret management services like:
+    - Azure KeyVault
+    - AWS Secrets Manager
+    - HashiCorp Vault
+    - Google Secret Manager
+    - Environment variables
+
+    Secrets are returned as Secret[str] objects to prevent accidental logging.
+
+    Optional Methods
+    ----------------
+    Adapters may optionally implement:
+    - ahealth_check(): Verify secret service connectivity and authentication
+    """
+
+    @abstractmethod
+    async def aget_secret(self, key: str) -> "Secret":
+        """Retrieve a single secret by key.
+
+        Args
+        ----
+            key: Secret identifier (e.g., "OPENAI_API_KEY", "database/password")
+
+        Returns
+        -------
+        Secret
+            Secret wrapper containing the secret value. Use .get() to retrieve the value.
+
+        Raises
+        ------
+        KeyError
+            If the secret does not exist
+        ValueError
+            If the secret value is empty or invalid
+
+        Examples
+        --------
+        Example usage::
+
+            # Fetch secret from KeyVault
+            secret = await keyvault.aget_secret("OPENAI_API_KEY")
+            api_key = secret.get()  # Unwrap the secret value
+        """
+        ...
+
+    @abstractmethod
+    async def aload_secrets_to_memory(
+        self,
+        memory: "Memory",
+        prefix: str = "secret:",
+        keys: list[str] | None = None,
+    ) -> dict[str, str]:
+        """Bulk load secrets into Memory port with a prefix.
+
+        This is the primary method for pre-DAG hooks to inject secrets
+        into the pipeline's memory for nodes to access.
+
+        Args
+        ----
+            memory: Memory port instance to store secrets in
+            prefix: Key prefix for stored secrets (default: "secret:")
+            keys: List of secret keys to load. If None, loads all available secrets.
+
+        Returns
+        -------
+        dict[str, str]
+            Mapping of original key → memory key (e.g., {"API_KEY": "secret:API_KEY"})
+
+        Examples
+        --------
+        Example usage::
+
+            # Load specific secrets
+            mapping = await keyvault.aload_secrets_to_memory(
+            memory=memory,
+            keys=["OPENAI_API_KEY", "DATABASE_PASSWORD"]
+            )
+            # Returns: {"OPENAI_API_KEY": "secret:OPENAI_API_KEY", ...}
+
+            # Load all secrets
+            mapping = await keyvault.aload_secrets_to_memory(memory=memory)
+
+            # Retrieve in nodes
+            api_key = await memory.aget("secret:OPENAI_API_KEY")
+        """
+        ...
+
+    async def alist_secret_names(self) -> list[str]:
+        """List all available secret names (optional).
+
+        Returns
+        -------
+        list[str]
+            List of secret identifiers available in this secret store
+
+        Examples
+        --------
+        Example usage::
+
+            names = await keyvault.alist_secret_names()
+            # ["OPENAI_API_KEY", "DATABASE_PASSWORD", "STRIPE_KEY"]
+        """
+        ...
+
+    async def ahealth_check(self) -> "HealthStatus":
+        """Check secret service health and connectivity (optional).
+
+        Adapters should verify:
+        - Authentication/authorization status
+        - Service connectivity
+        - Access permissions
+
+        This method is optional. If not implemented, the adapter will be
+        considered healthy by default.
+
+        Returns
+        -------
+        HealthStatus
+            Current health status with details about secret service connectivity
+
+        Examples
+        --------
+        Example usage::
+
+            # Azure KeyVault health check
+            status = await keyvault.ahealth_check()
+            status.status  # "healthy", "degraded", or "unhealthy"
+            status.details  # {"vault_url": "...", "authenticated": True}
+        """
+        ...

hexdag/core/ports/tool_router.py

@@ -0,0 +1,94 @@
+"""Port interface for Tool Routers."""
+
+from abc import abstractmethod
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ToolRouter(Protocol):
+    """Protocol for routing tool calls."""
+
+    # Required methods
+    @abstractmethod
+    async def acall_tool(self, tool_name: str, params: dict[str, Any]) -> Any:
+        """Call a tool with parameters.
+
+        Args
+        ----
+            tool_name: The name of the tool to call.
+            params: Parameters to pass to the tool.
+
+        Returns
+        -------
+            The result of the tool call.
+        """
+        ...
+
+    @abstractmethod
+    def get_available_tools(self) -> list[str]:
+        """Get list of available tool names (sync version for local adapters).
+
+        Returns
+        -------
+            List of tool names that can be called
+        """
+        ...
+
+    async def aget_available_tools(self) -> list[str]:
+        """Get list of available tool names (async version for remote/MCP adapters).
+
+        Default implementation delegates to sync version. Override for true async behavior.
+
+        Returns
+        -------
+            List of tool names that can be called
+        """
+        return self.get_available_tools()
+
+    def get_tool_schema(self, tool_name: str) -> dict[str, Any]:
+        """Get schema for a specific tool (sync version).
+
+        Args
+        ----
+            tool_name: Name of the tool
+
+        Returns
+        -------
+            Dictionary containing tool schema (name, description, parameters)
+        """
+        ...
+
+    async def aget_tool_schema(self, tool_name: str) -> dict[str, Any]:
+        """Get schema for a specific tool (async version for remote/MCP adapters).
+
+        Default implementation delegates to sync version. Override for true async behavior.
+
+        Args
+        ----
+            tool_name: Name of the tool
+
+        Returns
+        -------
+            Dictionary containing tool schema (name, description, parameters)
+        """
+        return self.get_tool_schema(tool_name)
+
+    def get_all_tool_schemas(self) -> dict[str, dict[str, Any]]:
+        """Get schemas for all available tools (sync version).
+
+        Returns
+        -------
+            Dictionary mapping tool names to their schemas
+        """
+        ...
+
+    async def aget_all_tool_schemas(self) -> dict[str, dict[str, Any]]:
+        """Get schemas for all available tools (async version for remote/MCP adapters).
+
+        Default implementation delegates to sync version. Override for true async behavior.
+
+        Returns
+        -------
+            Dictionary mapping tool names to their schemas
+        """
+        return self.get_all_tool_schemas()