claude-smart 0.2.46 → 0.2.47

package/plugin/vendor/reflexio/reflexio/server/services/storage/storage_base/playbook/_user.py

@@ -0,0 +1,333 @@
+"""Abstract user playbook CRUD + search declarations."""
+
+from abc import abstractmethod
+
+from reflexio.models.api_schema.common import BlockingIssue
+from reflexio.models.api_schema.domain import Status, UserPlaybook
+from reflexio.models.api_schema.retriever_schema import SearchUserPlaybookRequest
+from reflexio.models.config_schema import SearchOptions
+
+
+class UserPlaybookStoreMixin:
+    """Abstract user playbook CRUD + search methods."""
+
+    @abstractmethod
+    def save_user_playbooks(self, user_playbooks: list[UserPlaybook]) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_user_playbooks(
+        self,
+        limit: int = 100,
+        user_id: str | None = None,
+        playbook_name: str | None = None,
+        agent_version: str | None = None,
+        status_filter: list[Status | None] | None = None,
+        start_time: int | None = None,
+        end_time: int | None = None,
+        include_embedding: bool = False,
+        tags: list[str] | None = None,
+        offset: int = 0,
+        user_playbook_id: int | None = None,
+        request_id: str | None = None,
+        query: str | None = None,
+    ) -> list[UserPlaybook]:
+        """Get user playbooks from storage.
+
+        Args:
+            limit (int): Maximum number of playbooks to return
+            user_playbook_id (int, optional): Exact user playbook ID to retrieve.
+            user_id (str, optional): The user ID to filter by. If None, returns playbooks for all users.
+            request_id (str, optional): Request ID that generated the playbook.
+            query (str, optional): Case-insensitive text filter across visible fields.
+            playbook_name (str, optional): The playbook name to filter by. If None, returns all user playbooks.
+            agent_version (str, optional): The agent version to filter by. If None, returns all agent versions.
+            status_filter (list[Optional[Status]], optional): List of status values to filter by.
+                Can include None (current), Status.PENDING (from rerun), Status.ARCHIVED (old).
+                If None, returns playbooks with all statuses.
+            start_time (int, optional): Unix timestamp. Only return playbooks created at or after this time.
+            end_time (int, optional): Unix timestamp. Only return playbooks created at or before this time.
+            include_embedding (bool): If True, fetch and parse embedding vectors. Defaults to False.
+            tags (list[str], optional): Match playbooks having any of these tags.
+            offset (int): Number of matching rows to skip. Defaults to 0.
+
+        Returns:
+            list[UserPlaybook]: List of user playbook objects
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def count_user_playbooks(
+        self,
+        user_id: str | None = None,
+        playbook_name: str | None = None,
+        min_user_playbook_id: int | None = None,
+        agent_version: str | None = None,
+        status_filter: list[Status | None] | None = None,
+    ) -> int:
+        """Count user playbooks in storage efficiently.
+
+        Args:
+            user_id (str, optional): The user ID to filter by. If None, counts playbooks for all users.
+            playbook_name (str, optional): The playbook name to filter by. If None, counts all user playbooks.
+            min_user_playbook_id (int, optional): Only count playbooks with user_playbook_id greater than this value.
+            agent_version (str, optional): The agent version to filter by. If None, counts all agent versions.
+            status_filter (list[Optional[Status]], optional): List of status values to filter by.
+                Can include None (current), Status.PENDING (from rerun), Status.ARCHIVED (old).
+                If None, returns playbooks with all statuses.
+
+        Returns:
+            int: Count of user playbooks matching the filters
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def count_user_playbooks_by_session(self, session_id: str) -> int:
+        """Count user playbooks linked to a session via request_id -> requests.session_id.
+
+        Args:
+            session_id (str): The session ID to count user playbooks for
+
+        Returns:
+            int: Count of user playbooks linked to the session
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_all_user_playbooks(self) -> None:
+        """Delete all user playbooks from storage."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_all_user_playbooks_by_playbook_name(
+        self, playbook_name: str, agent_version: str | None = None
+    ) -> None:
+        """Delete all user playbooks by playbook name from storage.
+
+        Args:
+            playbook_name (str): The playbook name to delete
+            agent_version (str, optional): The agent version to filter by. If None, deletes all agent versions.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_user_playbook(self, user_playbook_id: int) -> None:
+        """Delete a user playbook by ID.
+
+        Args:
+            user_playbook_id (int): The ID of the user playbook to delete
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def update_all_user_playbooks_status(
+        self,
+        old_status: Status | None,
+        new_status: Status | None,
+        agent_version: str | None = None,
+        playbook_name: str | None = None,
+    ) -> int:
+        """Update all user playbooks with old_status to new_status atomically.
+
+        Args:
+            old_status: The current status to match (None for CURRENT)
+            new_status: The new status to set (None for CURRENT)
+            agent_version: Optional filter by agent version
+            playbook_name: Optional filter by playbook name
+
+        Returns:
+            int: Number of user playbooks updated
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_all_user_playbooks_by_status(
+        self,
+        status: Status,
+        agent_version: str | None = None,
+        playbook_name: str | None = None,
+    ) -> int:
+        """Delete all user playbooks with the given status atomically.
+
+        Args:
+            status: The status of user playbooks to delete
+            agent_version: Optional filter by agent version
+            playbook_name: Optional filter by playbook name
+
+        Returns:
+            int: Number of user playbooks deleted
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete_user_playbooks_by_ids(
+        self, user_playbook_ids: list[int], *, emit_hard_delete: bool = True
+    ) -> int:
+        """Delete user playbooks by their IDs.
+
+        Args:
+            user_playbook_ids: List of user_playbook_id values to delete
+            emit_hard_delete: When True (default), append a ``hard_delete``
+                lineage event per id (genuine erasure). Set False for rollback
+                cleanup of a never-live row (e.g. a lost supersede CAS), so no
+                spurious audit event is recorded.
+
+        Returns:
+            int: Number of user playbooks deleted
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_user_playbooks_by_ids(
+        self,
+        user_id: str,
+        user_playbook_ids: list[int],
+        status_filter: list[Status | None] | None = None,
+    ) -> list[UserPlaybook]:
+        """Fetch the subset of a user's playbooks whose ids are in the list.
+
+        Server-side filter on (``user_id``, ``user_playbook_id IN (...)``)
+        so callers (e.g. the reflection service resolving a small set of
+        cited playbook ids) avoid scanning every playbook for the user.
+
+        Args:
+            user_id (str): Owning user id.
+            user_playbook_ids (list[int]): Playbook ids to fetch. Empty
+                list returns ``[]`` without hitting storage.
+            status_filter (list[Status | None] | None): Statuses to
+                include. ``None`` (default) means CURRENT only — same
+                default as ``get_user_playbooks`` for consistency.
+
+        Returns:
+            list[UserPlaybook]: Matching playbooks. Order is unspecified.
+                Ids that do not exist (or do not match the user / status
+                filter) are silently omitted.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_user_playbook_by_id(
+        self, user_playbook_id: int, *, include_tombstones: bool = False
+    ) -> UserPlaybook | None:
+        """Fetch one user playbook by primary key.
+
+        Args:
+            user_playbook_id: The user_playbook_id to look up.
+            include_tombstones: When False (default), MERGED/SUPERSEDED rows
+                return None. Set to True for lineage resolution (resolve_current).
+
+        Returns:
+            The UserPlaybook if found and not filtered, otherwise None.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get_user_playbooks_by_ids_any_user(
+        self,
+        user_playbook_ids: list[int],
+        status_filter: list[Status | None] | None = None,
+    ) -> list[UserPlaybook]:
+        """Fetch user playbooks by ids without requiring a single owner id."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def archive_user_playbook_by_id(self, user_id: str, user_playbook_id: int) -> bool:
+        """Atomically archive a single user playbook by id, only if CURRENT.
+
+        Flips the row's ``status`` from ``None`` (CURRENT) to
+        ``Status.ARCHIVED``. No-op when the playbook does not exist, has
+        a different ``user_id``, or is already non-current.
+
+        Args:
+            user_id (str): Owning user id; used as a guard so callers
+                cannot accidentally archive another user's playbook.
+            user_playbook_id (int): The user_playbook_id to archive.
+
+        Returns:
+            bool: True if a row was archived; False otherwise.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def has_user_playbooks_with_status(
+        self,
+        status: Status | None,
+        agent_version: str | None = None,
+        playbook_name: str | None = None,
+    ) -> bool:
+        """Check if any user playbooks exist with given status and filters.
+
+        Args:
+            status: The status to check for (None for CURRENT)
+            agent_version: Optional filter by agent version
+            playbook_name: Optional filter by playbook name
+
+        Returns:
+            bool: True if any matching user playbooks exist
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def update_user_playbook(
+        self,
+        user_playbook_id: int,
+        playbook_name: str | None = None,
+        content: str | None = None,
+        trigger: str | None = None,
+        rationale: str | None = None,
+        blocking_issue: BlockingIssue | None = None,
+        tags: list[str] | None = None,
+    ) -> None:
+        """Update editable fields of a user playbook. Only non-None fields are updated.
+
+        Args:
+            user_playbook_id (int): The ID of the user playbook to update
+            playbook_name (str, optional): New playbook name
+            content (str, optional): New content text
+            trigger (str, optional): New trigger text
+            rationale (str, optional): New rationale text
+            blocking_issue (BlockingIssue, optional): New blocking issue
+            tags (list[str], optional): Replacement tags
+
+        Raises:
+            ValueError: If user playbook with the given ID is not found
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def supersede_user_playbooks_by_ids(
+        self, user_playbook_ids: list[int], request_id: str
+    ) -> int:
+        """Soft-delete user playbooks by setting status to SUPERSEDED.
+
+        Eligible rows (CURRENT, PENDING, or ARCHIVED; not already MERGED /
+        SUPERSEDED) are transitioned to SUPERSEDED and emit one status_change
+        lineage event under the shared request id. This is the user-playbook
+        analogue of the existing agent/profile soft-supersede helpers and
+        preserves dead-source content for point-in-time attribution reads.
+
+        Args:
+            user_playbook_ids (list[int]): User playbook ids to supersede.
+            request_id (str): Shared request id for all emitted lineage events.
+
+        Returns:
+            int: Number of user playbooks actually updated.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def search_user_playbooks(
+        self,
+        request: SearchUserPlaybookRequest,
+        options: SearchOptions | None = None,
+    ) -> list[UserPlaybook]:
+        """Search user playbooks with advanced filtering including semantic search.
+
+        Args:
+            request (SearchUserPlaybookRequest): Search request with query, filters, and pagination
+            options (SearchOptions, optional): Engine-level search parameters (e.g. pre-computed embedding)
+
+        Returns:
+            list[UserPlaybook]: List of matching user playbook objects
+        """
+        raise NotImplementedError

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

@@ -17,6 +17,7 @@ from collections import OrderedDict
 from collections.abc import Callable
 from concurrent.futures import Future, ThreadPoolExecutor
 from concurrent.futures import TimeoutError as FuturesTimeoutError
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any, cast
 
 from reflexio.models.api_schema.retriever_schema import (
@@ -41,6 +42,13 @@ from reflexio.models.config_schema import (
 from reflexio.server.llm.litellm_client import LiteLLMClient
 from reflexio.server.prompt.prompt_manager import PromptManager
 from reflexio.server.services.pre_retrieval import QueryReformulator
+from reflexio.server.services.retrieval.recency import (
+    RecencyConfig,
+    ScoredItem,
+    additive_penalty,
+    decay_for_item,
+    multiplicative_factor,
+)
 from reflexio.server.services.retrieval.relevance_floor import apply_relevance_floors
 from reflexio.server.services.storage.storage_base import BaseStorage
 from reflexio.server.tracing import profile_step, set_span_data
@@ -102,6 +110,7 @@ def run_unified_search(
     prompt_manager: PromptManager,
     pre_retrieval_model_name: str | None = None,
     retrieval_floor: RetrievalFloorConfig | None = None,
+    recency: RecencyConfig | None = None,
 ) -> UnifiedSearchResponse:
     """
     Search across all entity types (profiles, agent playbooks, user playbooks) in parallel.
@@ -129,7 +138,12 @@ def run_unified_search(
 
     floor_cfg = retrieval_floor or RetrievalFloorConfig()
     floor_on = floor_cfg.enabled
-    fetch_k = max(top_k, floor_cfg.pool_size) if floor_on else top_k
+    recency_on = bool(recency and recency.enabled)
+    fetch_k = max(
+        top_k,
+        floor_cfg.pool_size if floor_on else 0,
+        recency.pool_size if recency_on and recency is not None else 0,
+    )
 
     # --- Phase A: query reformulation + embedding generation ---
     reformulated_query, embedding = _run_phase_a(
@@ -153,6 +167,7 @@ def run_unified_search(
         query=reformulated_query,
         top_k=fetch_k,
         threshold=threshold,
+        recency_on=recency_on,
     )
 
     if profiles is None:
@@ -166,7 +181,28 @@ def run_unified_search(
             user_playbooks=user_playbooks,  # type: ignore[arg-type]
             top_k=top_k,
             cfg=floor_cfg,
+            recency=recency if recency_on else None,
+        )
+    elif recency_on and recency is not None:
+        profiles = _apply_combined_score_recency(
+            profiles or [], entity_type="profiles", top_k=top_k, cfg=recency
+        )
+        agent_playbooks = _apply_combined_score_recency(
+            agent_playbooks or [],
+            entity_type="agent_playbooks",
+            top_k=top_k,
+            cfg=recency,
+        )
+        user_playbooks = _apply_combined_score_recency(
+            user_playbooks or [],
+            entity_type="user_playbooks",
+            top_k=top_k,
+            cfg=recency,
         )
+    else:
+        profiles = _unwrap_items(profiles or [])[:top_k]
+        agent_playbooks = _unwrap_items(agent_playbooks or [])[:top_k]
+        user_playbooks = _unwrap_items(user_playbooks or [])[:top_k]
 
     user_playbooks = _suppress_source_user_playbooks(
         storage=storage,
@@ -284,10 +320,11 @@ def _run_phase_b(
     query: str,
     top_k: int,
     threshold: float,
+    recency_on: bool = False,
 ) -> tuple[
-    list[UserProfile] | None,
-    list[AgentPlaybook] | None,
-    list[UserPlaybook] | None,
+    list[Any] | None,
+    list[Any] | None,
+    list[Any] | None,
 ]:
     """Run parallel searches across all entity types by delegating to storage methods.
 
@@ -314,9 +351,18 @@ def _run_phase_b(
             entity_types=sorted(entity_types),
             top_k=top_k,
         ) as span:
-            if (
+            # Recency needs the per-row ``combined_score``, which only the scored
+            # single-RPC method threads back. Backends that don't advertise
+            # ``supports_unified_hybrid_search`` (e.g. native Postgres, which still
+            # inherits ``unified_hybrid_search_scored`` and runs it via the same
+            # ``_rpc`` it already uses for ``hybrid_match_*``) opt into the scored
+            # path only when recency is on, so non-recency routing is unchanged.
+            wants_scored_single_rpc = recency_on and callable(
+                getattr(storage, "unified_hybrid_search_scored", None)
+            )
+            if _unified_single_rpc_enabled() and (
                 getattr(storage, "supports_unified_hybrid_search", False)
-                and _unified_single_rpc_enabled()
+                or wants_scored_single_rpc
             ):
                 combined = _run_phase_b_single_rpc(
                     request=request,
@@ -327,6 +373,7 @@ def _run_phase_b(
                     threshold=threshold,
                     entity_types=entity_types,
                     allowed_agent_statuses=allowed_agent_statuses,
+                    recency_on=recency_on,
                 )
                 if combined is not None:
                     profiles, agent_playbooks, user_playbooks = combined
@@ -437,7 +484,8 @@ def _run_phase_b_single_rpc(
     threshold: float,
     entity_types: set[str],
     allowed_agent_statuses: list[PlaybookStatus] | None,
-) -> tuple[list[UserProfile], list[AgentPlaybook], list[UserPlaybook]] | None:
+    recency_on: bool = False,
+) -> tuple[list[Any], list[Any], list[Any]] | None:
     """Run all Phase B arms through one combined storage round trip.
 
     Trades the per-arm round-trip overhead for serialized execution of the
@@ -458,8 +506,16 @@ def _run_phase_b_single_rpc(
     )
     # Resolve storage.unified_hybrid_search before submit so missing or stale
     # capability flags can fall back to the fan-out path.
-    unified_hybrid_search = getattr(storage, "unified_hybrid_search", None)
+    method_name = (
+        "unified_hybrid_search_scored" if recency_on else "unified_hybrid_search"
+    )
+    unified_hybrid_search = getattr(storage, method_name, None)
     if not callable(unified_hybrid_search):
+        if recency_on:
+            logger.warning(
+                "event=search_recency_missing_scores source=single_rpc method=%s",
+                method_name,
+            )
         return None
 
     future = _submit_with_current_context(
@@ -490,13 +546,14 @@ def _run_phase_b_single_rpc(
         return None
 
     # Mirror _search_agent_playbooks_via_storage: dedupe by id, cap at top_k.
-    deduped: list[AgentPlaybook] = []
+    deduped: list[Any] = []
     seen_ids: set[str] = set()
-    for playbook in agent_playbooks:
+    for candidate in agent_playbooks:
+        playbook = _unwrap_item(candidate)
         playbook_id = str(getattr(playbook, "agent_playbook_id", ""))
         if playbook_id and playbook_id not in seen_ids:
             seen_ids.add(playbook_id)
-            deduped.append(playbook)
+            deduped.append(candidate)
             if len(deduped) >= top_k:
                 break
     return profiles, deduped, user_playbooks
@@ -509,6 +566,7 @@ def _apply_floors(
     user_playbooks: list[UserPlaybook],
     top_k: int,
     cfg: RetrievalFloorConfig,
+    recency: RecencyConfig | None = None,
 ) -> tuple[list[UserProfile], list[AgentPlaybook], list[UserPlaybook]]:
     """Apply the per-arm relevance floor with one batched cross-encoder call."""
     floored_profiles, floored_agent, floored_user = apply_relevance_floors(
@@ -519,8 +577,91 @@ def _apply_floors(
             ("user_playbooks", user_playbooks, cfg.user_playbook_floor),
         ],
         top_k,
+        content_of=lambda item: _unwrap_item(item).content,
     )
-    return floored_profiles, floored_agent, floored_user
+    return (
+        _finalize_floor_arm(
+            floored_profiles, entity_type="profiles", top_k=top_k, recency=recency
+        ),
+        _finalize_floor_arm(
+            floored_agent,
+            entity_type="agent_playbooks",
+            top_k=top_k,
+            recency=recency,
+        ),
+        _finalize_floor_arm(
+            floored_user,
+            entity_type="user_playbooks",
+            top_k=top_k,
+            recency=recency,
+        ),
+    )
+
+
+def _finalize_floor_arm(
+    result: Any,
+    *,
+    entity_type: str,
+    top_k: int,
+    recency: RecencyConfig | None,
+) -> list[Any]:
+    if not recency or not recency.enabled:
+        return _unwrap_items(result.items)[:top_k]
+    if result.scores is None:
+        return _apply_combined_score_recency(
+            result.items, entity_type=entity_type, top_k=top_k, cfg=recency
+        )
+    now = int(datetime.now(UTC).timestamp())
+    rescored = []
+    for item, score in zip(result.items, result.scores, strict=True):
+        unwrapped = _unwrap_item(item)
+        freshness = decay_for_item(unwrapped, entity_type=entity_type, now=now)
+        rescored.append(
+            (unwrapped, score - additive_penalty(freshness, recency.max_penalty_logit))
+        )
+    rescored.sort(key=lambda pair: pair[1], reverse=True)
+    return [item for item, _score in rescored[:top_k]]
+
+
+def _apply_combined_score_recency(
+    items: list[Any],
+    *,
+    entity_type: str,
+    top_k: int,
+    cfg: RecencyConfig,
+) -> list[Any]:
+    if not items:
+        return []
+    scored_items: list[tuple[Any, float]] = []
+    for item in items:
+        if not isinstance(item, ScoredItem) or item.score is None:
+            logger.warning(
+                "event=search_recency_missing_scores entity_type=%s items=%d",
+                entity_type,
+                len(items),
+            )
+            return _unwrap_items(items)[:top_k]
+        scored_items.append((item.item, item.score))
+    now = int(datetime.now(UTC).timestamp())
+    rescored = []
+    for item, score in scored_items:
+        freshness = decay_for_item(item, entity_type=entity_type, now=now)
+        rescored.append(
+            (
+                item,
+                score * multiplicative_factor(freshness, cfg.max_penalty_frac),
+            )
+        )
+    rescored.sort(key=lambda pair: pair[1], reverse=True)
+    return [item for item, _score in rescored[:top_k]]
+
+
+def _unwrap_item(item: Any) -> Any:
+    return item.item if isinstance(item, ScoredItem) else item
+
+
+def _unwrap_items(items: list[Any]) -> list[Any]:
+    return [_unwrap_item(item) for item in items]
 
 
 def _suppress_source_user_playbooks(

package/plugin/vendor/reflexio/reflexio/server/services/playbook/user_detail_stripping.py

@@ -1,84 +0,0 @@
-from __future__ import annotations
-
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import Protocol
-
-
-@dataclass(frozen=True)
-class DetectedEntity:
-    start: int
-    end: int
-    entity_type: str
-    replacement: str
-    confidence: float
-    source: str
-
-
-@dataclass(frozen=True)
-class StrippingResult:
-    text: str
-    detections: list[DetectedEntity] = field(default_factory=list)
-
-
-class UserDetailDetector(Protocol):
-    def detect(self, text: str) -> list[DetectedEntity]: ...
-
-
-class UserDetailStripper(Protocol):
-    prompt_extra_instructions: str | None
-
-    def strip_user_details(
-        self,
-        text: str,
-        shared_mapping: dict[str, int] | None = None,
-    ) -> StrippingResult: ...
-
-    def sanitize_aggregation_output_text(
-        self,
-        text: str | None,
-    ) -> tuple[str | None, int]: ...
-
-
-class PassthroughStripper:
-    prompt_extra_instructions: str | None = None
-
-    def strip_user_details(
-        self,
-        text: str,
-        shared_mapping: dict[str, int] | None = None,  # noqa: ARG002
-    ) -> StrippingResult:
-        return StrippingResult(text=text, detections=[])
-
-    def sanitize_aggregation_output_text(
-        self,
-        text: str | None,
-    ) -> tuple[str | None, int]:
-        return text, 0
-
-
-UserDetailStripperFactory = Callable[[object], UserDetailStripper | None]
-
-
-def _default_user_detail_stripper_factory(
-    _configurator: object,
-) -> UserDetailStripper | None:
-    return None
-
-
-_user_detail_stripper_factory: UserDetailStripperFactory = (
-    _default_user_detail_stripper_factory
-)
-
-
-def set_user_detail_stripper_factory(factory: UserDetailStripperFactory) -> None:
-    """Register the deployment-specific aggregation stripper factory."""
-    global _user_detail_stripper_factory  # noqa: PLW0603
-    _user_detail_stripper_factory = factory
-
-
-def create_aggregation_user_detail_stripper(
-    configurator: object,
-) -> UserDetailStripper | None:
-    """Create the deployment-specific stripper for aggregation, if any."""
-    return _user_detail_stripper_factory(configurator)