hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/core/secrets.py

@@ -0,0 +1,242 @@
+"""Simple secret resolution for adapters.
+
+This module provides a clean way to declare secrets in adapter __init__ signatures
+without complex Config classes. Secrets are resolved from environment variables
+or Memory port automatically.
+
+Example:
+    @adapter("llm", name="openai")
+    class OpenAIAdapter:
+        def __init__(
+            self,
+            api_key: str = secret(env="OPENAI_API_KEY"),
+            model: str = "gpt-4"
+        ):
+            self.api_key = api_key
+            self.model = model
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from hexdag.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class SecretDescriptor:
+    """Descriptor for a secret parameter.
+
+    This is used as a default value in __init__ to mark a parameter
+    as a secret that should be auto-resolved.
+
+    Attributes
+    ----------
+    env_var : str
+        Environment variable name to resolve from
+    memory_key : str | None
+        Key in Memory port (defaults to env_var with "secret:" prefix)
+    required : bool
+        Whether this secret is required
+    description : str
+        Human-readable description
+    """
+
+    env_var: str
+    memory_key: str | None = None
+    required: bool = True
+    description: str = ""
+
+    def resolve(self, memory: Any = None) -> str | None:
+        """Resolve secret value from environment or memory.
+
+        Resolution order:
+        1. Environment variable
+        2. Memory port (with "secret:" prefix)
+        3. None (if not required)
+
+        Parameters
+        ----------
+        memory : Any, optional
+            Memory port instance to read from
+
+        Returns
+        -------
+        str | None
+            Resolved secret value or None
+
+        Raises
+        ------
+        ValueError
+            If secret is required but not found
+        """
+        # Try environment first
+        if value := os.getenv(self.env_var):
+            logger.debug(f"Resolved secret from env: {self.env_var}")
+            return value
+
+        # Try memory
+        if memory:
+            memory_key = self.memory_key or f"secret:{self.env_var}"
+            try:
+                if hasattr(memory, "get"):
+                    value = memory.get(memory_key)
+                elif hasattr(memory, "aget"):
+                    # Async memory - can't resolve here
+                    logger.warning(
+                        f"Memory port is async, cannot resolve {memory_key} in __init__. "
+                        "Consider using environment variable."
+                    )
+                else:
+                    value = None
+
+                if value:
+                    logger.debug(f"Resolved secret from memory: {memory_key}")
+                    if hasattr(value, "get_secret_value"):
+                        return value.get_secret_value()  # type: ignore[no-any-return]
+                    return str(value)
+            except Exception as e:
+                logger.debug(f"Failed to read from memory: {e}")
+
+        # Not found
+        if self.required:
+            raise ValueError(
+                f"Required secret '{self.env_var}' not found. "
+                f"Set environment variable {self.env_var} or provide in memory."
+            )
+
+        return None
+
+
+def secret(
+    env: str, memory_key: str | None = None, required: bool = True, description: str = ""
+) -> SecretDescriptor:
+    """Mark a parameter as a secret that should be auto-resolved.
+
+    Use this as a default value in __init__ to declare secrets.
+    The @adapter decorator will automatically resolve these.
+
+    Parameters
+    ----------
+    env : str
+        Environment variable name (e.g., "OPENAI_API_KEY")
+    memory_key : str | None, optional
+        Alternative key in Memory port. If None, uses "secret:{env}"
+    required : bool, default=True
+        Whether this secret is required
+    description : str, default=""
+        Human-readable description for docs/CLI
+
+    Returns
+    -------
+    SecretDescriptor
+        Secret descriptor that will be resolved by @adapter decorator
+
+    Examples
+    --------
+    >>> @adapter("llm", name="openai")  # doctest: +SKIP
+    ... class OpenAIAdapter:
+    ...     def __init__(
+    ...         self,
+    ...         api_key: str = secret(env="OPENAI_API_KEY", description="OpenAI API key"),
+    ...         model: str = "gpt-4"
+    ...     ):
+    ...         self.api_key = api_key
+    ...         self.model = model
+    """
+    return SecretDescriptor(
+        env_var=env, memory_key=memory_key, required=required, description=description
+    )
+
+
+def resolve_secrets_in_kwargs(
+    cls: type, kwargs: dict[str, Any], memory: Any = None
+) -> dict[str, Any]:
+    """Resolve secrets in kwargs based on __init__ signature.
+
+    Scans the __init__ signature for SecretDescriptor defaults
+    and resolves them from environment or memory.
+
+    Parameters
+    ----------
+    cls : type
+        Class to inspect
+    kwargs : dict[str, Any]
+        Keyword arguments passed to __init__
+    memory : Any, optional
+        Memory port for secret resolution
+
+    Returns
+    -------
+    dict[str, Any]
+        Updated kwargs with resolved secrets
+
+    Examples
+    --------
+    >>> kwargs = resolve_secrets_in_kwargs(OpenAIAdapter, {}, memory)  # doctest: +SKIP
+    >>> # If OPENAI_API_KEY is set: kwargs = {"api_key": "sk-..."}
+    """
+    sig = inspect.signature(cls.__init__)  # type: ignore[misc]
+
+    for param_name, param in sig.parameters.items():
+        if param_name in ("self", "cls"):
+            continue
+
+        if isinstance(param.default, SecretDescriptor):
+            secret_desc = param.default
+
+            # Skip if already provided in kwargs
+            if param_name in kwargs and kwargs[param_name] is not None:
+                logger.debug(f"Secret '{param_name}' provided explicitly")
+                continue
+
+            # Resolve the secret
+            try:
+                resolved_value = secret_desc.resolve(memory=memory)
+                if resolved_value is not None:
+                    kwargs[param_name] = resolved_value
+                    logger.debug(f"Resolved secret '{param_name}'")
+            except ValueError as e:
+                # Required secret not found
+                logger.error(f"Failed to resolve secret '{param_name}': {e}")
+                raise
+
+    return kwargs
+
+
+def extract_secrets_from_signature(cls: type) -> dict[str, SecretDescriptor]:
+    """Extract all secret declarations from __init__ signature.
+
+    This is used by CLI to show which secrets are required.
+
+    Parameters
+    ----------
+    cls : type
+        Class to inspect
+
+    Returns
+    -------
+    dict[str, SecretDescriptor]
+        Mapping of parameter name to SecretDescriptor
+
+    Examples
+    --------
+    >>> secrets = extract_secrets_from_signature(OpenAIAdapter)  # doctest: +SKIP
+    >>> # {"api_key": SecretDescriptor(env_var="OPENAI_API_KEY", ...)}
+    """
+    sig = inspect.signature(cls.__init__)  # type: ignore[misc]
+    secrets = {}
+
+    for param_name, param in sig.parameters.items():
+        if param_name in ("self", "cls"):
+            continue
+
+        if isinstance(param.default, SecretDescriptor):
+            secrets[param_name] = param.default
+
+    return secrets

hexdag/core/types.py

@@ -0,0 +1,413 @@
+"""Central repository for reusable Annotated types.
+
+This module provides type aliases with validation constraints that are used
+throughout the hexDAG framework. Using Annotated types reduces boilerplate,
+improves type safety, and provides better IDE support.
+
+Type Categories
+---------------
+- **Numeric Constraints**: PositiveInt, NonNegativeInt, PositiveFloat, etc.
+- **LLM Parameters**: Temperature, TopP, Penalty, etc.
+- **Time/Duration**: TimeoutSeconds, DelaySeconds
+- **String Constraints**: NonEmptyStr, Identifier, QueryId
+- **Domain Types**: TenantId, Confidence
+
+Examples
+--------
+```python
+from hexdag.core.types import Temperature01, TimeoutSeconds
+
+class Config(BaseModel):
+    temperature: Temperature01 = 0.7
+    timeout: TimeoutSeconds = 60.0
+```
+"""
+
+from typing import Annotated, Any, get_args, get_origin
+
+from pydantic import Field
+
+# ============================================================================
+# Numeric Constraints
+# ============================================================================
+
+PositiveInt = Annotated[int, Field(gt=0, description="Positive integer (> 0)")]
+"""Integer greater than 0."""
+
+NonNegativeInt = Annotated[int, Field(ge=0, description="Non-negative integer (>= 0)")]
+"""Integer greater than or equal to 0."""
+
+PositiveFloat = Annotated[float, Field(gt=0, description="Positive float (> 0)")]
+"""Float greater than 0."""
+
+NonNegativeFloat = Annotated[float, Field(ge=0.0, description="Non-negative float (>= 0)")]
+"""Float greater than or equal to 0."""
+
+# ============================================================================
+# LLM Parameters
+# ============================================================================
+
+Temperature01 = Annotated[
+    float, Field(ge=0.0, le=1.0, description="Temperature sampling parameter [0.0, 1.0]")
+]
+"""LLM temperature parameter, range [0.0, 1.0]. Used by Anthropic/Claude."""
+
+Temperature02 = Annotated[
+    float, Field(ge=0.0, le=2.0, description="Temperature sampling parameter [0.0, 2.0]")
+]
+"""LLM temperature parameter, range [0.0, 2.0]. Used by OpenAI."""
+
+TopP = Annotated[float, Field(ge=0.0, le=1.0, description="Top-p (nucleus) sampling parameter")]
+"""Top-p sampling parameter, range [0.0, 1.0]."""
+
+FrequencyPenalty = Annotated[
+    float, Field(ge=-2.0, le=2.0, description="Frequency penalty [-2.0, 2.0]")
+]
+"""Frequency penalty for token repetition, range [-2.0, 2.0]."""
+
+PresencePenalty = Annotated[
+    float, Field(ge=-2.0, le=2.0, description="Presence penalty [-2.0, 2.0]")
+]
+"""Presence penalty for token diversity, range [-2.0, 2.0]."""
+
+TokenCount = Annotated[int, Field(gt=0, description="Number of tokens")]
+"""Token count, must be positive."""
+
+# ============================================================================
+# Time and Duration
+# ============================================================================
+
+TimeoutSeconds = Annotated[float, Field(gt=0, description="Timeout duration in seconds")]
+"""Timeout duration in seconds, must be positive."""
+
+DelaySeconds = Annotated[float, Field(ge=0.0, description="Delay duration in seconds")]
+"""Delay duration in seconds, non-negative."""
+
+# ============================================================================
+# Retry and Resilience
+# ============================================================================
+
+RetryCount = Annotated[int, Field(ge=0, description="Maximum retry attempts")]
+"""Maximum number of retry attempts, non-negative."""
+
+# ============================================================================
+# String Constraints
+# ============================================================================
+
+NonEmptyStr = Annotated[str, Field(min_length=1, max_length=255, description="Non-empty string")]
+"""Non-empty string with max length 255."""
+
+Identifier = Annotated[
+    str,
+    Field(
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*$",
+        min_length=1,
+        max_length=100,
+        description="Valid identifier (Python-style)",
+    ),
+]
+"""Valid Python-style identifier."""
+
+QueryId = Annotated[
+    str,
+    Field(
+        pattern=r"^[a-zA-Z0-9_-]+$",
+        min_length=1,
+        max_length=100,
+        description="Query identifier",
+    ),
+]
+"""Query identifier with alphanumeric, underscore, and hyphen characters."""
+
+FilePath = Annotated[str, Field(min_length=1, description="File system path")]
+"""File system path, non-empty."""
+
+# ============================================================================
+# Domain-Specific Types
+# ============================================================================
+
+TenantId = Annotated[int, Field(gt=0, description="Tenant identifier")]
+"""Unique tenant identifier, positive integer."""
+
+Confidence = Annotated[float, Field(ge=0.0, le=1.0, description="Confidence score [0.0, 1.0]")]
+"""Confidence score, range [0.0, 1.0]."""
+
+Percentage = Annotated[float, Field(ge=0.0, le=100.0, description="Percentage [0.0, 100.0]")]
+"""Percentage value, range [0.0, 100.0]."""
+
+# ============================================================================
+# Framework Type Aliases (Python 3.12+ type statement)
+# ============================================================================
+
+# These use the modern `type` statement (PEP 695) instead of TypeAlias
+# Note: Using Any here to avoid circular imports and external dependencies
+
+# Logger type (loguru.Logger - using Any to avoid import)
+type Logger = Any  # loguru.Logger
+
+# Port types (to be replaced with proper Protocol definitions)
+type PortInstance = Any  # Generic port implementation
+type PortsDict = dict[str, PortInstance]  # Dictionary of port name -> port instance
+
+# ============================================================================
+# Type Inspection Utilities
+# ============================================================================
+
+
+def is_literal_type(type_hint: Any) -> bool:
+    """Check if type hint is a Literal type.
+
+    Examples
+    --------
+    >>> from typing import Literal
+    >>> is_literal_type(Literal["a", "b"])
+    True
+    >>> is_literal_type(str)
+    False
+    """
+    try:
+        from typing import Literal
+
+        origin = get_origin(type_hint)
+        return origin is Literal
+    except ImportError:
+        return False
+
+
+def is_union_type(type_hint: Any) -> bool:
+    """Check if type hint is a Union type (including | syntax).
+
+    Examples
+    --------
+    >>> from typing import Union
+    >>> is_union_type(Union[str, int])
+    True
+    >>> is_union_type(str | int)
+    True
+    >>> is_union_type(str)
+    False
+    """
+    origin = get_origin(type_hint)
+
+    try:
+        from typing import Union
+
+        if origin is Union:
+            return True
+    except ImportError:
+        pass
+
+    try:
+        from types import UnionType
+
+        if isinstance(type_hint, UnionType):
+            return True
+    except ImportError:
+        pass
+
+    return False
+
+
+def is_list_type(type_hint: Any) -> bool:
+    """Check if type hint is a list type.
+
+    Examples
+    --------
+    >>> is_list_type(list[str])
+    True
+    >>> is_list_type(list)
+    True
+    >>> is_list_type(str)
+    False
+    """
+    origin = get_origin(type_hint)
+    return origin is list or type_hint is list
+
+
+def is_dict_type(type_hint: Any) -> bool:
+    """Check if type hint is a dict type.
+
+    Examples
+    --------
+    >>> is_dict_type(dict[str, int])
+    True
+    >>> is_dict_type(dict)
+    True
+    >>> is_dict_type(str)
+    False
+    """
+    origin = get_origin(type_hint)
+    return origin is dict or type_hint is dict
+
+
+def is_annotated_type(type_hint: Any) -> bool:
+    """Check if type hint is an Annotated type.
+
+    Examples
+    --------
+    >>> from typing import Annotated
+    >>> from pydantic import Field
+    >>> is_annotated_type(Annotated[int, Field(ge=0)])
+    True
+    >>> is_annotated_type(int)
+    False
+    """
+    try:
+        from typing import Annotated
+
+        origin = get_origin(type_hint)
+        return origin is Annotated
+    except ImportError:
+        return False
+
+
+def get_annotated_metadata(type_hint: Any) -> tuple[Any, tuple[Any, ...]]:
+    """Extract base type and metadata from Annotated type.
+
+    Examples
+    --------
+    >>> from typing import Annotated
+    >>> from pydantic import Field
+    >>> base, metadata = get_annotated_metadata(Annotated[int, Field(ge=0)])
+    >>> base
+    <class 'int'>
+    """
+    args = get_args(type_hint)
+    if not args:
+        return type_hint, ()
+
+    base_type = args[0]
+    metadata = args[1:] if len(args) > 1 else ()
+
+    return base_type, metadata
+
+
+# ============================================================================
+# Secret Wrapper
+# ============================================================================
+
+
+class Secret:
+    """Minimal secret wrapper to avoid accidental str() in logs.
+
+    This class wraps sensitive string values to prevent them from being
+    accidentally logged or printed. It's used by the SecretPort interface
+    to return secret values in a safe manner.
+
+    The Secret class uses name mangling (double underscore) to make it
+    harder to accidentally access the raw value.
+
+    Examples
+    --------
+    >>> secret = Secret("my-api-key")
+    >>> print(secret)  # Safe - won't print the value
+    <SECRET>
+    >>> str(secret)  # Safe - won't convert to string
+    '<SECRET>'
+    >>> secret.get()  # Explicit access required
+    'my-api-key'
+
+    Usage in adapters::
+
+        # SecretPort implementation
+        async def aget_secret(self, key: str) -> Secret:
+            value = os.getenv(key)
+            return Secret(value)
+
+        # Using the secret
+        secret = await adapter.aget_secret("API_KEY")
+        print(secret)  # <SECRET> (safe)
+        api_key = secret.get()  # "sk-..." (explicit)
+    """
+
+    def __init__(self, value: str) -> None:
+        """Initialize secret with a value.
+
+        Parameters
+        ----------
+        value : str
+            The secret value to wrap
+        """
+        self.__value = value  # Double underscore for name mangling
+
+    def get(self) -> str:
+        """Return the wrapped secret value securely.
+
+        This is the only way to access the actual secret value.
+        Requiring explicit .get() makes it clear when secrets are being accessed.
+
+        Returns
+        -------
+        str
+            The secret value
+        """
+        return self.__value
+
+    def __repr__(self) -> str:
+        """Return a safe string representation for debugging.
+
+        Returns
+        -------
+        str
+            A safe string representation "<SECRET>"
+        """
+        return "<SECRET>"
+
+    def __str__(self) -> str:
+        """Return a safe string representation for display.
+
+        Returns
+        -------
+        str
+            A safe string representation "<SECRET>"
+        """
+        return "<SECRET>"
+
+
+# ============================================================================
+# Backward Compatibility (deprecated, use specific types above)
+# ============================================================================
+
+# These were originally defined in agent_factory/models.py
+# Kept here for backward compatibility but prefer the specific types above
+__all__ = [
+    # Numeric
+    "PositiveInt",
+    "NonNegativeInt",
+    "PositiveFloat",
+    "NonNegativeFloat",
+    # LLM
+    "Temperature01",
+    "Temperature02",
+    "TopP",
+    "FrequencyPenalty",
+    "PresencePenalty",
+    "TokenCount",
+    # Time
+    "TimeoutSeconds",
+    "DelaySeconds",
+    # Retry
+    "RetryCount",
+    # String
+    "NonEmptyStr",
+    "Identifier",
+    "QueryId",
+    "FilePath",
+    # Domain
+    "TenantId",
+    "Confidence",
+    "Percentage",
+    # Secret wrapper
+    "Secret",
+    # Framework types
+    "Logger",
+    "PortInstance",
+    "PortsDict",
+    # Type inspection utilities
+    "is_literal_type",
+    "is_union_type",
+    "is_list_type",
+    "is_dict_type",
+    "is_annotated_type",
+    "get_annotated_metadata",
+]