claude-smart 0.2.45 → 0.2.47

package/plugin/vendor/reflexio/reflexio/models/api_schema/domain/entities.py

@@ -118,6 +118,11 @@ __all__ = [
     "ShareLink",
     "AdminInvalidateCacheRequest",
     "AdminInvalidateCacheResponse",
+    "PlaybookRetrievalLogItem",
+    "PlaybookRetrievalLog",
+    "LineageEvent",
+    "LineageContext",
+    "RecordRef",
 ]
 
 # ===============================
@@ -179,11 +184,7 @@ class Request(BaseModel):
     """A user-issued request that begins or continues a session.
 
     A Request is the unit of work the agent reacts to. Multiple Requests
-    share a ``session_id`` to form a multi-turn session. The optional
-    ``metadata`` dict carries per-request key/value annotations stamped by
-    customer integration code — distinct from ``playbook_metadata`` (a
-    JSON-encoded string) used by ``Playbook``-family entities elsewhere in
-    this module.
+    share a ``session_id`` to form a multi-turn session.
 
     Attributes:
         request_id (str): Unique identifier for this request.
@@ -192,22 +193,10 @@ class Request(BaseModel):
             to the current UTC time.
         source (str): Free-form origin tag (integration name, etc.).
         agent_version (str): The agent version that handled this request.
-        session_id (str | None): Session this request belongs to, or None
-            if the request is not part of a multi-turn session.
-        metadata (dict[str, Any]): Free-form per-request annotations.
-            Always a dict — never None. Conventional keys:
-
-            - ``reflexio_retrieval_enabled`` (bool): F2 group-by signal;
-              customer integration code stamps this to indicate whether
-              Reflexio retrieval was active for the session. Read by the
-              ``/api/get_evaluation_overview`` aggregator from the FIRST
-              request of each session for sticky group assignment.
-
-            Distinct from ``playbook_metadata`` on ``Playbook``-family
-            entities (which is a JSON-encoded string, not a dict).
-            On-the-wire serialization assumes JSON-encodable values;
-            non-JSON values like ``datetime`` or ``set`` will fail at
-            the storage / API boundary.
+        session_id (str): Non-empty session this request belongs to.
+        evaluation_only (bool): Whether this request is stored for
+            session-level evaluation only and must be excluded from
+            profile/playbook learning windows.
     """
 
     request_id: str
@@ -215,8 +204,8 @@ class Request(BaseModel):
     created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
     source: str = ""
     agent_version: str = ""
-    session_id: str | None = None
-    metadata: dict[str, Any] = Field(default_factory=dict)
+    session_id: NonEmptyStr
+    evaluation_only: bool = False
 
 
 # information about the user profile generated from the user interaction
@@ -237,10 +226,14 @@ class UserProfile(BaseModel):
         None  # Retained provenance data column (merged on dedup); new profiles write None.
     )
     expanded_terms: str | None = None
+    tags: list[str] | None = None  # None = not yet tagged; [] = tagged, no match
+    source_interaction_ids: list[int] = Field(default_factory=list)
     embedding: EmbeddingVector = []
     source_span: str | None = None
     notes: str | None = None
     reader_angle: str | None = None
+    merged_into: str | None = None
+    superseded_by: str | None = None
 
 
 # user playbook for agents
@@ -261,10 +254,13 @@ class UserPlaybook(BaseModel):
     source: str | None = None  # source of the interaction that generated this playbook
     source_interaction_ids: list[int] = Field(default_factory=list)
     expanded_terms: str | None = None
+    tags: list[str] | None = None  # None = not yet tagged; [] = tagged, no match
     embedding: EmbeddingVector = []
     source_span: str | None = None
     notes: str | None = None
     reader_angle: str | None = None
+    merged_into: int | None = None
+    superseded_by: int | None = None
 
 
 class ProfileChangeLog(BaseModel):
@@ -274,7 +270,6 @@ class ProfileChangeLog(BaseModel):
     created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
     added_profiles: list[UserProfile]
     removed_profiles: list[UserProfile]
-    mentioned_profiles: list[UserProfile]
 
 
 class AgentPlaybook(BaseModel):
@@ -289,10 +284,13 @@ class AgentPlaybook(BaseModel):
     playbook_status: PlaybookStatus = PlaybookStatus.PENDING
     playbook_metadata: str = ""
     expanded_terms: str | None = None
+    tags: list[str] | None = None  # None = not yet tagged; [] = tagged, no match
     embedding: EmbeddingVector = []
     status: Status | None = (
         None  # used for tracking intermediate states during playbook aggregation. Status.ARCHIVED for playbooks during aggregation process, None for current playbooks
     )
+    merged_into: int | None = None
+    superseded_by: int | None = None
 
 
 class PlaybookOptimizationJob(BaseModel):
@@ -330,6 +328,7 @@ class PlaybookOptimizationCandidate(BaseModel):
     parent_candidate_ids: list[int] = Field(default_factory=list)
     aggregate_score: float | None = None
     is_winner: bool = False
+    metadata_json: str = "{}"
     created_at: int = Field(default_factory=lambda: int(datetime.now(UTC).timestamp()))
 
 
@@ -384,6 +383,7 @@ class AgentPlaybookSourceWindow(BaseModel):
 
 class AgentSuccessEvaluationResult(BaseModel):
     result_id: int = 0
+    user_id: str = ""
     agent_version: str
     session_id: str
     is_success: bool
@@ -398,6 +398,100 @@ class AgentSuccessEvaluationResult(BaseModel):
     embedding: EmbeddingVector = []
 
 
+class PlaybookRetrievalLogItem(BaseModel):
+    """One retrieved agent playbook plus the serve-time attribution snapshot."""
+
+    retrieval_log_item_id: int = 0
+    retrieval_log_id: int = 0
+    ordinal: int
+    agent_playbook_id: int
+    source_user_playbook_ids: list[int] = Field(default_factory=list)
+    source_interaction_ids_by_user_playbook_id: dict[str, list[int]] = Field(
+        default_factory=dict
+    )
+
+
+class PlaybookRetrievalLog(BaseModel):
+    """A retrieval-log header with ordered item rows.
+
+    Used by retrieval-capture consumers to correlate retrieval decisions with
+    downstream outcomes. ``retrieval_log_id`` is assigned by the storage layer;
+    ``shown_items`` stores ids and serve-time attribution snapshots only.
+    """
+
+    retrieval_log_id: int = 0
+    request_id: str
+    session_id: str
+    interaction_id: int | None = None
+    user_id: str
+    query: str | None = None
+    agent_version: str | None = None
+    shown_items: list[PlaybookRetrievalLogItem] = Field(default_factory=list)
+    created_at: int = 0
+
+
+class LineageEvent(BaseModel):
+    """Append-only, content-free provenance record. NEVER carries content/PII.
+
+    Attributes:
+        event_id (int): PK assigned by storage (0 = not yet persisted).
+        org_id (str): Owning org (tenant) — required for RLS / isolation.
+        entity_type (str): One of "profile" | "user_playbook" | "agent_playbook".
+        entity_id (str): The affected record's id, stringified (profile_id is str).
+        op (str): create|revise|merge|aggregate|archive|soft_delete|hard_delete|purge|status_change.
+        prov_relation (str): W3C PROV relation (see spec §14).
+        source_ids (list[str]): Records merged/superseded into entity_id.
+        actor (str): Who/what triggered it (consolidator|reflection|offline_optimizer|...).
+        request_id (str): Triggering request — part of the idempotency key.
+        reason (str): Free-text rationale (no PII).
+        created_at (int): Unix epoch seconds (0 = unset; storage stamps it).
+    """
+
+    event_id: int = 0
+    org_id: str
+    entity_type: str
+    entity_id: str
+    op: str
+    prov_relation: str = ""
+    source_ids: list[str] = []
+    actor: str = ""
+    request_id: str = ""
+    reason: str = ""
+    created_at: int = 0
+    from_status: str | None = None
+    to_status: str | None = None
+    status_namespace: str | None = None
+
+
+class LineageContext(BaseModel):
+    """Caller-supplied intent the storage layer can't infer.
+
+    Required for merge/supersede/aggregate; optional for create/revise/archive.
+    """
+
+    op_kind: str
+    actor: str = ""
+    source_ids: list[str] = []
+    reason: str = ""
+    request_id: str | None = None
+
+
+class RecordRef(BaseModel):
+    """Result of resolve_current — the live survivor's id and whether its body was purged.
+
+    Attributes:
+        id: Primary key of the live survivor record.
+        is_purged: True when the survivor's content body has been blanked by
+            ``purge_content`` (GDPR/erasure).  Any consumer that dereferences the
+            resolved record's content MUST treat ``is_purged=True`` as "erased —
+            skip or treat as absent."  Reading blank content as if it were valid
+            is a silent data-quality bug.
+    """
+
+    id: str
+    is_purged: bool = False
+
+
 class ShareLink(BaseModel):
     """A shareable public link that maps a token to a resource within an org.
 
@@ -563,26 +657,21 @@ class PublishUserInteractionRequest(BaseModel):
     agent_version: str = (
         ""  # this is used for aggregating interactions for generating agent playbooks
     )
-    session_id: str | None = None  # used for grouping requests together
+    session_id: NonEmptyStr  # used for grouping requests together
     skip_aggregation: bool = (
         False  # when True, extract profiles/playbooks but skip aggregation
     )
     force_extraction: bool = False  # when True, bypass all extraction gates (stride_size, cheap pre-filter, LLM should_run) and always run extractors
+    evaluation_only: bool = False  # when True, store for evaluation and permanently exclude from profile/playbook extraction
     override_learning_stall: bool = False  # when True, run extraction even if a provider auth/billing stall is recorded
-    metadata: dict[str, Any] = Field(default_factory=dict)
-    """Per-request annotations stamped by customer integration code.
-
-    Mirrors ``Request.metadata`` — the publish path copies this dict
-    onto the ``Request`` row it creates so the eval pipeline (and the
-    F2 sticky-group aggregator in particular) can read it back from
-    the first request of each session.
 
-    Conventional keys:
-        - ``reflexio_retrieval_enabled`` (bool): F2 group assignment signal.
-
-    Defaults to ``{}`` (never None) for backward compatibility — existing
-    callers that don't pass ``metadata`` keep working unchanged.
-    """
+    @model_validator(mode="after")
+    def validate_evaluation_only(self) -> Self:
+        if self.evaluation_only and self.force_extraction:
+            raise ValueError("evaluation_only cannot be combined with force_extraction")
+        if self.evaluation_only and not self.session_id:
+            raise ValueError("evaluation_only publishes require session_id")
+        return self
 
 
 # publish user interaction response

package/plugin/vendor/reflexio/reflexio/models/api_schema/domain/enums.py

@@ -42,6 +42,10 @@ class Status(str, Enum):  # noqa: UP042 - CURRENT=None is not compatible with St
     ARCHIVE_IN_PROGRESS = (
         "archive_in_progress"  # temporary status during downgrade operation
     )
+    MERGED = "merged"  # tombstone: consolidated into a survivor (merged_into set)
+    SUPERSEDED = (
+        "superseded"  # tombstone: replaced by a new version (superseded_by set)
+    )
 
 
 class OperationStatus(StrEnum):

package/plugin/vendor/reflexio/reflexio/models/api_schema/domain/governance.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+AuditActorType = Literal["api_token", "jwt", "system"]
+AuditOperation = Literal["READ", "EXPORT", "ERASE", "CREATE", "UPDATE", "DELETE"]
+AuditEntityType = Literal[
+    "profile",
+    "user_playbook",
+    "agent_playbook",
+    "interaction",
+    "request",
+    "session",
+    "agent_success_evaluation_result",
+    "playbook_retrieval_log",
+    "org",
+]
+AuditStatus = Literal["ok", "error"]
+PurgeOperationType = Literal["user_erasure", "org_purge"]
+PurgeScopeType = Literal["user", "org"]
+PurgeStatus = Literal["pending", "running", "failed", "complete"]
+PurgeTargetStatus = Literal["pending", "running", "failed", "complete"]
+SubjectBarrierStatus = Literal["erasing", "erased", "failed"]
+
+__all__ = [
+    "AuditActorType",
+    "AuditOperation",
+    "AuditEntityType",
+    "AuditStatus",
+    "PurgeOperationType",
+    "PurgeScopeType",
+    "PurgeStatus",
+    "PurgeTargetStatus",
+    "SubjectBarrierStatus",
+    "AuditEvent",
+    "PurgeOperation",
+    "PurgeOperationTarget",
+    "SubjectWriteBarrier",
+    "UserExportResult",
+    "UserEraseResult",
+]
+
+
+def _now_epoch() -> int:
+    return int(datetime.now(UTC).timestamp())
+
+
+class AuditEvent(BaseModel):
+    org_id: str
+    actor_type: AuditActorType = "system"
+    actor_ref: str | None = None
+    operation: AuditOperation
+    entity_type: AuditEntityType
+    entity_id: str | None = None
+    subject_ref: str | None = None
+    request_ref: str
+    idempotency_key: str | None = None
+    status: AuditStatus = "ok"
+    detail: dict[str, Any] | None = None
+    created_at: int = Field(default_factory=_now_epoch)
+
+
+class PurgeOperation(BaseModel):
+    purge_id: str
+    org_id: str
+    operation_type: PurgeOperationType
+    scope_type: PurgeScopeType
+    subject_ref: str | None = None
+    request_ref: str
+    idempotency_key: str
+    status: PurgeStatus = "pending"
+    error_code: str | None = None
+    error_detail: str | None = None
+    created_at: int = Field(default_factory=_now_epoch)
+    updated_at: int = Field(default_factory=_now_epoch)
+    completed_at: int | None = None
+
+
+class PurgeOperationTarget(BaseModel):
+    purge_id: str
+    target_name: str
+    target_ref: str = ""
+    phase: str
+    status: PurgeTargetStatus = "pending"
+    detail: dict[str, Any] | None = None
+    deleted_count: int = 0
+    error_detail: str | None = None
+    started_at: int | None = None
+    completed_at: int | None = None
+
+
+class SubjectWriteBarrier(BaseModel):
+    org_id: str
+    subject_ref: str
+    purge_id: str
+    status: SubjectBarrierStatus
+    error_code: str | None = None
+    error_detail: str | None = None
+    created_at: int = Field(default_factory=_now_epoch)
+    updated_at: int = Field(default_factory=_now_epoch)
+
+
+class UserExportResult(BaseModel):
+    subject_ref: str
+    export_id: str
+    bundle: dict[str, Any]
+
+
+class UserEraseResult(BaseModel):
+    subject_ref: str
+    purge_id: str
+    status: PurgeStatus
+    deleted_counts: dict[str, int] = Field(default_factory=dict)
+    rebuilt_agent_playbook_ids: list[int] = Field(default_factory=list)

package/plugin/vendor/reflexio/reflexio/models/api_schema/eval_overview_schema.py

@@ -12,6 +12,7 @@ from typing import Literal, Self
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from reflexio.models.api_schema.validators import NonEmptyStr
+from reflexio.models.structured_output import StrictStructuredOutput
 
 HeroStateLiteral = Literal["full", "early", "shadow_off", "empty"]
 BucketLiteral = Literal["day", "week"]
@@ -98,6 +99,24 @@ class ScoreDistribution(BaseModel):
     labels: list[str]
 
 
+class EvaluationSourceSetRequest(BaseModel):
+    """One labeled request-source cohort for evaluation comparison.
+
+    ``sources`` match ``Request.source`` exactly. The empty string is valid and
+    represents requests published without a source.
+    """
+
+    label: NonEmptyStr
+    sources: list[str] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def validate_sources_are_unique(self) -> Self:
+        """Reject duplicate source values within a single set."""
+        if len(set(self.sources)) != len(self.sources):
+            raise ValueError("source set sources must be unique")
+        return self
+
+
 class GetEvaluationOverviewRequest(BaseModel):
     """Input for the overview endpoint.
 
@@ -107,18 +126,34 @@ class GetEvaluationOverviewRequest(BaseModel):
         bucket (BucketLiteral): Granularity of the hero trend buckets.
         include_shadow (bool): When False, skip the shadow-side aggregations
             (cheaper) — the hero will degrade to shadow_off state.
+        source_sets (list[EvaluationSourceSetRequest]): Optional labeled
+            request-source cohorts to compare. Sources are matched exactly
+            against the first request in each evaluated session.
     """
 
     from_ts: int = Field(ge=0)
     to_ts: int = Field(ge=0)
     bucket: BucketLiteral = "week"
     include_shadow: bool = True
+    source_sets: list[EvaluationSourceSetRequest] = Field(default_factory=list)
 
     @model_validator(mode="after")
-    def validate_time_window(self) -> Self:
-        """Ensure the requested time window is ordered."""
+    def validate_request(self) -> Self:
+        """Ensure the requested time window and source sets are valid."""
         if self.from_ts > self.to_ts:
             raise ValueError("from_ts must be <= to_ts")
+        labels = [s.label for s in self.source_sets]
+        if len(set(labels)) != len(labels):
+            raise ValueError("source set labels must be unique")
+        seen_sources: set[str] = set()
+        for source_set in self.source_sets:
+            overlap = seen_sources.intersection(source_set.sources)
+            if overlap:
+                overlap_list = ", ".join(sorted(repr(s) for s in overlap))
+                raise ValueError(
+                    f"source values cannot appear in multiple source sets: {overlap_list}"
+                )
+            seen_sources.update(source_set.sources)
         return self
 
 
@@ -139,41 +174,6 @@ class BraintrustTileRow(BaseModel):
     delta: float
 
 
-class TrendPoint(BaseModel):
-    """One point on a grouped success-rate trend curve (F2).
-
-    Args:
-        ts (int): Unix epoch seconds — bucket start.
-        rate (float): Success rate for sessions in this bucket, [0.0, 1.0].
-        n (int): Session count backing the rate. Must be non-negative.
-    """
-
-    ts: int
-    rate: float
-    n: int = Field(ge=0)
-
-
-class SuccessRateTrendByGroup(BaseModel):
-    """Group-split trend data for the dashboard's dual-curve chart (F2).
-
-    Grouping is by ``Request.metadata.reflexio_retrieval_enabled``, read from
-    the first request of each session in the window. Sessions whose first
-    request has the key absent OR a non-bool value land in ``untagged``.
-
-    Args:
-        treatment (list[TrendPoint]): Curve for sessions where the first
-            request had ``metadata.reflexio_retrieval_enabled = True``.
-        control (list[TrendPoint]): Curve for ``... = False``.
-        untagged (list[TrendPoint]): Curve for sessions where the key is
-            absent or non-bool — surfaced (not silently coerced) so
-            customers can see how many of their sessions are untagged.
-    """
-
-    treatment: list[TrendPoint] = Field(default_factory=list)
-    control: list[TrendPoint] = Field(default_factory=list)
-    untagged: list[TrendPoint] = Field(default_factory=list)
-
-
 class ShadowWinRateTrendPoint(BaseModel):
     """One daily bucket of per-turn shadow-comparison verdicts (F1).
 
@@ -243,18 +243,41 @@ class ShadowWinRateTrend(BaseModel):
     judge_prompt_version: str = Field(default="v1.0.0")
 
 
+class SourceSetEvaluationMetrics(BaseModel):
+    """Metrics for one labeled request-source set."""
+
+    label: str
+    sources: list[str]
+    session_count: int = Field(ge=0)
+    session_ids: list[str] = Field(default_factory=list)
+    success_rate_pp: float
+    buckets: list[HeroBucket]
+    context_tiles: ContextTile
+    score_distribution: ScoreDistribution
+    rule_attribution: list[RuleAttributionRow]
+    braintrust_tiles: list[BraintrustTileRow] = Field(default_factory=list)
+
+
+class SourceSetComparison(BaseModel):
+    """Comparison payload for request-source cohorts."""
+
+    available_sources: list[str] = Field(default_factory=list)
+    sets: list[SourceSetEvaluationMetrics] = Field(default_factory=list)
+    unmatched_session_count: int = Field(default=0, ge=0)
+
+
 class GetEvaluationOverviewResponse(BaseModel):
     hero: HeroBlock
     context_tiles: ContextTile
     rule_attribution: list[RuleAttributionRow]
     score_distribution: ScoreDistribution
     braintrust_tiles: list[BraintrustTileRow] = Field(default_factory=list)
-    success_rate_trend_by_group: SuccessRateTrendByGroup = Field(
-        default_factory=SuccessRateTrendByGroup
-    )
     shadow_win_rate_trend: ShadowWinRateTrend = Field(
         default_factory=ShadowWinRateTrend
     )
+    source_set_comparison: SourceSetComparison = Field(
+        default_factory=SourceSetComparison
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -406,7 +429,7 @@ class GradeOnDemandResponse(BaseModel):
 # ---------------------------------------------------------------------------
 
 
-class ShadowComparisonOutput(BaseModel):
+class ShadowComparisonOutput(StrictStructuredOutput):
     """LLM judge verdict for a per-turn Reflexio-vs-Shadow comparison (F1).
 
     Args:

package/plugin/vendor/reflexio/reflexio/models/api_schema/internal_schema.py

@@ -26,3 +26,22 @@ class SessionDescriptor(NamedTuple):
     session_id: str
     agent_version: str
     source: str
+
+
+class SessionFirstRequest(NamedTuple):
+    """Earliest request metadata for one session."""
+
+    session_id: str
+    user_id: str
+    source: str
+    created_at: int
+
+
+class SessionCitation(NamedTuple):
+    """One cited rule/profile occurrence, keyed by user/session."""
+
+    user_id: str
+    session_id: str
+    kind: str
+    real_id: str
+    title: str

package/plugin/vendor/reflexio/reflexio/models/api_schema/pending_tool_call_schema.py

@@ -3,14 +3,21 @@
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Any
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from reflexio.server.services.storage.storage_base import (
-    PendingToolCallRecord,
-    PendingToolCallStatus,
-)
+if TYPE_CHECKING:
+    from reflexio.server.services.storage.storage_base import PendingToolCallRecord
+
+
+class PendingToolCallStatus(StrEnum):
+    PENDING = "pending"
+    RESOLVED = "resolved"
+    EXPIRED = "expired"
+    SUPERSEDED = "superseded"
+    CANCELLED = "cancelled"
 
 
 class PendingToolCallResponse(BaseModel):