hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/builtin/adapters/secret/local_secret_adapter.py

@@ -0,0 +1,248 @@
+"""Local environment variable based secret adapter."""
+
+import os
+from typing import TYPE_CHECKING, Any
+
+from hexdag.core.logging import get_logger
+from hexdag.core.types import Secret
+
+if TYPE_CHECKING:
+    from hexdag.core.ports.healthcheck import HealthStatus
+    from hexdag.core.ports.memory import Memory
+
+logger = get_logger(__name__)
+
+
+class LocalSecretAdapter:
+    """Local secret adapter that reads from environment variables.
+
+    This adapter implements the SecretPort interface using local environment
+    variables as the secret source. It's useful for:
+    - Development and testing
+    - CI/CD pipelines
+    - Simple deployments without external secret managers
+
+    The adapter wraps secrets in the Secret class to prevent accidental logging.
+
+    Examples
+    --------
+    Basic usage::
+
+        secrets = LocalSecretAdapter()
+
+        api_key = await secrets.aget_secret("OPENAI_API_KEY")
+        print(api_key)  # <SECRET> (hidden)
+        print(api_key.get())  # "sk-..." (actual value)
+
+        # Load secrets into Memory for orchestrator
+        mapping = await secrets.aload_secrets_to_memory(
+            memory=memory,
+            keys=["OPENAI_API_KEY", "DATABASE_PASSWORD"]
+        )
+        # Returns: {"OPENAI_API_KEY": "secret:OPENAI_API_KEY", ...}
+
+    With prefix filtering::
+
+        # Only load secrets with specific prefix
+        secrets = LocalSecretAdapter(env_prefix="MYAPP_")
+        # Will look for MYAPP_OPENAI_API_KEY, etc.
+    """
+
+    # Type annotations for attributes
+    env_prefix: str
+    allow_empty: bool
+    _cache: dict[str, Secret]
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize local secret adapter.
+
+        Args
+        ----
+            **kwargs: Configuration options (env_prefix, allow_empty)
+        """
+        self.env_prefix = kwargs.get("env_prefix", "")
+        self.allow_empty = kwargs.get("allow_empty", False)
+
+        self._cache: dict[str, Secret] = {}
+
+    async def aget_secret(self, key: str) -> Secret:
+        """Retrieve a single secret from environment variables.
+
+        Args
+        ----
+            key: Secret identifier (environment variable name)
+
+        Returns
+        -------
+        Secret
+            Secret wrapper containing the secret value
+
+        Raises
+        ------
+        KeyError
+            If the secret is not found in environment variables
+        ValueError
+            If the secret value is empty (unless allow_empty=True)
+
+        Examples
+        --------
+        >>> import os
+        >>> os.environ["OPENAI_API_KEY"] = "sk-test"
+        >>> adapter = LocalSecretAdapter()
+        >>> secret = await adapter.aget_secret("OPENAI_API_KEY")  # doctest: +SKIP
+        >>> print(secret)  # doctest: +SKIP
+        <SECRET>
+        >>> secret.get()  # doctest: +SKIP
+        'sk-test'
+        """
+        # Check cache first (environment variables don't change at runtime)
+        if key in self._cache:
+            logger.debug(f"Retrieved secret '{key}' from cache")
+            return self._cache[key]
+
+        env_var_name = f"{self.env_prefix}{key}"
+
+        value = os.getenv(env_var_name)
+
+        if value is None:
+            raise KeyError(
+                f"Secret '{key}' not found in environment variables (looked for: {env_var_name})"
+            )
+
+        if value == "" and not self.allow_empty:
+            raise ValueError(
+                f"Secret '{key}' cannot be empty (set allow_empty=True to allow empty secrets)"
+            )
+
+        logger.debug(f"Retrieved secret '{key}' from environment")
+        secret = Secret(value)
+
+        self._cache[key] = secret
+
+        return secret
+
+    async def aload_secrets_to_memory(
+        self,
+        memory: "Memory",
+        prefix: str = "secret:",
+        keys: list[str] | None = None,
+    ) -> dict[str, str]:
+        """Bulk load secrets from environment into Memory port.
+
+        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 env vars.
+
+        Returns
+        -------
+        dict[str, str]
+            Mapping of original key → memory key
+
+        Examples
+        --------
+        >>> import os
+        >>> os.environ["OPENAI_API_KEY"] = "sk-test"
+        >>> os.environ["DATABASE_PASSWORD"] = "pass123"
+        >>> adapter = LocalSecretAdapter()
+        >>> # Load specific secrets
+        >>> mapping = await adapter.aload_secrets_to_memory(  # doctest: +SKIP
+        ...     memory=memory,
+        ...     keys=["OPENAI_API_KEY"]
+        ... )
+        >>> mapping  # doctest: +SKIP
+        {'OPENAI_API_KEY': 'secret:OPENAI_API_KEY'}
+        """
+        mapping: dict[str, str] = {}
+
+        if keys is None:
+            # Load all environment variables (with prefix if configured)
+            keys = [
+                key.removeprefix(self.env_prefix)
+                for key in os.environ
+                if key.startswith(self.env_prefix)
+            ]
+            logger.debug(f"Auto-discovered {len(keys)} environment variables")
+
+        # Load each secret
+        loaded_count = 0
+        for key in keys:
+            try:
+                secret = await self.aget_secret(key)
+                memory_key = f"{prefix}{key}"
+                await memory.aset(memory_key, secret.get())
+                mapping[key] = memory_key
+                loaded_count += 1
+                logger.debug(f"Loaded secret '{key}' → '{memory_key}'")
+            except (KeyError, ValueError) as e:
+                logger.warning(f"Failed to load secret '{key}': {e}")
+                continue
+
+        logger.info(f"Loaded {loaded_count}/{len(keys)} secrets into Memory with prefix '{prefix}'")
+        return mapping
+
+    async def alist_secret_names(self) -> list[str]:
+        """List all available secret names from environment variables.
+
+        Returns
+        -------
+        list[str]
+            List of environment variable names (with prefix removed)
+
+        Examples
+        --------
+        >>> import os
+        >>> os.environ["OPENAI_API_KEY"] = "sk-test"
+        >>> os.environ["DATABASE_PASSWORD"] = "pass123"
+        >>> adapter = LocalSecretAdapter()
+        >>> await adapter.alist_secret_names()  # doctest: +SKIP
+        ['OPENAI_API_KEY', 'DATABASE_PASSWORD', ...]
+        """
+        names = [
+            key.removeprefix(self.env_prefix)
+            for key in os.environ
+            if key.startswith(self.env_prefix)
+        ]
+        logger.debug(f"Found {len(names)} environment variables")
+        return names
+
+    async def ahealth_check(self) -> "HealthStatus":
+        """Check health status of local environment variable access.
+
+        Returns
+        -------
+        HealthStatus
+            Health status with environment variable count
+
+        Examples
+        --------
+        >>> adapter = LocalSecretAdapter()
+        >>> status = await adapter.ahealth_check()  # doctest: +SKIP
+        >>> status.status  # doctest: +SKIP
+        'healthy'
+        """
+        from hexdag.core.ports.healthcheck import HealthStatus
+
+        try:
+            # Count available env vars
+            names = await self.alist_secret_names()
+            return HealthStatus(
+                status="healthy",
+                adapter_name="local_env",
+                port_name="secret",
+                details={
+                    "env_vars_count": len(names),
+                    "env_prefix": self.env_prefix or "(none)",
+                },
+            )
+        except Exception as e:
+            return HealthStatus(
+                status="unhealthy",
+                adapter_name="local_env",
+                port_name="secret",
+                error=e,
+                details={
+                    "error_message": str(e),
+                },
+            )

hexdag/builtin/adapters/unified_tool_router.py

@@ -0,0 +1,280 @@
+"""ToolRouter adapter that aggregates multiple tool routers with namespacing."""
+
+import asyncio
+import inspect
+from typing import Any
+
+from hexdag.builtin.nodes.tool_utils import ToolDefinition, ToolParameter
+from hexdag.core.exceptions import ResourceNotFoundError
+from hexdag.core.logging import get_logger
+from hexdag.core.ports.tool_router import ToolRouter
+from hexdag.core.protocols import has_execute_method
+
+logger = get_logger(__name__)
+
+__all__ = ["UnifiedToolRouter"]
+
+
+class UnifiedToolRouter(ToolRouter):
+    """ToolRouter adapter that supports multiple tool sources with namespacing.
+
+    This adapter aggregates multiple tool routers and provides unified access
+    with namespace prefixes (e.g., "builtin::tool", "mcp::tool").
+
+    Example
+    -------
+        router = UnifiedToolRouter(routers={
+            "builtin": PythonToolRouter(),
+            "mcp_sql": MCPToolRouter("sqlite"),
+        })
+        result = await router.acall_tool("builtin::search_papers", {"query": "..."})
+    """
+
+    def __init__(self, routers: dict[str, ToolRouter] | None = None, **kwargs: Any) -> None:
+        """Initialize the router.
+
+        Args
+        ----
+            routers: Dict of {router_id: ToolRouter} for multi-router mode
+            **kwargs: Additional configuration options
+        """
+        self.routers = routers or {}
+
+        # Store first router as default for unprefixed calls
+        self.default_router = next(iter(self.routers.values())) if self.routers else None
+
+    async def acall_tool(self, tool_name: str, params: dict[str, Any]) -> Any:
+        """Call a tool with parameters.
+
+        Supports both namespaced ("router_id::tool_name") and plain tool names.
+
+        Args
+        ----
+            tool_name: Name of the tool to execute (with optional "router::" prefix)
+            params: Parameters to pass to the tool
+
+        Returns
+        -------
+            Tool execution result
+        """
+        # Parse namespace: "builtin::tool" or "tool"
+        if "::" in tool_name:
+            router_id, actual_tool = tool_name.split("::", 1)
+            if router_id not in self.routers:
+                available_routers = list(self.routers.keys())
+                raise ResourceNotFoundError(
+                    "tool_router",
+                    router_id,
+                    available_routers,
+                )
+            router = self.routers[router_id]
+        else:
+            # No prefix: use default router
+            if not self.default_router:
+                raise ResourceNotFoundError(
+                    "tool",
+                    tool_name,
+                    [],
+                )
+            router = self.default_router
+            actual_tool = tool_name
+
+        # Delegate to the specific router
+        return await router.acall_tool(actual_tool, params)
+
+    async def _execute_tool(self, tool: Any, params: dict[str, Any]) -> Any:
+        """Execute any tool (function, class, or instance) with parameters.
+
+        Raises
+        ------
+        ValueError
+            If tool is not executable
+        """
+        try:
+            if inspect.iscoroutinefunction(tool):
+                return await self._call_with_params(tool, params, is_async=True)
+            if has_execute_method(tool):
+                # Class with execute method (protocol-based check)
+                execute_method = tool.execute
+                if asyncio.iscoroutinefunction(execute_method):
+                    return await self._call_with_params(execute_method, params, is_async=True)
+                return self._call_with_params(execute_method, params, is_async=False)
+            if callable(tool):
+                # Regular function
+                return self._call_with_params(tool, params, is_async=False)
+            raise ValueError(f"Tool {tool} is not executable")
+
+        except Exception as e:
+            raise e
+
+    def _call_with_params(self, func: Any, params: dict[str, Any], is_async: bool) -> Any:
+        """Call function with appropriate parameters.
+
+        Args
+        ----
+            func: Function to call
+            params: Parameters dict
+            is_async: Whether function is async
+
+        Returns
+        -------
+            Function result (or coroutine if async)
+        """
+        sig = inspect.signature(func)
+
+        has_var_keyword = any(
+            p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values()
+        )
+
+        if has_var_keyword:
+            kwargs = params
+        else:
+            # Filter to only expected parameters
+            kwargs = {}
+            for param_name in sig.parameters:
+                if param_name in params:
+                    kwargs[param_name] = params[param_name]
+
+        if is_async:
+            return func(**kwargs)  # Return coroutine, caller will await
+        return func(**kwargs)
+
+    def get_available_tools(self) -> list[str]:
+        """Get list of available tool names.
+
+        Returns namespaced tools: ["router1::tool1", "router2::tool2"]
+        """
+        all_tools = []
+        for router_id, router in self.routers.items():
+            try:
+                router_tools = router.get_available_tools()
+                # Prefix each tool with router ID
+                namespaced_tools = [f"{router_id}::{tool}" for tool in router_tools]
+                all_tools.extend(namespaced_tools)
+            except Exception as e:
+                logger.debug("Could not list tools from router %s: %s", router_id, e)
+        return all_tools
+
+    def get_tool_schema(self, tool_name: str) -> dict[str, Any]:
+        """Get schema for a specific tool.
+
+        Args
+        ----
+            tool_name: Name of the tool (with optional "router::" prefix)
+
+        Returns
+        -------
+            Tool schema dictionary or empty dict if not found
+        """
+        # Parse namespace
+        router_id: str
+        if "::" in tool_name:
+            router_id, actual_tool = tool_name.split("::", 1)
+            if router_id not in self.routers:
+                return {}
+            router = self.routers[router_id]
+        else:
+            if not self.default_router:
+                return {}
+            router = self.default_router
+            router_id = "default"
+            actual_tool = tool_name
+
+        # Get schema from specific router
+        try:
+            schema = router.get_tool_schema(actual_tool)
+            # Add router info
+            schema["_router"] = router_id
+            return schema
+        except Exception as e:
+            logger.debug("Could not get tool schema from router: %s", e)
+            return {}
+
+    def get_all_tool_schemas(self) -> dict[str, dict[str, Any]]:
+        """Get schemas for all available tools.
+
+        Returns schemas with namespaced keys.
+        """
+        schemas = {}
+        for tool_name in self.get_available_tools():
+            if schema := self.get_tool_schema(tool_name):
+                schemas[tool_name] = schema
+        return schemas
+
+    async def aget_available_tools(self) -> list[str]:
+        """Async version of get_available_tools."""
+        all_tools = []
+        for router_id, router in self.routers.items():
+            try:
+                # Use async method if available
+                if hasattr(router, "aget_available_tools"):
+                    router_tools = await router.aget_available_tools()
+                else:
+                    router_tools = router.get_available_tools()
+                namespaced_tools = [f"{router_id}::{tool}" for tool in router_tools]
+                all_tools.extend(namespaced_tools)
+            except Exception as e:
+                logger.debug("Could not list tools from router %s: %s", router_id, e)
+        return all_tools
+
+    async def aget_tool_schema(self, tool_name: str) -> dict[str, Any]:
+        """Async version of get_tool_schema."""
+        # Parse namespace
+        router_id: str
+        if "::" in tool_name:
+            router_id, actual_tool = tool_name.split("::", 1)
+            if router_id not in self.routers:
+                return {}
+            router = self.routers[router_id]
+        else:
+            if not self.default_router:
+                return {}
+            router = self.default_router
+            router_id = "default"
+            actual_tool = tool_name
+
+        # Get schema from specific router (async if available)
+        try:
+            if hasattr(router, "aget_tool_schema"):
+                schema = await router.aget_tool_schema(actual_tool)
+            else:
+                schema = router.get_tool_schema(actual_tool)
+            schema["_router"] = router_id
+            return schema
+        except Exception as e:
+            logger.debug("Could not get tool schema from router: %s", e)
+            return {}
+
+    def get_tool_definitions(self) -> list[ToolDefinition]:
+        """Get ToolDefinitions from all routers.
+
+        Returns
+        -------
+            List of ToolDefinitions generated from router tools
+        """
+        definitions = []
+        for router_id, router in self.routers.items():
+            try:
+                for tool_name in router.get_available_tools():
+                    schema = router.get_tool_schema(tool_name)
+                    if schema:
+                        tool_def = ToolDefinition(
+                            name=f"{router_id}::{tool_name}",
+                            simplified_description=schema.get("description", f"Tool {tool_name}"),
+                            detailed_description=schema.get("description", f"Tool {tool_name}"),
+                            parameters=[
+                                ToolParameter(
+                                    name=p.get("name", ""),
+                                    description=p.get("description", ""),
+                                    param_type=p.get("type", "Any"),
+                                    required=p.get("required", False),
+                                    default=p.get("default"),
+                                )
+                                for p in schema.get("parameters", [])
+                            ],
+                            examples=[f"{router_id}::{tool_name}()"],
+                        )
+                        definitions.append(tool_def)
+            except Exception as e:
+                logger.debug("Could not get tool definitions from router %s: %s", router_id, e)
+        return definitions

hexdag/builtin/macros/__init__.py

@@ -0,0 +1,17 @@
+"""Built-in macro implementations for hexDAG."""
+
+from hexdag.builtin.macros.conversation_agent import ConversationConfig, ConversationMacro
+from hexdag.builtin.macros.llm_macro import LLMMacro, LLMMacroConfig
+from hexdag.builtin.macros.reasoning_agent import ReasoningAgentConfig, ReasoningAgentMacro
+from hexdag.builtin.macros.tool_macro import ToolMacro, ToolMacroConfig
+
+__all__ = [
+    "ConversationConfig",
+    "ConversationMacro",
+    "LLMMacro",
+    "LLMMacroConfig",
+    "ReasoningAgentConfig",
+    "ReasoningAgentMacro",
+    "ToolMacro",
+    "ToolMacroConfig",
+]