claude-smart 0.2.46 → 0.2.48

package/plugin/vendor/reflexio/reflexio/server/api_endpoints/README.md

@@ -1,5 +1,5 @@
 # server/api_endpoints
-Description: Bridge between FastAPI routes and business logic — builds `RequestContext`, validates requests, and delegates into `Reflexio`. Most endpoints are registered on the `core_router` in `../api.py`; the files here are the handlers/helpers it calls.
+Description: Shared helpers between FastAPI domain routes and business logic — builds `RequestContext`, validates requests, and delegates into `Reflexio`. Public route declarations live in `../routes/` and are aggregated by `core_router` in `../api.py`; the files here are reusable handlers/helpers those routes call.
 
 > For the complete endpoint list (publish, retrieval, search, profile/playbook lifecycle, evaluation, Braintrust, operations), see the parent [server README](../README.md#api-endpoints).
 
@@ -18,8 +18,9 @@ Description: Bridge between FastAPI routes and business logic — builds `Reques
 ## Architecture Pattern
 
 ```
-api.py (core_router + sub-routers)
-  -> Depends(get_request_context) -> RequestContext(org_id, storage, configurator, prompt_manager)
+api.py (create_app + core_router)
+  -> routes/<domain>.py (FastAPI routers)
+    -> Depends(get_request_context) -> RequestContext(org_id, storage, configurator, prompt_manager)
     -> get_reflexio(org_id) -> Reflexio (reflexio_lib) -> services/
 ```
 

package/plugin/vendor/reflexio/reflexio/server/api_endpoints/publisher_api.py

@@ -62,12 +62,22 @@ logger = logging.getLogger(__name__)
 def add_user_interaction(
     org_id: str,
     request: PublishUserInteractionRequest,
+    *,
+    use_publish_limiter: bool = True,
+    publish_limiter_wait_forever: bool = True,
+    defer_learning: bool = False,
 ) -> PublishUserInteractionResponse:
     """Add user interaction
 
     Args:
         org_id (str): Organization ID
         request (PublishUserInteractionRequest): The request containing interaction data
+        use_publish_limiter (bool): Whether GenerationService should throttle the
+            post-write learning pipeline.
+        publish_limiter_wait_forever (bool): Whether GenerationService should queue
+            indefinitely for that post-write learning limiter.
+        defer_learning (bool): Whether to enqueue post-persist learning instead
+            of running it inline.
 
     Returns:
         PublishUserInteractionResponse: Response containing success status and message
@@ -77,7 +87,12 @@ def add_user_interaction(
         return PublishUserInteractionResponse(success=False, message=message)
 
     reflexio = get_reflexio(org_id=org_id)
-    return reflexio.publish_interaction(request=request)
+    return reflexio.publish_interaction(
+        request=request,
+        use_publish_limiter=use_publish_limiter,
+        publish_limiter_wait_forever=publish_limiter_wait_forever,
+        defer_learning=defer_learning,
+    )
 
 
 def add_user_playbook(

package/plugin/vendor/reflexio/reflexio/server/api_endpoints/request_context.py

@@ -1,6 +1,6 @@
 from fastapi import Depends
 
-from reflexio.server._auth import default_get_org_id
+from reflexio.server.auth import default_get_org_id
 from reflexio.server.prompt.prompt_manager import PromptManager
 from reflexio.server.services.configurator.base_configurator import BaseConfigurator
 from reflexio.server.services.configurator.configurator import get_configurator_class

package/plugin/vendor/reflexio/reflexio/server/{_auth.py → auth.py}

@@ -5,6 +5,8 @@ Lives in its own module to avoid an import cycle: api endpoints reference
 :func:`default_get_org_id` (e.g. via FastAPI ``Depends``) and are themselves
 imported by :mod:`reflexio.server.api`. Putting the dependency here keeps the
 import graph acyclic.
+
+Public module path: :mod:`reflexio.server.auth`.
 """
 
 from __future__ import annotations

package/plugin/vendor/reflexio/reflexio/server/cache/reflexio_cache.py

@@ -65,6 +65,17 @@ _reflexio_cache: TTLCache = TTLCache(
     maxsize=REFLEXIO_CACHE_MAX_SIZE, ttl=REFLEXIO_CACHE_TTL_SECONDS
 )
 _reflexio_cache_lock = threading.Lock()
+_REFLEXIO_CONSTRUCTION_LOCK_STRIPES = 64
+_reflexio_construction_locks = tuple(
+    threading.Lock() for _ in range(_REFLEXIO_CONSTRUCTION_LOCK_STRIPES)
+)
+
+
+def _get_construction_lock(cache_key: CacheKey) -> threading.Lock:
+    """Return a bounded striped lock for cold Reflexio construction."""
+    return _reflexio_construction_locks[
+        hash(cache_key) % _REFLEXIO_CONSTRUCTION_LOCK_STRIPES
+    ]
 
 
 def _probe_version_safe(reflexio: Reflexio) -> _ProbeResult:
@@ -157,45 +168,60 @@ def get_reflexio(org_id: str, storage_base_dir: str | None = None) -> Reflexio:
                     del _reflexio_cache[cache_key]
             span.set_data("evicted", evicted)
 
-    # Cache miss (or just-evicted stale entry) - create a new instance
-    # outside the lock to avoid blocking concurrent requests for other orgs.
-    with profile_step("reflexio.cache.construct"):
-        reflexio = Reflexio(org_id=org_id, storage_base_dir=storage_base_dir)
-    with profile_step("reflexio.cache.version_probe", cache_state="miss") as span:
-        new_version = _probe_version_safe(reflexio)
-        span.set_data("probe_failed", new_version is _PROBE_FAILED)
-        span.set_data(
-            "probe_supported",
-            new_version is not None and new_version is not _PROBE_FAILED,
+    # Cache miss (or just-evicted stale entry). Only one request per cache
+    # key may construct at a time; construction can initialize storage and
+    # run migrations, so parallel cold starts for the same org are not safe.
+    construction_lock = _get_construction_lock(cache_key)
+    with construction_lock:
+        with _reflexio_cache_lock:
+            entry = _reflexio_cache.get(cache_key)
+        if entry is not None:
+            return entry.reflexio
+
+        logger.info(
+            "Constructing Reflexio instance for org %s storage_base_dir=%s",
+            org_id,
+            storage_base_dir,
         )
+        with profile_step("reflexio.cache.construct"):
+            reflexio = Reflexio(org_id=org_id, storage_base_dir=storage_base_dir)
+        with profile_step("reflexio.cache.version_probe", cache_state="miss") as span:
+            new_version = _probe_version_safe(reflexio)
+            span.set_data("probe_failed", new_version is _PROBE_FAILED)
+            span.set_data(
+                "probe_supported",
+                new_version is not None and new_version is not _PROBE_FAILED,
+            )
 
-    # Construction-time probe failure: serve this request from the
-    # newly-built instance but DON'T cache it. Caching with
-    # ``cached_version=None`` would conflate the entry with a
-    # legitimately-unprobeable backend and permanently disable
-    # auto-eviction. Skipping the cache means the next request pays a
-    # construction cost, but version-based eviction is preserved as
-    # soon as the backend recovers.
-    if new_version is _PROBE_FAILED:
-        return reflexio
-
-    new_entry = _CacheEntry(
-        reflexio=reflexio,
-        cached_version=new_version,  # type: ignore[arg-type]
-    )
-
-    with profile_step("reflexio.cache.store") as span:
-        with _reflexio_cache_lock:
-            # Double-check in case another thread populated while we were constructing.
-            existing = _reflexio_cache.get(cache_key)
-            stored = existing is None
-            if stored:
+        # Construction-time probe failure: serve this request from the
+        # newly-built instance but DON'T cache it. Caching with
+        # ``cached_version=None`` would conflate the entry with a
+        # legitimately-unprobeable backend and permanently disable
+        # auto-eviction. Skipping the cache means the next request pays a
+        # construction cost, but version-based eviction is preserved as
+        # soon as the backend recovers.
+        if new_version is _PROBE_FAILED:
+            logger.warning(
+                "Constructed uncached Reflexio instance for org %s because config version probe failed",
+                org_id,
+            )
+            return reflexio
+
+        new_entry = _CacheEntry(
+            reflexio=reflexio,
+            cached_version=new_version,  # type: ignore[arg-type]
+        )
+
+        with profile_step("reflexio.cache.store") as span:
+            with _reflexio_cache_lock:
                 _reflexio_cache[cache_key] = new_entry
-                result = reflexio
-            else:
-                result = existing.reflexio
-        span.set_data("stored", stored)
-        return result
+            span.set_data("stored", True)
+            logger.info(
+                "Stored Reflexio instance for org %s storage_base_dir=%s",
+                org_id,
+                storage_base_dir,
+            )
+            return reflexio
 
 
 def invalidate_reflexio_cache(org_id: str, storage_base_dir: str | None = None) -> bool:

package/plugin/vendor/reflexio/reflexio/server/deployment_profile.py

@@ -0,0 +1,69 @@
+"""Declarative deployment profile (Tier-3 Phase C).
+
+A ``DeploymentProfile`` is a minimal, frozen description of *what a running app
+serves*: its deployment ``role``, the set of ``router_groups`` it mounts, and
+whether auth is required. It is a cleaner internal representation of the knobs
+``create_app`` already accepts (``mount_data_plane`` / ``require_auth``) — the
+profile changes nothing observable; it just gives the composition root a single
+value to thread instead of scattered booleans.
+
+This module is an OSS public seam: it imports nothing from ``reflexio_ext`` and
+carries no enterprise backend knowledge (string/stdlib only). The enterprise
+composition defines its own profiles (self-host / platform) on top of this type.
+
+``mounts_data_plane`` is DERIVED from ``router_groups`` (membership of the
+``DATA_PLANE_GROUP``), not stored — so the two can never disagree.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# The single OSS router group: the data-plane surface (core product endpoints,
+# stall-state, pending-tool-call) that ``create_app`` mounts when data-plane is
+# active. Enterprise adds its own group names on top of this type.
+DATA_PLANE_GROUP = "data-plane"
+
+
+@dataclass(frozen=True)
+class DeploymentProfile:
+    """What a running app serves: role, mounted router groups, auth requirement.
+
+    Attributes:
+        role (str): Deployment role label (e.g. ``"all"``, ``"data-plane"``,
+            ``"control-plane"``). Informational for the OSS factory; enterprise
+            uses it to select its router set.
+        router_groups (frozenset[str]): Router-group names this app mounts.
+        auth_required (bool): Whether the app declares/enforces auth.
+    """
+
+    role: str
+    router_groups: frozenset[str]
+    auth_required: bool
+
+    @property
+    def mounts_data_plane(self) -> bool:
+        """Whether this profile mounts the data-plane router group."""
+        return DATA_PLANE_GROUP in self.router_groups
+
+
+def resolve_profile(*, mount_data_plane: bool, require_auth: bool) -> DeploymentProfile:
+    """Derive the OSS profile from the legacy ``create_app`` knobs.
+
+    Behaviour-preserving: this is the identity mapping from the two booleans
+    ``create_app`` has always accepted onto the profile representation.
+
+    Args:
+        mount_data_plane (bool): Whether the data-plane routers/lifespan run.
+        require_auth (bool): Whether auth (Bearer security scheme) is declared.
+
+    Returns:
+        DeploymentProfile: ``role="all"`` + the data-plane group when
+        ``mount_data_plane`` is True, otherwise ``role="control-plane"`` with no
+        router groups. ``auth_required`` mirrors ``require_auth``.
+    """
+    router_groups = frozenset({DATA_PLANE_GROUP}) if mount_data_plane else frozenset()
+    role = "all" if mount_data_plane else "control-plane"
+    return DeploymentProfile(
+        role=role, router_groups=router_groups, auth_required=require_auth
+    )

package/plugin/vendor/reflexio/reflexio/server/extensions.py

@@ -0,0 +1,213 @@
+"""OSS extension primitives: the process-global capability/service registry.
+
+OSS defines these seams; enterprise registers implementations at its composition
+root. OSS never imports reflexio_ext. The service registry is process-global (a
+module dict), mirroring set_configurator_class/get_configurator_class, so it is
+reachable from every RequestContext construction site — HTTP, library
+(lib/_base.py), and background workers — not just app-scoped ones.
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import ClassVar
+
+from fastapi import APIRouter
+
+from reflexio.server.services.unified_search_service import (
+    RetrievalCaptureHook,
+    configure_retrieval_capture_hook,
+)
+from reflexio.server.tracing import Tracer, configure_tracer
+from reflexio.server.usage_metrics import (
+    UsageEventRecorder,
+    configure_usage_event_recorder,
+)
+
+
+class ServiceKey[T]:
+    """Typed handle into the runtime-service registry.
+
+    Args:
+        name (str): Stable identifier, used in error messages and as the dict key.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"ServiceKey({self.name!r})"
+
+
+_services: dict[str, object] = {}
+
+
+def register_service[T](
+    key: ServiceKey[T], value: T, *, override: bool = False
+) -> None:
+    """Register a runtime-service provider under ``key`` (composition root only).
+
+    Args:
+        key (ServiceKey[T]): The typed key.
+        value (T): The provider/value.
+        override (bool): Allow replacing an existing registration. Default False.
+
+    Raises:
+        RuntimeError: If ``key`` is already registered and ``override`` is False.
+    """
+    if not override and key.name in _services:
+        raise RuntimeError(f"service already registered for key {key.name!r}")
+    _services[key.name] = value
+
+
+def get_service[T](key: ServiceKey[T]) -> T | None:
+    """Return the provider for ``key``, or None if unset (optional providers)."""
+    return _services.get(key.name)  # type: ignore[return-value]
+
+
+def require_service[T](key: ServiceKey[T]) -> T:
+    """Return the provider for ``key``, raising if unset (required providers).
+
+    Args:
+        key (ServiceKey[T]): The typed key whose provider to retrieve.
+
+    Returns:
+        T: The registered provider value.
+
+    Raises:
+        LookupError: If no provider is registered for ``key``.
+    """
+    if key.name not in _services:
+        raise LookupError(f"required service not registered for key {key.name!r}")
+    return _services[key.name]  # type: ignore[return-value]
+
+
+def reset_services() -> None:
+    """Clear all registered services. Test-only."""
+    _services.clear()
+
+
+# ---------------------------------------------------------------------------
+# Hook registry, app context, and capability lifecycle primitives
+# ---------------------------------------------------------------------------
+
+
+class HookRegistry:
+    """Facade over OSS process-global hook setters; capabilities install through it."""
+
+    def set_tracer(self, tracer: Tracer | None) -> None:
+        """Install (or clear) the process-global request tracer.
+
+        Args:
+            tracer (Tracer | None): Tracer implementation, or None to disable.
+        """
+        configure_tracer(tracer)
+
+    def set_usage_recorder(self, recorder: UsageEventRecorder | None) -> None:
+        """Install (or clear) the process-global usage-event recorder.
+
+        Args:
+            recorder (UsageEventRecorder | None): Recorder callable, or None to disable.
+        """
+        configure_usage_event_recorder(recorder)
+
+    def set_retrieval_capture(self, hook: RetrievalCaptureHook | None) -> None:
+        """Install (or clear) the process-global retrieval-capture hook.
+
+        Args:
+            hook (RetrievalCaptureHook | None): Hook callable, or None to disable.
+        """
+        configure_retrieval_capture_hook(hook)
+
+
+@dataclass(frozen=True)
+class AppContext:
+    """Inter-step startup data passed to Capability.on_startup.
+
+    Mirrors the values that thread through reflexio_ext lifespan locals
+    (prepare_enterprise_startup output).
+
+    Attributes:
+        self_host_org_id (str | None): Org ID for self-hosted deployments, or None for platform.
+        activated (bool): Whether the enterprise activation check passed.
+    """
+
+    self_host_org_id: str | None = None
+    activated: bool = False
+
+
+class Capability(ABC):
+    """An enterprise feature plugged into the app at its composition root.
+
+    All methods are no-op defaults so the registry can drive every capability
+    through the same phases without hasattr checks. The provider owns this
+    lifecycle shape (ABC); runtime-feature *contracts* are Protocols defined by OSS.
+    """
+
+    name: ClassVar[str]
+
+    def install_services(self) -> None:  # noqa: B027
+        """Register runtime-service providers (process-global). Default: none."""
+
+    def install_hooks(self, hooks: HookRegistry) -> None:  # noqa: B027
+        """Install pipeline hooks (tracer/usage-recorder/retrieval-capture). Default: none.
+
+        Args:
+            hooks (HookRegistry): Registry to install hooks through.
+        """
+
+    def routers(self, role: str) -> list[APIRouter]:  # noqa: ARG002
+        """Return routers to mount for this deployment role. Default: none.
+
+        Args:
+            role (str): Deployment role (e.g. "all", "data-plane").
+
+        Returns:
+            list[APIRouter]: Routers to mount; empty list by default.
+        """
+        return []
+
+    async def on_startup(self, ctx: AppContext) -> None:  # noqa: B027
+        """Start daemons/schedulers. Raising aborts boot (fail-loud). Default: none.
+
+        Args:
+            ctx (AppContext): Startup context produced by prepare_enterprise_startup.
+        """
+
+    async def on_shutdown(self) -> None:  # noqa: B027
+        """Stop what on_startup started. Default: none."""
+
+
+class CapabilityRegistry:
+    """Holds additive capabilities plus the two singular construction-time concerns.
+
+    Args:
+        capabilities (list[Capability]): Capability instances; names must be unique.
+        configurator_class (type | None): Single configurator class, or None.
+        billing_gate (Callable | None): Billing gate factory, or None.
+        role (str | None): Deployment role to thread into ``_wire_capabilities``
+            (e.g. ``"all"``, ``"data-plane"``). When ``None``, ``create_app``
+            derives the role from ``mount_data_plane``.
+
+    Raises:
+        RuntimeError: If two capabilities share the same name.
+    """
+
+    def __init__(
+        self,
+        capabilities: list[Capability],
+        *,
+        configurator_class: type | None = None,
+        billing_gate: Callable[[str], Callable[..., None]] | None = None,
+        role: str | None = None,
+    ) -> None:
+        names = [c.name for c in capabilities]
+        dupes = {n for n in names if names.count(n) > 1}
+        if dupes:
+            raise RuntimeError(f"duplicate capability names: {sorted(dupes)}")
+        self.capabilities = capabilities
+        self.configurator_class = configurator_class
+        self.billing_gate = billing_gate
+        self.role = role