claude-smart 0.2.47 → 0.2.49

package/plugin/vendor/reflexio/reflexio/server/services/generation_service.py

@@ -10,6 +10,7 @@ import uuid
 from collections.abc import Callable
 from concurrent.futures import ThreadPoolExecutor
 from concurrent.futures import TimeoutError as FuturesTimeoutError
+from contextlib import nullcontext
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
@@ -21,7 +22,9 @@ from reflexio.models.api_schema.service_schemas import (
 )
 from reflexio.models.config_schema import Config
 from reflexio.server.api_endpoints.request_context import RequestContext
+from reflexio.server.env_utils import env_str, env_truthy
 from reflexio.server.llm.litellm_client import LiteLLMClient
+from reflexio.server.operation_limiter import operation_limit
 from reflexio.server.services.agent_success_evaluation.runner import (
     run_group_evaluation,
 )
@@ -140,7 +143,12 @@ class GenerationService:
     # ===============================
 
     def run(
-        self, publish_user_interaction_request: PublishUserInteractionRequest
+        self,
+        publish_user_interaction_request: PublishUserInteractionRequest,
+        *,
+        use_publish_limiter: bool = True,
+        publish_limiter_wait_forever: bool = True,
+        defer_learning: bool = False,
     ) -> GenerationServiceResult:
         """
         Process a user interaction request by storing interactions and triggering generation services.
@@ -156,6 +164,14 @@ class GenerationService:
 
         Args:
             publish_user_interaction_request: The incoming user interaction request
+            use_publish_limiter: Whether this service should throttle the post-write
+                learning pipeline. Server sync calls acquire the bounded API
+                limiter before invoking this service, so they disable the inner
+                limiter to avoid waiting after storage side effects.
+            publish_limiter_wait_forever: Whether to queue indefinitely for the
+                post-write learning limiter when ``use_publish_limiter`` is true.
+            defer_learning: Whether to persist the publish and enqueue learning
+                for a process-local worker instead of running it inline.
 
         Returns:
             GenerationServiceResult: The request_id assigned to this publish call
@@ -234,17 +250,32 @@ class GenerationService:
                 session_id=publish_user_interaction_request.session_id,
                 evaluation_only=publish_user_interaction_request.evaluation_only,
             )
-            self.storage.add_request(new_request)  # type: ignore[reportOptionalMemberAccess]
 
-            # Add interactions to storage (bulk insert with batched embedding generation)
-            self.storage.add_user_interactions_bulk(  # type: ignore[reportOptionalMemberAccess]
-                user_id=user_id, interactions=new_interactions
+            # When the durable queue is enabled and this is a deferred publish, the
+            # request + interactions + job row are written together inside a single
+            # commit_scope (below).  Every other path persists here unconditionally.
+            use_durable_queue = env_truthy(
+                env_str("REFLEXIO_DURABLE_LEARNING_QUEUE", "false")
             )
+            _durable_defer = defer_learning and use_durable_queue
+
+            if not _durable_defer:
+                self.storage.add_request(new_request)  # type: ignore[reportOptionalMemberAccess]
+                # Add interactions to storage (bulk insert with batched embedding generation)
+                self.storage.add_user_interactions_bulk(  # type: ignore[reportOptionalMemberAccess]
+                    user_id=user_id, interactions=new_interactions
+                )
 
             # Extract source (empty string treated as None)
             source = publish_user_interaction_request.source or None
 
             if publish_user_interaction_request.evaluation_only:
+                if _durable_defer:
+                    # evaluation_only returns early; ensure data lands even on durable path.
+                    self.storage.add_request(new_request)  # type: ignore[reportOptionalMemberAccess]
+                    self.storage.add_user_interactions_bulk(  # type: ignore[reportOptionalMemberAccess]
+                        user_id=user_id, interactions=new_interactions
+                    )
                 self._schedule_group_evaluation_if_needed(
                     new_request=new_request,
                     user_id=user_id,
@@ -275,6 +306,12 @@ class GenerationService:
                 not publish_user_interaction_request.override_learning_stall
                 and (stall_warning := self._active_learning_stall_warning()) is not None
             ):
+                if _durable_defer:
+                    # Stall skips learning but data must still land.
+                    self.storage.add_request(new_request)  # type: ignore[reportOptionalMemberAccess]
+                    self.storage.add_user_interactions_bulk(  # type: ignore[reportOptionalMemberAccess]
+                        user_id=user_id, interactions=new_interactions
+                    )
                 result.warnings.append(stall_warning)
                 logger.warning("%s; skipping automatic extraction", stall_warning)
                 record_usage_event(
@@ -293,51 +330,295 @@ class GenerationService:
                 )
                 return result
 
-            # Reflection runs as its own sliding-window step BEFORE the
-            # extractor pool spins up, so any replacements it makes are
-            # visible to the extractors when they retrieve existing
-            # profile/playbook context. Wrapped in a broad except so a
-            # reflection bug never breaks the publish.
-            self._maybe_run_reflection(
-                user_id=user_id,
-                request_id=request_id,
-                agent_version=agent_version,
-                source=source,
-            )
+            if defer_learning:
+                if _durable_defer:
+                    # Durable atomic path: pre-generate embeddings OUTSIDE the
+                    # transaction (network call), then persist request + interactions
+                    # + job in one commit_scope.
+                    self.storage.prepare_interaction_embeddings(new_interactions)  # type: ignore[reportOptionalMemberAccess]
+                    covers_through = max(i.created_at for i in new_interactions)
+                    with self.storage.commit_scope():  # type: ignore[reportOptionalMemberAccess]
+                        self.storage.add_request(new_request)  # type: ignore[reportOptionalMemberAccess]
+                        self.storage.add_user_interactions_bulk(  # type: ignore[reportOptionalMemberAccess]
+                            user_id=user_id,
+                            interactions=new_interactions,
+                            embeddings_prepared=True,
+                        )
+                        self.storage.enqueue_learning_job(  # type: ignore[reportOptionalMemberAccess]
+                            org_id=self.org_id,
+                            user_id=user_id,
+                            request_id=request_id,
+                            covers_through=covers_through,
+                            force_extraction=publish_user_interaction_request.force_extraction,
+                            skip_aggregation=publish_user_interaction_request.skip_aggregation,
+                        )
+                    self._schedule_group_evaluation_if_needed(
+                        new_request=new_request,
+                        user_id=user_id,
+                        agent_version=agent_version,
+                        source=source,
+                    )
+                    record_usage_event(
+                        org_id=self.org_id,
+                        user_id=user_id,
+                        request_id=request_id,
+                        session_id=new_request.session_id,
+                        source=source,
+                        agent_version=agent_version,
+                        backend="durable",
+                        event_name="publish_request_succeeded",
+                        event_category="publish",
+                        outcome="success",
+                        count_value=len(new_interactions),
+                        duration_ms=int((time.perf_counter() - publish_start) * 1000),
+                        metadata={
+                            "defer_learning": True,
+                            "durable_queue": True,
+                            "warning_count": len(result.warnings),
+                        },
+                    )
+                    return result
+
+                from reflexio.server.services.publish_learning_worker import (
+                    PublishLearningJob,
+                    enqueue_publish_learning,
+                )
 
-            # Create generation services and requests
-            # Each service writes to separate storage tables and has no dependencies on others
-            profile_generation_service = ProfileGenerationService(
-                llm_client=self.client, request_context=self.request_context
-            )
-            profile_generation_request = ProfileGenerationRequest(
-                user_id=user_id,
-                request_id=request_id,
-                source=source,
-                force_extraction=publish_user_interaction_request.force_extraction,
-            )
+                self._schedule_group_evaluation_if_needed(
+                    new_request=new_request,
+                    user_id=user_id,
+                    agent_version=agent_version,
+                    source=source,
+                )
+                learning_queued = enqueue_publish_learning(
+                    PublishLearningJob(
+                        org_id=self.org_id,
+                        user_id=user_id,
+                        request_id=request_id,
+                        session_id=new_request.session_id,
+                        source=source,
+                        agent_version=agent_version,
+                        force_extraction=publish_user_interaction_request.force_extraction,
+                        skip_aggregation=publish_user_interaction_request.skip_aggregation,
+                    )
+                )
+                record_usage_event(
+                    org_id=self.org_id,
+                    user_id=user_id,
+                    request_id=request_id,
+                    session_id=new_request.session_id,
+                    source=source,
+                    agent_version=agent_version,
+                    backend="classic",
+                    event_name="publish_request_succeeded",
+                    event_category="publish",
+                    outcome="success",
+                    count_value=len(new_interactions),
+                    duration_ms=int((time.perf_counter() - publish_start) * 1000),
+                    metadata={
+                        "defer_learning": True,
+                        "learning_queued": learning_queued,
+                        "warning_count": len(result.warnings),
+                    },
+                )
+                return result
 
-            playbook_generation_service = PlaybookGenerationService(
-                llm_client=self.client,
-                request_context=self.request_context,
-                skip_aggregation=publish_user_interaction_request.skip_aggregation,
+            # The durable write above must not sit behind the publish limiter:
+            # async API callers have already received success=True. Throttle only
+            # the post-write learning pipeline so a hung LLM cannot silently drop
+            # later acknowledged publishes before they reach storage.
+            learning_limit = (
+                operation_limit(
+                    self.org_id,
+                    "publish",
+                    wait_forever=publish_limiter_wait_forever,
+                )
+                if use_publish_limiter
+                else nullcontext()
             )
-            playbook_generation_request = PlaybookGenerationRequest(
-                request_id=request_id,
-                agent_version=agent_version,
+            with learning_limit:
+                self._run_learning_steps(
+                    user_id=user_id,
+                    request_id=request_id,
+                    agent_version=agent_version,
+                    force_extraction=publish_user_interaction_request.force_extraction,
+                    skip_aggregation=publish_user_interaction_request.skip_aggregation,
+                    source=source,
+                    result=result,
+                )
+
+                # Schedule delayed group evaluation for the required session.
+                self._schedule_group_evaluation_if_needed(
+                    new_request=new_request,
+                    user_id=user_id,
+                    agent_version=agent_version,
+                    source=source,
+                )
+
+                record_usage_event(
+                    org_id=self.org_id,
+                    user_id=user_id,
+                    request_id=request_id,
+                    session_id=new_request.session_id,
+                    source=source,
+                    agent_version=agent_version,
+                    backend="classic",
+                    event_name="publish_request_succeeded",
+                    event_category="publish",
+                    outcome="success",
+                    count_value=len(new_interactions),
+                    duration_ms=int((time.perf_counter() - publish_start) * 1000),
+                    metadata={"warning_count": len(result.warnings)},
+                )
+                return result
+
+        except Exception as e:
+            record_usage_event(
+                org_id=self.org_id,
                 user_id=user_id,
-                source=source,
-                force_extraction=publish_user_interaction_request.force_extraction,
+                request_id=result.request_id,
+                session_id=publish_user_interaction_request.session_id,
+                source=publish_user_interaction_request.source,
+                agent_version=agent_version,
+                event_name="publish_request_failed",
+                event_category="publish",
+                outcome="failed",
+                duration_ms=int((time.perf_counter() - publish_start) * 1000),
+                error_kind=type(e).__name__,
             )
+            with sentry_tags(
+                subsystem="generation",
+                op="refresh_profile",
+                org_id=self.org_id,
+                user_id=user_id,
+                request_id=result.request_id,
+                error_type=type(e).__name__,
+            ):
+                logger.exception(
+                    "Failed to refresh user profile for user id: %s",
+                    user_id,
+                )
+            raise
+
+    # ===============================
+    # deferred learning
+    # ===============================
+
+    def run_deferred_learning(
+        self,
+        *,
+        user_id: str,
+        request_id: str,
+        session_id: str | None,  # noqa: ARG002 - kept for worker telemetry symmetry
+        source: str | None,
+        agent_version: str,
+        force_extraction: bool,
+        skip_aggregation: bool,
+        sequential: bool = False,
+    ) -> GenerationServiceResult:
+        """Run the learning steps for a deferred job.
+
+        Args:
+            sequential: When True, run profile and playbook generation on the
+                calling thread (no ThreadPoolExecutor).  Required when the
+                caller already holds the storage commit_scope lock — spawning
+                worker threads inside that scope would deadlock on the RLock.
+        """
+        result = GenerationServiceResult(request_id=request_id)
+        self._run_learning_steps(
+            user_id=user_id,
+            request_id=request_id,
+            agent_version=agent_version,
+            force_extraction=force_extraction,
+            skip_aggregation=skip_aggregation,
+            source=source,
+            result=result,
+            parallel=not sequential,
+        )
+        return result
+
+    # ===============================
+    # private methods
+    # ===============================
 
-            # Run profile and playbook generation services in parallel
-            # Each service creates its own internal ThreadPoolExecutor for extractors
-            # This is safe because we create separate, independent pool instances
-            # Uses manual executor management to avoid blocking on shutdown(wait=True)
-            # when threads are hung on LLM calls
+    def _run_learning_steps(
+        self,
+        *,
+        user_id: str,
+        request_id: str,
+        agent_version: str,
+        force_extraction: bool,
+        skip_aggregation: bool,
+        source: str | None,
+        result: GenerationServiceResult,
+        parallel: bool = True,
+    ) -> None:
+        # Reflection runs as its own sliding-window step BEFORE the extractor
+        # pool spins up, so replacements are visible to extractors.
+        self._maybe_run_reflection(
+            user_id=user_id,
+            request_id=request_id,
+            agent_version=agent_version,
+            source=source,
+        )
+
+        profile_generation_service = ProfileGenerationService(
+            llm_client=self.client, request_context=self.request_context
+        )
+        profile_generation_request = ProfileGenerationRequest(
+            user_id=user_id,
+            request_id=request_id,
+            source=source,
+            force_extraction=force_extraction,
+        )
+
+        playbook_generation_service = PlaybookGenerationService(
+            llm_client=self.client,
+            request_context=self.request_context,
+            skip_aggregation=skip_aggregation,
+        )
+        playbook_generation_request = PlaybookGenerationRequest(
+            request_id=request_id,
+            agent_version=agent_version,
+            user_id=user_id,
+            source=source,
+            force_extraction=force_extraction,
+        )
+
+        if not parallel:
+            # Sequential mode: run both services on the calling thread.
+            # Required when the caller holds a commit_scope lock — spawning
+            # child threads inside that scope would deadlock the SQLite RLock.
+            for svc_name, _run in (
+                (
+                    "profile_generation",
+                    lambda: profile_generation_service.run(profile_generation_request),
+                ),
+                (
+                    "playbook_generation",
+                    lambda: playbook_generation_service.run(
+                        playbook_generation_request
+                    ),
+                ),
+            ):
+                try:
+                    _run()
+                except Exception as e:
+                    msg = f"{svc_name} failed: {e}"
+                    with sentry_tags(
+                        subsystem="generation",
+                        service=svc_name,
+                        request_id=request_id,
+                        error_type=type(e).__name__,
+                    ):
+                        logger.exception(
+                            "Generation service failed for request %s",
+                            request_id,
+                        )
+                    result.warnings.append(msg)
+        else:
             executor = ThreadPoolExecutor(max_workers=2)
             try:
-                # Each thread needs its own context copy — Context.run() is non-reentrant
                 futures = [
                     executor.submit(
                         contextvars.copy_context().run,
@@ -351,14 +632,15 @@ class GenerationService:
                     ),
                 ]
 
-                # Collect results and handle any exceptions
-                # Each service failure is logged but doesn't block others
                 service_names = ["profile_generation", "playbook_generation"]
                 for future, service_name in zip(futures, service_names, strict=True):
                     try:
                         future.result(timeout=GENERATION_SERVICE_TIMEOUT_SECONDS)
                     except FuturesTimeoutError:  # noqa: PERF203
-                        msg = f"{service_name} timed out after {GENERATION_SERVICE_TIMEOUT_SECONDS}s"
+                        msg = (
+                            f"{service_name} timed out after "
+                            f"{GENERATION_SERVICE_TIMEOUT_SECONDS}s"
+                        )
                         with sentry_tags(
                             subsystem="generation",
                             service=service_name,
@@ -383,79 +665,19 @@ class GenerationService:
             finally:
                 executor.shutdown(wait=False, cancel_futures=True)
 
-            # Tagging runs an LLM call per newly generated entity, so defer it off
-            # the publish path. The scheduler debounces bursts and is idempotent
-            # (already-tagged entities are skipped).
-            try:
-                schedule_tagging(
-                    org_id=self.org_id,
-                    user_id=user_id,
-                    agent_version=agent_version,
-                    request_context=self.request_context,
-                    llm_client=self.client,
-                )
-            except Exception:
-                logger.exception(
-                    "Failed to schedule tagging for publish request %s",
-                    request_id,
-                )
-
-            # Schedule delayed group evaluation for the required session.
-            self._schedule_group_evaluation_if_needed(
-                new_request=new_request,
-                user_id=user_id,
-                agent_version=agent_version,
-                source=source,
-            )
-
-            record_usage_event(
+        try:
+            schedule_tagging(
                 org_id=self.org_id,
                 user_id=user_id,
-                request_id=request_id,
-                session_id=new_request.session_id,
-                source=source,
                 agent_version=agent_version,
-                backend="classic",
-                event_name="publish_request_succeeded",
-                event_category="publish",
-                outcome="success",
-                count_value=len(new_interactions),
-                duration_ms=int((time.perf_counter() - publish_start) * 1000),
-                metadata={"warning_count": len(result.warnings)},
+                request_context=self.request_context,
+                llm_client=self.client,
             )
-            return result
-
-        except Exception as e:
-            record_usage_event(
-                org_id=self.org_id,
-                user_id=user_id,
-                request_id=result.request_id,
-                session_id=publish_user_interaction_request.session_id,
-                source=publish_user_interaction_request.source,
-                agent_version=agent_version,
-                event_name="publish_request_failed",
-                event_category="publish",
-                outcome="failed",
-                duration_ms=int((time.perf_counter() - publish_start) * 1000),
-                error_kind=type(e).__name__,
+        except Exception:
+            logger.exception(
+                "Failed to schedule tagging for publish request %s",
+                request_id,
             )
-            with sentry_tags(
-                subsystem="generation",
-                op="refresh_profile",
-                org_id=self.org_id,
-                user_id=user_id,
-                request_id=result.request_id,
-                error_type=type(e).__name__,
-            ):
-                logger.exception(
-                    "Failed to refresh user profile for user id: %s",
-                    user_id,
-                )
-            raise
-
-    # ===============================
-    # private methods
-    # ===============================
 
     def _schedule_group_evaluation_if_needed(
         self,