claude-smart 0.2.47 → 0.2.48

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

@@ -2,46 +2,33 @@
 Base class for generation services
 """
 
-import contextvars
 import logging
-import os
 import re
 import time
 import uuid
 from abc import ABC, abstractmethod
-from concurrent.futures import ThreadPoolExecutor
-from concurrent.futures import TimeoutError as FuturesTimeoutError
 from dataclasses import dataclass
-from datetime import UTC, datetime, timedelta
-from enum import StrEnum
 from typing import Any, Generic, TypeVar
 
 from reflexio.models.api_schema.internal_schema import RequestInteractionDataModel
-from reflexio.models.api_schema.service_schemas import Status
 from reflexio.server.api_endpoints.request_context import RequestContext
 from reflexio.server.llm.litellm_client import LiteLLMClient
 from reflexio.server.llm.token_accounting import RunTokenTotals
-from reflexio.server.services.extraction.outcome import ExtractionOutcome
+from reflexio.server.services.base_generation import (
+    BatchProgressMixin,
+    ConfigFilterMixin,
+    ExtractionRunLifecycleMixin,
+    ShouldRunPrecheckMixin,
+    StatusChangeMixin,
+    UsageBillingMixin,
+)
+from reflexio.server.services.base_generation import (
+    StatusChangeOperation as StatusChangeOperation,  # re-export for back-compat
+)
 from reflexio.server.services.extractor_config_utils import (
-    filter_extractor_configs,
     get_extractor_name,
 )
-from reflexio.server.services.extractor_interaction_utils import (
-    get_effective_source_filter,
-    get_extractor_window_params,
-    should_extractor_run_by_stride,
-)
 from reflexio.server.services.operation_state_utils import OperationStateManager
-from reflexio.server.services.service_utils import log_llm_messages, log_model_response
-from reflexio.server.services.storage.storage_base import AgentRunStatus
-from reflexio.server.usage_metrics import record_usage_event
-
-
-class StatusChangeOperation(StrEnum):
-    """Operation type for upgrade/downgrade responses."""
-
-    UPGRADE = "upgrade"
-    DOWNGRADE = "downgrade"
 
 
 class ExtractorExecutionError(RuntimeError):
@@ -163,6 +150,12 @@ class PreparedGenerationRun(Generic[TExtractorConfig]):  # noqa: UP046
 
 # Unified base class for all generation services (evaluation, playbook, profile)
 class BaseGenerationService(
+    BatchProgressMixin[TRequest],
+    UsageBillingMixin[TExtractorConfig, TGenerationServiceConfig],
+    ExtractionRunLifecycleMixin[TExtractorConfig, TGenerationServiceConfig],
+    ShouldRunPrecheckMixin[TExtractorConfig, TGenerationServiceConfig],
+    ConfigFilterMixin[TExtractorConfig, TGenerationServiceConfig],
+    StatusChangeMixin[TRequest],
     ABC,
     Generic[TExtractorConfig, TExtractor, TGenerationServiceConfig, TRequest],  # noqa: UP046
 ):
@@ -220,187 +213,6 @@ class BaseGenerationService(
         # re-querying storage. None when the gate did not run (bypass paths).
         self._last_precheck_sessions: list[Any] | None = None
 
-    def _usage_pipeline(self) -> str | None:
-        service_name = self._get_service_name()
-        if "profile" in service_name:
-            return "profile"
-        if "playbook" in service_name:
-            return "playbook"
-        if "evaluation" in service_name:
-            return "evaluation"
-        return None
-
-    def _usage_context(self) -> dict[str, Any]:
-        service_config = self.service_config
-        return {
-            "org_id": self.org_id,
-            "user_id": getattr(service_config, "user_id", None),
-            "request_id": getattr(service_config, "request_id", None),
-            "source": getattr(service_config, "source", None),
-            "agent_version": getattr(service_config, "agent_version", None),
-            "pipeline": self._usage_pipeline(),
-        }
-
-    def _record_generation_event(
-        self,
-        *,
-        event_name: str,
-        outcome: str,
-        count_value: int = 1,
-        duration_ms: int | None = None,
-        error_kind: str | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> None:
-        record_usage_event(
-            **self._usage_context(),
-            event_name=event_name,
-            event_category="generation",
-            outcome=outcome,
-            count_value=count_value,
-            duration_ms=duration_ms,
-            error_kind=error_kind,
-            metadata=metadata,
-        )
-
-    def _extraction_input_text(self, prepared: "PreparedGenerationRun[Any]") -> str:
-        """Return the interaction content fed to the extractor as a single string.
-
-        Replays the same storage query the extractor uses (same user_id, source,
-        window params) so ``count_input_tokens`` sees the same text the LLM saw.
-        Returns an empty string when storage is unavailable or no interactions exist.
-
-        Args:
-            prepared: The prepared generation run, used to access extractor_config
-                for window/source parameters.
-
-        Returns:
-            str: Formatted interaction history string, or "" if nothing is found.
-        """
-        from reflexio.server.services.service_utils import (
-            format_sessions_to_history_string,
-        )
-
-        if self.storage is None or self.service_config is None:
-            return ""
-        # Reuse the window the should-run gate already fetched
-        # (_collect_scoped_interactions_for_precheck stashed it). Same query params,
-        # so the token count is byte-identical — and we avoid a second storage read.
-        if self._last_precheck_sessions is not None:
-            return format_sessions_to_history_string(self._last_precheck_sessions)
-        # Fallback storage read: used ONLY when the gate did not pre-fetch
-        # (bypass paths: auto_run=False, force_extraction, skip_should_run_check,
-        # mock mode). Re-fetches the extractor's input window so billing token
-        # counting sees exactly the text the LLM saw.
-        try:
-            root_config = self.request_context.configurator.get_config()
-            global_window_size = (
-                getattr(root_config, "window_size", None) if root_config else None
-            )
-            global_stride_size = (
-                getattr(root_config, "stride_size", None) if root_config else None
-            )
-            window_size, _ = get_extractor_window_params(
-                prepared.extractor_config, global_window_size, global_stride_size
-            )
-            should_skip, effective_source = get_effective_source_filter(
-                prepared.extractor_config, getattr(self.service_config, "source", None)
-            )
-            if should_skip:
-                return ""
-            session_data_models, _ = self.storage.get_last_k_interactions_grouped(
-                user_id=getattr(self.service_config, "user_id", None),
-                k=window_size,
-                sources=effective_source,
-                start_time=getattr(self.service_config, "rerun_start_time", None),
-                end_time=getattr(self.service_config, "rerun_end_time", None),
-                **self._get_precheck_interaction_query_kwargs(),
-            )
-            return format_sessions_to_history_string(session_data_models)
-        except Exception:
-            logger.warning(
-                "_extraction_input_text failed; billing_input_tokens will be 0",
-                exc_info=True,
-            )
-            return ""
-
-    def _record_billing_learning_events(
-        self, *, prepared: "PreparedGenerationRun[Any]", generated_count: int
-    ) -> None:
-        """Emit the ② Learning billing events. Called ONLY when extraction fired.
-
-        Emits ``learnings_generated`` (value facet) and ``extraction_tokens``
-        (cost facet) via the OSS emission helpers. ``platform_storage`` is left
-        ``None`` here and resolved enterprise-side at rollup (Phase 1).
-
-        Gated by ``EMITS_LEARNING_BILLING`` — only profile/playbook generation
-        services opt in. Evaluation, reflection, consolidation and aggregation
-        are bundled and must NOT separately meter the ② Learning line.
-
-        Args:
-            prepared: The prepared generation run (used for input-text computation).
-            generated_count: Number of learnings produced by this extraction run.
-        """
-        if not self.EMITS_LEARNING_BILLING:
-            return
-
-        try:
-            from reflexio.server.billing_meter import (
-                record_extraction_tokens,
-                record_learnings_generated,
-            )
-            from reflexio.server.billing_signals import (
-                count_input_tokens,
-                platform_llm_from_config,
-            )
-
-            config = self.request_context.configurator.get_config()
-            platform_llm = platform_llm_from_config(config)
-            ctx = self._usage_context()
-
-            # session_id is intentionally not passed: the generation path has no
-            # session_id source. _usage_context() never includes it, and neither
-            # the Profile/Playbook service configs nor their requests carry a
-            # session_id (unlike the Application-line path in server/api.py, which
-            # reads request_id/session_id off the search request payload). Learning
-            # events therefore meter without session attribution by design.
-
-            # ② Learning — value: learnings generated (helper no-ops on count <= 0).
-            record_learnings_generated(
-                org_id=ctx["org_id"],
-                count=generated_count,
-                platform_llm=platform_llm,
-                platform_storage=None,
-                pipeline=ctx.get("pipeline"),
-                request_id=ctx.get("request_id"),
-            )
-
-            # ② Learning — cost: input-anchored extraction tokens + real provider tokens.
-            totals = self._last_token_totals or RunTokenTotals()
-            billing_input_tokens = count_input_tokens(
-                self._extraction_input_text(prepared)
-            )
-            record_extraction_tokens(
-                org_id=ctx["org_id"],
-                billing_input_tokens=billing_input_tokens,
-                prompt_tokens=totals.prompt_tokens,
-                completion_tokens=totals.completion_tokens,
-                platform_llm=platform_llm,
-                platform_storage=None,
-                pipeline=ctx.get("pipeline"),
-                request_id=ctx.get("request_id"),
-            )
-        except Exception:
-            logger.warning(
-                "_record_billing_learning_events failed; billing learning events not emitted",
-                exc_info=True,
-            )
-
-    @staticmethod
-    def _count_generated_results(result: Any) -> int:
-        if isinstance(result, list):
-            return len(result)
-        return 1 if result else 0
-
     @abstractmethod
     def _load_extractor_config(self) -> TExtractorConfig | None:
         """
@@ -506,107 +318,6 @@ class BaseGenerationService(
             Optional[str]: Scope ID (e.g., user_id) or None for org-level scope
         """
 
-    def _filter_extractor_config_by_service_config(
-        self,
-        extractor_config: TExtractorConfig,
-        service_config: TGenerationServiceConfig,
-    ) -> TExtractorConfig | None:
-        """
-        Filter the extractor config based on request_sources_enabled and manual_trigger.
-        """
-        filtered = filter_extractor_configs(
-            extractor_configs=[extractor_config],
-            source=getattr(service_config, "source", None),
-            allow_manual_trigger=getattr(service_config, "allow_manual_trigger", False),
-        )
-        return filtered[0] if filtered else None
-
-    def _get_extractor_state_service_name(self) -> str | None:
-        """
-        Get the service name used for extractor state (stride_size bookmark) lookups.
-
-        Override in subclasses that support stride_size-based pre-filtering to return
-        the OperationStateManager service name (e.g., "profile_extractor", "playbook_extractor").
-        Returns None by default, meaning stride_size pre-filtering is skipped.
-
-        Returns:
-            Optional[str]: Service name for OperationStateManager, or None to skip stride_size pre-filtering
-        """
-        return None
-
-    def _filter_config_by_stride(
-        self, extractor_config: TExtractorConfig
-    ) -> TExtractorConfig | None:
-        """
-        Filter extractor config by stride_size check before the should_run LLM call.
-
-        Skips filtering when:
-        - _get_extractor_state_service_name() returns None (service doesn't support stride_size)
-        - auto_run is False (rerun/manual flows skip stride_size)
-
-        Args:
-            extractor_config: Extractor config after source/manual_trigger filtering
-
-        Returns:
-            Extractor config when it passes the stride_size check, otherwise None.
-        """
-        state_service_name = self._get_extractor_state_service_name()
-        if state_service_name is None:
-            return extractor_config
-
-        if not getattr(self.service_config, "auto_run", True):
-            return extractor_config
-
-        if getattr(self.service_config, "force_extraction", False):
-            return extractor_config
-
-        root_config = self.request_context.configurator.get_config()
-        global_window_size = (
-            getattr(root_config, "window_size", None) if root_config else None
-        )
-        global_stride_size = (
-            getattr(root_config, "stride_size", None) if root_config else None
-        )
-
-        state_manager = OperationStateManager(
-            self.storage,  # type: ignore[reportArgumentType]
-            self.org_id,
-            state_service_name,  # type: ignore[reportArgumentType]
-        )
-
-        name = get_extractor_name(extractor_config)
-        _, stride_size = get_extractor_window_params(
-            extractor_config, global_window_size, global_stride_size
-        )
-
-        # Resolve effective source filter for this extractor
-        should_skip, effective_source = get_effective_source_filter(
-            extractor_config, getattr(self.service_config, "source", None)
-        )
-        if should_skip:
-            return None
-
-        (
-            _,
-            new_interactions,
-        ) = state_manager.get_extractor_state_with_new_interactions(
-            extractor_name=name,
-            user_id=getattr(self.service_config, "user_id", None),
-            sources=effective_source,
-        )
-        new_count = sum(len(ri.interactions) for ri in new_interactions)
-
-        if should_extractor_run_by_stride(new_count, stride_size):
-            return extractor_config
-
-        logger.info(
-            "Stride pre-filter: skipping extractor '%s' (new=%d, stride_size=%s)",
-            name,
-            new_count,
-            stride_size,
-        )
-        return None
-
     # ===============================
     # In-progress state management via OperationStateManager
     # ===============================
@@ -949,880 +660,3 @@ class BaseGenerationService(
             extractor_name=extractor_name,
             identifier=identifier,
         )
-
-    def _execute_extractor(
-        self,
-        extractor_config: TExtractorConfig,
-        identifier: str,
-    ) -> Any | None:
-        """
-        Run the configured extractor with timeout and error handling.
-
-        The extractor runs in a thread pool with a timeout guard so providers that
-        ignore their own timeout cannot block generation forever.
-
-        Args:
-            extractor_config: Filtered extractor config to execute
-            identifier: Logging context identifier (user_id or request_id)
-
-        Returns:
-            Extractor result, or None if the extractor succeeded with no output.
-
-        Raises:
-            ExtractorExecutionError: If the extractor fails with an exception or timeout.
-        """
-        if (
-            self.service_config is None
-        ):  # pragma: no cover — set by _prepare_generation_run
-            raise RuntimeError("service_config must be set before executing extractor")
-
-        self._last_extractor_run_stats = {"total": 1, "failed": 0, "timed_out": 0}
-        extractor = self._create_extractor(extractor_config, self.service_config)
-        executor: ThreadPoolExecutor | None = None
-        try:
-            executor = ThreadPoolExecutor(max_workers=1)
-            # Copy context so correlation ID propagates to worker thread
-            ctx = contextvars.copy_context()
-            future = executor.submit(ctx.run, extractor.run)  # type: ignore[reportAttributeAccessIssue]
-            result = future.result(timeout=EXTRACTOR_TIMEOUT_SECONDS)
-            if isinstance(result, ExtractionOutcome):
-                if result.run_id:
-                    self._last_extraction_run_ids.append(result.run_id)
-                self._last_token_totals = result.token_totals
-                if result.status == "completed" and result.items:
-                    return result.items
-                logger.info(
-                    "No results generated for %s identifier: %s",
-                    self._get_service_name(),
-                    identifier,
-                )
-                return None
-            if result:
-                return result
-            logger.info(
-                "No results generated for %s identifier: %s",
-                self._get_service_name(),
-                identifier,
-            )
-            return None
-        except FuturesTimeoutError as exc:
-            self._last_extractor_run_stats = {"total": 1, "failed": 1, "timed_out": 1}
-            error_msg = (
-                f"Extractor timed out after {EXTRACTOR_TIMEOUT_SECONDS} seconds "
-                f"for {self._get_service_name()} identifier={identifier}"
-            )
-            logger.error(error_msg)
-            self._fail_active_extraction_runs(
-                extractor_kind=get_extractor_name(extractor_config),
-                last_error=error_msg,
-            )
-            raise ExtractorExecutionError(error_msg) from exc
-        except Exception as exc:
-            self._last_extractor_run_stats = {"total": 1, "failed": 1, "timed_out": 0}
-            error_msg = (
-                f"Extractor failed for {self._get_service_name()} "
-                f"identifier={identifier}: {exc} (type={type(exc).__name__})"
-            )
-            logger.error(error_msg)
-            raise ExtractorExecutionError(error_msg) from exc
-        finally:
-            if executor is not None:
-                executor.shutdown(wait=False, cancel_futures=True)
-
-    def _fail_active_extraction_runs(
-        self,
-        *,
-        extractor_kind: str,
-        last_error: str,
-    ) -> None:
-        """Mark active agent-run rows failed when the service timeout fires."""
-        if self.storage is None or self.service_config is None:
-            return
-        request_id = getattr(self.service_config, "request_id", None)
-        if not request_id:
-            return
-        user_id = getattr(self.service_config, "user_id", None)
-        try:
-            failed_count = self.storage.fail_running_agent_runs_for_request(
-                org_id=self.request_context.org_id,
-                extractor_kind=extractor_kind,
-                user_id=user_id,
-                request_id=request_id,
-                last_error=last_error,
-            )
-        except NotImplementedError:
-            return
-        except Exception as exc:  # noqa: BLE001 - keep timeout error primary
-            logger.warning(
-                "Failed to mark timed-out %s agent runs failed: %s",
-                extractor_kind,
-                exc,
-            )
-            return
-        if failed_count:
-            logger.warning(
-                "Marked %d timed-out %s agent run(s) failed for request_id=%s",
-                failed_count,
-                extractor_kind,
-                request_id,
-            )
-
-    def _finalize_extraction_runs(self) -> None:
-        if self.storage is None:
-            return
-        for run_id in self._last_extraction_run_ids:
-            run = self.storage.get_agent_run(run_id)
-            if run is None:
-                continue
-            status = (
-                AgentRunStatus.FINALIZED_PENDING_TOOL
-                if run.pending_tool_call_ids
-                else AgentRunStatus.FINALIZED
-            )
-            self.storage.update_agent_run_status(
-                run_id,
-                status,
-                pending_tool_call_ids=run.pending_tool_call_ids,
-            )
-
-    def _mark_extraction_runs_finalization_failed(self, exc: Exception) -> None:
-        if self.storage is None:
-            return
-        root_config = self.request_context.configurator.get_config()
-        pending_config = getattr(root_config, "pending_tool_call_config", None)
-        for run_id in self._last_extraction_run_ids:
-            run = self.storage.get_agent_run(run_id)
-            if run is None or run.committed_output is None:
-                continue
-            next_attempt_count = run.finalization_attempts + 1
-            max_attempts = (
-                pending_config.max_finalization_attempts
-                if pending_config is not None
-                else 3
-            )
-            status = (
-                AgentRunStatus.FAILED
-                if next_attempt_count >= max_attempts
-                else AgentRunStatus.FINALIZATION_FAILED
-            )
-            delay_seconds = min(300, max(1, 2 ** max(0, next_attempt_count - 1)))
-            self.storage.update_agent_run_status(
-                run_id,
-                status,
-                next_resume_at=datetime.now(UTC) + timedelta(seconds=delay_seconds),
-                last_error=str(exc),
-                increment_finalization_attempts=True,
-            )
-
-    def _should_run_before_extraction(self, extractor_config: TExtractorConfig) -> bool:
-        """
-        Pre-extraction check called before extractor execution.
-
-        Template method that:
-        1. Skips for non-auto runs and mock mode
-        2. Returns True immediately when service_config.force_extraction=True
-           (bypasses cheap pre-filter and LLM should_run vote)
-        3. Collects scoped interactions via _collect_scoped_interactions_for_precheck
-        4. Delegates prompt building to _build_should_run_prompt (subclass hook)
-        5. Makes a single LLM call to determine if extraction should proceed
-
-        Override _build_should_run_prompt in subclasses to provide service-specific
-        criteria and prompt construction. Default returns True (always run) when
-        no prompt hook is provided.
-
-        Args:
-            extractor_config: Enabled extractor config that will be run
-
-        Returns:
-            bool: True if extraction should proceed, False to skip
-        """
-        # Skip for non-auto runs (rerun/manual flows always run)
-        if not getattr(self.service_config, "auto_run", True):
-            return True
-
-        # Skip for mock mode
-        if os.getenv("MOCK_LLM_RESPONSE", "").lower() == "true":
-            return True
-
-        # `force_extraction=True` is the caller's explicit "no gates" signal —
-        # corrections, manual /learn, anything time-sensitive. Bypass the
-        # cheap pre-filter (slash-only / too-short rejects) and the LLM
-        # should_run vote so the extractor always runs on this batch.
-        if getattr(self.service_config, "force_extraction", False):
-            return True
-
-        # Skip if org config disables the pre-extraction check
-        root_config = self.request_context.configurator.get_config()
-        if root_config and root_config.skip_should_run_check:
-            logger.info(
-                "skip_should_run_check is enabled for %s, bypassing pre-extraction check",
-                self._get_service_name(),
-            )
-            return True
-
-        # Collect scoped interactions
-        session_data_models, scoped_config = (
-            self._collect_scoped_interactions_for_precheck(extractor_config)
-        )
-        if not session_data_models:
-            logger.info(
-                "No interactions found for consolidated should_generate check for %s",
-                self._get_service_name(),
-            )
-            return False
-
-        # Cheap pre-filter: reject batches that are structurally unable
-        # to yield signal (slash-commands only, too-short user turns,
-        # extractor-prompt echoes) without burning a 5–7s LLM call. See
-        # _cheap_should_run_reject for the rule set.
-        reject_reason = _cheap_should_run_reject(session_data_models)
-        if reject_reason is not None:
-            logger.info(
-                "Cheap pre-filter rejected %s should_run: reason=%s identifier=%s",
-                self._get_service_name(),
-                reject_reason,
-                getattr(self.service_config, "user_id", None) or "unknown",
-            )
-            return False
-
-        # Build prompt via subclass hook
-        prompt = self._build_should_run_prompt(scoped_config, session_data_models)
-        if not prompt:
-            return True  # No prompt means no check needed, proceed
-
-        # Resolve model and make LLM call
-        should_run_model = self._resolve_should_run_model()
-        identifier = getattr(self.service_config, "user_id", None) or "unknown"
-        try:
-            should_start = time.perf_counter()
-            logger.info(
-                "event=consolidated_should_run_start service=%s identifier=%s model=%s extractor=%s",
-                self._get_service_name(),
-                identifier,
-                should_run_model,
-                get_extractor_name(extractor_config),
-            )
-            log_llm_messages(
-                logger,
-                "Should extract check",
-                [{"role": "user", "content": prompt}],
-            )
-
-            content = self.client.generate_chat_response(
-                messages=[{"role": "user", "content": prompt}],
-                model=should_run_model,
-            )
-            log_model_response(
-                logger,
-                f"Consolidated {self._get_service_name()} should_run response",
-                content,
-            )
-            decision = bool(content and "true" in content.lower())  # type: ignore[reportAttributeAccessIssue]
-            logger.info(
-                "event=consolidated_should_run_end service=%s identifier=%s elapsed_seconds=%.3f decision=%s",
-                self._get_service_name(),
-                identifier,
-                time.perf_counter() - should_start,
-                decision,
-            )
-            return decision
-        except Exception as exc:
-            logger.error(
-                "Consolidated should_generate check failed for %s: %s, defaulting to run",
-                self._get_service_name(),
-                str(exc),
-            )
-            return True
-
-    def _build_should_run_prompt(
-        self,
-        scoped_config: TExtractorConfig,  # noqa: ARG002
-        session_data_models: list[RequestInteractionDataModel],  # noqa: ARG002
-    ) -> str | None:
-        """
-        Build the prompt for the consolidated should_run LLM check.
-
-        Override in subclasses to provide service-specific criteria building
-        and prompt rendering. Return None if no check is needed (always proceed).
-
-        Args:
-            scoped_config: Extractor config that had scoped interactions
-            session_data_models: Deduplicated request interaction data models
-
-        Returns:
-            Optional[str]: The rendered prompt string, or None to skip the check
-        """
-        return None
-
-    def _collect_scoped_interactions_for_precheck(
-        self, extractor_config: TExtractorConfig
-    ) -> tuple[list[RequestInteractionDataModel], TExtractorConfig]:
-        """
-        Collect interactions for consolidated pre-check using extractor-scoped filters.
-
-        Mirrors each extractor's source/window scope so the consolidated gate
-        does not skip valid extraction because of an unrelated fixed interaction slice.
-
-        Args:
-            extractor_config: Enabled extractor config after request-level filtering
-
-        Returns:
-            tuple: (session data models, extractor config)
-        """
-        root_config = self.request_context.configurator.get_config()
-        global_window_size = (
-            getattr(root_config, "window_size", None) if root_config else None
-        )
-        global_stride_size = (
-            getattr(root_config, "stride_size", None) if root_config else None
-        )
-
-        extra_kwargs = self._get_precheck_interaction_query_kwargs()
-
-        should_skip, effective_source = get_effective_source_filter(
-            extractor_config, getattr(self.service_config, "source", None)
-        )
-        if should_skip:
-            # Stash for the billing path to reuse (same window the gate saw).
-            self._last_precheck_sessions = []
-            return [], extractor_config
-
-        window_size, _ = get_extractor_window_params(
-            extractor_config, global_window_size, global_stride_size
-        )
-        session_data_models, _ = self.storage.get_last_k_interactions_grouped(  # type: ignore[reportOptionalMemberAccess]
-            user_id=getattr(self.service_config, "user_id", None),
-            k=window_size,
-            sources=effective_source,
-            start_time=getattr(self.service_config, "rerun_start_time", None),
-            end_time=getattr(self.service_config, "rerun_end_time", None),
-            **extra_kwargs,
-        )
-
-        # Stash for the billing path (_extraction_input_text) to reuse instead of
-        # re-querying storage for billing_input_tokens.
-        self._last_precheck_sessions = session_data_models
-        return session_data_models, extractor_config
-
-    def _get_precheck_interaction_query_kwargs(self) -> dict:
-        """
-        Return extra keyword arguments for get_last_k_interactions_grouped in precheck.
-
-        Override in subclasses that need additional query parameters
-        (e.g., agent_version for playbook services).
-
-        Returns:
-            dict: Extra kwargs to pass to get_last_k_interactions_grouped
-        """
-        return {}
-
-    def _resolve_should_run_model(self) -> str:
-        """
-        Resolve the model name for should_run/should_generate LLM checks.
-
-        Uses LLM config override if available, falls back to site var setting.
-
-        Returns:
-            str: Model name for the should_run check
-        """
-        from reflexio.server.llm.model_defaults import ModelRole, resolve_model_name
-        from reflexio.server.site_var.site_var_manager import SiteVarManager
-
-        root_config = self.request_context.configurator.get_config()
-        llm_config = root_config.llm_config if root_config else None
-        api_key_config = root_config.api_key_config if root_config else None
-
-        model_setting = SiteVarManager().get_site_var("llm_model_setting")
-        site_var = model_setting if isinstance(model_setting, dict) else {}
-
-        return resolve_model_name(
-            ModelRole.SHOULD_RUN,
-            site_var_value=site_var.get("should_run_model_name"),
-            config_override=llm_config.should_run_model_name if llm_config else None,
-            api_key_config=api_key_config,
-        )
-
-    # ===============================
-    # Batch with progress (shared by rerun + manual)
-    # ===============================
-
-    def _run_batch_with_progress(
-        self,
-        user_ids: list[str],
-        request: TRequest,
-        request_params: dict,
-        state_manager: OperationStateManager,
-    ) -> tuple[int, int]:
-        """Run a batch of users with progress tracking.
-
-        Shared logic for both run_rerun() and run_manual_regular().
-        Initializes progress, processes each user, and finalizes.
-        Checks for cancellation before each user.
-
-        Args:
-            user_ids: List of user IDs to process
-            request: The original request object
-            request_params: Parameters dict for progress state
-            state_manager: OperationStateManager instance
-
-        Returns:
-            Tuple of (users_processed, total_generated)
-        """
-        total_users = len(user_ids)
-        self._is_batch_mode = True
-
-        # Initialize progress
-        state_manager.initialize_progress(
-            total_users=total_users,
-            request_params=request_params,
-        )
-
-        try:
-            # Process each user
-            users_processed = 0
-            processed_user_ids: list[str] = []
-            for user_id in user_ids:
-                # Check for cancellation before starting next user
-                if state_manager.is_cancellation_requested():
-                    logger.info(
-                        "Cancellation requested for %s, stopping after %d/%d users",
-                        self._get_base_service_name(),
-                        users_processed,
-                        total_users,
-                    )
-                    state_manager.mark_cancelled()
-                    return users_processed, self._get_generated_count(
-                        request, processed_user_ids=processed_user_ids
-                    )
-
-                state_manager.set_current_item(user_id)
-
-                try:
-                    run_request = self._create_run_request_for_item(user_id, request)
-                    self.run(run_request)
-                    users_processed += 1
-                    processed_user_ids.append(user_id)
-
-                    state_manager.update_progress(
-                        item_id=user_id,
-                        count=0,  # Extractors collect their own data
-                        success=True,
-                        total_users=total_users,
-                    )
-
-                except Exception as e:
-                    logger.error(
-                        "Failed to process user %s for %s: %s",
-                        user_id,
-                        self._get_base_service_name(),
-                        str(e),
-                    )
-                    state_manager.update_progress(
-                        item_id=user_id,
-                        count=0,
-                        success=False,
-                        total_users=total_users,
-                        error=str(e),
-                    )
-                    continue
-
-            # Get generated count and finalize
-            total_generated = self._get_generated_count(
-                request, processed_user_ids=processed_user_ids
-            )
-            state_manager.finalize_progress(users_processed, total_generated)
-
-            return users_processed, total_generated
-        finally:
-            self._is_batch_mode = False
-
-    # ===============================
-    # Rerun methods (optional - override to enable rerun functionality)
-    # ===============================
-
-    def _get_rerun_user_ids(self, request: TRequest) -> list[str]:
-        """Get user IDs to process during rerun.
-
-        Override this method to enable rerun functionality for the service.
-        Returns a list of user IDs that have interactions matching the request filters.
-        Each extractor collects its own data using its configured window_size.
-
-        Args:
-            request: The rerun request object
-
-        Returns:
-            List of user IDs to process
-        """
-        raise NotImplementedError("Rerun not supported by this service")
-
-    def _build_rerun_request_params(self, request: TRequest) -> dict:
-        """Build request params dict for operation state tracking.
-
-        Override this method to enable rerun functionality for the service.
-
-        Args:
-            request: The rerun request object
-
-        Returns:
-            Dictionary of request parameters for state tracking
-        """
-        raise NotImplementedError("Rerun not supported by this service")
-
-    def _create_run_request_for_item(self, user_id: str, request: TRequest) -> TRequest:
-        """Create the request object to pass to self.run() for a single user.
-
-        Override this method to enable rerun functionality for the service.
-        Each extractor collects its own data using its configured window_size.
-
-        Args:
-            user_id: The user ID to process
-            request: The original rerun request object
-
-        Returns:
-            A request object suitable for self.run()
-        """
-        raise NotImplementedError("Rerun not supported by this service")
-
-    def _create_rerun_response(self, success: bool, msg: str, count: int) -> Any:
-        """Create the rerun response object.
-
-        Override this method to enable rerun functionality for the service.
-
-        Args:
-            success: Whether the operation succeeded
-            msg: Status message
-            count: Number of items generated
-
-        Returns:
-            A response object (e.g., RerunProfileGenerationResponse)
-        """
-        raise NotImplementedError("Rerun not supported by this service")
-
-    def _get_generated_count(
-        self,
-        request: TRequest,
-        processed_user_ids: list[str] | None = None,
-    ) -> int:
-        """Get the count of generated items (profiles or playbooks) after rerun.
-
-        Override this method to enable rerun functionality for the service.
-
-        Args:
-            request: The rerun request object (for filtering)
-            processed_user_ids: List of user IDs that were successfully processed
-                in the batch. Provided by _run_batch_with_progress so overrides
-                don't need to handle user_id=None from batch requests.
-
-        Returns:
-            Number of items generated during rerun
-        """
-        raise NotImplementedError("Rerun not supported by this service")
-
-    def _pre_process_rerun(self, request: TRequest) -> None:  # noqa: B027
-        """Hook called before processing rerun items.
-
-        Override in subclasses to perform cleanup or preparation before rerun.
-        Default implementation does nothing.
-
-        Args:
-            request: The rerun request object
-        """
-
-    def run_rerun(self, request: TRequest) -> Any:
-        """Run the rerun workflow for the service.
-
-        This template method orchestrates the rerun process:
-        1. Check for existing in-progress operations
-        2. Get user IDs to process
-        3. Pre-process hook
-        4. Run batch with progress tracking
-        5. Return response
-
-        Child classes must implement the hook methods to enable rerun functionality:
-        - _get_rerun_user_ids()
-        - _build_rerun_request_params()
-        - _create_run_request_for_item()
-        - _create_rerun_response()
-
-        Args:
-            request: The rerun request object
-
-        Returns:
-            A response object with success status, message, and count
-        """
-        state_manager = self._create_state_manager()
-
-        try:
-            # 1. Check for existing in-progress operation
-            error = state_manager.check_in_progress()
-            if error:
-                return self._create_rerun_response(False, error, 0)
-
-            # 2. Get user IDs to process
-            user_ids = self._get_rerun_user_ids(request)
-            if not user_ids:
-                return self._create_rerun_response(
-                    False, "No interactions found matching the specified filters", 0
-                )
-
-            # 3. Pre-process hook (e.g., delete existing pending items)
-            self._pre_process_rerun(request)
-
-            # 4. Run batch with progress tracking
-            users_processed, total_generated = self._run_batch_with_progress(
-                user_ids=user_ids,
-                request=request,
-                request_params=self._build_rerun_request_params(request),
-                state_manager=state_manager,
-            )
-
-            msg = f"Completed for {users_processed} user(s)"
-            return self._create_rerun_response(True, msg, total_generated)
-
-        except Exception as e:
-            state_manager.mark_progress_failed(str(e))
-            return self._create_rerun_response(
-                False,
-                f"Failed to run {self._get_base_service_name()}: {str(e)}",
-                0,
-            )
-
-    # ===============================
-    # Upgrade/Downgrade methods (optional - override to enable)
-    # ===============================
-
-    def _has_items_with_status(self, status: Status | None, request: TRequest) -> bool:
-        """Check if items exist with given status and filters from request.
-
-        Override this method to enable upgrade/downgrade functionality for the service.
-
-        Args:
-            status: The status to check for (None for CURRENT)
-            request: The upgrade/downgrade request object with filters
-
-        Returns:
-            bool: True if any matching items exist
-        """
-        raise NotImplementedError("Upgrade/downgrade not supported by this service")
-
-    def _delete_items_by_status(self, status: Status, request: TRequest) -> int:
-        """Delete items with given status matching request filters.
-
-        Override this method to enable upgrade/downgrade functionality for the service.
-
-        Args:
-            status: The status of items to delete
-            request: The upgrade/downgrade request object with filters
-
-        Returns:
-            int: Number of items deleted
-        """
-        raise NotImplementedError("Upgrade/downgrade not supported by this service")
-
-    def _update_items_status(
-        self,
-        old_status: Status | None,
-        new_status: Status | None,
-        request: TRequest,
-        user_ids: list[str] | None = None,
-    ) -> int:
-        """Update items from old_status to new_status with request filters.
-
-        Override this method to enable upgrade/downgrade functionality for the service.
-
-        Args:
-            old_status: The current status to match (None for CURRENT)
-            new_status: The new status to set (None for CURRENT)
-            request: The upgrade/downgrade request object with filters
-            user_ids: Optional pre-computed list of user IDs to filter by
-
-        Returns:
-            int: Number of items updated
-        """
-        raise NotImplementedError("Upgrade/downgrade not supported by this service")
-
-    def _get_affected_user_ids_for_upgrade(self, request: TRequest) -> list[str] | None:  # noqa: ARG002
-        """Get user IDs to filter by for upgrade operations.
-
-        Override this method to support the only_affected_users flag.
-        By default returns None (no filtering).
-
-        Args:
-            request: The upgrade request object
-
-        Returns:
-            Optional[list[str]]: List of user IDs to filter by, or None for no filtering
-        """
-        return None
-
-    def _get_affected_user_ids_for_downgrade(
-        self,
-        request: TRequest,  # noqa: ARG002
-    ) -> list[str] | None:
-        """Get user IDs to filter by for downgrade operations.
-
-        Override this method to support the only_affected_users flag.
-        By default returns None (no filtering).
-
-        Args:
-            request: The downgrade request object
-
-        Returns:
-            Optional[list[str]]: List of user IDs to filter by, or None for no filtering
-        """
-        return None
-
-    def _create_status_change_response(
-        self,
-        operation: StatusChangeOperation,
-        success: bool,
-        counts: dict,
-        msg: str,
-    ) -> Any:
-        """Create upgrade or downgrade response object based on operation type.
-
-        Override this method to enable upgrade/downgrade functionality for the service.
-
-        Args:
-            operation: The operation type (UPGRADE or DOWNGRADE)
-            success: Whether the operation succeeded
-            counts: Dictionary of counts (upgrade: deleted/archived/promoted, downgrade: demoted/restored)
-            msg: Status message
-
-        Returns:
-            A response object (e.g., UpgradeProfilesResponse, DowngradeUserPlaybooksResponse)
-        """
-        raise NotImplementedError("Upgrade/downgrade not supported by this service")
-
-    def run_upgrade(self, request: TRequest) -> Any:
-        """Run the upgrade workflow for the service.
-
-        This template method orchestrates the upgrade process:
-        1. Validate that pending items exist
-        2. Delete old archived items
-        3. Archive current items (None → ARCHIVED)
-        4. Promote pending items (PENDING → None/CURRENT)
-
-        Child classes must implement the hook methods to enable upgrade functionality:
-        - _has_items_with_status()
-        - _delete_items_by_status()
-        - _update_items_status()
-        - _create_status_change_response()
-
-        Args:
-            request: The upgrade request object with optional filters
-
-        Returns:
-            A response object with success status, counts, and message
-        """
-        try:
-            # 1. Validate pending items exist
-            if not self._has_items_with_status(Status.PENDING, request):
-                return self._create_status_change_response(
-                    StatusChangeOperation.UPGRADE,
-                    False,
-                    {"deleted": 0, "archived": 0, "promoted": 0},
-                    "No pending items found to upgrade",
-                )
-
-            # Get affected user IDs once (child class determines the logic)
-            affected_user_ids = self._get_affected_user_ids_for_upgrade(request)
-
-            # 2. Delete old archived items (skip if archive_current=False)
-            deleted = 0
-            archived = 0
-            if getattr(request, "archive_current", True):
-                deleted = self._delete_items_by_status(Status.ARCHIVED, request)
-
-                # 3. Archive current items (None → ARCHIVED)
-                archived = self._update_items_status(
-                    None, Status.ARCHIVED, request, user_ids=affected_user_ids
-                )
-
-            # 4. Promote pending items (PENDING → None)
-            promoted = self._update_items_status(
-                Status.PENDING, None, request, user_ids=affected_user_ids
-            )
-
-            msg = f"Upgraded: {promoted} promoted, {archived} archived, {deleted} old archived deleted"
-            return self._create_status_change_response(
-                StatusChangeOperation.UPGRADE,
-                True,
-                {"deleted": deleted, "archived": archived, "promoted": promoted},
-                msg,
-            )
-
-        except Exception as e:
-            return self._create_status_change_response(
-                StatusChangeOperation.UPGRADE,
-                False,
-                {"deleted": 0, "archived": 0, "promoted": 0},
-                f"Failed to upgrade: {str(e)}",
-            )
-
-    def run_downgrade(self, request: TRequest) -> Any:
-        """Run the downgrade workflow for the service.
-
-        This template method orchestrates the downgrade process:
-        1. Validate that archived items exist
-        2. Demote current items (None → ARCHIVE_IN_PROGRESS)
-        3. Restore archived items (ARCHIVED → None/CURRENT)
-        4. Complete archiving (ARCHIVE_IN_PROGRESS → ARCHIVED)
-
-        Child classes must implement the hook methods to enable downgrade functionality:
-        - _has_items_with_status()
-        - _update_items_status()
-        - _create_status_change_response()
-
-        Args:
-            request: The downgrade request object with optional filters
-
-        Returns:
-            A response object with success status, counts, and message
-        """
-        try:
-            # 1. Validate archived items exist
-            if not self._has_items_with_status(Status.ARCHIVED, request):
-                return self._create_status_change_response(
-                    StatusChangeOperation.DOWNGRADE,
-                    False,
-                    {"demoted": 0, "restored": 0},
-                    "No archived items found to restore",
-                )
-
-            # Get affected user IDs once (child class determines the logic)
-            affected_user_ids = self._get_affected_user_ids_for_downgrade(request)
-
-            # 2. Demote current (None → ARCHIVE_IN_PROGRESS)
-            demoted = self._update_items_status(
-                None, Status.ARCHIVE_IN_PROGRESS, request, user_ids=affected_user_ids
-            )
-
-            # 3. Restore archived (ARCHIVED → None)
-            restored = self._update_items_status(
-                Status.ARCHIVED, None, request, user_ids=affected_user_ids
-            )
-
-            # 4. Complete archiving (ARCHIVE_IN_PROGRESS → ARCHIVED)
-            self._update_items_status(
-                Status.ARCHIVE_IN_PROGRESS,
-                Status.ARCHIVED,
-                request,
-                user_ids=affected_user_ids,
-            )
-
-            msg = f"Downgraded: {demoted} archived, {restored} restored"
-            return self._create_status_change_response(
-                StatusChangeOperation.DOWNGRADE,
-                True,
-                {"demoted": demoted, "restored": restored},
-                msg,
-            )
-
-        except Exception as e:
-            return self._create_status_change_response(
-                StatusChangeOperation.DOWNGRADE,
-                False,
-                {"demoted": 0, "restored": 0},
-                f"Failed to downgrade: {str(e)}",
-            )