Skip to content

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

feat(langchain): add native async integration support (#3536)

Hao Zhe8eb89a636b53
diff --git a/docs/en/agent-integrations/07-langchain-langgraph.md b/docs/en/agent-integrations/07-langchain-langgraph.md
index 2db109f41..85b478925 100644
--- a/docs/en/agent-integrations/07-langchain-langgraph.md
+++ b/docs/en/agent-integrations/07-langchain-langgraph.md
@@ -1,6 +1,6 @@
# LangChain and LangGraph
-Wire OpenViking into your LangChain or LangGraph agent as the context backend. The SDK provides a retriever, chat history, context wrapper, agent tools, LangGraph store, and middleware — all connecting to a running OpenViking server over HTTP.
+Wire OpenViking into your LangChain or LangGraph agent as the context backend. The SDK provides a retriever, chat history, context wrapper, agent tools, LangGraph store, and middleware for HTTP-backed or embedded OpenViking deployments.
## Install
@@ -21,7 +21,77 @@ tools = create_openviking_tools(
)
```
-When `url` is omitted, the adapters load connection settings from the OpenViking CLI config. Embedding and VLM providers are configured in OpenViking, not in your app.
+When both `url` and `path` are omitted, adapters use the HTTP connection settings from the OpenViking CLI config. Pass `path` to use an embedded workspace through OpenViking's synchronous client. Embedding and VLM providers are configured in OpenViking, not in your app.
+
+### Async applications
+
+The retriever, context wrapper, chat history, session recorder, and LangGraph
+middleware all have native async paths. URL-based adapters create an async
+OpenViking HTTP client automatically:
+
+```python
+docs = await retriever.ainvoke("What did the user decide?")
+result = await chain.ainvoke(
+ {"messages": [...]},
+ config={"configurable": {"session_id": "support-thread-1"}},
+)
+```
+
+Async adapters support three client modes:
+
+| Configuration | Async interface | Ownership |
+|---------------|-----------------|-----------|
+| `client=` or `async_client=` | The injected client is returned unchanged | Caller |
+| `url=`, or neither `url` nor `path` | One recovery-capable HTTP handle per event loop | Adapter |
+| `path=` | A synchronous embedded client invoked in a worker thread | Adapter |
+
+Long-lived applications can initialize one caller-owned async client and reuse
+it across adapters running on the same event loop:
+
+```python
+from openviking.client import AsyncHTTPClient
+from openviking.integrations.langchain import OpenVikingRetriever
+
+client = AsyncHTTPClient(url="http://localhost:1933", api_key="...")
+await client.initialize()
+try:
+ retriever = OpenVikingRetriever(async_client=client)
+ docs = await retriever.ainvoke("deployment decision")
+finally:
+ await client.close()
+```
+
+Injected async clients are bound to the event loop that initializes them. Do
+not share one injected async client across event loops; create and manage one
+client per loop instead. An injected synchronous client remains safe to use
+from async adapter methods because its calls run in a worker thread.
+
+For embedded `path=` adapters, the synchronous fallback is intentional:
+`SyncOpenViking` keeps the stateful embedded engine on OpenViking's shared
+background loop while the application event loop remains non-blocking. To use
+native embedded async methods, construct and initialize `AsyncOpenViking`
+yourself, inject it with `async_client=`, use it from that same event loop, and
+close it yourself. Only one embedded workspace can be live per process; close
+or reset it before selecting another workspace.
+
+`OpenVikingChatMessageHistory` provides `aget_messages()`, `aadd_messages()`,
+and `aclear()`. `OpenVikingSessionRecorder` provides `arecord()`, `aflush()`,
+and `aclose()`. Async LangGraph runs select `awrap_model_call()` and
+`aafter_agent()` automatically. Concurrent first use creates one internal HTTP
+client per adapter and event loop.
+
+Adapters never close an injected client. When an adapter creates its own client,
+release it with `await retriever.aclose()`, `await assembler.aclose()`,
+`await middleware.aclose()`, `await history.aclose()`, or
+`await recorder.aclose()` as appropriate. Calling synchronous
+`recorder.close()` after an async operation raises and intentionally leaves the
+recorder open so `await recorder.aclose()` can still release every resource.
+When possible, close HTTP-backed adapters before shutting down their event
+loops; cleanup after an originating loop has already ended is best-effort.
+`with_openviking_context()` returns LangChain's standard
+`RunnableWithMessageHistory`, which has no close hook. Long-lived async
+applications using that helper should therefore inject and close a
+caller-owned async client as shown above.
## Peer Identity
@@ -152,6 +222,10 @@ commit. When supplying `context_parts`, resend them only if
has pending content. After `close()`, the recorder cannot be reused; injected
clients remain owned by the caller.
+For async lifecycles, use the equivalent `await recorder.arecord(...)`,
+`await recorder.aflush(...)`, and `await recorder.aclose()` methods. Do not
+finish an async lifecycle with `recorder.close()`.
+
## Try the examples
The repository includes runnable examples that work without model credentials using an in-memory test client:
diff --git a/docs/zh/agent-integrations/07-langchain-langgraph.md b/docs/zh/agent-integrations/07-langchain-langgraph.md
index d9bbb342f..1c35eb68a 100644
--- a/docs/zh/agent-integrations/07-langchain-langgraph.md
+++ b/docs/zh/agent-integrations/07-langchain-langgraph.md
@@ -1,6 +1,6 @@
# LangChain 和 LangGraph
-把 OpenViking 接入你的 LangChain 或 LangGraph Agent 作为上下文后端。SDK 提供 retriever、chat history、context wrapper、agent tools、LangGraph store 和 middleware——全部通过 HTTP 连接运行中的 OpenViking 服务。
+把 OpenViking 接入你的 LangChain 或 LangGraph Agent 作为上下文后端。SDK 提供 retriever、chat history、context wrapper、agent tools、LangGraph store 和 middleware,可连接 HTTP 服务或嵌入式 OpenViking。
## 安装
@@ -21,7 +21,73 @@ tools = create_openviking_tools(
)
```
-省略 `url` 时,适配器自动从 OpenViking CLI 配置加载连接信息。Embedding 和 VLM 在 OpenViking 侧配置,不在你的应用中。
+同时省略 `url` 和 `path` 时,适配器会使用 OpenViking CLI 配置中的 HTTP 连接信息。传入 `path` 时,通过 OpenViking 同步 client 使用嵌入式 workspace。Embedding 和 VLM 在 OpenViking 侧配置,不在你的应用中。
+
+### 异步应用
+
+Retriever、context wrapper、chat history、session recorder 和 LangGraph
+middleware 都支持原生异步路径。通过 URL 配置时,适配器会自动创建异步 OpenViking HTTP
+client:
+
+```python
+docs = await retriever.ainvoke("用户之前做了什么决定?")
+result = await chain.ainvoke(
+ {"messages": [...]},
+ config={"configurable": {"session_id": "support-thread-1"}},
+)
+```
+
+异步适配器支持三种 client 模式:
+
+| 配置 | 异步接口 | 所有权 |
+|------|----------|--------|
+| `client=` 或 `async_client=` | 原样返回注入的 client | 调用方 |
+| `url=`,或同时省略 `url` 和 `path` | 每个 event loop 一个支持恢复的 HTTP handle | Adapter |
+| `path=` | 在 worker thread 中调用同步嵌入式 client | Adapter |
+
+长期运行的应用可以初始化一个由调用方管理的异步 client,并在同一 event loop
+内的多个适配器之间复用:
+
+```python
+from openviking.client import AsyncHTTPClient
+from openviking.integrations.langchain import OpenVikingRetriever
+
+client = AsyncHTTPClient(url="http://localhost:1933", api_key="...")
+await client.initialize()
+try:
+ retriever = OpenVikingRetriever(async_client=client)
+ docs = await retriever.ainvoke("部署决定")
+finally:
+ await client.close()
+```
+
+注入的异步 client 会绑定到初始化它的 event loop。不要跨 event loop 共享同一个
+注入异步 client;应为每个 loop 分别创建并管理 client。注入的同步 client 仍可安全地
+用于异步 adapter 方法,因为调用会在 worker thread 中执行。
+
+`path=` 嵌入式 adapter 使用同步 fallback 是有意设计:`SyncOpenViking` 会让有状态的
+嵌入式引擎保持在 OpenViking 的共享后台 loop 上,同时不阻塞应用 event loop。若要使用
+原生嵌入式异步方法,请自行创建并初始化 `AsyncOpenViking`,通过 `async_client=` 注入,
+在同一个 event loop 中使用,并由调用方自行关闭。每个进程同时只能运行一个嵌入式
+workspace;切换 workspace 前应先关闭或 reset 当前 client。
+
+`OpenVikingChatMessageHistory` 提供 `aget_messages()`、`aadd_messages()` 和
+`aclear()`;`OpenVikingSessionRecorder` 提供 `arecord()`、`aflush()` 和
+`aclose()`。异步 LangGraph 运行会自动选择 `awrap_model_call()` 和
+`aafter_agent()`。同一 adapter 首次被并发调用时,每个 event loop 只会创建一个内部
+HTTP client。
+
+Adapter 不会关闭调用方注入的 client。对于 adapter 自行创建的 client,应按实际使用的组件调用
+`await retriever.aclose()`、`await assembler.aclose()`、
+`await middleware.aclose()`、`await history.aclose()` 或
+`await recorder.aclose()`。如果 async 操作完成后误调用同步
+`recorder.close()`,该方法会抛出异常并保持 recorder 可用,以便后续
+`await recorder.aclose()` 仍能释放全部资源。
+如果条件允许,应在关闭 event loop 前关闭 HTTP-backed adapter;原始 loop 已结束后的
+清理属于 best-effort。
+`with_openviking_context()` 返回 LangChain 标准的
+`RunnableWithMessageHistory`,而该类型没有 close hook。因此长期运行的异步应用使用此
+helper 时,应按上例注入并关闭由调用方管理的异步 client。
## Peer 身份
@@ -148,6 +214,10 @@ commit 策略。如果后续批次或写入后的 commit 失败,`OpenVikingPar
存在待提交内容时强制 commit。`close()` 后 recorder 不可复用;由调用方注入的 client
仍归调用方管理。
+异步生命周期使用对应的 `await recorder.arecord(...)`、
+`await recorder.aflush(...)` 和 `await recorder.aclose()`。不要用
+`recorder.close()` 结束异步生命周期。
+
## 运行示例
仓库内提供了可直接运行的最小示例,使用内存测试客户端,无需模型凭证:
diff --git a/openviking/integrations/langchain/client.py b/openviking/integrations/langchain/client.py
index e81ca3260..c6f7dc0c7 100644
--- a/openviking/integrations/langchain/client.py
+++ b/openviking/integrations/langchain/client.py
@@ -4,11 +4,15 @@
from __future__ import annotations
+import asyncio
+import copy
import inspect
import json
import logging
from dataclasses import dataclass
-from typing import Any, Iterable, Literal
+from typing import Any, Callable, Iterable, Literal
+
+from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
logger = logging.getLogger(__name__)
@@ -39,6 +43,7 @@ _RECOVERABLE_RUNTIME_MESSAGE_FRAGMENTS = (
"attached to a different loop",
"bound to a different event loop",
)
+_ASYNC_INITIALIZATION_LOCKS_ATTR = "_openviking_integration_initialize_locks"
class OptionalDependencyError(ImportError):
@@ -68,6 +73,7 @@ class OpenVikingConnection:
timeout: float = 60.0
extra_headers: dict[str, str] | None = None
auto_initialize: bool = True
+ async_client: Any = None
@dataclass(slots=True)
@@ -141,6 +147,161 @@ class OpenVikingClientHandle:
return recovered_method
+class OpenVikingAsyncClientHandle:
+ """Lazy, loop-local async client wrapper with one-shot recovery for safe reads.
+
+ Method calls through the handle are recovery-safe. Direct client attribute
+ access is best-effort and may be unavailable while recovery replaces the
+ underlying client.
+ """
+
+ def __init__(self, connection: OpenVikingConnection):
+ self._connection = connection
+ self._client: Any = None
+ self._client_lock = asyncio.Lock()
+ try:
+ self._loop: asyncio.AbstractEventLoop | None = asyncio.get_running_loop()
+ except RuntimeError:
+ self._loop = None
+
+ @property
+ def _initialized(self) -> bool:
+ client = self._client
+ return bool(client is not None and _async_client_is_initialized(client))
+
+ async def initialize(self) -> None:
+ """Initialize the underlying client once."""
+
+ await self.get()
+
+ async def close(self) -> None:
+ owner_loop = self._loop
+ current_loop = asyncio.get_running_loop()
+ if owner_loop is None or owner_loop is current_loop:
+ await self.reset()
+ return
+ if owner_loop.is_running():
+ reset = self.reset()
+ try:
+ future = asyncio.run_coroutine_threadsafe(reset, owner_loop)
+ except RuntimeError:
+ reset.close()
+ else:
+ await asyncio.wrap_future(future)
+ return
+ await self._reset_without_lock()
+
+ async def reset(self) -> None:
+ async with self._client_lock:
+ client = self._client
+ self._client = None
+ await self._close_client(client)
+
+ async def _reset_if_current(self, client: Any) -> None:
+ """Reset only when ``client`` is still the active snapshot."""
+
+ async with self._client_lock:
+ if self._client is not client:
+ return
+ self._client = None
+ await self._close_client(client)
+
+ async def _reset_without_lock(self) -> None:
+ """Detach a client after its originating loop has stopped."""
+
+ client = self._client
+ self._client = None
+ await self._close_client(client)
+
+ async def _close_client(self, client: Any) -> None:
+ if client is None:
+ return
+ try:
+ await aclose_openviking_client(client)
+ except Exception:
+ logger.debug("OpenViking async client close during recovery failed", exc_info=True)
+
+ async def get(self) -> Any:
+ """Return the current client snapshot, initializing it when necessary.
+
+ Read raw properties immediately and do not retain this client: a later
+ recovery may replace and close it.
+ """
+
+ current_loop = asyncio.get_running_loop()
+ if self._loop is None:
+ self._loop = current_loop
+ elif self._loop is not current_loop:
+ raise RuntimeError(
+ "OpenVikingAsyncClientHandle is loop-local and cannot be reused "
+ "from another event loop"
+ )
+ if self._client is None:
+ async with self._client_lock:
+ if self._client is None:
+ self._client = await _create_async_client_from_connection(self._connection)
+ return self._client
+
+ async def _openviking_acall(self, method_name: str, /, **kwargs: Any) -> Any:
+ return await self._call_with_recovery(method_name, **kwargs)
+
+ async def _call_with_recovery(
+ self,
+ method_name: str,
+ /,
+ *args: Any,
+ **kwargs: Any,
+ ) -> Any:
+ client = await self.get()
+ try:
+ return await _acall_client_method(
+ client,
+ method_name,
+ *args,
+ **kwargs,
+ )
+ except Exception as exc:
+ if not _is_recoverable_client_error(exc):
+ raise
+ await self._reset_if_current(client)
+ if not _should_retry_method(method_name):
+ raise
+ retry_client = await self.get()
+ try:
+ return await _acall_client_method(
+ retry_client,
+ method_name,
+ *args,
+ **kwargs,
+ )
+ except Exception as retry_exc:
+ if _is_recoverable_client_error(retry_exc):
+ await self._reset_if_current(retry_client)
+ raise
+
+ def __copy__(self) -> OpenVikingAsyncClientHandle:
+ return self
+
+ def __deepcopy__(self, memo: dict[int, Any]) -> OpenVikingAsyncClientHandle:
+ copied = type(self)(copy.deepcopy(self._connection, memo))
+ memo[id(self)] = copied
+ return copied
+
+ def __getattr__(self, name: str) -> Any:
+ if name.startswith("__") and name.endswith("__"):
+ raise AttributeError(name)
+ client = self._client
+ if client is not None:
+ attr = getattr(client, name)
+ if not callable(attr):
+ return attr
+
+ async def recovered_method(*args: Any, **kwargs: Any) -> Any:
+ return await self._call_with_recovery(name, *args, **kwargs)
+
+ return recovered_method
+
+
def ensure_client(connection: OpenVikingConnection) -> Any:
"""Return an initialized OpenViking client from explicit or connection settings."""
@@ -158,6 +319,49 @@ def ensure_client(connection: OpenVikingConnection) -> Any:
return client
+async def ensure_async_client(
+ connection: OpenVikingConnection,
+ *,
+ client_cache: LoopScopedAsyncClientCache | None = None,
+ embedded_client_factory: Callable[[], Any] | None = None,
+) -> Any:
+ """Return a client suitable for non-blocking OpenViking calls.
+
+ An explicitly supplied async client is preferred. Existing synchronous
+ clients remain supported and are dispatched through a worker thread by
+ :func:`acall_openviking`. Internally created HTTP handles can be scoped to
+ the running loop with ``client_cache``. Embedded ``path=`` connections
+ intentionally use the synchronous client so their stateful async internals
+ remain on OpenViking's shared background loop.
+ """
+
+ client = connection.async_client
+ if client is None and connection.client is not None:
+ client = connection.client
+ if client is None:
+ if _uses_http_client(connection):
+ if client_cache is None:
+ handle = OpenVikingAsyncClientHandle(connection)
+ else:
+ handle = client_cache.get(lambda: OpenVikingAsyncClientHandle(connection))
+ if connection.auto_initialize:
+ await handle.get()
+ return handle
+ if embedded_client_factory is not None:
+ if client_cache is not None:
+ # The thread hop is load-bearing: without a running event loop,
+ # the embedded singleton occupies the cache's shared fallback slot.
+ return await asyncio.to_thread(
+ client_cache.get,
+ embedded_client_factory,
+ )
+ return await asyncio.to_thread(embedded_client_factory)
+ return await asyncio.to_thread(_create_client_from_connection, connection)
+ if connection.auto_initialize and hasattr(client, "initialize"):
+ await _ainitialize_client(client)
+ return client
+
+
def apply_commit_policy(
client: Any,
session_id: str,
@@ -194,6 +398,47 @@ def apply_commit_policy(
)
+async def aapply_commit_policy(
+ client: Any,
+ session_id: str,
+ policy: OpenVikingCommitPolicy | None,
+) -> dict[str, Any] | None:
+ """Apply the configured session commit policy without blocking the event loop."""
+
+ if policy is None or policy.mode == "never":
+ return None
+ if policy.mode == "always":
+ return await acall_openviking(
+ client,
+ "commit_session",
+ session_id=session_id,
+ )
+ if policy.mode != "pending_tokens":
+ raise ValueError(f"Unsupported OpenViking commit policy: {policy.mode}")
+
+ try:
+ session = await acall_openviking(
+ client,
+ "get_session",
+ session_id=session_id,
+ auto_create=False,
+ )
+ except Exception:
+ logger.debug(
+ "Skipping OpenViking pending-token commit because session lookup failed",
+ exc_info=True,
+ )
+ return None
+ pending_tokens = int(item_value(session, "pending_tokens", 0) or 0)
+ if pending_tokens < policy.pending_token_threshold:
+ return None
+ return await acall_openviking(
+ client,
+ "commit_session",
+ session_id=session_id,
+ )
+
+
def call_openviking(client: Any, method_name: str, /, **kwargs: Any) -> Any:
"""Call a client method, filtering kwargs unsupported by local/HTTP variants."""
@@ -203,7 +448,17 @@ def call_openviking(client: Any, method_name: str, /, **kwargs: Any) -> Any:
return _call_client_method(client, method_name, **kwargs)
+async def acall_openviking(client: Any, method_name: str, /, **kwargs: Any) -> Any:
+ """Call an async or sync client method without blocking the event loop."""
+
+ openviking_call = getattr(client, "_openviking_acall", None)
+ if callable(openviking_call):
+ return await openviking_call(method_name, **kwargs)
+ return await _acall_client_method(client, method_name, **kwargs)
+
+
def _create_client_from_connection(connection: OpenVikingConnection) -> Any:
+ client: Any
if connection.url or connection.path is None:
from openviking.client import SyncHTTPClient
@@ -228,6 +483,70 @@ def _create_client_from_connection(connection: OpenVikingConnection) -> Any:
return client
+async def _create_async_client_from_connection(connection: OpenVikingConnection) -> Any:
+ if not _uses_http_client(connection):
+ raise ValueError("Native async clients are created automatically only for HTTP connections")
+
+ from openviking.client import AsyncHTTPClient
+
+ client: Any = AsyncHTTPClient(
+ url=connection.url,
+ api_key=connection.api_key,
+ account=connection.account,
+ user=connection.user,
+ user_id=connection.user_id,
+ actor_peer_id=connection.actor_peer_id,
+ timeout=connection.timeout,
+ extra_headers=connection.extra_headers,
+ )
+
+ try:
+ if connection.auto_initialize and hasattr(client, "initialize"):
+ await _ainitialize_client(client)
+ except BaseException:
+ try:
+ await aclose_openviking_client(client)
+ except Exception:
+ logger.debug(
+ "OpenViking async client close after initialization failure failed",
+ exc_info=True,
+ )
+ raise
+ return client
+
+
+async def aclose_openviking_client(client: Any) -> None:
+ """Close an async or sync OpenViking client without blocking the event loop."""
+
+ close = getattr(client, "close", None)
+ if not callable(close):
+ return
+ if inspect.iscoroutinefunction(close):
+ await close()
+ return
+ result = await asyncio.to_thread(close)
+ if inspect.isawaitable(result):
+ await result
+
+
+async def aclose_openviking_clients(*clients: Any) -> None:
+ """Close every distinct client and re-raise the first cleanup failure."""
+
+ seen: set[int] = set()
+ first_error: BaseException | None = None
+ for client in clients:
+ if client is None or id(client) in seen:
+ continue
+ seen.add(id(client))
+ try:
+ await aclose_openviking_client(client)
+ except BaseException as exc:
+ if first_error is None:
+ first_error = exc
+ if first_error is not None:
+ raise first_error
+
+
def _call_client_method(
client: Any,
method_name: str,
@@ -236,27 +555,100 @@ def _call_client_method(
**kwargs: Any,
) -> Any:
method = getattr(client, method_name)
+ return method(*args, **_filter_client_kwargs(method, kwargs))
+
+
+async def _acall_client_method(
+ client: Any,
+ method_name: str,
+ /,
+ *args: Any,
+ **kwargs: Any,
+) -> Any:
+ method = getattr(client, method_name)
+ filtered_kwargs = _filter_client_kwargs(method, kwargs)
+ if inspect.iscoroutinefunction(method):
+ return await method(*args, **filtered_kwargs)
+ result = await asyncio.to_thread(method, *args, **filtered_kwargs)
+ if inspect.isawaitable(result):
+ return await result
+ return result
+
+
+async def _ainitialize_client(client: Any) -> None:
+ if _async_client_is_initialized(client):
+ return
+ lock = _async_client_initialization_lock(client)
+ async with lock:
+ if _async_client_is_initialized(client):
+ return
+ await _acall_client_method(client, "initialize")
+ try:
+ client._openviking_integration_initialized = True
+ except Exception:
+ pass
+
+
+def _async_client_initialization_lock(client: Any) -> asyncio.Lock:
+ try:
+ locks = inspect.getattr_static(client, _ASYNC_INITIALIZATION_LOCKS_ATTR)
+ except AttributeError:
+ locks = LoopScopedAsyncClientCache()
+ try:
+ setattr(client, _ASYNC_INITIALIZATION_LOCKS_ATTR, locks)
+ except Exception:
+ return asyncio.Lock()
+ if not isinstance(locks, LoopScopedAsyncClientCache):
+ locks = LoopScopedAsyncClientCache()
+ try:
+ setattr(client, _ASYNC_INITIALIZATION_LOCKS_ATTR, locks)
+ except Exception:
+ return asyncio.Lock()
+ return locks.get(asyncio.Lock)
+
+
+def _uses_http_client(connection: OpenVikingConnection) -> bool:
+ """Return whether connection settings select the HTTP transport."""
+
+ return bool(connection.url) or connection.path is None
+
+
+def _async_client_is_initialized(client: Any) -> bool:
+ for name in ("_initialized", "_http"):
+ try:
+ inspect.getattr_static(client, name)
+ except AttributeError:
+ continue
+ value = getattr(client, name, None)
+ if name == "_http":
+ return value is not None
+ return bool(value)
+ try:
+ inspect.getattr_static(client, "_openviking_integration_initialized")
+ except AttributeError:
+ return False
+ return bool(getattr(client, "_openviking_integration_initialized", False))
+
+
+def _filter_client_kwargs(method: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+ """Drop ``None`` and arguments unsupported by a concrete client variant."""
+
try:
signature = inspect.signature(method)
except (TypeError, ValueError):
- return method(
- *args,
- **{key: value for key, value in kwargs.items() if value is not None},
- )
+ return {key: value for key, value in kwargs.items() if value is not None}
accepts_kwargs = any(
parameter.kind == inspect.Parameter.VAR_KEYWORD
for parameter in signature.parameters.values()
)
if accepts_kwargs:
- filtered = {key: value for key, value in kwargs.items() if value is not None}
- else:
- filtered = {
- key: value
- for key, value in kwargs.items()
- if value is not None and key in signature.parameters
- }
- return method(*args, **filtered)
+ return {key: value for key, value in kwargs.items() if value is not None}
+ return {
+ key: value
+ for key, value in kwargs.items()
+ if value is not None and key in signature.parameters
+ }
def _should_retry_method(method_name: str) -> bool:
diff --git a/openviking/integrations/langchain/context.py b/openviking/integrations/langchain/context.py
index fc71e085c..4b292b5e2 100644
--- a/openviking/integrations/langchain/context.py
+++ b/openviking/integrations/langchain/context.py
@@ -4,6 +4,7 @@
from __future__ import annotations
+import asyncio
import logging
from collections.abc import Callable
from dataclasses import dataclass, field
@@ -21,7 +22,10 @@ except ImportError as exc: # pragma: no cover - exercised by optional import pa
from openviking.integrations.langchain.client import (
OpenVikingCommitPolicy,
OpenVikingConnection,
+ acall_openviking,
+ aclose_openviking_clients,
call_openviking,
+ ensure_async_client,
ensure_client,
extract_message_text,
get_latest_user_text,
@@ -32,6 +36,7 @@ from openviking.integrations.langchain.history import (
)
from openviking.integrations.langchain.messages import OPENVIKING_CONTEXT_MARKER
from openviking.integrations.langchain.retrievers import OpenVikingRetriever
+from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
logger = logging.getLogger(__name__)
@@ -53,6 +58,7 @@ class OpenVikingSessionContextAssembler:
self,
*,
client: Any = None,
+ async_client: Any = None,
retriever: OpenVikingRetriever | None = None,
url: str | None = None,
api_key: str | None = None,
@@ -75,6 +81,7 @@ class OpenVikingSessionContextAssembler:
):
self._connection = OpenVikingConnection(
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -88,6 +95,7 @@ class OpenVikingSessionContextAssembler:
)
self.retriever = retriever or OpenVikingRetriever(
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -108,7 +116,11 @@ class OpenVikingSessionContextAssembler:
self.include_active_messages = include_active_messages
self.include_recall = include_recall
self.recall_header = recall_header
+ self._owns_client = client is None
+ self._owns_retriever = retriever is None
self._client_cache: Any = None
+ self._async_clients = LoopScopedAsyncClientCache()
+ self._closed = False
def assemble(
self,
@@ -123,6 +135,30 @@ class OpenVikingSessionContextAssembler:
session_id,
query,
)
+ return self._assembled_context(session_context, recall_documents)
+
+ async def aassemble(
+ self,
+ *,
+ session_id: str,
+ query: str = "",
+ ) -> OpenVikingAssembledContext:
+ """Asynchronously assemble session and recall context."""
+
+ client = await self._get_async_client()
+ await self._aensure_session(client, session_id)
+ session_context = await self._aget_session_context(client, session_id)
+ recall_documents = await self._aget_recall_documents(
+ session_id,
+ query,
+ )
+ return self._assembled_context(session_context, recall_documents)
+
+ def _assembled_context(
+ self,
+ session_context: dict[str, Any],
+ recall_documents: list[Any],
+ ) -> OpenVikingAssembledContext:
block = self._format_context_block(session_context, recall_documents)
return OpenVikingAssembledContext(
block=block,
@@ -132,10 +168,66 @@ class OpenVikingSessionContextAssembler:
)
def _get_client(self) -> Any:
+ self._raise_if_closed()
if self._client_cache is None:
self._client_cache = ensure_client(self._connection)
return self._client_cache
+ async def get_async_client(self) -> Any:
+ """Return the async client interface used by this assembler.
+
+ Injected clients are returned unchanged and remain caller-owned.
+ HTTP-backed connections return an internally managed, loop-local handle
+ whose method calls support recovery. Direct attributes on that handle
+ are best-effort during recovery; use ``await handle.get()`` only to read
+ raw properties immediately because recovery may replace that snapshot.
+ Embedded ``path=`` connections return an adapter-owned synchronous
+ client whose calls are dispatched through a worker thread.
+ """
+
+ self._raise_if_closed()
+ client = await ensure_async_client(
+ self._connection,
+ client_cache=self._async_clients,
+ embedded_client_factory=self._get_client,
+ )
+ self._raise_if_closed()
+ return client
+
+ async def _get_async_client(self) -> Any:
+ return await self.get_async_client()
+
+ async def aclose(self) -> None:
+ """Release clients and the default retriever owned by this assembler."""
+
+ if self._closed:
+ return
+ self._closed = True
+ sync_client = self._client_cache
+ self._client_cache = None
+ async_clients = await asyncio.to_thread(self._async_clients.pop_all)
+
+ first_error: BaseException | None = None
+ try:
+ await aclose_openviking_clients(
+ sync_client if self._owns_client else None,
+ *async_clients,
+ )
+ except BaseException as exc:
+ first_error = exc
+ if self._owns_retriever:
+ try:
+ await self.retriever.aclose()
+ except BaseException as exc:
+ if first_error is None:
+ first_error = exc
+ if first_error is not None:
+ raise first_error
+
+ def _raise_if_closed(self) -> None:
+ if self._closed:
+ raise RuntimeError("OpenVikingSessionContextAssembler is closed")
+
def _ensure_session(self, client: Any, session_id: str) -> None:
try:
call_openviking(client, "create_session", session_id=session_id)
@@ -143,6 +235,12 @@ class OpenVikingSessionContextAssembler:
logger.debug("OpenViking session ensure failed", exc_info=True)
pass
+ async def _aensure_session(self, client: Any, session_id: str) -> None:
+ try:
+ await acall_openviking(client, "create_session", session_id=session_id)
+ except Exception:
+ logger.debug("OpenViking session ensure failed", exc_info=True)
+
def _get_session_context(self, client: Any, session_id: str) -> dict[str, Any]:
if not self.include_session_context:
return {}
@@ -157,6 +255,24 @@ class OpenVikingSessionContextAssembler:
logger.debug("OpenViking session context assembly failed", exc_info=True)
return {}
+ async def _aget_session_context(
+ self,
+ client: Any,
+ session_id: str,
+ ) -> dict[str, Any]:
+ if not self.include_session_context:
+ return {}
+ try:
+ return await acall_openviking(
+ client,
+ "get_session_context",
+ session_id=session_id,
+ token_budget=self.token_budget,
+ )
+ except Exception:
+ logger.debug("OpenViking session context assembly failed", exc_info=True)
+ return {}
+
def _get_recall_documents(
self,
session_id: str,
@@ -175,6 +291,24 @@ class OpenVikingSessionContextAssembler:
logger.debug("OpenViking recall retrieval failed", exc_info=True)
return []
+ async def _aget_recall_documents(
+ self,
+ session_id: str,
+ query: str,
+ ) -> list[Any]:
+ if not self.include_recall or not query:
+ return []
+ try:
+ return list(
+ await _retriever_for_session(
+ self.retriever,
+ session_id,
+ ).ainvoke(query)
+ )
+ except Exception:
+ logger.debug("OpenViking recall retrieval failed", exc_info=True)
+ return []
+
def _format_context_block(
self,
session_context: dict[str, Any],
@@ -220,6 +354,7 @@ def with_openviking_context(
runnable: Any,
*,
client: Any = None,
+ async_client: Any = None,
url: str | None = None,
api_key: str | None = None,
account: str | None = None,
@@ -248,6 +383,7 @@ def with_openviking_context(
assembler = OpenVikingSessionContextAssembler(
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -289,6 +425,7 @@ def with_openviking_context(
peer_id,
),
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -335,7 +472,10 @@ def with_openviking_context(
session_history_factory = fixed_session_history_factory
history_factory_config = None
- def inject(input_value: Any, config: dict[str, Any] | None = None) -> Any:
+ def prepare_injection(
+ input_value: Any,
+ config: dict[str, Any] | None,
+ ) -> tuple[str, tuple[str, str], str] | None:
resolved_session_id = session_id or _session_id_from_config(
config,
key=session_id_config_key,
@@ -347,25 +487,52 @@ def with_openviking_context(
)
active_peer_ids[resolved_session_id] = resolved_peer_id
if not inject_context:
- return input_value
+ return None
pending_key = _pending_context_key(resolved_session_id, resolved_peer_id)
pending_context_parts.pop(pending_key, None)
query = _latest_user_text_from_input(input_value, input_messages_key)
- assembled = assembler.assemble(
- session_id=resolved_session_id,
- query=query,
- )
+ return resolved_session_id, pending_key, query
+
+ def apply_injection(
+ input_value: Any,
+ pending_key: tuple[str, str],
+ assembled: OpenVikingAssembledContext,
+ ) -> Any:
if not assembled.block:
return input_value
if assembled.context_parts:
pending_context_parts[pending_key] = assembled.context_parts
return _inject_system_context(input_value, assembled.block, input_messages_key)
+ def inject(input_value: Any, config: dict[str, Any] | None = None) -> Any:
+ prepared = prepare_injection(input_value, config)
+ if prepared is None:
+ return input_value
+ resolved_session_id, pending_key, query = prepared
+ assembled = assembler.assemble(
+ session_id=resolved_session_id,
+ query=query,
+ )
+ return apply_injection(input_value, pending_key, assembled)
+
+ async def ainject(input_value: Any, config: dict[str, Any] | None = None) -> Any:
+ prepared = prepare_injection(input_value, config)
+ if prepared is None:
+ return input_value
+ resolved_session_id, pending_key, query = prepared
+ assembled = await assembler.aassemble(
+ session_id=resolved_session_id,
+ query=query,
+ )
+ return apply_injection(input_value, pending_key, assembled)
+
def clear_pending_on_error(_run: Any, config: dict[str, Any] | None = None) -> None:
del config
pending_context_parts.clear()
- bound = (RunnableLambda(inject) | runnable).with_listeners(on_error=clear_pending_on_error)
+ bound = (RunnableLambda(inject, afunc=ainject) | runnable).with_listeners(
+ on_error=clear_pending_on_error
+ )
return RunnableWithMessageHistory(
bound,
session_history_factory,
diff --git a/openviking/integrations/langchain/history.py b/openviking/integrations/langchain/history.py
index f16ddf2b7..4f27328b3 100644
--- a/openviking/integrations/langchain/history.py
+++ b/openviking/integrations/langchain/history.py
@@ -18,6 +18,7 @@ except ImportError as exc: # pragma: no cover - exercised by optional import pa
from openviking.integrations.langchain.client import (
OpenVikingCommitPolicy,
+ acall_openviking,
call_openviking,
)
from openviking.integrations.langchain.messages import (
@@ -45,6 +46,7 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
session_id: str,
*,
client: Any = None,
+ async_client: Any = None,
url: str | None = None,
api_key: str | None = None,
account: str | None = None,
@@ -75,6 +77,7 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
self._pending_context_parts: list[dict[str, Any]] = []
self._recorder = OpenVikingSessionRecorder(
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -115,6 +118,24 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
return restore_openviking_messages(context.get("messages") or [])
+ async def aget_messages(self) -> list[BaseMessage]:
+ """Asynchronously return active messages from the OpenViking session."""
+
+ client = await self._get_async_client()
+ try:
+ context = await acall_openviking(
+ client,
+ "get_session_context",
+ session_id=self.session_id,
+ token_budget=self.token_budget,
+ )
+ except Exception:
+ logger.debug("OpenViking chat history context fetch failed", exc_info=True)
+ await self._aensure_session(client)
+ return []
+
+ return restore_openviking_messages(context.get("messages") or [])
+
def add_messages(self, messages: Sequence[BaseMessage]) -> None:
if not self._pending_context_parts and self.context_parts_provider:
self._pending_context_parts = list(self.context_parts_provider(self.session_id))
@@ -132,21 +153,57 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
if result.context_attached:
self._acknowledge_context_parts()
+ async def aadd_messages(self, messages: Sequence[BaseMessage]) -> None:
+ """Asynchronously persist messages through the shared session recorder."""
+
+ if not self._pending_context_parts and self.context_parts_provider:
+ self._pending_context_parts = list(self.context_parts_provider(self.session_id))
+ try:
+ result = await self._recorder.arecord(
+ self.session_id,
+ messages,
+ peer_id=self._effective_peer_id(),
+ context_parts=self._pending_context_parts,
+ )
+ except OpenVikingPartialWriteError as exc:
+ if exc.context_attached:
+ self._acknowledge_context_parts()
+ raise
+ if result.context_attached:
+ self._acknowledge_context_parts()
+
def clear(self) -> None:
client = self._get_client()
call_openviking(client, "delete_session", session_id=self.session_id)
self._ensure_session(client)
self._acknowledge_context_parts()
+ async def aclear(self) -> None:
+ """Asynchronously reset this OpenViking session."""
+
+ client = await self._get_async_client()
+ await acall_openviking(client, "delete_session", session_id=self.session_id)
+ await self._aensure_session(client)
+ self._acknowledge_context_parts()
+
def close(self) -> None:
"""Release resources owned by this history adapter."""
self._acknowledge_context_parts()
self._recorder.close()
+ async def aclose(self) -> None:
+ """Asynchronously release resources owned by this history adapter."""
+
+ self._acknowledge_context_parts()
+ await self._recorder.aclose()
+
def _get_client(self) -> Any:
return self._recorder.client
+ async def _get_async_client(self) -> Any:
+ return await self._recorder.get_async_client()
+
def _ensure_session(self, client: Any) -> None:
try:
call_openviking(client, "create_session", session_id=self.session_id)
@@ -154,6 +211,12 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
logger.debug("OpenViking chat history session ensure failed", exc_info=True)
pass
+ async def _aensure_session(self, client: Any) -> None:
+ try:
+ await acall_openviking(client, "create_session", session_id=self.session_id)
+ except Exception:
+ logger.debug("OpenViking chat history session ensure failed", exc_info=True)
+
def _effective_peer_id(self) -> str | None:
if self.peer_id_provider is None:
value = self.peer_id
diff --git a/openviking/integrations/langchain/middleware.py b/openviking/integrations/langchain/middleware.py
index 101e8c698..84349765e 100644
--- a/openviking/integrations/langchain/middleware.py
+++ b/openviking/integrations/langchain/middleware.py
@@ -5,11 +5,12 @@
from __future__ import annotations
import json
+from dataclasses import dataclass
from typing import Any, Callable
try:
from langchain.agents.middleware import AgentMiddleware
- from langchain.agents.middleware.types import ModelRequest
+ from langchain.agents.middleware.types import AgentState, ModelRequest
from langchain_core.messages import (
AIMessage,
BaseMessage,
@@ -27,7 +28,10 @@ from openviking.integrations.langchain.client import (
extract_message_text,
get_latest_user_text,
)
-from openviking.integrations.langchain.context import OpenVikingSessionContextAssembler
+from openviking.integrations.langchain.context import (
+ OpenVikingAssembledContext,
+ OpenVikingSessionContextAssembler,
+)
from openviking.integrations.langchain.recording import (
OpenVikingPartialWriteError,
OpenVikingSessionRecorder,
@@ -41,6 +45,18 @@ _SESSION_ID_ERROR = (
)
+@dataclass(slots=True)
+class _CapturePlan:
+ session_id: str
+ peer_id: str | None
+ key: tuple[str, str]
+ messages: list[Any]
+ signatures: tuple[str, ...]
+ start: int
+ context_parts: list[dict[str, Any]]
+ unchanged: bool = False
+
+
class OpenVikingContextMiddleware(AgentMiddleware):
"""Inject OpenViking recall into LangGraph agent model calls.
@@ -53,6 +69,7 @@ class OpenVikingContextMiddleware(AgentMiddleware):
self,
*,
client: Any = None,
+ async_client: Any = None,
retriever: OpenVikingRetriever | None = None,
url: str | None = None,
api_key: str | None = None,
@@ -77,6 +94,7 @@ class OpenVikingContextMiddleware(AgentMiddleware):
super().__init__()
self.recorder = OpenVikingSessionRecorder(
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -86,8 +104,10 @@ class OpenVikingContextMiddleware(AgentMiddleware):
path=path,
commit_policy=None,
)
+ self._owns_retriever = retriever is None
self.retriever = retriever or OpenVikingRetriever(
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -102,6 +122,7 @@ class OpenVikingContextMiddleware(AgentMiddleware):
)
self.assembler = OpenVikingSessionContextAssembler(
client=client,
+ async_client=async_client,
retriever=self.retriever,
url=url,
api_key=api_key,
@@ -130,27 +151,90 @@ class OpenVikingContextMiddleware(AgentMiddleware):
self._captured_signatures: dict[tuple[str, str], tuple[str, ...]] = {}
self._pending_context_parts: dict[tuple[str, str], list[dict[str, Any]]] = {}
+ async def aclose(self) -> None:
+ """Release all clients internally owned by this middleware."""
+
+ first_error: BaseException | None = None
+ components: list[Any] = [self.recorder, self.assembler]
+ if self._owns_retriever:
+ components.append(self.retriever)
+ for component in components:
+ try:
+ await component.aclose()
+ except BaseException as exc:
+ if first_error is None:
+ first_error = exc
+ if first_error is not None:
+ raise first_error
+
def wrap_model_call(self, request: ModelRequest, handler: Callable[[ModelRequest], Any]) -> Any:
- query = get_latest_user_text(request.messages)
- if not query:
+ plan = self._model_context_plan(request)
+ if plan is None:
return handler(request)
- session_id = self._resolve_session_id(
- getattr(request, "state", {}) or {},
- getattr(request, "runtime", None),
- )
- peer_id = self._resolve_peer_id(
- getattr(request, "state", {}) or {},
- getattr(request, "runtime", None),
- )
- pending_key = _capture_key(session_id, peer_id)
- self._pending_context_parts.pop(pending_key, None)
+ session_id, pending_key, query = plan
assembled = self.assembler.assemble(
session_id=session_id,
query=query,
)
+ updated_request = self._request_with_context(request, pending_key, assembled)
+ if updated_request is None:
+ return handler(request)
+ try:
+ return handler(updated_request)
+ except Exception:
+ self._pending_context_parts.pop(pending_key, None)
+ raise
+
+ async def awrap_model_call(
+ self,
+ request: ModelRequest,
+ handler: Callable[[ModelRequest], Any],
+ ) -> Any:
+ """Asynchronously inject OpenViking context before a model call."""
+
+ plan = self._model_context_plan(request)
+ if plan is None:
+ return await handler(request)
+ session_id, pending_key, query = plan
+ assembled = await self.assembler.aassemble(
+ session_id=session_id,
+ query=query,
+ )
+ updated_request = self._request_with_context(request, pending_key, assembled)
+ if updated_request is None:
+ return await handler(request)
+ try:
+ return await handler(updated_request)
+ except BaseException:
+ # CancelledError is a BaseException, so cancellation must also discard
+ # context references prepared for the interrupted model call.
+ self._pending_context_parts.pop(pending_key, None)
+ raise
+
+ def _model_context_plan(
+ self,
+ request: ModelRequest,
+ ) -> tuple[str, tuple[str, str], str] | None:
+ query = get_latest_user_text(request.messages)
+ if not query:
+ return None
+ state = getattr(request, "state", {}) or {}
+ runtime = getattr(request, "runtime", None)
+ session_id = self._resolve_session_id(state, runtime)
+ peer_id = self._resolve_peer_id(state, runtime)
+ pending_key = _capture_key(session_id, peer_id)
+ self._pending_context_parts.pop(pending_key, None)
+ return session_id, pending_key, query
+
+ def _request_with_context(
+ self,
+ request: ModelRequest,
+ pending_key: tuple[str, str],
+ assembled: OpenVikingAssembledContext,
+ ) -> ModelRequest | None:
context_block = assembled.block
if not context_block:
- return handler(request)
+ return None
if assembled.context_parts:
self._pending_context_parts[pending_key] = assembled.context_parts
@@ -160,13 +244,65 @@ class OpenVikingContextMiddleware(AgentMiddleware):
else:
content = extract_message_text(system_message.content)
updated_system = SystemMessage(content=f"{content}\n\n{context_block}".strip())
+ return request.override(system_message=updated_system)
+
+ def after_agent(self, state: AgentState[Any], runtime: Any) -> dict[str, Any] | None:
+ plan = self._capture_plan(state, runtime)
+ if plan is None:
+ return None
+ self.recorder.commit_policy = self.commit_policy
+ if plan.unchanged:
+ self.recorder.record(plan.session_id, ())
+ self._pending_context_parts.pop(plan.key, None)
+ return None
try:
- return handler(request.override(system_message=updated_system))
- except Exception:
- self._pending_context_parts.pop(pending_key, None)
+ result = self.recorder.record(
+ plan.session_id,
+ plan.messages[plan.start :],
+ peer_id=plan.peer_id,
+ context_parts=plan.context_parts,
+ )
+ except OpenVikingPartialWriteError as exc:
+ self._handle_partial_capture(plan, exc)
raise
- def after_agent(self, state: dict[str, Any], runtime: Any) -> dict[str, Any] | None:
+ self._complete_capture(plan, context_attached=result.context_attached)
+ return None
+
+ async def aafter_agent(
+ self,
+ state: AgentState[Any],
+ runtime: Any,
+ ) -> dict[str, Any] | None:
+ """Asynchronously capture messages after an agent run."""
+
+ plan = self._capture_plan(state, runtime)
+ if plan is None:
+ return None
+ self.recorder.commit_policy = self.commit_policy
+ if plan.unchanged:
+ await self.recorder.arecord(plan.session_id, ())
+ self._pending_context_parts.pop(plan.key, None)
+ return None
+ try:
+ result = await self.recorder.arecord(
+ plan.session_id,
+ plan.messages[plan.start :],
+ peer_id=plan.peer_id,
+ context_parts=plan.context_parts,
+ )
+ except OpenVikingPartialWriteError as exc:
+ self._handle_partial_capture(plan, exc)
+ raise
+
+ self._complete_capture(plan, context_attached=result.context_attached)
+ return None
+
+ def _capture_plan(
+ self,
+ state: AgentState[Any],
+ runtime: Any,
+ ) -> _CapturePlan | None:
if not self.capture_on_after_agent:
return None
messages = list(state.get("messages") or [])
@@ -174,46 +310,51 @@ class OpenVikingContextMiddleware(AgentMiddleware):
return None
session_id = self._resolve_session_id(state, runtime)
peer_id = self._resolve_peer_id(state, runtime)
- capture_key = _capture_key(session_id, peer_id)
- previous_signatures = self._captured_signatures.get(capture_key, ())
- current_signatures = tuple(_message_signature(message) for message in messages)
-
- if current_signatures == previous_signatures:
- self.recorder.commit_policy = self.commit_policy
- self.recorder.record(session_id, ())
- self._pending_context_parts.pop(capture_key, None)
- return None
+ key = _capture_key(session_id, peer_id)
+ previous_signatures = self._captured_signatures.get(key, ())
+ signatures = tuple(_message_signature(message) for message in messages)
+ unchanged = signatures == previous_signatures
start = 0
if (
- previous_signatures
- and len(current_signatures) > len(previous_signatures)
- and current_signatures[: len(previous_signatures)] == previous_signatures
+ not unchanged
+ and previous_signatures
+ and len(signatures) > len(previous_signatures)
+ and signatures[: len(previous_signatures)] == previous_signatures
):
start = len(previous_signatures)
+ return _CapturePlan(
+ session_id=session_id,
+ peer_id=peer_id,
+ key=key,
+ messages=messages,
+ signatures=signatures,
+ start=start,
+ context_parts=list(self._pending_context_parts.get(key, [])),
+ unchanged=unchanged,
+ )
- pending_context_parts = list(self._pending_context_parts.get(capture_key, []))
- self.recorder.commit_policy = self.commit_policy
- try:
- result = self.recorder.record(
- session_id,
- messages[start:],
- peer_id=peer_id,
- context_parts=pending_context_parts,
- )
- except OpenVikingPartialWriteError as exc:
- if exc.input_messages_consumed:
- consumed_end = start + exc.input_messages_consumed
- self._captured_signatures[capture_key] = current_signatures[:consumed_end]
- if exc.context_attached:
- self._pending_context_parts.pop(capture_key, None)
- raise
-
- self._captured_signatures[capture_key] = current_signatures
- if result.context_attached:
- self._pending_context_parts.pop(capture_key, None)
- return None
+ def _handle_partial_capture(
+ self,
+ plan: _CapturePlan,
+ error: OpenVikingPartialWriteError,
+ ) -> None:
+ if error.input_messages_consumed:
+ consumed_end = plan.start + error.input_messages_consumed
+ self._captured_signatures[plan.key] = plan.signatures[:consumed_end]
+ if error.context_attached:
+ self._pending_context_parts.pop(plan.key, None)
+
+ def _complete_capture(
+ self,
+ plan: _CapturePlan,
+ *,
+ context_attached: bool,
+ ) -> None:
+ self._captured_signatures[plan.key] = plan.signatures
+ if context_attached:
+ self._pending_context_parts.pop(plan.key, None)
- def _resolve_session_id(self, state: dict[str, Any], runtime: Any) -> str:
+ def _resolve_session_id(self, state: Any, runtime: Any) -> str:
if self.session_id_resolver:
resolved = _normalize_session_id(self.session_id_resolver(state, runtime))
if resolved:
@@ -232,7 +373,7 @@ class OpenVikingContextMiddleware(AgentMiddleware):
return resolved
raise ValueError(_SESSION_ID_ERROR)
- def _resolve_peer_id(self, state: dict[str, Any], runtime: Any) -> str | None:
+ def _resolve_peer_id(self, state: Any, runtime: Any) -> str | None:
if self.peer_id_resolver:
return _normalize_peer_id(self.peer_id_resolver(state, runtime))
candidates = [
diff --git a/openviking/integrations/langchain/recording.py b/openviking/integrations/langchain/recording.py
index bb98090d7..f14ea511d 100644
--- a/openviking/integrations/langchain/recording.py
+++ b/openviking/integrations/langchain/recording.py
@@ -4,6 +4,7 @@
from __future__ import annotations
+import asyncio
from collections.abc import Iterable, Sequence
from copy import deepcopy
from dataclasses import dataclass
@@ -19,8 +20,12 @@ except ImportError as exc: # pragma: no cover - exercised by optional import pa
from openviking.integrations.langchain.client import (
OpenVikingCommitPolicy,
OpenVikingConnection,
+ aapply_commit_policy,
+ acall_openviking,
+ aclose_openviking_clients,
apply_commit_policy,
call_openviking,
+ ensure_async_client,
ensure_client,
item_value,
)
@@ -29,6 +34,7 @@ from openviking.integrations.langchain.messages import (
is_recordable_langchain_message,
langchain_message_to_openviking,
)
+from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
MAX_RECORDING_BATCH_SIZE = 100
@@ -116,6 +122,7 @@ class OpenVikingSessionRecorder:
self,
*,
client: Any = None,
+ async_client: Any = None,
url: str | None = None,
api_key: str | None = None,
account: str | None = None,
@@ -133,6 +140,7 @@ class OpenVikingSessionRecorder:
raise ValueError(f"batch_size must be between 1 and {MAX_RECORDING_BATCH_SIZE}")
self._connection = OpenVikingConnection(
client=client,
+ async_client=async_client,
url=url,
api_key=api_key,
account=account,
@@ -146,6 +154,7 @@ class OpenVikingSessionRecorder:
)
self._owns_client = client is None
self._client_cache: Any = None
+ self._async_clients = LoopScopedAsyncClientCache()
self._pending_commit_sessions: set[str] = set()
self._closed = False
self.commit_policy = commit_policy
@@ -226,6 +235,72 @@ class OpenVikingSessionRecorder:
) from exc
return result
+ async def arecord(
+ self,
+ session_id: str,
+ messages: Iterable[BaseMessage],
+ peer_id: str | None = None,
+ context_parts: Sequence[dict[str, Any]] = (),
+ ) -> OpenVikingRecordResult:
+ """Asynchronously persist messages and apply the configured commit policy."""
+
+ self._raise_if_closed()
+ await self._aretry_pending_commit(session_id)
+ input_messages = list(messages)
+ prepared_messages = _prepare_messages(
+ input_messages,
+ peer_id=peer_id,
+ context_parts=context_parts,
+ )
+ if not prepared_messages:
+ return OpenVikingRecordResult(input_messages_consumed=len(input_messages))
+
+ batches = _prepare_batches(prepared_messages, batch_size=self.batch_size)
+ client = await self.get_async_client()
+ messages_written = 0
+ input_messages_consumed = 0
+ context_attached = False
+ for batch in batches:
+ try:
+ await acall_openviking(
+ client,
+ "batch_add_messages",
+ session_id=session_id,
+ messages=batch.payloads,
+ )
+ except Exception as exc:
+ if messages_written == 0:
+ raise
+ result = OpenVikingRecordResult(
+ messages_written=messages_written,
+ input_messages_consumed=input_messages_consumed,
+ context_attached=context_attached,
+ )
+ raise OpenVikingPartialWriteError(
+ session_id=session_id,
+ result=result,
+ cause=exc,
+ ) from exc
+ messages_written += len(batch.payloads)
+ input_messages_consumed = batch.input_end
+ context_attached = context_attached or batch.context_attached
+ result = OpenVikingRecordResult(
+ messages_written=messages_written,
+ input_messages_consumed=len(input_messages),
+ context_attached=context_attached,
+ )
+ try:
+ await aapply_commit_policy(client, session_id, self.commit_policy)
+ except Exception as exc:
+ self._pending_commit_sessions.add(session_id)
+ raise OpenVikingPartialWriteError(
+ session_id=session_id,
+ result=result,
+ cause=exc,
+ stage="commit",
+ ) from exc
+ return result
+
def flush(self, session_id: str) -> dict[str, Any] | None:
"""Commit a session only when it contains pending, uncommitted content."""
@@ -233,6 +308,13 @@ class OpenVikingSessionRecorder:
self._pending_commit_sessions.discard(session_id)
return result
+ async def aflush(self, session_id: str) -> dict[str, Any] | None:
+ """Asynchronously commit pending, uncommitted session content."""
+
+ result = await self._aflush_pending_content(session_id)
+ self._pending_commit_sessions.discard(session_id)
+ return result
+
def _flush_pending_content(self, session_id: str) -> dict[str, Any] | None:
client = self.client
try:
@@ -251,20 +333,79 @@ class OpenVikingSessionRecorder:
return None
return call_openviking(client, "commit_session", session_id=session_id)
+ async def _aflush_pending_content(self, session_id: str) -> dict[str, Any] | None:
+ client = await self.get_async_client()
+ try:
+ session = await acall_openviking(
+ client,
+ "get_session",
+ session_id=session_id,
+ auto_create=False,
+ )
+ except Exception as exc:
+ error_code = str(getattr(exc, "code", "")).upper()
+ if isinstance(exc, FileNotFoundError) or error_code == "NOT_FOUND":
+ return None
+ raise
+ if int(item_value(session, "pending_tokens", 0) or 0) <= 0:
+ return None
+ return await acall_openviking(client, "commit_session", session_id=session_id)
+
def _retry_pending_commit(self, session_id: str) -> None:
if session_id not in self._pending_commit_sessions:
return
self._flush_pending_content(session_id)
self._pending_commit_sessions.discard(session_id)
+ async def _aretry_pending_commit(self, session_id: str) -> None:
+ if session_id not in self._pending_commit_sessions:
+ return
+ await self._aflush_pending_content(session_id)
+ self._pending_commit_sessions.discard(session_id)
+
+ async def get_async_client(self) -> Any:
+ """Return the async client interface used by this recorder.
+
+ Injected clients are returned unchanged and remain caller-owned.
+ HTTP-backed connections return an internally managed, loop-local handle
+ whose method calls support recovery. Direct attributes on that handle
+ are best-effort during recovery; use ``await handle.get()`` only to read
+ raw properties immediately because recovery may replace that snapshot.
+ Embedded ``path=`` connections return an adapter-owned synchronous
+ client whose calls are dispatched through a worker thread.
+ """
+
+ self._raise_if_closed()
+ client = await ensure_async_client(
+ self._connection,
+ client_cache=self._async_clients,
+ embedded_client_factory=lambda: self.client,
+ )
+ self._raise_if_closed()
+ return client
+
+ async def _get_async_client(self) -> Any:
+ return await self.get_async_client()
+
def close(self) -> None:
- """Release an internally created client.
+ """Release resources after exclusively synchronous use.
Injected clients remain owned by their caller and are never closed here.
+ After any async operation has initialized an owned client, callers must
+ use :meth:`aclose`; this method leaves the recorder open so that async
+ cleanup can still complete.
"""
if self._closed:
return
+ uses_http_client = bool(self._connection.url) or self._connection.path is None
+ if uses_http_client and self._async_clients.has_clients():
+ raise RuntimeError(
+ "OpenVikingSessionRecorder has an active async client; "
+ "use `await recorder.aclose()`"
+ )
+ if not uses_http_client:
+ self._async_clients.pop_all()
self._closed = True
self._pending_commit_sessions.clear()
client = self._client_cache
@@ -275,6 +416,22 @@ class OpenVikingSessionRecorder:
if callable(close):
close()
+ async def aclose(self) -> None:
+ """Release internally created sync and async clients."""
+
+ if self._closed:
+ return
+ self._closed = True
+ self._pending_commit_sessions.clear()
+ sync_client = self._client_cache
+ self._client_cache = None
+ async_clients = await asyncio.to_thread(self._async_clients.pop_all)
+
+ await aclose_openviking_clients(
+ sync_client if self._owns_client else None,
+ *async_clients,
+ )
+
def _raise_if_closed(self) -> None:
if self._closed:
raise RuntimeError("OpenVikingSessionRecorder is closed")
diff --git a/openviking/integrations/langchain/retrievers.py b/openviking/integrations/langchain/retrievers.py
index fcab9ab09..0615c0f0a 100644
--- a/openviking/integrations/langchain/retrievers.py
+++ b/openviking/integrations/langchain/retrievers.py
@@ -19,12 +19,16 @@ except ImportError as exc: # pragma: no cover - exercised by optional import pa
from openviking.integrations.langchain.client import (
OpenVikingConnection,
+ acall_openviking,
+ aclose_openviking_clients,
call_openviking,
+ ensure_async_client,
ensure_client,
item_value,
iter_result_items,
stringify,
)
+from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
class OpenVikingRetriever(BaseRetriever):
@@ -33,6 +37,7 @@ class OpenVikingRetriever(BaseRetriever):
model_config = ConfigDict(arbitrary_types_allowed=True)
client: Any = None
+ async_client: Any = None
url: str | None = None
api_key: str | None = None
account: str | None = None
@@ -57,9 +62,16 @@ class OpenVikingRetriever(BaseRetriever):
tags: list[str] | None = Field(default=None, exclude=True)
_client_cache: Any = PrivateAttr(default=None)
+ _async_clients: LoopScopedAsyncClientCache = PrivateAttr(
+ default_factory=LoopScopedAsyncClientCache
+ )
+ _owns_client_cache: bool = PrivateAttr(default=False)
+ _closed: bool = PrivateAttr(default=False)
def _get_client(self) -> Any:
+ self._raise_if_closed()
if self._client_cache is None:
+ self._owns_client_cache = self.client is None
self._client_cache = ensure_client(
OpenVikingConnection(
client=self.client,
@@ -77,6 +89,62 @@ class OpenVikingRetriever(BaseRetriever):
)
return self._client_cache
+ async def get_async_client(self) -> Any:
+ """Return the async client interface used by this retriever.
+
+ Injected clients are returned unchanged and remain caller-owned.
+ HTTP-backed connections return an internally managed, loop-local handle
+ whose method calls support recovery. Direct attributes on that handle
+ are best-effort during recovery; use ``await handle.get()`` only to read
+ raw properties immediately because recovery may replace that snapshot.
+ Embedded ``path=`` connections return an adapter-owned synchronous
+ client whose calls are dispatched through a worker thread.
+ """
+
+ self._raise_if_closed()
+ client = await ensure_async_client(
+ OpenVikingConnection(
+ client=self.client,
+ async_client=self.async_client,
+ url=self.url,
+ api_key=self.api_key,
+ account=self.account,
+ user=self.user,
+ user_id=self.user_id,
+ actor_peer_id=self.actor_peer_id,
+ path=self.path,
+ timeout=self.timeout,
+ extra_headers=self.extra_headers,
+ auto_initialize=self.auto_initialize,
+ ),
+ client_cache=self._async_clients,
+ embedded_client_factory=self._get_client,
+ )
+ self._raise_if_closed()
+ return client
+
+ async def _get_async_client(self) -> Any:
+ return await self.get_async_client()
+
+ async def aclose(self) -> None:
+ """Release clients created internally by this retriever."""
+
+ if self._closed:
+ return
+ self._closed = True
+ sync_client = self._client_cache
+ self._client_cache = None
+ async_clients = await asyncio.to_thread(self._async_clients.pop_all)
+
+ await aclose_openviking_clients(
+ sync_client if self._owns_client_cache else None,
+ *async_clients,
+ )
+
+ def _raise_if_closed(self) -> None:
+ if self._closed:
+ raise RuntimeError("OpenVikingRetriever is closed")
+
def _get_relevant_documents(self, query: str, *, run_manager: Any) -> list[Document]:
client = self._get_client()
method = "search" if self.search_mode == "search" else "find"
@@ -93,9 +161,40 @@ class OpenVikingRetriever(BaseRetriever):
)
documents: list[Document] = []
for context_type, item in iter_result_items(result, self.context_types):
- uri = item_value(item, "uri", "")
content = self._content_for_item(client, item)
- metadata = {
+ documents.append(self._document_from_item(context_type, item, content))
+ return documents
+
+ async def _aget_relevant_documents(self, query: str, *, run_manager: Any) -> list[Document]:
+ client = await self._get_async_client()
+ method = "search" if self.search_mode == "search" else "find"
+ result = await acall_openviking(
+ client,
+ method,
+ query=query,
+ target_uri=self.target_uri,
+ session_id=self.session_id,
+ limit=self.limit,
+ score_threshold=self.score_threshold,
+ filter=self.filter,
+ tags=self.tags,
+ )
+ documents: list[Document] = []
+ for context_type, item in iter_result_items(result, self.context_types):
+ content = await self._acontent_for_item(client, item)
+ documents.append(self._document_from_item(context_type, item, content))
+ return documents
+
+ def _document_from_item(
+ self,
+ context_type: str,
+ item: Any,
+ content: str,
+ ) -> Document:
+ uri = item_value(item, "uri", "")
+ return Document(
+ page_content=content,
+ metadata={
"source": uri,
f"{self.metadata_prefix}_uri": uri,
f"{self.metadata_prefix}_context_type": context_type,
@@ -105,13 +204,7 @@ class OpenVikingRetriever(BaseRetriever):
f"{self.metadata_prefix}_match_reason": item_value(item, "match_reason"),
f"{self.metadata_prefix}_abstract": item_value(item, "abstract"),
f"{self.metadata_prefix}_overview": item_value(item, "overview"),
- }
- documents.append(Document(page_content=content, metadata=metadata))
- return documents
-
- async def _aget_relevant_documents(self, query: str, *, run_manager: Any) -> list[Document]:
- return await asyncio.to_thread(
- lambda: self._get_relevant_documents(query, run_manager=run_manager)
+ },
)
def _content_for_item(self, client: Any, item: Any) -> str:
@@ -130,6 +223,22 @@ class OpenVikingRetriever(BaseRetriever):
return self._read_or_fallback(client, uri, overview or abstract)
return stringify(overview or abstract, max_chars=self.max_content_chars)
+ async def _acontent_for_item(self, client: Any, item: Any) -> str:
+ uri = item_value(item, "uri", "")
+ abstract = item_value(item, "abstract", "")
+ overview = item_value(item, "overview", "")
+ level = item_value(item, "level")
+
+ if self.content_mode == "abstract":
+ return stringify(abstract or overview, max_chars=self.max_content_chars)
+ if self.content_mode == "overview":
+ return stringify(overview or abstract, max_chars=self.max_content_chars)
+ if self.content_mode == "read":
+ return await self._aread_or_fallback(client, uri, overview or abstract)
+ if level == 2 and uri:
+ return await self._aread_or_fallback(client, uri, overview or abstract)
+ return stringify(overview or abstract, max_chars=self.max_content_chars)
+
def _read_or_fallback(self, client: Any, uri: str, fallback: Any) -> str:
if uri:
try:
@@ -138,3 +247,12 @@ class OpenVikingRetriever(BaseRetriever):
except Exception:
pass
return stringify(fallback, max_chars=self.max_content_chars)
+
+ async def _aread_or_fallback(self, client: Any, uri: str, fallback: Any) -> str:
+ if uri:
+ try:
+ content = await acall_openviking(client, "read", uri=uri)
+ return stringify(content, max_chars=self.max_content_chars)
+ except Exception:
+ pass
+ return stringify(fallback, max_chars=self.max_content_chars)
diff --git a/openviking/utils/async_client_cache.py b/openviking/utils/async_client_cache.py
index a2a0e651e..713d35159 100644
--- a/openviking/utils/async_client_cache.py
+++ b/openviking/utils/async_client_cache.py
@@ -43,6 +43,18 @@ class LoopScopedAsyncClientCache:
self._fallback_client: Any = None
self._lock = threading.Lock()
+ def __copy__(self) -> LoopScopedAsyncClientCache:
+ """Return an empty cache instead of sharing live async clients."""
+
+ return type(self)()
+
+ def __deepcopy__(self, memo: dict[int, Any]) -> LoopScopedAsyncClientCache:
+ """Return an empty cache instead of copying loop-bound clients."""
+
+ copied = type(self)()
+ memo[id(self)] = copied
+ return copied
+
def get(self, factory: Callable[[], Any]) -> Any:
"""Return a client for the current loop, creating it with factory if needed."""
try:
@@ -60,6 +72,12 @@ class LoopScopedAsyncClientCache:
self._clients_by_loop[loop] = client
return client
+ def has_clients(self) -> bool:
+ """Return whether the cache currently retains any clients."""
+
+ with self._lock:
+ return bool(self._clients_by_loop) or self._fallback_client is not None
+
def pop_all(self) -> list[Any]:
"""Remove and return all cached clients."""
with self._lock:
diff --git a/tests/integration/langchain_langgraph/test_async_recording.py b/tests/integration/langchain_langgraph/test_async_recording.py
new file mode 100644
index 000000000..865a6f1ce
--- /dev/null
+++ b/tests/integration/langchain_langgraph/test_async_recording.py
@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+pytest.importorskip("langchain")
+pytest.importorskip("langchain_core")
+pytest.importorskip("langgraph")
+
+from langchain.agents import create_agent
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+from langchain_core.runnables import RunnableLambda
+from langchain_core.runnables.history import RunnableWithMessageHistory
+
+from openviking.integrations.langchain import (
+ InMemoryOpenVikingClient,
+ OpenVikingChatMessageHistory,
+ OpenVikingContextMiddleware,
+ with_openviking_context,
+)
+
+
+class AsyncTrackingClient:
+ """Native async facade for deterministic real-framework integration tests."""
+
+ def __init__(self, records: dict[str, str] | None = None):
+ self.backing = InMemoryOpenVikingClient(records)
+ self.calls: list[str] = []
+ self.batch_sizes: list[int] = []
+ self._initialized = False
+
+ async def initialize(self) -> None:
+ self._initialized = True
+
+ async def close(self) -> None:
+ self._initialized = False
+
+ def __getattr__(self, name: str) -> Any:
+ method = getattr(self.backing, name)
+ if not callable(method):
+ return method
+
+ async def call(*args: Any, **kwargs: Any) -> Any:
+ self.calls.append(name)
+ if name == "batch_add_messages":
+ self.batch_sizes.append(len(kwargs["messages"]))
+ return method(*args, **kwargs)
+
+ return call
+
+
+async def test_real_runnable_with_message_history_ainvoke_uses_async_history():
+ client = AsyncTrackingClient()
+
+ async def answer(messages: list[BaseMessage]) -> AIMessage:
+ remembered_azure = any(
+ "azure" in str(message.content).lower()
+ for message in messages
+ if isinstance(message, HumanMessage)
+ )
+ return AIMessage(content="I remember azure." if remembered_azure else "No preference.")
+
+ app = RunnableWithMessageHistory(
+ RunnableLambda(answer),
+ lambda session_id: OpenVikingChatMessageHistory(
+ session_id=session_id,
+ async_client=client,
+ ),
+ )
+ config = {"configurable": {"session_id": "real-async-history"}}
+
+ await app.ainvoke(
+ [HumanMessage(content="Remember that the deployment color is azure.")],
+ config=config,
+ )
+ response = await app.ainvoke(
+ [HumanMessage(content="Which deployment color do you remember?")],
+ config=config,
+ )
+
+ assert response.content == "I remember azure."
+ assert client.batch_sizes == [2, 2]
+ assert len(client.backing.sessions["real-async-history"]) == 4
+ assert client.calls.count("get_session_context") == 4
+
+
+async def test_real_openviking_context_wrapper_ainvoke_uses_async_lifecycle():
+ client = AsyncTrackingClient(
+ {"viking://resources/runbooks/async.md": "Async deployment color is teal."}
+ )
+
+ async def answer(messages: list[BaseMessage]) -> AIMessage:
+ assert "Async deployment color is teal." in str(messages[0].content)
+ return AIMessage(content="OpenViking says teal.")
+
+ app = with_openviking_context(
+ RunnableLambda(answer),
+ async_client=client,
+ session_id="real-async-wrapper",
+ target_uri="viking://resources",
+ )
+
+ result = await app.ainvoke([HumanMessage(content="What is the async deployment color?")])
+
+ assert result.content == "OpenViking says teal."
+ assert client.batch_sizes == [2]
+ assert {"create_session", "get_session_context", "search", "read"}.issubset(client.calls)
+ assistant_parts = client.backing.sessions["real-async-wrapper"][1]["parts"]
+ assert any(part["type"] == "context" for part in assistant_parts)
+
+
+async def test_real_async_context_wrapper_clears_pending_context_after_failure():
+ client = AsyncTrackingClient(
+ {"viking://resources/runbooks/failure.md": "Async failure context is amber."}
+ )
+ calls = 0
+
+ async def answer(_messages: list[BaseMessage]) -> AIMessage:
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ raise RuntimeError("synthetic async model failure")
+ return AIMessage(content="Recovered asynchronously.")
+
+ app = with_openviking_context(
+ RunnableLambda(answer),
+ async_client=client,
+ session_id="real-async-failure",
+ target_uri="viking://resources",
+ )
+
+ with pytest.raises(RuntimeError, match="synthetic async model failure"):
+ await app.ainvoke([HumanMessage(content="What amber failure context?")])
+
+ client.backing.records.clear()
+ result = await app.ainvoke([HumanMessage(content="No matching context on this retry.")])
+
+ assert result.content == "Recovered asynchronously."
+ assistant_parts = client.backing.sessions["real-async-failure"][-1]["parts"]
+ assert not any(part["type"] == "context" for part in assistant_parts)
+
+
+async def test_real_create_agent_ainvoke_uses_async_middleware_hooks():
+ client = AsyncTrackingClient()
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ session_id_resolver=lambda _state, _runtime: "real-async-agent",
+ )
+ agent = create_agent(
+ model=FakeListChatModel(responses=["Stored by async middleware."]),
+ tools=[],
+ middleware=[middleware],
+ )
+
+ result = await agent.ainvoke(
+ {"messages": [HumanMessage(content="Remember this async agent turn.")]},
+ config={"configurable": {"thread_id": "real-async-agent"}},
+ )
+
+ assert result["messages"][-1].content == "Stored by async middleware."
+ assert client.batch_sizes == [2]
+ assert [
+ message["parts"][0]["text"] for message in client.backing.sessions["real-async-agent"]
+ ] == [
+ "Remember this async agent turn.",
+ "Stored by async middleware.",
+ ]
diff --git a/tests/unit/test_async_client_cache.py b/tests/unit/test_async_client_cache.py
index 5a9311e36..605b41cd5 100644
--- a/tests/unit/test_async_client_cache.py
+++ b/tests/unit/test_async_client_cache.py
@@ -3,6 +3,7 @@
"""Tests for event-loop scoped async client caching."""
import asyncio
+import copy
import threading
from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
@@ -44,3 +45,17 @@ def test_loop_scoped_async_client_cache_reuses_within_loop_and_isolates_between_
assert worker_results[0][0] is worker_results[0][1]
assert main_first is not worker_results[0][0]
assert len(created) == 2
+
+
+def test_loop_scoped_async_client_cache_copies_without_live_clients():
+ cache = LoopScopedAsyncClientCache()
+ client = object()
+
+ assert cache.get(lambda: client) is client
+
+ shallow = copy.copy(cache)
+ deep = copy.deepcopy(cache)
+
+ assert cache.has_clients()
+ assert not shallow.has_clients()
+ assert not deep.has_clients()
diff --git a/tests/unit/test_langchain_async_integration.py b/tests/unit/test_langchain_async_integration.py
new file mode 100644
index 000000000..03df23d23
--- /dev/null
+++ b/tests/unit/test_langchain_async_integration.py
@@ -0,0 +1,1129 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import threading
+from typing import Any
+
+import pytest
+
+pytest.importorskip("langchain_core")
+pytest.importorskip("langgraph")
+
+from langchain_core.messages import AIMessage, HumanMessage
+
+from openviking.integrations.langchain import (
+ InMemoryOpenVikingClient,
+ OpenVikingChatMessageHistory,
+ OpenVikingCommitPolicy,
+ OpenVikingContextMiddleware,
+ OpenVikingPartialWriteError,
+ OpenVikingRetriever,
+ OpenVikingSessionContextAssembler,
+ OpenVikingSessionRecorder,
+)
+from openviking.integrations.langchain.client import (
+ OpenVikingAsyncClientHandle,
+ OpenVikingConnection,
+ acall_openviking,
+ ensure_async_client,
+)
+
+
+class AsyncInMemoryOpenVikingClient:
+ """Async facade that records whether adapters use native coroutine methods."""
+
+ def __init__(self, backing: InMemoryOpenVikingClient | None = None):
+ self.backing = backing or InMemoryOpenVikingClient()
+ self.calls: list[str] = []
+ self.call_thread_ids: list[int] = []
+ self._initialized = False
+ self.closed = False
+
+ async def initialize(self) -> None:
+ self._initialized = True
+
+ async def close(self) -> None:
+ self.closed = True
+ self._initialized = False
+
+ def __getattr__(self, name: str) -> Any:
+ method = getattr(self.backing, name)
+ if not callable(method):
+ return method
+
+ async def call(*args: Any, **kwargs: Any) -> Any:
+ self.calls.append(name)
+ self.call_thread_ids.append(threading.get_ident())
+ return method(*args, **kwargs)
+
+ return call
+
+
+async def test_ensure_async_client_defaults_to_native_http_client(monkeypatch):
+ created: dict[str, Any] = {}
+
+ class FakeAsyncHTTPClient:
+ def __init__(self, **kwargs: Any):
+ created.update(kwargs)
+ self.initialized = False
+
+ async def initialize(self) -> None:
+ self.initialized = True
+
+ async def find(self, query: str) -> dict[str, str]:
+ return {"query": query}
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FakeAsyncHTTPClient)
+
+ client = await ensure_async_client(
+ OpenVikingConnection(api_key="test-key", user_id="test-user")
+ )
+
+ assert await acall_openviking(
+ client,
+ "find",
+ query="async",
+ unsupported="ignored",
+ ) == {"query": "async"}
+ assert created["api_key"] == "test-key"
+ assert created["user_id"] == "test-user"
+ assert created["url"] is None
+ assert (await client.get()).initialized is True
+
+
+async def test_injected_async_client_is_initialized_only_once_across_adapters():
+ class AsyncClientWithoutInitializedFlag:
+ def __init__(self):
+ self.initialize_calls = 0
+
+ async def initialize(self) -> None:
+ await asyncio.sleep(0.01)
+ self.initialize_calls += 1
+
+ client = AsyncClientWithoutInitializedFlag()
+ connection = OpenVikingConnection(async_client=client)
+
+ clients = await asyncio.gather(*(ensure_async_client(connection) for _ in range(5)))
+
+ assert all(resolved is client for resolved in clients)
+ assert client.initialize_calls == 1
+
+
+async def test_shared_injected_async_client_initializes_once_across_real_adapters():
+ class SharedAsyncClient:
+ def __init__(self):
+ self.initialize_calls = 0
+ self.closed = False
+
+ async def initialize(self) -> None:
+ await asyncio.sleep(0.01)
+ self.initialize_calls += 1
+
+ async def close(self) -> None:
+ self.closed = True
+
+ client = SharedAsyncClient()
+ recorder = OpenVikingSessionRecorder(async_client=client)
+ retriever = OpenVikingRetriever(async_client=client)
+
+ resolved = await asyncio.gather(
+ recorder.get_async_client(),
+ retriever.get_async_client(),
+ )
+
+ assert resolved == [client, client]
+ assert client.initialize_calls == 1
+
+ await recorder.aclose()
+ await retriever.aclose()
+ assert client.closed is False
+
+
+async def test_injected_async_client_respects_disabled_auto_initialize():
+ class AsyncClient:
+ def __init__(self):
+ self.initialize_calls = 0
+
+ async def initialize(self) -> None:
+ self.initialize_calls += 1
+
+ client = AsyncClient()
+
+ assert (
+ await ensure_async_client(
+ OpenVikingConnection(
+ async_client=client,
+ auto_initialize=False,
+ )
+ )
+ is client
+ )
+ assert client.initialize_calls == 0
+
+
+async def test_async_client_handle_initializes_once_under_concurrency(monkeypatch):
+ instances: list[Any] = []
+
+ class SlowAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ await asyncio.sleep(0.01)
+
+ async def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", SlowAsyncHTTPClient)
+ handle = OpenVikingAsyncClientHandle(OpenVikingConnection(url="http://localhost:1933"))
+
+ clients = await asyncio.gather(*(handle.get() for _ in range(5)))
+
+ assert len(instances) == 1
+ assert all(client is clients[0] for client in clients)
+ await handle.close()
+ assert instances[0].closed is True
+
+
+async def test_async_client_initialization_failure_closes_candidate(monkeypatch):
+ instances: list[Any] = []
+
+ class FailingAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ raise RuntimeError("initialization failed")
+
+ async def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FailingAsyncHTTPClient)
+
+ with pytest.raises(RuntimeError, match="initialization failed"):
+ await ensure_async_client(OpenVikingConnection(url="http://localhost:1933"))
+
+ assert len(instances) == 1
+ assert instances[0].closed is True
+
+
+async def test_async_adapter_client_caches_initialize_once_under_concurrency(monkeypatch):
+ instances: list[Any] = []
+
+ class SlowAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ await asyncio.sleep(0.01)
+
+ async def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", SlowAsyncHTTPClient)
+ recorder = OpenVikingSessionRecorder(url="http://localhost:1933")
+ assembler = OpenVikingSessionContextAssembler(
+ url="http://localhost:1933",
+ include_recall=False,
+ )
+ retriever = OpenVikingRetriever(url="http://localhost:1933")
+
+ recorder_clients = await asyncio.gather(*(recorder.get_async_client() for _ in range(5)))
+ assembler_clients = await asyncio.gather(*(assembler.get_async_client() for _ in range(5)))
+ retriever_clients = await asyncio.gather(*(retriever.get_async_client() for _ in range(5)))
+
+ assert len(instances) == 3
+ assert all(client is recorder_clients[0] for client in recorder_clients)
+ assert all(client is assembler_clients[0] for client in assembler_clients)
+ assert all(client is retriever_clients[0] for client in retriever_clients)
+
+ await assembler.retriever.get_async_client()
+ assert len(instances) == 4
+
+ await recorder.aclose()
+ await assembler.aclose()
+ await retriever.aclose()
+ assert all(client.closed for client in instances)
+
+
+def test_async_adapter_clients_are_scoped_per_event_loop(monkeypatch):
+ instances: list[Any] = []
+
+ class LoopBoundAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.loop: asyncio.AbstractEventLoop | None = None
+ self.closed = False
+ self.writes = 0
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ await asyncio.sleep(0.01)
+ self.loop = asyncio.get_running_loop()
+
+ async def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ if asyncio.get_running_loop() is not self.loop:
+ raise RuntimeError("client used from a different event loop")
+ self.writes += 1
+ return {}
+
+ async def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", LoopBoundAsyncHTTPClient)
+ recorder = OpenVikingSessionRecorder(url="http://localhost:1933")
+
+ async def use_recorder(session_id: str) -> tuple[Any, Any]:
+ handles = await asyncio.gather(*(recorder.get_async_client() for _ in range(8)))
+ assert all(handle is handles[0] for handle in handles)
+ client = await handles[0].get()
+ await recorder.arecord(session_id, [HumanMessage(content=session_id)])
+ return handles[0], client
+
+ loop_a = asyncio.new_event_loop()
+ loop_b = asyncio.new_event_loop()
+ try:
+ handle_a, client_a = loop_a.run_until_complete(use_recorder("loop-a"))
+ handle_b, client_b = loop_b.run_until_complete(use_recorder("loop-b"))
+
+ assert handle_a is not handle_b
+ assert client_a is not client_b
+ assert len(instances) == 2
+ assert [client.writes for client in instances] == [1, 1]
+
+ loop_b.run_until_complete(recorder.aclose())
+ assert all(client.closed for client in instances)
+ finally:
+ loop_a.close()
+ loop_b.close()
+
+
+def test_async_adapter_aclose_after_originating_loop_ends_is_best_effort(monkeypatch):
+ class LoopBoundAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ pass
+
+ async def initialize(self) -> None:
+ await asyncio.sleep(0.01)
+
+ async def close(self) -> None:
+ raise RuntimeError("event loop is closed")
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", LoopBoundAsyncHTTPClient)
+ recorder = OpenVikingSessionRecorder(url="http://localhost:1933")
+
+ async def initialize_with_contention() -> None:
+ await asyncio.gather(*(recorder.get_async_client() for _ in range(4)))
+
+ asyncio.run(initialize_with_contention())
+ asyncio.run(recorder.aclose())
+ assert recorder._closed is True
+
+
+def test_async_adapter_aclose_routes_to_live_originating_loop(monkeypatch):
+ instances: list[Any] = []
+
+ class LoopBoundAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.initialized_loop: asyncio.AbstractEventLoop | None = None
+ self.closed_loop: asyncio.AbstractEventLoop | None = None
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ self.initialized_loop = asyncio.get_running_loop()
+
+ async def close(self) -> None:
+ self.closed_loop = asyncio.get_running_loop()
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", LoopBoundAsyncHTTPClient)
+ recorder = OpenVikingSessionRecorder(url="http://localhost:1933")
+ worker_loop = asyncio.new_event_loop()
+ ready = threading.Event()
+ worker_errors: list[BaseException] = []
+
+ async def initialize() -> None:
+ await recorder.get_async_client()
+
+ def run_worker_loop() -> None:
+ asyncio.set_event_loop(worker_loop)
+ try:
+ try:
+ worker_loop.run_until_complete(initialize())
+ except BaseException as exc:
+ worker_errors.append(exc)
+ return
+ ready.set()
+ worker_loop.run_forever()
+ finally:
+ ready.set()
+ asyncio.set_event_loop(None)
+
+ thread = threading.Thread(target=run_worker_loop)
+ thread.start()
+ assert ready.wait(timeout=2)
+ try:
+ assert not worker_errors
+ asyncio.run(recorder.aclose())
+ finally:
+ worker_loop.call_soon_threadsafe(worker_loop.stop)
+ thread.join(timeout=2)
+ worker_loop.close()
+
+ assert not thread.is_alive()
+ assert len(instances) == 1
+ assert instances[0].initialized_loop is worker_loop
+ assert instances[0].closed_loop is worker_loop
+
+
+async def test_async_handle_copy_and_missing_attribute_behavior(monkeypatch):
+ class FakeAsyncHTTPClient:
+ marker = "async-client"
+
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+
+ async def initialize(self) -> None:
+ return None
+
+ async def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FakeAsyncHTTPClient)
+ retriever = OpenVikingRetriever(url="http://localhost:1933")
+ handle = await retriever.get_async_client()
+
+ copied = copy.deepcopy(retriever)
+ assert not copied._async_clients.has_clients()
+ copied_handle = await copied.get_async_client()
+
+ assert isinstance(copied_handle, OpenVikingAsyncClientHandle)
+ assert copied_handle is not handle
+ assert (await copied_handle.get()).marker == "async-client"
+ assert handle.marker == "async-client"
+ assert not hasattr(handle, "definitely_not_an_openviking_client_attribute")
+ await copied.aclose()
+ await retriever.aclose()
+
+
+async def test_async_handle_method_lookup_survives_recovery_reset(monkeypatch):
+ instances: list[Any] = []
+ reset_started = asyncio.Event()
+ release_close = asyncio.Event()
+
+ class RecoveringAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.index = len(instances)
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ return None
+
+ async def find(self, **kwargs: Any) -> dict[str, Any]:
+ if self.index == 0:
+ raise ConnectionError("replace this client")
+ return {"query": kwargs["query"], "client": self.index}
+
+ async def close(self) -> None:
+ if self.index == 0:
+ reset_started.set()
+ await release_close.wait()
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", RecoveringAsyncHTTPClient)
+ handle = OpenVikingAsyncClientHandle(OpenVikingConnection(url="http://localhost:1933"))
+ await handle.initialize()
+
+ recovering_call = asyncio.create_task(handle.find(query="first"))
+ await asyncio.wait_for(reset_started.wait(), timeout=1)
+
+ sibling_method = handle.find
+ sibling_call = asyncio.create_task(sibling_method(query="second"))
+ release_close.set()
+
+ first_result, second_result = await asyncio.gather(recovering_call, sibling_call)
+
+ assert {first_result["query"], second_result["query"]} == {"first", "second"}
+ assert first_result["client"] == second_result["client"] == 1
+ assert len(instances) == 2
+ await handle.close()
+
+
+async def test_async_handle_stale_failure_does_not_reset_replacement(monkeypatch):
+ instances: list[Any] = []
+ stale_call_started = asyncio.Event()
+ release_stale_failure = asyncio.Event()
+ reset_started = asyncio.Event()
+ release_old_close = asyncio.Event()
+
+ class RecoveringAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.index = len(instances)
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ return None
+
+ async def find(self, *, query: str) -> dict[str, Any]:
+ if self.index != 0:
+ return {"query": query, "client": self.index}
+ if query == "stale":
+ stale_call_started.set()
+ await release_stale_failure.wait()
+ raise ConnectionError(f"{query} failed on the old client")
+
+ async def close(self) -> None:
+ self.closed = True
+ if self.index == 0:
+ reset_started.set()
+ await release_old_close.wait()
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", RecoveringAsyncHTTPClient)
+ handle = OpenVikingAsyncClientHandle(OpenVikingConnection(url="http://localhost:1933"))
+ await handle.initialize()
+
+ stale_call = asyncio.create_task(handle.find(query="stale"))
+ await asyncio.wait_for(stale_call_started.wait(), timeout=1)
+
+ recovering_call = asyncio.create_task(handle.find(query="first"))
+ await asyncio.wait_for(reset_started.wait(), timeout=1)
+
+ fresh_result = await handle.find(query="fresh")
+ release_stale_failure.set()
+ stale_result = await stale_call
+ release_old_close.set()
+ recovering_result = await recovering_call
+
+ assert fresh_result["client"] == stale_result["client"] == recovering_result["client"] == 1
+ assert len(instances) == 2
+ assert instances[0].closed is True
+ assert instances[1].closed is False
+ await handle.close()
+
+
+async def test_async_handle_missing_method_fails_when_called(monkeypatch):
+ class FakeAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ pass
+
+ async def initialize(self) -> None:
+ return None
+
+ async def close(self) -> None:
+ return None
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FakeAsyncHTTPClient)
+ handle = OpenVikingAsyncClientHandle(OpenVikingConnection(url="http://localhost:1933"))
+
+ missing_method = handle.definitely_not_an_openviking_client_attribute
+ with pytest.raises(AttributeError, match="definitely_not_an_openviking_client_attribute"):
+ await missing_method()
+
+ await handle.close()
+
+
+async def test_sync_close_after_async_use_remains_recoverable(monkeypatch):
+ class FakeAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+
+ async def initialize(self) -> None:
+ return None
+
+ async def close(self) -> None:
+ self.closed = True
+
+ class FakeSyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ self._initialized = False
+
+ def initialize(self) -> None:
+ self._initialized = True
+
+ def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FakeAsyncHTTPClient)
+ monkeypatch.setattr(client_module, "SyncHTTPClient", FakeSyncHTTPClient)
+ recorder = OpenVikingSessionRecorder(url="http://localhost:1933")
+ sync_handle = recorder.client
+ async_handle = await recorder.get_async_client()
+ sync_client = sync_handle.get()
+ async_client = await async_handle.get()
+
+ with pytest.raises(RuntimeError, match=r"await recorder\.aclose"):
+ recorder.close()
+
+ assert recorder._closed is False
+ assert sync_client.closed is False
+ assert async_client.closed is False
+
+ await recorder.aclose()
+
+ assert recorder._closed is True
+ assert sync_client.closed is True
+ assert async_client.closed is True
+
+
+async def test_async_middleware_closes_all_internally_owned_clients(monkeypatch):
+ instances: list[Any] = []
+
+ class FakeAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ return None
+
+ async def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FakeAsyncHTTPClient)
+ middleware = OpenVikingContextMiddleware(url="http://localhost:1933")
+
+ await middleware.recorder.get_async_client()
+ await middleware.assembler.get_async_client()
+ await middleware.retriever.get_async_client()
+ assert len(instances) == 3
+
+ await middleware.aclose()
+
+ assert all(client.closed for client in instances)
+
+
+async def test_async_middleware_does_not_close_injected_client():
+ client = AsyncInMemoryOpenVikingClient()
+ middleware = OpenVikingContextMiddleware(async_client=client)
+
+ await middleware.recorder.get_async_client()
+ await middleware.assembler.get_async_client()
+ await middleware.retriever.get_async_client()
+ await middleware.aclose()
+
+ assert client.closed is False
+
+
+async def test_async_middleware_does_not_close_injected_retriever():
+ client = AsyncInMemoryOpenVikingClient()
+ retriever = OpenVikingRetriever(async_client=client)
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ retriever=retriever,
+ )
+
+ await middleware.aclose()
+
+ assert retriever._closed is False
+ assert await retriever.ainvoke("still usable") == []
+ assert client.closed is False
+ await retriever.aclose()
+
+
+async def test_async_client_retries_safe_read_with_fresh_client(monkeypatch):
+ instances: list[Any] = []
+
+ class FlakyAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.index = len(instances)
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ return None
+
+ async def close(self) -> None:
+ self.closed = True
+
+ async def find(self, **_kwargs: Any) -> dict[str, Any]:
+ if self.index == 0:
+ raise ConnectionError("OpenViking server was not ready")
+ return {"memories": [], "resources": [], "skills": []}
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FlakyAsyncHTTPClient)
+
+ client = await ensure_async_client(OpenVikingConnection(url="http://localhost:1933"))
+ result = await acall_openviking(client, "find", query="recover")
+
+ assert result == {"memories": [], "resources": [], "skills": []}
+ assert len(instances) == 2
+ assert instances[0].closed is True
+
+
+async def test_async_client_evicts_without_replaying_mutating_call(monkeypatch):
+ instances: list[Any] = []
+
+ class FlakyAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ return None
+
+ async def close(self) -> None:
+ self.closed = True
+
+ async def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ raise ConnectionError("OpenViking connection dropped during write")
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FlakyAsyncHTTPClient)
+
+ client = await ensure_async_client(OpenVikingConnection(url="http://localhost:1933"))
+ with pytest.raises(ConnectionError):
+ await acall_openviking(
+ client,
+ "batch_add_messages",
+ session_id="async-mutation",
+ messages=[{"role": "user", "content": "hello"}],
+ )
+
+ assert len(instances) == 1
+ assert instances[0].closed is True
+
+
+async def test_sync_client_async_fallback_runs_outside_event_loop_thread():
+ main_thread_id = threading.get_ident()
+ call_thread_ids: list[int] = []
+
+ class SyncClient:
+ def find(self, query: str) -> dict[str, Any]:
+ call_thread_ids.append(threading.get_ident())
+ return {"memories": [], "resources": [], "skills": [], "query": query}
+
+ result = await acall_openviking(SyncClient(), "find", query="fallback")
+
+ assert result["query"] == "fallback"
+ assert call_thread_ids
+ assert call_thread_ids[0] != main_thread_id
+
+
+async def test_embedded_path_async_uses_owned_sync_client_in_worker(monkeypatch, tmp_path):
+ main_thread_id = threading.get_ident()
+ instances: list[Any] = []
+
+ class FakeSyncOpenViking:
+ def __init__(self, *, path: str, actor_peer_id: str | None = None):
+ self.path = path
+ self.actor_peer_id = actor_peer_id
+ self._initialized = False
+ self.initialize_thread_id: int | None = None
+ self.find_thread_id: int | None = None
+ self.closed = False
+ instances.append(self)
+
+ def initialize(self) -> None:
+ self.initialize_thread_id = threading.get_ident()
+ self._initialized = True
+
+ def find(self, **_kwargs: Any) -> dict[str, Any]:
+ self.find_thread_id = threading.get_ident()
+ return {
+ "memories": [
+ {
+ "uri": "viking://user/memories/example",
+ "abstract": "Embedded result.",
+ "level": 1,
+ }
+ ],
+ "resources": [],
+ "skills": [],
+ }
+
+ def close(self) -> None:
+ self.closed = True
+
+ import openviking.sync_client as sync_client_module
+
+ monkeypatch.setattr(sync_client_module, "SyncOpenViking", FakeSyncOpenViking)
+ retriever = OpenVikingRetriever(path=str(tmp_path), actor_peer_id="assistant-a")
+
+ documents = await retriever.ainvoke("embedded")
+ client = await retriever.get_async_client()
+
+ assert [document.page_content for document in documents] == ["Embedded result."]
+ assert len(instances) == 1
+ assert client is instances[0]
+ assert client is retriever._get_client()
+ assert client.actor_peer_id == "assistant-a"
+ assert client.initialize_thread_id != main_thread_id
+ assert client.find_thread_id != main_thread_id
+
+ await retriever.aclose()
+ assert client.closed is True
+
+ recorder = OpenVikingSessionRecorder(path=str(tmp_path / "recorder"))
+ recorder_client = await recorder.get_async_client()
+
+ assert recorder_client is recorder.client
+ recorder.close()
+ assert recorder._closed is True
+ assert recorder_client.closed is True
+
+
+async def test_async_retriever_uses_native_client_for_search_and_read():
+ backing = InMemoryOpenVikingClient(
+ {"viking://resources/runbooks/async.md": "Native async retrieval."}
+ )
+ client = AsyncInMemoryOpenVikingClient(backing)
+ main_thread_id = threading.get_ident()
+ retriever = OpenVikingRetriever(
+ async_client=client,
+ target_uri="viking://resources",
+ )
+
+ documents = await retriever.ainvoke("async retrieval")
+
+ assert [document.page_content for document in documents] == ["Native async retrieval."]
+ assert client.calls == ["find", "read"]
+ assert set(client.call_thread_ids) == {main_thread_id}
+
+
+async def test_async_recorder_preserves_batch_and_commit_semantics():
+ class BatchTrackingClient(InMemoryOpenVikingClient):
+ def __init__(self):
+ super().__init__()
+ self.batch_sizes: list[int] = []
+
+ def batch_add_messages(
+ self,
+ session_id: str,
+ messages: list[dict[str, Any]],
+ **kwargs: Any,
+ ) -> dict[str, Any]:
+ self.batch_sizes.append(len(messages))
+ return super().batch_add_messages(session_id, messages, **kwargs)
+
+ backing = BatchTrackingClient()
+ client = AsyncInMemoryOpenVikingClient(backing)
+ recorder = OpenVikingSessionRecorder(
+ async_client=client,
+ commit_policy=OpenVikingCommitPolicy(mode="always"),
+ )
+
+ result = await recorder.arecord(
+ "async-recorder",
+ [HumanMessage(content=f"Message {index}") for index in range(205)],
+ )
+
+ assert result.messages_written == 205
+ assert result.input_messages_consumed == 205
+ assert backing.batch_sizes == [100, 100, 5]
+ assert backing.sessions["async-recorder"] == []
+ assert len(backing.archives["async-recorder"][0]["messages"]) == 205
+
+
+async def test_async_recorder_retries_only_pending_commit_without_duplicate_writes():
+ class FailFirstCommitClient(InMemoryOpenVikingClient):
+ def __init__(self):
+ super().__init__()
+ self.batch_calls = 0
+ self.commit_calls = 0
+
+ def batch_add_messages(
+ self,
+ session_id: str,
+ messages: list[dict[str, Any]],
+ **kwargs: Any,
+ ) -> dict[str, Any]:
+ self.batch_calls += 1
+ return super().batch_add_messages(session_id, messages, **kwargs)
+
+ def commit_session(self, session_id: str, **kwargs: Any) -> dict[str, Any]:
+ self.commit_calls += 1
+ if self.commit_calls == 1:
+ raise RuntimeError("commit failed")
+ return super().commit_session(session_id, **kwargs)
+
+ backing = FailFirstCommitClient()
+ recorder = OpenVikingSessionRecorder(
+ async_client=AsyncInMemoryOpenVikingClient(backing),
+ commit_policy=OpenVikingCommitPolicy(mode="always"),
+ )
+
+ with pytest.raises(OpenVikingPartialWriteError) as captured:
+ await recorder.arecord(
+ "async-commit-retry",
+ [HumanMessage(content="Persist once.")],
+ )
+ result = await recorder.arecord("async-commit-retry", ())
+
+ assert captured.value.commit_pending is True
+ assert result.messages_written == 0
+ assert backing.batch_calls == 1
+ assert backing.commit_calls == 2
+ assert len(backing.archives["async-commit-retry"][0]["messages"]) == 1
+
+
+async def test_async_recorder_reports_confirmed_prefix_for_partial_batch_retry():
+ class FailSecondBatchClient(InMemoryOpenVikingClient):
+ def __init__(self):
+ super().__init__()
+ self.batch_sizes: list[int] = []
+
+ def batch_add_messages(
+ self,
+ session_id: str,
+ messages: list[dict[str, Any]],
+ **kwargs: Any,
+ ) -> dict[str, Any]:
+ self.batch_sizes.append(len(messages))
+ if len(self.batch_sizes) == 2:
+ raise RuntimeError("second batch failed")
+ return super().batch_add_messages(session_id, messages, **kwargs)
+
+ backing = FailSecondBatchClient()
+ recorder = OpenVikingSessionRecorder(async_client=AsyncInMemoryOpenVikingClient(backing))
+ messages = [HumanMessage(content=f"Message {index}") for index in range(101)]
+
+ with pytest.raises(OpenVikingPartialWriteError) as captured:
+ await recorder.arecord("async-partial-retry", messages)
+ await recorder.arecord(
+ "async-partial-retry",
+ messages[captured.value.input_messages_consumed :],
+ )
+
+ assert captured.value.messages_written == 100
+ assert captured.value.input_messages_consumed == 100
+ assert backing.batch_sizes == [100, 1, 1]
+ assert len(backing.sessions["async-partial-retry"]) == 101
+
+
+async def test_async_recorder_closes_only_internally_created_client(monkeypatch):
+ instances: list[Any] = []
+
+ class FakeAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ return None
+
+ async def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"added": 1}
+
+ async def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", FakeAsyncHTTPClient)
+ owned_recorder = OpenVikingSessionRecorder(url="http://localhost:1933")
+
+ await owned_recorder.arecord(
+ "async-owned-client",
+ [HumanMessage(content="Close owned client.")],
+ )
+ await owned_recorder.aclose()
+ await owned_recorder.aclose()
+
+ assert instances[0].closed is True
+ with pytest.raises(RuntimeError, match="closed"):
+ await owned_recorder.arecord(
+ "async-owned-client",
+ [HumanMessage(content="Rejected.")],
+ )
+
+ injected_client = AsyncInMemoryOpenVikingClient()
+ injected_recorder = OpenVikingSessionRecorder(async_client=injected_client)
+ await injected_recorder.arecord(
+ "async-injected-client",
+ [HumanMessage(content="Keep injected client open.")],
+ )
+ await injected_recorder.aclose()
+
+ assert injected_client.closed is False
+
+
+async def test_async_chat_history_reads_writes_and_clears_natively():
+ backing = InMemoryOpenVikingClient()
+ client = AsyncInMemoryOpenVikingClient(backing)
+ history = OpenVikingChatMessageHistory(
+ session_id="async-history",
+ async_client=client,
+ )
+
+ await history.aadd_messages(
+ [
+ HumanMessage(content="Remember async history."),
+ AIMessage(content="Stored asynchronously."),
+ ]
+ )
+ messages = await history.aget_messages()
+ await history.aclear()
+
+ assert [message.content for message in messages] == [
+ "Remember async history.",
+ "Stored asynchronously.",
+ ]
+ assert backing.sessions["async-history"] == []
+ assert client.calls == [
+ "batch_add_messages",
+ "get_session_context",
+ "delete_session",
+ "create_session",
+ ]
+
+
+async def test_async_context_assembler_combines_session_and_recall():
+ backing = InMemoryOpenVikingClient(
+ {"viking://resources/runbooks/async.md": "Async context is azure."}
+ )
+ backing.add_message("async-assembler", "user", content="Active async turn.")
+ client = AsyncInMemoryOpenVikingClient(backing)
+ assembler = OpenVikingSessionContextAssembler(
+ async_client=client,
+ target_uri="viking://resources",
+ )
+
+ assembled = await assembler.aassemble(
+ session_id="async-assembler",
+ query="azure",
+ )
+
+ assert "Active async turn." in assembled.block
+ assert "Async context is azure." in assembled.block
+ assert assembled.context_parts[0]["uri"] == "viking://resources/runbooks/async.md"
+
+
+async def test_async_middleware_injects_and_captures_context():
+ backing = InMemoryOpenVikingClient(
+ {"viking://user/memories/profile.md": "Async middleware prefers teal."}
+ )
+ client = AsyncInMemoryOpenVikingClient(backing)
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ target_uri="viking://user/memories",
+ session_id_resolver=lambda _state, _runtime: "async-middleware",
+ )
+ captured_request: dict[str, Any] = {}
+
+ class Request:
+ state: dict[str, Any] = {}
+ runtime = None
+ messages = [HumanMessage(content="What teal preference?")]
+ system_message = None
+
+ def override(self, **overrides: Any) -> Request:
+ request = Request()
+ request.system_message = overrides.get("system_message", self.system_message)
+ return request
+
+ async def handler(request: Any) -> AIMessage:
+ captured_request["request"] = request
+ return AIMessage(content="teal")
+
+ await middleware.awrap_model_call(Request(), handler)
+ await middleware.aafter_agent(
+ {
+ "messages": [
+ HumanMessage(content="What color?"),
+ AIMessage(content="teal"),
+ ]
+ },
+ runtime=None,
+ )
+
+ assert "Async middleware prefers teal." in (captured_request["request"].system_message.content)
+ assistant_parts = backing.sessions["async-middleware"][1]["parts"]
+ assert any(part["type"] == "context" for part in assistant_parts)
+
+
+async def test_async_middleware_clears_pending_context_when_model_call_is_cancelled():
+ backing = InMemoryOpenVikingClient(
+ {"viking://user/memories/profile.md": "Cancelled context must not be reused."}
+ )
+ client = AsyncInMemoryOpenVikingClient(backing)
+ middleware = OpenVikingContextMiddleware(
+ async_client=client,
+ target_uri="viking://user/memories",
+ session_id_resolver=lambda _state, _runtime: "async-cancelled-middleware",
+ )
+ handler_started = asyncio.Event()
+
+ class Request:
+ state: dict[str, Any] = {}
+ runtime = None
+ messages = [HumanMessage(content="Find the cancelled context.")]
+ system_message = None
+
+ def override(self, **overrides: Any) -> Request:
+ request = Request()
+ request.system_message = overrides.get("system_message", self.system_message)
+ return request
+
+ async def handler(_request: Any) -> AIMessage:
+ handler_started.set()
+ await asyncio.Event().wait()
+ raise AssertionError("unreachable")
+
+ model_call = asyncio.create_task(middleware.awrap_model_call(Request(), handler))
+ await asyncio.wait_for(handler_started.wait(), timeout=1)
+ model_call.cancel()
+
+ with pytest.raises(asyncio.CancelledError):
+ await model_call
+
+ assert middleware._pending_context_parts == {}