Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Wire adapters preserve native history; only executable calls are normalized.
Adapters hold everything the gateway knows about one wire protocol. They assemble
upstream replies, for relayed responses as well as the hidden tool loop, and
project the loop's visible events. They do not execute tools, own budgets, or
access storage. The shared loop owns those steps.
"""
import copy
import functools
import itertools
import uuid
from abc import ABC, abstractmethod
from collections.abc import Sequence
from dataclasses import dataclass
import orjson
from ..notices import TOOL_NOTICE, without_recall_notice
from ..protocols import prefix_chain, usage_of
PREFIX = "openviking_"
# None is the Chat Completions [DONE] marker; all other events are native JSON.
StreamEvent = dict | None
# Reasoning counts against these output caps, and some models reason without being
# asked, so a summary request first asks for this room beyond its own text. Models
# with a smaller output limit reject that cap, and the kernel retries without it.
SUMMARY_HEADROOM = 16000
class ToolLoopError(Exception):
def __init__(self, reason, status=502, content=None, headers=None):
super().__init__(reason)
self.status, self.content, self.headers = status, content, headers or {}
class SummaryError(Exception):
"""A summary request that produced no usable summary; ``reason`` becomes a metric."""
def __init__(self, reason):
super().__init__(reason)
self.reason = reason
def append(target, key, text):
"""``target[key] += text``, in linear time over a whole stream of deltas."""
value = target.get(key) or ""
# Without the dict's reference the string is the local's alone, so CPython grows it
# in place instead of copying everything streamed so far for every delta.
target[key] = ""
try:
value += text
finally:
target[key] = value
def merge_delta(target, delta):
for key, value in delta.items():
if value is None:
target.setdefault(key, None)
elif isinstance(value, dict):
if not isinstance(target.get(key), dict):
target[key] = {}
merge_delta(target[key], value)
elif isinstance(value, str) and key not in {"role", "type", "id"}:
append(target, key, value)
elif isinstance(value, list):
target.setdefault(key, []).extend(copy.deepcopy(value))
else:
target[key] = copy.deepcopy(value)
def add_usage(total, usage):
"""Sum per-round usage; a null in one round never erases another's counts."""
for key, value in usage.items():
if value is None:
continue
if isinstance(value, dict):
add_usage(total.setdefault(key, {}), value)
# Flags such as OpenRouter's is_byok are kept, not summed.
elif isinstance(value, (int, float)) and not isinstance(value, bool):
total[key] = total.get(key, 0) + value
else:
total[key] = value
def merge_usage(total, usage):
"""Overlay a later usage event; nulls, and zeros over counts, never erase earlier ones."""
total.update({k: v for k, v in usage.items() if v is not None and (v or not total.get(k))})
def without(value, path):
"""A copy of ``value`` without the dotted ``path``; everything else is shared."""
key, _, rest = path.partition(".")
if key not in value or (rest and not isinstance(value[key], dict)):
return value
if not rest:
return {k: v for k, v in value.items() if k != key}
return {**value, key: without(value[key], rest)}
def append_text(message, field, text, kind, joins_strings=False):
"""Append text to ``message[field]``; string content becomes text blocks unless joined."""
content = message.get(field, "")
if joins_strings and isinstance(content, str):
message[field] = content + "\n\n" + text
return
if isinstance(content, str):
content = [{"type": kind, "text": content}]
message[field] = [*content, {"type": kind, "text": text}]
def sse(value):
return b"data: " + orjson.dumps(value) + b"\n\n"
def call(identifier, name, arguments):
return {
"id": identifier,
"type": "function",
"function": {"name": name, "arguments": arguments},
}
def edit_text(content, edit, first=False):
"""``content`` with ``edit`` applied to its text, or ``content`` itself if unchanged.
A string is edited whole. In a list ``edit`` gets the text of every part that has some,
or with ``first`` only of the first such part, and a part the edit empties is dropped.
"""
if isinstance(content, str):
edited = edit(content)
return content if edited == content else edited
if not isinstance(content, list):
return content
parts, changed, offered = [], False, False
for part in content:
text = part.get("text") if isinstance(part, dict) else None
if isinstance(text, str) and not (first and offered):
offered, edited = True, edit(text)
if edited != text:
changed = True
if not edited.strip():
continue
part = {**part, "text": edited}
parts.append(part)
return parts if changed else content
def edit_replies(messages, edit, rebuild, first=False):
"""``messages`` with ``edit`` applied to assistant text, or ``messages`` itself if unchanged.
``edit_text`` says which text ``edit`` gets. ``rebuild(message, content, previous)``
returns an edited message with its new content, None to drop it, or ``message`` to keep
the edit out; ``previous`` is the item before it, ``{}`` for the first.
"""
result, changed = [], False
for previous, message in itertools.pairwise([{}, *messages]):
if isinstance(message, dict) and message.get("role") == "assistant":
content = edit_text(message.get("content"), edit, first)
if content is not message.get("content"):
rebuilt = rebuild(message, content, previous)
changed = changed or rebuilt is not message
if rebuilt is None:
continue
message = rebuilt
result.append(message)
return result if changed else messages
def strip_notices(messages):
"""Remove tool notices from echoed assistant text, dropping emptied text parts and messages."""
def rebuild(message, content, previous):
return {**message, "content": content} if content != [] else None
return edit_replies(messages, lambda text: TOOL_NOTICE.sub("", text), rebuild)
@dataclass(frozen=True)
class ToolRound:
"""The validated result of one upstream call, independent of wire format."""
output: list[dict]
calls: list[dict]
usage: dict
# The upstream stopped to have tools run, so the round's calls are complete.
tool_stop: bool
class ToolProtocol(ABC):
"""Native request/history rules and a per-request response assembler.
``accumulate`` and ``load`` assemble one upstream reply, and ``reply`` reads
it; relayed responses and the hidden tool loop share them. ``visible`` is the
cumulative client-visible history. ``end`` returns the completed round; the
loop never inspects the assembler's partial state. Event producers return
native JSON (or the Chat DONE marker); only encode turns events into bytes.
Adapters never execute tools or access storage.
"""
field = "messages"
id_prefix = ""
canonicalizes_history = False
# Dotted body paths a summary request drops: output formats, stop sequences, stream options.
summary_drops: tuple[str, ...] = ()
# Finish reasons of a reply that ended the way the model meant it to, not cut off.
reply_ends: frozenset[str] = frozenset()
# Thinking signatures cover the history before them, so history the gateway
# cannot resend exactly must go upstream without its thinking.
signed_thinking = False
# Usage counts cached and written prompt tokens apart from the input total.
usage_excludes_cache = False
def __init__(self, body: dict):
self.body = body
self.identifier = self.id_prefix + "ovgw-" + uuid.uuid4().hex
self.visible: list[dict] = []
self.started = False
# Text the reply starts with, shown before any upstream content.
self.lead = ""
@classmethod
def messages(cls, body: dict) -> list:
"""The body's history; may be malformed, which the caller checks."""
return body.get(cls.field, [])
@staticmethod
def enhanced_supported(body: dict) -> bool:
"""Whether the body carries the whole history, which recall and replay need."""
return True
@staticmethod
def is_reply(message: dict) -> bool:
"""Whether a history item belongs to a model reply, so a reply can end at it."""
return message.get("role") == "assistant"
@staticmethod
def accepts_context(message: dict) -> bool:
"""Whether append_context can extend the message: a user message or a tool result."""
return message.get("role") == "user"
@staticmethod
def append_context(message: dict, text: str) -> None:
"""Append text to a user message or tool result as a trailing text block."""
append_text(message, "content", text, "text")
@staticmethod
def thinking_as_text(message: dict) -> list[dict]:
"""Text blocks of a reply that may be its unsigned thinking, resent by the client as text."""
return []
@staticmethod
def unsigned_thinking(output: list[dict]) -> list[str]:
"""Thinking the reply carries without a signature, which clients may resend as text."""
return []
@staticmethod
def tool_choice(body: dict):
return body.get("tool_choice", "auto")
@classmethod
def block_reason(cls, body: dict) -> str:
return "" if cls.tool_choice(body) in ("auto", "none") else "tools_forced_choice"
@staticmethod
@abstractmethod
def wire_tools(tools: list[dict]) -> list[dict]:
"""Encode the frozen function catalogue for this protocol."""
@classmethod
def add_tools(cls, body: dict, tools: list[dict]) -> None:
body["tools"] = [*body.get("tools", []), *cls.wire_tools(tools)]
@staticmethod
def disable_tools(body: dict) -> None:
body["tool_choice"] = "none"
@staticmethod
def history_chain(messages: list[dict], after: Sequence[str] = ()) -> list[str]:
return prefix_chain(messages, after)
@staticmethod
def join_replayed_history(messages: list[dict]) -> list[dict]:
return messages
@staticmethod
def split_reasoning(output: list[dict]) -> tuple[list[dict], dict[int, dict]]:
"""A reply as a client that drops reasoning resends it, and the reasoning to restore.
The reasoning is keyed by the index, in that form, of the item that carries
it or that it precedes.
"""
return output, {}
@staticmethod
def restore_reasoning(previous: list[dict], message: dict, value: dict) -> list[dict]:
"""``message`` with recorded reasoning back, after the items ``previous`` holds.
A message that still carries reasoning comes back unchanged.
"""
return [message]
@classmethod
def strip_lead(cls, messages: list[dict]) -> list[dict]:
"""The history without the recall notice the gateway put at the start of replies.
Only an assistant message's first text can hold this lead; a user quoting it keeps
it. Returns ``messages`` itself when nothing changed.
"""
def rebuild(message, content, previous):
# A reply of tool calls alone had no content before the lead.
if content == "" and message.get("tool_calls"):
content = None
return {**message, "content": content}
return edit_replies(messages, without_recall_notice, rebuild, first=True)
# Whether omit_hidden_history removes reasoning, so none is restored before it.
omits_reasoning = False
@staticmethod
def omit_hidden_history(messages: list[dict]) -> list[dict]:
"""Drop what cannot be used without the omitted tool history."""
return strip_notices(messages)
@classmethod
def summary_request(
cls,
body: dict,
messages: list[dict],
instruction: str,
max_tokens: int,
headroom: int = SUMMARY_HEADROOM,
) -> dict:
"""Ask for a summary of ``messages`` without streaming.
System, tools and reasoning settings stay as the client sent them, so
the upstream can reuse its cached prefix. Output settings a plain-text
summary cannot follow are dropped, and a forced tool choice becomes none.
"""
request = {
**functools.reduce(without, cls.summary_drops, body),
cls.field: [*messages, {"role": "user", "content": instruction}],
"stream": False,
}
if cls.tool_choice(body) not in ("auto", "none"):
cls.disable_tools(request)
return request
@staticmethod
@abstractmethod
def summary_text(response: dict) -> str:
"""Return the reply's text; raise SummaryError for tool calls or a cut-off reply."""
def begin(self) -> None:
self.output, self.calls, self.usage, self.envelope = [], [], {}, {}
self.finish = None
@abstractmethod
def accumulate(self, value: dict) -> None:
"""Add an upstream event to the reply; events it does not know are ignored."""
@abstractmethod
def event(self, value: dict) -> list[dict]:
"""Accumulate an upstream event and return any client-visible events."""
@abstractmethod
def load(self, value: dict) -> None:
"""Consume a nonstreaming response."""
@abstractmethod
def assembled(self) -> tuple[dict | None, list[dict] | None]:
"""The reply so far as one message, and as output items where the protocol has them."""
@staticmethod
@abstractmethod
def has_calls(output: list[dict]) -> bool:
"""Whether the reply calls tools."""
def reply(self) -> dict:
"""The reply so far, as ``ResponseCapture`` holds it.
Every path reads completion here. A reply that ended in tool calls hands
the turn to the client's tools: it is finished, but the user's turn goes
on in the next request. Any other reply that ended completes the turn.
"""
message, items = self.assembled()
output = items or ([message] if message else [])
ended = self.finish in self.reply_ends
handoff = ended and self.has_calls(output)
return {
"message": message,
"output_items": items,
"usage": (
usage_of({"usage": self.usage}, self.usage_excludes_cache) if self.usage else None
),
"response_id": self.envelope.get("id") or "",
"complete": ended and not handoff,
"handoff": handoff,
}
@abstractmethod
def end(self) -> ToolRound:
"""Validate the assembled round before exposing executable calls."""
@abstractmethod
def publish_calls(self, client: list[dict]) -> list[dict]:
"""Add client-owned calls to visible history and return their events."""
def open_notice(self) -> list[dict]:
"""Start visible text for the calls the gateway runs and return its events."""
return []
@abstractmethod
def notice(self, text: str) -> list[dict]:
"""Append text to the open notice in visible history and return its events."""
def close_notice(self) -> list[dict]:
return []
def lead_with(self, text: str) -> None:
"""Start the visible reply with ``text``; the adapter shows it before upstream content."""
self.lead = text
def lead_notice(self) -> list[dict]:
"""Put the pending lead text first in visible history and return its events, once."""
text, self.lead = self.lead, ""
if not text:
return []
return [*self.open_notice(), *self.notice(text), *self.close_notice()]
@abstractmethod
def results(self, receipts: list[dict]) -> list[dict]:
"""Encode executor receipts as native tool-result messages."""
@abstractmethod
def final(self, usage: dict) -> dict:
"""Build the combined client response."""
@abstractmethod
def terminal(self, final: dict) -> list[StreamEvent]:
"""Return the protocol's success terminal events."""
def error(self, message: str) -> list[StreamEvent]:
return [{"type": "error", "error": {"type": "gateway_tool_error", "message": message}}]
def encode(self, value: StreamEvent) -> bytes:
if value is None:
return b"data: [DONE]\n\n"
return b"event: " + value["type"].encode() + b"\n" + sse(value)