hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/__init__.py

@@ -0,0 +1,116 @@
+"""Hex-DAG Agent Framework.
+
+A modular, deterministic, and extensible architecture for orchestrating LLM-powered agents alongside
+traditional code with YAML pipeline configuration.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+# Version is defined in pyproject.toml and read dynamically
+try:
+    from importlib.metadata import version
+
+    __version__ = version("hexdag")
+except Exception:
+    __version__ = "0.0.0.dev0"  # Fallback for development installs
+
+# Core framework exports
+from hexdag.builtin.nodes import (
+    ConditionalNode,
+    FunctionNode,
+    LLMNode,
+    LoopNode,
+    ReActAgentNode,
+)
+from hexdag.core.domain import DirectedGraph, NodeSpec
+from hexdag.core.orchestration.orchestrator import Orchestrator
+from hexdag.core.orchestration.prompt import FewShotPromptTemplate, PromptTemplate
+
+# YAML Workflow Builder
+from hexdag.core.pipeline_builder.yaml_builder import YamlPipelineBuilder
+
+# Port interfaces
+from hexdag.core.ports import LLM, APICall, DatabasePort, ToolRouter
+
+# Import resolver for component resolution
+from hexdag.core.resolver import resolve, resolve_function
+
+# Define placeholders for lazy-loaded adapters to satisfy __all__ checking
+# These will be replaced by __getattr__ when accessed
+if TYPE_CHECKING:
+    from hexdag.builtin.adapters.memory import InMemoryMemory
+    from hexdag.builtin.adapters.mock import MockDatabaseAdapter, MockLLM
+
+
+# Lazy loading for adapters and optional modules to avoid circular imports
+def __getattr__(name: str) -> Any:
+    """Lazy import for adapters and optional components.
+
+    Raises
+    ------
+    ImportError
+        If visualization module is not available
+    AttributeError
+        If the requested attribute does not exist
+    """
+    # Mock adapters
+    if name == "MockLLM":
+        from hexdag.builtin.adapters.mock import MockLLM as _MockLLM
+
+        return _MockLLM
+    if name == "MockDatabaseAdapter":
+        from hexdag.builtin.adapters.mock import MockDatabaseAdapter as _MockDatabaseAdapter
+
+        return _MockDatabaseAdapter
+    if name == "MockToolRouter":
+        from hexdag.builtin.adapters.mock import MockToolRouter as _MockToolRouter
+
+        return _MockToolRouter
+
+    # Visualization components (optional)
+    if name == "DAGVisualizer":
+        try:
+            from hexdag.visualization import DAGVisualizer as _DAGVisualizer
+
+            return _DAGVisualizer
+        except ImportError as e:
+            raise ImportError(
+                "Visualization module not available. Install with:\n"
+                "  pip install hexdag[viz]\n"
+                "  or\n"
+                "  uv pip install hexdag[viz]"
+            ) from e
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Version
+    "__version__",
+    # Module Resolution
+    "resolve",
+    "resolve_function",
+    # Core Framework - DAG Building and Execution
+    "Orchestrator",
+    "DirectedGraph",
+    "NodeSpec",
+    "YamlPipelineBuilder",
+    # Node Factories
+    "FunctionNode",
+    "LLMNode",
+    "ReActAgentNode",
+    "LoopNode",
+    "ConditionalNode",
+    # Templating System
+    "PromptTemplate",
+    "FewShotPromptTemplate",
+    # Port Interfaces
+    "LLM",
+    "APICall",
+    "ToolRouter",
+    "DatabasePort",
+    # Testing and Development Adapters
+    "InMemoryMemory",
+    "MockLLM",
+    "MockDatabaseAdapter",
+]

hexdag/__main__.py

@@ -0,0 +1,30 @@
+"""Entry point for running hexDAG as a module.
+
+Supports both CLI and MCP server modes:
+- python -m hexdag [CLI command]
+- python -m hexdag --mcp (starts MCP server)
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    """Main entry point for module execution."""
+    # Check if --mcp flag is present
+    if "--mcp" in sys.argv:
+        # Remove --mcp flag and run MCP server
+        sys.argv.remove("--mcp")
+        from hexdag.mcp_server import mcp
+
+        mcp.run()
+    else:
+        # Run regular CLI
+        from hexdag.cli import main as cli_main
+
+        cli_main()
+
+
+if __name__ == "__main__":
+    main()

hexdag/adapters/executors/__init__.py

@@ -0,0 +1,5 @@
+"""Executor adapters for different execution strategies."""
+
+from hexdag.adapters.executors.local_executor import LocalExecutor
+
+__all__ = ["LocalExecutor"]

hexdag/adapters/executors/local_executor.py

@@ -0,0 +1,316 @@
+"""Local in-process executor adapter.
+
+This executor runs nodes in the same process using asyncio, providing
+the same behavior as the built-in orchestrator execution but through
+the ExecutorPort interface.
+"""
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any
+
+from hexdag.core.context import get_port
+from hexdag.core.logging import get_logger
+from hexdag.core.orchestration.components import (
+    ExecutionCoordinator,
+    NodeExecutionError,
+    NodeExecutor,
+)
+from hexdag.core.orchestration.constants import (
+    EXECUTOR_CONTEXT_GRAPH,
+    EXECUTOR_CONTEXT_INITIAL_INPUT,
+    EXECUTOR_CONTEXT_NODE_RESULTS,
+)
+from hexdag.core.orchestration.hook_context import PipelineStatus
+from hexdag.core.orchestration.models import NodeExecutionContext
+from hexdag.core.ports.executor import (
+    ExecutionResult,
+    ExecutionTask,
+)
+
+if TYPE_CHECKING:
+    from hexdag.core.domain.dag import DirectedGraph, NodeSpec
+
+logger = get_logger(__name__)
+
+
+def _calculate_duration_ms(start_time: float) -> float:
+    """Calculate duration in milliseconds from start time.
+
+    Parameters
+    ----------
+    start_time : float
+        Start time from time.time()
+
+    Returns
+    -------
+    float
+        Duration in milliseconds
+    """
+    return (time.time() - start_time) * 1000
+
+
+class Local:
+    """Configuration for LocalExecutor.
+
+    Attributes
+    ----------
+    max_concurrent_nodes : int
+        Maximum number of nodes to execute concurrently (default: 10)
+    strict_validation : bool
+        If True, raise errors on validation failure (default: False)
+    default_node_timeout : float | None
+        Default timeout in seconds for each node (default: None, no timeout)
+    """
+
+    max_concurrent_nodes: int = 10
+    strict_validation: bool = False
+    default_node_timeout: float | None = None
+
+
+class LocalExecutor:
+    """Local in-process executor using asyncio.
+
+    This executor wraps the core NodeExecutor and WaveExecutor to provide
+    the same in-process execution behavior but through the ExecutorPort
+    interface. It's useful for:
+
+    1. Testing the executor abstraction
+    2. Providing a consistent interface across execution strategies
+    3. Serving as a reference implementation for other executors
+
+    The LocalExecutor maintains the same features as built-in execution:
+    - Async/sync function support
+    - Validation and type checking
+    - Timeout handling
+    - Event emission
+    - Policy evaluation
+
+    Examples
+    --------
+    Basic usage::
+
+        executor = LocalExecutor(max_concurrent_nodes=5)
+        orchestrator = Orchestrator(executor=executor)
+        results = await orchestrator.run(graph, input_data)
+
+    With validation and timeout::
+
+        executor = LocalExecutor(
+            strict_validation=True,
+            default_node_timeout=30.0
+        )
+        orchestrator = Orchestrator(executor=executor)
+
+    From YAML::
+
+        executor:
+          type: local
+          namespace: core
+          params:
+            max_concurrent_nodes: 20
+            strict_validation: true
+            default_node_timeout: 60.0
+    """
+
+    def __init__(
+        self, strict_validation: bool = True, default_node_timeout: float = 60.0, **kwargs: Any
+    ) -> None:
+        """Initialize local executor.
+
+        Parameters
+        ----------
+        strict_validation : bool, default=True
+            Enable strict validation
+        default_node_timeout : float, default=60.0
+            Default timeout for nodes in seconds
+        """
+        self.strict_validation = strict_validation
+        self.default_node_timeout = default_node_timeout
+        self.max_concurrent_nodes = kwargs.get("max_concurrent_nodes", 10)
+
+        # Core execution components
+        self._node_executor = NodeExecutor(
+            strict_validation=strict_validation,
+            default_node_timeout=default_node_timeout,
+        )
+        self._execution_coordinator = ExecutionCoordinator()
+
+        # State for tracking
+        self._initialized = False
+
+    async def aexecute_node(self, task: ExecutionTask) -> ExecutionResult:
+        """Execute a single node in-process.
+
+        Parameters
+        ----------
+        task : ExecutionTask
+            Task containing node information and input data
+
+        Returns
+        -------
+        ExecutionResult
+            Result of the execution with output or error information
+
+        Raises
+        ------
+        RuntimeError
+            If executor not initialized via asetup()
+
+        Notes
+        -----
+        This method expects that the orchestrator has set up the execution
+        context with the graph and ports. The task.context_data should contain
+        the necessary execution context information.
+        """
+        if not self._initialized:
+            raise RuntimeError("LocalExecutor not initialized - call asetup() first")
+
+        start_time = time.time()
+
+        try:
+            # Note: Uses ContextVar pattern consistent with rest of codebase
+            graph: DirectedGraph = get_port(EXECUTOR_CONTEXT_GRAPH)
+            node_results: dict[str, Any] = get_port(EXECUTOR_CONTEXT_NODE_RESULTS)
+            initial_input: Any = get_port(EXECUTOR_CONTEXT_INITIAL_INPUT)
+
+            if graph is None:
+                raise RuntimeError(
+                    "LocalExecutor requires execution context with graph. "
+                    "Ensure orchestrator has set up context properly."
+                )
+
+            if task.node_name not in graph.nodes:
+                return ExecutionResult(
+                    node_name=task.node_name,
+                    status=PipelineStatus.FAILED,
+                    error=f"Node '{task.node_name}' not found in graph",
+                    error_type="KeyError",
+                    duration_ms=_calculate_duration_ms(start_time),
+                )
+
+            node_spec: NodeSpec = graph.nodes[task.node_name]
+
+            # Prepare input using ExecutionCoordinator
+            node_input = self._execution_coordinator.prepare_node_input(
+                node_spec, node_results, initial_input
+            )
+
+            execution_context = NodeExecutionContext(
+                dag_id=task.context_data.get("dag_id", "unnamed"),
+                node_id=task.node_name,
+                wave_index=task.wave_index,
+                attempt=task.context_data.get("attempt", 1),
+                metadata=task.context_data,
+            )
+
+            # Execute using NodeExecutor
+            output = await self._node_executor.execute_node(
+                node_name=task.node_name,
+                node_spec=node_spec,
+                node_input=node_input,
+                context=execution_context,
+                coordinator=self._execution_coordinator,
+                wave_index=task.wave_index,
+                validate=task.should_validate,
+                **task.params,
+            )
+
+            return ExecutionResult(
+                node_name=task.node_name,
+                output=output,
+                status=PipelineStatus.SUCCESS,
+                duration_ms=_calculate_duration_ms(start_time),
+            )
+
+        except NodeExecutionError:
+            # NodeExecutionError should propagate directly (orchestrator will handle)
+            raise
+        except (ValueError, TypeError, KeyError, AttributeError, RuntimeError) as e:
+            # Catch expected execution errors (validation, type issues, missing data)
+            logger.error(f"LocalExecutor: Node '{task.node_name}' failed: {e}")
+            return ExecutionResult(
+                node_name=task.node_name,
+                status=PipelineStatus.FAILED,
+                error=str(e),
+                error_type=type(e).__name__,
+                duration_ms=_calculate_duration_ms(start_time),
+            )
+        except Exception as e:
+            # Catch unexpected errors but log with higher severity
+            logger.exception(f"LocalExecutor: Unexpected error in node '{task.node_name}': {e}")
+            return ExecutionResult(
+                node_name=task.node_name,
+                status=PipelineStatus.FAILED,
+                error=str(e),
+                error_type=type(e).__name__,
+                duration_ms=_calculate_duration_ms(start_time),
+            )
+
+    async def aexecute_wave(self, tasks: list[ExecutionTask]) -> dict[str, ExecutionResult]:
+        """Execute multiple nodes concurrently within a wave.
+
+        Parameters
+        ----------
+        tasks : list[ExecutionTask]
+            List of tasks to execute in parallel
+
+        Returns
+        -------
+        dict[str, ExecutionResult]
+            Map of node_name -> execution result
+
+        Raises
+        ------
+        RuntimeError
+            If executor not initialized via asetup()
+
+        Notes
+        -----
+        This method uses asyncio.gather to execute all tasks concurrently,
+        respecting the max_concurrent_nodes limit via semaphore.
+        """
+        if not self._initialized:
+            raise RuntimeError("LocalExecutor not initialized - call asetup() first")
+
+        semaphore = asyncio.Semaphore(self.max_concurrent_nodes)
+
+        async def execute_with_limit(task: ExecutionTask) -> ExecutionResult:
+            """Execute task with semaphore-based concurrency control."""
+            async with semaphore:
+                return await self.aexecute_node(task)
+
+        # Execute all tasks concurrently with semaphore limit
+        results_list = await asyncio.gather(
+            *[execute_with_limit(task) for task in tasks],
+            return_exceptions=True,
+        )
+
+        results = {}
+        for result in results_list:
+            if isinstance(result, ExecutionResult):
+                results[result.node_name] = result
+            elif isinstance(result, Exception):
+                # Can happen if task is cancelled during gather()
+                logger.error(f"Exception during wave execution: {result}")
+                raise result
+
+        return results
+
+    async def asetup(self) -> None:
+        """Initialize executor resources.
+
+        For LocalExecutor, this is a no-op as all resources are
+        in-process and don't require setup.
+        """
+        self._initialized = True
+        logger.debug("LocalExecutor initialized")
+
+    async def aclose(self) -> None:
+        """Cleanup executor resources.
+
+        For LocalExecutor, this is a no-op as all resources are
+        in-process and don't require cleanup.
+        """
+        self._initialized = False
+        logger.debug("LocalExecutor closed")

hexdag/builtin/__init__.py

@@ -0,0 +1,6 @@
+"""Built-in plugins for hexDAG framework.
+
+This module contains built-in implementations of nodes, adapters, tools,
+policies, and observers that ship with hexDAG. All components in this
+module are registrable plugins with namespace="core".
+"""

hexdag/builtin/adapters/__init__.py

@@ -0,0 +1,51 @@
+"""Initalize the hexdag adapter package."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .unified_tool_router import UnifiedToolRouter  # noqa: F401
+
+_LAZY_MAP: dict[str, tuple[str, str]] = {
+    "UnifiedToolRouter": (
+        "hexdag.adapters.unified_tool_router",
+        "UnifiedToolRouter",
+    ),
+    # Backward compatibility alias
+    "FunctionBasedToolRouter": (
+        "hexdag.adapters.unified_tool_router",
+        "UnifiedToolRouter",
+    ),
+}
+
+__all__: tuple[str, ...] = tuple(_LAZY_MAP)
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import for adapters.
+
+    Returns
+    -------
+    Any
+        The imported adapter class or module.
+
+    Raises
+    ------
+    AttributeError
+        If the requested name is not found in the lazy import map.
+    """
+    if name in _LAZY_MAP:
+        module_name, attr = _LAZY_MAP[name]
+        module = importlib.import_module(module_name)
+        value = getattr(module, attr)
+
+        # Register the port dynamically if necessary
+        if hasattr(value, "register_port"):
+            value.register_port()
+
+        globals()[name] = value  # Cache the imported module in the globals for future access
+        return value
+
+    raise AttributeError(f"module {__name__} has no attribute {name}")

hexdag/builtin/adapters/anthropic/__init__.py

@@ -0,0 +1,5 @@
+"""Anthropic adapters for hexDAG."""
+
+from hexdag.builtin.adapters.anthropic.anthropic_adapter import AnthropicAdapter
+
+__all__ = ["AnthropicAdapter"]

hexdag/builtin/adapters/anthropic/anthropic_adapter.py

@@ -0,0 +1,151 @@
+"""Anthropic adapter for LLM interactions."""
+
+import os
+from typing import Any
+
+from anthropic import AsyncAnthropic
+
+from hexdag.core.logging import get_logger
+from hexdag.core.ports.llm import MessageList
+from hexdag.core.types import (
+    PositiveInt,
+    RetryCount,
+    Temperature01,
+    TimeoutSeconds,
+    TopP,
+)
+
+logger = get_logger(__name__)
+
+
+class AnthropicAdapter:
+    """Anthropic implementation of the LLM port.
+
+    This adapter provides integration with Anthropic's Claude models through
+    their API. It supports async operations and handles message conversion
+    between hexDAG's format and Anthropic's format.
+
+    Secret Management
+    -----------------
+    API key resolution order:
+    1. Explicit parameter: AnthropicAdapter(api_key="sk-...")
+    2. Environment variable: ANTHROPIC_API_KEY
+    3. Memory port (orchestrator): secret:ANTHROPIC_API_KEY
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = "claude-3-5-sonnet-20241022",
+        temperature: Temperature01 = 0.7,
+        max_tokens: PositiveInt = 4096,
+        top_p: TopP = 1.0,
+        top_k: PositiveInt | None = None,
+        system_prompt: str | None = None,
+        timeout: TimeoutSeconds = 60.0,
+        max_retries: RetryCount = 2,
+        **kwargs: Any,  # ← For extra params like base_url
+    ):
+        """Initialize Anthropic adapter.
+
+        Parameters
+        ----------
+        api_key : str | None
+            Anthropic API key (auto-resolved from ANTHROPIC_API_KEY env var if not provided)
+        model : str, default="claude-3-5-sonnet-20241022"
+            Claude model to use
+        temperature : float, default=0.7
+            Sampling temperature (0-1)
+        max_tokens : int, default=4096
+            Maximum tokens in response
+        top_p : float, default=1.0
+            Nucleus sampling parameter
+        top_k : int | None, default=None
+            Top-k sampling parameter
+        system_prompt : str | None, default=None
+            System prompt to use
+        timeout : float, default=60.0
+            Request timeout in seconds
+        max_retries : int, default=2
+            Maximum retry attempts
+        """
+        self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+        if not self.api_key:
+            raise ValueError("api_key required (pass directly or set ANTHROPIC_API_KEY)")
+        self.model = model
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.top_p = top_p
+        self.top_k = top_k
+        self.system_prompt = system_prompt
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._extra_kwargs = kwargs  # Store extra params
+
+        client_kwargs: dict[str, Any] = {
+            "api_key": self.api_key,
+            "timeout": timeout,
+            "max_retries": max_retries,
+        }
+
+        if base_url := kwargs.get("base_url"):
+            client_kwargs["base_url"] = base_url
+
+        self.client = AsyncAnthropic(**client_kwargs)
+
+    async def aresponse(self, messages: MessageList) -> str | None:
+        """Generate a response using Anthropic's API.
+
+        Args
+        ----
+            messages: List of Message objects with role and content
+
+        Returns
+        -------
+            The generated response text, or None if failed
+        """
+        try:
+            # Anthropic requires system messages to be separate
+            system_message = self.system_prompt
+            anthropic_messages = []
+
+            for msg in messages:
+                if msg.role == "system":
+                    # Concatenate multiple system messages if present
+                    if system_message:
+                        system_message += "\n" + msg.content
+                    else:
+                        system_message = msg.content
+                else:
+                    anthropic_messages.append({"role": msg.role, "content": msg.content})
+
+            request_params: dict[str, Any] = {
+                "model": self.model,
+                "messages": anthropic_messages,
+                "temperature": self.temperature,
+                "max_tokens": self.max_tokens,
+                "top_p": self.top_p,
+            }
+
+            if system_message is not None:
+                request_params["system"] = system_message
+
+            if self.top_k is not None:
+                request_params["top_k"] = self.top_k
+
+            if stop_sequences := self._extra_kwargs.get("stop_sequences"):
+                request_params["stop_sequences"] = stop_sequences
+
+            response = await self.client.messages.create(**request_params)
+
+            if response.content and len(response.content) > 0:
+                first_content = response.content[0]
+                if hasattr(first_content, "text"):
+                    return str(first_content.text)
+
+            logger.warning("No text content in Anthropic response")
+            return None
+
+        except Exception as e:
+            logger.error(f"Anthropic API error: {e}", exc_info=True)
+            return None

hexdag/builtin/adapters/database/__init__.py

@@ -0,0 +1,6 @@
+"""Database adapters for HexDAG."""
+
+from hexdag.builtin.adapters.database.pgvector.pgvector_adapter import PgVectorAdapter
+from hexdag.builtin.adapters.database.sqlite.sqlite_adapter import SQLiteAdapter
+
+__all__ = ["PgVectorAdapter", "SQLiteAdapter"]