hexastack-flags 0.0.0__py3-none-any.whl

hexastack_flags/__init__.py

@@ -0,0 +1,12 @@
+from hexastack_flags import adapters, domain, infra, ports
+from hexastack_flags.adapters.openfeature import OpenFeatureFlagAdapter
+from hexastack_flags.infra.bootstrap import FeatureFlagBootstrapper
+
+__all__ = [
+    "adapters",
+    "domain",
+    "FeatureFlagBootstrapper",
+    "infra",
+    "OpenFeatureFlagAdapter",
+    "ports",
+]

hexastack_flags/adapters/__init__.py

@@ -0,0 +1,5 @@
+from hexastack_flags.adapters.openfeature import OpenFeatureFlagAdapter
+
+__all__ = [
+    "OpenFeatureFlagAdapter",
+]

hexastack_flags/adapters/openfeature.py

@@ -0,0 +1,211 @@
+"""CNCF OpenFeature flag adapter implementation.
+
+Notes/Architectural Intent:
+    Adapts the OpenFeature Python SDK (openfeature.api) to Hexastack's FeatureFlagPort.
+    Translates ambient UserContext / EvaluationContext seamlessly to OpenFeature
+    EvaluationContext and evaluates boolean, string, int, float, and JSON flags.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+import openfeature.api
+from openfeature.client import OpenFeatureClient
+from openfeature.evaluation_context import EvaluationContext as OfEvaluationContext
+
+from hexastack_core.domain.feature_flags import (
+    EvaluationContext,
+    FlagEvaluationDetails,
+    FlagEvaluationReason,
+)
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+
+__all__ = [
+    "OpenFeatureFlagAdapter",
+]
+
+
+class OpenFeatureFlagAdapter(FeatureFlagPort):
+    """FeatureFlagPort implementation delegating evaluations to OpenFeature SDK.
+
+    Notes/Architectural Intent:
+        Wraps an OpenFeature Client instance, connecting Hexastack application
+        layers (CQRS, FastAPI, CLI, GraphQL) to any configured OpenFeature provider.
+    """
+
+    def __init__(
+        self,
+        client: OpenFeatureClient | None = None,
+        client_name: str | None = None,
+    ) -> None:
+        self._client = client or openfeature.api.get_client(client_name)
+
+    def get_all_flags(self) -> dict[str, Any]:
+        """Introspect active flags from the underlying OpenFeature provider if supported.
+
+        Returns:
+            Dictionary mapping flag keys to their configured status/values.
+        """
+        flags: dict[str, Any] = {}
+        try:
+            provider: Any = openfeature.api.provider_registry.get_provider(None)
+            provider_flags = getattr(provider, "_flags", None)
+            if isinstance(provider_flags, dict):
+                for k, v in provider_flags.items():
+                    # If InMemoryFlag object, resolve current variant/value
+                    if hasattr(v, "variants") and hasattr(v, "default_variant"):
+                        flags[str(k)] = v.variants.get(
+                            v.default_variant, v.default_variant
+                        )
+                    elif hasattr(v, "state"):
+                        flags[str(k)] = str(v.state)
+                    else:
+                        flags[str(k)] = v
+        except Exception:
+            pass
+        return flags
+
+    def get_boolean_details(
+        self,
+        flag_key: str,
+        default: bool = False,
+        context: EvaluationContext | None = None,
+    ) -> FlagEvaluationDetails[bool]:
+        """Evaluate a boolean flag returning comprehensive evaluation metadata."""
+        of_ctx = _to_openfeature_context(
+            context or EvaluationContext.from_current_context()
+        )
+        details = self._client.get_boolean_details(
+            flag_key=flag_key,
+            default_value=default,
+            evaluation_context=of_ctx,
+        )
+        reason: FlagEvaluationReason = FlagEvaluationReason.UNKNOWN
+        if details.reason:
+            try:
+                reason = FlagEvaluationReason(str(details.reason).upper())
+            except ValueError:
+                reason = FlagEvaluationReason.UNKNOWN
+
+        return FlagEvaluationDetails(
+            flag_key=details.flag_key,
+            value=details.value,
+            reason=reason,
+            variant=details.variant,
+            error_code=str(details.error_code) if details.error_code else None,
+        )
+
+    def get_boolean_value(
+        self,
+        flag_key: str,
+        default: bool = False,
+        context: EvaluationContext | None = None,
+    ) -> bool:
+        """Evaluate a boolean feature flag."""
+        of_ctx = _to_openfeature_context(
+            context or EvaluationContext.from_current_context()
+        )
+        return self._client.get_boolean_value(
+            flag_key=flag_key,
+            default_value=default,
+            evaluation_context=of_ctx,
+        )
+
+    def get_float_value(
+        self,
+        flag_key: str,
+        default: float = 0.0,
+        context: EvaluationContext | None = None,
+    ) -> float:
+        """Evaluate a floating-point feature flag."""
+        of_ctx = _to_openfeature_context(
+            context or EvaluationContext.from_current_context()
+        )
+        return self._client.get_float_value(
+            flag_key=flag_key,
+            default_value=default,
+            evaluation_context=of_ctx,
+        )
+
+    def get_integer_value(
+        self,
+        flag_key: str,
+        default: int = 0,
+        context: EvaluationContext | None = None,
+    ) -> int:
+        """Evaluate an integer feature flag."""
+        of_ctx = _to_openfeature_context(
+            context or EvaluationContext.from_current_context()
+        )
+        return self._client.get_integer_value(
+            flag_key=flag_key,
+            default_value=default,
+            evaluation_context=of_ctx,
+        )
+
+    def get_object_value(
+        self,
+        flag_key: str,
+        default: Mapping[str, Any] | None = None,
+        context: EvaluationContext | None = None,
+    ) -> Mapping[str, Any]:
+        """Evaluate a structured JSON object feature flag."""
+        of_ctx = _to_openfeature_context(
+            context or EvaluationContext.from_current_context()
+        )
+        default_val = dict(default) if default is not None else {}
+        res = self._client.get_object_value(
+            flag_key=flag_key,
+            default_value=default_val,
+            evaluation_context=of_ctx,
+        )
+        return res if isinstance(res, Mapping) else default_val
+
+    def get_string_value(
+        self,
+        flag_key: str,
+        default: str = "",
+        context: EvaluationContext | None = None,
+    ) -> str:
+        """Evaluate a string/variant feature flag."""
+        of_ctx = _to_openfeature_context(
+            context or EvaluationContext.from_current_context()
+        )
+        return self._client.get_string_value(
+            flag_key=flag_key,
+            default_value=default,
+            evaluation_context=of_ctx,
+        )
+
+    def is_enabled(
+        self,
+        flag_key: str,
+        default: bool = False,
+        context: EvaluationContext | None = None,
+    ) -> bool:
+        """Evaluate whether a boolean feature flag is enabled."""
+        return self.get_boolean_value(
+            flag_key=flag_key, default=default, context=context
+        )
+
+
+def _to_openfeature_context(
+    context: EvaluationContext | None,
+) -> OfEvaluationContext | None:
+    """Convert Hexastack EvaluationContext to OpenFeature EvaluationContext."""
+    if context is None:
+        return None
+
+    targeting_key = context.targeting_key or context.user_id or ""
+    attributes: dict[str, Any] = dict(context.attributes)
+    if context.user_id:
+        attributes["user_id"] = context.user_id
+    if context.tenant_id:
+        attributes["tenant_id"] = context.tenant_id
+    if context.roles:
+        attributes["roles"] = list(context.roles)
+
+    return OfEvaluationContext(
+        targeting_key=targeting_key,
+        attributes=attributes,
+    )

hexastack_flags/adapters/providers/__init__.py

@@ -0,0 +1,5 @@
+from hexastack_flags.adapters.providers.factory import initialize_openfeature_provider
+
+__all__ = [
+    "initialize_openfeature_provider",
+]

hexastack_flags/adapters/providers/factory.py

@@ -0,0 +1,88 @@
+"""Factory for initializing OpenFeature provider backends.
+
+Notes/Architectural Intent:
+    Decouples application setup from concrete OpenFeature provider implementations
+    (Flagd, In-Memory, etc.), dynamically importing optional dependencies on demand.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import openfeature.api
+from openfeature.provider.in_memory_provider import InMemoryFlag, InMemoryProvider
+
+from hexastack_core.domain.exceptions import MissingDependencyError
+from hexastack_flags.domain.models import (
+    FeatureFlagProviderType,
+    FlagProviderOptions,
+)
+
+
+def initialize_openfeature_provider(
+    provider_type: FeatureFlagProviderType | str = FeatureFlagProviderType.IN_MEMORY,
+    options: FlagProviderOptions | None = None,
+    in_memory_flags: dict[str, Any] | None = None,
+) -> None:
+    """Initialize and register an OpenFeature provider backend globally.
+
+    Args:
+        provider_type: Target backend ("flagd", "in_memory", "env", etc.).
+        options: Configuration options (host, port, cache, etc.).
+        in_memory_flags: Initial flags dict when using in_memory provider.
+
+    Raises:
+        MissingDependencyError: If a provider extra (e.g. openfeature-provider-flagd) is missing.
+    """
+    opts = options or FlagProviderOptions()
+    p_type = str(provider_type).lower()
+
+    if p_type == FeatureFlagProviderType.FLAGD:
+        try:
+            import importlib
+
+            flagd_mod = importlib.import_module("openfeature.contrib.provider.flagd")
+            config_mod = importlib.import_module(
+                "openfeature.contrib.provider.flagd.config"
+            )
+            flagd_cls = flagd_mod.FlagdProvider
+            cache_type_cls = config_mod.CacheType
+
+            cache_val = cache_type_cls.LRU if opts.cache else cache_type_cls.DISABLED
+
+            provider = flagd_cls(
+                host=opts.host,
+                port=opts.port,
+                cache=cache_val,
+                timeout=opts.timeout_ms,
+            )
+            openfeature.api.set_provider(provider)
+        except (ImportError, AttributeError) as e:
+            raise MissingDependencyError(
+                "openfeature-provider-flagd is required for Flagd provider. "
+                "Install with 'pip install hexastack-flags[flagd]'."
+            ) from e
+
+    elif p_type == FeatureFlagProviderType.IN_MEMORY:
+        flags_dict: dict[str, InMemoryFlag[Any]] = {}
+        if in_memory_flags:
+            for k, v in in_memory_flags.items():
+                if isinstance(v, bool):
+                    flags_dict[k] = InMemoryFlag(
+                        state=InMemoryFlag.State.ENABLED,
+                        default_variant="on" if v else "off",
+                        variants={"on": True, "off": False},
+                    )
+                else:
+                    flags_dict[k] = InMemoryFlag(
+                        state=InMemoryFlag.State.ENABLED,
+                        default_variant="default",
+                        variants={"default": v},
+                    )
+        provider = InMemoryProvider(flags_dict)
+        openfeature.api.set_provider(provider)
+
+
+__all__ = [
+    "initialize_openfeature_provider",
+]

hexastack_flags/domain/__init__.py

@@ -0,0 +1,9 @@
+from hexastack_flags.domain.models import (
+    FeatureFlagProviderType,
+    FlagProviderOptions,
+)
+
+__all__ = [
+    "FeatureFlagProviderType",
+    "FlagProviderOptions",
+]

hexastack_flags/domain/models.py

@@ -0,0 +1,35 @@
+"""Domain models and enumerations for OpenFeature integration.
+
+Notes/Architectural Intent:
+    Encapsulates OpenFeature provider types, provider options, and evaluation
+    metadata conforming to the CNCF OpenFeature specification.
+"""
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "FeatureFlagProviderType",
+    "FlagProviderOptions",
+]
+
+
+class FeatureFlagProviderType(StrEnum):
+    """Supported CNCF OpenFeature provider backends."""
+
+    FLAGD = "flagd"
+    IN_MEMORY = "in_memory"
+    ENV = "env"
+    CUSTOM = "custom"
+
+
+class FlagProviderOptions(BaseModel):
+    """Configuration options for OpenFeature provider initialization."""
+
+    host: str = "localhost"
+    port: int = 8013
+    cache: bool = True
+    timeout_ms: int = 5000
+    extra: dict[str, Any] = Field(default_factory=dict)

hexastack_flags/infra/__init__.py

@@ -0,0 +1,8 @@
+from hexastack_flags.infra.bootstrap import FeatureFlagBootstrapper
+from hexastack_flags.infra.config import HexastackFlagsConfig, register_flags_config
+
+__all__ = [
+    "FeatureFlagBootstrapper",
+    "HexastackFlagsConfig",
+    "register_flags_config",
+]

hexastack_flags/infra/bootstrap.py

@@ -0,0 +1,52 @@
+"""Bootstrapper extension for hexastack-flags.
+
+Notes/Architectural Intent:
+    Configures the OpenFeature provider and registers OpenFeatureFlagAdapter
+    into the rodi.Container as the singleton FeatureFlagPort at order=14.
+"""
+
+from hexastack_core.infra.bootstrap import BootstrapContext
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_core.ports.bootstrap import BootstrapperPort
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+from hexastack_flags.adapters.openfeature import OpenFeatureFlagAdapter
+from hexastack_flags.adapters.providers.factory import initialize_openfeature_provider
+from hexastack_flags.domain.models import FlagProviderOptions
+from hexastack_flags.infra.config import HexastackFlagsConfig, register_flags_config
+
+__all__ = [
+    "FeatureFlagBootstrapper",
+]
+
+
+class FeatureFlagBootstrapper(BootstrapperPort):
+    """Bootstrapper that configures CNCF OpenFeature and binds OpenFeatureFlagAdapter."""
+
+    name: str = "feature_flags"
+    order: int = 14  # Runs before CQRS (20), FastAPI (30), etc.
+
+    def configure(self, context: BootstrapContext) -> None:
+        """Initialize OpenFeature provider and register OpenFeatureFlagAdapter in DI."""
+        config = context.get_config("flags", HexastackFlagsConfig)
+
+        options = FlagProviderOptions(
+            host=config.host,
+            port=config.port,
+            cache=config.cache,
+            timeout_ms=config.timeout_ms,
+            extra=config.options,
+        )
+
+        initialize_openfeature_provider(
+            provider_type=config.provider,
+            options=options,
+            in_memory_flags=config.flags,
+        )
+
+        adapter = OpenFeatureFlagAdapter()
+        context.container.add_instance(adapter, declared_class=FeatureFlagPort)
+        context.flags = adapter
+
+    def register_config(self, registry: ConfigRegistry) -> None:
+        """Register HexastackFlagsConfig under [hexastack.flags]."""
+        register_flags_config(registry)

hexastack_flags/infra/config.py

@@ -0,0 +1,49 @@
+"""Configuration schemas for hexastack-flags.
+
+Notes/Architectural Intent:
+    Defines Pydantic configuration schemas loaded from [hexastack.flags].
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from hexastack_core.infra.decorators import config_section
+from hexastack_core.infra.registries.config import ConfigRegistry
+from hexastack_flags.domain.models import FeatureFlagProviderType
+
+__all__ = [
+    "HexastackFlagsConfig",
+    "register_flags_config",
+]
+
+
+@config_section("flags")
+class HexastackFlagsConfig(BaseModel):
+    """Configuration options under [hexastack.flags]."""
+
+    provider: str = Field(
+        default=FeatureFlagProviderType.IN_MEMORY.value,
+        description="Feature flag provider backend: 'flagd', 'in_memory', 'env'",
+    )
+    host: str = Field(default="localhost", description="Flagd server hostname")
+    port: int = Field(default=8013, description="Flagd server port")
+    cache: bool = Field(
+        default=True, description="Enable local in-memory evaluation cache"
+    )
+    timeout_ms: int = Field(
+        default=5000, description="Evaluation timeout in milliseconds"
+    )
+    flags: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Static in-memory feature flags mapping (key -> bool/value)",
+    )
+    options: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Additional provider-specific configuration options",
+    )
+
+
+def register_flags_config(registry: ConfigRegistry) -> None:
+    """Register the flags configuration schema with the ConfigRegistry."""
+    registry.register_config_section("flags", HexastackFlagsConfig)

hexastack_flags/ports/__init__.py

@@ -0,0 +1,11 @@
+"""Ports module for hexastack_flags.
+
+Notes/Architectural Intent:
+    Re-exports FeatureFlagPort from hexastack_core for hexagonal boundary consistency.
+"""
+
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+
+__all__ = [
+    "FeatureFlagPort",
+]

hexastack_flags-0.0.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.3
+Name: hexastack-flags
+Version: 0.0.0
+Summary: CNCF OpenFeature provider adapters and enterprise feature flagging for Hexastack
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Requires-Dist: hexastack-core
+Requires-Dist: openfeature-sdk>=0.7.1
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: openfeature-provider-flagd>=0.2.0 ; extra == 'flagd'
+Requires-Python: >=3.13
+Provides-Extra: flagd
+Description-Content-Type: text/markdown
+
+# hexastack-flags
+
+**CNCF OpenFeature provider adapters and enterprise feature flagging for Hexastack.**
+
+Part of the [Hexastack Framework](https://github.com/TheTrueSCU/hexastack).
+
+---
+
+## 1. Architectural Overview
+
+`hexastack-flags` provides the production-grade adapter connecting Hexastack's [`FeatureFlagPort`](file:///home/rjdw/Projects/hexastack/packages/hexastack_core/src/hexastack_core/ports/feature_flags.py) to the **CNCF OpenFeature Python SDK**.
+
+It decouples your domain, CQRS handlers, REST routes, Typer commands, and GraphQL resolvers from proprietary feature flagging APIs, allowing seamless integration with **Flagd**, **Unleash**, **Flipt**, **GO Feature Flag**, or local in-memory providers.
+
+```mermaid
+graph TD
+    APP["Driving Adapters (FastAPI / CLI / GraphQL)"]
+    CQRS["CQRS Middleware Pipeline"]
+    PORT["FeatureFlagPort (hexastack-core)"]
+    ADAPTER["OpenFeatureFlagAdapter (hexastack-flags)"]
+    OF_SDK["CNCF OpenFeature SDK"]
+
+    subgraph Providers ["OpenFeature Providers"]
+        FLAGD["FlagdProvider (gRPC / Kubernetes)"]
+        UNLEASH["UnleashProvider"]
+        MEM["InMemoryProvider"]
+        ENV["EnvProvider"]
+    end
+
+    APP --> PORT
+    CQRS --> PORT
+    PORT -.-> ADAPTER
+    ADAPTER --> OF_SDK
+    OF_SDK --> FLAGD
+    OF_SDK --> UNLEASH
+    OF_SDK --> MEM
+    OF_SDK --> ENV
+```
+
+---
+
+## 2. Quickstart
+
+### Installation
+
+```bash
+# Core OpenFeature adapter with In-Memory support
+pip install hexastack-flags
+
+# With Flagd provider
+pip install "hexastack-flags[flagd]"
+```
+
+### Configuration (`hexastack.toml` or `pyproject.toml`)
+
+```toml
+[hexastack.flags]
+provider = "flagd" # "in_memory", "flagd", "env"
+host = "localhost"
+port = 8013
+cache = true
+timeout_ms = 5000
+```
+
+---
+
+## 3. Evaluation Examples
+
+```python
+from hexastack_core.ports.feature_flags import FeatureFlagPort
+from hexastack_core.domain.feature_flags import EvaluationContext
+
+flags = container.resolve(FeatureFlagPort)
+
+# 1. Simple boolean toggle
+if flags.is_enabled("features.checkout.v2", default=False):
+    ...
+
+# 2. Contextual evaluation (multi-tenant / user targeting)
+ctx = EvaluationContext(user_id="usr_123", tenant_id="tenant-alpha")
+theme = flags.get_string_value("features.ui.theme", default="light", context=ctx)
+```

hexastack_flags-0.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+hexastack_flags/__init__.py,sha256=sILX7G9bFKzH8FXOMtylEyPK2Yqctt8-SGlXDpb9rZ0,331
+hexastack_flags/adapters/__init__.py,sha256=zTMxW_o4w6cjS3GG6RlZXLpuP97mrnR1hJqhuSefops,117
+hexastack_flags/adapters/openfeature.py,sha256=9NWacdLtSMU4OAy9ySBVdG_N_gc_2DvYPnrnZyhrEeE,7114
+hexastack_flags/adapters/providers/__init__.py,sha256=ftKX_Y3qNNNKvLECwHim6Q5QMxXX2f1iTCnfftfLo-Y,141
+hexastack_flags/adapters/providers/factory.py,sha256=TAxSNFMY_q5Ot1tuAH7b2rFvA0AW3wr1FIJglO-au1M,3201
+hexastack_flags/domain/__init__.py,sha256=8oNhqS7YzqFbazlIjazuufiufUVIRZMWM71LAsGGNdE,173
+hexastack_flags/domain/models.py,sha256=7G3MxJc1tWGWQ0OguE6wNp1iheFQm9ErZvIqOcXrULU,852
+hexastack_flags/infra/__init__.py,sha256=M4f5otuwkSMj-R4ocHIoPxdWlJtomJBt5lLBvdKJZN8,256
+hexastack_flags/infra/bootstrap.py,sha256=SEAUYDPWciyiels127MVHN6O1I7paLzTqVVdNgWFYkE,2004
+hexastack_flags/infra/config.py,sha256=Q1OJcJzRk_IFD5vuWN0l9XCq9exywuYEzc8TCq9tZdc,1644
+hexastack_flags/ports/__init__.py,sha256=YqsjRH_ch1AOx0TTNZhJzSez07vvABX-iXTBj6fDG7k,259
+hexastack_flags-0.0.0.dist-info/WHEEL,sha256=EmLkUISDECbcUx3FMCYOqokNOJqNp2r0d4mJzjErvvs,80
+hexastack_flags-0.0.0.dist-info/entry_points.txt,sha256=fQ38RyM0PSxp8D1cP1vRZ-gkNeAg2Gm7KuZEuX1MAdw,91
+hexastack_flags-0.0.0.dist-info/METADATA,sha256=IDKaXc9IKMW2SAzyzQoIsYTrMuLePaS2OQJ9x2E94Z8,2733
+hexastack_flags-0.0.0.dist-info/RECORD,,

hexastack_flags-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.3
+Root-Is-Purelib: true
+Tag: py3-none-any

hexastack_flags-0.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[hexastack.bootstrappers]
+flags = hexastack_flags.infra.bootstrap:FeatureFlagBootstrapper
+