langchain-openviking 0.1.0__tar.gz

langchain_openviking-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: langchain-openviking
+Version: 0.1.0
+Summary: OpenViking integrations for LangChain and LangGraph
+Author-email: ByteDance <noreply@bytedance.com>
+License-Expression: AGPL-3.0
+Project-URL: Homepage, https://github.com/volcengine/openviking
+Project-URL: Documentation, https://openviking.ai
+Project-URL: Repository, https://github.com/volcengine/openviking
+Project-URL: Issues, https://github.com/volcengine/openviking/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-core<2.0.0,>=1.0.0
+Requires-Dist: openviking-sdk>=0.1.1
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: langgraph
+Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "langgraph"
+Requires-Dist: langgraph<2.0.0,>=1.0.0; extra == "langgraph"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# langchain-openviking
+
+`langchain-openviking` is the official OpenViking integration package for
+LangChain and LangGraph applications. It keeps framework-specific adapters
+separate from the OpenViking server and communicates with remote OpenViking
+instances through the lightweight `openviking-sdk` package.
+
+## Installation
+
+For LangChain retrievers, tools, message history, and context wrappers:
+
+```bash
+pip install langchain-openviking
+```
+
+For the LangGraph store and middleware:
+
+```bash
+pip install "langchain-openviking[langgraph]"
+```
+
+## Quick start
+
+```python
+from langchain_openviking import OpenVikingRetriever
+from openviking_sdk import SyncHTTPClient
+
+client = SyncHTTPClient(
+    url="http://127.0.0.1:1933",
+    api_key="your-user-api-key",
+)
+client.initialize()
+retriever = OpenVikingRetriever(
+    client=client,
+    target_uri="viking://user/memories",
+)
+
+try:
+    documents = retriever.invoke("What deployment preferences should I remember?")
+finally:
+    client.close()
+```
+
+The package also provides `OpenVikingSessionRecorder`,
+`OpenVikingContextMiddleware`, `OpenVikingStore`,
+`OpenVikingChatMessageHistory`, and `create_openviking_tools`.
+
+## Client ownership
+
+- A client supplied through `client=` or `async_client=` remains caller-owned.
+- Clients created from `url=` are managed by the adapter and can be closed with
+  `close()` or `aclose()` as documented by each adapter.
+- Embedded `path=` mode requires the full `openviking` package. It is kept for
+  compatibility, while the standalone package's default boundary is HTTP.
+
+The previous `openviking.integrations.langchain` import path remains available
+from the full `openviking` distribution as a compatibility shim.
+
+See the [OpenViking documentation](https://openviking.ai) and the repository's
+`examples/langchain-langgraph` directory for complete examples.

langchain_openviking-0.1.0/README.md

@@ -0,0 +1,60 @@
+# langchain-openviking
+
+`langchain-openviking` is the official OpenViking integration package for
+LangChain and LangGraph applications. It keeps framework-specific adapters
+separate from the OpenViking server and communicates with remote OpenViking
+instances through the lightweight `openviking-sdk` package.
+
+## Installation
+
+For LangChain retrievers, tools, message history, and context wrappers:
+
+```bash
+pip install langchain-openviking
+```
+
+For the LangGraph store and middleware:
+
+```bash
+pip install "langchain-openviking[langgraph]"
+```
+
+## Quick start
+
+```python
+from langchain_openviking import OpenVikingRetriever
+from openviking_sdk import SyncHTTPClient
+
+client = SyncHTTPClient(
+    url="http://127.0.0.1:1933",
+    api_key="your-user-api-key",
+)
+client.initialize()
+retriever = OpenVikingRetriever(
+    client=client,
+    target_uri="viking://user/memories",
+)
+
+try:
+    documents = retriever.invoke("What deployment preferences should I remember?")
+finally:
+    client.close()
+```
+
+The package also provides `OpenVikingSessionRecorder`,
+`OpenVikingContextMiddleware`, `OpenVikingStore`,
+`OpenVikingChatMessageHistory`, and `create_openviking_tools`.
+
+## Client ownership
+
+- A client supplied through `client=` or `async_client=` remains caller-owned.
+- Clients created from `url=` are managed by the adapter and can be closed with
+  `close()` or `aclose()` as documented by each adapter.
+- Embedded `path=` mode requires the full `openviking` package. It is kept for
+  compatibility, while the standalone package's default boundary is HTTP.
+
+The previous `openviking.integrations.langchain` import path remains available
+from the full `openviking` distribution as a compatibility shim.
+
+See the [OpenViking documentation](https://openviking.ai) and the repository's
+`examples/langchain-langgraph` directory for complete examples.

langchain_openviking-0.1.0/README_CN.md

@@ -0,0 +1,47 @@
+# langchain-openviking
+
+`langchain-openviking` 是 OpenViking 官方维护的 LangChain 和 LangGraph
+集成包。框架适配逻辑不再依赖 OpenViking 服务端实现，远程访问统一通过轻量的
+`openviking-sdk` 完成。
+
+## 安装
+
+LangChain Retriever、Tools、Message History 和 Context Wrapper：
+
+```bash
+pip install langchain-openviking
+```
+
+LangGraph Store 和 Middleware：
+
+```bash
+pip install "langchain-openviking[langgraph]"
+```
+
+## 快速开始
+
+```python
+from langchain_openviking import OpenVikingRetriever
+from openviking_sdk import SyncHTTPClient
+
+client = SyncHTTPClient(
+    url="http://127.0.0.1:1933",
+    api_key="your-user-api-key",
+)
+client.initialize()
+retriever = OpenVikingRetriever(
+    client=client,
+    target_uri="viking://user/memories",
+)
+
+try:
+    documents = retriever.invoke("需要记住哪些部署偏好？")
+finally:
+    client.close()
+```
+
+外部传入的 client 仍由调用方管理。通过 `url=` 创建的 client 由适配器管理。
+`path=` 嵌入模式需要另外安装完整的 `openviking` 包。
+
+完整 `openviking` 包会继续保留原有的
+`openviking.integrations.langchain` 导入路径，并转发到本包，方便现有应用平滑迁移。

langchain_openviking-0.1.0/pyproject.toml

@@ -0,0 +1,98 @@
+[build-system]
+requires = ["setuptools>=61.0", "setuptools-scm>=8.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-openviking"
+dynamic = ["version"]
+description = "OpenViking integrations for LangChain and LangGraph"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    {name = "ByteDance", email = "noreply@bytedance.com"},
+]
+license = "AGPL-3.0"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "langchain-core>=1.0.0,<2.0.0",
+    "openviking-sdk>=0.1.1",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+langgraph = [
+    "langchain>=1.0.0,<2.0.0",
+    "langgraph>=1.0.0,<2.0.0",
+]
+test = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+dev = [
+    "build>=1.2.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+    "twine>=5.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/volcengine/openviking"
+Documentation = "https://openviking.ai"
+Repository = "https://github.com/volcengine/openviking"
+Issues = "https://github.com/volcengine/openviking/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["langchain_openviking*"]
+
+[tool.setuptools.package-data]
+langchain_openviking = ["py.typed"]
+
+[tool.setuptools_scm]
+root = "../.."
+local_scheme = "no-local-version"
+tag_regex = "^langchain-openviking@(?P<version>[0-9]+(?:\\.[0-9]+)*)$"
+git_describe_command = "git describe --dirty --tags --long --match langchain-openviking@*"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = false
+warn_unused_configs = true
+check_untyped_defs = true
+no_implicit_optional = false
+warn_redundant_casts = true
+warn_unused_ignores = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "C", "B"]
+ignore = ["E501", "B008", "C901", "B006", "B904", "E741", "E722", "B027"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"

langchain_openviking-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

langchain_openviking-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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),
+    )