vinc-langgraph 0.1.0__py3-none-any.whl

vinc_langgraph/__init__.py

@@ -0,0 +1,27 @@
+"""Vinc for LangGraph and LangChain agents.
+
+Design and scope: [[vinc.plan.framework-integration-packages-2026-09-28]].
+``VincContextMiddleware`` needs the ``agents`` extra and is imported lazily.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+__version__ = "0.1.0"
+
+from .helpers import (aget_vinc_context, arecord_episode, build_system_message,  # noqa: E402
+                      create_vinc_tools, get_vinc_context, last_user_text, record_episode)
+
+
+def __getattr__(name: str) -> Any:
+    # 미들웨어는 langchain(agents 추가 설치)이 있어야 한다. 노드 헬퍼만 쓰는 사람에게
+    # 그 의존성을 강요하지 않으려고 이름을 처음 쓸 때 가져온다.
+    if name == "VincContextMiddleware":
+        from .middleware import VincContextMiddleware
+        return VincContextMiddleware
+    raise AttributeError(name)
+
+
+__all__ = ["__version__", "get_vinc_context", "aget_vinc_context", "build_system_message",
+           "create_vinc_tools", "record_episode", "arecord_episode", "last_user_text",
+           "VincContextMiddleware"]

vinc_langgraph/helpers.py

@@ -0,0 +1,152 @@
+"""Helpers for graph nodes: read context, build a system message, expose read tools, record.
+
+None of these writes on its own. ``record_episode`` writes because you call it,
+which in a graph belongs in a node after an ``interrupt()`` a person resumed.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable, Sequence
+
+from langchain_core.messages import HumanMessage, SystemMessage
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+from vinc_client import (AsyncVincClient, VincClient, VincQuotaExceeded, VincUnavailable,
+                         format_brief, format_search)
+from vinc_client.context import DEFAULT_MAX_CHARS
+
+
+def last_user_text(messages: str | Sequence[Any]) -> str:
+    """The newest human message's text; a plain string is returned as is."""
+    if isinstance(messages, str):
+        return messages.strip()
+    for message in reversed(list(messages or [])):
+        if isinstance(message, HumanMessage) or getattr(message, "type", "") == "human":
+            text = getattr(message, "text", None)
+            # 1.x 에서 .text 는 속성이다(호출하면 폐기 경고). 문자열이 아닌 호출체일 때만 부른다.
+            if callable(text) and not isinstance(text, str):
+                text = text()
+            return str(text if text is not None else message.content).strip()
+    return ""
+
+
+def get_vinc_context(client: VincClient, messages: str | Sequence[Any], *,
+                     search_fallback: bool = True, max_chars: int = DEFAULT_MAX_CHARS,
+                     max_excerpts: int = 3) -> str | None:
+    """A fenced context block for the newest human message, or ``None``.
+
+    ``None`` also when Vinc is unavailable or the quota is spent; a key or space
+    problem raises.
+    """
+    return client.get_context(last_user_text(messages), search_fallback=search_fallback,
+                              max_chars=max_chars, max_excerpts=max_excerpts)
+
+
+async def aget_vinc_context(client: AsyncVincClient, messages: str | Sequence[Any], *,
+                            search_fallback: bool = True, max_chars: int = DEFAULT_MAX_CHARS,
+                            max_excerpts: int = 3) -> str | None:
+    """Async :func:`get_vinc_context`."""
+    return await client.get_context(last_user_text(messages), search_fallback=search_fallback,
+                                    max_chars=max_chars, max_excerpts=max_excerpts)
+
+
+def build_system_message(block: str | None, base: SystemMessage | str | None = None
+                         ) -> SystemMessage | None:
+    """Append ``block`` to ``base`` (or start one). Returns ``base`` unchanged when there
+    is no block, and ``None`` when there is neither."""
+    if isinstance(base, str):
+        base = SystemMessage(content=base)
+    if not block:
+        return base
+    if base is None:
+        return SystemMessage(content=block)
+    return SystemMessage(content=[*base.content_blocks, {"type": "text", "text": block}])
+
+
+class _BriefArgs(BaseModel):
+    query: str = Field(description="A question, or an exact node id such as decision:some-slug.")
+
+
+class _SearchArgs(BaseModel):
+    query: str = Field(description="What to look for.")
+    limit: int = Field(default=5, ge=1, le=20, description="How many matches of each kind.")
+
+
+_DOWN = "Vinc is not available right now ({code}); answer without it."
+
+
+def create_vinc_tools(client: VincClient | None = None,
+                      async_client: AsyncVincClient | None = None, *,
+                      max_chars: int = DEFAULT_MAX_CHARS) -> list[StructuredTool]:
+    """Two read-only tools, ``vinc_brief`` and ``vinc_search``.
+
+    Pass a sync client, an async client, or both; each tool gets the paths it
+    has a client for. Nothing here can write.
+    """
+    if client is None and async_client is None:
+        raise ValueError("pass a VincClient, an AsyncVincClient, or both")
+
+    def brief(query: str) -> str:
+        try:
+            return (format_brief(client.brief(query), max_chars=max_chars)  # type: ignore[union-attr]
+                    or "Vinc has no single node for that; try vinc_search.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return _DOWN.format(code=exc.code)
+
+    async def abrief(query: str) -> str:
+        try:
+            return (format_brief(await async_client.brief(query), max_chars=max_chars)  # type: ignore[union-attr]
+                    or "Vinc has no single node for that; try vinc_search.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return _DOWN.format(code=exc.code)
+
+    def search(query: str, limit: int = 5) -> str:
+        try:
+            return (format_search(client.search(query, limit=limit),  # type: ignore[union-attr]
+                                  max_chars=max_chars, limit=limit) or "No matches in Vinc.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return _DOWN.format(code=exc.code)
+
+    async def asearch(query: str, limit: int = 5) -> str:
+        try:
+            return (format_search(await async_client.search(query, limit=limit),  # type: ignore[union-attr]
+                                  max_chars=max_chars, limit=limit) or "No matches in Vinc.")
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            return _DOWN.format(code=exc.code)
+
+    return [
+        StructuredTool.from_function(
+            func=brief if client else None, coroutine=abrief if async_client else None,
+            name="vinc_brief", args_schema=_BriefArgs,
+            description="Look up one node in the user's Vinc knowledge graph: a decision, "
+                        "record or concept with its summary, document excerpts and relations."),
+        StructuredTool.from_function(
+            func=search if client else None, coroutine=asearch if async_client else None,
+            name="vinc_search", args_schema=_SearchArgs,
+            description="Search the user's Vinc knowledge graph by text and meaning; returns "
+                        "matching nodes and document passages with their ids."),
+    ]
+
+
+def record_episode(client: VincClient, title: str, *, summary: str = "",
+                   about: Iterable[str] = (), date: str | None = None,
+                   domain: str | None = None, tags: Iterable[str] | None = None,
+                   space: str | None = None) -> dict[str, Any]:
+    """Write one Episode about existing concepts or decisions (needs a ``vinc_sk_`` key).
+
+    Put it in the node that runs after a person resumed an ``interrupt()``.
+    """
+    return client.record_episode(title, summary=summary, about=about, date=date,
+                                 domain=domain, tags=tags, space=space)
+
+
+async def arecord_episode(client: AsyncVincClient, title: str, *, summary: str = "",
+                          about: Iterable[str] = (), date: str | None = None,
+                          domain: str | None = None, tags: Iterable[str] | None = None,
+                          space: str | None = None) -> dict[str, Any]:
+    """Async :func:`record_episode`."""
+    return await client.record_episode(title, summary=summary, about=about, date=date,
+                                       domain=domain, tags=tags, space=space)
+
+
+__all__ = ["last_user_text", "get_vinc_context", "aget_vinc_context",
+           "build_system_message", "create_vinc_tools", "record_episode", "arecord_episode"]

vinc_langgraph/middleware.py

@@ -0,0 +1,96 @@
+"""Middleware for LangChain ``create_agent`` (which runs on LangGraph).
+
+Needs the ``agents`` extra: ``pip install "vinc-langgraph[agents]"``.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Awaitable, Callable
+
+from langchain.agents.middleware import AgentMiddleware, ModelRequest
+from vinc_client import AsyncVincClient, VincClient
+from vinc_client.context import DEFAULT_MAX_CHARS
+
+from .helpers import build_system_message, last_user_text
+
+
+class VincContextMiddleware(AgentMiddleware):
+    """Adds Vinc context to the system message of each model call.
+
+    An agent that calls tools calls the model several times for one question.
+    The answer for a question is kept for ``cache_seconds`` so those calls do not
+    each spend a Vinc call. Nothing is written: this middleware only reads.
+    """
+
+    def __init__(self, client: VincClient | None = None,
+                 async_client: AsyncVincClient | None = None, *, api_key: str | None = None,
+                 base_url: str | None = None, space: str | None = None,
+                 search_fallback: bool = True, max_chars: int = DEFAULT_MAX_CHARS,
+                 max_excerpts: int = 3, cache_seconds: float = 60.0) -> None:
+        super().__init__()
+        self._config = {"api_key": api_key, "base_url": base_url, "space": space}
+        self._client = client
+        self._async_client = async_client
+        self.search_fallback = search_fallback
+        self.max_chars = max_chars
+        self.max_excerpts = max_excerpts
+        self.cache_seconds = cache_seconds
+        self._cache: dict[str, tuple[float, str | None]] = {}
+
+    # 클라이언트는 쓰는 쪽(동기·비동기)만 만든다 — 둘 다 만들면 연결 풀이 두 벌 생긴다.
+    @property
+    def client(self) -> VincClient:
+        if self._client is None:
+            self._client = VincClient(self._config["api_key"], base_url=self._config["base_url"],
+                                      space=self._config["space"])
+        return self._client
+
+    @property
+    def async_client(self) -> AsyncVincClient:
+        if self._async_client is None:
+            self._async_client = AsyncVincClient(self._config["api_key"],
+                                                 base_url=self._config["base_url"],
+                                                 space=self._config["space"])
+        return self._async_client
+
+    def _cached(self, query: str) -> tuple[bool, str | None]:
+        hit = self._cache.get(query)
+        if hit and time.monotonic() - hit[0] < self.cache_seconds:
+            return True, hit[1]
+        return False, None
+
+    def _remember(self, query: str, block: str | None) -> None:
+        if len(self._cache) >= 64:
+            self._cache.pop(next(iter(self._cache)))
+        self._cache[query] = (time.monotonic(), block)
+
+    def _with_block(self, request: ModelRequest, block: str | None) -> ModelRequest:
+        if not block:
+            return request
+        if hasattr(request, "system_message"):
+            return request.override(
+                system_message=build_system_message(block, request.system_message))
+        # langchain 1.0 초기판의 ModelRequest 는 문자열 system_prompt 만 갖는다.
+        base = getattr(request, "system_prompt", None) or ""
+        return request.override(system_prompt=f"{base}\n\n{block}" if base else block)
+
+    def wrap_model_call(self, request: ModelRequest, handler: Callable[[ModelRequest], Any]) -> Any:
+        query = last_user_text(request.messages)
+        found, block = self._cached(query)
+        if not found:
+            block = self.client.get_context(query, search_fallback=self.search_fallback,
+                                            max_chars=self.max_chars,
+                                            max_excerpts=self.max_excerpts)
+            self._remember(query, block)
+        return handler(self._with_block(request, block))
+
+    async def awrap_model_call(self, request: ModelRequest,
+                               handler: Callable[[ModelRequest], Awaitable[Any]]) -> Any:
+        query = last_user_text(request.messages)
+        found, block = self._cached(query)
+        if not found:
+            block = await self.async_client.get_context(
+                query, search_fallback=self.search_fallback, max_chars=self.max_chars,
+                max_excerpts=self.max_excerpts)
+            self._remember(query, block)
+        return await handler(self._with_block(request, block))

vinc_langgraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: vinc-langgraph
+Version: 0.1.0
+Summary: Vinc for LangGraph and LangChain agents: bring decisions and records from your knowledge graph into graph nodes and model calls, and record an episode only when you choose to.
+Project-URL: Homepage, https://vincs.io
+Project-URL: Documentation, https://vincs.io/docs/
+Author: Vinculums
+License-Expression: MIT
+Keywords: knowledge-graph,langchain,langgraph,memory,middleware,vinc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: langgraph>=1.0
+Requires-Dist: vinc-client<0.2,>=0.1
+Provides-Extra: agents
+Requires-Dist: langchain>=1.0; extra == 'agents'
+Provides-Extra: test
+Requires-Dist: langchain>=1.0; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# vinc-langgraph
+
+[Vinc](https://vincs.io) for [LangGraph](https://langchain-ai.github.io/langgraph/) and LangChain agents. Vinc is a knowledge graph you share with AI: the decisions, records and documents your team wrote, with the reasons attached. This package brings the relevant part of it into your graph nodes and model calls.
+
+## Install
+
+```bash
+pip install vinc-langgraph            # node helpers and tools
+pip install "vinc-langgraph[agents]"  # plus the middleware for create_agent
+```
+
+Set `VINC_API_KEY` to a member key. A `vinc_ro_` key is enough for everything except `record_episode`.
+
+## In a graph node
+
+```python
+from vinc_client import VincClient
+from vinc_langgraph import build_system_message, get_vinc_context
+
+vinc = VincClient()
+
+def review(state):
+    block = get_vinc_context(vinc, state["messages"])   # newest human message
+    system = build_system_message(block, "You review design changes.")
+    return {"messages": [llm.invoke([system, *state["messages"]])]}
+```
+
+`get_vinc_context` makes one call, two when nothing matched or several nodes tied (it then widens with a search). It returns `None` when nothing matched, and also when Vinc is unreachable or the daily limit is spent, so the node goes on without it. A wrong key or space raises.
+
+## In a `create_agent` agent
+
+```python
+from langchain.agents import create_agent
+from vinc_langgraph import VincContextMiddleware
+
+agent = create_agent("openai:gpt-5", middleware=[VincContextMiddleware()])
+```
+
+The middleware adds the block to the system message of each model call. An agent that uses tools calls the model several times per question, so the answer is kept for 60 seconds (`cache_seconds`) instead of spending a Vinc call each time.
+
+## Tools the model can call
+
+```python
+from vinc_langgraph import create_vinc_tools
+
+tools = create_vinc_tools(VincClient())   # vinc_brief and vinc_search, read only
+```
+
+## Recording, after a person approved
+
+Nothing in this package writes on its own. Put `record_episode` in the node after an `interrupt()`, and give only that node a `vinc_sk_` key. `examples/approve_then_record.py` is a complete graph:
+
+```
+context -> review -> approve (interrupt) -> record
+```
+
+## License
+
+MIT

vinc_langgraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+vinc_langgraph/__init__.py,sha256=zCNRdAuCXLv3Sago5AILYbBPG5FL-IuHC4wXvB0nkHM,1084
+vinc_langgraph/helpers.py,sha256=F1VyKdMx2nJm2ASfj5xxuVUEvYQYeYW1ujRJCCnpG9Y,7389
+vinc_langgraph/middleware.py,sha256=bmX-eylBbh76i1eEGpiw8cTYRX9HPAOCXs2snvMBYuk,4483
+vinc_langgraph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vinc_langgraph-0.1.0.dist-info/METADATA,sha256=6lVN4VUOCwNiibBocC1Mzcojj2JOMCQ7KXgW1Tu3XLg,3172
+vinc_langgraph-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+vinc_langgraph-0.1.0.dist-info/RECORD,,

vinc_langgraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any