card: the b-collective shipped with NO README. Adds the native 8-task table (.6031 -> .7294, BIOSSES inverts favourably vs v2), the trunk-bound decomposition (port -.0424, keys recover 29%, retrain recovers all), alignment health, and the final_model.pt-vs-best_model.pt root distinction between the two repos

amoe/b-collective/README.md

@@ -0,0 +1,137 @@
+---
+license: mit
+tags: [amoe, adapter, mixture-of-experts, sentence-similarity, captionbert, aleph]
+base_model: AbstractPhil/captionbert-8192-v2-B
+library_name: amoe-lora
+---
+
+# captionbert-8192-v2-B :: AMOE 3-anchor collective (native)
+
+Three [amoe-lora](https://github.com/AbstractEyes/amoe-lora) aleph anchors trained
+on the **frozen** `captionbert-8192-v2-B` trunk, under a trained dispatch. The
+trunk never moves; only the adapters and the routing keys train.
+
+This folder exists because of a negative result: **the sibling trunk's anchors do
+not port here.** Both the ported set and the natively retrained set ship, so the
+comparison is reproducible.
+
+| file | what it is |
+|---|---|
+| `captionbert-b-arms-native.dispatch.pt` | **the ship** -- anchors retrained on -B |
+| `captionbert-b-arms-realigned.dispatch.pt` | v2's anchors, routing keys re-aligned on -B |
+| `equiv/simplify/paraphrase.anchor.pt` | the natively trained anchors |
+
+## Results -- 8 tasks, Spearman rho
+
+Single-anchor columns are **masked** reads (collective with the other two arms
+disabled). Masking never renormalizes the amplitude budget, so a masked single is
+not the same measurement as that anchor run alone.
+
+| task | OFF | `equiv` m | `simplify` m | `paraphrase` m | **COLLECTIVE** | v2's collective |
+|---|---|---|---|---|---|---|
+| STS-B   | .5752 | .7219 | .5995 | .6137 | **.7675** | .7684 |
+| SICK-R  | .6548 | .7200 | .6603 | .6612 | **.7374** | .7391 |
+| STS12   | .5012 | .6381 | .5266 | .5177 | **.6706** | .6682 |
+| STS13   | .6037 | .6890 | .6325 | .6361 | **.7381** | .7557 |
+| STS14   | .5470 | .6410 | .5760 | .5808 | **.6945** | .6921 |
+| STS15   | .7146 | .7793 | .7402 | .7325 | **.8109** | .8055 |
+| STS16   | .6782 | .7143 | .6896 | .7325 | **.7695** | .7626 |
+| BIOSSES | .5500 | .5702 | .5789 | .5612 | **.6472** | .6382 |
+| **mean** | **.6031** | .6842 | .6254 | .6295 | **.7294** | .7287 |
+| mean erank | 30.47 | 35.33 | 34.74 | 33.78 | **44.33** | 45.00 |
+
+With native anchors this trunk reaches **.7294**, against v2's .7287 -- a tie,
+and on **BIOSSES it inverts favourably** (.6472 vs .6382). "-B is worse out of
+domain" was an artifact of foreign anchors, not a property of the trunk.
+
+Note the bare trunk reads **.6031** here versus v2's .6077, despite -B training
+on 19% more corpus (66/66 chunks, ~33M rows, against v2's 56). **More data bought
+nothing.** The ceiling is teacher agreement, not corpus size: the consensus
+target uses only ~28.7 of 768 directions.
+
+## Why this folder exists: anchors are trunk-bound
+
+The two trunks are indistinguishable on every capability gauge available -- 8 STS
+tasks within +/-.0042 excluding the 100-row BIOSSES, erank 36.6 vs 36.1, self_cos
++.1396 vs +.1411. They are *not* indistinguishable to a 1.6M-parameter adapter:
+
+| configuration | 8-task mean |
+|---|---|
+| v2's arms on the v2 trunk | .7287 |
+| v2's arms on -B, unchanged | .6863 |
+| + routing keys re-aligned on -B (800 steps, anchors frozen) | .6987 |
+| **anchors retrained natively on -B** | **.7294** |
+
+Porting costs **.0424**. Re-aligning the keys recovers **.0124 -- 29%**.
+Retraining the anchors recovers all of it.
+
+**So 71% of transfer loss lives in the anchors, 29% in the routing keys.**
+Adapters read the *residual stream*; task gauges read the *pooled output*. The
+stream carries trunk identity the output does not, which makes an adapter a more
+sensitive instrument for trunk identity than the entire STS suite.
+
+Preregistered bars for the realignment stage were PASS >= .7100 and
+PARTIAL >= .6980; it landed .6987 -- **PARTIAL**.
+
+**Reusing anchors across trunks is a silent ~31% loss. No error, no warning.**
+That is why `modeling_captionbert.py` resolves the arms repo from the model's own
+identity rather than a hardcoded constant.
+
+## Alignment health (native stage)
+
+Mean `|w/z|` .4987 / .1944 / .1810 -- sum **.874**, matching the conserved
+amplitude-budget prediction. Usage .39 / .30 / .31, zero starvation strikes.
+Anchor drift plateaued (equiv .147 rad, paraphrase .110, simplify .081).
+
+## Load
+
+The model resolves its own arms -- this is the supported path, and on this repo
+it selects the native dispatch:
+
+```python
+from transformers import AutoModel
+model = AutoModel.from_pretrained("AbstractPhil/captionbert-8192-v2-B",
+                                  trust_remote_code=True)
+model.attach_amoe()                      # -> amoe/b-collective/...native.dispatch.pt
+emb = model.encode(["a cat on a windowsill"])
+with model.amoe_off():                   # the unsupervised baseline
+    base = model.encode(["a cat on a windowsill"])
+model.detach_amoe()                      # bit-exact restore, asserted
+```
+
+Explicitly, via amoe-lora:
+
+```python
+import amoe
+h = amoe.attach(trunk, ["amoe/b-collective/equiv.anchor.pt",
+                        "amoe/b-collective/simplify.anchor.pt",
+                        "amoe/b-collective/paraphrase.anchor.pt"],
+                dispatch="amoe/b-collective/captionbert-b-arms-native.dispatch.pt",
+                binding=CaptionBertV2Binding(d=512))   # from modeling_captionbert.py
+base = h.detach()        # bit-exact or raises
+```
+
+The trunk these anchors expect is **`checkpoints/final_model.pt`**, which is what
+this repo's root `model.safetensors` carries (verified tensor-for-tensor, max
+absolute delta 0.0). Note the sibling v2 repo ships `best_model.pt` at its root
+instead -- each repo's arms match its own root, but the two roots are selected by
+different criteria, so do not mix a trunk from one with arms from the other.
+
+All anchors disabled reproduces the bare trunk **bit-exact** (asserted at build
+time). Masking never renormalizes -- that is the damping law, not an oversight.
+
+Anchor `.pt` key layout is `{block}.{param}`. (`blocks.{site}.{param}` in the
+amoe README is the *safetensors* layout, a different serializer.)
+
+## Training
+
+Anchors: MNRL, in-batch + hard negatives where the source provides them, 1,500
+steps at batch 256, pure Adam wd=0 (`amoe.laws.make_optimizer`), fp32 / TF32 off
+(`amoe.laws.pin_precision`). Trunk frozen throughout. Dispatch: 800 steps,
+routing keys only, anchors frozen, starvation safeguard armed. tau 0.1.
+
+Budget for a fresh trunk: **~18 minutes** (3 anchors x 1,500 steps, plus the
+800-step keys-only alignment).
+
+SICK-R and BIOSSES are never trained on and are the honest transfer reads.
+Every number above is in `metrics.json`.