hexastack-core 0.0.0__py3-none-any.whl

hexastack_core/__init__.py

@@ -0,0 +1,10 @@
+from hexastack_core import adapters, domain, infra, ports, testing, utils
+
+__all__ = [
+    "adapters",
+    "domain",
+    "infra",
+    "ports",
+    "testing",
+    "utils",
+]

hexastack_core/adapters/__init__.py

@@ -0,0 +1,43 @@
+from hexastack_core.adapters.ai import (
+    InMemoryLlmProvider,
+    InMemoryVectorStore,
+    LlmCallRecord,
+)
+from hexastack_core.adapters.cache import (
+    AsyncInMemoryCache,
+    InMemoryCache,
+)
+from hexastack_core.adapters.clock import (
+    FrozenClock,
+    InMemoryClock,
+)
+from hexastack_core.adapters.logging import (
+    InMemoryLogger,
+    LogEntry,
+    StandardLogger,
+)
+from hexastack_core.adapters.repository import (
+    AsyncInMemoryRepository,
+    InMemoryRepository,
+)
+from hexastack_core.adapters.unit_of_work import (
+    AsyncInMemoryUnitOfWork,
+    InMemoryUnitOfWork,
+)
+
+__all__ = [
+    "AsyncInMemoryCache",
+    "AsyncInMemoryRepository",
+    "AsyncInMemoryUnitOfWork",
+    "FrozenClock",
+    "InMemoryCache",
+    "InMemoryClock",
+    "InMemoryLlmProvider",
+    "InMemoryLogger",
+    "InMemoryRepository",
+    "InMemoryUnitOfWork",
+    "InMemoryVectorStore",
+    "LlmCallRecord",
+    "LogEntry",
+    "StandardLogger",
+]

hexastack_core/adapters/ai/__init__.py

@@ -0,0 +1,11 @@
+from hexastack_core.adapters.ai.in_memory import (
+    InMemoryLlmProvider,
+    InMemoryVectorStore,
+    LlmCallRecord,
+)
+
+__all__ = [
+    "InMemoryLlmProvider",
+    "InMemoryVectorStore",
+    "LlmCallRecord",
+]

hexastack_core/adapters/ai/in_memory.py

@@ -0,0 +1,196 @@
+import math
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import BaseModel
+
+from hexastack_core.ports.ai import LlmProviderPort, Metadata, VectorStorePort
+
+
+@dataclass
+class LlmCallRecord:
+    """Record of an invocation made to InMemoryLlmProvider."""
+
+    prompt: str
+    system_prompt: str | None = None
+    response_schema: type[BaseModel] | None = None
+    response: Any = None
+
+
+class InMemoryLlmProvider(LlmProviderPort):
+    """In-memory LLM provider adapter for unit testing and local development.
+
+    Notes/Architectural Intent:
+        Implements LlmProviderPort, allowing tests to mock text and structured responses,
+        inspect invocation history, and simulate errors without API keys or external services.
+    """
+
+    def __init__(
+        self,
+        default_text: str = "Mock LLM text response",
+        default_structured: BaseModel | None = None,
+    ) -> None:
+        """Initialize InMemoryLlmProvider with optional default responses."""
+        self._default_text = default_text
+        self._default_structured = default_structured
+        self._text_responses: dict[str, str] = {}
+        self._structured_responses: dict[type[BaseModel], BaseModel] = {}
+        self._simulated_error: Exception | None = None
+        self.history: list[LlmCallRecord] = []
+
+    def _synthesize_mock_instance(self, response_schema: type[BaseModel]) -> BaseModel:
+        """Synthesize mock field values for a required Pydantic model schema."""
+        try:
+            return response_schema()
+        except Exception:  # noqa: BLE001
+            init_data = {}
+            for name, field_info in response_schema.model_fields.items():
+                if field_info.annotation is str:
+                    init_data[name] = f"Mock {name}"
+                elif field_info.annotation in (int, float):
+                    init_data[name] = 1
+                elif field_info.annotation is bool:
+                    init_data[name] = True
+                else:
+                    init_data[name] = None
+            return response_schema.model_validate(init_data)
+
+    def add_structured_response(
+        self, schema_cls: type[BaseModel], response: BaseModel
+    ) -> None:
+        """Map a response schema class to a specific model response instance."""
+        self._structured_responses[schema_cls] = response
+
+    def add_text_response(self, prompt_substring: str, response: str) -> None:
+        """Map a prompt substring to a specific text response."""
+        self._text_responses[prompt_substring] = response
+
+    def clear(self) -> None:
+        """Reset all mock history and mappings."""
+        self.history.clear()
+        self._text_responses.clear()
+        self._structured_responses.clear()
+        self._simulated_error = None
+
+    def generate_structured(
+        self,
+        prompt: str,
+        response_schema: type[BaseModel],
+        system_prompt: str | None = None,
+    ) -> BaseModel:
+        """Generate a structured Pydantic model response."""
+        if self._simulated_error is not None:
+            raise self._simulated_error
+
+        res: BaseModel
+        if response_schema in self._structured_responses:
+            res = self._structured_responses[response_schema]
+        elif self._default_structured is not None and isinstance(
+            self._default_structured, response_schema
+        ):
+            res = self._default_structured
+        else:
+            res = self._synthesize_mock_instance(response_schema)
+
+        record = LlmCallRecord(
+            prompt=prompt,
+            response_schema=response_schema,
+            response=res,
+        )
+        self.history.append(record)
+        return res
+
+    def generate_text(self, prompt: str, system_prompt: str | None = None) -> str:
+        """Generate text from prompt or match configured mock responses."""
+        if self._simulated_error is not None:
+            raise self._simulated_error
+
+        # Check explicit prompt substring mappings
+        response_text = self._default_text
+        for sub, resp in self._text_responses.items():
+            if sub in prompt:
+                response_text = resp
+                break
+
+        record = LlmCallRecord(
+            prompt=prompt,
+            system_prompt=system_prompt,
+            response=response_text,
+        )
+        self.history.append(record)
+        return response_text
+
+    def set_default_structured(self, model: BaseModel) -> None:
+        """Set the fallback structured model response."""
+        self._default_structured = model
+
+    def set_default_text(self, text: str) -> None:
+        """Set the fallback text response."""
+        self._default_text = text
+
+    def set_error(self, error: Exception | None) -> None:
+        """Set a simulated exception to raise on subsequent generation calls."""
+        self._simulated_error = error
+
+
+class InMemoryVectorStore(VectorStorePort):
+    """In-memory vector store adapter computing cosine similarity.
+
+    Notes/Architectural Intent:
+        Implements VectorStorePort with dictionary-backed in-memory vector storage
+        and exact cosine similarity search for local development and testing.
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty in-memory vector store."""
+        self._vectors: dict[str, tuple[list[float], Metadata]] = {}
+
+    def clear(self) -> None:
+        """Clear all stored vectors."""
+        self._vectors.clear()
+
+    def delete(self, vector_id: str) -> bool:
+        """Delete a vector by ID."""
+        return self._vectors.pop(vector_id, None) is not None
+
+    def get(self, vector_id: str) -> tuple[list[float], Metadata] | None:
+        """Retrieve stored embedding and metadata for a vector ID."""
+        return self._vectors.get(vector_id)
+
+    def search(self, query_embedding: list[float], limit: int = 5) -> list[Metadata]:
+        """Search for top similar vectors using cosine similarity."""
+        if not self._vectors:
+            return []
+
+        def cosine_similarity(v1: list[float], v2: list[float]) -> float:
+            dot = sum(a * b for a, b in zip(v1, v2, strict=False))
+            norm1 = math.sqrt(sum(a * a for a in v1))
+            norm2 = math.sqrt(sum(b * b for b in v2))
+            if norm1 == 0.0 or norm2 == 0.0:
+                return 0.0
+            return dot / (norm1 * norm2)
+
+        scored = []
+        for vid, (emb, meta) in self._vectors.items():
+            sim = cosine_similarity(query_embedding, emb)
+            meta_with_id = dict(meta)
+            meta_with_id["_id"] = vid
+            meta_with_id["_score"] = sim
+            scored.append((sim, meta_with_id))
+
+        # Sort descending by similarity score
+        scored.sort(key=lambda item: item[0], reverse=True)
+        return [meta for _, meta in scored[:limit]]
+
+    def upsert(
+        self, vector_id: str, embedding: list[float], metadata: Metadata
+    ) -> None:
+        """Store or update vector embedding and metadata."""
+        self._vectors[vector_id] = (list(embedding), dict(metadata))
+
+
+__all__ = [
+    "InMemoryLlmProvider",
+    "InMemoryVectorStore",
+    "LlmCallRecord",
+]

hexastack_core/adapters/cache/__init__.py

@@ -0,0 +1,9 @@
+from hexastack_core.adapters.cache.in_memory import (
+    AsyncInMemoryCache,
+    InMemoryCache,
+)
+
+__all__ = [
+    "AsyncInMemoryCache",
+    "InMemoryCache",
+]

hexastack_core/adapters/cache/in_memory.py

@@ -0,0 +1,90 @@
+import time
+from typing import Any
+
+from hexastack_core.ports.cache import AsyncCachePort, CachePort
+from hexastack_core.ports.clock import ClockPort
+
+
+class InMemoryCache(CachePort):
+    """In-memory dictionary cache adapter with TTL expiration support.
+
+    Notes/Architectural Intent:
+        Implements CachePort for local development, caching middleware tests,
+        and unit testing without requiring Redis. Accepts an optional ClockPort
+        for deterministic time testing.
+    """
+
+    def __init__(self, clock: ClockPort | None = None) -> None:
+        """Initialize empty in-memory cache.
+
+        Args:
+            clock: Optional ClockPort instance for time measurement.
+        """
+        self._store: dict[str, tuple[Any, float | None]] = {}
+        self._clock = clock
+
+    def _now(self) -> float:
+        return self._clock.timestamp() if self._clock else time.time()
+
+    def clear(self) -> None:
+        """Clear all keys from the cache."""
+        self._store.clear()
+
+    def delete(self, key: str) -> bool:
+        """Delete a key from the cache."""
+        return self._store.pop(key, None) is not None
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve a cached value if present and not expired."""
+        if key not in self._store:
+            return default
+        val, expiry = self._store[key]
+        if expiry is not None and self._now() > expiry:
+            del self._store[key]
+            return default
+        return val
+
+    def has(self, key: str) -> bool:
+        """Check if a key exists and has not expired."""
+        if key not in self._store:
+            return False
+        _, expiry = self._store[key]
+        if expiry is not None and self._now() > expiry:
+            del self._store[key]
+            return False
+        return True
+
+    def set(self, key: str, value: Any, ttl_seconds: float | None = None) -> None:
+        """Store a cached value with optional TTL expiration."""
+        expiry = self._now() + ttl_seconds if ttl_seconds is not None else None
+        self._store[key] = (value, expiry)
+
+
+class AsyncInMemoryCache(AsyncCachePort):
+    """Asynchronous in-memory cache adapter."""
+
+    def __init__(self, clock: ClockPort | None = None) -> None:
+        self._sync_cache = InMemoryCache(clock=clock)
+
+    async def clear_async(self) -> None:
+        self._sync_cache.clear()
+
+    async def delete_async(self, key: str) -> bool:
+        return self._sync_cache.delete(key)
+
+    async def get_async(self, key: str, default: Any = None) -> Any:
+        return self._sync_cache.get(key, default)
+
+    async def has_async(self, key: str) -> bool:
+        return self._sync_cache.has(key)
+
+    async def set_async(
+        self, key: str, value: Any, ttl_seconds: float | None = None
+    ) -> None:
+        self._sync_cache.set(key, value, ttl_seconds)
+
+
+__all__ = [
+    "AsyncInMemoryCache",
+    "InMemoryCache",
+]

hexastack_core/adapters/clock/__init__.py

@@ -0,0 +1,9 @@
+from hexastack_core.adapters.clock.in_memory import (
+    FrozenClock,
+    InMemoryClock,
+)
+
+__all__ = [
+    "FrozenClock",
+    "InMemoryClock",
+]

hexastack_core/adapters/clock/in_memory.py

@@ -0,0 +1,80 @@
+from datetime import UTC, datetime, timedelta
+
+from hexastack_core.ports.clock import ClockPort
+
+
+class InMemoryClock(ClockPort):
+    """Real-time clock adapter reading system UTC time.
+
+    Notes/Architectural Intent:
+        Default production/local adapter providing real-time clock access.
+    """
+
+    def now_utc(self) -> datetime:
+        """Return the current UTC datetime."""
+        return datetime.now(UTC)
+
+    def timestamp(self) -> float:
+        """Return the current POSIX timestamp."""
+        return datetime.now(UTC).timestamp()
+
+
+class FrozenClock(ClockPort):
+    """Deterministic simulated clock supporting time freezing and manual advancement.
+
+    Notes/Architectural Intent:
+        Allows test cases to freeze time at a fixed point and advance it explicitly
+        (e.g., clock.advance(minutes=10)) to verify TTL expiration and timeout logic.
+    """
+
+    def __init__(self, initial_time: datetime | None = None) -> None:
+        """Initialize FrozenClock.
+
+        Args:
+            initial_time: Optional datetime to start at. Defaults to current UTC time.
+        """
+        self._current_time: datetime = (
+            initial_time.astimezone(UTC)
+            if initial_time is not None
+            else datetime.now(UTC)
+        )
+
+    def advance(
+        self,
+        seconds: float = 0,
+        minutes: float = 0,
+        hours: float = 0,
+        days: float = 0,
+    ) -> datetime:
+        """Advance the frozen clock forward by a specified duration.
+
+        Args:
+            seconds: Seconds to advance.
+            minutes: Minutes to advance.
+            hours: Hours to advance.
+            days: Days to advance.
+
+        Returns:
+            The new current UTC datetime after advancement.
+        """
+        delta = timedelta(days=days, hours=hours, minutes=minutes, seconds=seconds)
+        self._current_time += delta
+        return self._current_time
+
+    def now_utc(self) -> datetime:
+        """Return the frozen UTC datetime."""
+        return self._current_time
+
+    def set_time(self, new_time: datetime) -> None:
+        """Set the frozen clock to an explicit datetime."""
+        self._current_time = new_time.astimezone(UTC)
+
+    def timestamp(self) -> float:
+        """Return the frozen POSIX timestamp."""
+        return self._current_time.timestamp()
+
+
+__all__ = [
+    "FrozenClock",
+    "InMemoryClock",
+]

hexastack_core/adapters/feature_flags/__init__.py

@@ -0,0 +1,7 @@
+from hexastack_core.adapters.feature_flags.config import ConfigFeatureFlagAdapter
+from hexastack_core.adapters.feature_flags.in_memory import InMemoryFeatureFlagAdapter
+
+__all__ = [
+    "ConfigFeatureFlagAdapter",
+    "InMemoryFeatureFlagAdapter",
+]

hexastack_core/adapters/feature_flags/config.py

@@ -0,0 +1,235 @@
+import importlib.util
+from collections.abc import Mapping
+from typing import Any
+
+from hexastack_core.domain.feature_flags import (
+    EvaluationContext,
+    FlagEvaluationDetails,
+    FlagEvaluationReason,
+)
+from hexastack_core.infra.config import HexastackConfig
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+
+
+class ConfigFeatureFlagAdapter(FeatureFlagPort):
+    """Feature flag adapter backed by HexastackConfig and static package inspection.
+
+    Notes/Architectural Intent:
+        Evaluates flags against loaded application configuration (`HexastackConfig`),
+        environment overrides, and static optional package installation checks
+        (via `importlib.util.find_spec`).
+    """
+
+    def __init__(
+        self,
+        config: HexastackConfig | None = None,
+        overrides: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Initialize adapter with optional configuration and static overrides.
+
+        Args:
+            config: Optional HexastackConfig instance.
+            overrides: Optional runtime dictionary overrides.
+        """
+        self._config = config
+        self._overrides: dict[str, Any] = dict(overrides or {})
+
+    def get_all_flags(self) -> dict[str, Any]:
+        """Return a dictionary of all active flags and overrides for UI introspection.
+
+        Returns:
+            Dictionary mapping flag keys to their configured values.
+        """
+        flags: dict[str, Any] = dict(self._overrides)
+        if self._config is not None and hasattr(self._config, "_core"):
+            for attr in dir(self._config._core):
+                if not attr.startswith("_"):
+                    val = getattr(self._config._core, attr)
+                    if isinstance(val, (bool, str, int, float)):
+                        flags[f"core.{attr}"] = val
+        return flags
+
+    def _lookup_config_path(self, path: str) -> Any:
+        """Lookup nested attribute or dictionary key in config."""
+        if self._config is None:
+            return None
+
+        # Check in _core first if top-level attribute
+        if hasattr(self._config, "_core"):
+            if hasattr(self._config._core, path):
+                return getattr(self._config._core, path)
+            if hasattr(self._config, "_sections"):
+                parts = path.split(".", 1)
+                if len(parts) == 2 and parts[0] in self._config._sections:
+                    section = self._config._sections[parts[0]]
+                    return getattr(section, parts[1], None)
+
+        parts = path.split(".")
+        current: Any = self._config
+        for part in parts:
+            if current is None:
+                return None
+            if isinstance(current, dict):
+                current = current.get(part)
+            elif hasattr(current, part):
+                current = getattr(current, part)
+            else:
+                return None
+        return current
+
+    def get_boolean_details(
+        self,
+        flag_key: str,
+        default: bool = False,
+        context: EvaluationContext | None = None,
+    ) -> FlagEvaluationDetails[bool]:
+        """Evaluate boolean flag with resolution reason."""
+        if flag_key in self._overrides:
+            val = self._overrides[flag_key]
+            if isinstance(val, bool):
+                return FlagEvaluationDetails(
+                    flag_key=flag_key,
+                    value=val,
+                    reason=FlagEvaluationReason.STATIC,
+                )
+
+        if flag_key.startswith("features.lib."):
+            lib_name = flag_key.removeprefix("features.lib.")
+            found = importlib.util.find_spec(lib_name) is not None
+            return FlagEvaluationDetails(
+                flag_key=flag_key,
+                value=found,
+                reason=FlagEvaluationReason.STATIC,
+            )
+
+        if self._config is not None:
+            val = self._lookup_config_path(flag_key)
+            if isinstance(val, bool):
+                return FlagEvaluationDetails(
+                    flag_key=flag_key,
+                    value=val,
+                    reason=FlagEvaluationReason.STATIC,
+                )
+
+        return FlagEvaluationDetails(
+            flag_key=flag_key,
+            value=default,
+            reason=FlagEvaluationReason.DEFAULT,
+        )
+
+    def get_boolean_value(
+        self,
+        flag_key: str,
+        default: bool = False,
+        context: EvaluationContext | None = None,
+    ) -> bool:
+        """Evaluate a boolean feature flag."""
+        return self.is_enabled(flag_key, default=default, context=context)
+
+    def get_float_value(
+        self,
+        flag_key: str,
+        default: float,
+        context: EvaluationContext | None = None,
+    ) -> float:
+        """Evaluate a floating-point feature flag."""
+        if flag_key in self._overrides:
+            val = self._overrides[flag_key]
+            if isinstance(val, (int, float)) and not isinstance(val, bool):
+                return float(val)
+
+        if self._config is not None:
+            val = self._lookup_config_path(flag_key)
+            if isinstance(val, (int, float)) and not isinstance(val, bool):
+                return float(val)
+
+        return default
+
+    def get_integer_value(
+        self,
+        flag_key: str,
+        default: int,
+        context: EvaluationContext | None = None,
+    ) -> int:
+        """Evaluate an integer feature flag."""
+        if flag_key in self._overrides:
+            val = self._overrides[flag_key]
+            if isinstance(val, int) and not isinstance(val, bool):
+                return val
+
+        if self._config is not None:
+            val = self._lookup_config_path(flag_key)
+            if isinstance(val, int) and not isinstance(val, bool):
+                return val
+
+        return default
+
+    def get_object_value(
+        self,
+        flag_key: str,
+        default: Mapping[str, Any],
+        context: EvaluationContext | None = None,
+    ) -> Mapping[str, Any]:
+        """Evaluate a structured JSON/dictionary feature flag."""
+        if flag_key in self._overrides:
+            val = self._overrides[flag_key]
+            if isinstance(val, Mapping):
+                return val
+
+        if self._config is not None:
+            val = self._lookup_config_path(flag_key)
+            if isinstance(val, Mapping):
+                return val
+
+        return default
+
+    def get_string_value(
+        self,
+        flag_key: str,
+        default: str,
+        context: EvaluationContext | None = None,
+    ) -> str:
+        """Evaluate a string feature flag."""
+        if flag_key in self._overrides:
+            val = self._overrides[flag_key]
+            if isinstance(val, str):
+                return val
+
+        if self._config is not None:
+            val = self._lookup_config_path(flag_key)
+            if isinstance(val, str):
+                return val
+
+        return default
+
+    def is_enabled(
+        self,
+        flag_key: str,
+        default: bool = False,
+        context: EvaluationContext | None = None,
+    ) -> bool:
+        """Evaluate a boolean feature flag against overrides, config, and package checks."""
+        # 1. Overrides take precedence
+        if flag_key in self._overrides:
+            val = self._overrides[flag_key]
+            if isinstance(val, bool):
+                return val
+
+        # 2. Check for dynamic library presence flags (e.g., 'features.lib.<pkg>')
+        if flag_key.startswith("features.lib."):
+            lib_name = flag_key.removeprefix("features.lib.")
+            return importlib.util.find_spec(lib_name) is not None
+
+        # 3. Check loaded configuration dict if available
+        if self._config is not None:
+            # Match top-level or dotted section attributes
+            val = self._lookup_config_path(flag_key)
+            if isinstance(val, bool):
+                return val
+
+        return default
+
+
+__all__ = [
+    "ConfigFeatureFlagAdapter",
+]