hexdag 0.5.0.dev1__py3-none-any.whl

hexdag_plugins/storage/file/local.py

@@ -0,0 +1,325 @@
+"""Local filesystem storage adapter."""
+
+import contextlib
+import shutil
+import time
+from pathlib import Path
+from typing import Any
+
+from hexdag.core.configurable import AdapterConfig, ConfigurableAdapter
+from hexdag.core.ports.file_storage import FileStoragePort
+from hexdag.core.ports.healthcheck import HealthStatus
+from hexdag.core.registry.decorators import adapter
+
+
+class LocalFileStorageConfig(AdapterConfig):
+    """Configuration for local file storage.
+
+    Attributes
+    ----------
+    base_path : str
+        Base directory for file storage (default: "./storage")
+    create_if_missing : bool
+        Create base directory if it doesn't exist (default: True)
+    """
+
+    base_path: str = "./storage"
+    create_if_missing: bool = True
+
+
+@adapter("file_storage", name="local", namespace="storage")
+class LocalFileStorage(ConfigurableAdapter, FileStoragePort):
+    """Local filesystem storage adapter.
+
+    Provides file storage on the local filesystem with a base directory.
+
+    Examples
+    --------
+    Basic usage::
+
+        from hexdag.core.registry import registry
+
+        storage = registry.get("local", namespace="storage")(
+            base_path="./data"
+        )
+
+        # Upload file
+        await storage.aupload("document.pdf", "docs/document.pdf")
+
+        # List files
+        files = await storage.alist(prefix="docs/")
+
+        # Download file
+        await storage.adownload("docs/document.pdf", "/tmp/document.pdf")
+
+        # Check if exists
+        exists = await storage.aexists("docs/document.pdf")
+
+        # Delete file
+        await storage.adelete("docs/document.pdf")
+    """
+
+    Config = LocalFileStorageConfig
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize local file storage."""
+        super().__init__(**kwargs)
+        self._base_path = Path(self.config.base_path)
+
+        if self.config.create_if_missing:
+            self._base_path.mkdir(parents=True, exist_ok=True)
+
+    async def aupload(self, local_path: str, remote_path: str) -> dict:
+        """Upload file to storage directory.
+
+        Parameters
+        ----------
+        local_path : str
+            Path to local file
+        remote_path : str
+            Destination path relative to base_path
+
+        Returns
+        -------
+        dict
+            Upload result with metadata
+        """
+        src = Path(local_path)
+        dest = self._base_path / remote_path
+
+        if not src.exists():
+            msg = f"Source file not found: {local_path}"
+            raise FileNotFoundError(msg)
+
+        # Create destination directory
+        dest.parent.mkdir(parents=True, exist_ok=True)
+
+        # Copy file
+        shutil.copy2(src, dest)
+
+        return {
+            "uploaded": True,
+            "local_path": str(src),
+            "remote_path": remote_path,
+            "storage_path": str(dest),
+            "size_bytes": dest.stat().st_size,
+        }
+
+    async def adownload(self, remote_path: str, local_path: str) -> dict:
+        """Download file from storage directory.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path in storage relative to base_path
+        local_path : str
+            Destination local path
+
+        Returns
+        -------
+        dict
+            Download result with metadata
+        """
+        src = self._base_path / remote_path
+        dest = Path(local_path)
+
+        if not src.exists():
+            msg = f"File not found in storage: {remote_path}"
+            raise FileNotFoundError(msg)
+
+        # Create destination directory
+        dest.parent.mkdir(parents=True, exist_ok=True)
+
+        # Copy file
+        shutil.copy2(src, dest)
+
+        return {
+            "downloaded": True,
+            "remote_path": remote_path,
+            "local_path": str(dest),
+            "size_bytes": dest.stat().st_size,
+        }
+
+    async def adelete(self, remote_path: str) -> dict:
+        """Delete file from storage.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path to file relative to base_path
+
+        Returns
+        -------
+        dict
+            Deletion result
+        """
+        file_path = self._base_path / remote_path
+
+        if not file_path.exists():
+            msg = f"File not found: {remote_path}"
+            raise FileNotFoundError(msg)
+
+        # Delete file
+        file_path.unlink()
+
+        # Clean up empty parent directories
+        with contextlib.suppress(FileNotFoundError):
+            parent = file_path.parent
+            if parent.is_dir():
+                parent.rmdir()
+
+        return {
+            "deleted": True,
+            "remote_path": remote_path,
+        }
+
+    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 relative to base_path
+        """
+        if prefix:
+            search_path = self._base_path / prefix
+            pattern = "**/*"
+        else:
+            search_path = self._base_path
+            pattern = "**/*"
+
+        if not search_path.exists():
+            return []
+
+        files = []
+        for path in search_path.glob(pattern):
+            if path.is_file():
+                # Get path relative to base_path
+                rel_path = path.relative_to(self._base_path)
+                files.append(str(rel_path))
+
+        return sorted(files)
+
+    async def aexists(self, remote_path: str) -> bool:
+        """Check if file exists.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path to check relative to base_path
+
+        Returns
+        -------
+        bool
+            True if file exists
+        """
+        file_path = self._base_path / remote_path
+        return file_path.exists() and file_path.is_file()
+
+    async def aget_metadata(self, remote_path: str) -> dict:
+        """Get file metadata.
+
+        Parameters
+        ----------
+        remote_path : str
+            Path to file relative to base_path
+
+        Returns
+        -------
+        dict
+            File metadata (size, modified_time, created_time)
+        """
+        file_path = self._base_path / remote_path
+
+        if not file_path.exists():
+            msg = f"File not found: {remote_path}"
+            raise FileNotFoundError(msg)
+
+        stat = file_path.stat()
+
+        return {
+            "path": remote_path,
+            "size_bytes": stat.st_size,
+            "modified_time": stat.st_mtime,
+            "created_time": stat.st_ctime,
+            "is_file": file_path.is_file(),
+            "absolute_path": str(file_path.absolute()),
+        }
+
+    async def ahealth_check(self) -> HealthStatus:
+        """Check storage health.
+
+        Returns
+        -------
+        HealthStatus
+            Health status of the local storage
+        """
+        start_time = time.time()
+
+        try:
+            # Check if base path exists and is writable
+            if not self._base_path.exists():
+                return HealthStatus(
+                    status="unhealthy",
+                    adapter_name="local_file_storage",
+                    port_name="file_storage",
+                    latency_ms=(time.time() - start_time) * 1000,
+                    details={
+                        "base_path": str(self._base_path),
+                        "error": "Base path does not exist",
+                    },
+                )
+
+            # Test write access
+            test_file = self._base_path / ".health_check"
+            try:
+                test_file.write_text("health_check")
+                test_file.unlink()
+            except Exception as e:
+                return HealthStatus(
+                    status="unhealthy",
+                    adapter_name="local_file_storage",
+                    port_name="file_storage",
+                    error=e,
+                    latency_ms=(time.time() - start_time) * 1000,
+                    details={
+                        "base_path": str(self._base_path),
+                        "error": "Cannot write to base path",
+                    },
+                )
+
+            # Count files
+            file_count = len(await self.alist())
+
+            return HealthStatus(
+                status="healthy",
+                adapter_name="local_file_storage",
+                port_name="file_storage",
+                latency_ms=(time.time() - start_time) * 1000,
+                details={
+                    "base_path": str(self._base_path.absolute()),
+                    "file_count": file_count,
+                    "writable": True,
+                },
+            )
+
+        except Exception as e:
+            return HealthStatus(
+                status="unhealthy",
+                adapter_name="local_file_storage",
+                port_name="file_storage",
+                error=e,
+                latency_ms=(time.time() - start_time) * 1000,
+                details={
+                    "base_path": str(self._base_path),
+                },
+            )
+
+    def __repr__(self) -> str:
+        """String representation."""
+        return f"LocalFileStorage(base_path={self._base_path})"

hexdag_plugins/storage/ports/__init__.py

@@ -0,0 +1,5 @@
+"""Port interfaces for hexdag-storage."""
+
+from .vector_store import VectorStorePort
+
+__all__ = ["VectorStorePort"]

hexdag_plugins/storage/ports/vector_store.py

@@ -0,0 +1,236 @@
+"""Vector store port interface for RAG operations."""
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from hexdag.core.registry.decorators import port
+
+if TYPE_CHECKING:
+    from hexdag.core.ports.healthcheck import HealthStatus
+
+
+@port(name="vector_store", namespace="plugin")
+@runtime_checkable
+class VectorStorePort(Protocol):
+    """Port interface for vector store adapters.
+
+    Vector stores provide semantic search capabilities by storing text embeddings
+    and enabling similarity-based retrieval. This port abstracts different vector
+    database backends (in-memory, PostgreSQL pgvector, ChromaDB, etc.).
+
+    All vector store implementations must provide:
+    - Document storage with embeddings
+    - Similarity search
+    - Document management (count, clear)
+
+    Optional Methods
+    ----------------
+    Adapters may optionally implement:
+    - adelete(ids): Delete documents by ID
+    - aget_stats(): Get storage statistics
+    - asetup(): Initialize database/connections
+    - aclose(): Clean up resources
+    - ahealth_check(): Verify adapter health and connectivity
+    """
+
+    @abstractmethod
+    async def aadd_documents(
+        self,
+        documents: list[dict[str, Any]],
+        embeddings: list[list[float]] | None = None,
+    ) -> None | dict[str, Any]:
+        """Add documents to the vector store.
+
+        Args
+        ----
+            documents: List of documents with required 'text' field and optional 'id', 'metadata'
+            embeddings: Optional pre-computed embeddings (if None, adapter may compute them)
+
+        Returns
+        -------
+            Optional dict with operation results (e.g., {'added': 5, 'ids': [...]})
+
+        Examples
+        --------
+        Basic usage::
+
+            await vector_store.aadd_documents([
+                {"text": "Python programming", "id": "doc1"},
+                {"text": "Machine learning", "id": "doc2"},
+            ])
+
+        With embeddings::
+
+            embeddings = await embedder.aembed_texts(["text1", "text2"])
+            await vector_store.aadd_documents(documents, embeddings=embeddings)
+        """
+        ...
+
+    @abstractmethod
+    async def asearch(
+        self,
+        query: str,
+        query_embedding: list[float] | None = None,
+        top_k: int | None = None,
+        filter_metadata: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Search for similar documents.
+
+        Args
+        ----
+            query: Search query text
+            query_embedding: Optional pre-computed query embedding
+            top_k: Number of results to return (adapter may have default)
+            filter_metadata: Optional metadata filters (e.g., {"category": "docs"})
+
+        Returns
+        -------
+            List of matching documents with 'id', 'text', 'score', and optional 'metadata'
+            Scores should be similarity scores (higher = more similar)
+
+        Examples
+        --------
+        Basic search::
+
+            results = await vector_store.asearch("Python tutorial", top_k=5)
+            for doc in results:
+                print(f"{doc['text']} (score: {doc['score']:.3f})")
+
+        With metadata filter::
+
+            results = await vector_store.asearch(
+                "tutorial",
+                filter_metadata={"category": "programming"}
+            )
+        """
+        ...
+
+    @abstractmethod
+    async def aclear(self) -> None | dict[str, Any]:
+        """Clear all documents from the vector store.
+
+        Returns
+        -------
+            Optional dict with operation results (e.g., {'removed': 100})
+
+        Examples
+        --------
+        ::
+
+            await vector_store.aclear()
+            count = await vector_store.acount()
+            assert count == 0
+        """
+        ...
+
+    @abstractmethod
+    async def acount(self) -> int:
+        """Get the number of documents in the vector store.
+
+        Returns
+        -------
+            Number of documents currently stored
+
+        Examples
+        --------
+        ::
+
+            count = await vector_store.acount()
+            print(f"Store contains {count} documents")
+        """
+        ...
+
+    # Optional methods for enhanced functionality
+
+    async def adelete(self, ids: list[str]) -> None | dict[str, Any]:
+        """Delete documents by ID (optional).
+
+        Args
+        ----
+            ids: List of document IDs to delete
+
+        Returns
+        -------
+            Optional dict with operation results (e.g., {'deleted': 3})
+
+        Examples
+        --------
+        ::
+
+            await vector_store.adelete(["doc1", "doc2"])
+        """
+        ...
+
+    async def aget_stats(self) -> dict[str, Any]:
+        """Get statistics about the vector store (optional).
+
+        Returns
+        -------
+            Dictionary with statistics like document count, storage size, etc.
+
+        Examples
+        --------
+        ::
+
+            stats = await vector_store.aget_stats()
+            print(f"Documents: {stats['document_count']}")
+            print(f"Size: {stats.get('storage_size_mb', 'N/A')} MB")
+        """
+        ...
+
+    async def asetup(self) -> None:
+        """Initialize the vector store (optional).
+
+        This method can be used for one-time setup like:
+        - Creating database tables/indexes
+        - Establishing connections
+        - Loading models
+
+        Examples
+        --------
+        ::
+
+            pgvector = PgVectorAdapter(connection_string="...")
+            await pgvector.asetup()  # Creates tables and indexes
+        """
+        ...
+
+    async def aclose(self) -> None:
+        """Close connections and clean up resources (optional).
+
+        Examples
+        --------
+        ::
+
+            await vector_store.aclose()
+        """
+        ...
+
+    async def ahealth_check(self) -> "HealthStatus":
+        """Check vector store health and connectivity (optional).
+
+        Adapters should verify:
+        - Storage backend connectivity (database, file system, etc.)
+        - Read/write operations
+        - Index health and performance
+        - Storage capacity/availability
+
+        This method is optional. If not implemented, the adapter will be
+        considered healthy by default.
+
+        Returns
+        -------
+        HealthStatus
+            Current health status with details about storage backend
+
+        Examples
+        --------
+        ::
+
+            status = await vector_store.ahealth_check()
+            if status.status == "healthy":
+                print(f"Store is healthy (latency: {status.latency_ms}ms)")
+            else:
+                print(f"Store is {status.status}: {status.error}")
+        """
+        ...

hexdag_plugins/storage/sql/__init__.py

@@ -0,0 +1,7 @@
+"""SQL database adapters."""
+
+from .base import DatabaseConfig, SQLAdapter
+from .mysql import MySQLAdapter
+from .postgresql import PostgreSQLAdapter
+
+__all__ = ["DatabaseConfig", "SQLAdapter", "MySQLAdapter", "PostgreSQLAdapter"]