claude-smart 0.2.41 → 0.2.43

package/plugin/vendor/reflexio/reflexio/server/services/reflection/reflection_service_utils.py

@@ -0,0 +1,146 @@
+"""Schemas and result types for the reflection service.
+
+Reflection runs as its own sliding-window step inside the publish flow,
+mirroring the existing profile / playbook extractor pattern: a window
+of size ``window_size`` (global) advanced every ``stride_size``
+interactions. When the gate passes and at least one Assistant
+interaction in the window carries citations, the service asks an LLM
+whether any cited user playbook / user profile rows should be replaced
+in light of how they were applied across the window.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from reflexio.models.api_schema.domain.enums import ProfileTimeToLive
+
+REFLECTION_OPERATION_NAME = "reflection"
+
+
+class ReflectionServiceRequest(BaseModel):
+    """Input to ``ReflectionService.run``.
+
+    The service is invoked once per publish with these scoping fields;
+    it does its own bookmark / window lookup against storage and decides
+    whether to fire.
+
+    Args:
+        user_id (str): User to scope the bookmark and window to.
+        agent_version (str): Agent version of the current publish; copied
+            into replacement playbooks.
+        source (str | None): Optional source filter for the window.
+            Matches the source filter used by extractors. None = all
+            sources for this user.
+    """
+
+    user_id: str
+    agent_version: str = ""
+    source: str | None = None
+
+
+class ReflectionDecision(BaseModel):
+    """A single per-citation decision returned by the LLM.
+
+    Default expected outcome is no_change (no revision fields set).
+
+    Attributes:
+        target_kind (Literal["profile", "playbook"]): Which kind of
+            cited item this decision is about.
+        target_id (str): Stable id of the cited row. ``profile_id`` for
+            profiles, stringified ``user_playbook_id`` for playbooks.
+        new_content (str | None): Replacement content text. Setting any
+            of ``new_content`` / ``new_trigger`` / ``new_rationale`` /
+            ``new_profile_time_to_live`` flags this decision as a
+            revision. Leave all None for no_change.
+
+            Polarity is never declared on the decision: a playbook
+            *flip* is expressed purely by rewriting ``new_content`` in
+            the opposite orientation (negative wording such as
+            ``Avoid`` / ``Do not`` / ``Don't`` / ``Never`` for a
+            success→failure flip; affirmative wording for the reverse).
+            A flip is LLM-reported via that rewritten ``new_content``
+            plus a ``new_rationale`` naming the motivating failure — it
+            is not derived from wording.
+        new_trigger (str | None): Replacement playbook trigger.
+            Optional even on revision; None falls back to the cited
+            value. Ignored for profiles.
+        new_rationale (str | None): Replacement playbook rationale.
+            Same fallback semantics. Required whenever applying a
+            ``new_content`` revision (the prompt sets it on substance
+            rewrites and flips alike, so a content rewrite needs an
+            audit trail naming the motivating failure/observation).
+            Ignored for profiles.
+        new_profile_time_to_live (ProfileTimeToLive | None): Replacement
+            profile TTL. None falls back to the cited value. Ignored
+            for playbooks.
+        reason (str): Short justification, logged.
+    """
+
+    target_kind: Literal["profile", "playbook"]
+    target_id: str
+    new_content: str | None = None
+    new_trigger: str | None = None
+    new_rationale: str | None = None
+    new_profile_time_to_live: ProfileTimeToLive | None = None
+    reason: str = ""
+
+
+class ReflectionOutput(BaseModel):
+    """Structured LLM output for one reflection pass."""
+
+    decisions: list[ReflectionDecision] = Field(default_factory=list)
+
+
+class ReflectionResult(BaseModel):
+    """Outcome of a single reflection pass for logging / tests.
+
+    Attributes:
+        ran (bool): True iff the LLM was actually called.
+        gate_open (bool): True when the stride_size bookmark gate
+            permitted this run.
+        cited_count (int): Distinct citations seen on Assistant
+            interactions in the window.
+        considered_count (int): Cited rows that were still current and
+            therefore handed to the LLM after the post-horizon filter.
+        skipped_count (int): Citations skipped because the target row
+            was missing or already archived, or eligibility was
+            ``deferred`` by the post-horizon filter.
+        no_change_count (int): Decisions with no revision fields set.
+        revised_count (int): Decisions with at least one revision
+            field set. Flips (orientation changes) are LLM-reported via
+            the rewritten ``new_content`` + ``new_rationale`` the prompt
+            emits and are counted as ordinary revisions — there is no
+            separate flip counter, because the prompt sets ``new_rationale``
+            on both flips and non-flip content rewrites, so the two cannot
+            be distinguished without re-deriving polarity (which is retired).
+        trigger_revised_count (int): Subset of applied revisions where
+            ``new_trigger`` was set (playbook trigger changed).
+        content_revised_count (int): Subset of applied revisions where
+            ``new_content`` was set (profile or playbook content changed).
+        ttl_changed_count (int): Subset of applied revisions where
+            ``new_profile_time_to_live`` was set (profile TTL changed).
+        capped_count (int): Revision-intent decisions skipped because the
+            per-pass cap (``ReflectionConfig.max_revisions_per_pass``) was
+            already reached. no_change decisions never count here.
+        failed_count (int): Per-decision failures, logged. Includes both
+            apply-step errors and decisions rejected by ``_validate_decision``
+            (e.g. a playbook ``new_content`` revision that omits
+            ``new_rationale``, which the prompt requires on every playbook
+            content edit).
+    """
+
+    ran: bool = False
+    gate_open: bool = False
+    cited_count: int = 0
+    considered_count: int = 0
+    skipped_count: int = 0
+    no_change_count: int = 0
+    revised_count: int = 0
+    trigger_revised_count: int = 0
+    content_revised_count: int = 0
+    ttl_changed_count: int = 0
+    capped_count: int = 0
+    failed_count: int = 0

package/plugin/vendor/reflexio/reflexio/server/services/retrieval/relevance_floor.py

@@ -0,0 +1,70 @@
+"""Read-path relevance floor: drop retrieved items below a cross-encoder score.
+
+Scores ``(query, item.content)`` pairs with the local cross-encoder (raw logits),
+drops anything below ``floor``, returns survivors sorted by score desc, capped at
+``top_k``. On reranker unavailability, degrades to the retrieved order (logged) —
+never crashes, never silently returns the full unfiltered list.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from reflexio.server.llm.rerank import score_pairs
+from reflexio.server.llm.rerank.cross_encoder_reranker import (
+    CrossEncoderUnavailableError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def apply_relevance_floor[T](
+    query: str,
+    items: list[T],
+    floor: float,
+    top_k: int,
+    *,
+    arm: str,
+    content_of: Callable[[T], str] = lambda item: item.content,  # type: ignore[attr-defined]
+) -> list[T]:
+    """Filter ``items`` to those scoring >= ``floor`` against ``query``.
+
+    Args:
+        query: The search query.
+        items: Retrieved candidates (each must expose ``.content`` or supply ``content_of``).
+        floor: Minimum raw cross-encoder logit to survive.
+        top_k: Max items to return after flooring.
+        arm: Label for logging (e.g. "profiles", "user_playbooks").
+        content_of: Extracts the text to score for an item.
+
+    Returns:
+        Survivors sorted by score descending, capped at ``top_k``. ``[]`` if none qualify.
+        On reranker unavailability, returns ``items[:top_k]`` unchanged (logged).
+    """
+    if not items:
+        return []
+    try:
+        scores = score_pairs(query, [content_of(item) for item in items])
+    except CrossEncoderUnavailableError:
+        logger.warning(
+            "event=relevance_floor_unavailable arm=%s items=%d (returning unfiltered top_k)",
+            arm,
+            len(items),
+        )
+        return items[:top_k]
+
+    ranked = sorted(
+        zip(items, scores, strict=True), key=lambda pair: pair[1], reverse=True
+    )
+    survivors = [item for item, score in ranked if score >= floor]
+    dropped = len(ranked) - len(survivors)
+    if dropped:
+        logger.info(
+            "event=relevance_floor arm=%s kept=%d dropped=%d floor=%.2f",
+            arm,
+            len(survivors),
+            dropped,
+            floor,
+        )
+    return survivors[:top_k]