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 28, 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 28, 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-1.0.1-cp311-abi3-win_arm64.whl (309.0 kB view details)

Uploaded CPython 3.11+Windows ARM64

band_sdk_core-1.0.1-cp311-abi3-win_amd64.whl (323.7 kB view details)

Uploaded CPython 3.11+Windows x86-64

band_sdk_core-1.0.1-cp311-abi3-musllinux_1_2_x86_64.whl (711.2 kB view details)

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

band_sdk_core-1.0.1-cp311-abi3-musllinux_1_2_aarch64.whl (675.0 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

band_sdk_core-1.0.1-cp311-abi3-manylinux_2_28_x86_64.whl (500.5 kB view details)

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

band_sdk_core-1.0.1-cp311-abi3-manylinux_2_28_aarch64.whl (497.4 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

band_sdk_core-1.0.1-cp311-abi3-macosx_11_0_arm64.whl (449.6 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

band_sdk_core-1.0.1-cp311-abi3-macosx_10_12_x86_64.whl (448.9 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 7ebdb88ac1c4cd7e8d116649965d43023c9c0505ecb0ecff860b5559dc256e17
MD5 01fa5fb58c9b1f18512deb3e063b1d99
BLAKE2b-256 eb67a716987c42910f0f5692a5f9fea3ec133ba2b15b22ac695570618b7c55c0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 5bbf57b1769e7e67b8374dc473cb2fdfc41944ce77894123835a44e027cd8b4d
MD5 8cfe03b3349b91a74369b479b8531930
BLAKE2b-256 362d81e0a6c945d6d2c789696238b2d884c9a30fe68c6571144541e147ce1c86

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 d018755b6ccb6d713664aa1015369e81a4b05b7121e2788d649c6b37dc4a5095
MD5 a445ca5cc9dd8d075f3478315d5a8333
BLAKE2b-256 5f7358c2043f50f55d0304aa8bef7520e549b0b138cf52b84adaee39ea4b6c27

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 f3b0e2d19b111407420c5804b5c04617a2996e22cbe7264b676dead4aa21e7dc
MD5 53955931931964d97382c73b31d0a69f
BLAKE2b-256 5c84a9253c540bf87c1524d8e1c984affb0c1e0c333bac173c3c5d141bb976c8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 3c9853cd3f2043618a22fcd60524affda338c9e41d18093817627fa9902f41fa
MD5 dbda7ad5784af30c67b7208a6caf6417
BLAKE2b-256 ec4fb7adb0a5060edc6870a82b940a20fb8c490d0bee742f2e5ba38877fb696d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 d243982ad2f712563dd523b08df5c6dfe68414d62a71519df9cc7434c32185a3
MD5 a0e249bcb7b8c9f06089cf1ef7528d6c
BLAKE2b-256 d0040dc7d3d1e261f4abf3b5e3405bc009ad16066466e30348305921b0177398

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1357df440dd4ab13e8eea637ef42bae2cb25945cbe78315d5bb1ac093a2b6c1a
MD5 06ee4482c53e86a4fe10de27c487fae0
BLAKE2b-256 d7872497d6b832aacf2769a9b6bdd74dcaa70a46fbc57ed2e001ca4ae2e98ae6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-1.0.1-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b5164b1db960859df2abd7009127169bfc0ac32bc19fbf008cd8f5e4e420caff
MD5 59dd32c518ab7e46fe631ff729bd2c49
BLAKE2b-256 20d5aeb477b538e8b45b39415a550b284df6cdc325a7aa68450afdf824599bd7

See more details on using hashes here.

Provenance

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

This release

1.0.1 This release

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