1-bit Quantization + BIT Beacons

Compact, verifiable BIT blobs for semantic vectors with TLVs, HMAC authentication, and CLI tools for drift beacons and routing keys. Optional eval integration to emit beacons over last-token logits during perplexity runs.

Features

• MU16 BIT format with CRC16 and TLV header
• TLVs: CONFIG_V1, FLAGS_V1, END; plus
  • CALIB_STATS_V1 (μ, Σ, W, [t0,t1])
  • RESULTS_V1 (JSON metrics: norm_dmu, cos_mu, tr_Sigma, SDS, thresholds)
  • HMAC_V1 (HS256 over ctx + TLVs (ex-HMAC, ex-END) + payload)
• Authenticated beacons (--hmac_key_hex)
• Routing key CLI (BLAKE2b-256 over header||payload, optional sharding)
• Verify CLI: CRC + HMAC
• Eval integration: emit drift beacons over logits window

Quickstart

Install deps:

python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt

Run tests (skip vendor suites):

PYTHONPATH=. pytest --ignore=quant/vendors

Emit a Drift Beacon from a matrix of vectors

PYTHONPATH=. python3 tools/drift_beacon.py \
  out/beacon_window.npy out/drift_beacon.bit \
  myspace mymodel mypi \
  --delta_q16 1024 \
  --sds_w_mu 1.0 --sds_w_trS 0.5 \
  --hmac_key_hex $(openssl rand -hex 32)

Verify a BIT blob (CRC + HMAC)

PYTHONPATH=. python3 tools/verify_bit.py out/drift_beacon.bit --hmac_key_hex <hex>

Compute routing key and optional shard

PYTHONPATH=. python3 tools/query_router_key.py out/drift_beacon.bit --shards 64

Emit beacon during evaluation

PYTHONPATH=. python3 eval/perplexity.py \
  --model TinyLlama/TinyLlama-1.1B-Chat-v1.0 \
  --quant ours --max-samples 256 \
  --beacon-out out/eval_logits_beacon.bit \
  --beacon-max 128 \
  --beacon-delta-q16 1024 \
  --beacon-sds-w-mu 1.0 --beacon-sds-w-trS 0.5 \
  --beacon-hmac-key-hex <hex>

Format Details

• Magic: "BIT\x01"
• ctx_hash64(space_id, model_id, pi_id, dim) is 64-bit blake2b of canonical JSON
• TLVs are big-endian: 1B type, 2B length, then value
• Payload: int16 array (MU16 quantization), little-endian platform order
• CRC16-CCITT over header (ex-magic) and payload
• HMAC_V1: 01 || HMAC_SHA256(key, ctx(8)+TLVs(no HMAC/END)+payload)

Modules

• braille_quant/io/bit.py – BIT packing/unpacking, TLVs, HMAC, validators
• tools/drift_beacon.py – compute windowed stats and emit beacon
• tools/verify_bit.py – CRC and HMAC verification
• tools/query_router_key.py – routing/sharding key
• eval/perplexity.py – optional beacon emission over logits

Interop with SCL (Semantic Compression Language)

Export BIT beacon Gaussian moments to SCL .npz and import back:

# Export: BIT (.bit) -> SCL Gaussian (.npz with mu,Sigma,W,t0,t1)
PYTHONPATH=. python3 tools/scl_export.py out/drift_beacon.bit out/scl_gaussian.npz

# Import: SCL Gaussian (.npz) -> BIT (.bit) with CALIB_STATS_V1 (+ RESULTS_V1)
PYTHONPATH=. python3 tools/scl_import.py \
  out/scl_gaussian.npz out/scl_imported.bit \
  myspace mymodel mypi \
  --delta_q16 1024 \
  --hmac_key_hex <hex-optional>

Notes:

• Export prefers CALIB_STATS_V1 if present; otherwise derives mu from payload and uses zero Sigma.
• Import validates shapes and emits minimal RESULTS_V1 with tr_Sigma for convenience.

License

Apache-2.0 (suggested). Update LICENSE if different.

CI

Minimal CI runs pytest --ignore=quant/vendors on push/PR.