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

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. Confirmed decisions: runtime-state-policy.md's ## Session section.

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: 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 26, 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 26, 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.8.0-cp311-abi3-win_arm64.whl (308.5 kB view details)

Uploaded CPython 3.11+Windows ARM64

band_sdk_core-0.8.0-cp311-abi3-win_amd64.whl (322.8 kB view details)

Uploaded CPython 3.11+Windows x86-64

band_sdk_core-0.8.0-cp311-abi3-musllinux_1_2_x86_64.whl (710.5 kB view details)

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

band_sdk_core-0.8.0-cp311-abi3-musllinux_1_2_aarch64.whl (674.9 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

band_sdk_core-0.8.0-cp311-abi3-manylinux_2_28_x86_64.whl (499.6 kB view details)

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

band_sdk_core-0.8.0-cp311-abi3-manylinux_2_28_aarch64.whl (497.3 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

band_sdk_core-0.8.0-cp311-abi3-macosx_11_0_arm64.whl (451.6 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

band_sdk_core-0.8.0-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-0.8.0-cp311-abi3-win_arm64.whl.

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 6a32b9a83e134e496c8e63725d3326d23d6313469396b89a51cc4c062742c823
MD5 842f5ca902bcdae03d41773cd149d2e5
BLAKE2b-256 d383a54e3d3b1f0d53c5ef1d8e276dd013c6c3d946eeb76cdc7f87e99339aa5a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4659949afe82b903b63600fe02c252d57aae5bdef42f5de476516ceed5ce1b39
MD5 e1fc4593eefe42197454371a7bd95ae8
BLAKE2b-256 ad013b84a6e415b0755704776b4f1c4759df3ff7a641376217a8941b200b45d6

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 b0edb3166d6282ce426a69beccb5fe59d086ea7a81097fe5602e3c5e36226d97
MD5 7e6a497a9adc808b0eafaab38c830122
BLAKE2b-256 24cd47258e68886dff08340206f502edc58293ea7a1e6342a275550681c160a0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 958bfe1def7a105d734e060c2a8643460042171dc6fa98b567558e1bc9b26b7e
MD5 28d8d1e22f5813aa37603035ba9a8c46
BLAKE2b-256 cd58cf3209eada08e01a0873d95af89b80db80e146a2ef55c36f66ada22a5c31

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2fb5a36f89b3e61282ad797ce737c99e29caa98f66308801d0aef29978ac2dc4
MD5 c98203d6db88b75c4903673bad9de1a1
BLAKE2b-256 0cff6ca9a5d9093bb0fbb24be63573c85578d936e4b2c068acd5a48635c4321b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 2ada87a268de1f706f7cbabd8e9bfa6122a584eb4e04287fedba14e718ffd300
MD5 a1eb8e611b6f8befa1ef5e1811f8d399
BLAKE2b-256 d4f4239ea6aa2bec1256d52028230257db64b6c98f3836ea648fe369348abbec

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3bbfcdc45ea559f0498fa87b5c1c10af8aee44cce1985bc684dc0c4c5ad4abd0
MD5 c77c043f0b927b5874658594e867de5c
BLAKE2b-256 a11219c224f7d46a69d5639193fe353e510f59c4da57cea4a312d057422792b5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.8.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 71dced29c7087f60903b3d9c5424e2d7c28eb2cbccd2326b6a8d583af1a837a7
MD5 1b54949abda4facc3ad660183b247a14
BLAKE2b-256 9d188c3e72658bbc567727f4a1838c094663f5e0b3cfb3137fb54f08886eeaaf

See more details on using hashes here.

Provenance

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

This release

0.8.0 This release

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