vinc-client 0.1.0__tar.gz

vinc_client-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_client-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: vinc-client
+Version: 0.1.0
+Summary: Python client for the Vinc REST v1 API: read a knowledge graph you share with AI, and write episodes to it on purpose.
+Project-URL: Homepage, https://vincs.io
+Project-URL: Documentation, https://vincs.io/docs/
+Author: Vinculums
+License-Expression: MIT
+Keywords: agents,knowledge-graph,memory,rest,vinc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: anyio>=4; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# vinc-client
+
+Python client for the [Vinc](https://vincs.io) REST v1 API. Vinc is a knowledge graph you share with AI: decisions, records and documents your team wrote, with the reasons attached.
+
+This package reads that graph for an agent and writes to it only when your code asks. It is the base of `vinc-langgraph` and `vinc-agent-framework`.
+
+## Install
+
+```bash
+pip install vinc-client
+```
+
+## Keys and spaces
+
+Create a member key in your Vinc account. A `vinc_ro_` key reads; a `vinc_sk_` key can also write. Use a read-only key wherever the agent only needs context.
+
+```python
+from vinc_client import VincClient
+
+vinc = VincClient()                      # reads VINC_API_KEY
+team = VincClient(space="<team id>")     # a team's shared graph instead of your personal one
+```
+
+## Context for a model turn
+
+```python
+block = vinc.get_context("Why are our colour tokens stored as OKLCH?")
+if block:
+    system_prompt += "\n\n" + block
+```
+
+`get_context` makes one call per turn. It returns `None` when nothing matched, and also when Vinc is unreachable or the daily limit is spent, so the model call goes on without it. A key or space problem raises, because it will not fix itself.
+
+The block is fenced and introduced as data, not instructions: text in the graph can be written by anyone with access to it, so the model is told to treat it as reference material.
+
+## Reading
+
+```python
+vinc.brief("release checklist")          # one node, its excerpts and relations
+vinc.search("spacing scale", limit=10)   # text and meaning search
+vinc.recall(domain="vinc/design")        # episode timeline, newest first
+vinc.node("decision:tokens-are-oklch")   # one node by id
+```
+
+## Writing, on purpose
+
+Nothing in this package writes because a conversation happened. Record an episode when a person approved what the agent did:
+
+```python
+vinc = VincClient(api_key=WRITE_KEY)     # vinc_sk_
+vinc.record_episode(
+    "Fixed contrast on the dark secondary button",
+    summary="Token text-secondary moved to pass 4.5:1 on the dark surface.",
+    about=["decision:tokens-are-oklch"],
+)
+```
+
+Every `about` id is read before the write, so a typo raises `VincNotFound` instead of creating an empty node.
+
+## Errors
+
+| Class | Meaning |
+|---|---|
+| `VincAuthError` | missing, malformed, refused or read-only key; configuration is wrong |
+| `VincNotFound` | the node, document or space does not exist for this key |
+| `VincInvalidArgument` | the request was malformed or refused (for example a topic limit) |
+| `VincQuotaExceeded` | the daily limit is spent; `retry_after` is in seconds |
+| `VincUnavailable` | network or server failure; for a write, check `details["write_may_have_applied"]` |
+| `VincPartialWrite` | part of a write was skipped; `result` holds what the server said |
+
+## Async
+
+`AsyncVincClient` has the same methods, awaited.
+
+## License
+
+MIT

vinc_client-0.1.0/README.md

@@ -0,0 +1,77 @@
+# vinc-client
+
+Python client for the [Vinc](https://vincs.io) REST v1 API. Vinc is a knowledge graph you share with AI: decisions, records and documents your team wrote, with the reasons attached.
+
+This package reads that graph for an agent and writes to it only when your code asks. It is the base of `vinc-langgraph` and `vinc-agent-framework`.
+
+## Install
+
+```bash
+pip install vinc-client
+```
+
+## Keys and spaces
+
+Create a member key in your Vinc account. A `vinc_ro_` key reads; a `vinc_sk_` key can also write. Use a read-only key wherever the agent only needs context.
+
+```python
+from vinc_client import VincClient
+
+vinc = VincClient()                      # reads VINC_API_KEY
+team = VincClient(space="<team id>")     # a team's shared graph instead of your personal one
+```
+
+## Context for a model turn
+
+```python
+block = vinc.get_context("Why are our colour tokens stored as OKLCH?")
+if block:
+    system_prompt += "\n\n" + block
+```
+
+`get_context` makes one call per turn. It returns `None` when nothing matched, and also when Vinc is unreachable or the daily limit is spent, so the model call goes on without it. A key or space problem raises, because it will not fix itself.
+
+The block is fenced and introduced as data, not instructions: text in the graph can be written by anyone with access to it, so the model is told to treat it as reference material.
+
+## Reading
+
+```python
+vinc.brief("release checklist")          # one node, its excerpts and relations
+vinc.search("spacing scale", limit=10)   # text and meaning search
+vinc.recall(domain="vinc/design")        # episode timeline, newest first
+vinc.node("decision:tokens-are-oklch")   # one node by id
+```
+
+## Writing, on purpose
+
+Nothing in this package writes because a conversation happened. Record an episode when a person approved what the agent did:
+
+```python
+vinc = VincClient(api_key=WRITE_KEY)     # vinc_sk_
+vinc.record_episode(
+    "Fixed contrast on the dark secondary button",
+    summary="Token text-secondary moved to pass 4.5:1 on the dark surface.",
+    about=["decision:tokens-are-oklch"],
+)
+```
+
+Every `about` id is read before the write, so a typo raises `VincNotFound` instead of creating an empty node.
+
+## Errors
+
+| Class | Meaning |
+|---|---|
+| `VincAuthError` | missing, malformed, refused or read-only key; configuration is wrong |
+| `VincNotFound` | the node, document or space does not exist for this key |
+| `VincInvalidArgument` | the request was malformed or refused (for example a topic limit) |
+| `VincQuotaExceeded` | the daily limit is spent; `retry_after` is in seconds |
+| `VincUnavailable` | network or server failure; for a write, check `details["write_may_have_applied"]` |
+| `VincPartialWrite` | part of a write was skipped; `result` holds what the server said |
+
+## Async
+
+`AsyncVincClient` has the same methods, awaited.
+
+## License
+
+MIT

vinc_client-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vinc-client"
+version = "0.1.0"
+description = "Python client for the Vinc REST v1 API: read a knowledge graph you share with AI, and write episodes to it on purpose."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Vinculums" }]
+keywords = ["vinc", "knowledge-graph", "agents", "memory", "rest"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "anyio>=4"]
+
+[project.urls]
+Homepage = "https://vincs.io"
+Documentation = "https://vincs.io/docs/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vinc_client"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

vinc_client-0.1.0/src/vinc_client/__init__.py

@@ -0,0 +1,18 @@
+"""Python client for the Vinc REST v1 API.
+
+Design and scope: [[vinc.plan.framework-integration-packages-2026-09-28]].
+"""
+__version__ = "0.1.0"
+
+from .client import AsyncVincClient, VincClient  # noqa: E402
+from .context import BOUNDARY, fence, format_answer, format_brief, format_search  # noqa: E402
+from .episode import build_episode_fragment  # noqa: E402
+from .errors import (VincAuthError, VincError, VincInvalidArgument, VincNotFound,  # noqa: E402
+                     VincPartialWrite, VincQuotaExceeded, VincUnavailable)
+
+__all__ = [
+    "__version__", "VincClient", "AsyncVincClient",
+    "BOUNDARY", "fence", "format_answer", "format_brief", "format_search", "build_episode_fragment",
+    "VincError", "VincAuthError", "VincNotFound", "VincInvalidArgument",
+    "VincQuotaExceeded", "VincUnavailable", "VincPartialWrite",
+]

vinc_client-0.1.0/src/vinc_client/client.py

@@ -0,0 +1,384 @@
+"""Synchronous and asynchronous clients for the Vinc REST v1 API.
+
+Both read a member key (``vinc_sk_`` full, ``vinc_ro_`` read only) and act on
+one space: the personal graph, or a team by its id. Nothing here writes on its
+own; the only write paths are ``ingest`` and ``record_episode``, and both are
+explicit calls.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+from urllib.parse import quote, urlparse
+
+import httpx
+
+from . import __version__
+from .context import DEFAULT_MAX_CHARS, format_answer
+from .episode import build_episode_fragment, check_about
+from .errors import (VincAuthError, VincError, VincInvalidArgument, VincPartialWrite,
+                     VincQuotaExceeded, VincUnavailable, error_class)
+
+log = logging.getLogger("vinc_client")
+
+DEFAULT_BASE_URL = "https://mcp.vincs.io"
+KEY_PREFIXES = ("vinc_sk_", "vinc_ro_")
+_LOOPBACK = frozenset({"localhost", "127.0.0.1", "::1"})
+#: 브리프가 한 노드로 못 좁힌 두 경우. 자연어 질문은 동점(choose)이 흔하다(라이브 실측).
+_WIDEN = ("none", "choose")
+_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+
+def resolve_key(api_key: str | None) -> str:
+    key = (api_key or os.environ.get("VINC_API_KEY") or "").strip()
+    if not key:
+        raise VincAuthError("not_authenticated", "Pass api_key or set VINC_API_KEY.")
+    if not key.startswith(KEY_PREFIXES):
+        raise VincAuthError("not_authenticated",
+                            "A Vinc member key starts with vinc_sk_ or vinc_ro_.")
+    return key
+
+
+def resolve_base_url(base_url: str | None) -> str:
+    base = (base_url or os.environ.get("VINC_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+    parsed = urlparse(base)
+    # http 는 루프백만 — 키가 평문으로 네트워크를 지나지 않게. CLI 와 같은 규칙.
+    if parsed.scheme == "https" or (parsed.scheme == "http" and parsed.hostname in _LOOPBACK):
+        return base
+    raise VincInvalidArgument("invalid_argument",
+                              "The API URL must use https (http is allowed only for localhost).")
+
+
+def normalize_space(space: str | None) -> str:
+    value = (space or "personal").strip().lower()
+    if value != "personal" and not _UUID.fullmatch(value):
+        raise ValueError("space must be 'personal' or a team id (a UUID)")
+    return value
+
+
+def _segment(value: str) -> str:
+    # `.`·`..` 는 경로 정규화가 되감는 조각이라 그대로 보내면 다른 라우트로 간다.
+    text = quote(str(value), safe="")
+    return text.replace(".", "%2E") if text in (".", "..") else text
+
+
+def _drop_none(values: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in values.items() if v is not None}
+
+
+@dataclass
+class _Call:
+    method: str
+    path: str
+    params: dict[str, Any] = field(default_factory=dict)
+    body: dict[str, Any] | None = None
+    space: str | None = None
+
+
+def _retry_after(response: httpx.Response, details: dict[str, Any]) -> float | None:
+    raw = response.headers.get("Retry-After") or details.get("retry_after_s")
+    try:
+        return float(raw) if raw not in (None, "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _parse(response: httpx.Response) -> dict[str, Any]:
+    status = response.status_code
+    if 300 <= status < 400:
+        # 리다이렉트를 따라가면 Authorization 이 그 주소로 가고, POST 쓰기가 본문 없는
+        # GET 으로 바뀌어 성공처럼 보인다. 따라가지 않고 실패로 말한다.
+        raise VincUnavailable("upstream_unavailable",
+                              f"The API answered a redirect (HTTP {status}); it was not followed.",
+                              status=status)
+    try:
+        payload = response.json()
+    except ValueError:
+        payload = None
+    if 200 <= status < 300:
+        if not isinstance(payload, dict):
+            raise VincUnavailable("upstream_unavailable", "The API returned invalid JSON.",
+                                  status=status)
+        return payload
+    raw = payload.get("error") if isinstance(payload, dict) else None
+    error: dict[str, Any] = raw if isinstance(raw, dict) else {
+        "code": "upstream_unavailable" if status >= 500 else "http_error",
+        "message": f"HTTP {status}"}
+    raw_details = error.get("details")
+    details: dict[str, Any] = raw_details if isinstance(raw_details, dict) else {}
+    raise error_class(status)(
+        str(error.get("code") or "http_error"), str(error.get("message") or ""),
+        status=status, request_id=str(error.get("request_id") or
+                                      response.headers.get("Vinc-Request-Id") or ""),
+        details=details, retry_after=_retry_after(response, details))
+
+
+def _raise_if_partial(result: dict[str, Any]) -> dict[str, Any]:
+    if result.get("partial"):
+        raise VincPartialWrite("The write was accepted only in part; read result['warnings'].",
+                               result)
+    return result
+
+
+class _Base:
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None,
+                 space: str | None = None, timeout: float = 30.0) -> None:
+        self._key = resolve_key(api_key)
+        self.base_url = resolve_base_url(base_url)
+        self.space = normalize_space(space)
+        self.timeout = timeout
+
+    @property
+    def read_only(self) -> bool:
+        """True for a ``vinc_ro_`` key: every write is refused before it is sent."""
+        return self._key.startswith("vinc_ro_")
+
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._key}", "Accept": "application/json",
+                "User-Agent": f"vinc-client/{__version__}"}
+
+    def _request_args(self, call: _Call) -> dict[str, Any]:
+        space = normalize_space(call.space) if call.space is not None else self.space
+        params = {k: (",".join(v) if isinstance(v, (list, tuple)) else
+                      ("true" if v else "false") if isinstance(v, bool) else v)
+                  for k, v in call.params.items() if v is not None}
+        if space != "personal":
+            params["space"] = space
+        args: dict[str, Any] = {"method": call.method, "url": call.path, "params": params}
+        if call.body is not None:
+            args["json"] = call.body
+        return args
+
+    def _require_write_key(self) -> None:
+        if self.read_only:
+            raise VincAuthError("read_only_key",
+                                "This is a read-only key (vinc_ro_); writing needs a vinc_sk_ key.")
+
+    # ── 라우트 한 줄씩. 경로·필드 이름은 vinc_mcp/openapi_v1.json 과 대조된다 ──
+    @staticmethod
+    def _whoami(space) -> _Call:
+        return _Call("GET", "/v1/me", space=space)
+
+    @staticmethod
+    def _brief(query, max_excerpts, historical, space) -> _Call:
+        return _Call("POST", "/v1/brief", body=_drop_none(
+            {"query": query, "max_excerpts": max_excerpts, "historical": historical}), space=space)
+
+    @staticmethod
+    def _node(node_id, space) -> _Call:
+        return _Call("GET", f"/v1/nodes/{_segment(node_id)}", space=space)
+
+    @staticmethod
+    def _search(query, limit, cursor, detail, historical, space) -> _Call:
+        return _Call("POST", "/v1/search", body=_drop_none(
+            {"query": query, "limit": limit, "cursor": cursor, "detail": detail,
+             "historical": historical}), space=space)
+
+    @staticmethod
+    def _recall(domain, tags, limit, cursor, space) -> _Call:
+        return _Call("GET", "/v1/episodes", params={
+            "domain": domain, "tags": list(tags) if tags else None,
+            "limit": limit, "cursor": cursor}, space=space)
+
+    @staticmethod
+    def _ingest(nodes, edges, space) -> _Call:
+        return _Call("POST", "/v1/fragments",
+                     body={"nodes": list(nodes), "edges": list(edges or [])}, space=space)
+
+
+class VincClient(_Base):
+    """Blocking client. Use as a context manager or call ``close()``."""
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None,
+                 space: str | None = None, timeout: float = 30.0,
+                 transport: httpx.BaseTransport | None = None) -> None:
+        super().__init__(api_key, base_url=base_url, space=space, timeout=timeout)
+        self._http = httpx.Client(base_url=self.base_url, headers=self._headers(),
+                                  timeout=timeout, follow_redirects=False, transport=transport)
+
+    def __enter__(self) -> "VincClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _send(self, call: _Call) -> dict[str, Any]:
+        try:
+            response = self._http.request(**self._request_args(call))
+        except httpx.TimeoutException as exc:
+            raise VincUnavailable("upstream_unavailable", f"Timed out: {exc}") from None
+        except httpx.TransportError as exc:
+            raise VincUnavailable("upstream_unavailable",
+                                  f"The API is unreachable: {type(exc).__name__}") from None
+        return _parse(response)
+
+    def whoami(self, *, space: str | None = None) -> dict[str, Any]:
+        """``GET /v1/me``: the key's owner, plan and the teams it can reach."""
+        return self._send(self._whoami(space))
+
+    def brief(self, query: str, *, max_excerpts: int | None = None,
+              historical: bool | None = None, space: str | None = None) -> dict[str, Any]:
+        """``POST /v1/brief``: resolve a question (or a node id) to one node with its material."""
+        return self._send(self._brief(query, max_excerpts, historical, space))
+
+    def node(self, node_id: str, *, space: str | None = None) -> dict[str, Any]:
+        """``GET /v1/nodes/{id}``: read one node by id. Raises ``VincNotFound`` if absent."""
+        return self._send(self._node(node_id, space))
+
+    def search(self, query: str, *, limit: int | None = None, cursor: str | None = None,
+               detail: str | None = None, historical: bool | None = None,
+               space: str | None = None) -> dict[str, Any]:
+        """``POST /v1/search``: hybrid text and meaning search, paged by ``cursor``."""
+        return self._send(self._search(query, limit, cursor, detail, historical, space))
+
+    def recall(self, *, domain: str | None = None, tags: Iterable[str] | None = None,
+               limit: int | None = None, cursor: str | None = None,
+               space: str | None = None) -> dict[str, Any]:
+        """``GET /v1/episodes``: the episode timeline, newest first."""
+        return self._send(self._recall(domain, tags, limit, cursor, space))
+
+    def ingest(self, nodes: Iterable[dict[str, Any]], edges: Iterable[dict[str, Any]] | None = None,
+               *, space: str | None = None) -> dict[str, Any]:
+        """``POST /v1/fragments``: merge nodes and edges by id.
+
+        ``props`` sent for a node replace its stored props whole; read them first
+        and send the merged dict. Raises ``VincPartialWrite`` when part was skipped.
+        """
+        self._require_write_key()
+        return _raise_if_partial(self._send(self._ingest(nodes, edges, space)))
+
+    def get_context(self, query: str, *, search_fallback: bool = False,
+                    max_chars: int = DEFAULT_MAX_CHARS, max_excerpts: int = 3,
+                    min_query_chars: int = 3, space: str | None = None) -> str | None:
+        """A fenced context block for ``query``, or ``None``.
+
+        One call per turn, two with ``search_fallback`` when the brief found
+        nothing or several nodes tied (a natural question often ties). When Vinc is unavailable or the quota is spent this logs a
+        warning and returns ``None``: the caller's model call goes on without it.
+        A key or space problem still raises, because it will not fix itself.
+        """
+        text = (query or "").strip()
+        if len(text) < min_query_chars:
+            return None
+        try:
+            brief = self.brief(text, max_excerpts=max_excerpts, space=space)
+            search = (self.search(text, limit=5, space=space)
+                      if search_fallback and brief.get("status") in _WIDEN else None)
+            return format_answer(brief, search, max_chars=max_chars)
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            log.warning("vinc context skipped for this turn: %s (retry_after=%s)",
+                        exc, exc.retry_after)
+            return None
+
+    def record_episode(self, title: str, *, summary: str = "", about: Iterable[str] = (),
+                       date: str | None = None, domain: str | None = None,
+                       tags: Iterable[str] | None = None, episode_id: str | None = None,
+                       space: str | None = None) -> dict[str, Any]:
+        """Write one Episode, ``about`` existing concepts or decisions.
+
+        Call it on purpose, after a person approved what happened; nothing in
+        this package calls it for you. Every ``about`` id is read first, so a
+        typo raises ``VincNotFound`` instead of creating an empty node.
+        """
+        self._require_write_key()
+        targets = check_about(about)
+        for target in targets:
+            self.node(target, space=space)
+        fragment = build_episode_fragment(title, summary=summary, about=targets, date=date,
+                                          domain=domain, tags=tags, episode_id=episode_id)
+        return self.ingest(fragment["nodes"], fragment["edges"], space=space)
+
+
+class AsyncVincClient(_Base):
+    """Async twin of :class:`VincClient`; same methods, awaited."""
+
+    def __init__(self, api_key: str | None = None, *, base_url: str | None = None,
+                 space: str | None = None, timeout: float = 30.0,
+                 transport: httpx.AsyncBaseTransport | None = None) -> None:
+        super().__init__(api_key, base_url=base_url, space=space, timeout=timeout)
+        self._http = httpx.AsyncClient(base_url=self.base_url, headers=self._headers(),
+                                       timeout=timeout, follow_redirects=False,
+                                       transport=transport)
+
+    async def __aenter__(self) -> "AsyncVincClient":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _send(self, call: _Call) -> dict[str, Any]:
+        try:
+            response = await self._http.request(**self._request_args(call))
+        except httpx.TimeoutException as exc:
+            raise VincUnavailable("upstream_unavailable", f"Timed out: {exc}") from None
+        except httpx.TransportError as exc:
+            raise VincUnavailable("upstream_unavailable",
+                                  f"The API is unreachable: {type(exc).__name__}") from None
+        return _parse(response)
+
+    async def whoami(self, *, space: str | None = None) -> dict[str, Any]:
+        return await self._send(self._whoami(space))
+
+    async def brief(self, query: str, *, max_excerpts: int | None = None,
+                    historical: bool | None = None, space: str | None = None) -> dict[str, Any]:
+        return await self._send(self._brief(query, max_excerpts, historical, space))
+
+    async def node(self, node_id: str, *, space: str | None = None) -> dict[str, Any]:
+        return await self._send(self._node(node_id, space))
+
+    async def search(self, query: str, *, limit: int | None = None, cursor: str | None = None,
+                     detail: str | None = None, historical: bool | None = None,
+                     space: str | None = None) -> dict[str, Any]:
+        return await self._send(self._search(query, limit, cursor, detail, historical, space))
+
+    async def recall(self, *, domain: str | None = None, tags: Iterable[str] | None = None,
+                     limit: int | None = None, cursor: str | None = None,
+                     space: str | None = None) -> dict[str, Any]:
+        return await self._send(self._recall(domain, tags, limit, cursor, space))
+
+    async def ingest(self, nodes: Iterable[dict[str, Any]],
+                     edges: Iterable[dict[str, Any]] | None = None, *,
+                     space: str | None = None) -> dict[str, Any]:
+        self._require_write_key()
+        return _raise_if_partial(await self._send(self._ingest(nodes, edges, space)))
+
+    async def get_context(self, query: str, *, search_fallback: bool = False,
+                          max_chars: int = DEFAULT_MAX_CHARS, max_excerpts: int = 3,
+                          min_query_chars: int = 3, space: str | None = None) -> str | None:
+        text = (query or "").strip()
+        if len(text) < min_query_chars:
+            return None
+        try:
+            brief = await self.brief(text, max_excerpts=max_excerpts, space=space)
+            search = (await self.search(text, limit=5, space=space)
+                      if search_fallback and brief.get("status") in _WIDEN else None)
+            return format_answer(brief, search, max_chars=max_chars)
+        except (VincUnavailable, VincQuotaExceeded) as exc:
+            log.warning("vinc context skipped for this turn: %s (retry_after=%s)",
+                        exc, exc.retry_after)
+            return None
+
+    async def record_episode(self, title: str, *, summary: str = "", about: Iterable[str] = (),
+                             date: str | None = None, domain: str | None = None,
+                             tags: Iterable[str] | None = None, episode_id: str | None = None,
+                             space: str | None = None) -> dict[str, Any]:
+        self._require_write_key()
+        targets = check_about(about)
+        for target in targets:
+            await self.node(target, space=space)
+        fragment = build_episode_fragment(title, summary=summary, about=targets, date=date,
+                                          domain=domain, tags=tags, episode_id=episode_id)
+        return await self.ingest(fragment["nodes"], fragment["edges"], space=space)
+
+
+__all__ = ["VincClient", "AsyncVincClient", "VincError", "resolve_key", "resolve_base_url",
+           "normalize_space", "DEFAULT_BASE_URL"]