feat(langchain): add LangChain and LangGraph context adapters

[ehz0ah]

Description

This adds optional LangChain and LangGraph adapters so Python agent applications can use OpenViking as their context backend without each app writing its own glue code.

The usual deployment is: the LangChain or LangGraph app keeps owning the agent flow and LLM calls, while OpenViking handles context storage, indexing, retrieval, session memory, and source information returned with retrieved context.

Changes

• Added openviking.integrations.langchain with lazy exports for:
  • with_openviking_context() for LangChain runnable context injection and session capture
  • OpenVikingContextMiddleware for LangGraph agent context injection and post-run capture
  • OpenVikingChatMessageHistory for LangChain message history backed by OpenViking sessions
  • OpenVikingRetriever for LangChain document retrieval from OpenViking search/find results
  • OpenVikingStore for LangGraph durable store usage
  • create_openviking_tools() for exposing common OpenViking read/search/write tools to agents
• Added optional langchain and langgraph package extras.
• Added English and Chinese docs plus examples under examples/langchain-langgraph/ for LangChain RAG, LangChain context backend, LangChain message history, LangGraph agent tools/store, and LangGraph middleware.
• Added focused unit coverage, deterministic smoke examples, and a true-live e2e suite for local OpenViking + LLM validation.

Design Notes

The adapters follow the host framework shapes instead of introducing a separate agent framework. LangChain users get runnables, retrievers, chat history, and tools. LangGraph users get middleware and a BaseStore-style store. OpenViking remains the source of truth for sessions, URIs, indexing, retrieval, and persistence.

LangChain/LangGraph dependencies are optional and loaded lazily, so installing or importing core OpenViking does not pull those frameworks in unless the user opts into the integration extras.

Validation

• uv run --extra test --extra langchain --extra langgraph pytest tests/client/test_http_client_config.py tests/unit/test_langchain_integration.py tests/integration/langchain_langgraph/test_smoke.py -q
  • Result: 60 passed
• uv run --extra test --extra langchain --extra langgraph pytest tests/integration/langchain_langgraph/live_e2e.py -q -s
  • Result: 5 passed against a fresh local OpenViking workspace
• Changed-file ruff checks:
  • uv run --extra dev ruff format --check ...
  • uv run --extra dev ruff check ...
• git diff --check

The tests exercise real LangChain and LangGraph application flows, not just mocked adapter calls.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🏅 Score: 85

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 Multiple PR themes Sub-PR theme: Add LangChain integration components Relevant files: openviking/integrations/langchain/init.py openviking/integrations/langchain/client.py openviking/integrations/langchain/history.py openviking/integrations/langchain/context.py openviking/integrations/langchain/retrievers.py tests/unit/test_langchain_integration.py examples/langchain-rag/* examples/langchain-context-backend/* Sub-PR theme: Add LangGraph integration components Relevant files: openviking/integrations/langchain/middleware.py openviking/integrations/langchain/store.py examples/langgraph-agent/* Sub-PR theme: Add documentation for LangChain/LangGraph integrations Relevant files: docs/en/agent-integrations/05-langchain-langgraph.md docs/zh/agent-integrations/05-langchain-langgraph.md

⚡ Recommended focus areas for review Potential unexpected comparison fallback The _compare function defaults to equality check for unrecognized operators, which could lead to unexpected behavior if an invalid operator is used. def _compare(actual: Any, op: str, target: Any) -> bool: if op in {"$eq", "eq"}: return actual == target if op in {"$ne", "ne"}: return actual != target if op in {"$gt", "gt"}: return actual > target if op in {"$gte", "gte"}: return actual >= target if op in {"$lt", "lt"}: return actual < target if op in {"$lte", "lte"}: return actual <= target if op in {"$in", "in"}: return actual in target return actual == target

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.

[qin-ctx]

Thanks for putting together the LangChain/LangGraph integration. I found two blocking issues that should be addressed before merge: the middleware currently falls back to a shared default session when no thread/session id is present, and the LangGraph store cannot resolve canonicalized user/agent store URIs under namespace isolation.

[qin-ctx]

Thanks for the LangChain/LangGraph integration work. I re-reviewed the latest head and found two blocking issues plus one test-gating suggestion. The previous blocking comments about the shared LangGraph fallback session and canonical store URI parsing look fixed in this head.

[qin-ctx]

Thanks for the updates. I re-reviewed the current head and the prior two blocking comments look addressed. I found two remaining blocking issues: the HTTP user_id connection parameter is currently ignored by the underlying client path, and LangGraph store filter range comparisons can raise on missing or incompatible fields instead of skipping non-matches.

[ZaynJarvis]

merge to feel

approved elsewhere