BrainPatch smoke_v0: SAE, feature database, experiment artifacts

ARTIFACTS.json

@@ -58,16 +58,20 @@
       "bytes": 5020
     },
     {
-      "path": "patches/experimental-feature-727-scheduled.json",
+      "path": "patches/research/experimental-feature-727-scheduled.json",
       "bytes": 1899
     },
     {
-      "path": "patches/experimental-feature-727.json",
+      "path": "patches/research/experimental-feature-727.json",
       "bytes": 4714
     },
+    {
+      "path": "patches/runtime/experimental-feature-727.brainpatch",
+      "bytes": 6523
+    },
     {
       "path": "README.md",
-      "bytes": 17573
+      "bytes": 16598
     }
   ]
 }

README.md

@@ -62,13 +62,14 @@ delta_raw = strength × unit_decoder_column / input_scale
 
 | Path | What |
 |---|---|
+| **`patches/runtime/*.brainpatch`** | **Portable runtime patches — 6.4 KB, self-contained, no SAE needed** |
+| `patches/research/*.json` | v0.1 research patches (reference SAE feature IDs; need the SAE) |
 | `sae/smoke_v0/sae_latest.pt` | SAE weights, optimizer state, liveness buffers, config |
 | `sae/smoke_v0/config.json` | Architecture and training configuration |
 | `sae/smoke_v0/metrics.jsonl` | Per-step training metrics |
 | `feature-db/smoke_v0/features.jsonl` | Per-feature statistics and top-activating contexts |
 | `activations/smoke_v0/manifest.json` | Corpus provenance (metadata only — no shards) |
 | `experiments/smoke_v0_intervention/` | All generations, metrics, and the report |
-| `patches/` | BrainPatch JSON files |
 
 The Qwen base weights are **not** duplicated here. Load them from [`Qwen/Qwen2.5-1.5B-Instruct`](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct) at revision `989aa7980e4cf806f80c7fef2b1adb7bc71aa306`.
 
@@ -78,85 +79,60 @@ Raw activation shards are not published: 58.8 MB derived from a CC BY-SA corpus,
 
 ## Usage
 
-Requires a CUDA GPU, `torch`, `transformers`, and the `brainpatch` package:
+**Most users want the portable patch, not the SAE.** A `.brainpatch` file is
+6.4 KB and self-contained; the 72 MB SAE checkpoint is a research artifact you
+only need if you are discovering new features.
 
 ```bash
-pip install torch transformers "brainpatch @ git+https://github.com/09Catho/BrainPatch.git"
+pip install "brainpatch[transformers,hub]"
+brainpatch install 09Catho/BrainPatch-Qwen2.5-1.5B:patches/runtime/experimental-feature-727.brainpatch
+brainpatch compare --model Qwen/Qwen2.5-1.5B-Instruct --patch experimental-feature-727 --prompt "Explain why the sky is blue."
 ```
 
-This snippet is **copy-paste runnable from a clean environment**. Both the SAE
-checkpoint *and* the patch file are fetched from this repository — nothing is
-assumed to exist on disk. It is verified end to end in a fresh Modal container
-by `modal run modal_app/app.py::verify_model_card_example`.
-
 ```python
-from huggingface_hub import hf_hub_download
-
 from brainpatch import BrainPatchedModel
 
-REPO = "09Catho/BrainPatch-Qwen2.5-1.5B"
-
-# Both artifacts come from the Hub. The patch is a small JSON file; the
-# checkpoint is ~72 MB. The Qwen base weights are downloaded by transformers.
-checkpoint_path = hf_hub_download(REPO, "sae/smoke_v0/sae_latest.pt")
-patch_path = hf_hub_download(REPO, "patches/experimental-feature-727.json")
-
 model = BrainPatchedModel.from_pretrained(
     "Qwen/Qwen2.5-1.5B-Instruct",
     revision="989aa7980e4cf806f80c7fef2b1adb7bc71aa306",
+    backend="transformers",
+    device="auto",
 )
-model.load_sae(checkpoint_path, reference="smoke_v0")
-
-# install() validates the patch against the loaded model and SAE, and raises
-# PatchCompatibilityError on any mismatch of model, revision, layer or SAE.
-model.install(patch_path)
-
-# set_patch_strength is a MULTIPLIER on the patch's own strength, not an
-# absolute value. This patch declares strength 16.0, so 1.0 keeps the effective
-# coefficient at 16 — the value the dose-response sweep found changes output
-# while fluency holds. See the warning below before raising it.
-model.set_patch_strength("experimental-feature-727", 1.0)
-
+patch = model.install("experimental-feature-727")   # installed above
+patch.strength = 1.0                                 # live, clamped to the patch envelope
 print(model.generate("Solve this problem: what is 17 + 25?"))
 ```
 
-`reference="smoke_v0"` must match the patch's `sae.reference` field; that is the
-check which stops feature IDs from one dictionary being applied to another.
-
-> **The multiplier compounds, and the model breaks well before you might expect.**
-> An earlier draft of this example used `1.5`, giving an effective coefficient of
-> 24. Run on Modal, that produced `"17 + 25 = 32"` — a wrong answer, followed by
-> a confused digression about the commutative property of *multiplication* —
-> where the unpatched model correctly answered 42.
->
-> That is not a bug; it is what a ~34% residual-stream perturbation does to a
-> 1.5B model. The measured sweep is in the dose–response table below: usable
-> around 8–16, looping at 32, collapse at 64. **Treat any strength you have not
-> measured as unsafe**, and check arithmetic and instruction-following whenever
-> you change it.
+`patch.strength = 0.0` recovers baseline **byte-identically** — verified on an
+L4 with 0 applied hook passes.
 
-Ad-hoc single-feature steering, no patch file needed:
+Token-level schedule (Transformers backend only):
 
 ```python
-model.add_feature(layer=18, feature_id=727, strength=16.0)
+patch.schedule = {0: 0.0, 24: 1.0, 48: 2.0}
 ```
 
-Dynamic mid-generation steering, keyed on **generated**-token index:
+No Modal, no hosted service, and no network once the model and patch are local.
 
-```python
-from brainpatch.steering import StrengthSchedule
-
-model.set_patch_schedule(
-    "experimental-feature-727", StrengthSchedule({0: 0.0, 24: 1.0, 48: 2.0})
-)
-```
+### Verified runtime properties
 
-To recover the baseline, either uninstall the patch or set its strength to zero
-— the two are byte-identical by construction:
+Measured by `modal run modal_app/app.py::test_transformers_backend` on
+Qwen2.5-1.5B-Instruct / NVIDIA L4:
 
-```python
-model.set_patch_strength("experimental-feature-727", 0.0)
-```
+| check | result |
+|---|---|
+| weights frozen and unchanged after patched generation | pass |
+| `strength = 0` byte-identical to baseline | pass (0 applied passes) |
+| non-zero strength changes output | pass |
+| measured delta norm vs expected | **28.5177 == 28.5177** |
+| token schedule fires at keyframe | pass |
+| disable / remove restore baseline | pass |
+
+Compilation is numerically exact: the 6.4 KB portable artifact reproduces the
+original SAE-based pipeline's delta norm (28.5178) to fp16 rounding.
+
+Overhead on L4 (3 runs, 96 tokens): **−1.3%** (within noise), **0.01 MB** VRAM,
+**0.21 s** patch load.
 
 ---
 

patches/research/experimental-feature-727-scheduled.json

@@ -0,0 +1,47 @@
+{
+  "authors": [],
+  "base_model": "Qwen/Qwen2.5-1.5B-Instruct",
+  "description": "The same unvalidated feature-727 direction, with a token-indexed schedule, demonstrating dynamic mid-generation steering. The intervention is off for the first 24 generated tokens, switches on at token 24, and doubles at token 48. Measured delta norms during a real generation were 0.0 at tokens 0-23, 28.518 at token 24, and 57.036 at token 48, matching the predicted schedule to within 3.6e-06. This patch demonstrates a RUNTIME CAPABILITY. It makes no behavioural claim whatsoever: see experimental-feature-727.json for the control results, which are negative.",
+  "evaluation": {
+    "experiment": "dynamic_steering_demo",
+    "measured_delta_norm_by_generated_token": {
+      "0": 0.0,
+      "23": 0.0,
+      "24": 28.51780128479004,
+      "48": 57.03560256958008
+    },
+    "max_abs_error_vs_expected_schedule": 3.6103930867170675e-06,
+    "matches_expected_schedule": true,
+    "conclusion": "Token-indexed strength scheduling works as specified. No behavioural effect is claimed."
+  },
+  "evidence_level": "none",
+  "features": [
+    {
+      "feature_id": 727,
+      "mode": "add",
+      "strength": 16.0
+    }
+  ],
+  "format_version": "0.1",
+  "license": "Apache-2.0",
+  "metadata": {
+    "purpose": "runtime capability demonstration",
+    "schedule_semantics": "Keys are GENERATED-token indices (the prompt is not counted). Values multiply the feature strength. Step-hold: the value at index n is the value of the largest keyframe <= n."
+  },
+  "model_revision": "989aa7980e4cf806f80c7fef2b1adb7bc71aa306",
+  "name": "experimental-feature-727-scheduled",
+  "sae": {
+    "d_in": 1536,
+    "d_sae": 2048,
+    "hook": "residual_post",
+    "input_scale": 0.5610531069008018,
+    "layer": 18,
+    "reference": "smoke_v0",
+    "sha256": null
+  },
+  "schedule": {
+    "0": 0.0,
+    "24": 1.0,
+    "48": 2.0
+  }
+}

patches/research/experimental-feature-727.json

@@ -0,0 +1,74 @@
+{
+  "authors": [],
+  "base_model": "Qwen/Qwen2.5-1.5B-Instruct",
+  "description": "Single-feature steering direction from the smoke_v0 SAE. This patch is named after its feature ID because nothing about its behaviour has been established. Steering it at strength 16 does change the model's output (mean 3-gram divergence 0.71 from baseline over 6 prompts), but a SCALE-MATCHED RANDOM DIRECTION of identical L2 norm changed the output MORE (0.85). There is no evidence that this direction carries any specific behavioural meaning. NOTE ALSO that feature 727 is a pathological selection: it fires on only 5 of 20,000 tokens with an activation 158x the dictionary median, and belongs to a cluster of 32 near-duplicate features that all fire on the same rare token. Published as a reproducible artifact of the smoke_v0 pipeline, not as a working behavioural patch.",
+  "evaluation": {
+    "experiment": "smoke_v0_intervention",
+    "num_prompts": 6,
+    "generation": "greedy, max_new_tokens=96, identical settings across all conditions",
+    "delta_norm_all_conditions": 28.51780128479004,
+    "divergence_from_baseline": {
+      "zero": 0.0,
+      "positive": 0.709797049449183,
+      "negative": 0.7314236228213818,
+      "random_positive": 0.8469011791109867,
+      "random_negative": 0.698357839417966,
+      "unrelated_positive_feature_1270": 0.6808128064619702
+    },
+    "effect_vs_controls": {
+      "positive_minus_random": -0.13710412966180374,
+      "positive_minus_unrelated": 0.028984242987212805,
+      "unrelated_control_retracted": "INVALID. Feature 1270 was selected by the same max_activation ranking as the target and is a near-duplicate of it: 3 fires out of 20,000 tokens, max activation 1385.8, same top token ' Bd', same 32-feature outlier cluster. It is not an unrelated feature and this comparison is uninformative. The random-direction control is unaffected and remains valid.",
+      "valid_controls": ["zero", "random_positive", "random_negative"]
+    },
+    "feature_selection_flaw": {
+      "target_fire_count": 5,
+      "target_firing_rate": 0.00025,
+      "target_max_activation": 1429.7736816406250,
+      "dictionary_median_fire_count": 271,
+      "dictionary_median_max_activation": 9.06184,
+      "outlier_cluster_size": 32,
+      "outlier_cluster_shared_top_token": " Bd",
+      "note": "Ranking by max_activation selected the single most extreme outlier in the dictionary. An undertrained SAE shatters rare high-norm tokens across many near-duplicate features; this ranking finds exactly those. Use min_firing_rate or rank by mean_activation instead."
+    },
+    "zero_strength_matches_baseline": "6/6 prompts byte-identical",
+    "utility_probes": {
+      "baseline_accuracy": 0.9,
+      "patched_accuracy": 0.8,
+      "accuracy_delta": -0.1,
+      "n_probes": 10,
+      "note": "10 hand-written probes; a 1-item change carries no statistical weight"
+    },
+    "conclusion": "NEGATIVE. The scale-matched random-direction control diverged MORE than the intervention, so there is no support for a feature-specific causal effect. The infrastructure is verified; the behavioural claim is not. A specific, fixable cause was identified after publication: the max_activation selection rule picked a degenerate outlier feature (see feature_selection_flaw), so this result says more about the selection rule than about SAE features in general.",
+    "statistical_caveat": "6 prompts, single greedy generation per condition, no repeated sampling. These differences have no significance testing behind them and should not be read as effect sizes."
+  },
+  "evidence_level": "none",
+  "features": [
+    {
+      "feature_id": 727,
+      "mode": "add",
+      "strength": 16.0
+    }
+  ],
+  "format_version": "0.1",
+  "license": "Apache-2.0",
+  "metadata": {
+    "corpus": "Salesforce/wikitext:wikitext-2-raw-v1 train, 20000 activation tokens",
+    "sae_training": "2220 steps, train explained variance 0.762, validation 0.658",
+    "selection_rule": "highest max_activation among features firing on <50% of tokens",
+    "strength_rationale": "Measured dose-response sweep: strength 8-16 changes output without triggering degeneration; 32 loops; 64 collapses. Residual-stream L2 norm at layer 18 is approximately 70 in raw units.",
+    "warning": "Feature IDs are meaningless outside the smoke_v0 SAE. This file cannot be applied to another model, another layer, or another SAE."
+  },
+  "model_revision": "989aa7980e4cf806f80c7fef2b1adb7bc71aa306",
+  "name": "experimental-feature-727",
+  "sae": {
+    "d_in": 1536,
+    "d_sae": 2048,
+    "hook": "residual_post",
+    "input_scale": 0.5610531069008018,
+    "layer": 18,
+    "reference": "smoke_v0",
+    "sha256": null
+  },
+  "schedule": null
+}