Metadata-Version: 2.4
Name: amkb
Version: 0.0.1
Summary: Python SDK and reference implementation for the Agent-Managed Knowledge Base (AMKB) protocol
Project-URL: Specification, https://github.com/takyone/amkb-spec
Project-URL: Repository, https://github.com/takyone/amkb-sdk
Author: takyone
License: Apache-2.0
License-File: LICENSE
Keywords: agent,amkb,knowledge-base,rag
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: msgspec>=0.18
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov>=5.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# amkb — Python SDK for the Agent-Managed Knowledge Base protocol

> 🚧 **Not yet usable.** This `0.0.x` release exists only to reserve
> the name on PyPI while the protocol settles. The first usable
> release will be `0.1.0`, gated on a real reference implementation
> (Spikuit adapter) passing the full conformance suite. Until then,
> the public API may change without notice and there is no install
> story worth recommending. Track progress at
> [amkb-spec](https://github.com/takyone/amkb-spec) and
> [amkb-sdk](https://github.com/takyone/amkb-sdk).

`amkb` is a **backend-agnostic** Python SDK for the AMKB protocol. It
provides the types, error catalog, filter algebra, Store protocol,
and a reusable conformance suite. It intentionally ships **no storage
backend**: SQLite, Chroma, Postgres, an in-memory dict, or a custom
engine are all equally valid implementations of the protocol.

The package consists of:

1. **Core types** (`amkb.types`) — `Node`, `Edge`, `Actor`, `Transaction`,
   `ChangeSet`, `Event`, plus reserved kind / layer / rel constants.
2. **Canonical errors** (`amkb.errors`) — 22 error codes in 5
   categories, as a typed exception hierarchy.
3. **Filter algebra** (`amkb.filters`) — `Eq` / `In` / `Range` /
   `And` / `Or` / `Not`, JSON-serializable via msgspec tags.
4. **Store protocol** (`amkb.store`) — `Store` and `Transaction` as
   `typing.Protocol` types. Implementations satisfy them structurally,
   without inheritance.
5. **Conformance suite** (`amkb.conformance`) — pytest functions
   mirroring the test matrix at
   [amkb-spec/conformance/](https://github.com/takyone/amkb-spec/tree/main/conformance).
   Any implementation can exercise the suite by providing a ``store``
   fixture and running `pytest --pyargs amkb.conformance`.

## Relationship to Spikuit

[Spikuit](https://github.com/takyone/spikuit) is a neural learning
graph and will be the first real consumer of `amkb`. Spikuit features
such as FSRS scheduling, APPNP propagation, and pressure dynamics live
on top of the AMKB protocol, not inside it. A future
`spikuit.amkb_adapter` module will expose Spikuit's internal state as
an `amkb.Store` without changing Spikuit's own vocabulary.

## Install

```bash
pip install amkb             # types, errors, filters, protocol
pip install amkb[test]       # + conformance suite deps (pytest)
```

`amkb` has one runtime dependency: [msgspec](https://jcristharif.com/msgspec/).

## Reading order

1. [amkb-spec](https://github.com/takyone/amkb-spec) — the normative
   protocol (authoritative).
2. `src/amkb/types.py` — data shapes.
3. `src/amkb/errors.py` — the 22 canonical codes.
4. `src/amkb/filters.py` — the filter algebra.
5. `src/amkb/store.py` — the `Store` and `Transaction` protocols.
6. `src/amkb/conformance/` — the executable test matrix.

## Implementing a Store

Any class whose shape matches the `Store` protocol is a valid AMKB
store. A minimal dict-backed implementation used as an executable
reference for the conformance suite lives in `tests/impls/dict_store.py`
— it is intentionally kept in tests rather than shipped as part of
the package, to reinforce that the SDK itself is backend-agnostic.

## License

Apache-2.0. See [LICENSE](LICENSE).
