Skip to content

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

27.9 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Shared helpers for LangChain/LangGraph integration adapters."""

from __future__ import annotations

import asyncio
import copy
import inspect
import json
import logging
import threading
from dataclasses import dataclass
from typing import Any, Iterable, Literal

from langchain_openviking._async_client_cache import LoopScopedAsyncClientCache

logger = logging.getLogger(__name__)

_RETRYABLE_READ_METHODS = {
    "abstract",
    "archive_expand",
    "archive_search",
    "find",
    "get_session",
    "get_session_archive",
    "get_session_context",
    "get_status",
    "glob",
    "health",
    "is_healthy",
    "ls",
    "overview",
    "read",
    "search",
    "session_exists",
    "stat",
}

_RECOVERABLE_OPENVIKING_CODES = {"DEADLINE_EXCEEDED", "UNAVAILABLE"}
_RECOVERABLE_RUNTIME_MESSAGE_FRAGMENTS = (
    "event loop is closed",
    "attached to a different loop",
    "bound to a different event loop",
)
_ASYNC_INITIALIZATION_LOCKS_ATTR = "_openviking_integration_initialize_locks"


class OptionalDependencyError(ImportError):
    """Raised when an optional framework dependency is not installed."""


def missing_dependency(extra: str, package: str | None = None) -> OptionalDependencyError:
    package = package or extra
    install_target = "langchain-openviking"
    if extra == "langgraph":
        install_target += "[langgraph]"
    return OptionalDependencyError(
        f"{package} is required for this OpenViking integration. "
        f'Install it with `pip install "{install_target}"`.'
    )


@dataclass(slots=True)
class OpenVikingConnection:
    """Connection settings for lazily creating an OpenViking client."""

    client: Any = None
    url: str | None = None
    api_key: str | None = None
    account: str | None = None
    user: str | None = None
    user_id: str | None = None
    actor_peer_id: str | None = None
    timeout: float = 60.0
    extra_headers: dict[str, str] | None = None
    auto_initialize: bool = True
    async_client: Any = None

    def __deepcopy__(self, memo: dict[int, Any]) -> OpenVikingConnection:
        """Copy configuration while preserving caller-owned client identities."""

        copied = type(self)(
            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,
            timeout=self.timeout,
            extra_headers=copy.deepcopy(self.extra_headers, memo),
            auto_initialize=self.auto_initialize,
        )
        memo[id(self)] = copied
        return copied


@dataclass(slots=True)
class OpenVikingCommitPolicy:
    """Commit behavior for OpenViking-backed agent sessions."""

    mode: Literal["never", "always", "pending_tokens"] = "never"
    pending_token_threshold: int = 8_000


class OpenVikingClientHandle:
    """Lazy OpenViking client wrapper with one-shot recovery for safe reads."""

    def __init__(self, connection: OpenVikingConnection):
        self._connection = connection
        self._client: Any = None
        self._client_lock = threading.Lock()

    @property
    def supports_request_actor_peer(self) -> bool:
        """Return whether this handle supports request-scoped actor peers."""

        return True

    @property
    def _initialized(self) -> bool:
        client = self._client
        return bool(client is not None and getattr(client, "_initialized", False))

    def close(self) -> None:
        self.reset()

    def reset(self) -> 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)
        if not callable(close):
            return
        try:
            close()
        except Exception:
            logger.debug("OpenViking client close during recovery failed", exc_info=True)

    def get(self) -> Any:
        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(client, method_name, *args, **kwargs)
        except Exception as exc:
            if not _is_recoverable_client_error(exc):
                raise
            self._reset_if_current(client)
            if not _should_retry_method(method_name):
                raise
            retry_client = self.get()
            try:
                return _call_client_method(retry_client, method_name, *args, **kwargs)
            except Exception as retry_exc:
                if _is_recoverable_client_error(retry_exc):
                    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):
            return attr

        def recovered_method(*args: Any, **kwargs: Any) -> Any:
            return self._call_with_recovery(name, *args, **kwargs)

        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 supports_request_actor_peer(self) -> bool:
        """Return whether this handle supports request-scoped actor peers."""

        return True

    @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.

        Creating the client does not initialize it when the connection has
        ``auto_initialize`` disabled, so an explicit request must run the
        once-only async initialization itself.
        """

        client = await self.get()
        if hasattr(client, "initialize"):
            await _ainitialize_client(client)

    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."""

    client = connection.client
    if client is None:
        handle = OpenVikingClientHandle(connection)
        if connection.auto_initialize:
            handle.get()
        return handle
    if connection.auto_initialize and hasattr(client, "initialize"):
        if not getattr(client, "_initialized", False):
            client.initialize()
    return client


async def ensure_async_client(
    connection: OpenVikingConnection,
    *,
    client_cache: LoopScopedAsyncClientCache | 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``.
    """

    client = connection.async_client
    if client is None and connection.client is not None:
        client = connection.client
    if client is None:
        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 connection.auto_initialize and hasattr(client, "initialize"):
        await _ainitialize_client(client)
    return client


def is_not_found_error(exc: BaseException) -> bool:
    """True for OpenViking NOT_FOUND across cli/sdk exception classes."""

    if isinstance(exc, FileNotFoundError):
        return True
    return str(getattr(exc, "code", "") or "").upper() == "NOT_FOUND"


def apply_commit_policy(
    client: Any,
    session_id: str,
    policy: OpenVikingCommitPolicy | None,
    *,
    persisted_pending_tokens: Any = None,
) -> dict[str, Any] | None:
    """Apply the configured session commit policy after message persistence.

    ``persisted_pending_tokens`` is the post-write value returned by
    ``add_message`` or ``batch_add_messages``.  When an older client does not
    return it, the pending-token policy falls back to the legacy session lookup.
    Committing remains a separate operation from message persistence.
    """

    if policy is None or policy.mode == "never":
        return None
    if policy.mode == "always":
        return call_openviking(
            client,
            "commit_session",
            session_id=session_id,
        )
    if policy.mode != "pending_tokens":
        raise ValueError(f"Unsupported OpenViking commit policy: {policy.mode}")

    pending_tokens: int | None = None
    if persisted_pending_tokens is not None:
        try:
            pending_tokens = int(persisted_pending_tokens or 0)
        except (TypeError, ValueError):
            logger.debug(
                "Ignoring invalid persisted pending-token value and falling back "
                "to session lookup: %r",
                persisted_pending_tokens,
            )

    if pending_tokens is None:
        try:
            session = call_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 call_openviking(
        client,
        "commit_session",
        session_id=session_id,
    )


async def aapply_commit_policy(
    client: Any,
    session_id: str,
    policy: OpenVikingCommitPolicy | None,
    *,
    persisted_pending_tokens: Any = 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}")

    pending_tokens: int | None = None
    if persisted_pending_tokens is not None:
        try:
            pending_tokens = int(persisted_pending_tokens or 0)
        except (TypeError, ValueError):
            logger.debug(
                "Ignoring invalid persisted pending-token value and falling back "
                "to session lookup: %r",
                persisted_pending_tokens,
            )

    if pending_tokens is None:
        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 client variants."""

    openviking_call = getattr(client, "_openviking_call", None)
    if callable(openviking_call):
        return openviking_call(method_name, **kwargs)
    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:
    from openviking_sdk import SyncHTTPClient

    client: Any = SyncHTTPClient(
        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,
    )

    if connection.auto_initialize and hasattr(client, "initialize"):
        if not getattr(client, "_initialized", False):
            client.initialize()
    return client


async def _create_async_client_from_connection(connection: OpenVikingConnection) -> Any:
    from openviking_sdk 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,
    /,
    *args: Any,
    **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 _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 {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:
        return {key: value for key, value in kwargs.items() if value is not None}
    values = {key: value for key, value in kwargs.items() if value is not None}
    filtered = {key: value for key, value in values.items() if key in signature.parameters}
    extra = {key: value for key, value in values.items() if key not in signature.parameters}
    if "message" in signature.parameters and "message" not in filtered and extra:
        filtered["message"] = extra
    elif "options" in signature.parameters and "options" not in filtered and extra:
        filtered["options"] = extra
    return filtered


def _should_retry_method(method_name: str) -> bool:
    return method_name in _RETRYABLE_READ_METHODS


def _is_recoverable_client_error(exc: BaseException) -> bool:
    code = getattr(exc, "code", None)
    if isinstance(code, str) and code.upper() in _RECOVERABLE_OPENVIKING_CODES:
        return True
    if isinstance(exc, (ConnectionError, TimeoutError, OSError)):
        return True
    if isinstance(exc, RuntimeError):
        message = str(exc).lower()
        return any(fragment in message for fragment in _RECOVERABLE_RUNTIME_MESSAGE_FRAGMENTS)
    try:
        import httpx
    except Exception:  # pragma: no cover - httpx is available in HTTP installs
        return False
    return isinstance(exc, (httpx.TimeoutException, httpx.TransportError))


def result_groups(result: Any) -> list[tuple[str, list[Any]]]:
    """Normalize OpenViking retrieval results into named context groups."""

    if result is None:
        return []
    if isinstance(result, dict):
        return [
            ("memory", list(result.get("memories") or [])),
            ("resource", list(result.get("resources") or [])),
            ("skill", list(result.get("skills") or [])),
        ]
    return [
        ("memory", list(getattr(result, "memories", []) or [])),
        ("resource", list(getattr(result, "resources", []) or [])),
        ("skill", list(getattr(result, "skills", []) or [])),
    ]


def item_value(item: Any, key: str, default: Any = None) -> Any:
    if isinstance(item, dict):
        return item.get(key, default)
    return getattr(item, key, default)


def iter_result_items(
    result: Any,
    context_types: Iterable[str] = ("memory", "resource", "skill"),
) -> Iterable[tuple[str, Any]]:
    allowed = set(context_types)
    for context_type, items in result_groups(result):
        if context_type not in allowed:
            continue
        for item in items:
            yield context_type, item


def compact_json(value: Any) -> str:
    return json.dumps(value, ensure_ascii=False, default=str, separators=(",", ":"))


def stringify(value: Any, *, max_chars: int = 12_000) -> str:
    if value is None:
        text = ""
    elif isinstance(value, str):
        text = value
    else:
        text = json.dumps(value, ensure_ascii=False, default=str, indent=2)
    if max_chars > 0 and len(text) > max_chars:
        return text[:max_chars] + "\n...[truncated]"
    return text


def extract_message_text(content: Any) -> str:
    """Extract text from LangChain/OpenAI-style message content."""

    if isinstance(content, str):
        return content
    if isinstance(content, list):
        chunks: list[str] = []
        for block in content:
            if isinstance(block, str):
                chunks.append(block)
            elif isinstance(block, dict):
                if block.get("type") in ("text", "input_text", "output_text") and isinstance(
                    block.get("text"), str
                ):
                    chunks.append(block["text"])
                elif isinstance(block.get("content"), str):
                    chunks.append(block["content"])
        return "\n".join(chunk for chunk in chunks if chunk)
    if content is None:
        return ""
    return str(content)


def get_message_role(message: Any) -> str:
    """Normalize conversation role aliases, preserving typed-message precedence."""

    if isinstance(message, dict):
        role = message.get("type") or message.get("role")
    else:
        role = getattr(message, "type", None) or getattr(message, "role", None)
    if role in ("chat", "ChatMessageChunk"):
        role = message.get("role") if isinstance(message, dict) else getattr(message, "role", None)
    if role in ("human", "user", "HumanMessageChunk"):
        return "user"
    if role in ("system", "developer", "SystemMessageChunk"):
        return "system"
    if role in ("ai", "assistant", "AIMessageChunk"):
        return "assistant"
    return str(role or "")


def get_latest_user_text(messages: Iterable[Any]) -> str:
    for message in reversed(list(messages)):
        if get_message_role(message) == "user":
            content = (
                message.get("content")
                if isinstance(message, dict)
                else getattr(message, "content", "")
            )
            text = extract_message_text(content).strip()
            if text:
                return text
    return ""