@soulcraft/brawn (1.0.0)
Installation
@soulcraft:registry=npm install @soulcraft/brawn@1.0.0"@soulcraft/brawn": "1.0.0"About this package
brawn
brawn is the model runner every Soulcraft product's models can run on:
embedding, rerank and two streaming speech doors, served from one binary over
a private address. The tokenizer it embeds with is part of the identity
/health publishes, not a door of its own — there is no token-counting
endpoint in 1.0.
Brainy — the database engine — runs its models in-process by default; no
product requires brawn to work. brawn is optional acceleration: point an
engine at a running brawn and it offloads bulk embedding (and, with the
speech feature, transcription and synthesis) to whatever hardware brawn
runs on, CPU or GPU, with an identity handshake and an equivalence gate
proving the remote vectors are the engine's own before a single row is
routed to it. No answer, or a failed gate, and the engine keeps serving
everything itself — brawn is never a dependency, only a speed-up.
Status
1.0.0 — brainy's services/embed-service, split out as its own project
(decisions own-by-domain-not-by-language, brawn-model-runner,
2026-09-11), history preserved via git subtree split. Same doors, same port
default, same feature flags, same environment variables as that binary;
renamed to its own crate, binary and package identity. See CHANGELOG.md for
what did and did not move.
What 1.0 is
- The four serving doors of brainy 11.4's model service —
GET /health,POST /v1/embed,POST /v1/rerank, and (built with--features speech)GET /v1/speech/healthplus the two WebSocket doorsGET /v1/transcribeandGET /v1/synthesize— one process, one port, one bearer token, one licence. - Three published packages:
@soulcraft/brawn(this resolver CLI),@soulcraft/brawn-linux-x64-gnu(the CPU binary, built with thespeechfeature), and@soulcraft/brawn-linux-x64-gnu-cuda(one binary per compute capability —sm_89andsm_120— plus the two ONNX Runtime execution-provider shared objects andCAPS.txt). - The licence verifier and the embedding model's identity read from brainy's own crates, pinned by revision — no second copy of either law.
What 1.0 is not
- No chat lane. Chat and completion serving arrives in 1.1, on Anima's chat contract; nothing in this release serves a generative model, and no door is reserved for one.
- No Kokoro CANDLE port. Synthesis runs on the ONNX Runtime path exactly as brainy 11.4.x shipped it. The pure-candle port is a separate verdict that has not been made.
- No weights. Neither the embedding model nor a speech model ships in any of the three packages; the embedding assets are resolved from the paired engine install and the speech models stay Anima's mounted artifact.
- No token-counting door, and no
/v1/tokens. The tokenizer's digest is published on/healthas identity; counting is not a service this release offers. - One platform. Linux x64 (glibc). Every other platform is refused by name — never a silent CPU fallback, never a download at run time.
Build and test
cargo build --release
cargo test --release # embedding + rerank doors
cargo build --release --features speech
cargo test --release --features speech # + the two speech doors
cargo build --release --features cuda # GPU inference (needs nvcc + CUDA headers)
The licence verifier and the embedding model's identity come from brainy's
own crates — brainy-license and brainy-model-identity, git dependencies
pinned to an immutable brainy revision in Cargo.toml (decision
brawn-shared-crates, 2026-09-11). The build needs read access to
soulcraft/brainy on The Source and nothing else; there is no paired
checkout to place, no BRAWN_BRAINY_REPO to set, and no second copy of
either law in this tree. The pin is a revision, never a branch, so a
published binary is reproducible from the tree that made it.
What build.rs still bakes is the one identity fact that was always brawn's
own: the Whisper and Kokoro provenance, from this crate's own
speech-models.json.
The speech feature's own pins additionally need a mounted voice-models
fixture: BRAINY_SPEECH_ASSETS=<dir> (or BRAWN_SPEECH_ASSETS=<dir> — both
names are read identically) pointing at a directory holding MODELS.sha256
and the Whisper/Kokoro model files docs/speech-doors.md describes. Without
one, only the speech tests that do not need a loaded model run.
The doors
GET /health, POST /v1/embed, POST /v1/rerank, and — with --features speech — GET /v1/speech/health, GET /v1/transcribe (WebSocket), GET /v1/synthesize (WebSocket). Full contract: docs/embed-service.md (the
operator page) and docs/speech-doors.md (the public protocol page).
Identity and licensing
brawn serves the exact model the brainy engine ships and proves it at every
start: the expected asset digests come from brainy-model-identity, the
engine's own crate, and the service hashes what it resolved and refuses to
run on any mismatch. It shares the engine's licence verifier the same way —
brainy-license, one implementation of one law — and refuses to LISTEN
without a valid key, before it binds a socket and before it loads a model.
A key is read from $BRAINY_LICENSE (or the legacy variables), then from
~/.config/soulcraft/brainy-license. There is no degraded mode.
Licensed under the terms in LICENSE — a commercial licence, not MIT.
The equivalence gate
scripts/equivalence.mjs is the conformance pin: it embeds the same sample
texts through a running brawn and through the paired engine's own native
embedder and asserts the vectors match (bit-for-bit on CPU, within a stated
tolerance for a GPU build against the CPU reference). Run it against a live
brawn --bind <addr>:
node scripts/equivalence.mjs --endpoint http://<addr> --token "$SOULCRAFT_SERVICE_SECRET"
Running it needs a built, paired engine checkout (BRAWN_BRAINY_REPO=<path>,
or a sibling ../brainy) for the reference side, and for a CUDA receipt a GPU
host.
MEASURED for 1.0.0, on the build box, against the packaged CPU binary: 6 of 6 rows bit-identical, worst component difference 0, worst cosine 0.9999999999999998, at tolerance 0 — bit equality, not a tolerance. The CUDA build's own receipt is taken on the GPU host it is deployed to, against this CPU reference.
Install
The @soulcraft scope lives on The Source, never on npmjs — point the scope at
it once, then install:
npm config set @soulcraft:registry https://source.soulcraft.com/api/packages/soulcraftlabs/npm/
npm install @soulcraft/brawn # the resolver CLI + the CPU binary
npm install @soulcraft/brawn-linux-x64-gnu-cuda # on a CUDA 13 / cuDNN 9 GPU host
npx brawn --bind 10.0.0.5:8200 # a private address; there is no default
npm install @soulcraft/brawn pulls whichever platform package matches the
host through optionalDependencies; a GPU host needs the CUDA package
installed explicitly, and npx brawn refuses by name (naming it) rather than
serving a GPU host from the CPU build.
Packaging
scripts/packages.mjs builds the platform-specific npm packages
(@soulcraft/brawn-linux-x64-gnu, @soulcraft/brawn-linux-x64-gnu-cuda) that
carry the prebuilt binary, its MANIFEST.sha256, the licence text and, for the
CUDA package, the two ONNX Runtime provider sidecars and CAPS.txt. npx brawn resolves and execs whichever one matches the host. No speech weight and
no embedding model weight is ever in one of these packages — see
docs/embed-service.md.
Published only to The Source, at the PUBLIC org's registry path
(https://source.soulcraft.com/api/packages/soulcraftlabs/npm/) — a Forgejo
package is exactly as visible as the org that owns it, and these packages are
customer-installable (decision brainy-public-package-home, 2026-09-12). The
names keep the @soulcraft scope and this repository stays private. Never
npmjs.
Dependencies
Development dependencies
| ID | Version |
|---|---|
| vitest | ^3.2.4 |
Optional dependencies
| ID | Version |
|---|---|
| @soulcraft/brawn-linux-x64-gnu | 1.0.0 |
| @soulcraft/brawn-linux-x64-gnu-cuda | 1.0.0 |