unique-toolkit 2026.24.0.dev7__tar.gz → 2026.24.0.dev8__tar.gz

{unique_toolkit-2026.24.0.dev7 → unique_toolkit-2026.24.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 2026.24.0.dev7
+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.dev7 → unique_toolkit-2026.24.0.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "2026.24.0.dev7"
+version = "2026.24.0.dev8"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"
@@ -28,7 +28,7 @@ dependencies = [
     "openai>=1.105.0,<3",
     "platformdirs>=4.0.0,<5",
     "pillow>=12.1.1",
-    "unique-sdk>=2026.24.0.dev2,<2026.24.0rc0",
+    "unique-sdk>=2026.24.0.dev3,<2026.24.0rc0",
     "jambo>=0.1.2,<0.2",
     "jinja2>=3.1.6,<4",
     "docxtpl>=0.20.1,<0.21",
@@ -43,6 +43,7 @@ dependencies = [
     "pypandoc>=1.16.2,<2",
     "tenacity>=9.1.4",
     "pydantic-core>=2.41.5",
+    "cachetools>=5.0,<6",
 ]
 
 [project.optional-dependencies]
@@ -60,7 +61,6 @@ fastapi = [
 monitoring = [
     "prometheus_client>=0.24.1,<1",
 ]
-
 [build-system]
 requires = ["uv_build>=0.8.14,<0.9.0"]
 build-backend = "uv_build"
@@ -69,7 +69,9 @@ build-backend = "uv_build"
 module-root = ""
 
 [dependency-groups]
-dev = []
+dev = [
+    "types-cachetools>=5.0,<6",
+]
 
 [tool.uv]
 exclude-newer = "2 weeks"

{unique_toolkit-2026.24.0.dev7 → unique_toolkit-2026.24.0.dev8}/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-2026.24.0.dev7 → unique_toolkit-2026.24.0.dev8}/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-2026.24.0.dev8/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-2026.24.0.dev8/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-2026.24.0.dev8/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-2026.24.0.dev8/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