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
feat(integrations): add Microsoft Agent Framework context provider (#5578)
z1gon7f69dd24c19d
diff --git a/.github/workflows/python-agent-framework.yml b/.github/workflows/python-agent-framework.ymlnew file mode 100644index 000000000..a69bc6333--- /dev/null+++ b/.github/workflows/python-agent-framework.yml@@ -0,0 +1,44 @@+name: Microsoft Agent Framework Integration++on:+ pull_request:+ paths:+ - 'examples/agent-framework/**'+ - '.github/workflows/python-agent-framework.yml'+ push:+ branches: [main]+ paths:+ - 'examples/agent-framework/**'+ - '.github/workflows/python-agent-framework.yml'++permissions:+ contents: read++jobs:+ contracts:+ runs-on: ubuntu-24.04+ strategy:+ matrix:+ include:+ - maf: 'agent-framework-core==1.20.0'+ sdk: 'openviking-sdk==0.1.13'+ - maf: 'agent-framework-core>=1.20,<2'+ sdk: 'openviking-sdk>=0.1.13,<0.2'+ defaults:+ run:+ working-directory: examples/agent-framework+ steps:+ - uses: actions/checkout@v6+ - uses: actions/setup-python@v6+ with:+ python-version: '3.12'+ - name: Install supported dependencies+ run: python -m pip install '.[test,dev]' '${{ matrix.maf }}' '${{ matrix.sdk }}'+ - name: Check package and offline contracts+ run: |+ ruff check .+ ruff format --check .+ mypy src+ pytest -q --confcutdir=tests tests+ python -m build+ python -m twine check dist/*diff --git a/examples/agent-framework/README.md b/examples/agent-framework/README.mdnew file mode 100644index 000000000..e113ce3f2--- /dev/null+++ b/examples/agent-framework/README.md@@ -0,0 +1,118 @@+# OpenViking for Microsoft Agent Framework++An optional Python package for MAF agents. It recalls OpenViking context before a+run and captures completed agent runs, including tool calls and results.+The application controls when memory extraction is requested.++## Install and try++Requires Python 3.10+, MAF core 1.20–1.x, OpenViking SDK 0.1.13–0.1.x, and a+running OpenViking 0.4.23+ server. Install from an OpenViking checkout:++```bash+pip install './examples/agent-framework[example]'+```++Set `OPENVIKING_URL`, `OPENVIKING_API_KEY` (a normal user key), `OPENAI_API_KEY`,+`OPENAI_BASE_URL`, and `OPENAI_MODEL`, then run:++```bash+python examples/agent-framework/example.py+```++The example records a preference, waits for extraction, and asks about it in a new+conversation. Its OpenAI-compatible model client is optional; the provider works+with other MAF chat clients that support chat middleware (including the built-in+clients). The package installs neither the OpenViking server+nor a model client unless the `example` extra is selected.++## Attach to an existing agent++With an initialized, application-owned `AsyncHTTPClient`:++```python+from agent_framework import Agent+from openviking_agent_framework import OpenVikingContextProvider++memory = OpenVikingContextProvider(client)+agent = Agent(chat_client, context_providers=[memory])+session = agent.create_session()+response = await agent.run("Remember my preferred reply format: JSON.", session=session)+job = await memory.commit(session)+```++`commit()` returns task acceptance. Poll `client.get_task(job["task_id"])` until+completion before checking extracted memory. Close the client in the application.++## Capture and commit policies++```python+memory = OpenVikingContextProvider(+ client,+ capture=True,+ commit_policy="pending_tokens",+ commit_token_threshold=20_000,+)+```++| `commit_policy` | Behavior |+| --- | --- |+| `"never"` (default) | Capture automatically; the application calls `commit(session)` |+| `"always"` | Request a commit after each completed, captured agent invocation |+| `"pending_tokens"` | Request a commit when OV's post-capture pending tokens reach the threshold |++The threshold defaults to 20,000 and must be a positive integer. It counts the+session's captured, uncommitted tokens; `token_budget` controls recalled context.+Policies run only after all message batches are acknowledged. A successful+`flush()` of pending capture also applies the policy. Commit or metadata errors+propagate, but acknowledged messages remain recorded and are not sent again;+the next completed invocation or an explicit `commit()` can retry the commit.+Automatic commits start background extraction and do not wait for completion.++Set `capture=False` for automatic recall without conversation uploads or+automatic commits. Explicit `flush()` and `commit()` remain available. Turning+capture off does not discard existing pending messages. The application still+calls `commit()` at its conversation/workflow boundary to extract a tail below+the threshold. These policies do not change OV's server-side auto-commit settings.++## State and failure handling++- Use one client/provider per user and actor; serialize work for the same session.+- Persist `session.to_dict()` and restore with `AgentSession.from_dict()` under the+ same authenticated user. Preserve message IDs when replaying previous messages.+- Recalled context is attributed reference data and is excluded from capture.+ System instructions, hidden reasoning, and nontext media are also excluded.+- Fully consume streaming responses. Capture happens after each completed agent+ run, including each `AgentLoopMiddleware` iteration, for both streaming and+ non-streaming runs. If a later iteration is interrupted, earlier completed+ iterations remain captured; the interrupted iteration is excluded.+- Middleware must preserve provider state. `fresh_context=True` rolls that state+ back between loop iterations and is unsupported; detected state resets raise+ before further capture or commit.+- Errors propagate. Unconfirmed capture blocks another run and `commit()`.+ `flush(session)` retries pending messages after a known failure before sending.+ A lost response can mean the server already appended the messages: inspect+ active records and archives by `source_message_ids` before retrying or updating+ the saved provider state. Blind retries can duplicate capture.++The application owns MAF session persistence; there is no exactly-once guarantee.+Options are `source_id="openviking"`, `limit=5`, `token_budget=4000` (64–32000),+and `peer_scope="all"`. Use `peer_scope="actor"` with the SDK client's actor ID.+The server owns access control, retrieval, storage, and extraction; MAF owns agent+execution and chat history. No framework modifications or MCP tools are required.++## Validate++```bash+pip install -e './examples/agent-framework[test,dev]'+cd examples/agent-framework+pytest -q --confcutdir=tests tests+ruff check .+ruff format --check .+mypy src+python -m build+```++Offline tests use the real MAF agent lifecycle with deterministic model and SDK+boundaries. They require no server, credentials, or model calls. Support belongs+in [OpenViking issues](https://github.com/volcengine/OpenViking/issues/new/choose).diff --git a/examples/agent-framework/example.py b/examples/agent-framework/example.pynew file mode 100644index 000000000..a8cee0171--- /dev/null+++ b/examples/agent-framework/example.py@@ -0,0 +1,57 @@+"""Record a preference and recall it in a new MAF conversation."""++import asyncio+import os+import time++from agent_framework import Agent+from agent_framework.openai import OpenAIChatCompletionClient+from openai import AsyncOpenAI+from openviking_sdk import AsyncHTTPClient++from openviking_agent_framework import OpenVikingContextProvider+++async def main():+ client = AsyncHTTPClient(+ url=os.environ["OPENVIKING_URL"], api_key=os.environ["OPENVIKING_API_KEY"], timeout=60+ )+ await client.initialize()+ try:+ memory = OpenVikingContextProvider(client)+ async with AsyncOpenAI(+ api_key=os.environ["OPENAI_API_KEY"], base_url=os.environ["OPENAI_BASE_URL"]+ ) as model:+ agent = Agent(+ OpenAIChatCompletionClient(model=os.environ["OPENAI_MODEL"], async_client=model),+ instructions="Use retrieved reference data when relevant.",+ context_providers=[memory],+ )+ session = agent.create_session()+ print(+ (await agent.run("Remember my preferred reply format: JSON.", session=session)).text+ )+ job = await memory.commit(session)+ deadline = time.monotonic() + 180+ while time.monotonic() < deadline:+ task = await client.get_task(job["task_id"])+ if task is None or task["status"] in {"failed", "cancelled"}:+ raise RuntimeError(f"Extraction failed: {task}")+ if task["status"] == "completed":+ break+ await asyncio.sleep(1)+ else:+ raise TimeoutError("Extraction did not complete within 180 seconds")+ print(+ (+ await agent.run(+ "What reply format do I prefer?", session=agent.create_session()+ )+ ).text+ )+ finally:+ await client.close()+++if __name__ == "__main__":+ asyncio.run(main())diff --git a/examples/agent-framework/pyproject.toml b/examples/agent-framework/pyproject.tomlnew file mode 100644index 000000000..4818dc7f8--- /dev/null+++ b/examples/agent-framework/pyproject.toml@@ -0,0 +1,43 @@+[build-system]+requires = ["setuptools>=77.0", "wheel"]+build-backend = "setuptools.build_meta"++[project]+name = "openviking-agent-framework"+version = "0.1.0"+description = "OpenViking context provider for Microsoft Agent Framework"+readme = "README.md"+requires-python = ">=3.10"+license = "AGPL-3.0"+dependencies = ["agent-framework-core>=1.20,<2", "openviking-sdk>=0.1.13,<0.2"]++[project.optional-dependencies]+example = ["agent-framework-openai>=1.15,<2"]+test = ["pytest>=8", "pytest-asyncio>=0.24"]+dev = ["ruff", "mypy", "build", "twine"]++[project.urls]+Repository = "https://github.com/volcengine/OpenViking"+Documentation = "https://github.com/volcengine/OpenViking/tree/main/examples/agent-framework"+Issues = "https://github.com/volcengine/OpenViking/issues/new/choose"++[tool.setuptools.packages.find]+where = ["src"]++[tool.setuptools.package-data]+openviking_agent_framework = ["py.typed"]++[tool.pytest.ini_options]+asyncio_mode = "auto"++[tool.ruff]+line-length = 100+target-version = "py310"++[tool.ruff.lint]+select = ["E", "F", "I", "B"]++[tool.mypy]+python_version = "3.10"+check_untyped_defs = true+ignore_missing_imports = truediff --git a/examples/agent-framework/src/openviking_agent_framework/__init__.py b/examples/agent-framework/src/openviking_agent_framework/__init__.pynew file mode 100644index 000000000..ff9046b4c--- /dev/null+++ b/examples/agent-framework/src/openviking_agent_framework/__init__.py@@ -0,0 +1,7 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""OpenViking memory for Microsoft Agent Framework."""++from .provider import OpenVikingContextProvider++__all__ = ["OpenVikingContextProvider"]diff --git a/examples/agent-framework/src/openviking_agent_framework/provider.py b/examples/agent-framework/src/openviking_agent_framework/provider.pynew file mode 100644index 000000000..730540fc2--- /dev/null+++ b/examples/agent-framework/src/openviking_agent_framework/provider.py@@ -0,0 +1,303 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Recall and conversation capture through MAF's public context provider interface."""++from __future__ import annotations++import asyncio+import json+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping+from typing import Any, Literal+from uuid import uuid4+from weakref import WeakKeyDictionary++from agent_framework import (+ AgentSession,+ ChatContext,+ ChatMiddleware,+ ChatResponseUpdate,+ ContextProvider,+ Message,+ ResponseStream,+ SessionContext,+ SupportsAgentRun,+)+from openviking_sdk import AsyncHTTPClient+++class _CaptureCompletion(ChatMiddleware):+ """Distinguish stream exhaustion from MAF's early-close finalization."""++ def __init__(self, state: dict[str, Any]) -> None:+ self.state = state++ async def process(self, context: ChatContext, call_next: Callable[[], Awaitable[None]]) -> None:+ self.state["capture_ready"] = False+ await call_next()+ if not isinstance(context.result, ResponseStream):+ self.state["capture_ready"] = True+ return+ original = context.result++ async def updates() -> AsyncIterator[ChatResponseUpdate]:+ async with original:+ async for update in original:+ yield update+ self.state["capture_ready"] = True++ context.result = ResponseStream(+ updates(), finalizer=lambda _: original.get_final_response()+ )+++class OpenVikingContextProvider(ContextProvider):+ """Attach OpenViking memory to an agent using an application-owned HTTP client.++ Use one provider per authenticated user and actor. Serialize runs for each MAF+ session. Different sessions may share a provider on the same asyncio event loop.+ The caller initializes and closes the client and persists MAF session state.+ Capture defaults to enabled; commits default to explicit application requests.+ Automatic policies run after acknowledged capture and never wait for extraction.+ """++ # Capture each completed agent run: loop-level streamed responses only contain+ # the final iteration in MAF, while per-run responses retain all tool evidence.+ after_run_once_per_turn = False++ def __init__(+ self,+ client: AsyncHTTPClient,+ *,+ source_id: str = "openviking",+ peer_scope: Literal["all", "actor"] = "all",+ limit: int = 5,+ token_budget: int = 4000,+ capture: bool = True,+ commit_policy: Literal["never", "always", "pending_tokens"] = "never",+ commit_token_threshold: int = 20_000,+ ) -> None:+ if not source_id or limit < 1 or not 64 <= token_budget <= 32000:+ raise ValueError("source_id must be non-empty; limit > 0; token_budget in [64, 32000]")+ if peer_scope not in ("all", "actor"):+ raise ValueError("peer_scope must be 'all' or 'actor'")+ if not isinstance(capture, bool):+ raise ValueError("capture must be a boolean")+ if commit_policy not in ("never", "always", "pending_tokens"):+ raise ValueError("commit_policy must be 'never', 'always', or 'pending_tokens'")+ if type(commit_token_threshold) is not int or commit_token_threshold < 1:+ raise ValueError("commit_token_threshold must be a positive integer")+ super().__init__(source_id)+ self.client = client+ self.peer_scope = peer_scope+ self.limit = limit+ self.token_budget = token_budget+ self.capture = capture+ self.commit_policy = commit_policy+ self.commit_token_threshold = commit_token_threshold+ self._write_lock = asyncio.Lock()+ self._session_states: WeakKeyDictionary[AgentSession, dict[str, Any]] = WeakKeyDictionary()++ def _state(self, session: AgentSession) -> dict[str, Any]:+ state = session.state.setdefault(self.source_id, {})+ # A loop's fresh_context mode rolls provider state back between iterations.+ # External appends cannot be rolled back with it; fail before another write.+ previous = self._session_states.get(session)+ if previous is not None and previous != state:+ raise RuntimeError(+ "OpenViking provider state was reset during this session. "+ "State-resetting middleware such as fresh_context=True is unsupported."+ )+ self._session_states[session] = state+ return state++ async def _ensure_session(self, session: AgentSession) -> str:+ state = self._state(session)+ if "session_id" not in state:+ # Retain the proposed ID even if the create acknowledgement is lost.+ state["session_id"] = f"maf-{uuid4().hex}"+ session_id: str = state["session_id"]+ await self.client.get_session(session_id, auto_create=True)+ return session_id++ async def before_run(+ self,+ *,+ agent: SupportsAgentRun,+ session: AgentSession,+ context: SessionContext,+ state: dict[str, Any],+ ) -> None:+ """Retrieve context before inference; never replay unconfirmed writes implicitly."""+ self._state(session)+ if state.get("pending_messages"):+ raise RuntimeError(+ "OpenViking capture is unconfirmed. Inspect server records and pending_messages "+ "in provider state before explicitly calling flush(session); "+ "a lost acknowledgement may mean the messages were already appended."+ )+ state["capture_ready"] = False+ if self.capture:+ context.extend_middleware(self.source_id, [_CaptureCompletion(state)])+ for message in context.input_messages:+ if message.message_id is None:+ message.message_id = uuid4().hex+ query = "\n".join(+ message.text+ for message in context.input_messages+ if message.role == "user" and not message.additional_properties.get("_attribution")+ )+ if not query.strip():+ return+ session_id = await self._ensure_session(session)+ result = await self.client.search_context(+ query=query,+ session_id=session_id,+ limit=self.limit,+ options={"max_tokens": self.token_budget, "peer_scope": self.peer_scope},+ )+ rendered = result.get("rendered", "")+ if rendered and result.get("entries"):+ # Memory is data from an external source, never system/developer instructions.+ context.extend_messages(+ self,+ [Message("user", ["Retrieved OpenViking context (reference data):\n" + rendered])],+ )++ async def after_run(+ self,+ *,+ agent: SupportsAgentRun,+ session: AgentSession,+ context: SessionContext,+ state: dict[str, Any],+ ) -> None:+ """Capture the completed run and apply its commit policy after acknowledgement."""+ if not self.capture or context.response is None or not state.pop("capture_ready", False):+ return+ if state.get("pending_messages"):+ raise RuntimeError("OpenViking has pending capture; flush it before another run")+ messages = [*context.input_messages, *context.response.messages]+ recorded = set(state.get("recorded_message_ids", []))+ payloads = _messages(messages, recorded)+ if not payloads and not recorded:+ return+ # Retain capture even if cancellation happens while waiting for another session.+ if payloads:+ state["pending_messages"] = payloads+ async with self._write_lock:+ await self._flush(session)+ await self._maybe_commit(session)++ async def flush(self, session: AgentSession) -> None:+ """Explicitly retry pending capture, removing only acknowledged batches.++ A lost HTTP response can mean the server already appended the batch.+ Check server records before retrying: the append API is not idempotent.+ Recovered capture applies the automatic policy when capture is enabled.+ """+ async with self._write_lock:+ had_pending = bool(self._state(session).get("pending_messages"))+ await self._flush(session)+ if had_pending and self.capture:+ await self._maybe_commit(session)++ async def _flush(self, session: AgentSession) -> None:+ state = self._state(session)+ pending = state.get("pending_messages", [])+ if not pending:+ return+ session_id = await self._ensure_session(session)+ while pending:+ batch = pending[:100]+ result = await self.client.batch_add_messages(session_id, batch)+ if result.get("added") != len(batch):+ raise RuntimeError("OpenViking did not acknowledge the complete message batch")+ state.setdefault("recorded_message_ids", []).extend(+ message["source_message_ids"][0] for message in batch+ )+ del pending[: len(batch)]++ async def _maybe_commit(self, session: AgentSession) -> None:+ """Apply the policy under the write lock, after capture is acknowledged."""+ if self.commit_policy == "never":+ return+ session_id = self._state(session)["session_id"]+ if self.commit_policy == "pending_tokens":+ metadata = await self.client.get_session(session_id)+ if int(metadata.get("pending_tokens") or 0) < self.commit_token_threshold:+ return+ # Do not call commit(): this path already owns the non-reentrant lock.+ await self.client.commit_session(session_id)++ async def commit(self, session: AgentSession) -> dict[str, Any]:+ """Request extraction after capture; task acceptance is not completion."""+ async with self._write_lock:+ if self._state(session).get("pending_messages"):+ raise RuntimeError("Resolve pending OpenViking capture before committing")+ session_id = await self._ensure_session(session)+ return await self.client.commit_session(session_id)+++def _messages(messages: list[Message], recorded: set[str]) -> list[dict[str, Any]]:+ """Translate native messages without recording injected context or hidden reasoning."""+ calls = {+ content.call_id: content+ for message in messages+ for content in message.contents+ if content.type == "function_call"+ }+ payloads = []+ for message in messages:+ if message.role not in ("user", "assistant", "tool"):+ continue+ if message.additional_properties.get("_attribution"):+ continue+ message_id = message.message_id or uuid4().hex+ message.message_id = message_id+ if message_id in recorded:+ continue+ parts: list[dict[str, Any]] = []+ for content in message.contents:+ if content.type == "text" and content.text:+ parts.append({"type": "text", "text": content.text})+ elif content.type in ("function_call", "function_result"):+ call = content if content.type == "function_call" else calls.get(content.call_id)+ arguments = call.arguments if call else None+ if isinstance(arguments, str):+ try:+ arguments = json.loads(arguments)+ except ValueError:+ arguments = {"raw_arguments": arguments}+ is_result = content.type == "function_result"+ output = content.result+ parts.append(+ {+ "type": "tool",+ "tool_id": content.call_id or "",+ "tool_name": (call.name if call else content.name) or "",+ "tool_input": dict(arguments)+ if isinstance(arguments, Mapping)+ else ({"raw_arguments": arguments} if arguments is not None else None),+ "tool_output": (+ output if isinstance(output, str) else json.dumps(output, default=str)+ )+ if is_result+ else "",+ "tool_status": ("error" if content.exception else "completed")+ if is_result+ else "pending",+ }+ )+ if parts:+ payloads.append(+ {+ "role": "user" if message.role == "tool" else message.role,+ "parts": parts,+ "source_message_ids": [message_id],+ "message_kind": "tool_transport"+ if message.role == "tool"+ else ("user_query" if message.role == "user" else "assistant_step"),+ }+ )+ recorded.add(message_id)+ return payloadsdiff --git a/examples/agent-framework/src/openviking_agent_framework/py.typed b/examples/agent-framework/src/openviking_agent_framework/py.typednew file mode 100644index 000000000..e69de29bbdiff --git a/examples/agent-framework/tests/test_provider.py b/examples/agent-framework/tests/test_provider.pynew file mode 100644index 000000000..f4dba0b67--- /dev/null+++ b/examples/agent-framework/tests/test_provider.py@@ -0,0 +1,666 @@+"""Offline contracts through the real MAF agent and session lifecycle."""++import asyncio+import json+from copy import deepcopy++import httpx+import pytest+from agent_framework import (+ Agent,+ AgentLoopMiddleware,+ AgentSession,+ BaseChatClient,+ ChatMiddlewareLayer,+ ChatResponse,+ ChatResponseUpdate,+ Content,+ FunctionInvocationLayer,+ Message,+ ResponseStream,+)+from openviking_sdk import AsyncHTTPClient++from openviking_agent_framework import OpenVikingContextProvider+++class MemoryClient(AsyncHTTPClient):+ """Model the SDK boundary, including ambiguous append acknowledgements."""++ def __init__(self):+ super().__init__(url="http://openviking.test", api_key="test-user")+ self.rows = []+ self.sessions = []+ self.searches = []+ self.commits = []+ self.batches = 0+ self.fail_batch = None+ self.lose_ack = False+ self.recall_error = None+ self.metadata_error = None+ self.commit_error = None+ self.ack_override = None+ self.pending_tokens = {}+ self.commit_attempts = []+ self.commit_sizes = []+ self.rows_by_session = {}++ async def get_session(self, session_id, *, auto_create=False):+ if not auto_create and self.metadata_error:+ raise self.metadata_error+ self.sessions.append(session_id)+ return {"session_id": session_id, "pending_tokens": self.pending_tokens.get(session_id, 0)}++ async def search_context(self, **kwargs):+ if self.recall_error:+ raise self.recall_error+ self.searches.append(kwargs)+ return {"rendered": "Preferred format: JSON", "entries": [{"uri": "viking://memory"}]}++ async def batch_add_messages(self, session_id, messages):+ self.batches += 1+ if self.batches == self.fail_batch:+ raise ConnectionError("request not sent")+ self.rows.extend(deepcopy(messages))+ self.rows_by_session.setdefault(session_id, []).extend(deepcopy(messages))+ self.pending_tokens[session_id] = self.pending_tokens.get(session_id, 0) + 10 * len(+ messages+ )+ if self.lose_ack:+ raise ConnectionError("lost acknowledgement")+ return {"added": len(messages) if self.ack_override is None else self.ack_override}++ async def commit_session(self, session_id):+ self.commit_attempts.append(session_id)+ if self.commit_error:+ raise self.commit_error+ self.commits.append(session_id)+ self.commit_sizes.append(len(self.rows_by_session.get(session_id, [])))+ self.pending_tokens[session_id] = 0+ return {"task_id": "extraction-job"}+++class ChatClient(FunctionInvocationLayer, ChatMiddlewareLayer, BaseChatClient):+ """Deterministic model results; MAF still owns tools and streaming."""++ def __init__(self, responses=None):+ super().__init__()+ self.inputs = []+ self.responses = iter(responses) if responses is not None else None+ self.error = None++ def _inner_get_response(self, *, messages, stream, options, **kwargs):+ self.inputs.append(deepcopy(list(messages)))+ message = (+ deepcopy(next(self.responses)) if self.responses else Message("assistant", ["Answer"])+ )+ if stream:++ async def updates():+ if self.error:+ raise self.error+ for content in message.contents:+ yield ChatResponseUpdate(+ role="assistant", contents=[content], message_id=message.message_id+ )++ return ResponseStream(updates(), finalizer=ChatResponse.from_updates)++ async def response():+ if self.error:+ raise self.error+ return ChatResponse(messages=[message])++ return response()+++def setup(responses=None, **options):+ client = MemoryClient()+ provider = OpenVikingContextProvider(client, **options)+ model = ChatClient(responses)+ agent = Agent(model, context_providers=[provider])+ return client, provider, model, agent, agent.create_session()+++async def test_recall_capture_and_explicit_commit():+ client, provider, model, agent, session = setup()+ await agent.run(+ [Message("system", ["Private instructions"]), Message("user", ["My question"])],+ session=session,+ )+ assert "Preferred format: JSON" in json.dumps([m.to_dict() for m in model.inputs[0]])+ assert [row["role"] for row in client.rows] == ["user", "assistant"]+ assert "Preferred format" not in json.dumps(client.rows)+ assert "Private instructions" not in json.dumps(client.rows)+ assert client.searches[0]["options"] == {"max_tokens": 4000, "peer_scope": "all"}+ assert not client.commits+ assert await provider.commit(session) == {"task_id": "extraction-job"}+ assert client.commits == [session.state[provider.source_id]["session_id"]]++[email protected]("commit_policy", ["never", "always", "pending_tokens"])[email protected]("stream", [False, True])+async def test_tools_keep_calls_and_results_paired(commit_policy, stream):+ def lookup_label():+ """Return the current label."""+ return "LABEL"++ client, _, _, agent, session = setup(+ [+ Message(+ "assistant",+ [Content("function_call", call_id="call-1", name="lookup_label", arguments={})],+ ),+ Message("assistant", ["LABEL"]),+ ],+ commit_policy=commit_policy,+ commit_token_threshold=1,+ )+ if stream:+ async with agent.run(+ "Read the label", tools=[lookup_label], session=session, stream=True+ ) as result:+ async for _ in result:+ assert not client.commits+ else:+ await agent.run("Read the label", tools=[lookup_label], session=session)+ parts = [part for row in client.rows for part in row["parts"] if part["type"] == "tool"]+ assert len(parts) == 2+ assert [part["tool_status"] for part in parts] == ["pending", "completed"]+ assert {part["tool_id"] for part in parts} == {"call-1"}+ assert {part["tool_name"] for part in parts} == {"lookup_label"}+ assert parts[1]["tool_output"] == "LABEL"+ assert len(client.commits) == (0 if commit_policy == "never" else 1)+ if client.commits:+ assert client.commit_sizes == [len(client.rows)]++[email protected]("complete", [False, True])[email protected]("commit_policy", ["never", "always", "pending_tokens"])+async def test_stream_capture_requires_complete_consumption(complete, commit_policy):+ client, _, _, agent, session = setup(+ [Message("assistant", ["First", "Second"])],+ commit_policy=commit_policy,+ commit_token_threshold=1,+ )+ async with agent.run("Question", session=session, stream=True) as stream:+ async for _ in stream:+ assert not client.commits+ if not complete:+ break+ assert len(client.rows) == (2 if complete else 0)+ assert len(client.commits) == (1 if complete and commit_policy != "never" else 0)+++async def test_restoration_preserves_session_and_acknowledged_message_ids():+ client, provider, _, agent, session = setup()+ question = Message("user", ["Same text"], message_id="original")+ response = await agent.run(question, session=session)+ restored = AgentSession.from_dict(json.loads(json.dumps(session.to_dict())))+ await agent.run(+ [question, *response.messages, Message("user", ["Same text"], message_id="new")],+ session=restored,+ )+ assert len(client.rows) == 4+ ids = [row["source_message_ids"][0] for row in client.rows]+ assert len(ids) == len(set(ids))+ assert {"original", "new"}.issubset(ids)+ assert len(set(client.sessions)) == 1+ assert (+ restored.state[provider.source_id]["session_id"]+ == session.state[provider.source_id]["session_id"]+ )++[email protected]("commit_policy", ["never", "always", "pending_tokens"])+async def test_partial_write_keeps_only_unacknowledged_messages_for_flush(commit_policy):+ client, provider, _, agent, session = setup(+ commit_policy=commit_policy, commit_token_threshold=1+ )+ client.fail_batch = 2+ messages = [Message("user", [f"Item {i}"], message_id=str(i)) for i in range(101)]+ with pytest.raises(Exception, match="request not sent"):+ await agent.run(messages, session=session)+ assert len(client.rows) == 100+ assert len(session.state[provider.source_id]["pending_messages"]) == 2+ assert not client.commit_attempts+ client.fail_batch = None+ await provider.flush(session)+ assert len(client.rows) == 102+ assert not session.state[provider.source_id]["pending_messages"]+ assert len(client.commits) == (0 if commit_policy == "never" else 1)+ await provider.flush(session)+ assert len(client.commits) == (0 if commit_policy == "never" else 1)++[email protected]("commit_policy", ["never", "always", "pending_tokens"])+async def test_lost_ack_blocks_implicit_retry_and_commit(commit_policy):+ client, provider, model, agent, session = setup(+ commit_policy=commit_policy, commit_token_threshold=1+ )+ client.lose_ack = True+ with pytest.raises(Exception, match="lost acknowledgement"):+ await agent.run("Question", session=session)+ assert len(client.rows) == 2+ assert not client.commit_attempts+ assert len(session.state[provider.source_id]["pending_messages"]) == 2+ with pytest.raises(RuntimeError, match="unconfirmed"):+ await agent.run("Another question", session=session)+ with pytest.raises(RuntimeError, match="pending"):+ await provider.commit(session)+ assert len(model.inputs) == 1+ assert len(client.rows) == 2+++async def test_recall_failure_stops_inference_and_remains_retryable():+ client, _, model, agent, session = setup()+ client.recall_error = ConnectionError("recall unavailable")+ with pytest.raises(Exception, match="recall unavailable"):+ await agent.run("Question", session=session)+ assert not model.inputs and not client.rows+ client.recall_error = None+ await agent.run("Question", session=session)+ assert len(client.rows) == 2++[email protected]("error", [RuntimeError("model failed"), asyncio.CancelledError()])[email protected]("commit_policy", ["never", "always", "pending_tokens"])[email protected]("stream", [False, True])+async def test_failed_or_cancelled_inference_is_not_captured(error, commit_policy, stream):+ client, _, model, agent, session = setup(commit_policy=commit_policy, commit_token_threshold=1)+ model.error = error+ with pytest.raises(type(error)):+ if stream:+ async with agent.run("Question", session=session, stream=True) as result:+ async for _ in result:+ pass+ else:+ await agent.run("Question", session=session)+ assert not client.rows+ assert not session.state["openviking"].get("pending_messages")+ assert not client.commit_attempts+ model.error = None+ await agent.run("Retry", session=session)+ assert len(client.rows) == 2+++async def test_hidden_reasoning_media_and_other_provider_context_are_excluded():+ client, _, _, agent, session = setup(+ [+ Message(+ "assistant",+ [Content("text", text="Visible"), Content("text_reasoning", text="Hidden")],+ )+ ]+ )+ await agent.run(+ [+ Message("user", ["Question", Content("image", uri="https://example.test/private.png")]),+ Message(+ "user",+ ["Other memory"],+ additional_properties={"_attribution": {"source_id": "other"}},+ ),+ ],+ session=session,+ )+ captured = json.dumps(client.rows)+ assert "Question" in captured and "Visible" in captured+ assert all(value not in captured for value in ("Hidden", "private.png", "Other memory"))+ assert client.searches[0]["query"] == "Question"+++async def test_shared_provider_keeps_session_state_separate():+ client, provider, _, agent, first = setup()+ second = agent.create_session()+ await asyncio.gather(agent.run("First", session=first), agent.run("Second", session=second))+ assert (+ first.state[provider.source_id]["session_id"]+ != second.state[provider.source_id]["session_id"]+ )+ assert len(client.rows) == 4+ assert not first.state[provider.source_id]["pending_messages"]+ assert not second.state[provider.source_id]["pending_messages"]+++async def loop_capture(+ stream, *, fresh_context=False, return_final_only=False, tools=False, **options+):+ def lookup_label():+ """Return the current label."""+ return "TOOL_VALUE"++ responses = [+ Message("assistant", ["First draft"], message_id="draft"),+ Message("assistant", ["Final answer"], message_id="final"),+ ]+ if tools:+ responses.insert(+ 0,+ Message(+ "assistant",+ [Content("function_call", call_id="loop-call", name="lookup_label", arguments={})],+ message_id="tool-call",+ ),+ )+ client, provider, model, agent, session = setup(responses, **options)+ middleware = [+ AgentLoopMiddleware(+ lambda *, iteration, **kwargs: iteration < 2,+ next_message=lambda **kwargs: "Please refine the draft",+ fresh_context=fresh_context,+ return_final_only=return_final_only,+ )+ ]+ # Per-call middleware exercises the public runtime override as well.+ kwargs = {"middleware": middleware, "tools": [lookup_label] if tools else []}+ if stream:+ async with agent.run("Question", session=session, stream=True, **kwargs) as response:+ async for _ in response:+ pass+ else:+ await agent.run("Question", session=session, **kwargs)+ return client, provider, model, session++[email protected]("tools", [False, True])[email protected]("return_final_only", [False, True])[email protected]("commit_policy", ["never", "always", "pending_tokens"])+async def test_streamed_agent_loop_preserves_the_same_transcript(+ tools, return_final_only, commit_policy+):+ options = {"commit_policy": commit_policy, "commit_token_threshold": 1}+ ordinary, _, _, _ = await loop_capture(+ False, tools=tools, return_final_only=return_final_only, **options+ )+ streamed, _, _, _ = await loop_capture(+ True, tools=tools, return_final_only=return_final_only, **options+ )++ def transcript(client):+ return [{"role": row["role"], "parts": row["parts"]} for row in client.rows]++ assert transcript(streamed) == transcript(ordinary)+ assert "First draft" in json.dumps(streamed.rows)+ assert "Please refine the draft" in json.dumps(streamed.rows)+ assert "Final answer" in json.dumps(streamed.rows)+ assert "Preferred format" not in json.dumps(streamed.rows)+ assert len(set(streamed.sessions)) == 1+ assert len({row["source_message_ids"][0] for row in streamed.rows}) == len(streamed.rows)+ assert len(streamed.commits) == (0 if commit_policy == "never" else 2)+ assert streamed.commit_sizes == ordinary.commit_sizes+ if streamed.commits:+ assert streamed.commit_sizes == [4 if tools else 2, len(streamed.rows)]+ if tools:+ parts = [p for row in streamed.rows for p in row["parts"] if p["type"] == "tool"]+ assert [p["tool_status"] for p in parts] == ["pending", "completed"]+ assert {p["tool_id"] for p in parts} == {"loop-call"}+ assert parts[1]["tool_output"] == "TOOL_VALUE"++[email protected]("stream", [False, True])+async def test_loop_cannot_silently_reset_capture_progress(stream):+ with pytest.raises(RuntimeError, match="state.*reset.*fresh_context=True"):+ await loop_capture(stream, fresh_context=True)++[email protected]("commit_policy", ["never", "always", "pending_tokens"])+async def test_interrupted_streamed_loop_keeps_only_completed_iterations(commit_policy):+ client, _, _, agent, session = setup(+ [+ Message("assistant", ["First draft"], message_id="draft"),+ Message("assistant", ["Final answer"], message_id="final"),+ ],+ commit_policy=commit_policy,+ commit_token_threshold=1,+ )+ loop = AgentLoopMiddleware(lambda *, iteration, **kwargs: iteration < 2)+ async with agent.run("Question", session=session, middleware=[loop], stream=True) as response:+ async for update in response:+ if "Final answer" in update.text:+ break+ assert [p["text"] for row in client.rows for p in row["parts"]] == ["Question", "First draft"]+ assert not session.state["openviking"]["pending_messages"]+ assert len(client.commits) == (0 if commit_policy == "never" else 1)+++async def test_state_rollback_blocks_flush_and_commit_but_equal_state_restoration_is_safe():+ client, provider, _, agent, session = setup()+ await agent.run("Question", session=session)+ saved = AgentSession.from_dict(json.loads(json.dumps(session.to_dict()))).state+ session.state = {}+ with pytest.raises(RuntimeError, match="state was reset"):+ await provider.flush(session)+ with pytest.raises(RuntimeError, match="state was reset"):+ await provider.commit(session)+ assert not client.commits+ session.state = saved+ await agent.run("Next", session=session)+ assert len(client.rows) == 4++[email protected]("threshold,commits", [(19, 1), (20, 1), (21, 0)])+async def test_pending_token_policy_uses_post_capture_server_count(threshold, commits):+ client, _, _, agent, session = setup(+ commit_policy="pending_tokens", commit_token_threshold=threshold+ )+ await agent.run("Question", session=session)+ assert len(client.rows) == 2+ assert len(client.commits) == commits+ if commits:+ assert client.commit_sizes == [2]+++async def test_threshold_counts_the_session_backlog_and_survives_restoration():+ client, _, _, agent, session = setup(commit_policy="pending_tokens", commit_token_threshold=30)+ await agent.run("First", session=session)+ assert not client.commits+ restored = AgentSession.from_dict(json.loads(json.dumps(session.to_dict())))+ await agent.run("Second", session=restored)+ assert client.commit_sizes == [4]+ await agent.run("Third", session=restored)+ assert client.commit_sizes == [4]+++async def test_threshold_does_not_combine_different_sessions():+ client, _, _, agent, first = setup(commit_policy="pending_tokens", commit_token_threshold=30)+ second = agent.create_session()+ await asyncio.gather(agent.run("First", session=first), agent.run("Second", session=second))+ assert not client.commits+ await agent.run("More", session=first)+ assert client.commits == [first.state["openviking"]["session_id"]]+ assert client.pending_tokens[second.state["openviking"]["session_id"]] == 20++[email protected]("commit_policy", ["never", "always", "pending_tokens"])[email protected]("stream", [False, True])+async def test_capture_disabled_keeps_recall_and_tools_without_automatic_writes(+ commit_policy, stream+):+ client, provider, model, session = await loop_capture(+ stream, tools=True, capture=False, commit_policy=commit_policy, commit_token_threshold=1+ )+ assert client.searches+ assert "Preferred format" in json.dumps([m.to_dict() for m in model.inputs[0]])+ assert len(model.inputs) == 3+ assert not client.rows and not client.commit_attempts+ assert not session.state[provider.source_id].get("recorded_message_ids")+ assert await provider.commit(session) == {"task_id": "extraction-job"}+ assert len(client.commits) == 1++[email protected]("commit_policy", ["always", "pending_tokens"])[email protected]("stream", [False, True])+async def test_commit_failure_does_not_replay_acknowledged_capture(commit_policy, stream):+ reply = Message("assistant", ["Answer"], message_id="reply")+ question = Message("user", ["Question"], message_id="question")+ client, provider, _, agent, session = setup(+ [reply, reply], commit_policy=commit_policy, commit_token_threshold=1+ )+ client.commit_error = ConnectionError("commit unavailable")++ async def run():+ if stream:+ async with agent.run(question, session=session, stream=True) as result:+ async for _ in result:+ pass+ else:+ await agent.run(question, session=session)++ with pytest.raises(Exception, match="commit unavailable"):+ await run()+ assert len(client.rows) == 2+ assert not session.state[provider.source_id]["pending_messages"]+ assert set(session.state[provider.source_id]["recorded_message_ids"]) == {"question", "reply"}+ client.commit_error = None+ await run()+ assert client.batches == 1 and len(client.rows) == 2+ assert len(client.commit_attempts) == 2 and len(client.commits) == 1+++async def test_post_capture_metadata_failure_retains_acknowledged_progress():+ reply = Message("assistant", ["Answer"], message_id="reply")+ question = Message("user", ["Question"], message_id="question")+ client, _, _, agent, session = setup(+ [reply, reply], commit_policy="pending_tokens", commit_token_threshold=1+ )+ client.metadata_error = ConnectionError("metadata unavailable")+ with pytest.raises(Exception, match="metadata unavailable"):+ await agent.run(question, session=session)+ assert len(client.rows) == 2 and not client.commit_attempts+ client.metadata_error = None+ await agent.run(question, session=session)+ assert len(client.rows) == 2 and client.batches == 1+ assert len(client.commits) == 1++[email protected]("commit_policy", ["always", "pending_tokens"])+async def test_incomplete_acknowledgement_never_triggers_commit(commit_policy):+ client, _, _, agent, session = setup(commit_policy=commit_policy, commit_token_threshold=1)+ client.ack_override = 1+ with pytest.raises(Exception, match="acknowledge the complete"):+ await agent.run("Question", session=session)+ assert not client.commit_attempts+ assert len(session.state["openviking"]["pending_messages"]) == 2+ assert not session.state["openviking"].get("recorded_message_ids")+++ "options",+ [+ {"capture": "false"},+ {"commit_policy": "manual"},+ {"commit_token_threshold": 0},+ {"commit_token_threshold": True},+ {"commit_token_threshold": 1.5},+ ],+)+def test_invalid_capture_and_commit_options_are_rejected(options):+ with pytest.raises(ValueError):+ OpenVikingContextProvider(MemoryClient(), **options)++[email protected]("commit_policy", ["always", "pending_tokens"])+async def test_disabling_capture_preserves_pending_recovery_without_automatic_commit(commit_policy):+ client, provider, _, agent, session = setup(+ commit_policy=commit_policy, commit_token_threshold=1+ )+ client.fail_batch = 1+ with pytest.raises(Exception, match="request not sent"):+ await agent.run("Question", session=session)+ provider.capture = False+ with pytest.raises(RuntimeError, match="unconfirmed"):+ await agent.run("Another", session=session)+ client.fail_batch = None+ await provider.flush(session)+ assert len(client.rows) == 2 and not client.commits+ await agent.run("Recall only", session=session)+ assert len(client.rows) == 2 and not client.commits+ await provider.commit(session)+ assert len(client.commits) == 1++[email protected]("commit_policy", ["always", "pending_tokens"])+async def test_no_eligible_capture_does_not_create_or_commit_an_empty_session(commit_policy):+ client, _, _, agent, session = setup(+ [Message("assistant", [Content("text_reasoning", text="Hidden")])],+ commit_policy=commit_policy,+ commit_token_threshold=1,+ )+ await agent.run(Message("system", ["Instructions"]), session=session)+ assert not client.rows and not client.commit_attempts and not client.sessions++[email protected]("stream", [False, True])+async def test_real_sdk_writes_tool_evidence_before_threshold_commit(monkeypatch, stream):+ rows = []+ writes = []+ pending = 0++ def handle(request):+ nonlocal pending+ assert request.headers["X-API-Key"] == "test-key"+ path = request.url.path+ if path == "/api/v1/search/search":+ result = {"rendered": "Preferred format: JSON", "entries": [{"uri": "viking://memory"}]}+ elif path.endswith("/messages/batch"):+ messages = json.loads(request.content)["messages"]+ rows.extend(messages)+ pending += 10 * len(messages)+ writes.append("capture")+ result = {"added": len(messages), "pending_tokens": pending}+ elif path.endswith("/commit"):+ assert len(rows) == 4+ assert json.loads(request.content)["keep_recent_count"] == 0+ writes.append("commit")+ pending = 0+ result = {"task_id": "extraction-job"}+ else:+ assert request.method == "GET" and path.startswith("/api/v1/sessions/")+ result = {"pending_tokens": pending}+ return httpx.Response(200, json={"status": "ok", "result": result})++ http_client = httpx.AsyncClient++ def create_http_client(**kwargs):+ return http_client(**kwargs, transport=httpx.MockTransport(handle))++ monkeypatch.setattr(httpx, "AsyncClient", create_http_client)+ client = AsyncHTTPClient(url="http://openviking.test", api_key="test-key", auth_mode="api_key")+ await client.initialize()+ try:++ def lookup_label():+ """Return the current label."""+ return "LABEL"++ model = ChatClient(+ [+ Message(+ "assistant",+ [Content("function_call", call_id="call-1", name="lookup_label", arguments={})],+ ),+ Message("assistant", ["LABEL"]),+ ]+ )+ provider = OpenVikingContextProvider(+ client, commit_policy="pending_tokens", commit_token_threshold=40+ )+ agent = Agent(model, context_providers=[provider])+ session = agent.create_session()+ if stream:+ async with agent.run(+ "Question", tools=[lookup_label], session=session, stream=True+ ) as result:+ async for _ in result:+ assert not writes+ else:+ await agent.run("Question", tools=[lookup_label], session=session)+ assert writes == ["capture", "commit"]+ parts = [p for row in rows for p in row["parts"] if p["type"] == "tool"]+ assert [p["tool_status"] for p in parts] == ["pending", "completed"]+ assert {p["tool_id"] for p in parts} == {"call-1"}+ assert parts[1]["tool_output"] == "LABEL"+ assert "Preferred format" not in json.dumps(rows)+ finally:+ await client.close()