kimetsu 0.1.0__tar.gz

kimetsu-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

kimetsu-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: publish
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kimetsu-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.superpowers/

kimetsu-0.1.0/LICENSE

@@ -0,0 +1,150 @@
+Licensed under either of MIT or Apache-2.0 at your option.
+
+================================================================================
+MIT License
+================================================================================
+
+Copyright (c) 2026 RodCor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+================================================================================
+
+Copyright 2026 RodCor
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of such
+entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source, and
+configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object
+code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work (an example is provided in the Appendix
+below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+   (a) You must give any other recipients of the Work or Derivative Works a
+       copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices stating
+       that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works that You
+       distribute, all copyright, patent, trademark, and attribution notices
+       from the Source form of the Work; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained within
+       such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES
+OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory shall any
+Contributor be liable to You for damages, including any direct, indirect,
+special, incidental, or consequential damages arising as a result of this
+License.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+consistent with this License.
+
+END OF TERMS AND CONDITIONS

kimetsu-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: kimetsu
+Version: 0.1.0
+Summary: Typed Python client for the Kimetsu remote brain
+Project-URL: Homepage, https://github.com/RodCor/kimetsu-py
+Project-URL: Repository, https://github.com/RodCor/kimetsu-py
+Project-URL: Main project, https://github.com/RodCor/kimetsu
+Author: Rodrigo Cordoba
+License-Expression: MIT OR Apache-2.0
+License-File: LICENSE
+Keywords: agent,kimetsu,llm,mcp,memory,sdk
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# kimetsu
+
+Typed Python client for the Kimetsu remote brain.
+
+## What it is
+
+A sync + async client over the Kimetsu remote brain's MCP JSON-RPC endpoint.
+Requires a running `kimetsu-remote` server; you supply its base URL, a bearer
+token, and the repo name.
+
+## Install
+
+```
+pip install kimetsu
+```
+
+## Quickstart (sync)
+
+```python
+from kimetsu import KimetsuClient
+
+client = KimetsuClient(base_url="https://brain.example.com", token="tok_...", repo="web")
+client.record("Use `just migrate`, never raw sqlx", tags=["db", "workflow"])
+ctx = client.context("how do we run migrations?", tags=["db"])
+print(ctx.capsules)
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+from kimetsu import AsyncKimetsuClient
+
+async def main():
+    async with AsyncKimetsuClient(base_url="https://brain.example.com", token="tok_...", repo="web") as client:
+        ctx = await client.context("how do we run migrations?", tags=["db"])
+        print(ctx.capsules)
+
+asyncio.run(main())
+```
+
+## Configuration / env vars
+
+`KIMETSU_REMOTE_URL`, `KIMETSU_REMOTE_TOKEN`, `KIMETSU_REMOTE_REPO` (used when
+the matching constructor arg is omitted). Optional `timeout` (default 30s).
+
+## API surface — method → remote tool
+
+| SDK call | Remote tool |
+| --- | --- |
+| `context` | `kimetsu_brain_context` |
+| `record` | `kimetsu_brain_record` |
+| `status` | `kimetsu_brain_status` |
+| `insights` | `kimetsu_brain_insights` |
+| `memory.search` | `kimetsu_brain_memory_search` |
+| `memory.add` | `kimetsu_brain_memory_add` |
+| `memory.list` | `kimetsu_brain_memory_list` |
+| `memory.top` | `kimetsu_brain_memory_top` |
+| `memory.accept` | `kimetsu_brain_memory_accept` |
+| `memory.reject` | `kimetsu_brain_memory_reject` |
+| `memory.invalidate` | `kimetsu_brain_memory_invalidate` |
+| `memory.blame` | `kimetsu_brain_memory_blame` (per-run citation attribution — pass a `run_id`, returns which memories that run cited) |
+| `memory.proposals` | `kimetsu_brain_memory_proposals` |
+| `memory.conflicts` | `kimetsu_brain_memory_conflicts` |
+| `memory.conflict_resolve` | `kimetsu_brain_conflict_resolve` |
+| `memory.prune` | `kimetsu_brain_prune` |
+| `config.show` | `kimetsu_brain_config_show` |
+| `models.list` | `kimetsu_brain_model_list` |
+| `benchmark.context` | `kimetsu_benchmark_context` |
+| `benchmark.record_outcome` | `kimetsu_benchmark_record_outcome` |
+
+(`AsyncKimetsuClient` mirrors every method with `await`.)
+
+Required arguments: `record` requires `tags`, `memory.add` requires `scope`,
+and `benchmark.record_outcome` requires `task` — all three raise `TypeError`
+if omitted, e.g. `client.benchmark.record_outcome(task="my-task", passed=True)`.
+
+## Errors
+
+All error types are exported from the top level: `from kimetsu import KimetsuAuthError`.
+
+`KimetsuError` (base), `KimetsuAuthError` (401/403), `KimetsuRateLimitError`
+(429, `.retry_after`), `KimetsuToolError` (JSON-RPC tool error, `.code`),
+`KimetsuProtocolError` (handshake/malformed envelope).
+
+## Typed returns
+
+`context`→`Context` (`.capsules`), `status`→`Status` (`.initialized`,
+`.accepted`), `memory.add`→`Memory` (`.id`, `.text`, `.tags`). Other methods
+return `dict`.
+
+## License
+
+MIT OR Apache-2.0.
+
+## Links
+
+Main project: https://github.com/RodCor/kimetsu

kimetsu-0.1.0/README.md

@@ -0,0 +1,98 @@
+# kimetsu
+
+Typed Python client for the Kimetsu remote brain.
+
+## What it is
+
+A sync + async client over the Kimetsu remote brain's MCP JSON-RPC endpoint.
+Requires a running `kimetsu-remote` server; you supply its base URL, a bearer
+token, and the repo name.
+
+## Install
+
+```
+pip install kimetsu
+```
+
+## Quickstart (sync)
+
+```python
+from kimetsu import KimetsuClient
+
+client = KimetsuClient(base_url="https://brain.example.com", token="tok_...", repo="web")
+client.record("Use `just migrate`, never raw sqlx", tags=["db", "workflow"])
+ctx = client.context("how do we run migrations?", tags=["db"])
+print(ctx.capsules)
+```
+
+## Quickstart (async)
+
+```python
+import asyncio
+from kimetsu import AsyncKimetsuClient
+
+async def main():
+    async with AsyncKimetsuClient(base_url="https://brain.example.com", token="tok_...", repo="web") as client:
+        ctx = await client.context("how do we run migrations?", tags=["db"])
+        print(ctx.capsules)
+
+asyncio.run(main())
+```
+
+## Configuration / env vars
+
+`KIMETSU_REMOTE_URL`, `KIMETSU_REMOTE_TOKEN`, `KIMETSU_REMOTE_REPO` (used when
+the matching constructor arg is omitted). Optional `timeout` (default 30s).
+
+## API surface — method → remote tool
+
+| SDK call | Remote tool |
+| --- | --- |
+| `context` | `kimetsu_brain_context` |
+| `record` | `kimetsu_brain_record` |
+| `status` | `kimetsu_brain_status` |
+| `insights` | `kimetsu_brain_insights` |
+| `memory.search` | `kimetsu_brain_memory_search` |
+| `memory.add` | `kimetsu_brain_memory_add` |
+| `memory.list` | `kimetsu_brain_memory_list` |
+| `memory.top` | `kimetsu_brain_memory_top` |
+| `memory.accept` | `kimetsu_brain_memory_accept` |
+| `memory.reject` | `kimetsu_brain_memory_reject` |
+| `memory.invalidate` | `kimetsu_brain_memory_invalidate` |
+| `memory.blame` | `kimetsu_brain_memory_blame` (per-run citation attribution — pass a `run_id`, returns which memories that run cited) |
+| `memory.proposals` | `kimetsu_brain_memory_proposals` |
+| `memory.conflicts` | `kimetsu_brain_memory_conflicts` |
+| `memory.conflict_resolve` | `kimetsu_brain_conflict_resolve` |
+| `memory.prune` | `kimetsu_brain_prune` |
+| `config.show` | `kimetsu_brain_config_show` |
+| `models.list` | `kimetsu_brain_model_list` |
+| `benchmark.context` | `kimetsu_benchmark_context` |
+| `benchmark.record_outcome` | `kimetsu_benchmark_record_outcome` |
+
+(`AsyncKimetsuClient` mirrors every method with `await`.)
+
+Required arguments: `record` requires `tags`, `memory.add` requires `scope`,
+and `benchmark.record_outcome` requires `task` — all three raise `TypeError`
+if omitted, e.g. `client.benchmark.record_outcome(task="my-task", passed=True)`.
+
+## Errors
+
+All error types are exported from the top level: `from kimetsu import KimetsuAuthError`.
+
+`KimetsuError` (base), `KimetsuAuthError` (401/403), `KimetsuRateLimitError`
+(429, `.retry_after`), `KimetsuToolError` (JSON-RPC tool error, `.code`),
+`KimetsuProtocolError` (handshake/malformed envelope).
+
+## Typed returns
+
+`context`→`Context` (`.capsules`), `status`→`Status` (`.initialized`,
+`.accepted`), `memory.add`→`Memory` (`.id`, `.text`, `.tags`). Other methods
+return `dict`.
+
+## License
+
+MIT OR Apache-2.0.
+
+## Links
+
+Main project: https://github.com/RodCor/kimetsu

kimetsu-0.1.0/examples/quickstart.py

@@ -0,0 +1,25 @@
+"""Minimal Kimetsu SDK example. Run against a live kimetsu-remote:
+
+    KIMETSU_REMOTE_URL=https://brain.example.com \
+    KIMETSU_REMOTE_TOKEN=tok_... \
+    KIMETSU_REMOTE_REPO=web \
+    python examples/quickstart.py
+"""
+from __future__ import annotations
+
+from kimetsu import KimetsuClient
+
+
+def main() -> None:
+    # base_url/token/repo fall back to KIMETSU_REMOTE_* env vars.
+    client = KimetsuClient()
+    client.record("Example lesson from the quickstart", tags=["example"])
+    ctx = client.context("what did the quickstart record?", tags=["example"])
+    print("capsules:", ctx.capsules)
+    hits = client.memory.search("quickstart")
+    print("search:", hits)
+    client.close()
+
+
+if __name__ == "__main__":
+    main()

kimetsu-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kimetsu"
+version = "0.1.0"
+description = "Typed Python client for the Kimetsu remote brain"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT OR Apache-2.0"
+authors = [{ name = "Rodrigo Cordoba" }]
+dependencies = ["httpx>=0.27", "pydantic>=2"]
+keywords = ["kimetsu", "memory", "mcp", "sdk", "llm", "agent"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/RodCor/kimetsu-py"
+Repository = "https://github.com/RodCor/kimetsu-py"
+"Main project" = "https://github.com/RodCor/kimetsu"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "respx>=0.21", "ruff", "mypy"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kimetsu"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.ruff]
+target-version = "py39"

kimetsu-0.1.0/src/kimetsu/__init__.py

@@ -0,0 +1,26 @@
+from .async_client import AsyncKimetsuClient
+from .client import KimetsuClient
+from .errors import (
+    KimetsuError,
+    KimetsuAuthError,
+    KimetsuRateLimitError,
+    KimetsuToolError,
+    KimetsuProtocolError,
+)
+from .models import Context, Memory, Status
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncKimetsuClient",
+    "KimetsuClient",
+    "__version__",
+    "Context",
+    "Memory",
+    "Status",
+    "KimetsuError",
+    "KimetsuAuthError",
+    "KimetsuRateLimitError",
+    "KimetsuToolError",
+    "KimetsuProtocolError",
+]

kimetsu-0.1.0/src/kimetsu/_transport.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import asyncio
+import itertools
+from typing import Any
+from typing import Dict
+from typing import Optional
+
+import httpx
+
+from .errors import KimetsuAuthError
+from .errors import KimetsuProtocolError
+from .errors import KimetsuRateLimitError
+from .errors import KimetsuToolError
+
+PROTOCOL_VERSION = "2024-11-05"
+
+
+def build_call(name: str, arguments: Dict[str, Any], *, request_id: int) -> Dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "method": "tools/call",
+            "params": {"name": name, "arguments": arguments}}
+
+
+def _build_initialize(request_id: int, protocol_version: str) -> Dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "method": "initialize",
+            "params": {"protocolVersion": protocol_version, "capabilities": {},
+                       "clientInfo": {"name": "kimetsu-py", "version": "0.1.0"}}}
+
+
+def parse_envelope(status_code: int, body: Dict[str, Any], headers: Dict[str, str]) -> Dict[str, Any]:
+    if status_code in (401, 403):
+        raise KimetsuAuthError(f"authentication failed (HTTP {status_code})")
+    if status_code == 429:
+        ra = headers.get("retry-after")
+        retry_after: Optional[float] = None
+        if ra:
+            try:
+                retry_after = float(ra)
+            except ValueError:
+                retry_after = None
+        raise KimetsuRateLimitError("rate limited (HTTP 429)", retry_after=retry_after)
+    if status_code >= 400:
+        raise KimetsuProtocolError(f"unexpected HTTP {status_code}")
+    if "error" in body:
+        err = body["error"]
+        raise KimetsuToolError(err.get("message", "tool error"), code=err.get("code"))
+    if "result" not in body:
+        raise KimetsuProtocolError("missing result in JSON-RPC envelope")
+    result: Dict[str, Any] = body["result"]
+    return result
+
+
+class SyncTransport:
+    def __init__(self, base_url: str, token: str, repo: str, *,
+                 timeout: float = 30.0, protocol_version: str = PROTOCOL_VERSION,
+                 client: Optional[httpx.Client] = None) -> None:
+        self._url = f"{base_url.rstrip('/')}/mcp/{repo}"
+        self._headers = {"authorization": f"Bearer {token}", "content-type": "application/json"}
+        self._protocol_version = protocol_version
+        self._ids = itertools.count(1)
+        self._client = client or httpx.Client(timeout=timeout)
+        self._initialized = False
+
+    def _post(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        resp = self._client.post(self._url, headers=self._headers, json=payload)
+        try:
+            body = resp.json() if resp.content else {}
+        except ValueError:
+            body = {}
+        return parse_envelope(resp.status_code, body, dict(resp.headers))
+
+    def _ensure_init(self) -> None:
+        if self._initialized:
+            return
+        result = self._post(_build_initialize(next(self._ids), self._protocol_version))
+        got = result.get("protocolVersion")
+        if got and got != self._protocol_version:
+            raise KimetsuProtocolError(f"server protocol {got} != {self._protocol_version}")
+        self._initialized = True
+
+    def call(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        self._ensure_init()
+        return self._post(build_call(name, arguments, request_id=next(self._ids)))
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncTransport:
+    def __init__(self, base_url: str, token: str, repo: str, *,
+                 timeout: float = 30.0, protocol_version: str = PROTOCOL_VERSION,
+                 client: Optional[httpx.AsyncClient] = None) -> None:
+        self._url = f"{base_url.rstrip('/')}/mcp/{repo}"
+        self._headers = {"authorization": f"Bearer {token}", "content-type": "application/json"}
+        self._protocol_version = protocol_version
+        self._ids = itertools.count(1)
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._initialized = False
+        self._init_lock = asyncio.Lock()
+
+    async def _post(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        resp = await self._client.post(self._url, headers=self._headers, json=payload)
+        try:
+            body = resp.json() if resp.content else {}
+        except ValueError:
+            body = {}
+        return parse_envelope(resp.status_code, body, dict(resp.headers))
+
+    async def _ensure_init(self) -> None:
+        if self._initialized:
+            return
+        async with self._init_lock:
+            if self._initialized:
+                return
+            result = await self._post(_build_initialize(next(self._ids), self._protocol_version))
+            got = result.get("protocolVersion")
+            if got and got != self._protocol_version:
+                raise KimetsuProtocolError(f"server protocol {got} != {self._protocol_version}")
+            self._initialized = True
+
+    async def call(self, name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+        await self._ensure_init()
+        return await self._post(build_call(name, arguments, request_id=next(self._ids)))
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

kimetsu-0.1.0/src/kimetsu/async_client.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+import os
+from ._transport import AsyncTransport
+from .client import _clean
+from .models import Context, Memory, Status
+
+
+class _AsyncMemory:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    async def search(self, query: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_search", _clean({"query": query, **kw}))
+        return res
+
+    async def add(self, text: str, *, scope: str, kind: Optional[str] = None, **kw: Any) -> Memory:
+        return Memory.model_validate(await self._t.call("kimetsu_brain_memory_add", _clean({"text": text, "scope": scope, "kind": kind, **kw})))
+
+    async def list(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_list", _clean(kw))
+        return res
+
+    async def top(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_top", _clean(kw))
+        return res
+
+    async def accept(self, proposal_id: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_accept", _clean({"proposal_id": proposal_id, **kw}))
+        return res
+
+    async def reject(self, proposal_id: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_reject", _clean({"proposal_id": proposal_id, **kw}))
+        return res
+
+    async def invalidate(self, memory_id: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_invalidate", _clean({"memory_id": memory_id, **kw}))
+        return res
+
+    async def blame(self, run_id: str, **kw: Any) -> Dict[str, Any]:
+        """Per-run citation attribution: which memories a run cited. Pass a run_id (ULID)."""
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_blame", _clean({"run_id": run_id, **kw}))
+        return res
+
+    async def proposals(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_proposals", _clean(kw))
+        return res
+
+    async def conflicts(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_memory_conflicts", _clean(kw))
+        return res
+
+    async def conflict_resolve(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_conflict_resolve", _clean(kw))
+        return res
+
+    async def prune(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_prune", _clean(kw))
+        return res
+
+
+class _AsyncConfig:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    async def show(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_config_show", _clean(kw))
+        return res
+
+
+class _AsyncModels:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    async def list(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_model_list", _clean(kw))
+        return res
+
+
+class _AsyncBenchmark:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    async def context(self, query: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_benchmark_context", _clean({"query": query, **kw}))
+        return res
+
+    async def record_outcome(self, task: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_benchmark_record_outcome", _clean({"task": task, **kw}))
+        return res
+
+
+class AsyncKimetsuClient:
+    def __init__(self, base_url: Optional[str] = None, token: Optional[str] = None,
+                 repo: Optional[str] = None, *, timeout: float = 30.0,
+                 transport: Optional[Any] = None) -> None:
+        if transport is not None:
+            self._t = transport
+        else:
+            base_url = base_url or os.environ["KIMETSU_REMOTE_URL"]
+            token = token or os.environ["KIMETSU_REMOTE_TOKEN"]
+            repo = repo or os.environ["KIMETSU_REMOTE_REPO"]
+            self._t = AsyncTransport(base_url, token, repo, timeout=timeout)
+        self.memory = _AsyncMemory(self._t)
+        self.config = _AsyncConfig(self._t)
+        self.models = _AsyncModels(self._t)
+        self.benchmark = _AsyncBenchmark(self._t)
+
+    async def context(self, query: str, *, tags: Optional[List[str]] = None, **kw: Any) -> Context:
+        return Context.model_validate(await self._t.call("kimetsu_brain_context", _clean({"query": query, "tags": tags, **kw})))
+
+    async def record(self, lesson: str, *, tags: List[str],
+                     kind: Optional[str] = None, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_record", _clean({"lesson": lesson, "tags": tags, "kind": kind, **kw}))
+        return res
+
+    async def status(self) -> Status:
+        return Status.model_validate(await self._t.call("kimetsu_brain_status", {}))
+
+    async def insights(self) -> Dict[str, Any]:
+        res: Dict[str, Any] = await self._t.call("kimetsu_brain_insights", {})
+        return res
+
+    async def aclose(self) -> None:
+        if hasattr(self._t, "aclose"):
+            await self._t.aclose()
+
+    async def __aenter__(self) -> "AsyncKimetsuClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()

kimetsu-0.1.0/src/kimetsu/client.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+import os
+from ._transport import SyncTransport
+from .models import Context, Memory, Status
+
+
+def _clean(d: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+class _Memory:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    def search(self, query: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_search", _clean({"query": query, **kw}))
+        return res
+
+    def add(self, text: str, *, scope: str, kind: Optional[str] = None, **kw: Any) -> Memory:
+        return Memory.model_validate(
+            self._t.call("kimetsu_brain_memory_add", _clean({"text": text, "scope": scope, "kind": kind, **kw}))
+        )
+
+    def list(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_list", _clean(kw))
+        return res
+
+    def top(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_top", _clean(kw))
+        return res
+
+    def accept(self, proposal_id: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_accept", _clean({"proposal_id": proposal_id, **kw}))
+        return res
+
+    def reject(self, proposal_id: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_reject", _clean({"proposal_id": proposal_id, **kw}))
+        return res
+
+    def invalidate(self, memory_id: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_invalidate", _clean({"memory_id": memory_id, **kw}))
+        return res
+
+    def blame(self, run_id: str, **kw: Any) -> Dict[str, Any]:
+        """Per-run citation attribution: which memories a run cited. Pass a run_id (ULID)."""
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_blame", _clean({"run_id": run_id, **kw}))
+        return res
+
+    def proposals(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_proposals", _clean(kw))
+        return res
+
+    def conflicts(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_memory_conflicts", _clean(kw))
+        return res
+
+    def conflict_resolve(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_conflict_resolve", _clean(kw))
+        return res
+
+    def prune(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_prune", _clean(kw))
+        return res
+
+
+class _Config:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    def show(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_config_show", _clean(kw))
+        return res
+
+
+class _Models:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    def list(self, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_model_list", _clean(kw))
+        return res
+
+
+class _Benchmark:
+    def __init__(self, t: Any) -> None:
+        self._t = t
+
+    def context(self, query: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_benchmark_context", _clean({"query": query, **kw}))
+        return res
+
+    def record_outcome(self, task: str, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_benchmark_record_outcome", _clean({"task": task, **kw}))
+        return res
+
+
+class KimetsuClient:
+    def __init__(self, base_url: Optional[str] = None, token: Optional[str] = None,
+                 repo: Optional[str] = None, *, timeout: float = 30.0,
+                 transport: Optional[Any] = None) -> None:
+        if transport is not None:
+            self._t = transport
+        else:
+            base_url = base_url or os.environ["KIMETSU_REMOTE_URL"]
+            token = token or os.environ["KIMETSU_REMOTE_TOKEN"]
+            repo = repo or os.environ["KIMETSU_REMOTE_REPO"]
+            self._t = SyncTransport(base_url, token, repo, timeout=timeout)
+        self.memory = _Memory(self._t)
+        self.config = _Config(self._t)
+        self.models = _Models(self._t)
+        self.benchmark = _Benchmark(self._t)
+
+    def context(self, query: str, *, tags: Optional[List[str]] = None, **kw: Any) -> Context:
+        return Context.model_validate(
+            self._t.call("kimetsu_brain_context", _clean({"query": query, "tags": tags, **kw}))
+        )
+
+    def record(self, lesson: str, *, tags: List[str],
+               kind: Optional[str] = None, **kw: Any) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call(
+            "kimetsu_brain_record", _clean({"lesson": lesson, "tags": tags, "kind": kind, **kw})
+        )
+        return res
+
+    def status(self) -> Status:
+        return Status.model_validate(self._t.call("kimetsu_brain_status", {}))
+
+    def insights(self) -> Dict[str, Any]:
+        res: Dict[str, Any] = self._t.call("kimetsu_brain_insights", {})
+        return res
+
+    def close(self) -> None:
+        if hasattr(self._t, "close"):
+            self._t.close()
+
+    def __enter__(self) -> "KimetsuClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

kimetsu-0.1.0/src/kimetsu/errors.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from typing import Optional
+
+
+class KimetsuError(Exception):
+    """Base class for all Kimetsu SDK errors."""
+
+
+class KimetsuAuthError(KimetsuError):
+    """HTTP 401 (missing/invalid token) or 403 (wrong repo / scope)."""
+
+
+class KimetsuRateLimitError(KimetsuError):
+    """HTTP 429."""
+
+    def __init__(self, message: str, *, retry_after: Optional[float] = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class KimetsuToolError(KimetsuError):
+    """A JSON-RPC `error` object returned in the MCP envelope."""
+
+    def __init__(self, message: str, *, code: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+class KimetsuProtocolError(KimetsuError):
+    """Handshake failure or malformed JSON-RPC envelope."""

kimetsu-0.1.0/src/kimetsu/models.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, ConfigDict
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class Memory(_Base):
+    id: Optional[str] = None
+    text: Optional[str] = None
+    tags: Optional[List[str]] = None
+
+
+class Context(_Base):
+    capsules: List[Dict[str, Any]] = []
+
+
+class Status(_Base):
+    initialized: Optional[bool] = None
+    accepted: Optional[int] = None

kimetsu-0.1.0/tests/test_async.py

@@ -0,0 +1,35 @@
+import json
+import httpx
+import pytest
+import respx
+from kimetsu import AsyncKimetsuClient
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_context_matches_sync_wire():
+    route = respx.post("https://brain.test/mcp/web").mock(side_effect=[
+        httpx.Response(200, json={"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05"}}),
+        httpx.Response(200, json={"jsonrpc": "2.0", "id": 2, "result": {"capsules": []}}),
+    ])
+    async with AsyncKimetsuClient("https://brain.test", "tok", "web") as c:
+        ctx = await c.context("q", tags=["a"])
+    assert ctx.capsules == []
+    sent = route.calls.last.request
+    assert sent.headers["authorization"] == "Bearer tok"
+    assert json.loads(sent.content)["params"] == {
+        "name": "kimetsu_brain_context",
+        "arguments": {"query": "q", "tags": ["a"]},
+    }
+
+
+@respx.mock
+@pytest.mark.asyncio
+async def test_async_memory_add_maps_and_wraps():
+    respx.post("https://brain.test/mcp/web").mock(side_effect=[
+        httpx.Response(200, json={"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05"}}),
+        httpx.Response(200, json={"jsonrpc": "2.0", "id": 2, "result": {"id": "01ABC", "text": "m"}}),
+    ])
+    async with AsyncKimetsuClient("https://brain.test", "tok", "web") as c:
+        m = await c.memory.add("m", scope="project")
+    assert m.id == "01ABC"

kimetsu-0.1.0/tests/test_client_core.py

@@ -0,0 +1,44 @@
+import pytest
+
+from kimetsu import KimetsuClient
+
+
+class FakeTransport:
+    def __init__(self):
+        self.calls = []
+
+    def call(self, name, arguments):
+        self.calls.append((name, arguments))
+        return {"echo": name}
+
+
+def test_core_methods_map_to_tools():
+    t = FakeTransport()
+    c = KimetsuClient(transport=t)
+    c.context("how to migrate", tags=["db"])
+    c.record("use just migrate", tags=["db"], kind="semantic_operator")
+    c.status()
+    c.insights()
+    names = [n for n, _ in t.calls]
+    assert names == ["kimetsu_brain_context", "kimetsu_brain_record",
+                      "kimetsu_brain_status", "kimetsu_brain_insights"]
+    assert t.calls[0][1] == {"query": "how to migrate", "tags": ["db"]}
+
+
+def test_env_fallback(monkeypatch):
+    monkeypatch.setenv("KIMETSU_REMOTE_URL", "https://b.test")
+    monkeypatch.setenv("KIMETSU_REMOTE_TOKEN", "tok")
+    monkeypatch.setenv("KIMETSU_REMOTE_REPO", "web")
+    c = KimetsuClient()   # must not raise
+    assert c is not None
+
+
+def test_required_args_enforced_by_signature():
+    t = FakeTransport()
+    c = KimetsuClient(transport=t)
+    with pytest.raises(TypeError):
+        c.record("no tags")          # tags is required
+    with pytest.raises(TypeError):
+        c.memory.add("no scope")     # scope is required
+    with pytest.raises(TypeError):
+        c.benchmark.record_outcome() # task is required

kimetsu-0.1.0/tests/test_errors.py

@@ -0,0 +1,16 @@
+from kimetsu.errors import (
+    KimetsuError, KimetsuAuthError, KimetsuRateLimitError,
+    KimetsuToolError, KimetsuProtocolError,
+)
+
+def test_hierarchy():
+    for cls in (KimetsuAuthError, KimetsuRateLimitError, KimetsuToolError, KimetsuProtocolError):
+        assert issubclass(cls, KimetsuError)
+
+def test_rate_limit_carries_retry_after():
+    e = KimetsuRateLimitError("slow down", retry_after=1.5)
+    assert e.retry_after == 1.5
+
+def test_tool_error_carries_code():
+    e = KimetsuToolError("nope", code=-32601)
+    assert e.code == -32601 and str(e) == "nope"

kimetsu-0.1.0/tests/test_memory.py

@@ -0,0 +1,40 @@
+from kimetsu import KimetsuClient
+
+
+class FakeTransport:
+    def __init__(self):
+        self.calls = []
+
+    def call(self, name, arguments):
+        self.calls.append((name, arguments))
+        return {}
+
+
+def test_memory_methods_map_to_tools():
+    t = FakeTransport()
+    c = KimetsuClient(transport=t)
+    c.memory.search("q")
+    c.memory.add("m", scope="project", kind="fact")
+    c.memory.list()
+    c.memory.top()
+    c.memory.accept("prop1")
+    c.memory.reject("prop2")
+    c.memory.invalidate("mem3")
+    c.memory.blame("run4")
+    c.memory.proposals()
+    c.memory.conflicts()
+    c.memory.conflict_resolve()
+    c.memory.prune()
+    assert [n for n, _ in t.calls] == [
+        "kimetsu_brain_memory_search", "kimetsu_brain_memory_add",
+        "kimetsu_brain_memory_list", "kimetsu_brain_memory_top",
+        "kimetsu_brain_memory_accept", "kimetsu_brain_memory_reject",
+        "kimetsu_brain_memory_invalidate", "kimetsu_brain_memory_blame",
+        "kimetsu_brain_memory_proposals", "kimetsu_brain_memory_conflicts",
+        "kimetsu_brain_conflict_resolve", "kimetsu_brain_prune",
+    ]
+    assert t.calls[1][1] == {"text": "m", "scope": "project", "kind": "fact"}
+    assert t.calls[4][1] == {"proposal_id": "prop1"}   # accept
+    assert t.calls[5][1] == {"proposal_id": "prop2"}   # reject
+    assert t.calls[6][1] == {"memory_id": "mem3"}      # invalidate
+    assert t.calls[7][1] == {"run_id": "run4"}         # blame

kimetsu-0.1.0/tests/test_models.py

@@ -0,0 +1,10 @@
+from kimetsu.models import Context, Status, Memory
+
+
+def test_models_parse_and_tolerate_extra():
+    ctx = Context.model_validate({"capsules": [{"text": "x"}], "note": "unexpected"})
+    assert ctx.capsules[0]["text"] == "x"
+    st = Status.model_validate({"initialized": True, "accepted": 5})
+    assert st.initialized is True and st.accepted == 5
+    m = Memory.model_validate({"id": "01ABC", "text": "lesson"})
+    assert m.id == "01ABC"

kimetsu-0.1.0/tests/test_other_namespaces.py

@@ -0,0 +1,25 @@
+from kimetsu import KimetsuClient
+
+
+class FakeTransport:
+    def __init__(self):
+        self.calls = []
+
+    def call(self, name, arguments):
+        self.calls.append((name, arguments))
+        return {}
+
+
+def test_config_models_benchmark():
+    t = FakeTransport()
+    c = KimetsuClient(transport=t)
+    c.config.show()
+    c.models.list()
+    c.benchmark.context("term-bench task")
+    c.benchmark.record_outcome(task="t1", passed=True)
+    assert [n for n, _ in t.calls] == [
+        "kimetsu_brain_config_show", "kimetsu_brain_model_list",
+        "kimetsu_benchmark_context", "kimetsu_benchmark_record_outcome",
+    ]
+    assert t.calls[2][1] == {"query": "term-bench task"}
+    assert t.calls[3][1] == {"task": "t1", "passed": True}

kimetsu-0.1.0/tests/test_smoke.py

@@ -0,0 +1,4 @@
+import kimetsu
+
+def test_version_exposed():
+    assert isinstance(kimetsu.__version__, str)

kimetsu-0.1.0/tests/test_transport.py

@@ -0,0 +1,62 @@
+import httpx
+import pytest
+import respx
+
+from kimetsu._transport import build_call, parse_envelope, SyncTransport
+from kimetsu.errors import KimetsuAuthError, KimetsuRateLimitError, KimetsuToolError
+
+
+def test_build_call_shape():
+    body = build_call("kimetsu_brain_record", {"lesson": "x"}, request_id=7)
+    assert body == {"jsonrpc": "2.0", "id": 7, "method": "tools/call",
+                    "params": {"name": "kimetsu_brain_record", "arguments": {"lesson": "x"}}}
+
+
+def test_parse_result():
+    env = {"jsonrpc": "2.0", "id": 1, "result": {"ok": True}}
+    assert parse_envelope(200, env, {}) == {"ok": True}
+
+
+def test_parse_tool_error():
+    env = {"jsonrpc": "2.0", "id": 1, "error": {"code": -32000, "message": "not available in remote mode"}}
+    with pytest.raises(KimetsuToolError) as ei:
+        parse_envelope(200, env, {})
+    assert ei.value.code == -32000
+
+
+@pytest.mark.parametrize("code,exc", [(401, KimetsuAuthError), (403, KimetsuAuthError), (429, KimetsuRateLimitError)])
+def test_parse_http_errors(code, exc):
+    with pytest.raises(exc):
+        parse_envelope(code, {}, {"retry-after": "2"} if code == 429 else {})
+
+
+@respx.mock
+def test_transport_call_hits_endpoint():
+    route = respx.post("https://brain.test/mcp/web").mock(side_effect=[
+        httpx.Response(200, json={"jsonrpc": "2.0", "id": 1, "result": {"capabilities": {}}}),  # initialize
+        httpx.Response(200, json={"jsonrpc": "2.0", "id": 2, "result": {"ok": True}}),          # tools/call
+    ])
+    t = SyncTransport("https://brain.test", "tok_x", "web")
+    assert t.call("kimetsu_brain_status", {}) == {"ok": True}
+    assert route.calls.last.request.headers["authorization"] == "Bearer tok_x"
+
+
+@respx.mock
+def test_non_json_error_body_maps_to_typed_error():
+    # A 401 with an HTML gateway body must raise KimetsuAuthError, not a JSON decode error.
+    respx.post("https://brain.test/mcp/web").mock(
+        return_value=httpx.Response(401, text="<html>401 Unauthorized</html>")
+    )
+    t = SyncTransport("https://brain.test", "tok_x", "web")
+    with pytest.raises(KimetsuAuthError):
+        t.call("kimetsu_brain_status", {})
+
+
+def test_retry_after_http_date_degrades_to_none():
+    from kimetsu.errors import KimetsuRateLimitError
+    try:
+        parse_envelope(429, {}, {"retry-after": "Wed, 21 Oct 2026 07:28:00 GMT"})
+    except KimetsuRateLimitError as e:
+        assert e.retry_after is None
+    else:
+        raise AssertionError("expected KimetsuRateLimitError")