A polymorphic, LLM-backed ranker for catalog-aware recommendations. Every backbone, store, reward, and loss is a registered concrete — swappable from one config, runnable from one CLI.
braid ships four backbones, four catalog stores, three verbalizer families, five real rewards, six loss terms, seven evaluators, and four drift detectors — all reachable through one dispatch.
Backbones, catalog stores, verbalizers, rewards, losses, evaluators, routers — every component is a registered concrete dispatched through `braid.registry.create(category, name, **cfg)`.
`braidedloss` combines ranking-CE, L-max, diversity entropy, and reward-weighted terms into a single trainable scalar — without silent fallbacks.
Scoring is `h @ E.T` over embeddings. Swap in `matmulinmem`, `matmulint4awq`, `faissivfstore`, or RQ-VAE semantic IDs from one config field — same dispatch API.
Long-term return, diversity bonus, novelty, content-type balance — and a `composite` that weighted-sums them at training time. All real implementations, not stubs.
Every concrete in braid opts in to the same eight layers. Capabilities, traits, observability, and a fail-fast error model compose into a single uniform surface — the spine.
create(category, name, **cfg)
streamable · cachable · persistable · observable · idempotent · distributable · teachable · asyncable
setup · warmup · shutdown · health
gpu · async · fusedkernel · int4quantize · distributable · teachable
configmigrator walks configs between versions
item · event · context · prompt · rankrequest/response (versioned)
obsgen → Prometheus rules + Grafana JSON + metric catalogue
requestcontext flows through every layer
Every subcommand resolves a concrete. Inspect any component. Dryrun a config without executing. Generate observability assets with one command.
$ python -m braid dryrun \\
--config configs/train/phase2.yaml
"wouldinstantiate": [
"category": "backbone", "name": "minicpm5" ,
"category": "catalogstore", "name": "matmulinmem" ,
"category": "loss", "name": "braidedloss" ,
"category": "rewards", "name": "composite"
],
"maxsteps": 8000,
"resolves": true
$ python -m braid inspect \\
catalogstore matmulinmem
name matmulinmem
category catalogstore
version 1.0.0
module braid.catalogstore.matmulinmem
capabilities distributable, observable
methods:
build
metrics
numshards
observability
score
shardrank
warmupEvery concrete is real. Every capability is declared. Inspect, swap, and compose them at runtime — or extend the registry from your own entry points.
Continued-pretraining and ranking heads for MiniCPM-5, Llama 3.2, Qwen 2.5, and Pythia-1B.
Matmul, int4 AWQ, FAISS IVF, and RQ-VAE semantic-id stores — all gated by `h @ E.T`.
Long-term return, diversity bonus, novelty, content-type balance — and a composite that weighted-sums them.
Ranking-CE, L-max, calibration, reward-weighted, diversity-entropy — and `braidedloss` to combine them.
Offline ranking, calibration, diversity, replay, interleaving, baseline — plus a composite with bootstrap CI.
PSI, Kolmogorov-Smirnov, Jensen-Shannon divergence, and Page-Hinkley — all detectable from the registry.
Drop in a new backbone, reward, or loss without forking the training loop. The conformance harness reports pass / fail-fast across all 147 concretes.
A FastAPI app with `/rank`, `/metrics`, `/health`, `/ready`. Lifecycle hooks, typed errors, prefix KV-cache, drift-aware routers.
Composite rewards and braided losses let product, growth, and policy teams share one ranker without rule soup. Inspect every weight at runtime.
Bootstrap a working environment, inspect the registry, dryrun any config, then start ranking — without Kubernetes, without Kafka, without a separately-licensed inference engine.
$ git clone https://github.com/sachncs/braid
$ cd braid && make bootstrap
$ make list # 44 categories × 147 concretes
$ make conformance # 131 / 147 real-pass
# python -m braid serve → :8080