hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/core/protocols.py

@@ -0,0 +1,273 @@
+"""Protocols for structural typing in hexDAG.
+
+This module defines protocols (structural types) to reduce isinstance() usage
+and enable duck typing with static type checking support.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+# ============================================================================
+# Component Protocols
+# ============================================================================
+
+
+@runtime_checkable
+class ComponentWithExecute(Protocol):
+    """Protocol for components that have an execute method.
+
+    This allows duck typing for tool classes without isinstance checks.
+
+    Examples
+    --------
+    Example usage::
+
+        class MyTool:
+        def execute(self, **kwargs: Any) -> Any:
+        return "result"
+
+        def use_tool(tool: ComponentWithExecute) -> Any:
+        return tool.execute(param=1)
+    """
+
+    def execute(self, **kwargs: Any) -> Any:
+        """Execute the component with given parameters."""
+        ...
+
+
+# ============================================================================
+# Port Protocols
+# ============================================================================
+
+
+@runtime_checkable
+class ConfigurablePort(Protocol):
+    """Protocol for ports that support configuration.
+
+    Examples
+    --------
+    Example usage::
+
+        class MyAdapter:
+        @classmethod
+        def get_config_class(cls) -> type:
+        return MyConfig
+    """
+
+    @classmethod
+    def get_config_class(cls) -> type[Any]:
+        """Return the configuration class for this port."""
+        ...
+
+
+@runtime_checkable
+class HealthCheckable(Protocol):
+    """Protocol for components that support health checks.
+
+    Examples
+    --------
+    Example usage::
+
+        class MyAdapter:
+        async def ahealth_check(self) -> dict[str, Any]:
+        return {"status": "healthy"}
+    """
+
+    async def ahealth_check(self) -> dict[str, Any]:
+        """Perform async health check.
+
+        Returns
+        -------
+            Health status dictionary with at least 'status' key
+        """
+        ...
+
+
+# ============================================================================
+# Data Conversion Protocols
+# ============================================================================
+
+
+@runtime_checkable
+class DictConvertible(Protocol):
+    """Protocol for objects that can be converted to dict.
+
+    This includes Pydantic models and other dict-like objects.
+
+    Examples
+    --------
+    Example usage::
+
+        class MyModel:
+        def model_dump(self) -> dict[str, Any]:
+        return {"field": "value"}
+    """
+
+    def model_dump(self) -> dict[str, Any]:
+        """Convert to dictionary representation."""
+        ...
+
+
+@runtime_checkable
+class SchemaProvider(Protocol):
+    """Protocol for classes that provide schema information.
+
+    Examples
+    --------
+    Example usage::
+
+        class MyModel:
+        @classmethod
+        def model_json_schema(cls) -> dict[str, Any]:
+        return {"type": "object", "properties": {}}
+    """
+
+    @classmethod
+    def model_json_schema(cls) -> dict[str, Any]:
+        """Return JSON schema for this model."""
+        ...
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def has_execute_method(obj: Any) -> bool:
+    """Check if object has an execute method (duck typing).
+
+    This is more Pythonic than isinstance checks.
+
+    Args
+    ----
+        obj: Object to check
+
+    Returns
+    -------
+        True if object has callable execute method
+
+    Examples
+    --------
+    Example usage::
+
+        class Tool:
+        def execute(self): pass
+        has_execute_method(Tool())
+    True
+    """
+    return isinstance(obj, ComponentWithExecute)
+
+
+def is_dict_convertible(obj: Any) -> bool:
+    """Check if object can be converted to dict.
+
+    Args
+    ----
+        obj: Object to check
+
+    Returns
+    -------
+        True if object has model_dump method or is a dict
+
+    Examples
+    --------
+    Example usage::
+
+        from pydantic import BaseModel
+        class MyModel(BaseModel):
+        field: str
+        is_dict_convertible(MyModel(field="value"))
+    True
+        is_dict_convertible({"key": "value"})
+    True
+    """
+    return isinstance(obj, (dict, DictConvertible))
+
+
+def is_schema_type(type_obj: Any) -> bool:
+    """Check if type is a Pydantic model class (not instance).
+
+    Args
+    ----
+        type_obj: Type to check
+
+    Returns
+    -------
+        True if type is a Pydantic BaseModel subclass
+
+    Examples
+    --------
+    Example usage::
+
+        from pydantic import BaseModel
+        class MyModel(BaseModel):
+        field: str
+        is_schema_type(MyModel)  # Type check
+    True
+        is_schema_type(MyModel(field="val"))  # Instance check
+    False
+    """
+    try:
+        return isinstance(type_obj, type) and issubclass(type_obj, SchemaProvider)
+    except TypeError:
+        return False
+
+
+def to_dict(obj: Any) -> dict[str, Any]:
+    """Convert object to dictionary, handling multiple input types.
+
+    This centralizes the type conversion logic used throughout the codebase.
+
+    Args
+    ----
+        obj: Object to convert (dict, Pydantic model, or other)
+
+    Returns
+    -------
+        Dictionary representation of the object
+
+    Raises
+    ------
+        TypeError
+            If object cannot be converted to dict
+
+    Examples
+    --------
+    Example usage::
+
+        to_dict({"key": "value"})
+    {'key': 'value'}
+        from pydantic import BaseModel
+        class MyModel(BaseModel):
+        field: str
+        to_dict(MyModel(field="value"))
+    {'field': 'value'}
+        to_dict("not_convertible")  # Raises TypeError
+    """
+    # Case 1: Already a dict
+    if isinstance(obj, dict):
+        return obj
+
+    # Case 2: Pydantic model or dict-convertible
+    if isinstance(obj, DictConvertible):
+        return obj.model_dump()
+
+    # Case 3: Cannot convert
+    raise TypeError(
+        f"Cannot convert {type(obj).__name__} to dict. "
+        f"Expected dict or object with model_dump() method"
+    )
+
+
+__all__ = [
+    "ComponentWithExecute",
+    "ConfigurablePort",
+    "HealthCheckable",
+    "DictConvertible",
+    "SchemaProvider",
+    "has_execute_method",
+    "is_dict_convertible",
+    "is_schema_type",
+    "to_dict",
+]

hexdag/core/resolver.py

@@ -0,0 +1,304 @@
+"""Simple module path resolver for hexDAG components.
+
+This replaces the registry system with Python's import system.
+Components are resolved by their full module path.
+
+Examples
+--------
+>>> from hexdag.core.resolver import resolve
+>>> LLMNode = resolve("hexdag.builtin.nodes.LLMNode")
+>>> adapter = resolve("hexdag.builtin.adapters.mock.MockLLM")
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+class ResolveError(Exception):
+    """Raised when a module path cannot be resolved."""
+
+    def __init__(self, kind: str, reason: str):
+        self.kind = kind
+        self.reason = reason
+        super().__init__(f"Cannot resolve '{kind}': {reason}")
+
+
+# Runtime storage for dynamically created components (e.g., YAML-defined macros)
+_runtime_components: dict[str, type[Any]] = {}
+
+# User-registered aliases (separate from built-in short names)
+_user_aliases: dict[str, str] = {}
+
+# Builtin aliases registered by hexdag.builtin during bootstrap
+_builtin_aliases: dict[str, str] = {}
+
+# Flag to track if builtin has been bootstrapped
+_builtin_bootstrapped: bool = False
+
+
+def register_builtin_aliases(aliases: dict[str, str]) -> None:
+    """Register builtin node aliases (called by hexdag.builtin during bootstrap).
+
+    This allows the builtin package to register its auto-discovered aliases
+    without core needing to import from builtin (maintaining hexagonal architecture).
+
+    Parameters
+    ----------
+    aliases : dict[str, str]
+        Mapping of alias -> full module path
+    """
+    global _builtin_bootstrapped
+    _builtin_aliases.update(aliases)
+    _builtin_bootstrapped = True
+
+
+def _ensure_builtin_bootstrapped() -> None:
+    """Ensure builtin aliases are loaded (triggers bootstrap if needed)."""
+    global _builtin_bootstrapped
+    if not _builtin_bootstrapped:
+        # Import builtin to trigger its bootstrap which calls register_builtin_aliases
+        import hexdag.builtin.nodes  # noqa: F401
+
+        _builtin_bootstrapped = True
+
+
+def get_builtin_aliases() -> dict[str, str]:
+    """Get a copy of all builtin aliases.
+
+    Returns
+    -------
+    dict[str, str]
+        Copy of the alias -> full_path mapping
+    """
+    _ensure_builtin_bootstrapped()
+    return dict(_builtin_aliases)
+
+
+def register_runtime(name: str, component: type[Any]) -> None:
+    """Register a component created at runtime (e.g., YAML-defined macros).
+
+    Parameters
+    ----------
+    name : str
+        Component name (will be prefixed with 'runtime:')
+    component : type
+        The component class
+    """
+    _runtime_components[name] = component
+
+
+def get_runtime(name: str) -> type[Any] | None:
+    """Get a runtime-registered component.
+
+    Parameters
+    ----------
+    name : str
+        Component name
+
+    Returns
+    -------
+    type | None
+        The component class or None if not found
+    """
+    return _runtime_components.get(name)
+
+
+def register_alias(alias: str, full_path: str) -> None:
+    """Register a user-defined alias for a component path.
+
+    This allows using short names in YAML instead of full module paths.
+    User aliases take precedence over built-in short name aliases.
+
+    Parameters
+    ----------
+    alias : str
+        Short name to use in YAML (e.g., "my_processor")
+    full_path : str
+        Full module path (e.g., "myapp.nodes.ProcessorNode")
+
+    Examples
+    --------
+    >>> register_alias("my_processor", "myapp.nodes.ProcessorNode")
+    >>> resolve("my_processor")  # doctest: +SKIP
+    <class 'myapp.nodes.ProcessorNode'>
+
+    >>> # Use in YAML:
+    >>> # spec:
+    >>> #   aliases:
+    >>> #     my_processor: myapp.nodes.ProcessorNode
+    >>> #   nodes:
+    >>> #     - kind: my_processor  # Uses alias!
+    """
+    if not alias:
+        raise ValueError("Alias cannot be empty")
+    if not full_path:
+        raise ValueError("Full path cannot be empty")
+    _user_aliases[alias] = full_path
+
+
+def unregister_alias(alias: str) -> bool:
+    """Remove a user-registered alias.
+
+    Parameters
+    ----------
+    alias : str
+        The alias to remove
+
+    Returns
+    -------
+    bool
+        True if alias was removed, False if it didn't exist
+    """
+    if alias in _user_aliases:
+        del _user_aliases[alias]
+        return True
+    return False
+
+
+def get_registered_aliases() -> dict[str, str]:
+    """Get a copy of all user-registered aliases.
+
+    Returns
+    -------
+    dict[str, str]
+        Copy of the alias -> full_path mapping
+    """
+    return dict(_user_aliases)
+
+
+def clear_aliases() -> None:
+    """Clear all user-registered aliases.
+
+    This is primarily useful for testing.
+    """
+    _user_aliases.clear()
+
+
+def resolve(kind: str) -> type[Any]:
+    """Resolve a kind string to a Python class.
+
+    Parameters
+    ----------
+    kind : str
+        Full module path to the class (e.g., "hexdag.builtin.nodes.LLMNode")
+        or a runtime component name (e.g., "my_macro")
+        or a legacy short name (e.g., "llm_node", "core:llm_node")
+
+    Returns
+    -------
+    type
+        The resolved class
+
+    Raises
+    ------
+    ResolveError
+        If the module or class cannot be found
+
+    Examples
+    --------
+    >>> resolve("hexdag.builtin.nodes.LLMNode")  # doctest: +SKIP
+    <class 'hexdag.builtin.nodes.llm_node.LLMNode'>
+
+    >>> resolve("myapp.nodes.MyProcessor")  # doctest: +SKIP
+    <class 'myapp.nodes.MyProcessor'>
+
+    >>> # Legacy short name support
+    >>> resolve("llm_node")  # doctest: +SKIP
+    <class 'hexdag.builtin.nodes.llm_node.LLMNode'>
+    """
+    # First check runtime components (e.g., YAML-defined macros)
+    if runtime_component := get_runtime(kind):
+        return runtime_component
+
+    # Check user-registered aliases (higher priority than built-in)
+    if kind in _user_aliases:
+        kind = _user_aliases[kind]
+
+    # Check builtin aliases (registered by hexdag.builtin during bootstrap)
+    _ensure_builtin_bootstrapped()
+    if kind in _builtin_aliases:
+        kind = _builtin_aliases[kind]
+
+    if "." not in kind:
+        raise ResolveError(
+            kind,
+            "Must be a full module path (e.g., 'hexdag.builtin.nodes.LLMNode') "
+            "or a registered runtime component",
+        )
+
+    try:
+        module_path, class_name = kind.rsplit(".", 1)
+    except ValueError as e:
+        raise ResolveError(kind, "Invalid format - expected 'module.path.ClassName'") from e
+
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as e:
+        raise ResolveError(kind, f"Module '{module_path}' not found: {e}") from e
+    except ImportError as e:
+        raise ResolveError(kind, f"Failed to import '{module_path}': {e}") from e
+
+    try:
+        cls = getattr(module, class_name)
+    except AttributeError as e:
+        available = [name for name in dir(module) if not name.startswith("_")]
+        raise ResolveError(
+            kind,
+            f"Class '{class_name}' not found in '{module_path}'. "
+            f"Available: {', '.join(available[:10])}",
+        ) from e
+
+    if not isinstance(cls, type):
+        raise ResolveError(kind, f"'{class_name}' is not a class (got {type(cls).__name__})")
+
+    return cls
+
+
+def resolve_function(path: str) -> Any:
+    """Resolve a path to a function or callable.
+
+    Parameters
+    ----------
+    path : str
+        Full module path to the function (e.g., "json.loads")
+
+    Returns
+    -------
+    Callable
+        The resolved function
+
+    Raises
+    ------
+    ResolveError
+        If the module or function cannot be found
+    """
+    if "." not in path:
+        raise ResolveError(
+            path,
+            "Must be a full module path (e.g., 'json.loads')",
+        )
+
+    module_path, func_name = path.rsplit(".", 1)
+
+    try:
+        module = importlib.import_module(module_path)
+    except ModuleNotFoundError as e:
+        raise ResolveError(path, f"Module '{module_path}' not found: {e}") from e
+    except ImportError as e:
+        raise ResolveError(path, f"Failed to import '{module_path}': {e}") from e
+
+    try:
+        func = getattr(module, func_name)
+    except AttributeError as e:
+        available = [name for name in dir(module) if not name.startswith("_")]
+        raise ResolveError(
+            path,
+            f"'{func_name}' not found in '{module_path}'. Available: {', '.join(available[:10])}",
+        ) from e
+
+    if not callable(func):
+        raise ResolveError(path, f"'{func_name}' is not callable (got {type(func).__name__})")
+
+    return func

hexdag/core/schema/__init__.py

@@ -0,0 +1,9 @@
+"""Schema generation and validation for hexDAG components.
+
+This module provides automatic schema generation from Python type hints,
+enabling auto-documentation and YAML validation.
+"""
+
+from hexdag.core.schema.generator import SchemaGenerator
+
+__all__ = ["SchemaGenerator"]