hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/core/ports/embedding.py

@@ -0,0 +1,215 @@
+"""Port interface definitions for Embedding generation.
+
+.. deprecated:: 0.5.0
+    The standalone ``embedding`` port is deprecated in favor of the unified ``llm`` port
+    with ``SupportsEmbedding`` protocol. Use ``LLM`` port and implement ``SupportsEmbedding``
+    instead. This port will be removed in version 1.0.0.
+
+    Migration guide:
+        Old (deprecated)::
+
+            from hexdag.core.ports.embedding import Embedding
+
+            @adapter("embedding", name="my_embedder")
+            class MyEmbeddingAdapter(Embedding):
+                async def aembed(self, text: str) -> list[float]:
+                    ...
+
+        New (recommended)::
+
+            from hexdag.core.ports.llm import LLM, SupportsEmbedding
+
+            @adapter("llm", name="my_embedder")
+            class MyEmbeddingAdapter(LLM, SupportsEmbedding):
+                async def aresponse(self, messages):
+                    # For pure embedding adapters, can raise NotImplementedError
+                    raise NotImplementedError("This is an embedding-only adapter")
+
+                async def aembed(self, text: str) -> list[float]:
+                    ...
+"""
+
+import warnings
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from hexdag.core.ports.healthcheck import HealthStatus
+
+type ImageInput = str | bytes
+
+# Issue deprecation warning when module is imported
+warnings.warn(
+    "The 'embedding' port is deprecated and will be removed in version 0.5.0. "
+    "Use 'llm' port with 'SupportsEmbedding' protocol instead. "
+    "See hexdag.core.ports.llm.SupportsEmbedding for details.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
+@runtime_checkable
+class Embedding(Protocol):
+    """Port interface for Embedding generation.
+
+    .. deprecated:: 0.5.0
+        Use :class:`hexdag.core.ports.llm.LLM` with
+        :class:`hexdag.core.ports.llm.SupportsEmbedding` protocol instead.
+
+    Embeddings provide vector representations of text and images that capture semantic meaning.
+    Implementations may use various backends (OpenAI, local models, etc.) but must
+    provide the aembed method for generating embeddings from text.
+
+    Required Methods
+    ----------------
+    - aembed(text: str): Generate embedding for text
+    - aembed_image(image: ImageInput): Generate embedding for image
+
+    Optional Methods
+    ----------------
+    Adapters may optionally implement:
+    - ahealth_check(): Verify embedding API connectivity and availability
+    - aembed_batch(): Batch embedding generation for efficiency
+    - aembed_image_batch(): Batch image embedding generation for efficiency
+    """
+
+    @abstractmethod
+    async def aembed(self, text: str) -> list[float]:
+        """Generate embedding vector for a single text input (async).
+
+        Args
+        ----
+            text: Text string to embed
+
+        Returns
+        -------
+            List of floats representing the embedding vector
+
+        Examples
+        --------
+        Single text embedding::
+
+            embedding = await adapter.aembed("Hello, world!")
+            # Returns: [0.123, -0.456, 0.789, ...]
+        """
+        ...
+
+    @abstractmethod
+    async def aembed_image(self, image: ImageInput) -> list[float]:
+        """Generate embedding vector for a single image input (async).
+
+        Args
+        ----
+            image: Image to embed, either as:
+                - str: File path to image or base64-encoded image data
+                - bytes: Raw image bytes
+
+        Returns
+        -------
+            List of floats representing the embedding vector
+
+        Examples
+        --------
+        Image embedding from file path::
+
+            embedding = await adapter.aembed_image("/path/to/image.jpg")
+            # Returns: [0.123, -0.456, 0.789, ...]
+
+        Image embedding from bytes::
+
+            with open("image.jpg", "rb") as f:
+                image_bytes = f.read()
+            embedding = await adapter.aembed_image(image_bytes)
+            # Returns: [0.123, -0.456, 0.789, ...]
+
+        Image embedding from base64::
+
+            base64_image = "data:image/jpeg;base64,/9j/4AAQ..."
+            embedding = await adapter.aembed_image(base64_image)
+            # Returns: [0.123, -0.456, 0.789, ...]
+        """
+        ...
+
+    async def aembed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts efficiently (optional).
+
+        This method enables batch processing for improved performance when
+        embedding multiple texts. If not implemented, the framework will
+        fall back to sequential calls to aembed().
+
+        Args
+        ----
+            texts: List of text strings to embed
+
+        Returns
+        -------
+            List of embedding vectors, one per input text
+
+        Examples
+        --------
+        Batch embedding::
+
+            texts = ["Hello", "World", "AI"]
+            embeddings = await adapter.aembed_batch(texts)
+            # Returns: [[0.1, 0.2, ...], [0.3, 0.4, ...], [0.5, 0.6, ...]]
+        """
+        ...
+
+    async def aembed_image_batch(self, images: list[ImageInput]) -> list[list[float]]:
+        """Generate embeddings for multiple images efficiently (optional).
+
+        This method enables batch processing for improved performance when
+        embedding multiple images. If not implemented, the framework will
+        fall back to sequential calls to aembed_image().
+
+        Args
+        ----
+            images: List of images to embed, each can be:
+                - str: File path to image or base64-encoded image data
+                - bytes: Raw image bytes
+
+        Returns
+        -------
+            List of embedding vectors, one per input image
+
+        Examples
+        --------
+        Batch image embedding::
+
+            images = [
+                "/path/to/image1.jpg",
+                "/path/to/image2.png",
+                image_bytes
+            ]
+            embeddings = await adapter.aembed_image_batch(images)
+            # Returns: [[0.1, 0.2, ...], [0.3, 0.4, ...], [0.5, 0.6, ...]]
+        """
+        ...
+
+    async def ahealth_check(self) -> "HealthStatus":
+        """Check embedding adapter health and connectivity (optional).
+
+        Adapters should verify:
+        - API connectivity to the embedding service
+        - Model availability
+        - Authentication status
+        - Rate limit status (if applicable)
+
+        This method is optional. If not implemented, the adapter will be
+        considered healthy by default.
+
+        Returns
+        -------
+        HealthStatus
+            Current health status with details about connectivity and availability
+
+        Examples
+        --------
+        OpenAI adapter health check::
+
+            status = await openai_adapter.ahealth_check()
+            status.status  # "healthy", "degraded", or "unhealthy"
+            status.latency_ms  # Time taken for health check
+            status.details  # {"model": "text-embedding-3-small"}
+        """
+        ...

hexdag/core/ports/executor.py

@@ -0,0 +1,237 @@
+"""Port interface for DAG execution strategies.
+
+This port enables pluggable execution backends for the orchestrator,
+allowing the same DAG to run locally (in-process), with Celery
+(distributed task queue), or Azure Functions (serverless).
+"""
+
+from abc import abstractmethod
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from hexdag.core.orchestration.hook_context import PipelineStatus
+
+
+class ExecutionTask(BaseModel):
+    """A serializable task definition for node execution.
+
+    This model encapsulates all information needed to execute a node,
+    allowing it to be passed across process boundaries for distributed execution.
+
+    Attributes
+    ----------
+    node_name : str
+        Unique identifier for the node within the DAG
+    node_input : Any
+        Input data for the node (None = executor should prepare from context)
+    wave_index : int
+        Wave number in the DAG execution sequence
+    should_validate : bool
+        Whether to perform input/output validation
+    context_data : dict[str, Any]
+        Execution context metadata (dag_id, run_id, attempt, etc.)
+    params : dict[str, Any]
+        Additional parameters passed to the node function
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True, populate_by_name=True)
+
+    node_name: str
+    node_input: Any | None = None
+    wave_index: int = 0
+    should_validate: bool = Field(default=True, validation_alias="validate")
+    context_data: dict[str, Any] = Field(default_factory=dict)
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+class ExecutionResult(BaseModel):
+    """Result of a node execution.
+
+    Attributes
+    ----------
+    node_name : str
+        Name of the executed node
+    output : Any
+        Result data from the node execution
+    duration_ms : float
+        Execution time in milliseconds
+    status : PipelineStatus
+        Execution status (SUCCESS, FAILED, CANCELLED)
+    error : str | None
+        Error message if execution failed, None otherwise
+    error_type : str | None
+        Type of error that occurred, if any
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    node_name: str
+    output: Any = None
+    duration_ms: float = 0.0
+    status: PipelineStatus = PipelineStatus.SUCCESS
+    error: str | None = None
+    error_type: str | None = None
+
+
+@runtime_checkable
+class ExecutorPort(Protocol):
+    """Port interface for DAG node execution strategies.
+
+    This port abstracts the execution backend, allowing the orchestrator
+    to delegate node execution to different implementations:
+
+    - **LocalExecutor**: In-process async execution (default)
+    - **CeleryExecutor**: Distributed execution via Celery task queue
+    - **AzureFunctionsExecutor**: Serverless execution via Azure Functions
+
+    The port provides a consistent interface regardless of where/how
+    nodes are actually executed.
+
+    Lifecycle
+    ---------
+    Executors may implement optional setup/cleanup methods:
+    - asetup(): Initialize resources (connections, workers, etc.)
+    - aclose(): Cleanup resources (called automatically by orchestrator)
+
+    Optional Methods
+    ----------------
+    Adapters may optionally implement:
+    - asetup(): Initialize executor resources before first use
+    - aclose(): Cleanup executor resources after execution completes
+    """
+
+    @abstractmethod
+    async def aexecute_node(self, task: ExecutionTask) -> ExecutionResult:
+        """Execute a single node and return the result.
+
+        The executor is responsible for:
+        1. Resolving the node function (by name or from task data)
+        2. Executing the function with the provided input
+        3. Handling timeouts and errors
+        4. Wrapping the result in ExecutionResult
+
+        Parameters
+        ----------
+        task : ExecutionTask
+            Task definition containing all execution parameters
+
+        Returns
+        -------
+        ExecutionResult
+            Execution result with output or error information
+
+        Examples
+        --------
+        Local execution::
+
+            task = ExecutionTask(
+                node_name="fetch_data",
+                node_input={"url": "https://api.example.com"},
+                wave_index=0,
+                validate=True
+            )
+            result = await executor.aexecute_node(task)
+            if result.status == PipelineStatus.SUCCESS:
+                print(result.output)
+
+        Distributed execution (same interface)::
+
+            # Task is serialized and sent to remote worker
+            result = await celery_executor.aexecute_node(task)
+        """
+        ...
+
+    @abstractmethod
+    async def aexecute_wave(self, tasks: list[ExecutionTask]) -> dict[str, ExecutionResult]:
+        """Execute multiple nodes concurrently within a wave.
+
+        The executor should run all tasks in parallel (respecting concurrency
+        limits) and return results as a dictionary.
+
+        Parameters
+        ----------
+        tasks : list[ExecutionTask]
+            List of tasks to execute in parallel
+
+        Returns
+        -------
+        dict[str, ExecutionResult]
+            Map of node_name -> execution result
+
+        Raises
+        ------
+        Exception
+            If any task fails, the exception should be captured in
+            ExecutionResult.error rather than raised directly
+
+        Examples
+        --------
+        Execute wave of independent nodes::
+
+            tasks = [
+                ExecutionTask(node_name="fetch_a", ...),
+                ExecutionTask(node_name="fetch_b", ...),
+                ExecutionTask(node_name="fetch_c", ...),
+            ]
+            results = await executor.aexecute_wave(tasks)
+            # All three nodes executed concurrently
+            assert "fetch_a" in results
+            assert "fetch_b" in results
+            assert "fetch_c" in results
+        """
+        ...
+
+    async def asetup(self) -> None:
+        """Initialize executor resources before first use (optional).
+
+        Implementations should use this to:
+        - Establish connections to brokers/queues
+        - Initialize worker pools
+        - Verify remote endpoints are accessible
+        - Load configuration
+
+        This method is called automatically by the orchestrator during
+        the managed_ports lifecycle.
+
+        Examples
+        --------
+        Celery executor setup::
+
+            async def asetup(self):
+                self.celery_app = Celery('hexdag', broker=self.broker_url)
+                await self._verify_broker_connection()
+
+        Azure Functions executor setup::
+
+            async def asetup(self):
+                self.http_client = aiohttp.ClientSession()
+                await self._verify_function_endpoint()
+        """
+        ...
+
+    async def aclose(self) -> None:
+        """Cleanup executor resources after execution completes (optional).
+
+        Implementations should use this to:
+        - Close connections to brokers/queues
+        - Shutdown worker pools
+        - Close HTTP clients
+        - Flush any pending tasks
+
+        This method is called automatically by the orchestrator during
+        cleanup phase.
+
+        Examples
+        --------
+        Celery executor cleanup::
+
+            async def aclose(self):
+                await self.celery_app.close()
+
+        Azure Functions executor cleanup::
+
+            async def aclose(self):
+                await self.http_client.close()
+        """
+        ...

hexdag/core/ports/file_storage.py

@@ -0,0 +1,117 @@
+"""File storage port definition."""
+
+from typing import Protocol, runtime_checkable
+
+from hexdag.core.ports.healthcheck import HealthStatus
+
+
+@runtime_checkable
+class FileStoragePort(Protocol):
+    """Port for file storage operations.
+
+    Provides a unified interface for local and cloud file storage.
+    """
+
+    async def aupload(self, local_path: str, remote_path: str) -> dict:
+        """Upload a file.
+
+        Parameters
+        ----------
+        local_path : str
+            Path to local file
+        remote_path : str
+            Destination path in storage
+
+        Returns
+        -------
+        dict
+            Upload result with metadata
+        """
+        ...
+
+    async def adownload(self, remote_path: str, local_path: str) -> dict:
+        """Download a file.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path in storage
+        local_path : str
+            Destination local path
+
+        Returns
+        -------
+        dict
+            Download result with metadata
+        """
+        ...
+
+    async def adelete(self, remote_path: str) -> dict:
+        """Delete a file.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path to file in storage
+
+        Returns
+        -------
+        dict
+            Deletion result
+        """
+        ...
+
+    async def alist(self, prefix: str = "") -> list[str]:
+        """List files with optional prefix.
+
+        Parameters
+        ----------
+        prefix : str
+            Optional path prefix for filtering
+
+        Returns
+        -------
+        list[str]
+            List of file paths
+        """
+        ...
+
+    async def aexists(self, remote_path: str) -> bool:
+        """Check if file exists.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path to check
+
+        Returns
+        -------
+        bool
+            True if file exists
+        """
+        ...
+
+    async def aget_metadata(self, remote_path: str) -> dict:
+        """Get file metadata.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path to file
+
+        Returns
+        -------
+        dict
+            File metadata (size, modified_time, etc.)
+        """
+        ...
+
+    async def ahealth_check(self) -> HealthStatus:
+        """Check storage health.
+
+        Returns
+        -------
+        HealthStatus
+            Health status of the storage system
+        """
+        ...

hexdag/core/ports/healthcheck.py

@@ -0,0 +1,87 @@
+"""Health check models and types for adapter monitoring.
+
+This module provides shared types for adapter health checking.
+Each port can optionally implement an ahealth_check() method that returns HealthStatus.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+__all__ = ["HealthStatus"]
+
+
+@dataclass(slots=True)
+class HealthStatus:
+    """Health check result returned by adapters.
+
+    Adapters can implement an optional async ahealth_check() method
+    that returns this status object to indicate their operational state.
+
+    Attributes
+    ----------
+    status : Literal["healthy", "degraded", "unhealthy"]
+        Current health status:
+        - "healthy": Adapter is fully operational
+        - "degraded": Adapter is operational but with reduced performance
+        - "unhealthy": Adapter is not operational
+    adapter_name : str
+        Name of the adapter being checked
+    port_name : str | None
+        Name of the port this adapter implements (e.g., "llm", "database")
+    details : dict[str, Any]
+        Additional context about the health check (e.g., error messages, metrics)
+    latency_ms : float | None
+        Time taken to perform the health check in milliseconds
+    error : Exception | None
+        Exception if the health check failed
+
+    Examples
+    --------
+    Example usage::
+
+        # Healthy adapter
+        HealthStatus(
+        status="healthy",
+        adapter_name="openai",
+        port_name="llm",
+        latency_ms=45.2
+        )
+
+        # Unhealthy adapter with error
+        HealthStatus(
+        status="unhealthy",
+        adapter_name="postgres",
+        port_name="database",
+        error=ConnectionError("Could not connect to database"),
+        details={"host": "localhost", "port": 5432}
+        )
+    """
+
+    status: Literal["healthy", "degraded", "unhealthy"]
+    adapter_name: str
+    port_name: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+    latency_ms: float | None = None
+    error: Exception | None = None
+
+    def is_healthy(self) -> bool:
+        """Check if status is healthy.
+
+        Returns
+        -------
+        bool
+            True if status is "healthy", False otherwise
+        """
+        return self.status == "healthy"
+
+    def is_operational(self) -> bool:
+        """Check if adapter is operational (healthy or degraded).
+
+        Returns
+        -------
+        bool
+            True if status is "healthy" or "degraded", False if "unhealthy"
+        """
+        return self.status in ("healthy", "degraded")