claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/server/services/profile/profile_generation_service_utils.py

@@ -0,0 +1,290 @@
+"""Utility functions for the profile generation service"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from reflexio.models.api_schema.common import NEVER_EXPIRES_TIMESTAMP
+from reflexio.models.api_schema.internal_schema import RequestInteractionDataModel
+from reflexio.models.api_schema.service_schemas import (
+    ProfileTimeToLive,
+    UserProfile,
+)
+from reflexio.server.prompt.prompt_manager import PromptManager
+from reflexio.server.services.service_utils import (
+    MessageConstructionConfig,
+    PromptConfig,
+    construct_messages_from_interactions,
+    extract_interactions_from_request_interaction_data_models,
+    format_sessions_to_history_string,
+)
+
+
+class ProfileUpdates(BaseModel):
+    add_profiles: list[UserProfile] = []
+    delete_profiles: list[UserProfile] = []
+    mention_profiles: list[UserProfile] = []
+
+    @field_validator(
+        "add_profiles", "delete_profiles", "mention_profiles", mode="before"
+    )
+    @classmethod
+    def coerce_none_to_list(cls, v: Any) -> list[UserProfile]:
+        return v if v is not None else []
+
+
+class ProfileGenerationRequest(BaseModel):
+    user_id: str
+    request_id: str
+    source: str | None = None
+    rerun_start_time: int | None = None  # Unix timestamp for rerun flows
+    rerun_end_time: int | None = None  # Unix timestamp for rerun flows
+    auto_run: bool = (
+        True  # True for regular flow (checks stride_size), False for rerun/manual
+    )
+    force_extraction: bool = False  # when True, bypass all extraction gates (stride_size, cheap pre-filter, LLM should_run)
+
+
+@dataclass(frozen=True)
+class ProfileGenerationServiceConstants:
+    PROFILE_EXTRACTORS_CONFIG_NAME = "profile_extractor_config"
+    # ===============================
+    # prompt ids
+    # ===============================
+    PROFILE_SHOULD_GENERATE_PROMPT_ID = "profile_should_generate"
+    PROFILE_SHOULD_GENERATE_OVERRIDE_PROMPT_ID = "profile_should_generate_override"
+    PROFILE_UPDATE_MAIN_PROMPT_ID = "profile_update_main"
+    PROFILE_UPDATE_INSTRUCTION_START_PROMPT_ID = "profile_update_instruction_start"
+    PROFILE_UPDATE_INSTRUCTION_PROMPT_ID = "profile_update_instruction"
+
+
+# ===============================
+# Pydantic classes for profile_update_main prompt output schema
+# ===============================
+
+
+class ProfileAddItem(BaseModel):
+    """
+    Schema for a single profile item to be added.
+
+    Attributes:
+        content (str): The profile content based on content definition
+        time_to_live (str): Time to live for the profile - one of: 'one_day', 'one_week', 'one_month', 'one_quarter', 'one_year', 'infinity'
+        metadata (str, optional): Metadata extracted for the profile based on metadata definition
+    """
+
+    content: str = Field(description="Profile content based on content definition")
+    time_to_live: Literal[
+        "one_day", "one_week", "one_month", "one_quarter", "one_year", "infinity"
+    ] = Field(
+        description="Time to live for the profile - determines when the profile expires"
+    )
+    metadata: str | None = Field(
+        default=None,
+        description="Metadata extracted for the profile based on metadata definition",
+    )
+    source_span: str | None = Field(
+        default=None,
+        description="Verbatim excerpt from the source that most directly supports this profile item",
+    )
+    notes: str | None = Field(
+        default=None,
+        description="Free-form extraction notes — confidence, caveats, or alternative readings",
+    )
+    reader_angle: str | None = Field(
+        default=None,
+        description="The extraction perspective or reader role that surfaced this item",
+    )
+
+    # OpenAI structured output requires explicit schema constraints
+    model_config = ConfigDict(
+        extra="allow",
+        json_schema_extra={"additionalProperties": False},
+    )
+
+
+class ProfileUpdateOutput(BaseModel):
+    """
+    Legacy output schema for profile_update_main prompt (kept for backward compatibility).
+    Represents the complete set of profile updates including additions, deletions, and mentions.
+
+    Attributes:
+        add (list[ProfileAddItem], optional): List of new profiles to be added
+        delete (list[str], optional): List of existing profile contents to be deleted
+        mention (list[str], optional): List of existing profile contents that were mentioned/referenced
+    """
+
+    add: list[ProfileAddItem] | None = Field(
+        default=None,
+        description="List of new profiles to be added with their content, time to live, and optional metadata",
+    )
+    delete: list[str] | None = Field(
+        default=None,
+        description="List of existing profile contents to be deleted (profiles that are contradicted by new interactions)",
+    )
+    mention: list[str] | None = Field(
+        default=None,
+        description="List of existing profile contents that were mentioned or referenced in the new interactions",
+    )
+
+    # OpenAI schema parsing requires explicitly forbidding additional properties
+    model_config = ConfigDict(
+        extra="allow",
+        json_schema_extra={"additionalProperties": False},
+    )
+
+
+class StructuredProfilesOutput(BaseModel):
+    """
+    Output schema for extraction-only profile extraction.
+    Only extracts profiles — no delete/mention operations.
+
+    Attributes:
+        profiles (list[ProfileAddItem], optional): List of extracted profiles with content, time_to_live, and optional metadata
+    """
+
+    profiles: list[ProfileAddItem] | None = Field(
+        default=None,
+        description="List of extracted profiles with content, time_to_live, and optional metadata",
+    )
+
+    model_config = ConfigDict(
+        extra="allow",
+        json_schema_extra={"additionalProperties": False},
+    )
+
+
+def calculate_expiration_timestamp(
+    last_modified_timestamp: int, profile_time_to_live: ProfileTimeToLive
+) -> int:
+    """
+    Calculate the expiration timestamp for a profile based on the last modified timestamp and the profile time to live.
+    Args:
+        last_modified_timestamp (int): The timestamp of the last modification of the profile.
+        profile_time_to_live (ProfileTimeToLive): The time to live of the profile.
+    Returns:
+        The expiration timestamp for the profile.
+    """
+    if profile_time_to_live == ProfileTimeToLive.INFINITY:
+        return NEVER_EXPIRES_TIMESTAMP
+
+    last_modified_datetime = datetime.fromtimestamp(last_modified_timestamp)
+    if profile_time_to_live == ProfileTimeToLive.ONE_DAY:
+        expiration_timestamp = last_modified_datetime + timedelta(days=1)
+    elif profile_time_to_live == ProfileTimeToLive.ONE_WEEK:
+        expiration_timestamp = last_modified_datetime + timedelta(days=7)
+    elif profile_time_to_live == ProfileTimeToLive.ONE_MONTH:
+        expiration_timestamp = last_modified_datetime + timedelta(days=30)
+    elif profile_time_to_live == ProfileTimeToLive.ONE_QUARTER:
+        expiration_timestamp = last_modified_datetime + timedelta(days=90)
+    elif profile_time_to_live == ProfileTimeToLive.ONE_YEAR:
+        expiration_timestamp = last_modified_datetime + timedelta(days=365)
+    else:
+        raise ValueError(f"Invalid profile time to live: {profile_time_to_live}")
+    return int(expiration_timestamp.timestamp())
+
+
+def check_string_token_overlap(str1: str, str2: str, threshold: float = 0.7) -> bool:
+    """
+    Check if two strings have significant token overlap, indicating they might be referring to the same thing.
+    This is useful for fuzzy matching when exact string matching is too strict.
+
+    Args:
+        str1 (str): First string to compare
+        str2 (str): Second string to compare
+        threshold (float): Minimum overlap ratio required to consider strings as matching (0.0 to 1.0)
+
+    Returns:
+        bool: True if strings have significant overlap, False otherwise
+    """
+    # Normalize strings: lowercase and split into tokens
+    tokens1 = set(str1.lower().split())
+    tokens2 = set(str2.lower().split())
+
+    # Calculate overlap
+    if not tokens1 or not tokens2:
+        return False
+
+    # Calculate Jaccard similarity
+    intersection = len(tokens1.intersection(tokens2))
+
+    # Calculate overlap ratio
+    overlap_ratio = max(intersection / len(tokens1), intersection / len(tokens2))
+
+    return overlap_ratio >= threshold
+
+
+def construct_profile_extraction_messages_from_sessions(
+    prompt_manager: PromptManager,
+    request_interaction_data_models: list[RequestInteractionDataModel],
+    existing_profiles: list[UserProfile],
+    agent_context_prompt: str,
+    context_prompt: str,
+    extraction_definition_prompt: str,
+    metadata_definition_prompt: str | None = None,
+) -> list[dict]:
+    """
+    Construct LLM messages for profile extraction from sessions.
+
+    This function uses the shared message construction interface to build messages
+    with a system prompt and a final user prompt specific to profile extraction.
+    Interactions are formatted grouped by session.
+
+    Args:
+        prompt_manager: The prompt manager for rendering prompt templates
+        request_interaction_data_models: List of request interaction groups to extract profiles from
+        existing_profiles: List of existing user profiles for context
+        agent_context_prompt: Context about the agent for system message
+        context_prompt: Additional context for system message
+        extraction_definition_prompt: Definition of what profiles should contain
+        metadata_definition_prompt: Optional definition for profile metadata
+
+    Returns:
+        list[dict]: List of messages ready for profile extraction
+    """
+    # Format existing profiles for the final prompt
+    formatted_existing_profiles = ", ".join(
+        [profile.content for profile in existing_profiles]
+    )
+
+    # Configure system message (before interactions)
+    # Stable content (instructions, examples, definitions) goes in system message for token caching
+    system_config = PromptConfig(
+        prompt_id=ProfileGenerationServiceConstants.PROFILE_UPDATE_INSTRUCTION_START_PROMPT_ID,
+        variables={
+            "agent_context_prompt": agent_context_prompt,
+            "context_prompt": context_prompt,
+            "extraction_definition_prompt": extraction_definition_prompt,
+            "metadata_definition_prompt": metadata_definition_prompt,
+        },
+    )
+
+    # Configure final user message (after interactions)
+    # Only dynamic per-call data goes in user message
+    user_config = PromptConfig(
+        prompt_id=ProfileGenerationServiceConstants.PROFILE_UPDATE_MAIN_PROMPT_ID,
+        variables={
+            "existing_profiles": formatted_existing_profiles,
+            "interactions": format_sessions_to_history_string(
+                request_interaction_data_models
+            ),
+        },
+    )
+
+    # Extract flat interactions for message construction (needed for image handling)
+    interactions = extract_interactions_from_request_interaction_data_models(
+        request_interaction_data_models
+    )
+
+    # Use shared message construction
+    config = MessageConstructionConfig(
+        prompt_manager=prompt_manager,
+        system_prompt_config=system_config,
+        user_prompt_config=user_config,
+    )
+
+    return construct_messages_from_interactions(interactions, config)

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

@@ -0,0 +1,17 @@
+"""Reflection service: critique-and-revise of cited memories after publish."""
+
+from reflexio.server.services.reflection.reflection_service import ReflectionService
+from reflexio.server.services.reflection.reflection_service_utils import (
+    ReflectionDecision,
+    ReflectionOutput,
+    ReflectionResult,
+    ReflectionServiceRequest,
+)
+
+__all__ = [
+    "ReflectionService",
+    "ReflectionServiceRequest",
+    "ReflectionDecision",
+    "ReflectionOutput",
+    "ReflectionResult",
+]

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

@@ -0,0 +1,247 @@
+"""LLM call that proposes per-citation reflection decisions."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from reflexio.server.llm.litellm_client import LiteLLMClient
+from reflexio.server.llm.model_defaults import ModelRole, resolve_model_name
+from reflexio.server.services.reflection.reflection_service_utils import (
+    ReflectionOutput,
+)
+from reflexio.server.services.service_utils import (
+    log_llm_messages,
+    log_model_response,
+)
+from reflexio.server.site_var.site_var_manager import SiteVarManager
+
+if TYPE_CHECKING:
+    from reflexio.models.api_schema.domain.entities import (
+        Interaction,
+        UserPlaybook,
+        UserProfile,
+    )
+    from reflexio.server.api_endpoints.request_context import RequestContext
+
+logger = logging.getLogger(__name__)
+
+REFLECTION_TIMEOUT_SECONDS = 300
+REFLECTION_MAX_RETRIES = 1
+REFLECTION_PROMPT_ID = "memory_reflection"
+
+
+class ReflectionExtractor:
+    """Build the reflection prompt and ask the LLM for decisions.
+
+    Thin wrapper around one ``LiteLLMClient`` call using
+    ``ReflectionOutput`` as the structured-output schema. Does not touch
+    storage.
+    """
+
+    def __init__(
+        self,
+        request_context: RequestContext,
+        llm_client: LiteLLMClient,
+        agent_context: str,
+        model_override: str | None,
+    ):
+        """Build a new extractor.
+
+        Args:
+            request_context (RequestContext): For prompt manager and
+                config access.
+            llm_client (LiteLLMClient): Shared LLM client.
+            agent_context (str): Agent-context prompt fragment from
+                config (free-form text describing the agent).
+            model_override (str | None): If set, used directly. Otherwise
+                falls back to ``LLMConfig.generation_model_name`` and the
+                site default for ``ModelRole.GENERATION``.
+        """
+        self.request_context = request_context
+        self.client = llm_client
+        self.agent_context = agent_context
+        self.model_name = self._resolve_model(model_override)
+
+    def _resolve_model(self, model_override: str | None) -> str:
+        config = self.request_context.configurator.get_config()
+        llm_config = config.llm_config if config else None
+        api_key_config = config.api_key_config if 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.GENERATION,
+            site_var_value=site_var.get("default_generation_model_name"),
+            config_override=(
+                model_override
+                or (llm_config.generation_model_name if llm_config else None)
+            ),
+            api_key_config=api_key_config,
+        )
+
+    def run(
+        self,
+        *,
+        window_interactions: list[Interaction],
+        cited_profiles: list[UserProfile],
+        cited_user_playbooks: list[UserPlaybook],
+        horizon_by_key: dict[tuple[str, str], bool] | None = None,
+    ) -> ReflectionOutput:
+        """Render the prompt, call the LLM, return parsed output.
+
+        Returns an empty ``ReflectionOutput`` when nothing to consider
+        or when the LLM response cannot be parsed. LLM exceptions
+        propagate — the calling service decides whether to swallow.
+        """
+        if not cited_profiles and not cited_user_playbooks:
+            return ReflectionOutput()
+
+        per_citation_context = _build_per_citation_context(
+            cited_profiles=cited_profiles,
+            cited_user_playbooks=cited_user_playbooks,
+            horizon_by_key=horizon_by_key or {},
+        )
+
+        rendered = self.request_context.prompt_manager.render_prompt(
+            REFLECTION_PROMPT_ID,
+            {
+                "agent_context": self.agent_context or "",
+                "window_interactions_json": _interactions_to_json(window_interactions),
+                "cited_profiles_json": _profiles_to_json(cited_profiles),
+                "cited_user_playbooks_json": _playbooks_to_json(cited_user_playbooks),
+                "per_citation_context_json": per_citation_context,
+            },
+        )
+        messages = [{"role": "user", "content": rendered}]
+
+        logger.info(
+            "event=reflection_llm_start cited_profiles=%d cited_playbooks=%d "
+            "window_interactions=%d model=%s",
+            len(cited_profiles),
+            len(cited_user_playbooks),
+            len(window_interactions),
+            self.model_name,
+        )
+        log_llm_messages(logger, "Memory reflection", messages)
+
+        response = self.client.generate_chat_response(
+            messages=messages,
+            model=self.model_name,
+            response_format=ReflectionOutput,
+            timeout=REFLECTION_TIMEOUT_SECONDS,
+            max_retries=REFLECTION_MAX_RETRIES,
+        )
+        log_model_response(logger, "Memory reflection model response", response)
+
+        if isinstance(response, ReflectionOutput):
+            return response
+        logger.warning(
+            "event=reflection_llm_unparsed response_type=%s",
+            type(response).__name__,
+        )
+        return ReflectionOutput()
+
+
+def _interactions_to_json(interactions: list[Interaction]) -> str:
+    payload: list[dict[str, Any]] = [
+        {
+            "interaction_id": i.interaction_id,
+            "request_id": i.request_id,
+            "role": i.role,
+            "content": i.content,
+            "tools_used": (
+                [t.model_dump() for t in i.tools_used] if i.tools_used else []
+            ),
+            "citations": [c.model_dump() for c in i.citations] if i.citations else [],
+            "created_at": i.created_at,
+        }
+        for i in interactions
+    ]
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _profiles_to_json(profiles: list[UserProfile]) -> str:
+    payload = [
+        {
+            "profile_id": p.profile_id,
+            "content": p.content,
+            "profile_time_to_live": p.profile_time_to_live.value,
+            "custom_features": p.custom_features,
+            "source": p.source,
+            "last_modified_timestamp": p.last_modified_timestamp,
+        }
+        for p in profiles
+    ]
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _playbooks_to_json(playbooks: list[UserPlaybook]) -> str:
+    """Serialize cited playbooks for the reflection prompt.
+
+    The prompt reads each rule's orientation directly from its ``content``
+    wording — no derived ``polarity`` hint is injected (that would re-derive
+    polarity, which is retired under LLM-judged orientation).
+
+    Args:
+        playbooks (list[UserPlaybook]): The cited playbooks to serialize.
+
+    Returns:
+        str: JSON array string with one object per cited playbook.
+    """
+    payload = [
+        {
+            "user_playbook_id": p.user_playbook_id,
+            "playbook_name": p.playbook_name,
+            "content": p.content,
+            "trigger": p.trigger,
+            "rationale": p.rationale,
+            "source": p.source,
+        }
+        for p in playbooks
+    ]
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _build_per_citation_context(
+    *,
+    cited_profiles: list[UserProfile],
+    cited_user_playbooks: list[UserPlaybook],
+    horizon_by_key: dict[tuple[str, str], bool],
+) -> str:
+    """Serialize per-citation horizon flags into a JSON string for the prompt.
+
+    For each cited profile/playbook, emits an object with target_kind,
+    target_id, and has_full_horizon. ``has_full_horizon`` defaults to
+    True when the citation key isn't in ``horizon_by_key`` (defensive
+    fallback — the caller normally populates the dict from
+    _filter_citations_by_horizon).
+
+    Args:
+        cited_profiles (list[UserProfile]): Profile citations to include.
+        cited_user_playbooks (list[UserPlaybook]): Playbook citations to include.
+        horizon_by_key (dict[tuple[str, str], bool]): Maps (kind, id) to
+            has_full_horizon flag.
+
+    Returns:
+        str: JSON array string with per-citation horizon context.
+    """
+    payload: list[dict[str, Any]] = [
+        {
+            "target_kind": "profile",
+            "target_id": p.profile_id,
+            "has_full_horizon": horizon_by_key.get(("profile", p.profile_id), True),
+        }
+        for p in cited_profiles
+    ]
+    payload.extend(
+        {
+            "target_kind": "playbook",
+            "target_id": str(pb.user_playbook_id),
+            "has_full_horizon": horizon_by_key.get(
+                ("playbook", str(pb.user_playbook_id)), True
+            ),
+        }
+        for pb in cited_user_playbooks
+    )
+    return json.dumps(payload, ensure_ascii=False, indent=2)