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
