claude-smart 0.2.45 → 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/tagging/README.md

@@ -0,0 +1,8 @@
+# tagging
+
+Compact post-generation entity tagging capability.
+
+- `service.py` tags profiles and playbooks with the configured tagging prompts.
+- `tagging_scheduler.py` debounces post-publish tagging and rebuilds request context for background execution.
+
+This package intentionally does not use `components/`: the service and scheduler are the only module responsibilities.

package/plugin/vendor/reflexio/reflexio/server/services/tagging/__init__.py

@@ -0,0 +1 @@
+"""Post-generation entity tagging services."""

package/plugin/vendor/reflexio/reflexio/server/services/tagging/service.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+import logging
+import os
+
+from pydantic import ConfigDict, Field
+
+from reflexio.models.api_schema.service_schemas import (
+    AgentPlaybook,
+    UserPlaybook,
+    UserProfile,
+)
+from reflexio.models.structured_output import StrictStructuredOutput
+from reflexio.server.api_endpoints.request_context import RequestContext
+from reflexio.server.llm.litellm_client import LiteLLMClient
+from reflexio.server.llm.model_defaults import ModelRole, resolve_model_name
+from reflexio.server.services.service_utils import log_llm_messages, log_model_response
+from reflexio.server.site_var.site_var_manager import SiteVarManager
+
+logger = logging.getLogger(__name__)
+
+TAGGING_PROMPT_ID = "tagging"
+
+# Upper bound on how many current playbooks a single tagging pass will scan for
+# untagged entries. Tagging is idempotent (already-tagged entities are skipped),
+# so steady-state passes only tag newly generated entities; this bound just keeps
+# a one-time backfill from being silently truncated at the storage default of 100.
+_TAGGING_FETCH_LIMIT = 1000
+
+
+class TagsOutput(StrictStructuredOutput):
+    tags: list[str] = Field(default_factory=list)
+
+    model_config = ConfigDict(
+        extra="allow",
+        json_schema_extra={"additionalProperties": False},
+    )
+
+
+class TaggingService:
+    def __init__(
+        self,
+        llm_client: LiteLLMClient,
+        request_context: RequestContext,
+    ) -> None:
+        self.client = llm_client
+        self.request_context = request_context
+        self.configurator = request_context.configurator
+        self.storage = request_context.storage
+
+        model_setting = SiteVarManager().get_site_var("llm_model_setting")
+        site_var = model_setting if isinstance(model_setting, dict) else {}
+        config = self.configurator.get_config()
+        llm_config = config.llm_config if config else None
+        api_key_config = config.api_key_config if config else None
+        self.model_name = resolve_model_name(
+            ModelRole.GENERATION,
+            site_var_value=site_var.get("default_generation_model_name"),
+            config_override=llm_config.generation_model_name if llm_config else None,
+            api_key_config=api_key_config,
+        )
+
+    def run(
+        self,
+        *,
+        user_id: str,
+        agent_version: str,
+        tag_profiles: bool = True,
+        tag_playbooks: bool = True,
+    ) -> None:
+        if self.storage is None:
+            return
+
+        config = self.configurator.get_config()
+        if config is None:
+            return
+
+        profile_prompt = getattr(
+            config.profile_extractor_config, "tagging_definition_prompt", None
+        )
+        user_playbook_prompt = getattr(
+            config.user_playbook_extractor_config, "tagging_definition_prompt", None
+        )
+
+        if tag_profiles and profile_prompt:
+            self._tag_profiles(
+                user_id=user_id, tagging_definition_prompt=profile_prompt
+            )
+        if tag_playbooks and user_playbook_prompt:
+            self._tag_user_playbooks(
+                user_id=user_id,
+                agent_version=agent_version,
+                tagging_definition_prompt=user_playbook_prompt,
+            )
+            self._tag_agent_playbooks(
+                agent_version=agent_version,
+                tagging_definition_prompt=user_playbook_prompt,
+            )
+
+    def _tag_profiles(self, *, user_id: str, tagging_definition_prompt: str) -> None:
+        profiles = self.storage.get_user_profile(user_id)  # type: ignore[union-attr]
+        for profile in profiles:
+            if profile.tags is not None:
+                continue  # already tagged (incl. empty result) — tag each entity once
+            tags = self._generate_tags(
+                tagging_definition_prompt=tagging_definition_prompt,
+                content=self._profile_content(profile),
+            )
+            self.storage.update_user_profile_tags(  # type: ignore[union-attr]
+                user_id, profile.profile_id, tags
+            )
+
+    def _tag_user_playbooks(
+        self,
+        *,
+        user_id: str,
+        agent_version: str,
+        tagging_definition_prompt: str,
+    ) -> None:
+        playbooks = self.storage.get_user_playbooks(  # type: ignore[union-attr]
+            limit=_TAGGING_FETCH_LIMIT,
+            user_id=user_id,
+            agent_version=agent_version,
+            status_filter=[None],
+        )
+        for playbook in playbooks:
+            if playbook.tags is not None:
+                continue  # already tagged (incl. empty result) — tag each entity once
+            tags = self._generate_tags(
+                tagging_definition_prompt=tagging_definition_prompt,
+                content=self._playbook_content(playbook),
+            )
+            self.storage.update_user_playbook(  # type: ignore[union-attr]
+                playbook.user_playbook_id,
+                tags=tags,
+            )
+
+    def _tag_agent_playbooks(
+        self,
+        *,
+        agent_version: str,
+        tagging_definition_prompt: str,
+    ) -> None:
+        playbooks = self.storage.get_agent_playbooks(  # type: ignore[union-attr]
+            limit=_TAGGING_FETCH_LIMIT,
+            agent_version=agent_version,
+            status_filter=[None],
+        )
+        for playbook in playbooks:
+            if playbook.tags is not None:
+                continue  # already tagged (incl. empty result) — tag each entity once
+            tags = self._generate_tags(
+                tagging_definition_prompt=tagging_definition_prompt,
+                content=self._playbook_content(playbook),
+            )
+            self.storage.update_agent_playbook(  # type: ignore[union-attr]
+                playbook.agent_playbook_id,
+                tags=tags,
+            )
+
+    def _generate_tags(
+        self, *, tagging_definition_prompt: str, content: str
+    ) -> list[str]:
+        if os.getenv("MOCK_LLM_RESPONSE", "").lower() == "true":
+            return ["example_tag"]
+
+        prompt = self.request_context.prompt_manager.render_prompt(
+            TAGGING_PROMPT_ID,
+            {
+                "tagging_definition_prompt": tagging_definition_prompt.strip(),
+                "content": content,
+            },
+        )
+        messages = [{"role": "user", "content": prompt}]
+        log_llm_messages(logger, "Tagging", messages)
+        response = self.client.generate_chat_response(
+            messages=messages,
+            model=self.model_name,
+            response_format=TagsOutput,
+        )
+        log_model_response(logger, "Tagging response", response)
+        if not isinstance(response, TagsOutput):
+            logger.warning(
+                "Unexpected response type from tagging LLM: %s", type(response)
+            )
+            return []
+        return [tag.strip() for tag in response.tags if tag.strip()]
+
+    @staticmethod
+    def _profile_content(profile: UserProfile) -> str:
+        return profile.content
+
+    @staticmethod
+    def _playbook_content(playbook: UserPlaybook | AgentPlaybook) -> str:
+        parts = [playbook.content]
+        if playbook.trigger:
+            parts.append(f"Trigger: {playbook.trigger}")
+        if playbook.rationale:
+            parts.append(f"Rationale: {playbook.rationale}")
+        return "\n".join(part for part in parts if part)

package/plugin/vendor/reflexio/reflexio/server/services/tagging/tagging_scheduler.py

@@ -0,0 +1,149 @@
+"""Singleton scheduler for deferred, off-publish-path entity tagging.
+
+Tagging runs an LLM call per newly generated profile/playbook, so it must not
+block the publish request. This scheduler mirrors
+:class:`GroupEvaluationScheduler`: a single daemon thread with a min-heap, where
+each publish upserts the fire time for its ``(org_id, user_id, agent_version)``
+key. Rapid successive publishes for the same key debounce into a single tagging
+pass; when the timer fires, the tagging callback runs on its own daemon thread.
+
+Tagging is idempotent (already-tagged entities are skipped), so a deferred pass
+naturally handles both newly generated entities and the one-time backfill that
+happens when a tagging definition is first configured.
+"""
+
+from __future__ import annotations
+
+import heapq
+import logging
+import os
+import threading
+import time
+from collections.abc import Callable
+
+from reflexio.server.api_endpoints.request_context import RequestContext
+from reflexio.server.llm.litellm_client import LiteLLMClient
+from reflexio.server.services.tagging.service import TaggingService
+
+logger = logging.getLogger(__name__)
+
+# Delay before a tagging pass fires after the last publish for a key. Long enough
+# to debounce a burst of publishes into one pass, short enough that tags appear
+# promptly. Kept as a patch point for tests.
+TAGGING_DELAY_SECONDS = 15
+IS_TEST_ENV = os.environ.get("IS_TEST_ENV", "false").strip().lower() == "true"
+_EFFECTIVE_DELAY_SECONDS = 1 if IS_TEST_ENV else TAGGING_DELAY_SECONDS
+
+# (org_id, user_id, agent_version)
+TaggingKey = tuple[str, str, str]
+
+
+class TaggingScheduler:
+    """Singleton scheduler that fires entity tagging after a short debounce."""
+
+    _instance = None
+    _lock = threading.Lock()
+
+    @classmethod
+    def get_instance(cls) -> TaggingScheduler:
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def __init__(self) -> None:
+        self._scheduled: dict[TaggingKey, tuple[float, Callable]] = {}
+        self._heap: list[tuple[float, TaggingKey]] = []
+        self._mutex = threading.Lock()
+        self._wake_event = threading.Event()
+        self._thread = threading.Thread(
+            target=self._scheduler_loop, daemon=True, name="tagging-scheduler"
+        )
+        self._thread.start()
+        logger.info("TaggingScheduler started")
+
+    def schedule(self, key: TaggingKey, callback: Callable) -> None:
+        """Schedule or reschedule a tagging pass for ``key`` (slides the fire time forward)."""
+        fire_time = time.monotonic() + _EFFECTIVE_DELAY_SECONDS
+        with self._mutex:
+            self._scheduled[key] = (fire_time, callback)
+            heapq.heappush(self._heap, (fire_time, key))
+        self._wake_event.set()
+
+    def _scheduler_loop(self) -> None:
+        while True:
+            try:
+                with self._mutex:
+                    next_fire_time = self._heap[0][0] if self._heap else None
+
+                if next_fire_time is None:
+                    self._wake_event.wait()
+                    self._wake_event.clear()
+                    continue
+
+                wait_seconds = next_fire_time - time.monotonic()
+                if wait_seconds > 0:
+                    self._wake_event.wait(timeout=wait_seconds)
+                    self._wake_event.clear()
+                    continue
+
+                with self._mutex:
+                    while self._heap and self._heap[0][0] <= time.monotonic():
+                        fire_time, key = heapq.heappop(self._heap)
+
+                        current = self._scheduled.get(key)
+                        if current is None:
+                            continue
+                        current_fire_time, callback = current
+                        if abs(current_fire_time - fire_time) > 0.001:
+                            # Superseded by a newer schedule for the same key.
+                            continue
+
+                        del self._scheduled[key]
+                        t = threading.Thread(
+                            target=self._run_callback,
+                            args=(key, callback),
+                            daemon=True,
+                            name=f"tagging-{key[1][:20]}",
+                        )
+                        t.start()
+            except Exception:
+                logger.exception("Error in tagging scheduler loop")
+                time.sleep(1)
+
+    @staticmethod
+    def _run_callback(key: TaggingKey, callback: Callable) -> None:
+        try:
+            logger.info("Firing tagging for key=%s", key)
+            callback()
+            logger.info("Completed tagging for key=%s", key)
+        except Exception:
+            logger.exception("Tagging callback failed for key=%s", key)
+
+
+def schedule_tagging(
+    *,
+    org_id: str,
+    user_id: str,
+    agent_version: str,
+    request_context: RequestContext,
+    llm_client: LiteLLMClient,
+) -> None:
+    """Enqueue a deferred tagging pass for the given user/agent off the publish path."""
+    if not user_id:
+        return
+
+    key: TaggingKey = (org_id, user_id, agent_version)
+    storage_base_dir = getattr(request_context, "storage_base_dir", None)
+
+    def callback() -> None:
+        fresh_context = RequestContext(
+            org_id=org_id,
+            storage_base_dir=storage_base_dir,
+        )
+        TaggingService(llm_client=llm_client, request_context=fresh_context).run(
+            user_id=user_id, agent_version=agent_version
+        )
+
+    TaggingScheduler.get_instance().schedule(key, callback)