unique_toolkit 2026.24.0.dev6__py3-none-any.whl → 2026.24.0.dev8__py3-none-any.whl

unique_toolkit/experimental/README.md

@@ -31,7 +31,7 @@ flowchart TD
     end
 
     internal["<b>_internal/</b><br/><i>package-private primitives</i>"]
-    sdk[("<b>unique_sdk</b><br/><i>external</i>")]
+    sdk[("<b>unique_sdk / config-backend / …</b><br/><i>internal Unique AI backends</i>")]
 
     integrations ==> facades
     integrations -.-> primitives
@@ -75,9 +75,9 @@ API. Think: HTTP plumbing, Pydantic helpers, time/string/exception utilities.
   users, promote it into `resources/`, `components/`, or
   `integrations/` — whichever layer fits — and re-export it there.
 
-### `resources/<name>/` — typed adapters over `unique_sdk`
+### `resources/<name>/` — typed adapters over internal Unique AI backends
 
-One subfolder per SDK resource family. The canonical shape is:
+One subfolder per backend resource family. The canonical shape is:
 
 ```
 resources/<name>/
@@ -87,15 +87,17 @@ resources/<name>/
     __init__.py    # re-exports
 ```
 
-A module belongs here **iff** it could be deleted without losing any
-functionality relative to raw `unique_sdk` usage — it's pure typing + a
-slightly nicer call surface, nothing more.
+"Backend" is deliberately broad: `unique_sdk`, configuration-backend,
+and any other internal Unique AI service are all valid targets. A module
+belongs here **iff** it is a thin, typed adapter — pure schemas + a
+slightly nicer call surface — with no cross-cutting orchestration of its
+own.
 
 - **May import:** `unique_sdk`, `_internal/`, stdlib, third-party libs.
 - **Must not import:** sibling resources (see `facades/` below for the
   exception), `components/`, `integrations/`.
 - **Concrete examples in-tree today:** `user/`, `group/`,
-  `content_folder/`, `scheduled_task/`.
+  `content_folder/`, `scheduled_task/`, `feature_flags/`.
 - **Resources** should be stateless classes
 
 ### `resources/facades/<name>/` — aggregating resources
@@ -208,7 +210,7 @@ way to the bottom is a signal that the module probably does not belong in
 ```mermaid
 flowchart TD
     start(["I'm adding new code"])
-    q1{"Calls <b>unique_sdk</b> directly?"}
+    q1{"Typed adapter over an internal<br/>Unique AI backend<br/>(unique_sdk, config-backend, …)?"}
     q2{"Resource-shaped facade —<br/>composes 2+ primitives with<br/>one-liner delegation methods?"}
     q3{"Adds behaviour beyond the SDK<br/>(orchestration, parallelism,<br/>derived views, evaluation, …)<br/><b>and</b> framework-agnostic?"}
     q4{"Adapter for a specific<br/>third-party framework?"}
@@ -223,7 +225,7 @@ flowchart TD
 
     start --> q1
     q1 -- yes --> primitive
-    q1 -- no --> q2
+    q1 -- no  --> q2
     q2 -- yes --> facade
     q2 -- no --> q3
     q3 -- yes --> component

unique_toolkit/experimental/resources/__init__.py

@@ -1,4 +1,4 @@
-"""Typed adapters over ``unique_sdk``.
+"""Typed adapters over internal Unique AI backends (``unique_sdk``, configuration-backend, etc.).
 
 Thin wrappers around individual SDK resources that add little beyond
 Pydantic schemas and sync/async function pairs. The canonical shape is::
@@ -53,6 +53,8 @@ Planned contents (current home → new home):
 * ``scheduled_task``   ← :mod:`unique_toolkit.experimental.scheduled_task`
 * ``facades.identity`` ← :mod:`unique_toolkit.experimental.identity`
   (the :class:`Identity` facade bundling the :class:`Users` and :class:`Groups` services)
+* ``feature_flags``    — configuration-backend GraphQL adapter; evaluates feature flags
+  with TTL cache, stale-value fallback, and env-var fallback
 
 One thing that *looks* like it should live here but does not:
 

unique_toolkit/experimental/resources/feature_flags/README.md

@@ -0,0 +1,183 @@
+# `feature_flags` — Python feature flag client
+
+Remote feature flag evaluation backed by configuration-backend's GraphQL API,
+with in-process TTL caching and graceful env-var fallback.
+
+Mirrors the OpenFeature `evaluate` / `isEnabled` semantics used by the
+Node.js `@unique/feature-flags` package. The OpenFeature Python SDK is
+deliberately **not** used as a dependency — the interface is implemented
+directly to avoid SDK overhead.
+
+---
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `CONFIGURATION_BACKEND_URL` | **Yes** | — | Base URL of your configuration-backend instance. |
+| `FEATURE_FLAG_SERVICE_ID` | **Yes** | — | Service identifier sent as `x-service-id`. Must match a registered value in configuration-backend's `Service` enum. |
+| `FEATURE_FLAG_CACHE_TTL_MS` | No | `5000` | In-process cache TTL in milliseconds. |
+
+---
+
+## `flag` argument convention
+
+The `flag` argument to `evaluate()` / `is_enabled()` must be the
+**upper-snake env-var-style key**, e.g.:
+
+```
+FEATURE_FLAG_ENABLE_MY_FEATURE
+FEATURE_FLAG_ENABLE_OTHER_FEATURE_UN_12345
+```
+
+This matches both the configuration-backend registry key convention and the
+existing env-var names in Python services, so the env-var fallback path
+requires no transformation.
+
+Define flag name constants in your service (not in the toolkit) to avoid
+magic strings:
+
+```python
+# in your service
+class MyServiceFlags:
+    ENABLE_MY_FEATURE = "FEATURE_FLAG_ENABLE_MY_FEATURE"
+    ENABLE_OTHER_FEATURE = "FEATURE_FLAG_ENABLE_OTHER_FEATURE_UN_12345"
+```
+
+---
+
+## Usage
+
+### Constructor injection (recommended for testing)
+
+```python
+from unique_toolkit.experimental.resources.feature_flags import FeatureFlagClient
+
+client = FeatureFlagClient(
+    url="https://your-configuration-backend",
+    service_id="my-service",
+    ttl_ms=5_000,
+)
+
+result = await client.evaluate(
+    "FEATURE_FLAG_ENABLE_MY_FEATURE",
+    company_id=company_id,
+    user_id=user_id,
+)
+# result.value  → bool
+# result.reason → "remote" | "cached" | "stale" | "fallback"
+
+enabled = await client.is_enabled(
+    "FEATURE_FLAG_ENABLE_MY_FEATURE",
+    company_id=company_id,
+    user_id=user_id,
+)
+```
+
+### `from_settings()` factory (recommended for services)
+
+`from_settings()` is a process-level singleton — repeated calls always return
+the same instance, keeping the TTL cache warm across requests.
+
+```python
+# Call lazily — inside a request handler or app startup hook,
+# NOT at module import time. Env vars must be fully injected before
+# the first call or a ValueError is raised.
+client = FeatureFlagClient.from_settings()
+```
+
+> **⚠️ Do not call `from_settings()` at module level.** In some container
+> runtimes, env vars are not yet available when Python modules are imported.
+> Call it inside your app's startup hook or on first request.
+
+### `bind_settings()` — per-request bound client
+
+For services that use `UniqueSettings` / `AuthContext`, bind the singleton
+once per request to avoid passing `company_id` / `user_id` at every call site:
+
+```python
+from unique_toolkit.experimental.resources.feature_flags import (
+    BoundFeatureFlagClient,
+    FeatureFlagClient,
+)
+
+# once at startup
+client = FeatureFlagClient.from_settings()
+
+# once per request (settings carries company_id / user_id)
+bound: BoundFeatureFlagClient = client.bind_settings(settings)
+
+if await bound.is_enabled("FEATURE_FLAG_ENABLE_MY_FEATURE"):
+    ...
+```
+
+---
+
+## Evaluation order
+
+1. **TTL cache** — returns the cached value if present (within the TTL window).
+2. **Remote** — calls configuration-backend's `evaluateFlag` GraphQL query.
+   One retry on transient 5xx errors.
+3. **Stale cache** — on failure, returns the last successfully fetched value
+   for this `(flag, company_id, user_id)` key if one exists.
+4. **Env-var fallback** — if no stale value is available, reads the flag's
+   env var. Supports plain booleans (`"true"` / `"false"`) and
+   comma-separated company-ID allowlists (`"company1,company2"`), consistent
+   with `unique_toolkit.agentic.feature_flags.FeatureFlags`.
+
+```mermaid
+flowchart TD
+    A(["evaluate(flag, company_id)"]) --> B{TTL cache hit?}
+
+    B -- yes --> C([return value, reason=cached])
+
+    B -- no --> D[fetch from\nconfiguration-backend GraphQL]
+    D -- 200 OK --> E[store in TTL cache\n+ stale cache]
+    E --> F([return value, reason=remote])
+
+    D -- 5xx --> G[retry once]
+    G -- 200 OK --> E
+    G -- 5xx again --> L[⚠ log.warning\nfetch failed — trying stale cache]
+
+    D -- timeout / network error --> L
+    L --> H{stale cache hit?}
+
+    H -- yes --> M[⚠ log.warning\nstale cache hit]
+    M --> I([return stale value, reason=stale])
+
+    H -- no --> N[⚠ log.warning\nno stale value — env var fallback]
+    N --> J[read env var\nbool or company-ID allowlist]
+    J --> K([return env value, reason=fallback])
+
+    style C fill:#22c55e,color:#fff
+    style F fill:#22c55e,color:#fff
+    style I fill:#f59e0b,color:#fff
+    style K fill:#ef4444,color:#fff
+    style L fill:#fef9c3,color:#713f12
+    style M fill:#fef9c3,color:#713f12
+    style N fill:#fef9c3,color:#713f12
+```
+
+---
+
+## `FlagEvaluation.reason` values
+
+| Value | Meaning |
+|---|---|
+| `"remote"` | Value was freshly fetched from configuration-backend. |
+| `"cached"` | Value was returned from the in-process TTL cache. |
+| `"stale"` | Transport error; last-known-good value for this company returned. |
+| `"fallback"` | No prior value available; env-var default used. |
+
+---
+
+## Adopting in another Python service
+
+1. Install `unique-toolkit` (cachetools is a core dep, no extra group needed): `uv add unique-toolkit`
+2. Set env vars: `CONFIGURATION_BACKEND_URL`, `FEATURE_FLAG_SERVICE_ID`
+3. Add the service ID to configuration-backend's `Service` enum (`tyk-auth`)
+   and to the `@AllowAccess` whitelist on the `evaluateFlag` resolver.
+4. Register any new flag keys in `feature-flag.registry.ts`.
+5. Define flag name constants in your service (see convention above).
+6. Replace `os.getenv("FEATURE_FLAG_*", "false")` call sites with
+   `await client.is_enabled("FEATURE_FLAG_*", company_id=..., user_id=...)`.

unique_toolkit/experimental/resources/feature_flags/__init__.py

@@ -0,0 +1,43 @@
+"""Feature flag client backed by configuration-backend's GraphQL API.
+
+Evaluates flags remotely with a 5 s TTL cache, stale-value fallback on
+transport errors, and env-var fallback when no prior value exists.
+Env-var values support both plain booleans and comma-separated company-ID
+allowlists, consistent with ``unique_toolkit.agentic.feature_flags``.
+
+Required env vars::
+
+    CONFIGURATION_BACKEND_URL=https://<your-configuration-backend>
+    FEATURE_FLAG_SERVICE_ID=your-service-name
+
+Quick start — explicit IDs::
+
+    from unique_toolkit.experimental.resources.feature_flags import FeatureFlagClient
+
+    client = FeatureFlagClient.from_settings()  # singleton; call at startup or first request
+    enabled = await client.is_enabled("FEATURE_FLAG_ENABLE_X", company_id=company_id)
+
+Per-request binding (when you have UniqueSettings / AuthContext)::
+
+    bound = client.bind_settings(settings)      # bind once per request
+    enabled = await bound.is_enabled("FEATURE_FLAG_ENABLE_X")
+
+Define flag name constants in your service to avoid magic strings::
+
+    class MyServiceFlags:
+        ENABLE_X = "FEATURE_FLAG_ENABLE_X"
+        ENABLE_Y = "FEATURE_FLAG_ENABLE_Y"
+
+See README.md for the full evaluation-order diagram and adoption steps.
+"""
+
+from .client import BoundFeatureFlagClient, FeatureFlagClient
+from .schemas import FlagEvaluation
+from .settings import FeatureFlagSettings
+
+__all__ = [
+    "BoundFeatureFlagClient",
+    "FeatureFlagClient",
+    "FlagEvaluation",
+    "FeatureFlagSettings",
+]

unique_toolkit/experimental/resources/feature_flags/_graphql_client.py

@@ -0,0 +1,57 @@
+import httpx
+
+
+async def evaluate_flag(
+    *,
+    http: httpx.AsyncClient,
+    url: str,
+    flag: str,
+    service_id: str,
+    company_id: str,
+    user_id: str | None = None,
+) -> bool:
+    """Call configuration-backend's ``evaluateFlag`` GraphQL query.
+
+    Args:
+        http: Shared HTTP client (caller owns lifecycle).
+        url: Base URL of configuration-backend (no trailing slash).
+        flag: Upper-snake flag key, e.g. ``FEATURE_FLAG_ENABLE_MY_FEATURE``.
+        service_id: Value sent as ``x-service-id`` header.
+        company_id: Value sent as ``x-company-id`` header.
+        user_id: Value sent as ``x-user-id`` header. Omitted when ``None``.
+
+    Returns:
+        The boolean evaluation result from the server.
+
+    Raises:
+        httpx.HTTPError: On transport or HTTP-level errors.
+        RuntimeError: On GraphQL errors or a non-boolean response value.
+    """
+    headers: dict[str, str] = {
+        "x-service-id": service_id,
+        "x-company-id": company_id,
+        "Content-Type": "application/json",
+    }
+    if user_id is not None:
+        headers["x-user-id"] = user_id
+
+    response = await http.post(
+        f"{url}/graphql",
+        json={
+            "query": "query EvaluateFlag($key: String!) { evaluateFlag(key: $key) }",
+            "variables": {"key": flag},
+        },
+        headers=headers,
+    )
+    response.raise_for_status()
+    data = response.json()
+
+    if "errors" in data:
+        raise RuntimeError(f"GraphQL error evaluating '{flag}': {data['errors']}")
+
+    value = data.get("data", {}).get("evaluateFlag")
+    if not isinstance(value, bool):
+        raise RuntimeError(
+            f"evaluateFlag returned unexpected value for '{flag}': {value!r}"
+        )
+    return value

unique_toolkit/experimental/resources/feature_flags/_ttl_cache.py

@@ -0,0 +1,65 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from cachetools import LRUCache, TTLCache
+
+# Sentinel for distinguishing a stored False/None from a missing key.
+# Never stored as a value; only used as the default in .get() calls.
+_MISSING = object()
+
+
+class AsyncTTLCache:
+    """Per-key async TTL cache with stampede protection.
+
+    Uses a per-key asyncio.Lock to ensure only one coroutine fetches a
+    value on a cache miss; subsequent waiters reuse the fetched result.
+    Both the value cache and the lock dict are bounded by ``maxsize``.
+
+    Keys may be any hashable — strings, tuples, etc.
+    """
+
+    def __init__(self, *, maxsize: int = 1024, ttl_ms: float = 5_000) -> None:
+        self._cache: TTLCache[Any, Any] = TTLCache(maxsize=maxsize, ttl=ttl_ms / 1000)
+        self._stale: LRUCache[Any, Any] = LRUCache(maxsize=maxsize)
+        self._locks: LRUCache[Any, asyncio.Lock] = LRUCache(maxsize=maxsize)
+        self._dict_lock = asyncio.Lock()
+
+    async def _get_key_lock(self, key: Any) -> asyncio.Lock:
+        async with self._dict_lock:
+            lock = self._locks.get(key)
+            if lock is None:
+                lock = asyncio.Lock()
+                self._locks[key] = lock
+            return lock
+
+    async def get_or_fetch(
+        self,
+        key: Any,
+        fetcher: Callable[[], Awaitable[Any]],
+    ) -> tuple[Any, bool]:
+        """Return ``(value, from_cache)``, fetching on a miss with per-key stampede protection."""
+        cached = self._cache.get(key, _MISSING)
+        if cached is not _MISSING:
+            self._stale[key] = cached  # keep stale warm while TTL cache is hot
+            return cached, True
+
+        # Acquire per-key lock; re-check inside in case another waiter already fetched.
+        key_lock = await self._get_key_lock(key)
+        async with key_lock:
+            cached = self._cache.get(key, _MISSING)
+            if cached is not _MISSING:
+                self._stale[key] = cached  # keep stale warm while TTL cache is hot
+                return cached, True
+
+            value = await fetcher()
+            self._cache[key] = value
+            self._stale[key] = value
+            return value, False
+
+    def get_stale(self, key: Any) -> tuple[Any, bool]:
+        """Return ``(value, True)`` if a prior successful fetch exists for *key*, else ``(None, False)``."""
+        value = self._stale.get(key, _MISSING)
+        if value is _MISSING:
+            return None, False
+        return value, True

unique_toolkit/experimental/resources/feature_flags/client.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import logging
+import os
+from typing import ClassVar
+
+import httpx
+from tenacity import retry, retry_if_exception, stop_after_attempt
+
+from unique_toolkit.app.unique_settings import AuthContextProtocol, UniqueSettings
+
+from ._graphql_client import evaluate_flag
+from ._ttl_cache import AsyncTTLCache
+from .schemas import FlagEvaluation
+from .settings import FeatureFlagSettings
+
+logger = logging.getLogger(__name__)
+
+
+class FeatureFlagClient:
+    """Feature flag client backed by configuration-backend's GraphQL API.
+
+    Mirrors the OpenFeature ``evaluate`` / ``isEnabled`` semantics used by the
+    Node.js ``@unique/feature-flags`` package without taking a dependency on
+    the OpenFeature Python SDK.
+
+    Evaluation order:
+    1. Check the in-process TTL cache; return a cached value if present.
+    2. Call configuration-backend's ``evaluateFlag`` GraphQL query (one
+       retry on transient 5xx errors).
+    3. On failure, return the last successfully fetched value (stale cache)
+       if one exists, otherwise fall back to the env-var default.
+
+    The ``flag`` argument must be the upper-snake env-var-style key, e.g.
+    ``FEATURE_FLAG_ENABLE_MY_FEATURE``. This matches both the
+    configuration-backend registry key convention and the existing env-var
+    names, so env-var fallback requires no transformation.
+
+    Example (with UniqueSettings)::
+
+        client = FeatureFlagClient.from_settings()
+        bound  = client.bind_settings(settings)
+        if await bound.is_enabled("FEATURE_FLAG_ENABLE_MY_FEATURE"):
+            ...
+
+    Example (explicit IDs)::
+
+        result = await client.evaluate(
+            "FEATURE_FLAG_ENABLE_MY_FEATURE",
+            company_id="acme",
+            user_id="user-123",
+        )
+    """
+
+    _instance: ClassVar[FeatureFlagClient | None] = None
+
+    def __init__(self, *, url: str, service_id: str, ttl_ms: int = 5_000) -> None:
+        self._url = url
+        self._service_id = service_id
+        self._cache = AsyncTTLCache(ttl_ms=ttl_ms)
+        self._http = httpx.AsyncClient(timeout=httpx.Timeout(2.0, connect=1.0))
+
+    @classmethod
+    def from_settings(cls) -> FeatureFlagClient:
+        """Construct (or return the cached) singleton from environment variables.
+
+        Reads :class:`.FeatureFlagSettings` (``CONFIGURATION_BACKEND_URL``,
+        ``FEATURE_FLAG_SERVICE_ID``, ``FEATURE_FLAG_CACHE_TTL_MS``).
+
+        Raises:
+            ValueError: If ``CONFIGURATION_BACKEND_URL`` or
+                ``FEATURE_FLAG_SERVICE_ID`` are not set.
+        """
+        if cls._instance is not None:
+            return cls._instance
+        s = FeatureFlagSettings()
+        if not s.configuration_backend_url:
+            raise ValueError(
+                "CONFIGURATION_BACKEND_URL is required to use FeatureFlagClient"
+            )
+        if not s.feature_flag_service_id:
+            raise ValueError(
+                "FEATURE_FLAG_SERVICE_ID is required to use FeatureFlagClient"
+            )
+        cls._instance = cls(
+            url=s.configuration_backend_url,
+            service_id=s.feature_flag_service_id,
+            ttl_ms=s.feature_flag_cache_ttl_ms,
+        )
+        return cls._instance
+
+    def bind_settings(self, settings: UniqueSettings) -> BoundFeatureFlagClient:
+        """Return a :class:`BoundFeatureFlagClient` for the request-level auth context."""
+        return BoundFeatureFlagClient(self, settings.authcontext)
+
+    async def evaluate(
+        self,
+        flag: str,
+        *,
+        company_id: str,
+        user_id: str | None = None,
+    ) -> FlagEvaluation:
+        """Evaluate *flag* for the given context."""
+        company_id = company_id.strip()
+        if not company_id:
+            raise ValueError("company_id must be a non-empty string")
+
+        cache_key = (flag, company_id, user_id)
+        try:
+            value, from_cache = await self._cache.get_or_fetch(
+                cache_key,
+                lambda: self._fetch(flag=flag, company_id=company_id, user_id=user_id),
+            )
+            return FlagEvaluation(
+                value=value, reason="cached" if from_cache else "remote"
+            )
+        except Exception:
+            logger.warning(
+                "FeatureFlagClient: fetch failed for '%s' (company=%s) — trying stale cache",
+                flag,
+                company_id,
+                exc_info=True,
+            )
+            stale_value, stale_hit = self._cache.get_stale(cache_key)
+            if stale_hit:
+                logger.warning(
+                    "FeatureFlagClient: stale cache hit for '%s' (company=%s, value=%s)",
+                    flag,
+                    company_id,
+                    stale_value,
+                )
+                return FlagEvaluation(value=stale_value, reason="stale")
+            logger.warning(
+                "FeatureFlagClient: no stale value for '%s' (company=%s) — falling back to env var",
+                flag,
+                company_id,
+            )
+            return FlagEvaluation(
+                value=self._env_fallback(flag, company_id), reason="fallback"
+            )
+
+    async def is_enabled(
+        self,
+        flag: str,
+        *,
+        company_id: str,
+        user_id: str | None = None,
+    ) -> bool:
+        """Return ``True`` if *flag* is enabled for the given context."""
+        return (await self.evaluate(flag, company_id=company_id, user_id=user_id)).value
+
+    @retry(
+        retry=retry_if_exception(
+            lambda exc: (
+                isinstance(exc, httpx.HTTPStatusError)
+                and exc.response.status_code >= 500
+            )
+        ),
+        stop=stop_after_attempt(2),
+        reraise=True,
+    )
+    async def _fetch(
+        self,
+        *,
+        flag: str,
+        company_id: str,
+        user_id: str | None,
+    ) -> bool:
+        return await evaluate_flag(
+            http=self._http,
+            url=self._url,
+            flag=flag,
+            service_id=self._service_id,
+            company_id=company_id,
+            user_id=user_id,
+        )
+
+    @staticmethod
+    def _env_fallback(flag: str, company_id: str | None = None) -> bool:
+        """Read *flag* from env vars using the same semantics as ``FeatureFlag``.
+
+        Supports both plain booleans (``"true"`` / ``"false"``) and
+        comma-separated company-ID allowlists (``"company1,company2"``),
+        consistent with ``unique_toolkit.agentic.feature_flags.FeatureFlags``.
+        """
+        raw = os.getenv(flag, "false").strip()
+        raw_lower = raw.lower()
+        if raw_lower in ("true", "1", "yes"):
+            return True
+        if raw_lower in ("false", "0", "no", ""):
+            return False
+        # Comma-separated company-ID allowlist
+        allowed = {part.strip() for part in raw.split(",") if part.strip()}
+        return company_id in allowed if company_id else False
+
+
+class BoundFeatureFlagClient:
+    """A :class:`FeatureFlagClient` bound to a request-level auth context.
+
+    Obtain via :meth:`FeatureFlagClient.bind_settings` — do not instantiate directly.
+    """
+
+    def __init__(self, client: FeatureFlagClient, auth: AuthContextProtocol) -> None:
+        self._client = client
+        self._auth = auth
+
+    async def evaluate(self, flag: str) -> FlagEvaluation:
+        return await self._client.evaluate(
+            flag,
+            company_id=self._auth.get_confidential_company_id(),
+            user_id=self._auth.get_confidential_user_id(),
+        )
+
+    async def is_enabled(self, flag: str) -> bool:
+        return (await self.evaluate(flag)).value

unique_toolkit/experimental/resources/feature_flags/schemas.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class FlagEvaluation:
+    """Result of a feature flag evaluation.
+
+    ``reason`` indicates how the value was determined:
+    - ``"remote"``   — freshly fetched from configuration-backend.
+    - ``"cached"``   — served from the in-process TTL cache.
+    - ``"stale"``    — transport error; last-known-good value for this flag+company used.
+    - ``"fallback"`` — transport error and no prior value; env-var default used.
+    """
+
+    value: bool
+    reason: Literal["remote", "cached", "stale", "fallback"]

unique_toolkit/experimental/resources/feature_flags/settings.py

@@ -0,0 +1,33 @@
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from unique_toolkit.app.find_env_file import find_env_file
+
+
+class FeatureFlagSettings(BaseSettings):
+    """Env-var settings for :class:`FeatureFlagClient`.
+
+    ``CONFIGURATION_BACKEND_URL`` and ``FEATURE_FLAG_SERVICE_ID`` are required;
+    :meth:`FeatureFlagClient.from_settings` raises ``ValueError`` if either is absent.
+    """
+
+    configuration_backend_url: str | None = None
+    feature_flag_service_id: str | None = None
+    feature_flag_cache_ttl_ms: int = 5_000
+
+    @field_validator(
+        "configuration_backend_url", "feature_flag_service_id", mode="before"
+    )
+    @classmethod
+    def _strip_strings(cls, v: object) -> object:
+        if isinstance(v, str):
+            stripped = v.strip()
+            return stripped if stripped else None
+        return v
+
+    model_config = SettingsConfigDict(
+        extra="ignore",
+        case_sensitive=False,
+        env_file=find_env_file(".env", required=False),
+        env_file_encoding="utf-8",
+    )

unique_toolkit/monitoring/gunicorn.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+
+
+def child_exit(server, worker) -> None:
+    """Gunicorn child_exit hook: clean up dead worker's per-PID metric files.
+
+    Wire this up in gunicorn.conf.py:
+
+        from unique_toolkit.monitoring.gunicorn import child_exit  # noqa: F401
+
+    Gunicorn calls any function named child_exit(server, worker) in the
+    config file whenever a worker process exits. Without this, dead workers'
+    .db files accumulate in PROMETHEUS_MULTIPROC_DIR and inflate aggregated
+    metric values on every future scrape.
+
+    No-ops when PROMETHEUS_MULTIPROC_DIR is not set (single-process mode).
+    """
+    if not os.environ.get("PROMETHEUS_MULTIPROC_DIR"):
+        return
+    from prometheus_client import multiprocess  # pyright: ignore[reportMissingImports]
+
+    multiprocess.mark_process_dead(worker.pid)

unique_toolkit/monitoring/middleware.py

@@ -11,22 +11,23 @@ from prometheus_client import (  # pyright: ignore[reportMissingImports]
 from .registry import REGISTRY
 
 _http_requests_total = Counter(
-    "http_requests_total",
+    "python_http_requests_total",
     "Total HTTP requests",
     ["method", "path", "status_code"],
     registry=REGISTRY,
 )
 _http_request_duration_seconds = Histogram(
-    "http_request_duration_seconds",
+    "python_http_request_duration_seconds",
     "HTTP request duration",
     ["method", "path"],
     registry=REGISTRY,
 )
 _http_requests_in_progress = Gauge(
-    "http_requests_in_progress",
+    "python_http_requests_in_progress",
     "In-flight HTTP requests",
     ["method"],
     registry=REGISTRY,
+    multiprocess_mode="livesum",
 )
 
 _DEFAULT_EXCLUDED_PATHS = frozenset({"/health", "/metrics", "/"})

unique_toolkit/monitoring/registry.py

@@ -2,9 +2,11 @@ from __future__ import annotations
 
 import asyncio
 import functools
+import os
 import time
+import warnings
 from contextlib import contextmanager
-from typing import Any, Callable
+from typing import Any, Callable, Literal
 
 from prometheus_client import (  # pyright: ignore[reportMissingImports]
     CollectorRegistry,
@@ -18,7 +20,36 @@ REGISTRY = CollectorRegistry()
 
 
 def get_metrics() -> bytes:
-    """Returns all registered metrics in Prometheus text format."""
+    """Returns all registered metrics in Prometheus text format.
+
+    In multiprocess mode (PROMETHEUS_MULTIPROC_DIR is set), aggregates
+    per-PID .db files from all Gunicorn workers via MultiProcessCollector.
+    In single-process mode, returns metrics from the in-process REGISTRY.
+
+    NOTE: PROMETHEUS_MULTIPROC_DIR must be set in the shell/entrypoint
+    *before* Python starts. Setting it from Python after prometheus_client
+    has been imported has no effect — metrics will silently bypass per-PID
+    files and this function will emit a warning.
+    """
+    if os.environ.get("PROMETHEUS_MULTIPROC_DIR"):
+        from prometheus_client import (  # pyright: ignore[reportMissingImports]
+            multiprocess,
+            values,
+        )
+
+        if not getattr(values.ValueClass, "_multiprocess", False):
+            warnings.warn(
+                "PROMETHEUS_MULTIPROC_DIR is set but prometheus_client was imported "
+                "before the env var — metrics will silently bypass per-PID files. "
+                "Set PROMETHEUS_MULTIPROC_DIR in the shell/entrypoint before launching Python.",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+        registry = CollectorRegistry()
+        multiprocess.MultiProcessCollector(registry)
+        return generate_latest(registry)
+
     return generate_latest(REGISTRY)
 
 
@@ -43,8 +74,31 @@ class MetricNamespace:
     def counter(self, name: str, description: str, labels: list[str]) -> Counter:
         return Counter(f"{self._prefix}_{name}", description, labels, registry=REGISTRY)
 
-    def gauge(self, name: str, description: str, labels: list[str]) -> Gauge:
-        return Gauge(f"{self._prefix}_{name}", description, labels, registry=REGISTRY)
+    def gauge(
+        self,
+        name: str,
+        description: str,
+        labels: list[str],
+        multiprocess_mode: Literal[
+            "all",
+            "liveall",
+            "min",
+            "livemin",
+            "max",
+            "livemax",
+            "sum",
+            "livesum",
+            "mostrecent",
+            "livemostrecent",
+        ] = "all",
+    ) -> Gauge:
+        return Gauge(
+            f"{self._prefix}_{name}",
+            description,
+            labels,
+            registry=REGISTRY,
+            multiprocess_mode=multiprocess_mode,
+        )
 
 
 @contextmanager

{unique_toolkit-2026.24.0.dev6.dist-info → unique_toolkit-2026.24.0.dev8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.24.0.dev6
+Version: 2026.24.0.dev8
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>
@@ -16,7 +16,7 @@ Requires-Dist: sseclient>=0.0.27,<0.0.28
 Requires-Dist: openai>=1.105.0,<3
 Requires-Dist: platformdirs>=4.0.0,<5
 Requires-Dist: pillow>=12.1.1
-Requires-Dist: unique-sdk>=2026.24.0.dev2,<2026.24.0rc0
+Requires-Dist: unique-sdk>=2026.24.0.dev3,<2026.24.0rc0
 Requires-Dist: jambo>=0.1.2,<0.2
 Requires-Dist: jinja2>=3.1.6,<4
 Requires-Dist: docxtpl>=0.20.1,<0.21
@@ -31,6 +31,7 @@ Requires-Dist: deepdiff>=8.6.1,<9
 Requires-Dist: pypandoc>=1.16.2,<2
 Requires-Dist: tenacity>=9.1.4
 Requires-Dist: pydantic-core>=2.41.5
+Requires-Dist: cachetools>=5.0,<6
 Requires-Dist: fastapi>=0.121.0,<0.122 ; extra == 'fastapi'
 Requires-Dist: starlette>=0.49.1 ; extra == 'fastapi'
 Requires-Dist: uvicorn>=0.37.0,<0.38 ; extra == 'fastapi'

{unique_toolkit-2026.24.0.dev6.dist-info → unique_toolkit-2026.24.0.dev8.dist-info}/RECORD

@@ -276,7 +276,7 @@ unique_toolkit/embedding/functions.py,sha256=OWzY-iPNBjwXgSNNXDmu89Lzu-PAMG3Q7ig
 unique_toolkit/embedding/schemas.py,sha256=1GvKCaSk4jixzVQ2PKq8yDqwGEVY_hWclYtoAr6CC2g,96
 unique_toolkit/embedding/service.py,sha256=SSBIsn7ZyQ_5JtoCMqnP1bDoZzp0S3Lt-ao9YBUt1Bc,5232
 unique_toolkit/embedding/utils.py,sha256=v86lo__bCJbxZBQ3OcLu5SuwT6NbFfWlcq8iyk6BuzQ,279
-unique_toolkit/experimental/README.md,sha256=i8IrrfPqqQfhcBCBZ6_VhK7CY3vQt3g5KzVeHOWMEnI,11105
+unique_toolkit/experimental/README.md,sha256=52uUCehy0ZRoIrTrsvk8k6O_NxSUh9-3dATOzZ7wWjU,11350
 unique_toolkit/experimental/__init__.py,sha256=fhSv-QhH0yxnnGqSwbFhX7Rp3TCG_zBphLHNC5GLBgA,393
 unique_toolkit/experimental/_internal/__init__.py,sha256=wClblbvHTnOCjymmXVoAde1is3AF18iQ46lK6wKObr4,995
 unique_toolkit/experimental/_internal/streaming/__init__.py,sha256=YExuxaOHB96xT1k0FsWiZEo6Ngiyv54GumhCAKW_3aA,942
@@ -331,7 +331,7 @@ unique_toolkit/experimental/integrations/openai/streaming/event_routing/response
 unique_toolkit/experimental/integrations/openai/streaming/event_routing/subscribers/__init__.py,sha256=4wpUt9kzfPzncO9tlKcvOQUzQG5e6kVp5AKZI5grxOk,276
 unique_toolkit/experimental/integrations/openai/streaming/event_routing/subscribers/message_persister.py,sha256=nHh2vQWF6YWurdkijof6UXhTMFzllj_4eSdr8nm9aDI,8016
 unique_toolkit/experimental/integrations/openai/streaming/event_routing/subscribers/progress_log_persister.py,sha256=VCYGZY3WSpI7mvVs2gO89-M0JenakW01BGfBfFkPDrw,3499
-unique_toolkit/experimental/resources/__init__.py,sha256=f0l77ZKwyMuG1JfWxb8r8PyRJVn6paWu4tobGcHlqlI,3167
+unique_toolkit/experimental/resources/__init__.py,sha256=KdMPaaneY0twZ-JBfwImRjXZaWT68NVuOIeqdNXFh_Y,3377
 unique_toolkit/experimental/resources/content_folder/__init__.py,sha256=c5MUj1xIP10L7tcM4-hG2m1_yUMVfKr_jHAncUXVNvo,2492
 unique_toolkit/experimental/resources/content_folder/functions.py,sha256=nJle9Qnh-x1SLNetBBhTbQPu-zEBfQaHFnMq8N9RGEQ,16692
 unique_toolkit/experimental/resources/content_folder/schemas.py,sha256=LYWRpMLFVg_iKT9dw2AyCNfTPVmKeB8erMSsgbIkZ48,5345
@@ -339,6 +339,13 @@ unique_toolkit/experimental/resources/content_folder/service.py,sha256=tSNVJ681c
 unique_toolkit/experimental/resources/facades/__init__.py,sha256=imKXMz2nsQcg5zmG-Yq5aQJTMAgpJ3-cXW3L1WfP280,1421
 unique_toolkit/experimental/resources/facades/identity/__init__.py,sha256=7r-1_gr81Idc6AJ1IRO6GCHx7psmC81BtD15BWxrlYs,1640
 unique_toolkit/experimental/resources/facades/identity/service.py,sha256=A5I7QkNy-Su9FmOkrl8z1iwWhqzoo6KgxEgcdvnWN2M,4287
+unique_toolkit/experimental/resources/feature_flags/README.md,sha256=ChPgYn4-SzY1UyF3OQgBxHzMk6JH_hVKfzHsTcKhcXo,6122
+unique_toolkit/experimental/resources/feature_flags/__init__.py,sha256=eGU17swqiJdIqGC-HIGHjGk8rZFpc84IeTFFYkbZxpA,1510
+unique_toolkit/experimental/resources/feature_flags/_graphql_client.py,sha256=a0KxF0EJk7baYChVKFy8bllIJShHKELyQReFd_B9bXs,1743
+unique_toolkit/experimental/resources/feature_flags/_ttl_cache.py,sha256=lPEdWX1JkP2985M1AqQ0uYyWGlagXB0LvOtQPltbgJo,2520
+unique_toolkit/experimental/resources/feature_flags/client.py,sha256=DicPHPpdckzQsHh2Xe5UMUWqdkqM0zZBKR1grB0_bHg,7600
+unique_toolkit/experimental/resources/feature_flags/schemas.py,sha256=chLsBNkIL4BOvGrwrGeixy7BmNSi2BagXD6Jr2fZcqs,602
+unique_toolkit/experimental/resources/feature_flags/settings.py,sha256=3L_c-0zxj4cpuHd3NL3mZ2kN35V6npgh6_hSwu6Gk00,1071
 unique_toolkit/experimental/resources/group/__init__.py,sha256=qPi2DWgWLZw1ku0zi-UsPdornfl8pczW6QSYT5P8CzQ,2098
 unique_toolkit/experimental/resources/group/functions.py,sha256=DrrafmR_6nfGZ1ThnqDxK7PP0zyAAo0uXKgp_mcIf-Q,7990
 unique_toolkit/experimental/resources/group/schemas.py,sha256=t6lXLETGDBGzC9ROKDngQ6mg0KRf5XDTKj0j2uj2b60,3179
@@ -376,8 +383,9 @@ unique_toolkit/language_model/settings.py,sha256=xkoMv3ATb2ft5V3MA8JvqW-EO8AnZ5t
 unique_toolkit/language_model/stream_transform.py,sha256=iNNGpLY_7G6Bpp9Y4KtbIkQm3WB4yZt75BXcqx0DVkI,2775
 unique_toolkit/language_model/utils.py,sha256=bPQ4l6_YO71w-zaIPanUUmtbXC1_hCvLK0tAFc3VCRc,1902
 unique_toolkit/monitoring/__init__.py,sha256=z1gkOCLxGcg936MFuLSeWFa0tREcBFSUbV09NxilBw4,1065
-unique_toolkit/monitoring/middleware.py,sha256=QSOcRwaByN4t6gWY5-IUgW2JXoN7Yl-0JR5kSmOjxM8,2877
-unique_toolkit/monitoring/registry.py,sha256=8VG1NkfzrDiMfPr7KsX7uWEJBK3rNSRWOB8HNQ5B9jY,3333
+unique_toolkit/monitoring/gunicorn.py,sha256=urTFFS5zYHKoxb1TEQHcLqb2byi-aYgFRHGwgYRzYYI,844
+unique_toolkit/monitoring/middleware.py,sha256=JNh5v_INAkexuLtXhCG9n5n2t6Pnf8ZdPTnimAVS0_s,2931
+unique_toolkit/monitoring/registry.py,sha256=8r9jqaQoRHZveGRZe_GQvBzvQpmUV4cpw8Ej1ssDIdE,5056
 unique_toolkit/protocols/support.py,sha256=x5edzbBmKAUuvm3oLFh52gkgQsqR5LU7M0t8RHK0DZk,5161
 unique_toolkit/services/__init__.py,sha256=b9Wl7Wvz1JmZDbDexIZzBoXZ0wscXuczGAH8LoL-Qak,572
 unique_toolkit/services/chat_service.py,sha256=FPY-GTFAkD0C9pYfPfkfAvyIKnL9DX9iDk75gDeghCc,95209
@@ -391,6 +399,6 @@ unique_toolkit/short_term_memory/service.py,sha256=Ncw0_0CNM6kmzJSLVJGG5GcKpBduI
 unique_toolkit/smart_rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 unique_toolkit/smart_rules/compile.py,sha256=vRe0aMJWuVIK-VsqomgxQImzke7MDmwgSxxJfYCa7zw,1386
 unique_toolkit/test_utilities/events.py,sha256=FLrhMh0A_mQutAUjoD0FdMcVQ4Gq31r35OVGzRjvLro,6760
-unique_toolkit-2026.24.0.dev6.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-unique_toolkit-2026.24.0.dev6.dist-info/METADATA,sha256=9iqeteqQZ9CeoDz6t3gI0L0YdK6AnpC376d7cqfdps4,7392
-unique_toolkit-2026.24.0.dev6.dist-info/RECORD,,
+unique_toolkit-2026.24.0.dev8.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+unique_toolkit-2026.24.0.dev8.dist-info/METADATA,sha256=JE05F3xARkbw1R2yqL_Yc-YtzJhIXXjifPc7LLCQz6Q,7426
+unique_toolkit-2026.24.0.dev8.dist-info/RECORD,,