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.7.2-cp311-abi3-win_arm64.whl (306.6 kB view details)

Uploaded CPython 3.11+Windows ARM64

band_sdk_core-0.7.2-cp311-abi3-win_amd64.whl (321.1 kB view details)

Uploaded CPython 3.11+Windows x86-64

band_sdk_core-0.7.2-cp311-abi3-musllinux_1_2_x86_64.whl (709.0 kB view details)

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

band_sdk_core-0.7.2-cp311-abi3-musllinux_1_2_aarch64.whl (674.0 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

band_sdk_core-0.7.2-cp311-abi3-manylinux_2_28_x86_64.whl (497.8 kB view details)

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

band_sdk_core-0.7.2-cp311-abi3-manylinux_2_28_aarch64.whl (495.4 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

band_sdk_core-0.7.2-cp311-abi3-macosx_11_0_arm64.whl (448.5 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

band_sdk_core-0.7.2-cp311-abi3-macosx_10_12_x86_64.whl (446.4 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 a346cddbe44578532f8a518c6d58138a174e662d9a70bc9fee10a6fe333b3bea
MD5 fcad044fa33ab560ae7c61cf97eced1e
BLAKE2b-256 8b5aa94d50108611fe917e7b74c71b9d0b1d95aa1d6915ac8c3676dc90ce6c89

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 bde0d8c5cf424df6832d5cf8be14108fb588892f7e6957a0a8af2e0d083db92e
MD5 f4d349ba702fc209d1e353a02aaff9c0
BLAKE2b-256 f75859eb4a562f7b344b1ffc21693d3e254974febb30cd1328167526282f1458

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 eed8262d67ff65f14d2a57216c7023573e043dbe809fc3e02de828f16f9dbac3
MD5 a64b43bd718535e6cf5e246e987ab3ae
BLAKE2b-256 c7e044d753e3cd7b38ea768cb3fcd61c23770660894c7b249d854560defb404d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 64890438f1b094516d249d1795af3b6b278a781c7e46b5e2fea486c4226c3608
MD5 6b637bd0da2e307f7b2a851f1a4da8e3
BLAKE2b-256 e352d4b587bcdde4bcc38bad702b60f98881aa1a76f900218b09ae5400b1ca64

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5f67adad762a763a58d294b1e31460df1cf28600509d602bb7b837523f9cbf7b
MD5 db1f55c4b96c9a3418ecc131710aa9e8
BLAKE2b-256 5933a3a09d817c0ed5a938cf0485fe822a7885c8dd8267a6d99f7cccdc7114c8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 782be8e9f4a41f1c22c36c0f31b7c9c2a885c2abfabe7a2c7c9edfb28b4369cb
MD5 3ad05f1e2e6679a26844a63846ff4677
BLAKE2b-256 ea07f749efd4d62ce8eb6059716a0f9f59c20c2ee4b7996a24d4ccf2b740cfe9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f99e4559df394be3837b2b1221612d41382e1252aa3118ac8a0f0ef4b293390e
MD5 e9afd1db338fb359540756dae51c4147
BLAKE2b-256 08c12d4a5be20ee26ff54b20f65038e06eba999b7441396cf1630aa7701cb471

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.2-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 574b41b37a79c0b8d436be9ef84b386dbb36711035018098188827d417814c8e
MD5 831c74eabb7cfa914042a997e61c7d7a
BLAKE2b-256 5867e8292ca46080dfe45192c03f236e8953acd897b21e084b4f228e540307de

See more details on using hashes here.

Provenance

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

This release

0.7.2 This release

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