band-sdk-core

Shared Band event-payload validation, memory-taxonomy, and inbound-delivery runtime state, compiled from Rust into a native Python extension (import band_sdk_core). Every function is synchronous, pure computation — no network, filesystem, or logging.

band-sdk-core-core (Rust)  -->  band-sdk-core (this package, PyPI)  -->  band-sdk-python

If you're using band-sdk-python, it already depends on this package — you don't need to install it yourself. Install it directly only if you're calling into it without that SDK. Full picture: repository architecture.

Install

pip install band-sdk-core

Wheels are prebuilt (abi3, Python >= 3.11) for Linux (manylinux/musllinux, x86_64/aarch64), macOS (arm64/x86_64), and Windows (amd64/arm64) — no Rust toolchain needed to install.

Quickstart

import band_sdk_core

try:
    payload = band_sdk_core.validate_event_payload("room_deleted", {"id": "room-1"})
except ValueError as e:
    for path, code, message in e.issues:
        print(f"{path}: {code} - {message}")

validate_event_payload is the platform's inbound WebSocket payload policy: normalize a well-formed payload, or reject a malformed one with every violation reported at once, never just the first.

Public surface

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.

EventType

The closed set of inbound event names.

Delivery-state runtime classes

ClaimRegistry, RetryTracker, ParticipantRoster, and SubscriptionTracker are the inbound-delivery runtime state classes — lifecycle and design decisions: 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.

SubscriptionTracker provides synchronous, transport-independent decisions for agent-topic joins and the two-topic room subscription transaction. It returns opaque integer tickets; callers supply the matching ticket when recording each completion. Failed rollbacks and failed or unknown leaves require explicit reconciliation before a fresh claim is allowed.

SubscriptionTracker lifecycle

from band_sdk_core import LeaveOutcome, RoomStatus, RoomSubscribeResult, SubscriptionTracker

tracker = SubscriptionTracker()
ticket = tracker.begin_room_subscribe("room-1")
if ticket is None:
    raise RuntimeError("room is not claimable")

result = tracker.record_room_participants_join_failed("room-1", ticket, False)
if result is RoomSubscribeResult.RollbackFailed:
    assert tracker.room_status("room-1") is RoomStatus.NeedsReconciliation
    assert tracker.acknowledge_room_reconciled("room-1") is True
    ticket = tracker.begin_room_subscribe("room-1")
    assert ticket is not None
    assert tracker.record_both_room_topics_joined("room-1", ticket) is RoomSubscribeResult.Subscribed
    leave_ticket = tracker.unsubscribe_room("room-1")
    assert leave_ticket is not None
    assert tracker.mark_room_leave_complete("room-1", leave_ticket, LeaveOutcome.Left) is True
else:
    match result:
        case (
            RoomSubscribeResult.Subscribed
            | RoomSubscribeResult.JoinFailed
            | RoomSubscribeResult.RolledBack
            | RoomSubscribeResult.Stale
        ):
            pass
        case _:
            raise AssertionError(f"unhandled subscription result: {result}")

Memory taxonomy

MemorySystem, MemoryType, MemorySegment, MemoryStoreScope, MemoryListScope, MemoryStatus are the canonical memory taxonomy — design decisions: 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 dicts. 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.

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

Wheels are platform-specific. Recipes use 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.

License

MIT — see LICENSE.

Project links

Data verified by PyPI on Aug 23, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.4.0)

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: band.ai

GitHub Statistics

Data verified by PyPI on Aug 23, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

band sdk validation events

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

band_sdk_core-0.5.0-cp311-abi3-win_arm64.whl (262.5 kB view details)

Uploaded CPython 3.11+Windows ARM64

band_sdk_core-0.5.0-cp311-abi3-win_amd64.whl (275.1 kB view details)

Uploaded CPython 3.11+Windows x86-64

band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl (654.8 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ x86-64

band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl (620.4 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_x86_64.whl (447.7 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ x86-64

band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_aarch64.whl (442.9 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

band_sdk_core-0.5.0-cp311-abi3-macosx_11_0_arm64.whl (399.0 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

band_sdk_core-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl (399.3 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-win_arm64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 3af0c15ded79461a1977778f271e3c993e4f99e7d7d4b812f80a65ad925343a3
MD5 73751a9118c98713bbca96dbe3e731c6
BLAKE2b-256 2916fc72d8970773a2da6942076d5ff12d1240c876d308a2d7f247aead4e1826

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-win_arm64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 82168a2b72f90c53bf2c5c718821349f644316f3a59d8a7e5fa47127a489323e
MD5 f093780733e545348503b9d0fb37d1e9
BLAKE2b-256 862fb6300ff34616334dc88727b7f4010c9cf5e5f0cfd39ba099e868e435708e

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-win_amd64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 e24415544bb2021e86d7bba2ffd517a3610fcb78fe20314ce94e5e83b5a0a4da
MD5 7106f78cbfc2f5f807418986a59be1ca
BLAKE2b-256 9ebcc30d257a9e96f5f1cf4f9332b571de0317a0ce2450e04c840e871fb42765

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 a46a2695d36860f934e494d85cb9c802ece1b838af37e9e0510cf6e80f777756
MD5 956b6d313abc5c4b6e5f32f5a0982904
BLAKE2b-256 749f38dcad9a4747bccc00a6a02d3fb33c40be6e6f8a391ad10b8092b5a469f3

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 85208e53bef499636baa3d8672a216821cd4bf671669005d2d61bb9b22436184
MD5 e836ac5931dabe2400b2371b3df4a9d0
BLAKE2b-256 404dafc0300a727d40e80ce65cd83488a1486c8e79d29b61153e9680870eb150

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_x86_64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 24b76d92c961c222f2cd290eb2e7ee16a99a8f4d82679ecc2cd2a55131f5f4bd
MD5 099239836d7ef93e14981793e4fdaaf9
BLAKE2b-256 d5a25f7db63aa4d12fb2a35dd9274351b1fb2e307d71337bc93927cf43196a9c

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-manylinux_2_28_aarch64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2837dab03ae6f2a06cdc35135d51178d1ddfc8cb4e6e5876f5a5cb58f1e3dd77
MD5 d043de063c67160b8bfffd7a7bbdd867
BLAKE2b-256 f10c036e05b0a55f435ce9e8e790becbbc93342f4513f361f76e9f6b0dc86fbb

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file band_sdk_core-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 9402e522e30475a07251b2234c0b7cf4fb440017a45fe56e0bfb82542b61be77
MD5 6e1f1590ea0c188f519a0daabc04427c
BLAKE2b-256 ef5a77dc9d11812b7d8021c5af682fb6a16a3ddec3b5e45554d5c925b7f11627

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: publish.yml on band-ai/band-sdk-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.4.0

8 files

2.3.0

8 files

2.2.0

8 files

2.1.0

8 files

2.0.0

8 files

1.2.1

8 files

1.2.0

8 files

1.1.0

8 files

1.0.1

8 files

1.0.0

8 files

0.8.0

8 files

0.7.2

8 files

0.7.1

8 files

0.7.0

8 files

0.6.0

8 files

This release

0.5.0 This release

8 files

0.4.1

8 files

0.4.0

8 files

Pre-release

0.4.0.dev2

8 files

Pre-release

0.4.0.dev1

8 files

Pre-release

0.4.0.dev0

8 files

Pre-release

0.2.1.dev4

6 files

Pre-release

0.2.1.dev2

6 files

Pre-release

0.2.1.dev1

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page