Metadata-Version: 2.4
Name: band-sdk-core
Version: 0.4.0.dev2
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Typing :: Typed
Summary: Shared Band event-payload validation
Keywords: band,sdk,validation,events
Author: band.ai
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/band-ai/band-sdk-core/blob/main/crates/py/CHANGELOG.md
Project-URL: Homepage, https://github.com/band-ai/band-sdk-core
Project-URL: Issues, https://github.com/band-ai/band-sdk-core/issues
Project-URL: Repository, https://github.com/band-ai/band-sdk-core

# band-sdk-core-py

Python package for [`band-sdk-core-core`](../core) (`import band_sdk_core`).

## Public surface

`EventType` is the closed set of inbound event names.

`validate_event_payload(event_type, raw, trace_context=None)`: `event_type`
is a platform name (`"message_created"`, `"agent.control"`, …) or an
`EventType`. `raw` is a JSON-shaped Python value. Success returns the
normalized payload (`event_created` returns the input unchanged). Failure
raises `ValueError` with `.args == (message,)` (`str(e)` is ordinary),
`.issues` (a tuple of `(path, code, message)`), and `.trace_context`.
There is no custom exception class.

`ClaimRegistry`, `RetryTracker`, `ParticipantRoster` are the
inbound-delivery runtime state classes -- lifecycle and design decisions:
[`../core/docs/runtime-state-policy.md`](../core/docs/runtime-state-policy.md).
A participant is any mapping; `add`/`set_all` read `id`, `name`, `type`,
`handle`, `description` from it and `list()` returns dicts with exactly
those five keys. `id` is required and must be a string; the other four are
each a string or `None`. A non-mapping value, a missing/non-string `id`, or
another field that is not a string or `None` raises `TypeError`. `set_all`
takes an optional `trace_context` and raises `ValueError` -- leaving the
roster unchanged, with `.issues` and `.trace_context` attached like
`validate_event_payload`'s error -- if its snapshot names the same `id`
twice. `RetryTracker`'s `max_tracked` must be at least `1`; `0` raises
`ValueError`. `ClaimRegistry`'s `max_completed` must be at least `1` too --
`0` also raises `ValueError`.

`MemorySystem`, `MemoryType`, `MemorySegment`, `MemoryStoreScope`,
`MemoryListScope`, `MemoryStatus` are the canonical memory taxonomy --
design decisions:
[`../core/docs/memory-taxonomy-policy.md`](../core/docs/memory-taxonomy-policy.md).
Each is a closed set with a `wire_name` property and a `from_wire_name`
static method (`None` for an unrecognized string), mirroring `EventType`.

`validate_memory_type_for_system(system, memory_type, trace_context=None)`:
`system`/`memory_type` are each a wire-name string or the matching
`MemorySystem`/`MemoryType` instance (mirroring `validate_event_payload`'s
acceptance of either an event name or an `EventType`), and it returns
`None` on success. Failure raises `ValueError` with the same
`.issues`/`.trace_context` contract as `validate_event_payload` -- an
unrecognized `system` and an unrecognized `memory_type` are independent
issues, both reported when both strings are invalid.

## Values across the language boundary

JSON objects become Python `dict`s. JSON `null` becomes `None`. An
explicit null stays distinct from an absent key — a distinction the
payload validator uses. Values that cannot be converted raise
`TypeError`, which `except Exception` catches.

## Build / test

`just check` type-checks and lints this crate. Linking the extension
happens through `uv` / maturin (`just test-py`, `just build-py`), not
`cargo test`.

```bash
just test-py     # uv sync, pytest, isolated wheel install
just build-py    # uv build (wheel only)
```

Wheels are platform-specific. Recipes use [`uv`](https://docs.astral.sh/uv/)
and honor `UV_PYTHON`, or `PYTHON` / `PYTHON_BIN`. Windows builds need the
MSVC toolchain rustup's default host target uses.

The wheel is `abi3` for Python >= 3.11. Typed stubs are `band_sdk_core.pyi` plus
an empty `py.typed`. `just test-py` checks they match the runtime package
and that they ship in the wheel.

