Skip to content

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

fix(langchain): manage context wrapper resources (#3599)

Hao Zhed2082ad2f795
diff --git a/docs/en/agent-integrations/07-langchain-langgraph.md b/docs/en/agent-integrations/07-langchain-langgraph.md
index de9f622d5..9a8d3f5c3 100644
--- a/docs/en/agent-integrations/07-langchain-langgraph.md
+++ b/docs/en/agent-integrations/07-langchain-langgraph.md
@@ -78,12 +78,14 @@ or reset it before selecting another workspace.
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. Each `with_openviking_context()` invocation
-owns the history snapshot, peer identity, and recalled-context references used
-to record its turn. Concurrent calls may therefore share a session without a
+client per adapter and event loop. Each runnable invocation through
+`with_openviking_context()` owns the history snapshot, peer identity, and
+recalled-context references used to record its turn. Concurrent calls may
+therefore share a session without a
second live history read losing messages, and an abandoned stream does not hold
a session-wide lifecycle lock. Only the final append-and-commit step is
-serialized per session and event loop.
+serialized: async writes are serialized per session within each event loop,
+while synchronous writes are serialized per session across threads.
If cancellation occurs after a recorder has confirmed part of a write,
`arecord()` re-raises the original `asyncio.CancelledError`. Pass that exception,
@@ -101,10 +103,34 @@ release it with `await retriever.aclose()`, `await assembler.aclose()`,
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.
+
+`with_openviking_context()` returns an `OpenVikingContextRunnable`, a compatible
+subclass of LangChain's `RunnableWithMessageHistory` that owns the context and
+recording adapters it creates. It reuses their loop-scoped clients across
+invocations while keeping invocation history, peer identity, and recalled
+references isolated. Prefer a managed lifecycle:
+
+```python
+async with with_openviking_context(runnable, url="http://localhost:1933") as chain:
+ result = await chain.ainvoke(
+ {"messages": [...]},
+ config={"configurable": {"session_id": "support-thread-1"}},
+ )
+```
+
+Use `with ...` for synchronous calls, or call `close()` / `await aclose()`
+explicitly. `close()` cannot run inside an active event loop; use `aclose()`
+there. Injected clients remain caller-owned.
+
+LCEL composition returns a plain `RunnableSequence`, which does not expose the
+OpenViking close methods. Keep the managed wrapper and compose inside its
+lifecycle:
+
+```python
+async with with_openviking_context(runnable, url="http://localhost:1933") as managed:
+ chain = managed | another_step
+ result = await chain.ainvoke(...)
+```
## Peer Identity
@@ -162,11 +188,12 @@ from langchain_core.messages import AIMessage
from langchain_core.runnables import RunnableLambda
from openviking.integrations.langchain import with_openviking_context
-chain = with_openviking_context(
+with with_openviking_context(
RunnableLambda(lambda msgs: AIMessage(content="...")),
url="http://localhost:1933",
api_key="...",
-)
+) as chain:
+ result = chain.invoke(...)
```
### Agent tools
diff --git a/docs/zh/agent-integrations/07-langchain-langgraph.md b/docs/zh/agent-integrations/07-langchain-langgraph.md
index daa58bb7b..2269b8f45 100644
--- a/docs/zh/agent-integrations/07-langchain-langgraph.md
+++ b/docs/zh/agent-integrations/07-langchain-langgraph.md
@@ -75,11 +75,12 @@ workspace;切换 workspace 前应先关闭或 reset 当前 client。
`aclear()`;`OpenVikingSessionRecorder` 提供 `arecord()`、`aflush()` 和
`aclose()`。异步 LangGraph 运行会自动选择 `awrap_model_call()` 和
`aafter_agent()`。同一 adapter 首次被并发调用时,每个 event loop 只会创建一个内部
-HTTP client。每次 `with_openviking_context()` 调用都独立持有本次写入所需的 history
-快照、peer 身份和召回上下文引用。因此,同一 session 的调用可以并发执行,不会因为
+HTTP client。通过 `with_openviking_context()` 执行的每次 runnable 调用都独立持有
+本次写入所需的 history 快照、peer 身份和召回上下文引用。因此,同一 session 的调用
+可以并发执行,不会因为
退出时再次读取实时 history 而丢失消息;未消费完的 stream 也不会占用 session 级
-lifecycle lock。只有最终的 append-and-commit 步骤会在同一个 event loop 中按 session
-串行执行。
+lifecycle lock。只有最终的 append-and-commit 步骤会被串行化:async 写入在每个
+event loop 内按 session 串行执行,sync 写入则会跨线程按 session 串行执行。
如果 recorder 已确认部分写入后任务被取消,`arecord()` 会重新抛出原始
`asyncio.CancelledError`。可将该异常或外层的 `asyncio.TimeoutError` 传给
@@ -95,9 +96,31 @@ Adapter 不会关闭调用方注入的 client。对于 adapter 自行创建的 c
`await recorder.aclose()` 仍能释放全部资源。
如果条件允许,应在关闭 event loop 前关闭 HTTP-backed adapter;原始 loop 已结束后的
清理属于 best-effort。
-`with_openviking_context()` 返回 LangChain 标准的
-`RunnableWithMessageHistory`,而该类型没有 close hook。因此长期运行的异步应用使用此
-helper 时,应按上例注入并关闭由调用方管理的异步 client。
+
+`with_openviking_context()` 返回 `OpenVikingContextRunnable`。它兼容 LangChain 的
+`RunnableWithMessageHistory`,并负责管理其创建的 context 和 recording adapter。
+它会在多次调用之间复用按 event loop 隔离的 client,同时继续隔离每次调用的 history、
+peer 身份和召回引用。推荐使用托管生命周期:
+
+```python
+async with with_openviking_context(runnable, url="http://localhost:1933") as chain:
+ result = await chain.ainvoke(
+ {"messages": [...]},
+ config={"configurable": {"session_id": "support-thread-1"}},
+ )
+```
+
+同步调用使用 `with ...`,也可以显式调用 `close()` 或 `await aclose()`。不要在正在运行的
+event loop 中调用 `close()`,此时应使用 `aclose()`。注入的 client 仍由调用方管理。
+
+LCEL 组合会返回普通的 `RunnableSequence`,不会暴露 OpenViking 的 close 方法。应保留
+托管 wrapper,并在其生命周期内完成组合:
+
+```python
+async with with_openviking_context(runnable, url="http://localhost:1933") as managed:
+ chain = managed | another_step
+ result = await chain.ainvoke(...)
+```
## Peer 身份
@@ -155,11 +178,12 @@ from langchain_core.messages import AIMessage
from langchain_core.runnables import RunnableLambda
from openviking.integrations.langchain import with_openviking_context
-chain = with_openviking_context(
+with with_openviking_context(
RunnableLambda(lambda msgs: AIMessage(content="...")),
url="http://localhost:1933",
api_key="...",
-)
+) as chain:
+ result = chain.invoke(...)
```
### Agent tools
diff --git a/openviking/integrations/langchain/__init__.py b/openviking/integrations/langchain/__init__.py
index bedca28d6..5f9d97217 100644
--- a/openviking/integrations/langchain/__init__.py
+++ b/openviking/integrations/langchain/__init__.py
@@ -15,6 +15,7 @@ __all__ = [
"OpenVikingChatMessageHistory",
"OpenVikingCancellationProgress",
"OpenVikingCommitPolicy",
+ "OpenVikingContextRunnable",
"OpenVikingContextMiddleware",
"OpenVikingPartialWriteError",
"OpenVikingRecordResult",
@@ -49,6 +50,10 @@ def __getattr__(name: str) -> Any:
from openviking.integrations.langchain.context import OpenVikingSessionContextAssembler
return OpenVikingSessionContextAssembler
+ if name == "OpenVikingContextRunnable":
+ from openviking.integrations.langchain.context import OpenVikingContextRunnable
+
+ return OpenVikingContextRunnable
if name == "OpenVikingSessionRecorder":
from openviking.integrations.langchain.recording import OpenVikingSessionRecorder
diff --git a/openviking/integrations/langchain/client.py b/openviking/integrations/langchain/client.py
index 167c741d6..6ddb8bc6b 100644
--- a/openviking/integrations/langchain/client.py
+++ b/openviking/integrations/langchain/client.py
@@ -9,6 +9,7 @@ import copy
import inspect
import json
import logging
+import threading
from dataclasses import dataclass
from typing import Any, Callable, Iterable, Literal
@@ -110,6 +111,7 @@ class OpenVikingClientHandle:
def __init__(self, connection: OpenVikingConnection):
self._connection = connection
self._client: Any = None
+ self._client_lock = threading.Lock()
@property
def _initialized(self) -> bool:
@@ -120,8 +122,20 @@ class OpenVikingClientHandle:
self.reset()
def reset(self) -> None:
- client = self._client
- self._client = None
+ with self._client_lock:
+ client = self._client
+ self._client = None
+ self._close_client(client)
+
+ def _reset_if_current(self, client: Any) -> None:
+ with self._client_lock:
+ if self._client is not client:
+ return
+ self._client = None
+ self._close_client(client)
+
+ @staticmethod
+ def _close_client(client: Any) -> None:
if client is None:
return
close = getattr(client, "close", None)
@@ -133,29 +147,40 @@ class OpenVikingClientHandle:
logger.debug("OpenViking client close during recovery failed", exc_info=True)
def get(self) -> Any:
- if self._client is None:
- self._client = _create_client_from_connection(self._connection)
- return self._client
+ with self._client_lock:
+ if self._client is None:
+ self._client = _create_client_from_connection(self._connection)
+ return self._client
def _openviking_call(self, method_name: str, /, **kwargs: Any) -> Any:
return self._call_with_recovery(method_name, **kwargs)
def _call_with_recovery(self, method_name: str, /, *args: Any, **kwargs: Any) -> Any:
+ client = self.get()
try:
- return _call_client_method(self.get(), method_name, *args, **kwargs)
+ return _call_client_method(client, method_name, *args, **kwargs)
except Exception as exc:
if not _is_recoverable_client_error(exc):
raise
- self.reset()
+ self._reset_if_current(client)
if not _should_retry_method(method_name):
raise
+ retry_client = self.get()
try:
- return _call_client_method(self.get(), method_name, *args, **kwargs)
+ return _call_client_method(retry_client, method_name, *args, **kwargs)
except Exception as retry_exc:
if _is_recoverable_client_error(retry_exc):
- self.reset()
+ self._reset_if_current(retry_client)
raise
+ def __copy__(self) -> OpenVikingClientHandle:
+ return self
+
+ def __deepcopy__(self, memo: dict[int, Any]) -> OpenVikingClientHandle:
+ copied = type(self)(copy.deepcopy(self._connection, memo))
+ memo[id(self)] = copied
+ return copied
+
def __getattr__(self, name: str) -> Any:
attr = getattr(self.get(), name)
if not callable(attr):
diff --git a/openviking/integrations/langchain/context.py b/openviking/integrations/langchain/context.py
index dd4c4537d..707554f4e 100644
--- a/openviking/integrations/langchain/context.py
+++ b/openviking/integrations/langchain/context.py
@@ -6,10 +6,14 @@ from __future__ import annotations
import asyncio
import logging
+import threading
from collections.abc import AsyncIterator, Callable, Sequence
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager, contextmanager
+from copy import deepcopy
from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Iterator
+
+from pydantic import PrivateAttr
try:
from langchain_core.messages import BaseMessage, SystemMessage
@@ -37,6 +41,7 @@ from openviking.integrations.langchain.history import (
context_parts_from_documents,
)
from openviking.integrations.langchain.messages import OPENVIKING_CONTEXT_MARKER
+from openviking.integrations.langchain.recording import OpenVikingSessionRecorder
from openviking.integrations.langchain.retrievers import OpenVikingRetriever
from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
@@ -85,17 +90,51 @@ class _AsyncSessionWriteLockPool:
self._entries.pop(session_id, None)
+@dataclass(slots=True)
+class _SyncSessionWriteLockEntry:
+ lock: threading.Lock = field(default_factory=threading.Lock)
+ users: int = 0
+
+
+class _SyncSessionWriteLockPool:
+ """Serialize synchronous writes without retaining inactive session IDs."""
+
+ def __init__(self) -> None:
+ self._entries: dict[str, _SyncSessionWriteLockEntry] = {}
+ self._entries_lock = threading.Lock()
+
+ @contextmanager
+ def acquire(self, session_id: str) -> Iterator[None]:
+ with self._entries_lock:
+ entry = self._entries.get(session_id)
+ if entry is None:
+ entry = _SyncSessionWriteLockEntry()
+ self._entries[session_id] = entry
+ entry.users += 1
+ try:
+ with entry.lock:
+ yield
+ finally:
+ with self._entries_lock:
+ entry.users -= 1
+ if entry.users == 0 and self._entries.get(session_id) is entry:
+ self._entries.pop(session_id, None)
+
+
class _InvocationOpenVikingChatMessageHistory(OpenVikingChatMessageHistory):
"""Hold the entry history snapshot for one runnable invocation."""
def __init__(
self,
*args: Any,
+ recorder: OpenVikingSessionRecorder,
+ sync_write_lock_pool: _SyncSessionWriteLockPool,
async_write_lock_pools: LoopScopedAsyncClientCache,
**kwargs: Any,
):
- super().__init__(*args, **kwargs)
+ super().__init__(*args, _recorder=recorder, **kwargs)
self._entry_snapshot: list[BaseMessage] | None = None
+ self._sync_write_lock_pool = sync_write_lock_pool
self._async_write_lock_pools = async_write_lock_pools
@property
@@ -111,7 +150,8 @@ class _InvocationOpenVikingChatMessageHistory(OpenVikingChatMessageHistory):
def add_messages(self, messages: Sequence[BaseMessage]) -> None:
try:
- super().add_messages(messages)
+ with self._sync_write_lock_pool.acquire(self.session_id):
+ super().add_messages(messages)
finally:
self._entry_snapshot = None
@@ -192,9 +232,39 @@ class OpenVikingSessionContextAssembler:
self._owns_client = client is None
self._owns_retriever = retriever is None
self._client_cache: Any = None
+ self._client_cache_lock = threading.Lock()
self._async_clients = LoopScopedAsyncClientCache()
self._closed = False
+ def __deepcopy__(
+ self,
+ memo: dict[int, Any] | None = None,
+ ) -> OpenVikingSessionContextAssembler:
+ """Copy configuration with fresh caches and preserved injected ownership."""
+
+ memo = {} if memo is None else memo
+ for client in (self._connection.client, self._connection.async_client):
+ if client is not None:
+ memo[id(client)] = client
+ if not self._owns_retriever:
+ memo[id(self.retriever)] = self.retriever
+
+ copied = type(self).__new__(type(self))
+ memo[id(self)] = copied
+ copied.__dict__ = {
+ name: (
+ None
+ if name == "_client_cache"
+ else threading.Lock()
+ if name == "_client_cache_lock"
+ else LoopScopedAsyncClientCache()
+ if name == "_async_clients"
+ else deepcopy(value, memo)
+ )
+ for name, value in self.__dict__.items()
+ }
+ return copied
+
def assemble(
self,
*,
@@ -241,8 +311,13 @@ 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
+ with self._client_cache_lock:
+ self._raise_if_closed()
+ if self._client_cache is None:
+ self._client_cache = ensure_client(self._connection)
+ client = self._client_cache
+ self._raise_if_closed()
+ return client
async def get_async_client(self) -> Any:
"""Return the async client interface used by this assembler.
@@ -274,8 +349,9 @@ class OpenVikingSessionContextAssembler:
if self._closed:
return
self._closed = True
- sync_client = self._client_cache
- self._client_cache = None
+ with self._client_cache_lock:
+ 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
@@ -437,6 +513,115 @@ class OpenVikingSessionContextAssembler:
return f"{OPENVIKING_CONTEXT_MARKER}\n" + "\n\n".join(sections) + "\n</openviking_context>"
+class _OpenVikingContextResources:
+ """Share one lifecycle owner across derived runnable copies."""
+
+ def __init__(
+ self,
+ assembler: OpenVikingSessionContextAssembler,
+ recorder: OpenVikingSessionRecorder,
+ ) -> None:
+ self._assembler = assembler
+ self._recorder = recorder
+ self._closed = False
+ self._close_lock = threading.Lock()
+
+ def __copy__(self) -> _OpenVikingContextResources:
+ return self
+
+ def __deepcopy__(self, memo: dict[int, Any]) -> _OpenVikingContextResources:
+ memo[id(self)] = self
+ return self
+
+ def close(self) -> None:
+ with self._close_lock:
+ if self._closed:
+ return
+ try:
+ asyncio.get_running_loop()
+ except RuntimeError:
+ asyncio.run(self.aclose())
+ return
+ raise RuntimeError(
+ "OpenVikingContextRunnable.close() cannot run inside an active event loop; "
+ "use `await runnable.aclose()`"
+ )
+
+ async def aclose(self) -> None:
+ with self._close_lock:
+ if self._closed:
+ return
+ self._closed = True
+
+ first_error: BaseException | None = None
+ for component in (self._assembler, self._recorder):
+ 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 raise_if_closed(self) -> None:
+ with self._close_lock:
+ if self._closed:
+ raise RuntimeError("OpenVikingContextRunnable is closed")
+
+
+class OpenVikingContextRunnable(RunnableWithMessageHistory):
+ """LangChain history wrapper with deterministic OpenViking cleanup."""
+
+ _resources: _OpenVikingContextResources = PrivateAttr()
+
+ def __init__(
+ self,
+ *args: Any,
+ _resources: _OpenVikingContextResources,
+ **kwargs: Any,
+ ) -> None:
+ super().__init__(*args, **kwargs)
+ self._resources = _resources
+
+ def close(self) -> None:
+ """Release internally created resources outside a running event loop."""
+
+ self._resources.close()
+
+ async def aclose(self) -> None:
+ """Release internally created context and recording resources."""
+
+ await self._resources.aclose()
+
+ def __enter__(self) -> OpenVikingContextRunnable:
+ """Enter a synchronous managed lifecycle."""
+
+ self._resources.raise_if_closed()
+ return self
+
+ def __exit__(
+ self,
+ _exc_type: type[BaseException] | None,
+ _exc: BaseException | None,
+ _traceback: Any,
+ ) -> None:
+ self.close()
+
+ async def __aenter__(self) -> OpenVikingContextRunnable:
+ """Enter an asynchronous managed lifecycle."""
+
+ self._resources.raise_if_closed()
+ return self
+
+ async def __aexit__(
+ self,
+ _exc_type: type[BaseException] | None,
+ _exc: BaseException | None,
+ _traceback: Any,
+ ) -> None:
+ await self.aclose()
+
+
def with_openviking_context(
runnable: Any,
*,
@@ -465,8 +650,12 @@ def with_openviking_context(
session_id_config_key: str = "session_id",
peer_id_config_key: str = "peer_id",
inject_context: bool = True,
-) -> RunnableWithMessageHistory:
- """Wrap a runnable with invocation-scoped OpenViking history and context."""
+) -> OpenVikingContextRunnable:
+ """Wrap a runnable with invocation-scoped history and managed resources.
+
+ Use the returned runnable as a context manager, or call ``close()`` /
+ ``await aclose()`` when it is no longer needed.
+ """
assembler = OpenVikingSessionContextAssembler(
client=client,
@@ -488,27 +677,34 @@ def with_openviking_context(
include_active_messages=False,
include_recall=inject_context,
)
+ recorder = OpenVikingSessionRecorder(
+ client=client,
+ async_client=async_client,
+ url=url,
+ api_key=api_key,
+ account=account,
+ user=user,
+ user_id=user_id,
+ actor_peer_id=actor_peer_id,
+ path=path,
+ timeout=timeout,
+ extra_headers=extra_headers,
+ auto_initialize=auto_initialize,
+ commit_policy=commit_policy,
+ )
+ resources = _OpenVikingContextResources(assembler, recorder)
+ sync_write_lock_pool = _SyncSessionWriteLockPool()
async_write_lock_pools = LoopScopedAsyncClientCache()
def make_history(active_session_id: str) -> OpenVikingChatMessageHistory:
+ resources.raise_if_closed()
return _InvocationOpenVikingChatMessageHistory(
session_id=active_session_id,
+ recorder=recorder,
+ sync_write_lock_pool=sync_write_lock_pool,
async_write_lock_pools=async_write_lock_pools,
peer_id=peer_id,
- client=client,
- async_client=async_client,
- url=url,
- api_key=api_key,
- account=account,
- user=user,
- user_id=user_id,
- actor_peer_id=actor_peer_id,
- path=path,
- timeout=timeout,
- extra_headers=extra_headers,
- auto_initialize=auto_initialize,
token_budget=token_budget,
- commit_policy=commit_policy,
)
if session_id is None:
@@ -611,13 +807,14 @@ def with_openviking_context(
bound = (RunnableLambda(inject, afunc=ainject) | runnable).with_listeners(
on_error=clear_pending_on_error
)
- wrapped = RunnableWithMessageHistory(
+ wrapped = OpenVikingContextRunnable(
bound,
session_history_factory,
input_messages_key=input_messages_key,
output_messages_key=output_messages_key,
history_messages_key=history_messages_key,
history_factory_config=history_factory_config,
+ _resources=resources,
)
return wrapped
diff --git a/openviking/integrations/langchain/history.py b/openviking/integrations/langchain/history.py
index ff992e9ca..6c05f9c5a 100644
--- a/openviking/integrations/langchain/history.py
+++ b/openviking/integrations/langchain/history.py
@@ -67,6 +67,7 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
context_parts_acknowledger: Callable[[str], None] | None = None,
peer_id: str | None = None,
peer_id_provider: Callable[[str], str | None] | None = None,
+ _recorder: OpenVikingSessionRecorder | None = None,
):
self.session_id = session_id
self.peer_id = peer_id
@@ -78,7 +79,8 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
self.context_parts_provider = context_parts_provider
self.context_parts_acknowledger = context_parts_acknowledger
self._pending_context_parts: list[dict[str, Any]] = []
- self._recorder = OpenVikingSessionRecorder(
+ self._owns_recorder = _recorder is None
+ self._recorder = _recorder or OpenVikingSessionRecorder(
client=client,
async_client=async_client,
url=url,
@@ -200,13 +202,15 @@ class OpenVikingChatMessageHistory(BaseChatMessageHistory):
"""Release resources owned by this history adapter."""
self._acknowledge_context_parts()
- self._recorder.close()
+ if self._owns_recorder:
+ self._recorder.close()
async def aclose(self) -> None:
"""Asynchronously release resources owned by this history adapter."""
self._acknowledge_context_parts()
- await self._recorder.aclose()
+ if self._owns_recorder:
+ await self._recorder.aclose()
def _get_client(self) -> Any:
return self._recorder.client
diff --git a/openviking/integrations/langchain/recording.py b/openviking/integrations/langchain/recording.py
index ca1947b06..90083159a 100644
--- a/openviking/integrations/langchain/recording.py
+++ b/openviking/integrations/langchain/recording.py
@@ -5,6 +5,7 @@
from __future__ import annotations
import asyncio
+import threading
from collections.abc import Iterable, Sequence
from copy import deepcopy
from dataclasses import dataclass
@@ -226,20 +227,58 @@ class OpenVikingSessionRecorder:
)
self._owns_client = client is None
self._client_cache: Any = None
+ self._client_cache_lock = threading.Lock()
self._async_clients = LoopScopedAsyncClientCache()
self._pending_commit_sessions: set[str] = set()
+ self._pending_commit_lock = threading.Lock()
self._closed = False
self.commit_policy = commit_policy
self.batch_size = batch_size
+ def __deepcopy__(
+ self,
+ memo: dict[int, Any] | None = None,
+ ) -> OpenVikingSessionRecorder:
+ """Copy configuration and logical state with fresh runtime resources."""
+
+ memo = {} if memo is None else memo
+ for client in (self._connection.client, self._connection.async_client):
+ if client is not None:
+ memo[id(client)] = client
+ with self._pending_commit_lock:
+ pending_commit_sessions = set(self._pending_commit_sessions)
+
+ copied = type(self).__new__(type(self))
+ memo[id(self)] = copied
+ copied.__dict__ = {
+ name: (
+ None
+ if name == "_client_cache"
+ else threading.Lock()
+ if name in {"_client_cache_lock", "_pending_commit_lock"}
+ else LoopScopedAsyncClientCache()
+ if name == "_async_clients"
+ else pending_commit_sessions
+ if name == "_pending_commit_sessions"
+ else deepcopy(value, memo)
+ )
+ for name, value in self.__dict__.items()
+ }
+ return copied
+
@property
def client(self) -> Any:
"""Return the lazily initialized OpenViking client used by this recorder."""
self._raise_if_closed()
if self._client_cache is None:
- self._client_cache = ensure_client(self._connection)
- return self._client_cache
+ with self._client_cache_lock:
+ self._raise_if_closed()
+ if self._client_cache is None:
+ self._client_cache = ensure_client(self._connection)
+ client = self._client_cache
+ self._raise_if_closed()
+ return client
def record(
self,
@@ -310,7 +349,7 @@ class OpenVikingSessionRecorder:
persisted_pending_tokens=persisted_pending_tokens,
)
except Exception as exc:
- self._pending_commit_sessions.add(session_id)
+ self._mark_commit_pending(session_id)
raise OpenVikingPartialWriteError(
session_id=session_id,
result=result,
@@ -402,7 +441,7 @@ class OpenVikingSessionRecorder:
persisted_pending_tokens=persisted_pending_tokens,
)
except asyncio.CancelledError as exc:
- self._pending_commit_sessions.add(session_id)
+ self._mark_commit_pending(session_id)
_attach_cancellation_progress(
exc,
session_id=session_id,
@@ -411,7 +450,7 @@ class OpenVikingSessionRecorder:
)
raise
except Exception as exc:
- self._pending_commit_sessions.add(session_id)
+ self._mark_commit_pending(session_id)
raise OpenVikingPartialWriteError(
session_id=session_id,
result=result,
@@ -424,14 +463,14 @@ class OpenVikingSessionRecorder:
"""Commit a session only when it contains pending, uncommitted content."""
result = self._flush_pending_content(session_id)
- self._pending_commit_sessions.discard(session_id)
+ self._discard_pending_commit(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)
+ self._discard_pending_commit(session_id)
return result
def _flush_pending_content(self, session_id: str) -> dict[str, Any] | None:
@@ -471,16 +510,32 @@ class OpenVikingSessionRecorder:
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:
+ if not self._is_commit_pending(session_id):
return
self._flush_pending_content(session_id)
- self._pending_commit_sessions.discard(session_id)
+ self._discard_pending_commit(session_id)
async def _aretry_pending_commit(self, session_id: str) -> None:
- if session_id not in self._pending_commit_sessions:
+ if not self._is_commit_pending(session_id):
return
await self._aflush_pending_content(session_id)
- self._pending_commit_sessions.discard(session_id)
+ self._discard_pending_commit(session_id)
+
+ def _is_commit_pending(self, session_id: str) -> bool:
+ with self._pending_commit_lock:
+ return session_id in self._pending_commit_sessions
+
+ def _mark_commit_pending(self, session_id: str) -> None:
+ with self._pending_commit_lock:
+ self._pending_commit_sessions.add(session_id)
+
+ def _discard_pending_commit(self, session_id: str) -> None:
+ with self._pending_commit_lock:
+ self._pending_commit_sessions.discard(session_id)
+
+ def _clear_pending_commits(self) -> None:
+ with self._pending_commit_lock:
+ self._pending_commit_sessions.clear()
async def get_async_client(self) -> Any:
"""Return the async client interface used by this recorder.
@@ -526,9 +581,10 @@ class OpenVikingSessionRecorder:
if not uses_http_client:
self._async_clients.pop_all()
self._closed = True
- self._pending_commit_sessions.clear()
- client = self._client_cache
- self._client_cache = None
+ self._clear_pending_commits()
+ with self._client_cache_lock:
+ client = self._client_cache
+ self._client_cache = None
if client is None or not self._owns_client:
return
close = getattr(client, "close", None)
@@ -541,9 +597,10 @@ class OpenVikingSessionRecorder:
if self._closed:
return
self._closed = True
- self._pending_commit_sessions.clear()
- sync_client = self._client_cache
- self._client_cache = None
+ self._clear_pending_commits()
+ with self._client_cache_lock:
+ sync_client = self._client_cache
+ self._client_cache = None
async_clients = await asyncio.to_thread(self._async_clients.pop_all)
await aclose_openviking_clients(
diff --git a/openviking/integrations/langchain/retrievers.py b/openviking/integrations/langchain/retrievers.py
index 8e53ae2d7..572696246 100644
--- a/openviking/integrations/langchain/retrievers.py
+++ b/openviking/integrations/langchain/retrievers.py
@@ -5,6 +5,7 @@
from __future__ import annotations
import asyncio
+import threading
from typing import Any, Literal
from pydantic import ConfigDict, Field, PrivateAttr
@@ -31,6 +32,35 @@ from openviking.integrations.langchain.client import (
from openviking.utils.async_client_cache import LoopScopedAsyncClientCache
+class _SharedSyncClientCache:
+ """Share one lazily created sync client across shallow retriever copies."""
+
+ def __init__(self) -> None:
+ self._client: Any = None
+ self._owned = False
+ self._lock = threading.Lock()
+
+ def __deepcopy__(self, memo: dict[int, Any]) -> _SharedSyncClientCache:
+ copied = type(self)()
+ memo[id(self)] = copied
+ return copied
+
+ def get(self, factory: Any, *, owned: bool) -> Any:
+ with self._lock:
+ if self._client is None:
+ self._client = factory()
+ self._owned = owned
+ return self._client
+
+ def pop_owned(self) -> Any:
+ with self._lock:
+ client = self._client
+ owned = self._owned
+ self._client = None
+ self._owned = False
+ return client if owned else None
+
+
class OpenVikingRetriever(BaseRetriever):
"""Retrieve LangChain ``Document`` objects from OpenViking contexts."""
@@ -61,11 +91,10 @@ class OpenVikingRetriever(BaseRetriever):
metadata_prefix: str = "openviking"
tags: list[str] | None = Field(default=None, exclude=True)
- _client_cache: Any = PrivateAttr(default=None)
+ _sync_client_cache: _SharedSyncClientCache = PrivateAttr(default_factory=_SharedSyncClientCache)
_async_clients: LoopScopedAsyncClientCache = PrivateAttr(
default_factory=LoopScopedAsyncClientCache
)
- _owns_client_cache: bool = PrivateAttr(default=False)
_closed: bool = PrivateAttr(default=False)
def __deepcopy__(
@@ -93,9 +122,8 @@ class OpenVikingRetriever(BaseRetriever):
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(
+ return self._sync_client_cache.get(
+ lambda: ensure_client(
OpenVikingConnection(
client=self.client,
url=self.url,
@@ -109,8 +137,9 @@ class OpenVikingRetriever(BaseRetriever):
extra_headers=self.extra_headers,
auto_initialize=self.auto_initialize,
)
- )
- return self._client_cache
+ ),
+ owned=self.client is None,
+ )
async def get_async_client(self) -> Any:
"""Return the async client interface used by this retriever.
@@ -155,12 +184,11 @@ class OpenVikingRetriever(BaseRetriever):
if self._closed:
return
self._closed = True
- sync_client = self._client_cache
- self._client_cache = None
+ sync_client = self._sync_client_cache.pop_owned()
async_clients = await asyncio.to_thread(self._async_clients.pop_all)
await aclose_openviking_clients(
- sync_client if self._owns_client_cache else None,
+ sync_client,
*async_clients,
)
diff --git a/tests/integration/langchain_langgraph/test_context_lifecycle.py b/tests/integration/langchain_langgraph/test_context_lifecycle.py
new file mode 100644
index 000000000..d447669ae
--- /dev/null
+++ b/tests/integration/langchain_langgraph/test_context_lifecycle.py
@@ -0,0 +1,434 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import threading
+from typing import Any
+
+import pytest
+
+pytest.importorskip("langchain_core")
+
+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 (
+ OpenVikingCommitPolicy,
+ OpenVikingContextRunnable,
+ with_openviking_context,
+)
+
+
+def _empty_session_context() -> dict[str, Any]:
+ return {
+ "messages": [],
+ "latest_archive_overview": "",
+ "pre_archive_abstracts": [],
+ }
+
+
+def _sync_http_client_type(instances: list[Any]) -> type[Any]:
+ class TrackingSyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ def initialize(self) -> None:
+ return None
+
+ def close(self) -> None:
+ self.closed = True
+
+ def create_session(self, **_kwargs: Any) -> dict[str, Any]:
+ return {}
+
+ def get_session_context(self, **_kwargs: Any) -> dict[str, Any]:
+ return _empty_session_context()
+
+ def search(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"memories": [], "resources": [], "skills": []}
+
+ def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"added": 2}
+
+ return TrackingSyncHTTPClient
+
+
+def _async_http_client_type(instances: list[Any]) -> type[Any]:
+ class TrackingAsyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.loop: asyncio.AbstractEventLoop | None = None
+ self.close_calls = 0
+ self.close_started = asyncio.Event()
+ self.block_close = False
+ instances.append(self)
+
+ async def initialize(self) -> None:
+ self.loop = asyncio.get_running_loop()
+
+ def _check_loop(self) -> None:
+ if asyncio.get_running_loop() is not self.loop:
+ raise RuntimeError("client used from a different event loop")
+
+ async def close(self) -> None:
+ self.close_calls += 1
+ self.close_started.set()
+ if self.block_close:
+ await asyncio.Event().wait()
+
+ async def create_session(self, **_kwargs: Any) -> dict[str, Any]:
+ self._check_loop()
+ return {}
+
+ async def get_session_context(self, **_kwargs: Any) -> dict[str, Any]:
+ self._check_loop()
+ return _empty_session_context()
+
+ async def search(self, **_kwargs: Any) -> dict[str, Any]:
+ self._check_loop()
+ return {"memories": [], "resources": [], "skills": []}
+
+ async def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ self._check_loop()
+ return {"added": 2}
+
+ return TrackingAsyncHTTPClient
+
+
+def _sync_answer(messages: list[BaseMessage]) -> AIMessage:
+ latest = next(
+ message.content for message in reversed(messages) if isinstance(message, HumanMessage)
+ )
+ return AIMessage(content=f"answer:{latest}")
+
+
+async def _async_answer(messages: list[BaseMessage]) -> AIMessage:
+ await asyncio.sleep(0)
+ return _sync_answer(messages)
+
+
+def test_context_wrapper_reuses_and_closes_owned_sync_clients(monkeypatch):
+ instances: list[Any] = []
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "SyncHTTPClient", _sync_http_client_type(instances))
+
+ with with_openviking_context(
+ RunnableLambda(_sync_answer),
+ url="http://localhost:1933",
+ session_id="sync-lifecycle",
+ ) as app:
+ assert isinstance(app, OpenVikingContextRunnable)
+ assert isinstance(app, RunnableWithMessageHistory)
+ assert app.invoke([HumanMessage(content="one")]).content == "answer:one"
+ assert app.invoke([HumanMessage(content="two")]).content == "answer:two"
+ assert len(instances) == 3
+ assert not any(client.closed for client in instances)
+
+ assert all(client.closed for client in instances)
+ app.close()
+ with pytest.raises(RuntimeError, match="OpenVikingContextRunnable is closed"):
+ app.invoke([HumanMessage(content="after-close")])
+
+
+def test_context_wrapper_reuses_sync_clients_across_batch_threads(monkeypatch):
+ instances: list[Any] = []
+ instances_lock = threading.Lock()
+ client_type = _sync_http_client_type(instances)
+ original_init = client_type.__init__
+
+ def synchronized_init(self: Any, **kwargs: Any) -> None:
+ with instances_lock:
+ original_init(self, **kwargs)
+
+ monkeypatch.setattr(client_type, "__init__", synchronized_init)
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "SyncHTTPClient", client_type)
+ app = with_openviking_context(
+ RunnableLambda(_sync_answer),
+ url="http://localhost:1933",
+ inject_context=False,
+ )
+ configs = [{"configurable": {"session_id": f"sync-thread-{index}"}} for index in range(8)]
+
+ results = app.batch(
+ [[HumanMessage(content=f"message-{index}")] for index in range(8)],
+ config=configs,
+ )
+
+ assert [result.content for result in results] == [
+ f"answer:message-{index}" for index in range(8)
+ ]
+ assert len(instances) == 1
+ app.close()
+ assert instances[0].closed is True
+ with pytest.raises(RuntimeError, match="OpenVikingContextRunnable is closed"):
+ app.invoke([HumanMessage(content="after-close")], config=configs[0])
+
+
+def test_context_wrapper_copies_share_one_lifecycle_owner():
+ app = with_openviking_context(
+ RunnableLambda(_sync_answer),
+ async_client=object(),
+ session_id="copied-lifecycle",
+ )
+
+ copied = copy.deepcopy(app)
+ model_copied = app.model_copy(deep=True)
+
+ assert copied is not app
+ assert model_copied is not app
+ assert copied._resources is app._resources
+ assert model_copied._resources is app._resources
+
+ copied.close()
+ with pytest.raises(RuntimeError, match="OpenVikingContextRunnable is closed"):
+ app.invoke([HumanMessage(content="after-copy-close")])
+
+
+def test_composed_runnable_uses_retained_context_wrapper_lifecycle():
+ app = with_openviking_context(
+ RunnableLambda(_sync_answer),
+ async_client=object(),
+ session_id="composed-lifecycle",
+ inject_context=False,
+ )
+ composed = app | RunnableLambda(lambda message: message)
+
+ assert not hasattr(composed, "close")
+ app.close()
+
+ with pytest.raises(RuntimeError, match="OpenVikingContextRunnable is closed"):
+ composed.invoke([HumanMessage(content="after-close")])
+
+
+def test_context_wrapper_does_not_close_injected_sync_client():
+ class InjectedSyncClient:
+ def __init__(self):
+ self._initialized = False
+ self.initialize_calls = 0
+ self.close_calls = 0
+
+ def initialize(self) -> None:
+ self._initialized = True
+ self.initialize_calls += 1
+
+ def close(self) -> None:
+ self.close_calls += 1
+
+ def create_session(self, **_kwargs: Any) -> dict[str, Any]:
+ return {}
+
+ def get_session_context(self, **_kwargs: Any) -> dict[str, Any]:
+ return _empty_session_context()
+
+ def search(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"memories": [], "resources": [], "skills": []}
+
+ def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"added": 2}
+
+ client = InjectedSyncClient()
+ with with_openviking_context(
+ RunnableLambda(_sync_answer),
+ client=client,
+ session_id="injected-sync-lifecycle",
+ ) as app:
+ assert app.invoke([HumanMessage(content="injected")]).content == "answer:injected"
+
+ assert client.initialize_calls == 1
+ assert client.close_calls == 0
+ client.close()
+
+
+async def test_context_wrapper_reuses_and_closes_owned_async_clients(monkeypatch):
+ instances: list[Any] = []
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", _async_http_client_type(instances))
+
+ async with with_openviking_context(
+ RunnableLambda(_async_answer),
+ url="http://localhost:1933",
+ session_id="async-lifecycle",
+ ) as app:
+ assert (await app.ainvoke([HumanMessage(content="one")])).content == "answer:one"
+ assert (await app.ainvoke([HumanMessage(content="two")])).content == "answer:two"
+ assert len(instances) == 3
+ assert not any(client.close_calls for client in instances)
+
+ assert [client.close_calls for client in instances] == [1, 1, 1]
+ await app.aclose()
+ with pytest.raises(RuntimeError, match="OpenVikingContextRunnable is closed"):
+ await app.ainvoke([HumanMessage(content="after-close")])
+
+
+def test_context_wrapper_keeps_owned_async_clients_loop_scoped(monkeypatch):
+ instances: list[Any] = []
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", _async_http_client_type(instances))
+ app = with_openviking_context(
+ RunnableLambda(_async_answer),
+ url="http://localhost:1933",
+ session_id="cross-loop-lifecycle",
+ )
+
+ async def invoke(label: str) -> str:
+ result = await app.ainvoke([HumanMessage(content=label)])
+ return str(result.content)
+
+ assert asyncio.run(invoke("loop-a")) == "answer:loop-a"
+ assert asyncio.run(invoke("loop-b")) == "answer:loop-b"
+ assert len(instances) == 6
+ assert len({client.loop for client in instances}) == 2
+
+ asyncio.run(app.aclose())
+
+ assert all(client.close_calls == 1 for client in instances)
+
+
+async def test_context_wrapper_does_not_close_injected_async_client():
+ class InjectedAsyncClient:
+ def __init__(self):
+ self.initialize_calls = 0
+ self.close_calls = 0
+
+ async def initialize(self) -> None:
+ self.initialize_calls += 1
+
+ async def close(self) -> None:
+ self.close_calls += 1
+
+ async def create_session(self, **_kwargs: Any) -> dict[str, Any]:
+ return {}
+
+ async def get_session_context(self, **_kwargs: Any) -> dict[str, Any]:
+ return _empty_session_context()
+
+ async def search(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"memories": [], "resources": [], "skills": []}
+
+ async def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"added": 2}
+
+ client = InjectedAsyncClient()
+ app = with_openviking_context(
+ RunnableLambda(_async_answer),
+ async_client=client,
+ session_id="injected-lifecycle",
+ )
+
+ await app.ainvoke([HumanMessage(content="injected")])
+ await app.aclose()
+
+ assert client.initialize_calls == 1
+ assert client.close_calls == 0
+ await client.close()
+
+
+async def test_context_wrapper_close_inside_event_loop_remains_recoverable():
+ app = with_openviking_context(
+ RunnableLambda(_async_answer),
+ async_client=object(),
+ session_id="active-loop-close",
+ inject_context=False,
+ )
+
+ with pytest.raises(RuntimeError, match=r"await runnable\.aclose"):
+ app.close()
+
+ app._resources.raise_if_closed()
+ await app.aclose()
+ with pytest.raises(RuntimeError, match="closed"):
+ app._resources.raise_if_closed()
+
+
+async def test_context_wrapper_finishes_cleanup_when_aclose_is_cancelled(monkeypatch):
+ instances: list[Any] = []
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "AsyncHTTPClient", _async_http_client_type(instances))
+ app = with_openviking_context(
+ RunnableLambda(_async_answer),
+ url="http://localhost:1933",
+ session_id="cancelled-close",
+ )
+ await app.ainvoke([HumanMessage(content="initialize")])
+ assert len(instances) == 3
+ instances[0].block_close = True
+
+ closing = asyncio.create_task(app.aclose())
+ await asyncio.wait_for(instances[0].close_started.wait(), timeout=1)
+ closing.cancel()
+
+ with pytest.raises(asyncio.CancelledError):
+ await closing
+
+ assert [client.close_calls for client in instances] == [1, 1, 1]
+ await app.aclose()
+
+
+async def test_context_wrapper_retries_pending_commit_across_invocations():
+ class FailFirstCommitClient:
+ def __init__(self):
+ self.events: list[str] = []
+ self.commit_calls = 0
+
+ async def initialize(self) -> None:
+ return None
+
+ async def close(self) -> None:
+ return None
+
+ async def get_session_context(self, **_kwargs: Any) -> dict[str, Any]:
+ self.events.append("get_session_context")
+ return _empty_session_context()
+
+ async def get_session(self, **_kwargs: Any) -> dict[str, Any]:
+ self.events.append("get_session")
+ return {"pending_tokens": 1}
+
+ async def batch_add_messages(self, **_kwargs: Any) -> dict[str, Any]:
+ self.events.append("batch_add_messages")
+ return {"added": 2}
+
+ async def commit_session(self, **_kwargs: Any) -> dict[str, Any]:
+ self.events.append("commit_session")
+ self.commit_calls += 1
+ if self.commit_calls == 1:
+ raise RuntimeError("first commit failed")
+ return {}
+
+ client = FailFirstCommitClient()
+ app = with_openviking_context(
+ RunnableLambda(_async_answer),
+ async_client=client,
+ session_id="pending-commit-lifecycle",
+ inject_context=False,
+ commit_policy=OpenVikingCommitPolicy(mode="always"),
+ )
+
+ first = await app.ainvoke([HumanMessage(content="first")])
+ result = await app.ainvoke([HumanMessage(content="second")])
+
+ assert first.content == "answer:first"
+ assert result.content == "answer:second"
+ assert client.events == [
+ "get_session_context",
+ "batch_add_messages",
+ "commit_session",
+ "get_session_context",
+ "get_session",
+ "commit_session",
+ "batch_add_messages",
+ "commit_session",
+ ]
+ await app.aclose()
diff --git a/tests/unit/test_langchain_lifecycle_resources.py b/tests/unit/test_langchain_lifecycle_resources.py
new file mode 100644
index 000000000..c324a3f5b
--- /dev/null
+++ b/tests/unit/test_langchain_lifecycle_resources.py
@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+import pytest
+
+pytest.importorskip("langchain_core")
+
+from openviking.integrations.langchain import (
+ OpenVikingCommitPolicy,
+ OpenVikingRetriever,
+ OpenVikingSessionContextAssembler,
+ OpenVikingSessionRecorder,
+)
+from openviking.integrations.langchain.client import (
+ OpenVikingClientHandle,
+ OpenVikingConnection,
+)
+
+
+def test_sync_client_handle_initializes_once_under_concurrency(monkeypatch):
+ instances: list[Any] = []
+
+ class SlowSyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ def initialize(self) -> None:
+ time.sleep(0.01)
+
+ def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "SyncHTTPClient", SlowSyncHTTPClient)
+ handle = OpenVikingClientHandle(OpenVikingConnection(url="http://localhost:1933"))
+
+ with ThreadPoolExecutor(max_workers=8) as executor:
+ clients = list(executor.map(lambda _index: handle.get(), range(8)))
+
+ assert len(instances) == 1
+ assert all(client is instances[0] for client in clients)
+ assert copy.copy(handle) is handle
+ copied = copy.deepcopy(handle)
+ assert copied is not handle
+ assert copied.get() is instances[1]
+ handle.close()
+ copied.close()
+ assert all(client.closed for client in instances)
+
+
+def test_sync_client_handle_recovery_does_not_discard_fresh_client(monkeypatch):
+ instances: list[Any] = []
+ first_client_calls = threading.Barrier(2)
+
+ class RecoveringSyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.index = len(instances)
+ self.closed = False
+ instances.append(self)
+
+ def initialize(self) -> None:
+ return None
+
+ def close(self) -> None:
+ self.closed = True
+
+ def find(self, **_kwargs: Any) -> dict[str, int]:
+ if self.index == 0:
+ first_client_calls.wait(timeout=1)
+ raise ConnectionError("replace the first client")
+ return {"client": self.index}
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "SyncHTTPClient", RecoveringSyncHTTPClient)
+ handle = OpenVikingClientHandle(OpenVikingConnection(url="http://localhost:1933"))
+
+ with ThreadPoolExecutor(max_workers=2) as executor:
+ results = list(executor.map(lambda _index: handle.find(query="recover"), range(2)))
+
+ assert results == [{"client": 1}, {"client": 1}]
+ assert len(instances) == 2
+ assert instances[0].closed is True
+ assert instances[1].closed is False
+ handle.close()
+ assert instances[1].closed is True
+
+
+def test_session_scoped_retriever_copies_share_owned_sync_client(monkeypatch):
+ instances: list[Any] = []
+
+ class TrackingSyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ def initialize(self) -> None:
+ return None
+
+ def close(self) -> None:
+ self.closed = True
+
+ def find(self, **_kwargs: Any) -> dict[str, Any]:
+ return {"memories": [], "resources": [], "skills": []}
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "SyncHTTPClient", TrackingSyncHTTPClient)
+ retriever = OpenVikingRetriever(url="http://localhost:1933")
+ session_a = retriever.model_copy(update={"session_id": "session-a"})
+ session_b = retriever.model_copy(update={"session_id": "session-b"})
+
+ assert session_a.invoke("first") == []
+ assert session_b.invoke("second") == []
+ assert len(instances) == 1
+
+ independent = copy.deepcopy(retriever)
+ assert independent.invoke("deep-copy") == []
+ assert len(instances) == 2
+
+ asyncio.run(retriever.aclose())
+ asyncio.run(independent.aclose())
+
+ assert all(client.closed for client in instances)
+
+
+def test_recorder_deepcopy_preserves_configuration_with_fresh_runtime_state():
+ class NonCopyableClient:
+ def __deepcopy__(self, _memo: dict[int, Any]) -> None:
+ raise AssertionError("injected clients must not be deep-copied")
+
+ client = NonCopyableClient()
+ recorder = OpenVikingSessionRecorder(
+ client=client,
+ extra_headers={"X-Tenant": "tenant-a"},
+ commit_policy=OpenVikingCommitPolicy(mode="always"),
+ batch_size=25,
+ )
+ assert recorder.client is client
+ recorder._mark_commit_pending("pending-session")
+ recorder._async_clients.get(object)
+
+ copied = copy.deepcopy(recorder)
+
+ assert copied is not recorder
+ assert copied._connection.client is client
+ assert copied._connection.extra_headers == recorder._connection.extra_headers
+ assert copied._connection.extra_headers is not recorder._connection.extra_headers
+ assert copied.commit_policy == recorder.commit_policy
+ assert copied.commit_policy is not recorder.commit_policy
+ assert copied.batch_size == 25
+ assert copied._pending_commit_sessions == {"pending-session"}
+ assert copied._pending_commit_sessions is not recorder._pending_commit_sessions
+ assert copied._client_cache is None
+ assert copied._client_cache_lock is not recorder._client_cache_lock
+ assert copied._pending_commit_lock is not recorder._pending_commit_lock
+ assert recorder._async_clients.has_clients()
+ assert not copied._async_clients.has_clients()
+ assert copied.client is client
+
+ recorder._closed = True
+ assert copy.deepcopy(recorder)._closed is True
+
+
+def test_assembler_deepcopy_preserves_retriever_ownership_with_fresh_runtime_state():
+ class NonCopyableClient:
+ def __deepcopy__(self, _memo: dict[int, Any]) -> None:
+ raise AssertionError("injected clients must not be deep-copied")
+
+ client = NonCopyableClient()
+ assembler = OpenVikingSessionContextAssembler(
+ client=client,
+ target_uri=["viking://resources"],
+ token_budget=4096,
+ )
+ assert assembler._get_client() is client
+ assembler._async_clients.get(object)
+
+ copied = copy.deepcopy(assembler)
+
+ assert copied is not assembler
+ assert copied._connection.client is client
+ assert copied._client_cache is None
+ assert copied._client_cache_lock is not assembler._client_cache_lock
+ assert assembler._async_clients.has_clients()
+ assert not copied._async_clients.has_clients()
+ assert copied.token_budget == 4096
+ assert copied._owns_retriever is True
+ assert copied.retriever is not assembler.retriever
+ assert copied.retriever.client is client
+ assert copied.retriever.target_uri == ["viking://resources"]
+ assert copied.retriever.target_uri is not assembler.retriever.target_uri
+
+ injected_retriever = OpenVikingRetriever(client=client)
+ with_injected_retriever = OpenVikingSessionContextAssembler(
+ client=client,
+ retriever=injected_retriever,
+ )
+ copied_with_injected_retriever = copy.deepcopy(with_injected_retriever)
+
+ assert copied_with_injected_retriever.retriever is injected_retriever
+ assert copied_with_injected_retriever._owns_retriever is False
+
+ assembler._closed = True
+ assert copy.deepcopy(assembler)._closed is True
+
+
+def test_recorder_and_assembler_deepcopy_do_not_share_owned_sync_clients(monkeypatch):
+ instances: list[Any] = []
+
+ class TrackingSyncHTTPClient:
+ def __init__(self, **_kwargs: Any):
+ self.closed = False
+ instances.append(self)
+
+ def initialize(self) -> None:
+ return None
+
+ def close(self) -> None:
+ self.closed = True
+
+ import openviking.client as client_module
+
+ monkeypatch.setattr(client_module, "SyncHTTPClient", TrackingSyncHTTPClient)
+ recorder = OpenVikingSessionRecorder(url="http://localhost:1933")
+ assembler = OpenVikingSessionContextAssembler(
+ url="http://localhost:1933",
+ include_recall=False,
+ )
+ assert recorder.client.get() is instances[0]
+ assert assembler._get_client().get() is instances[1]
+
+ copied_recorder = copy.deepcopy(recorder)
+ copied_assembler = copy.deepcopy(assembler)
+ assert copied_recorder.client.get() is instances[2]
+ assert copied_assembler._get_client().get() is instances[3]
+
+ recorder.close()
+ asyncio.run(assembler.aclose())
+ copied_recorder.close()
+ asyncio.run(copied_assembler.aclose())
+
+ assert len(instances) == 4
+ assert all(client.closed for client in instances)