langchain-openviking 0.1.dev1885__py3-none-any.whl

langchain_openviking/__init__.py

@@ -0,0 +1,106 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""LangChain and LangGraph integrations for OpenViking.
+
+The base distribution depends on ``langchain-core``. LangGraph middleware is
+loaded only when the ``langgraph`` extra (or compatible dependencies) is
+installed.
+"""
+
+from __future__ import annotations
+
+from importlib.util import find_spec
+from typing import Any
+
+from langchain_openviking.actor_peer import (
+    has_request_actor_peer_support,
+)
+
+__all__ = [
+    "InMemoryOpenVikingClient",
+    "OpenVikingChatMessageHistory",
+    "OpenVikingCancellationProgress",
+    "OpenVikingCommitPolicy",
+    "OpenVikingContextRunnable",
+    "OpenVikingPartialWriteError",
+    "OpenVikingRecordResult",
+    "OpenVikingRetriever",
+    "OpenVikingSessionContextAssembler",
+    "OpenVikingSessionRecorder",
+    "OpenVikingStore",
+    "create_openviking_tools",
+    "get_openviking_cancellation_progress",
+    "has_request_actor_peer_support",
+    "with_openviking_context",
+]
+
+if find_spec("langchain") is not None:
+    __all__.append("OpenVikingContextMiddleware")
+
+
+def __getattr__(name: str) -> Any:
+    if name == "OpenVikingRetriever":
+        from langchain_openviking.retrievers import OpenVikingRetriever
+
+        return OpenVikingRetriever
+    if name == "create_openviking_tools":
+        from langchain_openviking.tools import create_openviking_tools
+
+        return create_openviking_tools
+    if name == "OpenVikingStore":
+        from langchain_openviking.store import OpenVikingStore
+
+        return OpenVikingStore
+    if name == "OpenVikingChatMessageHistory":
+        from langchain_openviking.history import OpenVikingChatMessageHistory
+
+        return OpenVikingChatMessageHistory
+    if name == "OpenVikingSessionContextAssembler":
+        from langchain_openviking.context import OpenVikingSessionContextAssembler
+
+        return OpenVikingSessionContextAssembler
+    if name == "OpenVikingContextRunnable":
+        from langchain_openviking.context import OpenVikingContextRunnable
+
+        return OpenVikingContextRunnable
+    if name == "OpenVikingSessionRecorder":
+        from langchain_openviking.recording import OpenVikingSessionRecorder
+
+        return OpenVikingSessionRecorder
+    if name == "OpenVikingPartialWriteError":
+        from langchain_openviking.recording import OpenVikingPartialWriteError
+
+        return OpenVikingPartialWriteError
+    if name == "OpenVikingRecordResult":
+        from langchain_openviking.recording import OpenVikingRecordResult
+
+        return OpenVikingRecordResult
+    if name == "OpenVikingCancellationProgress":
+        from langchain_openviking.recording import (
+            OpenVikingCancellationProgress,
+        )
+
+        return OpenVikingCancellationProgress
+    if name == "get_openviking_cancellation_progress":
+        from langchain_openviking.recording import (
+            get_openviking_cancellation_progress,
+        )
+
+        return get_openviking_cancellation_progress
+    if name == "OpenVikingCommitPolicy":
+        from langchain_openviking.client import OpenVikingCommitPolicy
+
+        return OpenVikingCommitPolicy
+    if name == "with_openviking_context":
+        from langchain_openviking.context import with_openviking_context
+
+        return with_openviking_context
+    if name == "OpenVikingContextMiddleware":
+        from langchain_openviking.middleware import OpenVikingContextMiddleware
+
+        return OpenVikingContextMiddleware
+    if name == "InMemoryOpenVikingClient":
+        from langchain_openviking.testing import InMemoryOpenVikingClient
+
+        return InMemoryOpenVikingClient
+    raise AttributeError(name)

langchain_openviking/_async_client_cache.py

@@ -0,0 +1,124 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Private event-loop scoped cache for integration-owned async clients."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+import weakref
+from collections.abc import Callable
+from typing import Any, Protocol
+
+
+class _Closeable(Protocol):
+    def close(self) -> Any: ...
+
+
+class _AsyncCloseable(Protocol):
+    def aclose(self) -> Any: ...
+
+
+def _close_client(client: _Closeable) -> Any:
+    return client.close()
+
+
+def _aclose_client(client: _AsyncCloseable) -> Any:
+    return client.aclose()
+
+
+class LoopScopedAsyncClientCache:
+    """Cache integration-owned async clients per running event loop.
+
+    HTTP clients may bind internal asyncio primitives to the loop that first
+    uses them. Keeping this small cache private lets the adapter own that
+    lifecycle without importing OpenViking server utilities.
+    """
+
+    def __init__(self) -> None:
+        self._clients_by_loop: weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, Any] = (
+            weakref.WeakKeyDictionary()
+        )
+        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 the client for the current loop, creating it if necessary."""
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            with self._lock:
+                if self._fallback_client is None:
+                    self._fallback_client = factory()
+                return self._fallback_client
+
+        with self._lock:
+            client = self._clients_by_loop.get(loop)
+            if client is None:
+                client = factory()
+                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 every retained client."""
+
+        with self._lock:
+            clients = list(self._clients_by_loop.values())
+            self._clients_by_loop.clear()
+            if self._fallback_client is not None:
+                clients.append(self._fallback_client)
+                self._fallback_client = None
+            return clients
+
+    @staticmethod
+    async def _close_clients(clients: list[Any], close_client: Callable[[Any], Any]) -> None:
+        seen: set[int] = set()
+        for client in clients:
+            client_id = id(client)
+            if client_id in seen:
+                continue
+            seen.add(client_id)
+            result = close_client(client)
+            if inspect.isawaitable(result):
+                await result
+
+    def close_all(self, close_client: Callable[[Any], Any]) -> None:
+        """Close and clear all cached clients on a best-effort basis."""
+
+        clients = self.pop_all()
+        if not clients:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+        if loop and loop.is_running():
+            loop.create_task(self._close_clients(clients, close_client))
+        else:
+            asyncio.run(self._close_clients(clients, close_client))
+
+    def close_all_with_close(self) -> None:
+        self.close_all(_close_client)
+
+    def close_all_with_aclose(self) -> None:
+        self.close_all(_aclose_client)

langchain_openviking/_testing_utils.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Private deterministic helpers for the in-memory integration test client."""
+
+from __future__ import annotations
+
+import math
+import re
+
+_IDENTIFIER_PATTERN = re.compile(r"^[a-zA-Z0-9_.@-]+$")
+
+
+def normalize_peer_id(peer_id: str | None) -> str | None:
+    """Normalize a peer identifier using OpenViking's public wire constraints."""
+
+    if peer_id is None:
+        return None
+    if not isinstance(peer_id, str):
+        raise ValueError("Invalid peer_id: peer_id must be a string.")
+    normalized = peer_id.strip()
+    if not normalized:
+        return None
+    if normalized in {".", ".."}:
+        raise ValueError("Invalid peer_id: peer_id must not be '.' or '..'")
+    if not _IDENTIFIER_PATTERN.fullmatch(normalized):
+        raise ValueError("Invalid peer_id: peer_id must be alpha_numeric string.")
+    if normalized.count("@") > 1:
+        raise ValueError("Invalid peer_id: peer_id must have at most one @.")
+    return normalized
+
+
+def _is_cjk_code_point(code_point: int) -> bool:
+    return (
+        0x3400 <= code_point <= 0x4DBF
+        or 0x4E00 <= code_point <= 0x9FFF
+        or 0xF900 <= code_point <= 0xFAFF
+        or 0x20000 <= code_point <= 0x2EBEF
+        or 0x3040 <= code_point <= 0x30FF
+        or 0x31F0 <= code_point <= 0x31FF
+        or 0xAC00 <= code_point <= 0xD7AF
+        or 0x1100 <= code_point <= 0x11FF
+        or 0x3130 <= code_point <= 0x318F
+        or 0xFF00 <= code_point <= 0xFFEF
+        or 0x3000 <= code_point <= 0x303F
+    )
+
+
+def estimate_text_tokens(text: str | None) -> int:
+    """Estimate tokens conservatively without depending on server internals."""
+
+    if not text:
+        return 0
+    weight = 0.0
+    for char in text:
+        code_point = ord(char)
+        if _is_cjk_code_point(code_point):
+            weight += 1.5
+        elif code_point > 0xFFFF:
+            weight += 2.0
+        else:
+            weight += 0.25
+    return math.ceil(weight)

langchain_openviking/_uri.py

@@ -0,0 +1,61 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Narrow Viking URI parsing used by the LangGraph store adapter."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+_CONTENT_SEGMENTS = frozenset({"memories", "resources", "skills"})
+_PEER_CONTENT_SEGMENTS = frozenset({"memories", "resources"})
+
+
+@dataclass(frozen=True)
+class UriClassification:
+    """Structural URI information needed to validate store record paths."""
+
+    parts: tuple[str, ...]
+    scope: str
+    content_index: int | None
+
+
+def _uri_parts(uri: str) -> tuple[str, ...]:
+    value = str(uri or "").split("?", 1)[0].strip()
+    if not value:
+        return ()
+    if value == "/":
+        value = "viking://"
+    elif not value.startswith("viking://"):
+        value = f"viking://{value.lstrip('/')}"
+    if value.rstrip("/") == "viking:":
+        return ()
+    return tuple(part for part in value[len("viking://") :].split("/") if part)
+
+
+def _content_segment_index(parts: tuple[str, ...]) -> int | None:
+    if len(parts) >= 2 and parts[:2] == ("agent", "skills"):
+        return 1
+    if len(parts) >= 3 and parts[0] == "agent" and parts[2] in _CONTENT_SEGMENTS:
+        return 2
+    if len(parts) < 2 or parts[0] != "user":
+        return None
+    if parts[1] in _CONTENT_SEGMENTS:
+        return 1
+    if len(parts) >= 4 and parts[1] == "peers" and parts[3] in _PEER_CONTENT_SEGMENTS:
+        return 3
+    if len(parts) >= 5 and parts[2] == "peers" and parts[4] in _PEER_CONTENT_SEGMENTS:
+        return 4
+    if len(parts) >= 3 and parts[2] in _CONTENT_SEGMENTS:
+        return 2
+    return None
+
+
+def classify_uri(uri: str) -> UriClassification:
+    """Classify the user/agent namespace shape of a Viking URI."""
+
+    parts = _uri_parts(uri)
+    return UriClassification(
+        parts=parts,
+        scope=parts[0] if parts else "",
+        content_index=_content_segment_index(parts),
+    )

langchain_openviking/actor_peer.py

@@ -0,0 +1,48 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Compatibility bridge for request-scoped actor peers in openviking-sdk."""
+
+from __future__ import annotations
+
+from contextlib import AbstractContextManager
+from importlib import import_module
+from typing import Callable, cast
+
+_openviking_sdk = import_module("openviking_sdk")
+_actor_peer_getter = getattr(_openviking_sdk, "get_actor_peer_id", None)
+_actor_peer_scope = getattr(_openviking_sdk, "use_actor_peer", None)
+
+
+def has_request_actor_peer_support() -> bool:
+    """Return whether the installed SDK supports request-scoped actor peers."""
+
+    return _actor_peer_getter is not None and _actor_peer_scope is not None
+
+
+def require_request_actor_peer_support() -> None:
+    """Raise an actionable error when request-scoped actor peers are unavailable."""
+
+    if not has_request_actor_peer_support():
+        raise ImportError(
+            "Runtime actor peers require an openviking-sdk release with "
+            "request-scoped actor-peer support. Upgrade openviking-sdk and retry."
+        )
+
+
+def get_actor_peer_id() -> str | None:
+    """Return the active SDK actor peer, tolerating older SDKs when unused."""
+
+    if _actor_peer_getter is None:
+        return None
+    return cast(Callable[[], str | None], _actor_peer_getter)()
+
+
+def use_actor_peer(actor_peer_id: str | None) -> AbstractContextManager[None]:
+    """Apply an SDK actor-peer scope after confirming SDK support."""
+
+    require_request_actor_peer_support()
+    scope_factory = cast(
+        Callable[[str | None], AbstractContextManager[None]],
+        _actor_peer_scope,
+    )
+    return scope_factory(actor_peer_id)