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 25, 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 25, 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.1-cp311-abi3-win_arm64.whl (305.4 kB view details)

Uploaded CPython 3.11+Windows ARM64

band_sdk_core-0.7.1-cp311-abi3-win_amd64.whl (320.4 kB view details)

Uploaded CPython 3.11+Windows x86-64

band_sdk_core-0.7.1-cp311-abi3-musllinux_1_2_x86_64.whl (708.2 kB view details)

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

band_sdk_core-0.7.1-cp311-abi3-musllinux_1_2_aarch64.whl (673.8 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

band_sdk_core-0.7.1-cp311-abi3-manylinux_2_28_x86_64.whl (497.0 kB view details)

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

band_sdk_core-0.7.1-cp311-abi3-manylinux_2_28_aarch64.whl (495.2 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ ARM64

band_sdk_core-0.7.1-cp311-abi3-macosx_11_0_arm64.whl (447.8 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

band_sdk_core-0.7.1-cp311-abi3-macosx_10_12_x86_64.whl (445.7 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-win_arm64.whl
Algorithm Hash digest
SHA256 09b361f84cdf725254d34e5ad57d0c02c6d86e36d55e5243d6725d490fdad47b
MD5 d93289418343d9b94c6d1c713c957c77
BLAKE2b-256 1915940d8846152687b5856fd2f3a73de7501eea261c2dec98db3d7fed3a9021

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 8894f06d54251a9e99f784057e7185be0537a23e3e90fd7213339f2c3473ebaf
MD5 95b7392ea674c74488fa34d07732c29b
BLAKE2b-256 098410f920a9a11062810be75747b7753c6c21c395c1f29d31d8f3dfd1e2a445

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 a3bc50a2322028d5fa01f03d6177b8649528572397e5494e416df84f6af23203
MD5 057531b53860012ba6ef407be4d828c2
BLAKE2b-256 1a42c31cd3c11fee1db664ed334c8326be345d5e44150fbba2dd780589dcf163

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 d1ccc94e33fbf8da1f29b98d66bef14f8cec08de8a0ed7cb3c255f6b6cb2b53d
MD5 8e4c142d660e023ebc594d7740786ece
BLAKE2b-256 2fc1fd42271154f7adb5899f5f04e27f5f86bc523c343952294eb1e400abcdbd

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 947f8e0b5eed4c41a6ee8ce0d0411ee7e36b5a90c4bea622c6b4d156cdeebc9a
MD5 5b866d7d3012516f3b124330a31d7d33
BLAKE2b-256 fc63015c156b0048b793121e9159805ecaea3d2bc7aff893a4955288fce889a7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 b9df30848cfac4b0ebd7d134122174d6b20b5f6975a66da5670c70dc6f26a81e
MD5 e3825023c9c0fbcf23747686669d6167
BLAKE2b-256 4a0088580689996655948c0eb84936198459015c2414679619763eb7b5c20cff

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f55f744f25b24504acfefeb41e57cf90f44158e932cbbb6deca220a62e545b54
MD5 5587a7aa5b5218433ab237636c9d98e2
BLAKE2b-256 c56fc6d565d241a587e44f6454e09defeefb8315824de7954bac1b901b4c61c5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for band_sdk_core-0.7.1-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 960159353042ba9c2b44cb2c47fa3eb49df552f127308223c28cb258b46dc8dd
MD5 49555c35feff24969284952dac1d919d
BLAKE2b-256 e4025095245e52ded2b4bcdbf26c656c23a95a9b705c3a3da4e28d62ade701a1

See more details on using hashes here.

Provenance

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

1.0.1

8 files

1.0.0

8 files

0.8.0

8 files

0.7.2

8 files

This release

0.7.1 This release

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