hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/builtin/adapters/mock/README.md

@@ -0,0 +1,89 @@
+# Mock Adapters
+
+Mock adapter implementations for testing and development without external dependencies.
+
+## Loading Mock Adapters
+
+Mock adapters are **not loaded by default**. To use them, you have two options:
+
+### Option 1: Load via Configuration File
+
+```python
+from hexdag.core.bootstrap import bootstrap_registry
+
+# Load mock adapters explicitly
+bootstrap_registry("hexdag/adapters/mock/hexdag.toml")
+```
+
+### Option 2: Direct Import
+
+```python
+from hexdag.adapters.mock.mock_llm import MockLLM
+from hexdag.adapters.mock.mock_database import MockDatabaseAdapter
+from hexdag.adapters.mock.mock_tool_router import MockToolRouter
+
+# Create instances directly
+llm = MockLLM()
+db = MockDatabaseAdapter()
+router = MockToolRouter()
+```
+
+## Available Mock Adapters
+
+### MockLLM
+Simulates LLM responses without API calls.
+
+```python
+from hexdag.core.ports.llm import Message
+
+llm = registry.get("mock_llm", namespace="plugin")
+messages = [Message(role="user", content="Hello!")]
+response = await llm.aresponse(messages)
+```
+
+### MockDatabaseAdapter
+Provides sample e-commerce data for testing database operations.
+
+```python
+db = registry.get("mock_database", namespace="plugin")
+schemas = await db.aget_table_schemas()
+results = await db.aexecute_query("SELECT * FROM customers LIMIT 5")
+```
+
+### MockToolRouter
+Simulates tool execution with predefined responses.
+
+```python
+router = registry.get("mock_tool_router", namespace="plugin")
+tools = router.get_available_tools()
+result = await router.acall_tool("calculate", {"expression": "2 + 2"})
+```
+
+## Configuration
+
+Mock adapters can be configured via the `hexdag.toml` file:
+
+```toml
+[settings.mock_llm]
+responses = ["Custom response 1", "Custom response 2"]
+delay_seconds = 0.1
+
+[settings.mock_database]
+enable_sample_data = true
+delay_seconds = 0.0
+
+[settings.mock_tool_router]
+available_tools = ["search", "calculate", "get_weather"]
+raise_on_unknown_tool = true
+```
+
+## Use Cases
+
+- **Unit Testing**: Test workflows without external dependencies
+- **Development**: Rapid prototyping without API keys or database setup
+- **CI/CD**: Reliable, deterministic tests in pipelines
+- **Demos**: Showcase functionality without infrastructure
+
+## Example
+
+See `examples/22_mock_adapters_demo.py` for a complete demonstration of using mock adapters in workflows.

hexdag/builtin/adapters/mock/__init__.py

@@ -0,0 +1,15 @@
+"""Enhanced mock implementations for testing purposes."""
+
+from .mock_database import MockDatabaseAdapter
+from .mock_embedding import MockEmbedding
+from .mock_llm import MockLLM
+from .mock_tool_adapter import MockToolAdapter
+from .mock_tool_router import MockToolRouter
+
+__all__ = [
+    "MockLLM",
+    "MockEmbedding",
+    "MockDatabaseAdapter",
+    "MockToolRouter",
+    "MockToolAdapter",
+]

hexdag/builtin/adapters/mock/hexdag.toml

@@ -0,0 +1,50 @@
+# HexDAG Configuration
+# This configuration loads the mock adapters as our first plugin
+
+# Core modules to load - these are the essential framework components
+modules = [
+    "hexdag.core.ports",               # Core port definitions (must load before adapters)
+    "hexdag.builtin.nodes",            # Core node factories
+    "hexdag.builtin.adapters.mock",    # Mock implementations of all ports
+    "hexdag.builtin.adapters.memory",  # Memory adapter implementations
+]
+
+# Development mode - allows post-bootstrap registration for testing
+dev_mode = true
+
+[settings]
+# Logging configuration
+log_level = "INFO"
+enable_metrics = true
+
+# Mock adapter default configurations
+[settings.mock_llm]
+# Default responses for the mock LLM
+responses = [
+    "I understand your request.",
+    "Let me help you with that.",
+    "Here's what I found.",
+]
+delay_seconds = 0.0
+
+[settings.mock_database]
+# Enable sample e-commerce data by default
+enable_sample_data = true
+delay_seconds = 0.0
+
+[settings.mock_memory]
+# In-memory storage settings
+delay_seconds = 0.0
+max_size = 1000  # Maximum number of items to store
+
+[settings.mock_tool_router]
+# Available mock tools
+available_tools = [
+    "search",
+    "calculate",
+    "get_weather",
+    "get_time",
+    "translate",
+]
+delay_seconds = 0.0
+raise_on_unknown_tool = true

hexdag/builtin/adapters/mock/mock_database.py

@@ -0,0 +1,225 @@
+"""Mock database port implementation for testing."""
+
+import asyncio
+from typing import Any
+
+from hexdag.core.ports.database import DatabasePort
+
+
+class MockDatabaseAdapter(DatabasePort):
+    """Mock implementation of DatabasePort for testing and demos."""
+
+    # Type annotations for attributes
+    enable_sample_data: bool
+    delay_seconds: float
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize with configuration.
+
+        Args
+        ----
+            **kwargs: Configuration options (enable_sample_data, delay_seconds)
+        """
+        self.enable_sample_data = kwargs.get("enable_sample_data", True)
+        self.delay_seconds = kwargs.get("delay_seconds", 0.0)
+
+        if not self.enable_sample_data:
+            self._table_schemas: dict[str, dict[str, Any]] = {}
+            self._relationships: list[dict[str, Any]] = []
+            self._indexes: list[dict[str, Any]] = []
+            self._table_statistics: dict[str, dict[str, Any]] = {}
+            return
+
+        self._table_schemas = {
+            "customers": {
+                "table_name": "customers",
+                "columns": {
+                    "id": "INTEGER PRIMARY KEY",
+                    "customer_name": "VARCHAR(255)",
+                    "email": "VARCHAR(255)",
+                    "segment": "VARCHAR(50)",
+                    "created_date": "TIMESTAMP",
+                    "status": "VARCHAR(20)",
+                },
+                "primary_keys": ["id"],
+                "foreign_keys": [],
+            },
+            "orders": {
+                "table_name": "orders",
+                "columns": {
+                    "id": "INTEGER PRIMARY KEY",
+                    "customer_id": "INTEGER",
+                    "order_date": "DATE",
+                    "order_value": "DECIMAL(10,2)",
+                    "status": "VARCHAR(20)",
+                    "created_at": "TIMESTAMP",
+                },
+                "primary_keys": ["id"],
+                "foreign_keys": [
+                    {
+                        "column": "customer_id",
+                        "references_table": "customers",
+                        "references_column": "id",
+                    }
+                ],
+            },
+            "products": {
+                "table_name": "products",
+                "columns": {
+                    "id": "INTEGER PRIMARY KEY",
+                    "product_name": "VARCHAR(255)",
+                    "category": "VARCHAR(100)",
+                    "price": "DECIMAL(8,2)",
+                    "created_at": "TIMESTAMP",
+                },
+                "primary_keys": ["id"],
+                "foreign_keys": [],
+            },
+            "order_items": {
+                "table_name": "order_items",
+                "columns": {
+                    "id": "INTEGER PRIMARY KEY",
+                    "order_id": "INTEGER",
+                    "product_id": "INTEGER",
+                    "quantity": "INTEGER",
+                    "unit_price": "DECIMAL(8,2)",
+                },
+                "primary_keys": ["id"],
+                "foreign_keys": [
+                    {
+                        "column": "order_id",
+                        "references_table": "orders",
+                        "references_column": "id",
+                    },
+                    {
+                        "column": "product_id",
+                        "references_table": "products",
+                        "references_column": "id",
+                    },
+                ],
+            },
+        }
+
+        self._relationships = [
+            {
+                "from_table": "orders",
+                "from_column": "customer_id",
+                "to_table": "customers",
+                "to_column": "id",
+                "relationship_type": "many_to_one",
+            },
+            {
+                "from_table": "order_items",
+                "from_column": "order_id",
+                "to_table": "orders",
+                "to_column": "id",
+                "relationship_type": "many_to_one",
+            },
+            {
+                "from_table": "order_items",
+                "from_column": "product_id",
+                "to_table": "products",
+                "to_column": "id",
+                "relationship_type": "many_to_one",
+            },
+        ]
+
+        self._indexes = [
+            {
+                "index_name": "idx_customers_email",
+                "table_name": "customers",
+                "columns": ["email"],
+                "index_type": "btree",
+                "is_unique": True,
+            },
+            {
+                "index_name": "idx_orders_customer_id",
+                "table_name": "orders",
+                "columns": ["customer_id"],
+                "index_type": "btree",
+                "is_unique": False,
+            },
+            {
+                "index_name": "idx_orders_date",
+                "table_name": "orders",
+                "columns": ["order_date"],
+                "index_type": "btree",
+                "is_unique": False,
+            },
+            {
+                "index_name": "idx_order_items_order_id",
+                "table_name": "order_items",
+                "columns": ["order_id"],
+                "index_type": "btree",
+                "is_unique": False,
+            },
+        ]
+
+        self._table_statistics = {
+            "customers": {
+                "row_count": 10000,
+                "size_bytes": 2048000,
+                "last_updated": "2024-01-15T10:30:00Z",
+            },
+            "orders": {
+                "row_count": 50000,
+                "size_bytes": 8192000,
+                "last_updated": "2024-01-15T11:45:00Z",
+            },
+            "products": {
+                "row_count": 1000,
+                "size_bytes": 512000,
+                "last_updated": "2024-01-10T09:00:00Z",
+            },
+            "order_items": {
+                "row_count": 150000,
+                "size_bytes": 12288000,
+                "last_updated": "2024-01-15T11:45:00Z",
+            },
+        }
+
+    # Required methods from DatabasePort
+    async def aget_table_schemas(self) -> dict[str, dict[str, Any]]:
+        """Get schema information for all tables."""
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+        return self._table_schemas.copy()
+
+    async def aexecute_query(
+        self, query: str, params: dict[str, Any] | None = None
+    ) -> list[dict[str, Any]]:
+        """Execute a SQL query and return results."""
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+
+        # Mock implementation - returns sample data based on query keywords
+        if "customers" in query.lower():
+            return [
+                {"id": 1, "customer_name": "John Doe", "segment": "Premium"},
+                {"id": 2, "customer_name": "Jane Smith", "segment": "Standard"},
+            ]
+        if "orders" in query.lower():
+            return [
+                {"id": 101, "customer_id": 1, "order_value": 299.99},
+                {"id": 102, "customer_id": 2, "order_value": 149.50},
+            ]
+        return []
+
+    # Optional methods from DatabasePort
+    async def aget_relationships(self) -> list[dict[str, Any]]:
+        """Get foreign key relationships between tables."""
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+        return self._relationships.copy()
+
+    async def aget_indexes(self) -> list[dict[str, Any]]:
+        """Get index information for performance optimization."""
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+        return self._indexes.copy()
+
+    async def aget_table_statistics(self) -> dict[str, dict[str, Any]]:
+        """Get table statistics for query optimization."""
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+        return self._table_statistics.copy()

hexdag/builtin/adapters/mock/mock_embedding.py

@@ -0,0 +1,223 @@
+"""Mock Embedding implementation for testing purposes."""
+
+import asyncio
+import hashlib
+from typing import TYPE_CHECKING, Any
+
+from hexdag.core.ports.embedding import ImageInput
+
+if TYPE_CHECKING:
+    from hexdag.core.ports.healthcheck import HealthStatus
+
+
+class MockEmbedding:
+    """Mock implementation of the Embedding interface for testing.
+
+    This mock generates deterministic embeddings based on the input text's hash,
+    making tests predictable and reproducible. It also provides utilities for
+    testing like call inspection and configurable delays.
+    """
+
+    # Type annotations for attributes
+    delay_seconds: float
+    dimensions: int
+    call_count: int
+    last_texts: list[str]
+    last_images: list[ImageInput]
+    should_raise: bool
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialize with configuration.
+
+        Args
+        ----
+            **kwargs: Configuration options
+                - dimensions: Embedding vector dimensions (default: 1536)
+                - delay_seconds: Delay before returning embeddings (default: 0.0)
+        """
+        self.delay_seconds = kwargs.get("delay_seconds", 0.0)
+        self.dimensions = kwargs.get("dimensions", 1536)
+
+        # Non-config state
+        self.call_count = 0
+        self.last_texts: list[str] = []
+        self.last_images: list[ImageInput] = []
+        self.should_raise = False
+
+    def _generate_embedding(self, text: str) -> list[float]:
+        """Generate a deterministic embedding vector from text.
+
+        Uses text hash to generate consistent embeddings for the same input.
+        """
+        # Use hash to generate deterministic values (not for security)
+        text_hash = hashlib.md5(text.encode(), usedforsecurity=False).hexdigest()  # noqa: S324
+
+        # Generate embedding values from hash
+        embedding = []
+        for i in range(self.dimensions):
+            # Use chunks of the hash to generate values
+            chunk_idx = (i * 4) % len(text_hash)
+            chunk = text_hash[chunk_idx : chunk_idx + 4]
+            # Convert to float in range [-1, 1]
+            value = (int(chunk, 16) / 65535.0) * 2 - 1
+            embedding.append(value)
+
+        return embedding
+
+    def _generate_image_embedding(self, image: ImageInput) -> list[float]:
+        """Generate a deterministic embedding vector from image.
+
+        Uses image data hash to generate consistent embeddings for the same input.
+        """
+        # Convert image to bytes for hashing
+        image_bytes = image.encode() if isinstance(image, str) else image
+
+        # Use hash to generate deterministic values (not for security)
+        image_hash = hashlib.md5(image_bytes, usedforsecurity=False).hexdigest()  # noqa: S324
+
+        # Generate embedding values from hash
+        embedding = []
+        for i in range(self.dimensions):
+            # Use chunks of the hash to generate values
+            chunk_idx = (i * 4) % len(image_hash)
+            chunk = image_hash[chunk_idx : chunk_idx + 4]
+            # Convert to float in range [-1, 1]
+            value = (int(chunk, 16) / 65535.0) * 2 - 1
+            embedding.append(value)
+
+        return embedding
+
+    async def aembed(self, text: str) -> list[float]:
+        """Generate embedding vector for a single text input.
+
+        Parameters
+        ----------
+        text : str
+            Text string to embed
+
+        Returns
+        -------
+        list[float]
+            Mock embedding vector
+
+        Raises
+        ------
+        Exception
+            When should_raise is True for testing error conditions
+        """
+        self.last_texts = [text]
+
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+
+        if self.should_raise:
+            raise Exception("Mock Embedding error for testing")
+
+        self.call_count += 1
+        return self._generate_embedding(text)
+
+    async def aembed_batch(self, texts: list[str]) -> list[list[float]]:
+        """Generate embeddings for multiple texts.
+
+        Parameters
+        ----------
+        texts : list[str]
+            List of text strings to embed
+
+        Returns
+        -------
+        list[list[float]]
+            List of mock embedding vectors
+
+        Raises
+        ------
+        Exception
+            When should_raise is True for testing error conditions
+        """
+        self.last_texts = texts
+
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+
+        if self.should_raise:
+            raise Exception("Mock Embedding batch error for testing")
+
+        self.call_count += len(texts)
+        return [self._generate_embedding(text) for text in texts]
+
+    async def aembed_image(self, image: ImageInput) -> list[float]:
+        """Generate embedding vector for a single image input.
+
+        Parameters
+        ----------
+        image : ImageInput
+            Image to embed (file path, base64 string, or bytes)
+
+        Returns
+        -------
+        list[float]
+            Mock embedding vector
+
+        Raises
+        ------
+        Exception
+            When should_raise is True for testing error conditions
+        """
+        self.last_images = [image]
+
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+
+        if self.should_raise:
+            raise Exception("Mock Image Embedding error for testing")
+
+        self.call_count += 1
+        return self._generate_image_embedding(image)
+
+    async def aembed_image_batch(self, images: list[ImageInput]) -> list[list[float]]:
+        """Generate embeddings for multiple images.
+
+        Parameters
+        ----------
+        images : list[ImageInput]
+            List of images to embed (file paths, base64 strings, or bytes)
+
+        Returns
+        -------
+        list[list[float]]
+            List of mock embedding vectors
+
+        Raises
+        ------
+        Exception
+            When should_raise is True for testing error conditions
+        """
+        self.last_images = images
+
+        if self.delay_seconds > 0:
+            await asyncio.sleep(self.delay_seconds)
+
+        if self.should_raise:
+            raise Exception("Mock Image Embedding batch error for testing")
+
+        self.call_count += len(images)
+        return [self._generate_image_embedding(image) for image in images]
+
+    async def ahealth_check(self) -> "HealthStatus":
+        """Health check for Mock Embedding (always healthy)."""
+        from hexdag.core.ports.healthcheck import HealthStatus
+
+        return HealthStatus(
+            status="healthy",
+            adapter_name="MockEmbedding",
+            latency_ms=0.1,
+            details={"dimensions": self.dimensions},
+        )
+
+    # Testing utilities (not part of the Embedding port interface)
+    def reset(self) -> None:
+        """Reset the mock state for testing."""
+        self.call_count = 0
+        self.last_texts = []
+        self.last_images = []
+        self.should_raise = False