Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

5.6 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Shared contract for memory extraction output protocols."""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any

from pydantic import BaseModel

from openviking.session.memory.dataclass import MemoryFile, MemoryTypeSchema
from openviking.session.memory.extraction_output_protocol import prompt_fragments as prompts
from openviking.session.memory.merge_op import FieldType, MergeOp


class ExtractionOutputProtocolError(ValueError):
    """A model response does not satisfy the selected output protocol."""

    def __init__(self, message: str, *, allow_tool_retry: bool = False) -> None:
        super().__init__(message)
        # True when the failure means "the model tried to read/search from the
        # write-only SDK"; the loop should re-open native tools for the retry.
        self.allow_tool_retry = allow_tool_retry


@dataclass(slots=True)
class ExtractionOutputContext:
    operations_model: type[BaseModel]
    schemas: tuple[MemoryTypeSchema, ...]
    page_id_map: Any
    read_file_contents: dict[str, MemoryFile]
    link_enabled: bool
    role_scope: Any | None = None
    available_tools: tuple[str, ...] = ()
    template_context: dict[str, Any] = field(default_factory=dict)

    @property
    def inspection_tools(self) -> tuple[str, ...]:
        """Native inspection tools in canonical prompt order."""
        return tuple(name for name in ("search", "read") if name in self.available_tools)

    @property
    def add_only(self) -> bool:
        """Whether every selected schema only creates new memory records."""
        return bool(self.schemas) and all(
            getattr(schema, "operation_mode", "upsert") == "add_only" for schema in self.schemas
        )

    @property
    def supports_string_patch(self) -> bool:
        """Whether an upsert schema exposes an existing string's edit/drop methods."""
        return any(
            getattr(schema, "operation_mode", "upsert") != "add_only"
            and any(
                field.field_type == FieldType.STRING and field.merge_op == MergeOp.PATCH
                for field in getattr(schema, "fields", ())
            )
            for schema in self.schemas
        )


class ExtractionOutputProtocol(ABC):
    """Render and parse one model-facing extraction output protocol."""

    name: str

    def render_context_rules(self, context: ExtractionOutputContext) -> str:
        """Render shared read/patch guidance without exposing unavailable tools."""
        read_rules = prompts.READ_FORMAT_RULES if "read" in context.inspection_tools else ""
        patch_rules = prompts.PATCH_CONTEXT_RULES if context.supports_string_patch else ""
        return "".join((read_rules, patch_rules))

    @abstractmethod
    def render_contract(self, context: ExtractionOutputContext) -> str:
        """Render the output API/schema shown to the model."""

    @abstractmethod
    def render_reference_rules(self, context: ExtractionOutputContext) -> str:
        """Render rules for referring to existing and newly created memories."""

    @abstractmethod
    def parse(
        self, content: str, context: ExtractionOutputContext
    ) -> tuple[Any | None, str | None]:
        """Parse model output into the shared dynamic operations model."""

    @abstractmethod
    def render_final_instruction(self, context: ExtractionOutputContext) -> str:
        """Render the instruction used when tool iterations are exhausted."""

    @abstractmethod
    def render_format_retry(self, error: str | None = None) -> str:
        """Render guidance after output parsing fails."""

    @abstractmethod
    def render_patch_repair(self, patch_errors: list[dict[str, Any]]) -> str:
        """Render guidance after a patch cannot be applied."""

    @abstractmethod
    def render_resolution_repair(self, issues: list[dict[str, Any]]) -> str:
        """Render guidance after event operations fail to resolve a write target.

        The loop preserves every already-successful operation and asks the model
        to re-emit only the corrected event operations, so the wording MUST match
        this protocol's own output shape (JSON object vs restricted Python SDK).
        """

    def render_new_bindings(self, context: ExtractionOutputContext, *, source: str) -> str:
        """Render newly available existing-memory references, if the protocol needs them."""
        del context, source
        return ""

    @abstractmethod
    def render_tool_result_messages(
        self,
        context: ExtractionOutputContext,
        *,
        call_id: str | int,
        tool_name: str,
        params: dict[str, Any],
        result: Any,
        source: str,
    ) -> list[dict[str, Any]]:
        """Render one completed tool invocation into model-facing context."""

    def render_prefetch_messages(
        self,
        messages: list[dict[str, Any]],
        context: ExtractionOutputContext,
    ) -> list[dict[str, Any]]:
        """Render provider-prefetched context in this protocol's model-facing form."""
        del context
        return list(messages)

    def normalize_provider_instruction(self, instruction: str) -> str:
        """Adapt provider-specific output wording to this protocol."""
        return instruction

    def describe_empty_response(self) -> str | None:
        """Return the parse-error text for an empty model response, if any."""
        return None

    def keep_tools_enabled_after_parse_error(self, error: str | None) -> bool:
        """Return whether native tools should remain available for the retry."""
        del error
        return False