Crate bytesandbrains 

bytesandbrains

Composable building blocks for decentralized + federated machine learning. Facade crate re-exporting bb-ir, bb-dsl, bb-compiler, bb-runtime, bb-ops, and bb-derive. See docs/ for the canonical spec.

Re-exports

pub use install::install;

pub use install::Config;

pub use install::InstallError;

pub use bb_ir::bincode;

pub use bb_ir::inventory;

pub use bb_compiler as compiler;

pub use bb_ops as ops;

Modules

aggregators

Concrete Aggregator implementations the framework ships (e.g. FedAvg). Concrete Aggregator Contract implementations the framework ships out of the box. Each impl bridges the user-facing bb_runtime::contracts::Aggregator trait to the engine’s dispatch_atomic path through the bb_derive::Aggregator macro and self-registers via inventory::submit!.

atomic

Atomic dispatch declaration types + DispatchResult. Catalog declarations stay in bb-ir; DispatchResult carries CommandId and so lives here. AtomicOpsetDecl, AtomicOpDecl, AtomicOpKind, DispatchResult. Engine-side atomic dispatch result. Catalog types (AtomicOpsetDecl, AtomicOpDecl, AtomicOpKind) live in bb_ir::atomic; re-exported here for one-import access.

backends

Concrete Backend implementations the framework ships (CpuBackend + the execute_graph walker that drives a GraphProto through it). Concrete backend implementations. Each backend (cpu, cuda, …) is one self-contained unit under bb_ops::backends::<name>.

bus

Typed in-Node event bus. Typed in-Node event bus. Typed in-Node event bus. Cross-Component signaling per docs/ENGINE.md §13.1.

completion

CompletionHandle for async Contract methods. CompletionHandle, CompletionSink, ContractResponse. CompletionHandle for async Contract methods. Implementations call [CompletionHandle::complete]; the handle routes through a [CompletionSink] (typically IngressQueue), which the engine drains on its next poll to unpark the suspended op.

component

ErasedComponent + AnyComponent traits + foundation polymorphism plumbing (ComponentPackage, RestoreError, SerializeFn, RestoreFn). Foundation polymorphism plumbing shared by bb-dsl (authoring) and bb-runtime (dispatch).

concrete

ConcreteComponent polymorphism contract + the ComponentHandle fn-pointer-capture wrapper. ConcreteComponent polymorphism contract — canonical home in bb-runtime::concrete. This module re-exports the type for authoring ergonomics so bb_dsl::concrete::ConcreteComponent keeps resolving.

contracts

User-facing Contract traits (Index, Aggregator, Model, Codec, DataSource, PeerSelector, Backend, Protocol). User-facing Contract traits — canonical home is bb-runtime::contracts. This module re-exports the traits for authoring ergonomics so bb_dsl::contracts::Index etc. keep resolving.

engine

The sans-IO Engine state machine. The sans-IO Engine state machine. The sans-IO Engine state machine

envelope

WireEnvelope codec; per-type decoders register through bb_ir::slot_value::register_type_node!. WireEnvelope codec; per-type decoders register through bb_ir::slot_value::register_type_node!. WireEnvelope codec

errors

Public error taxonomies. Public error taxonomies. Public error taxonomies surfaced by the user-facing API.

exec_state

Per-poll execution-state bundle owned by Engine.exec. ExecState — per-poll execution-state bundle (frontier, slot table, pending state, scheduler, inbound contexts, monotonic ID allocator). Owned by Engine as one field. ExecState — the engine’s per-poll execution-state bundle.

fallible

Test-only components, gated behind the test-components feature. Thread-local try_reserve_exact fault-injection seam. Exposed under test-components so integration tests in tests/ drive the same seam as crate-internal sibling tests. try_reserve_exact wrapper at ingress boundaries so allocator failures surface as typed events. fallible::testing is a stub-allocator seam under test-components. Fallible Vec::try_reserve_exact wrapper used at engine ingress boundaries per docs/internal/superpowers/specs/2026-06-24-engine-boundary-fallibility-and-backend-owned-tensors.md §1 (Principle 1) + §2.1 sites S4 / S5.

framework

Framework primitives bundled into every RuntimeResourceRef. Framework primitives bundled into every RuntimeResourceRef. 9 framework primitives the engine bundles into the RuntimeResourceRef for every dispatch_atomic call per docs/ENGINE.md §10 + docs/internal/IMPLEMENTATION_PLAN.md //! lines 770-779.

graph

Graph recording context. Recording context wrapping the in-progress FunctionProto. The proto is the IR — semantic BB attributes ride on proto fields, not a parallel Rust shadow store. See docs/IR_AND_DSL.md §2.

ids

Identity newtypes. Engine-internal IDs (NodeSiteId, OpRef, ExecId, CommandId, ComponentRef) live here; wire/compiler IDs (PeerId, RequestId, OpsetId, ComponentTag) come from bb-ir re-exported through this module. Engine identifier types — PeerId, NodeSiteId, OpRef, ComponentRef, ExecId, CommandId, RequestId, OpsetId, ComponentTag. Engine-internal IDs. Wire/IR IDs come from bb_ir::ids re-exported here for a single import surface.

ingress

Lock-free MPMC ingress queue. Lock-free MPMC ingress queue. Lock-free MPMC ingress queue.

install

bb::install — single Node construction entry point.

keys

Framework attribute-key string constants (BACKEND_SUBGRAPH_BODY_ATTR, WIRE_TRANSPORT_KEY, …). Re-exported so proc-macro emission reaches them without users depending on bb-ir directly. Single source of truth for metadata-key string constants shared across DSL → Compiler → Runtime. Reference these constants rather than re-typing "ai.bytesandbrains.*" literals.

module

The Module trait. Module::build() returns a recorded ModelProto that Compiler consumes. The Module trait. Module::build() produces one pre-compile ModelProto where functions[0] is the top-level body and functions[1..] are composed sub-Modules (deduped by name()).

node

Public Node + lazy build chain. Public Node + lazy build chain. Node — the framework’s runtime construct, installed via [bytesandbrains::install] and driven through Node::poll.

output

Non-generic Output handle threaded through DSL method chains. Non-generic Output handle threaded through DSL method chains.

peer_class

Peer-class metadata stamps (SELF_CLASS, PEER_CLASS_KEY, HOME_CLASS_KEY). Peer-class metadata for partitioning by “what kind of Node does this op run on.” PEER_CLASS_KEY tags Output<PeerId> producers; HOME_CLASS_KEY tags each NodeProto with the class of Node it runs on (stamped by infer_peer_classes).

placeholders

Role-method dispatch slot placeholders (BackendSlot, IndexSlot, ModelSlot, …). Module fields are typed against these; the compiler binds them to concrete implementations. Role-method dispatch slot placeholders. Each *Slot unit struct is a generic slot bound at compile time via Compiler::new().bind_<role>::<T>("slot"). DSL methods record NodeProtos stamped with (required_trait, slot_id) for binding-resolution routing.

prelude

Canonical authoring surface in a single import.

proto

Prost-generated proto bindings (ONNX + bb.core). Prost-generated proto bindings.

protocols

Concrete Protocol implementations the framework ships (e.g. GlobalRegistryClient, GlobalRegistryServer). Protocol implementations - <Role>Runtime bridges for concrete coordination protocols. Each lives in a sub-directory and self-registers via inventory::submit! per the standard component-authoring contract.

recorded

RecordedModule — the DSL → Compiler hand-off produced by Graph::finish(). RecordedModule - the compiler’s input type.

registry

Global inventory-collected registry for custom ops + concrete components. Proc-macros emit ::bytesandbrains::registry::* paths into this namespace. Global inventory-collected registry for custom ops. Global registries collected via inventory.

roles

The <Role>Runtime role traits. The <Role>Runtime role traits. Framework-internal engine-side <Role>Runtime traits.

runtime

Runtime resource handle + ComponentTimerKind. Runtime resource handle + ComponentTimerKind. Runtime resource handle threaded into every dispatch_atomic call.

slot_value

Universal slot value trait. Re-exports bb_ir::slot_value plus engine-side carriers (BackendTensorCarrier) that bypass the serde-driven blanket impl. The universal SlotValue trait. The universal SlotValue trait — every value flowing through slot sites (DSL outputs, wire payloads, syscall returns, role-method returns) implements it via the blanket impl<T: Tensor> SlotValue and per-primitive impls.

snapshot

NodeSnapshot. NodeSnapshot. NodeSnapshot

syscall

ai.bytesandbrains.syscall v1 opset (runtime-side dispatch + DSL-side helpers). Foundation SlotValue impls - PeerIdValue, WireReqIdValue, TriggerValue, BytesValue, CommandIdValue. Foundation SlotValue impls - PeerIdValue, WireReqIdValue, TriggerValue, BytesValue, CommandIdValue. The polymorphism layer every syscall component consumes; kept in bb-runtime so components in bb-ops link against a single canonical source.

syscall_ids

Stable (domain, op_type) + attribute-name string constants for every framework syscall - the IR contract between bb-compiler + bb-runtime. Syscall identifier string constants — the IR-level contract between compiler (gate emission) and runtime (dispatch).

telemetry

Optional OpenTelemetry layer constructors for the engine’s tracing:: spans. Optional OpenTelemetry layer constructors for the engine’s tracing:: spans. Optional OpenTelemetry layer constructors for the engine’s tracing:: spans.

tensor

Tensor and Scalar abstractions. Backends implement. Tensor + Scalar abstractions. The framework crate ships no concrete tensor type; backends implement these traits over their own storage of choice.

types

Polymorphic type system — hierarchical TypeNode tree resolved at compile time by the bb-compiler’s TypeSolver. Hierarchical type system resolved at compile time by the compiler’s TypeSolver. The tree is open via inventory: backends and DSL authors register new leaves via inventory::submit!. The Lattice is built once at startup; is_subtype_of walks the parent chain with caching. The runtime never sees abstract types.

wire

Wire codec contract + canonical TypeNode statics (TYPE_TENSOR_F32, TYPE_TRIGGER, TYPE_PEER_ID, …). Wire codec hash helper.

Macros

register_op

register_op!{} proc-macro re-exported from bb-derive. Register a custom op with the global inventory.

register_protocol

register_protocol!{} proc-macro re-exported from bb-derive. Declarative macro emitting a complete ProtocolRuntime impl from a struct + opset + ops block.

Structs

Address

Multiaddr - a sequence of typed Protocol segments describing a delivery path. Per docs/ADDRESSING.md, this is BB’s canonical address type: the suffix segments tell the receiver where to route inside its own node, so no per-message-type or per-endpoint-id lookup tables are needed.

BootstrapInput

Host-supplied bootstrap input staging request — borrowed shape. The host hands the engine a target name plus an ordered (input_name, value_bytes) slice; the engine validates against the target’s declared formal input ports and runs the Principle 1a copy (cap-check → try_reserve_exact → extend_from_slice) so the caller’s borrowed buffers can drop the moment crate::node::Node::run_bootstrap returns.

Compiler

The single compile entry point.

EngineStats

Point-in-time hot-path counters for dashboards + saturation detection. Not synchronized against an in-flight poll cycle.

GenericSlotSpec

Description of a generic placeholder slot the user must bind at Node construction via with_<role>(impl).

Graph

Recording context every DSL method writes into.

IngressQueue

Lock-free MPMC ingress queue + waker. Multiple external producers may push concurrently; the engine’s single consumer drains via drain_all on each poll cycle.

IngressQueueRef

Cheap-clone handle to the shared IngressQueue surfaced by crate::node::Node::ingress_handle. Behaves identically to Arc<IngressQueue> via Deref so callers can .push(IngressEvent::...) directly. The newtype wrapper isolates the public API from the underlying smart-pointer choice.

Node

Constructed BB Node ready to drive ML work. Produced by [bytesandbrains::install] — by the time the host holds one, the engine has resolved its dispatch table, registered every bound concrete, and installed the target function as the root graph.

NodeConfig

Construction-time configuration for a Node.

NodeSnapshot

Top-level snapshot per ENGINE.md §15.1.

Output

Handle passed between DSL methods. Carries the recorded ONNX value name plus a &'static pointer to the canonical TypeNode of the value’s type.

PeerId

Peer identity. Wraps a fixed-capacity Multihash<64> so overlays pick their own digest algorithm. Same wire shape as libp2p_identity::PeerId; bytes round-trip without translation.

TransientSnapshot

Runtime ephemeral state per ENGINE.md §15.1.

TypeNode

Static type-identity carrier. Identity is pointer equality; subtype queries route through Lattice.

Enums

BuildError

Recording-time errors. Compile-time errors come from the compiler.

DeliveryError

Errors surfaced by host-facing delivery methods on Node.

EngineStep

One step of work the engine performed during a poll cycle. Engine::poll returns Vec<EngineStep> capturing every event the host can observe.

IngressEvent

External-event variants pushed to the ingress queue per docs/ENGINE.md §6 entry points.

RestoreError

Errors surfaced by Node::restore (the public surface arrives in the commit that lands src/node.rs).

Statics

TYPE_PEER_ID

Concrete PeerId - canonical peer identifier (multihash).

TYPE_TENSOR_F32

Concrete Tensor<F32> - dense f32 tensor.

Traits

Aggregator

User-facing Contract trait for a federated/decentralized aggregator. The derive bridges these methods to the engine’s crate::roles::AggregatorRuntime trait.

Backend

User-facing Contract trait for a tensor compute backend.

Codec

User-facing Contract trait for a typed in/out storage codec.

DataSource

User-facing Contract trait for a data source / data loader.

Index

User-facing Contract trait for a vector index.

Model

User-facing Contract trait for an ML model.

Module

Unit of composition. Implement name() + body(); framework supplies op() and build(). Body declares inputs via g.input("name") and emits via g.output("name", value) (local) or g.net_out("name", peers, value) (network).

PeerSelector

User-facing Contract trait for a peer-selection protocol.

Functions

address_book_insert_many

Record an AddressBook::InsertMany(peer, addresses) custom-op NodeProto into a Graph. New peer creates an entry with ref_count = 1; known peer dedupe-appends every address without touching ref_count. Empty addresses vec surfaces as a dispatch-time OpError.

address_book_lookup

Record an AddressBook::Lookup(peer) custom-op NodeProto into a Graph. Output carries the full ordered TYPE_ADDRESS_VEC; callers that need a single address pick one downstream. Unknown or empty-address peer surfaces as a dispatch-time OpError.

announce

Record a GlobalRegistryClient::Announce NodeProto. The client reads ctx.local_addresses() automatically, throttles sub-interval calls to the server’s last advertised heartbeat interval, and merges the server’s address bag from the Handshake reply.

constant

Record a typed Constant syscall NodeProto. Bootstrap-stage constants seed the AddressBook + GlobalRegistry ops with the server’s PeerId and dial bag at install time. The compiler’s expand_constant pass requires value: TensorProto; this helper satisfies that contract with an empty tensor sized for the declared scalar kind.

gate_dispatch

Record a GateDispatch syscall NodeProto into a Graph - a multi-edge synchronization barrier.

pass_through

Record a PassThrough syscall NodeProto into a Graph.

Derive Macros

Aggregator

#[derive(bb::Aggregator)] — bridges a Contract impl to AggregatorRuntime. Derive bb::Aggregator bridge.

Backend

#[derive(bb::Backend)] — bridges a Contract impl to BackendRuntime and emits the ai.onnx v1 opset declaration. Derive bb::Backend bridge - emits the ai.onnx v1 51-op opset declaration; dispatch_atomic forwards into Backend::execute.

Codec

#[derive(bb::Codec)] — bridges a Contract impl to CodecRuntime. Derive bb::Codec bridge - emits ConcreteComponent + CodecRuntime.

Concrete

#[derive(bb::Concrete)] — emits the ConcreteComponent

DataSource

#[derive(bb::DataSource)] — bridges a Contract impl to DataSourceRuntime. Derive bb::DataSource bridge.

Index

#[derive(bb::Index)] — bridges a Contract impl to IndexRuntime. Derive bb::Index bridge - emits ConcreteComponent, AnyComponent, IndexRuntime, and inventory::submit!.

Model

#[derive(bb::Model)] — bridges a Contract impl to ModelRuntime. Derive bb::Model bridge.

PeerSelector

#[derive(bb::PeerSelector)] — bridges a Contract impl to PeerSelectorRuntime. Derive bb::PeerSelector bridge.