vinc-langgraph 0.1.0__tar.gz

vinc_langgraph-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+# 예외: 디자인 허브 산출물은 **계약**이라 추적한다. 소비 리포의 사본
+# (app/src/tokens.*.css·theme.ts)이 커밋돼 있으므로 그 비교 대상도 리포에 있어야
+# `sync_out.py --check`(CI 드리프트 게이트)가 성립한다. 없으면 게이트가
+# "[MISSING·허브]" 로 죽는다 — 2026-08-08 CI 실패의 원인.
+!design-hub/dist/
+# 단, Claude Design 푸시 번들은 제외 — 업로드 직전에 만드는 임시 산출물이고
+# 대조할 커밋된 소비 사본이 없다(그쪽은 claude.ai 프로젝트에 산다).
+design-hub/dist/claude-design/
+build/
+*.egg-info/
+models/
+vinc_store
+*.lbug
+vinc_e2e/
+node_modules/
+app/src-tauri/target/
+app/src-tauri/binaries/
+app/src-tauri/gen/
+# .claude/ 는 기기별 설정(launch.json·ui-events.jsonl·worktrees)이라 **어느 깊이에서도**
+# 추적하지 않는다. 예외는 이제 없다. 역할 껍데기는 `agents/shells/` 에서 추적되고
+# (`agents_sync.py --check` 가 CI 에서 대조), 하네스가 읽는 사본은 리포 밖 워크스페이스
+# 루트에 `--install` 이 쓴다. 리포 안 `.claude/agents` 는 체크아웃의 브랜치를 따라
+# 수가 달라지는 두 번째 로스터였다.
+# ⚠ 전에는 루트의 `.claude/agents/` 만 되살리려고 네 줄을 겹쳐 썼다(한 줄로는 예외가
+# 사문이 되거나 `_migration/**/.claude/` 중첩본이 새어 나갔다, 2026-08-23 PR #69).
+# 예외가 사라졌으니 모든 깊이를 잡는 이 한 줄이면 된다.
+.claude/
+# 서명·접속 키 — 커밋되면 되돌릴 수 없다. 지금 키들은 리포 **바깥**(워크스페이스
+# 루트)에 있어 커밋된 적이 없지만, 누가 안으로 옮겨도 막히도록 패턴을 박아 둔다.
+# 업데이터 개인키를 잃으면 배포된 전 사용자가 자동 업데이트에서 영구 이탈한다
+# (복구 경로 없음 — DEPLOYMENT.md §1.6 백업 절차 참조).
+*.key
+*.pem
+*.p12
+*.pfx
+
+# uv 캐시 락파일 — 로컬 테스트 실행(`uv run`)이 만든다. 정본 의존성은
+# pyproject.toml 이고, 이 락은 기기별 파생물이라 추적하지 않는다.
+uv.lock
+
+# 평가·리허설 부산물 — 모델 가중치 수백 MB 가 여기 앉는다.
+# 이 워킹트리는 세션 공유라 남의 `git add -A` 가 이것을 집는다.
+.cache/
+work/
+
+# design-hub capture PNGs are build products of scripts/capture_*.mjs; the manifests are committed
+design-hub/reports/captures/**/*.png

vinc_langgraph-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,59 @@
+# 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/constraints-min.txt

@@ -0,0 +1,4 @@
+# Lowest supported framework versions; CI installs and tests this set separately.
+langgraph==1.0.0
+langchain==1.0.0
+langchain-core==1.0.0

vinc_langgraph-0.1.0/examples/approve_then_record.py

@@ -0,0 +1,70 @@
+"""A review graph that reads Vinc, stops for a person, and records only what was approved.
+
+    context -> review -> approve (interrupt) -> record
+
+Run it against your own graph with two keys: a read-only key for the reading
+nodes and a write key for the recording node only.
+
+    VINC_API_KEY=vinc_ro_...  VINC_WRITE_KEY=vinc_sk_...  python approve_then_record.py
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, TypedDict
+
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.graph import END, START, StateGraph
+from langgraph.types import Command, interrupt
+from vinc_client import VincClient
+
+from vinc_langgraph import get_vinc_context, record_episode
+
+
+class ReviewState(TypedDict, total=False):
+    question: str
+    context: str | None
+    draft: str
+    approved: bool
+    about: list[str]
+    written: dict[str, Any] | None
+
+
+def build_graph(reader: VincClient, writer: VincClient, review=None):
+    """``review`` turns (question, context) into a draft; a model call in real use."""
+    review = review or (lambda question, context: f"Reviewed: {question}")
+
+    def context_node(state: ReviewState) -> ReviewState:
+        return {"context": get_vinc_context(reader, state["question"])}
+
+    def review_node(state: ReviewState) -> ReviewState:
+        return {"draft": review(state["question"], state.get("context"))}
+
+    def approve_node(state: ReviewState) -> ReviewState:
+        # 사람이 재개할 때까지 여기서 멈춘다. 재개 값이 참일 때만 기록한다.
+        return {"approved": bool(interrupt({"draft": state["draft"]}))}
+
+    def record_node(state: ReviewState) -> ReviewState:
+        if not state.get("approved"):
+            return {"written": None}
+        return {"written": record_episode(writer, state["draft"], about=state.get("about") or [])}
+
+    graph = StateGraph(ReviewState)
+    graph.add_node("context", context_node)
+    graph.add_node("review", review_node)
+    graph.add_node("approve", approve_node)
+    graph.add_node("record", record_node)
+    graph.add_edge(START, "context")
+    graph.add_edge("context", "review")
+    graph.add_edge("review", "approve")
+    graph.add_edge("approve", "record")
+    graph.add_edge("record", END)
+    return graph.compile(checkpointer=InMemorySaver())
+
+
+if __name__ == "__main__":
+    app = build_graph(VincClient(), VincClient(os.environ["VINC_WRITE_KEY"]))
+    config = {"configurable": {"thread_id": "review-1"}}
+    paused = app.invoke({"question": "Does the new secondary button meet contrast on dark?",
+                         "about": []}, config)
+    print("waiting for approval:", paused["__interrupt__"][0].value)
+    print(app.invoke(Command(resume=input("approve? [y/N] ").lower() == "y"), config))

vinc_langgraph-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vinc-langgraph"
+version = "0.1.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Vinculums" }]
+keywords = ["vinc", "langgraph", "langchain", "middleware", "knowledge-graph", "memory"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["vinc-client>=0.1,<0.2", "langgraph>=1.0", "langchain-core>=1.0"]
+
+[project.optional-dependencies]
+agents = ["langchain>=1.0"]
+test = ["pytest>=8", "langchain>=1.0"]
+
+[project.urls]
+Homepage = "https://vincs.io"
+Documentation = "https://vincs.io/docs/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vinc_langgraph"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vinc_langgraph-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_langgraph.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import asyncio
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+from langgraph.types import Command
+
+from vinc_client import AsyncVincClient, VincAuthError, VincClient
+from vinc_langgraph import (aget_vinc_context, build_system_message, create_vinc_tools,
+                            get_vinc_context, last_user_text, record_episode)
+
+RO_KEY = "vinc_ro_" + "a" * 32
+SK_KEY = "vinc_sk_" + "b" * 32
+RESOLVED = {
+    "status": "resolved",
+    "node": {"id": "decision:tokens-are-oklch", "title": "Colour tokens are stored as OKLCH"},
+    "one_liner": "Tokens keep OKLCH so contrast can be checked per theme.",
+    "grounds": ["decision:tokens-are-oklch"],
+}
+DOWN = (503, {"error": {"code": "upstream_unavailable", "message": "down"}})
+
+
+class Routes:
+    def __init__(self, routes: dict[tuple[str, str], Any]):
+        self.routes = routes
+        self.seen: list[httpx.Request] = []
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.seen.append(request)
+        answer = self.routes.get((request.method, request.url.path))
+        if answer is None:
+            return httpx.Response(404, json={"error": {"code": "route_not_found", "message": ""}})
+        status, body = answer if isinstance(answer, tuple) else (200, answer)
+        return httpx.Response(status, json=body)
+
+    def paths(self) -> list[str]:
+        return [r.url.path for r in self.seen]
+
+
+def sync_client(routes: Routes, key: str = RO_KEY) -> VincClient:
+    return VincClient(key, transport=httpx.MockTransport(routes))
+
+
+def async_client(routes: Routes, key: str = RO_KEY) -> AsyncVincClient:
+    return AsyncVincClient(key, transport=httpx.MockTransport(routes))
+
+
+class RecordingModel(BaseChatModel):
+    """Answers "ok" and keeps every message list it was given."""
+
+    calls: list = []
+
+    @property
+    def _llm_type(self) -> str:
+        return "recording"
+
+    def _generate(self, messages, stop=None, run_manager=None, **kwargs) -> ChatResult:
+        self.calls.append(list(messages))
+        return ChatResult(generations=[ChatGeneration(message=AIMessage(content="ok"))])
+
+    def system_text(self) -> str:
+        first = self.calls[-1][0]
+        return first.text if isinstance(first, SystemMessage) else ""
+
+
+# ── 헬퍼 ───────────────────────────────────────────────────────────────────────
+
+def test_last_user_text_takes_the_newest_human_message():
+    msgs = [HumanMessage("first"), AIMessage("answer"), HumanMessage("the follow-up")]
+    assert last_user_text(msgs) == "the follow-up"
+    assert last_user_text("  plain  ") == "plain"
+    assert last_user_text([AIMessage("only ai")]) == ""
+
+
+def test_get_vinc_context_sync_and_async():
+    routes = Routes({("POST", "/v1/brief"): RESOLVED})
+    assert "decision:tokens-are-oklch" in get_vinc_context(sync_client(routes),
+                                                           [HumanMessage("why oklch tokens")])
+    block = asyncio.run(aget_vinc_context(async_client(routes), "why oklch tokens"))
+    assert "decision:tokens-are-oklch" in block
+
+
+def test_context_is_none_when_vinc_is_down():
+    routes = Routes({("POST", "/v1/brief"): DOWN})
+    assert get_vinc_context(sync_client(routes), "why oklch tokens") is None
+
+
+def test_build_system_message_appends_and_keeps():
+    assert build_system_message(None) is None
+    base = SystemMessage(content="You review design changes.")
+    assert build_system_message(None, base) is base
+    fresh = build_system_message("BLOCK")
+    assert fresh.text == "BLOCK"
+    joined = build_system_message("BLOCK", "You review design changes.")
+    assert "You review design changes." in joined.text and "BLOCK" in joined.text
+
+
+# ── 도구 ───────────────────────────────────────────────────────────────────────
+
+def test_tools_are_read_only_and_work_sync_and_async():
+    routes = Routes({("POST", "/v1/brief"): RESOLVED,
+                     ("POST", "/v1/search"): {"rows": [], "node_hits": [
+                         {"id": "concept:spacing", "title": "Spacing", "kind": "concept"}]}})
+    tools = {t.name: t for t in create_vinc_tools(sync_client(routes), async_client(routes))}
+    assert sorted(tools) == ["vinc_brief", "vinc_search"]
+    assert "decision:tokens-are-oklch" in tools["vinc_brief"].invoke({"query": "tokens"})
+    out = asyncio.run(tools["vinc_search"].ainvoke({"query": "spacing", "limit": 2}))
+    assert "concept:spacing" in out and json.loads(routes.seen[-1].content)["limit"] == 2
+
+
+def test_tools_degrade_to_a_sentence_when_vinc_is_down():
+    routes = Routes({("POST", "/v1/brief"): DOWN})
+    brief = {t.name: t for t in create_vinc_tools(sync_client(routes))}["vinc_brief"]
+    assert "not available" in brief.invoke({"query": "tokens"})
+
+
+def test_tools_need_a_client():
+    with pytest.raises(ValueError):
+        create_vinc_tools()
+
+
+# ── 쓰기 ───────────────────────────────────────────────────────────────────────
+
+def test_record_episode_needs_a_write_key():
+    routes = Routes({})
+    with pytest.raises(VincAuthError):
+        record_episode(sync_client(routes), "Merged", about=["decision:tokens-are-oklch"])
+    assert routes.seen == []
+
+
+# ── create_agent 미들웨어 ──────────────────────────────────────────────────────
+
+def make_agent(middleware):
+    from langchain.agents import create_agent
+    model = RecordingModel()
+    model.calls = []
+    return create_agent(model, system_prompt="You review design changes.",
+                        middleware=[middleware]), model
+
+
+def test_middleware_puts_the_block_in_the_system_message():
+    from vinc_langgraph import VincContextMiddleware
+    routes = Routes({("POST", "/v1/brief"): RESOLVED})
+    agent, model = make_agent(VincContextMiddleware(sync_client(routes)))
+    out = agent.invoke({"messages": [HumanMessage("Why are colour tokens OKLCH?")]})
+    assert out["messages"][-1].content == "ok"
+    system = model.system_text()
+    assert "You review design changes." in system and "decision:tokens-are-oklch" in system
+    assert routes.paths() == ["/v1/brief"]
+
+
+def test_middleware_reuses_the_answer_for_the_same_question():
+    from vinc_langgraph import VincContextMiddleware
+    routes = Routes({("POST", "/v1/brief"): RESOLVED})
+    agent, _ = make_agent(VincContextMiddleware(sync_client(routes)))
+    for _ in range(2):
+        agent.invoke({"messages": [HumanMessage("Why are colour tokens OKLCH?")]})
+    assert routes.paths() == ["/v1/brief"]
+
+
+def test_middleware_async_path_and_vinc_down():
+    from vinc_langgraph import VincContextMiddleware
+    routes = Routes({("POST", "/v1/brief"): DOWN})
+    agent, model = make_agent(VincContextMiddleware(async_client=async_client(routes)))
+    out = asyncio.run(agent.ainvoke({"messages": [HumanMessage("why are tokens oklch")]}))
+    assert out["messages"][-1].content == "ok"
+    assert "DATA" not in model.system_text()
+
+
+# ── 예제 그래프: interrupt 로 멈추고, 승인한 것만 쓴다 ─────────────────────────
+
+def load_example():
+    path = Path(__file__).resolve().parents[1] / "examples" / "approve_then_record.py"
+    spec = importlib.util.spec_from_file_location("approve_then_record", path)
+    module = importlib.util.module_from_spec(spec)
+    # 상태 TypedDict 의 주석을 LangGraph 가 모듈 전역으로 푼다 — 등록 안 하면 못 찾는다.
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+@pytest.mark.parametrize("approved", [True, False])
+def test_example_graph_writes_only_after_approval(approved):
+    reads = Routes({("POST", "/v1/brief"): RESOLVED})
+    writes = Routes({("GET", "/v1/nodes/decision:tokens-are-oklch"): RESOLVED,
+                     ("POST", "/v1/fragments"): {"warnings": [], "stored": []}})
+    app = load_example().build_graph(sync_client(reads), sync_client(writes, SK_KEY))
+    config = {"configurable": {"thread_id": f"t-{approved}"}}
+    paused = app.invoke({"question": "Does the secondary button meet contrast on dark?",
+                         "about": ["decision:tokens-are-oklch"]}, config)
+    assert "__interrupt__" in paused and writes.seen == []
+    done = app.invoke(Command(resume=approved), config)
+    if approved:
+        assert writes.paths() == ["/v1/nodes/decision:tokens-are-oklch", "/v1/fragments"]
+        assert done["written"] is not None
+    else:
+        assert writes.seen == [] and done["written"] is None
+    assert reads.paths() == ["/v1/brief"]