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 live as rustdoc on each type in crates/core/src/runtime/.

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}")

Session — WebSocket reconnect state machine

Session/SessionPolicy are a sans-io session state machine plus reconnect backoff/jitter policy; classify_close/classify_upgrade classify a WebSocket close code or HTTP upgrade-rejection status. Session never sleeps, connects, or closes a socket itself — the caller drives its own transport and reports what happened through on_connected/ on_socket_close/on_upgrade_rejected/on_supersede. Decisions live as rustdoc in crates/core/src/runtime/session.rs.

Session lifecycle

from band_sdk_core import Session, SessionPolicy, SessionState

session = Session(SessionPolicy.default())
epoch = session.begin_attempt(0.0)
assert epoch is not None

connected = session.on_connected(epoch, 0.0)
assert connected.state is SessionState.Up

disconnected = session.on_socket_close(epoch, 5.0, 1006, 0.5)
assert disconnected.state is SessionState.Reconnecting
assert disconnected.retry_after_s is not None

Memory taxonomy

MemorySystem, MemoryType, MemorySegment, MemoryStoreScope, MemoryListScope, MemoryStatus are the canonical memory taxonomy — design decisions live as rustdoc in crates/core/src/memory.rs. 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 29, 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 29, 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-2.0.0-cp311-abi3-win_arm64.whl (314.8 kB view details)

Uploaded CPython 3.11+Windows ARM64

band_sdk_core-2.0.0-cp311-abi3-win_amd64.whl (332.0 kB view details)

Uploaded CPython 3.11+Windows x86-64

band_sdk_core-2.0.0-cp311-abi3-musllinux_1_2_x86_64.whl (724.5 kB view details)

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

band_sdk_core-2.0.0-cp311-abi3-musllinux_1_2_aarch64.whl (687.2 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

band_sdk_core-2.0.0-cp311-abi3-manylinux_2_28_x86_64.whl (510.4 kB view details)

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

band_sdk_core-2.0.0-cp311-abi3-manylinux_2_28_aarch64.whl (509.8 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

band_sdk_core-2.0.0-cp311-abi3-macosx_11_0_arm64.whl (458.7 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

band_sdk_core-2.0.0-cp311-abi3-macosx_10_12_x86_64.whl (457.4 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 d802cb5a411afa5b7e6089962cdc3b4573ad6d43048fc2b28a8a9079a247aa0b
MD5 19a0e9e8e87ae7fdb3df69af140e14a3
BLAKE2b-256 ab93aa331d33db1d8436dba57df83d4592c6534223ffc11bf94c1eb5090714cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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-2.0.0-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 8ac8e95b466e8110f4e3dd99afaa4520f825c294e2b731d04c246efe1edd7685
MD5 d2a8b8def0c63cef5de2c0565a34c77c
BLAKE2b-256 ea17c795774be4b1b1c96633c68b5a8f2966bfd0752004835920f6f0a676153a

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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-2.0.0-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 3606b58f5a3d9ff006fcd9db425cc4ac47c4482380146a282e23299ca6f0fcab
MD5 c9bf6e7d0ddea159aa185c7a4ce2c16d
BLAKE2b-256 088d61d49368320438ad8ee7ebfc689cfc62163cdb9a5d7592e8d48a3438aae4

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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-2.0.0-cp311-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 430fb51e32080fa58a1c84f8d2342c443865c85a05f8ad727288063e5bdb425a
MD5 c3b75921061c75f49bb3d15f0b943a5c
BLAKE2b-256 67871eef985931ddddf2f2ff9623622f15bab460d4d943aa7dc96d1da8227d37

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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-2.0.0-cp311-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9f581c2173967e44a219d86f124a65650fc915c8c99a1f9ddf69c0e98612253f
MD5 ca82053f53b211236d8fea309b21ee7c
BLAKE2b-256 b19518d976f8a12d24819e3788a2c880ec7d07945673c6a34b68fd7653142ee8

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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-2.0.0-cp311-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 19e58438cf932bb0324c0358a8c332437eade63bb253e6f7cddbfa02c928051e
MD5 983de37930f7ce57e3505a059434f91b
BLAKE2b-256 16c3a894dd0a873a80184bdf443e770917c2ec85e671a8c72f4c8400584692e9

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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-2.0.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 556f420711b7026b0b3dbb9abf0a2dcdd6f7126f2c09ec40ca281c081229851c
MD5 e9a6de39bb6233af1214dca168dfd592
BLAKE2b-256 a69912d8e5a5fb4ef42e684117de2687cbb7bf8df0b706eeb65587caa9867b49

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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-2.0.0-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for band_sdk_core-2.0.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 7db8f08f4dc4616ecee2aa5e8a7bd61d846d959a309a6b25da598e649d4ac278
MD5 f54273a3d400f83df73279ed181cbea7
BLAKE2b-256 e6b0c0450d0df122aa46ffaf11aabacd5dcf27b81e35ff1f5b08639c0cfa1457

See more details on using hashes here.

Provenance

The following attestation bundles were made for band_sdk_core-2.0.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

This release

2.0.0 This release

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

0.5.0

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