claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/server/services/extraction/plan.py

@@ -0,0 +1,138 @@
+"""Plan-op types, ExtractionCtx, HandlerBundle, and commit-result types for the agentic-v2 pipeline.
+
+Tool handlers append PlanOp instances to ``ctx.plan`` rather than hitting
+storage directly. A deterministic commit stage at ``finish`` (or on
+``max_steps``) runs invariants and applies the valid ops atomically.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Mirrors ProfileTimeToLive — kept as Literal to avoid circular import on enum.
+ProfileTTL = Literal[
+    "one_day", "one_week", "one_month", "one_quarter", "one_year", "infinity"
+]
+
+PlaybookStrength = Literal["hard", "soft"]
+
+
+class _BasePlanOp(BaseModel):
+    """Base class for all PlanOp variants. Discriminated union via ``op``."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class CreateUserProfileOp(_BasePlanOp):
+    op: Literal["create_user_profile"] = "create_user_profile"
+    content: Annotated[str, Field(min_length=1)]
+    ttl: ProfileTTL
+    source_span: Annotated[str, Field(min_length=1)]
+
+
+class DeleteUserProfileOp(_BasePlanOp):
+    op: Literal["delete_user_profile"] = "delete_user_profile"
+    id: Annotated[str, Field(min_length=1)]
+
+
+class CreateUserPlaybookOp(_BasePlanOp):
+    op: Literal["create_user_playbook"] = "create_user_playbook"
+    trigger: Annotated[str, Field(min_length=1)]
+    content: Annotated[str, Field(min_length=1)]
+    rationale: str = ""
+    strength: PlaybookStrength = "soft"
+    source_span: Annotated[str, Field(min_length=1)]
+
+
+class DeleteUserPlaybookOp(_BasePlanOp):
+    op: Literal["delete_user_playbook"] = "delete_user_playbook"
+    id: Annotated[str, Field(min_length=1)]
+
+
+PlanOp = Annotated[
+    CreateUserProfileOp
+    | DeleteUserProfileOp
+    | CreateUserPlaybookOp
+    | DeleteUserPlaybookOp,
+    Field(discriminator="op"),
+]
+
+
+@dataclass
+class ExtractionCtx:
+    """Per-run state for the extraction agent.
+
+    Attributes:
+        user_id: Authenticated user the run is scoped to.
+        agent_version: Agent version from the active config.
+        request_id: Source publish_interaction request UUID — embedded into
+            every profile/playbook this run creates so retrieval can trace
+            back to the originating session. Empty string when called from
+            test contexts that don't have a publish request.
+        plan: Accumulated PlanOps awaiting commit.
+        known_ids: Ids the agent has legitimately seen (from search/get/create
+            handlers). Invariant B checks delete ids against this set.
+        search_count: Number of search_* tool calls. Invariant A gates on this.
+        finished: True once the agent calls the ``finish`` tool.
+    """
+
+    user_id: str
+    agent_version: str
+    request_id: str = ""
+    plan: list = field(
+        default_factory=list
+    )  # list[PlanOp] — type-erased to avoid forward-ref issues
+    known_ids: set[str] = field(default_factory=set)
+    search_count: int = 0
+    finished: bool = False
+    search_answer: str | None = None
+    agent_playbook_status_filter: list[str] | None = None
+    # Compressed rehydration excerpts captured by `read_session_text` calls
+    # during the agent loop. Surfaced verbatim on the response so callers can
+    # include them in downstream context without going through the search
+    # agent's natural-language `finish(answer=…)` synthesis (which paraphrases
+    # operands and loses fidelity).
+    rehydrated_excerpts: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class HandlerBundle:
+    """Glue so tool handlers can access shared services through one param.
+
+    The run_tool_loop primitive passes a single ``ctx`` param to tool handlers;
+    handlers in tools.py need access to BaseStorage and an ExtractionCtx. A few
+    handlers (e.g., the rehydration tool) additionally call back into the LLM
+    layer for in-tool denoising — those receive ``llm_client`` and
+    ``prompt_manager`` here. The tool-loop caller builds one of these before
+    driving the loop.
+
+    Args:
+        storage: BaseStorage handle.
+        ctx: ExtractionCtx with per-run state.
+        llm_client: Optional LiteLLMClient for in-tool LLM calls (e.g.
+            compression). ``None`` in test paths that don't exercise tools
+            requiring LLM completions.
+        prompt_manager: Optional PromptManager for rendering in-tool prompts.
+            Same ``None`` semantics as ``llm_client``.
+    """
+
+    storage: object
+    ctx: ExtractionCtx
+    llm_client: object | None = None
+    prompt_manager: object | None = None
+
+
+class Violation(BaseModel):
+    code: Literal["A", "B", "D", "E", "F", "H", "J", "K"]
+    severity: Literal["hard", "soft"]
+    affected_op_indices: list[int]
+    msg: str
+
+
+class CommitResult(BaseModel):
+    applied: list[PlanOp]
+    violations: list[Violation]
+    outcome: Literal["finish_tool", "max_steps", "error"]

package/plugin/vendor/reflexio/reflexio/server/services/extraction/prior_answer_search.py

@@ -0,0 +1,217 @@
+"""Prior Knowledge context for resumable extraction agents."""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from reflexio.server.services.storage.storage_base import (
+    BaseStorage,
+    PendingToolCallStatus,
+    PriorAnswerMatch,
+    build_scope_hash,
+    canonical_json,
+    human_feedback_scope,
+)
+
+logger = logging.getLogger(__name__)
+
+ASK_HUMAN_TOOL_NAME = "ask_human"
+MAX_KNOWLEDGE_QUERY_CHARS = 4_000
+MAX_RESULT_CHARS = 1_200
+
+
+def _content_to_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                text = item.get("text") or item.get("content")
+                if isinstance(text, str):
+                    parts.append(text)
+            elif isinstance(item, str):
+                parts.append(item)
+        return "\n".join(parts)
+    return str(content)
+
+
+def build_knowledge_need_query(
+    *,
+    extractor_kind: str,
+    extractor_config: Any,
+    source: str | None,
+    agent_version: str | None,
+    messages: list[dict[str, Any]],
+) -> str:
+    """Build a compact question-like query for prior human requests."""
+    definition = getattr(extractor_config, "extraction_definition_prompt", "") or ""
+    recent_messages = "\n".join(
+        _content_to_text(message.get("content")) for message in messages[-4:]
+    )
+    query = "\n".join(
+        [
+            f"Extractor kind: {extractor_kind}",
+            f"Source: {source or 'unknown'}",
+            f"Agent version: {agent_version or 'unknown'}",
+            f"Extraction definition: {definition}",
+            "Recent extraction context:",
+            recent_messages,
+            "Find prior human clarification questions or answers that may help this extraction.",
+        ]
+    )
+    return query[:MAX_KNOWLEDGE_QUERY_CHARS]
+
+
+def _query_embedding(storage: BaseStorage, query: str) -> list[float] | None:
+    get_embedding = getattr(storage, "_get_embedding", None)
+    if not callable(get_embedding):
+        return None
+    try:
+        embedding = get_embedding(query, purpose="query")
+    except TypeError:
+        embedding = get_embedding(query)
+    except Exception as exc:  # pragma: no cover - backend logs details elsewhere
+        logger.warning(
+            "event=prior_answer_query_embedding_failed error_type=%s error=%s",
+            type(exc).__name__,
+            exc,
+        )
+        return None
+    return embedding if isinstance(embedding, list) else None
+
+
+def find_prior_answer_matches(
+    *,
+    storage: BaseStorage,
+    org_id: str,
+    knowledge_need_query: str,
+    limit: int = 8,
+    similarity_threshold: float = 0.0,
+    exclude_pending_tool_call_ids: set[str] | None = None,
+) -> list[PriorAnswerMatch]:
+    scope = human_feedback_scope(org_id)
+    query_embedding = _query_embedding(storage, knowledge_need_query)
+    matches = storage.search_prior_tool_calls(
+        org_id=org_id,
+        scope_hash=build_scope_hash(scope),
+        tool_name=ASK_HUMAN_TOOL_NAME,
+        query_embedding=query_embedding,
+        now=datetime.now(UTC),
+        limit=limit,
+    )
+    excluded = exclude_pending_tool_call_ids or set()
+    if excluded:
+        # On resume, the run's own just-resolved calls are injected separately
+        # as explicit "Agent Builder provided additional information" messages;
+        # excluding them here avoids surfacing the same answer twice.
+        matches = [
+            match for match in matches if match.pending_tool_call_id not in excluded
+        ]
+    if similarity_threshold <= 0.0:
+        return matches
+    return [
+        match
+        for match in matches
+        if match.similarity is None or match.similarity >= similarity_threshold
+    ]
+
+
+def _format_datetime(value: datetime | None) -> str:
+    return value.date().isoformat() if value else "unknown"
+
+
+def _format_result(result: dict[str, Any] | None) -> str:
+    text = canonical_json(result or {})
+    if len(text) > MAX_RESULT_CHARS:
+        return f"{text[:MAX_RESULT_CHARS]}..."
+    return text
+
+
+def format_prior_knowledge_context(matches: list[PriorAnswerMatch]) -> str | None:
+    """Return a seed-context block, or None when there is no prior knowledge."""
+    if not matches:
+        return None
+
+    resolved = [
+        match for match in matches if match.status == PendingToolCallStatus.RESOLVED
+    ]
+    pending = [
+        match for match in matches if match.status == PendingToolCallStatus.PENDING
+    ]
+    lines = [
+        "Prior Knowledge for org-scoped human feedback",
+        "Use these entries only if they are relevant to the current extraction window.",
+    ]
+    if resolved:
+        lines.append("")
+        lines.append("Resolved answers:")
+        for match in resolved:
+            lines.extend(
+                [
+                    f"- source_request_id: {match.pending_tool_call_id}",
+                    f"  question: {match.question_text}",
+                    f"  answer: {_format_result(match.result)}",
+                    f"  resolved_at: {_format_datetime(match.resolved_at)}",
+                    f"  valid_until: {_format_datetime(match.valid_until)}",
+                ]
+            )
+    if pending:
+        lines.append("")
+        lines.append(
+            "Pending requests: only call attach_pending_info_request with one of "
+            "the pending_tool_call_id values in this section when the pending request "
+            "is relevant and this run should resume when answered."
+        )
+        for match in pending:
+            lines.extend(
+                [
+                    f"- pending_tool_call_id: {match.pending_tool_call_id}",
+                    f"  question: {match.question_text}",
+                    f"  answer_format: {match.answer_format or 'unspecified'}",
+                    f"  expires_at: {_format_datetime(match.expires_at)}",
+                ]
+            )
+    return "\n".join(lines)
+
+
+def append_prior_knowledge_context(
+    *,
+    messages: list[dict[str, Any]],
+    storage: BaseStorage,
+    org_id: str,
+    extractor_kind: str,
+    extractor_config: Any,
+    source: str | None,
+    agent_version: str | None,
+    limit: int = 8,
+    similarity_threshold: float = 0.0,
+    exclude_pending_tool_call_ids: set[str] | None = None,
+) -> list[dict[str, Any]]:
+    query = build_knowledge_need_query(
+        extractor_kind=extractor_kind,
+        extractor_config=extractor_config,
+        source=source,
+        agent_version=agent_version,
+        messages=messages,
+    )
+    matches = find_prior_answer_matches(
+        storage=storage,
+        org_id=org_id,
+        knowledge_need_query=query,
+        limit=limit,
+        similarity_threshold=similarity_threshold,
+        exclude_pending_tool_call_ids=exclude_pending_tool_call_ids,
+    )
+    context = format_prior_knowledge_context(matches)
+    if context is None:
+        return messages
+    logger.info(
+        "event=prior_answer_injected org_id=%s extractor_kind=%s count=%d",
+        org_id,
+        extractor_kind,
+        len(matches),
+    )
+    return [*messages, {"role": "user", "content": context}]