brainpatch 1.2.0__py3-none-any.whl

brainpatch-1.2.0.dist-info/METADATA

@@ -0,0 +1,556 @@
+Metadata-Version: 2.4
+Name: brainpatch
+Version: 1.2.0
+Summary: A portable format and runtime for reversible activation-space interventions in frozen language models.
+Author: Blackdrome AI Labs
+Maintainer-email: Blackdrome AI Labs <hello@blackdrome.tech>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/blackdromeai-labs/brainpatch
+Project-URL: Repository, https://github.com/blackdromeai-labs/brainpatch
+Project-URL: Documentation, https://github.com/blackdromeai-labs/brainpatch/tree/main/docs
+Project-URL: Issues, https://github.com/blackdromeai-labs/brainpatch/issues
+Project-URL: Changelog, https://github.com/blackdromeai-labs/brainpatch/blob/main/CHANGELOG.md
+Project-URL: Organization, https://github.com/blackdromeai-labs
+Keywords: activation-steering,interpretability,llm,mechanistic-interpretability,activation-patching,model-steering,inference-time-intervention
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Provides-Extra: transformers
+Requires-Dist: torch>=2.1; extra == "transformers"
+Requires-Dist: transformers>=4.40; extra == "transformers"
+Requires-Dist: accelerate>=0.30; extra == "transformers"
+Provides-Extra: vllm
+Requires-Dist: vllm>=0.6; extra == "vllm"
+Requires-Dist: torch>=2.1; extra == "vllm"
+Provides-Extra: mlx
+Requires-Dist: mlx-lm>=0.20; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "mlx"
+Provides-Extra: llamacpp
+Requires-Dist: gguf>=0.10; extra == "llamacpp"
+Requires-Dist: numpy>=1.24; extra == "llamacpp"
+Provides-Extra: hub
+Requires-Dist: huggingface_hub>=0.25; extra == "hub"
+Provides-Extra: server
+Requires-Dist: fastapi>=0.110; extra == "server"
+Requires-Dist: uvicorn>=0.30; extra == "server"
+Requires-Dist: pydantic>=2.0; extra == "server"
+Provides-Extra: ui
+Requires-Dist: gradio>=4.44; extra == "ui"
+Provides-Extra: research
+Requires-Dist: torch>=2.1; extra == "research"
+Requires-Dist: transformers>=4.40; extra == "research"
+Requires-Dist: datasets>=2.19; extra == "research"
+Requires-Dist: accelerate>=0.30; extra == "research"
+Requires-Dist: safetensors>=0.4; extra == "research"
+Requires-Dist: numpy>=1.24; extra == "research"
+Requires-Dist: pyyaml>=6.0; extra == "research"
+Requires-Dist: huggingface_hub>=0.25; extra == "research"
+Provides-Extra: modal
+Requires-Dist: modal>=1.5.0; extra == "modal"
+Provides-Extra: all
+Requires-Dist: brainpatch[hub,llamacpp,server,transformers,ui]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# BrainPatch
+
+**A portable format and runtime for reversible activation-space interventions in
+frozen language models.**
+
+No fine-tuning. No weight modification. No prompt injection. No hosted service.
+
+An open-source system from [Blackdrome AI Labs](https://blackdrome.tech).
+
+```bash
+pip install "brainpatch[transformers]"
+brainpatch install ./experimental-feature-727.brainpatch
+brainpatch compare --model Qwen/Qwen2.5-1.5B-Instruct \
+                   --patch experimental-feature-727 \
+                   --prompt "Explain why the sky is blue."
+```
+
+```python
+from brainpatch import BrainPatchedModel
+
+model = BrainPatchedModel.from_pretrained(
+    "Qwen/Qwen2.5-1.5B-Instruct", backend="transformers", device="auto"
+)
+patch = model.install("./experimental-feature-727.brainpatch")
+patch.strength = 0.8
+print(model.generate("Evaluate my idea."))
+```
+
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/blackdromeai-labs/brainpatch/blob/main/LICENSE)
+[![Format](https://img.shields.io/badge/format-.brainpatch%20v1-orange.svg)](https://github.com/blackdromeai-labs/brainpatch/blob/main/docs/patch-format.md)
+[![Blackdrome AI Labs](https://img.shields.io/badge/Blackdrome%20AI%20Labs-open%20source-black.svg)](https://github.com/blackdromeai-labs)
+
+---
+
+## What it is
+
+A **BrainPatch** is a small file containing one or more direction vectors and the
+layers to add them to. Loading one installs a behavioural intervention into a
+model whose weights are never touched.
+
+BrainPatch is **infrastructure, not a method**. It is agnostic about how a
+direction was discovered — difference-of-means, PCA, a linear probe, an SAE
+feature, or anything else — and it is not tied to any one behaviour. The project
+began as an SAE tool; on our own benchmark the SAE finished behind PCA and
+difference-of-means, and the format outlived that assumption.
+
+| | LoRA / fine-tune | Prompt engineering | **BrainPatch** |
+|---|---|---|---|
+| changes weights | yes | no | **no** |
+| artifact size | MB – GB | n/a | **6.7 KB** (measured, below) |
+| costs context | no | yes, every call | **no** |
+| adjustable at runtime | no | crudely | **yes, continuously** |
+| removable mid-session | no | yes | **yes** |
+| changeable *during* generation | no | no | **yes** (token schedules) |
+
+Measured on the reference patch in this repository: **6,856 bytes**, against
+**3,087,467,144 bytes** of Qwen2.5-1.5B-Instruct weights — a ratio of
+**450,331×**. Runtime overhead on an L4 was **−1.3% (within noise)** on
+Transformers and **+2.2% (tokens/second)** on vLLM, with
+**0.01 MB** of extra VRAM.
+
+## Read this before using the example patches
+
+The runtime is verified. **The example patches' behaviour is weakly established
+and we label them accordingly.** BrainPatch will not name a patch after a
+behaviour it has not demonstrated.
+
+| patch | evidence | what it is |
+|---|---|---|
+| `experimental-feature-727` | `none` | named after its feature ID because its controls came back negative — a scale-matched random direction moved the output *further* from baseline than the real one. Ships as a working demonstration of the format. |
+| `experimental-commitment` | `controlled_interventional` | a real, replicated effect on commitment / anti-evasion. **Formerly named `anti-sycophancy`; that name was withdrawn** because sycophantic agreement *rose* under it. |
+| `experimental-independent-criticism-candidate` | `none` | a candidate direction, never validated. |
+
+## What the research established, in order
+
+Four experiments, four times the conclusion changed. The write-ups include the
+numbers that looked good before they didn't.
+
+**`anti_sycophancy_v1` — negative.** 198 propositions, topic-disjoint splits,
+true-assertion controls so "disagree with everything" cannot score as
+independence, criteria [pre-registered](https://github.com/blackdromeai-labs/brainpatch/blob/main/experiments/anti_sycophancy_v1/success_criteria.md)
+before the test split was opened. The selected direction beat all ten
+scale-matched random directions, beat three unrelated real directions and
+reversed under sign inversion — but its per-item effect correlated **+0.457**
+with response-length gap, over a threshold set in advance, and free generation
+moved the wrong way. [Full write-up](https://github.com/blackdromeai-labs/brainpatch/blob/main/experiments/anti_sycophancy_v1/RESULTS.md).
+
+Three findings outlived the null:
+
+- **The SAE came last.** Both SAE variants lost to PCA, to a linear probe and to difference-of-means, and both failed the true-claim control by making the model disagree with *true* statements.
+- **Probe accuracy is not steerability.** A probe separating the classes at **100%** accuracy steered worse than PCA, which uses no labels when fitting. Readable and pushable are different properties.
+- **Where you inject beats almost everything else.** Prompt-token steering was ~**6×** more effective than steering generated tokens.
+
+**`anti_sycophancy_v2` — negative, test split never opened.** Rebuilt the dataset
+to remove the length confound (preferred response longer in **53%** of pairs
+instead of 96%). The pre-registered free-generation gate stopped it at
+validation. It produced the most useful finding in the project, across 27
+configurations that passed every log-probability gate:
+
+```
+corr(log-probability effect, free-generation correction gain) = −0.298
+```
+
+**Ranking activation-steering directions by paired log-probability
+*anti-selects* for the behaviour you want in generation.** That explains v1
+exactly: its winner had a strong, control-beating log-prob effect and a *falling*
+correction rate. Only **27 of 330** configurations survived the true-claim guard —
+most directions that "work" are simply contrarian.
+[Full write-up](https://github.com/blackdromeai-labs/brainpatch/tree/main/experiments/anti_sycophancy_v2).
+
+**`anti_sycophancy_v3` — the first positive result.** Selecting by *generated
+behaviour* instead of log-probability, on a third fresh dataset, a single SAE
+feature injected at the prompt raised the correction rate on false user
+assertions from **0.233 to 0.400** on 200 held-out items — CI [+0.092, +0.242],
+McNemar **p = 3.6 × 10⁻⁵**, all **11** pre-registered gates passed.
+[Full write-up](https://github.com/blackdromeai-labs/brainpatch/tree/main/experiments/anti_sycophancy_v3).
+
+**`anti_sycophancy_specificity_v1` — replicated the effect, then took its name
+away.** On 407 fresh propositions with zero overlap against all prior data, the
+effect reproduced *through the compiled artifact*: correction **0.248 → 0.376**,
+CI [+0.072, +0.184], McNemar **p = 2.1 × 10⁻⁵**.
+
+Against **100** norm-matched random directions it reached the **95.0th
+percentile**, empirical **p = 0.0594** — a pre-registered pass, but 5 of 100
+random directions matched or beat it. Specificity is real and weak.
+
+Then the transition matrix showed what the headline hid. Only ~**22%** of the
+gain (+0.028, p = 0.17) was a claim moving from *agreement* to *challenge*. Most
+was evasive replies becoming committed ones, landing correct or sycophantic at
+chance (28 vs 26, p = 0.89) — and **sycophantic agreement rose, 0.280 → 0.352**.
+Removing the user's endorsement kept 75% of the effect.
+
+So the patch was renamed **`experimental-commitment`**. It steers commitment and
+suppresses evasion; it does not reduce sycophancy. The evidence level was
+deliberately *not* upgraded ([why](https://github.com/blackdromeai-labs/brainpatch/blob/main/docs/evidence_level_decision.md)).
+[Full write-up](https://github.com/blackdromeai-labs/brainpatch/tree/main/experiments/anti_sycophancy_specificity_v1).
+
+**`artifact_fidelity_v1` — a claim of ours, refuted.** We had shipped an artifact
+with an inverted coefficient sign that passed a cosine check at 1.0, and
+hypothesised that behavioural testing was therefore *required* to catch such
+defects. Thirteen controlled corruptions said otherwise: signed cosine, delta
+norm and execution tracing together caught **all eleven** real defects, and
+behavioural reproduction caught **nothing they missed** while missing two they
+caught. The lesson was narrower than the hypothesis — *the reference had been
+unsigned* — and it is now the [`brainpatch verify`](https://github.com/blackdromeai-labs/brainpatch/blob/main/docs/verification.md)
+workflow. [Full write-up](https://github.com/blackdromeai-labs/brainpatch/blob/main/experiments/artifact_fidelity_v1/report.md).
+
+Total compute for all five experiments: **~$4.65**. None of these failures needed
+scale to find; they needed the next question to be asked.
+
+---
+
+## Install
+
+```bash
+pip install brainpatch                    # core: format, registry, CLI. No ML stack.
+pip install "brainpatch[transformers]"    # PyTorch backend (CUDA / CPU / MPS)
+pip install "brainpatch[llamacpp]"        # GGUF control-vector export
+pip install "brainpatch[vllm]"            # high-throughput serving
+pip install "brainpatch[server]"          # OpenAI-compatible HTTP API
+pip install "brainpatch[ui]"              # local web UI
+pip install "brainpatch[research]"        # patch authoring: SAEs, extraction
+```
+
+The core wheel pulls in **only `typer` and `rich`** — no torch, no numpy, not
+even `safetensors` (the container is parsed by a pure-Python reader). Installing,
+inspecting and validating a patch works on a bare Python 3.10+.
+
+```bash
+brainpatch doctor      # which engines are installed and usable
+brainpatch backends    # full capability matrix
+```
+
+## Supported backends
+
+| Backend | Status | Static | Schedules | Server | Verified against |
+|---|---|---|---|---|---|
+| **Transformers** | **verified** | ✅ | ✅ | ✅ | Qwen2.5-1.5B bf16, NVIDIA L4 |
+| **llama.cpp** | **verified** | ✅ | ❌ | ✅ | upstream **b10344**, **Q4_K_M** GGUF |
+| **vLLM** | **verified** | ✅ | ❌ | ✅ | **vLLM 0.11.0**, L4, OpenAI server |
+| **MLX-LM** | experimental | ✅ | ❌ | ❌ | never run on Apple Silicon |
+
+"Verified" means an automated acceptance suite ran against a real model and
+passed. "Implemented" means the adapter is written and reviewed but no hardware
+has confirmed it. We do not use the word "supported" for the latter.
+
+What "verified" cost, concretely — each backend ran an automated acceptance
+suite against a real model:
+
+- **Transformers**: weights provably unchanged, `strength=0` byte-identical to
+  baseline, measured delta norm **28.5177 == expected 28.5177**, schedules fire
+  at the keyframe, disable/remove restore baseline.
+- **llama.cpp**: 0-based BrainPatch layer 18 maps to the `direction.19` tensor
+  (1-based), scale-0 output character-identical to baseline, non-zero scale
+  changes output, no crash — on a real 1.12 GB Q4_K_M GGUF.
+- **vLLM**: hooks confirmed **inside the worker process** (`Qwen2ForCausalLM`,
+  28 layers, `active_hooks: 1`, `cuda:0`), OpenAI server serves concurrent
+  requests with no state leak, mismatched per-request strength rejected 400.
+
+Capability gaps are real, not oversights:
+
+- **llama.cpp has no token schedules** — a control vector is bound for a whole
+  run and the CLI exposes no per-decode-step control.
+- **vLLM has no per-request strength** — continuous batching means one forward
+  pass serves many sequences, so a per-request coefficient would change *other
+  users'* output. Patch state is frozen while serving, which is what makes
+  concurrency safe.
+- **Quantization is not assumed to transfer.** A direction fitted on bf16 was
+  checked to still change output at Q4_K_M; whether it produces the *same*
+  behavioural effect at 4-bit is untested.
+
+## CLI
+
+```bash
+brainpatch install <file.brainpatch | owner/repo>
+brainpatch list
+brainpatch inspect <name>
+brainpatch validate <name> --model Qwen/Qwen2.5-1.5B-Instruct
+brainpatch verify <name> --reference known-good.brainpatch --model <model>
+brainpatch run "prompt" --model <model> --patch <name>
+brainpatch compare --model <model> --patch <name> --prompt "..."
+brainpatch chat --model <model> --patch <name>
+brainpatch serve --model <model> --patch <name> --port 8000
+brainpatch ui
+brainpatch compile research.json --sae ./sae.pt -o out.brainpatch
+brainpatch compile out.brainpatch --backend llama.cpp -o cv.gguf
+brainpatch benchmark --model <model> --patch <name>
+brainpatch doctor
+brainpatch backends
+```
+
+## Verifying a patch
+
+`validate` asks *is this file well-formed and loadable*. `verify` asks *does it
+do what it says*. Those are different questions:
+
+```bash
+brainpatch verify ./my-patch.brainpatch     --reference ./known-good.brainpatch     --model Qwen/Qwen2.5-1.5B-Instruct
+```
+
+```
+numerical
+  signed_direction  FAIL  signed cosine -1.00000000 (threshold 0.999000);
+                          unsigned |cos| 1.00000000 would have passed
+```
+
+Four levels, each catching what the one above it cannot. A level whose inputs are
+missing is reported `skipped`, never dropped — an absent check reads as a pass.
+
+| level | needs | catches |
+|---|---|---|
+| structural | nothing | corrupt archive, malformed manifest, wrong shape, wrong base model |
+| numerical | `--reference` | wrong direction **including sign**, wrong magnitude |
+| execution | `--model` | wrong layer, wrong injection site, lost schedule |
+| behavioural | a recorded result | drift that survives all of the above |
+
+We built this because we shipped a sign-inverted artifact that passed every
+file-level check. Measured across thirteen controlled corruptions: schema,
+checksum, shape and model-compatibility caught **0 of 11** real defects; layer and
+site defects were invisible to *every* file-level check including signed cosine.
+Only tracing the runtime found them.
+
+**Checksums prove a file was not modified. They prove nothing about whether it
+encodes the right intervention.** Full detail: [docs/verification.md](https://github.com/blackdromeai-labs/brainpatch/blob/main/docs/verification.md).
+
+## OpenAI-compatible server
+
+```bash
+brainpatch serve --model Qwen/Qwen2.5-1.5B-Instruct --patch my-patch --port 8000
+```
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
+client.chat.completions.create(model="qwen", messages=[{"role": "user", "content": "hi"}])
+```
+
+Existing clients work unchanged. Patch strength is configured at **startup**, not
+per request — with a shared model, honouring a per-request strength would alter
+other in-flight requests' output. A mismatched `brainpatch` extra field returns
+a clear 400 rather than being silently ignored.
+
+## The `.brainpatch` format
+
+A ZIP containing only inert data:
+
+```
+manifest.json         what to add, where, how strongly
+vectors.safetensors   the direction vectors
+checksums.json        sha256 of every member
+README.md             optional
+```
+
+**A patch cannot execute code.** No pickle, no scripts. The loader reads members
+by exact name, rejects unexpected members, absolute paths, `..` traversal,
+symlinks and zip bombs, and verifies every checksum before use. Archives are
+byte-deterministic, so a published patch has a stable hash.
+
+Compatibility is enforced in three modes — `strict` (default; model id and
+revision must match), `architecture`, and `unsafe` — because a direction fitted
+in one model's basis means nothing in another's.
+
+Full specification: [docs/patch-format.md](https://github.com/blackdromeai-labs/brainpatch/blob/main/docs/patch-format.md).
+
+## Architecture
+
+```mermaid
+flowchart TD
+    REPO["patch repository<br/>(Hugging Face, a file, anywhere)"]
+    ART["tiny .brainpatch<br/>~6 KB"]
+    REPO --> ART
+
+    ART --> LOCAL["local workstation"]
+    ART --> CLOUD["cloud server"]
+
+    LOCAL --> TF["Transformers"]
+    LOCAL --> LC["llama.cpp"]
+    LOCAL --> MLX["MLX"]
+    CLOUD --> VLLM["vLLM"]
+
+    TF --> FROZEN["frozen base LLM<br/>weights untouched"]
+    LC --> FROZEN
+    MLX --> FROZEN
+    VLLM --> FROZEN
+
+    style ART fill:#fff4e6,stroke:#d99b4a
+    style FROZEN fill:#eefaf0,stroke:#4ad97a
+```
+
+The runtime knows nothing about where a patch was trained. Separately, the
+research toolkit is how patches are *made*:
+
+```mermaid
+flowchart TD
+    A["activation extraction"] --> B["sparse autoencoder"]
+    B --> C["feature discovery"]
+    C --> D["causal validation<br/>+ controls"]
+    D --> E["patch compile"]
+    E --> F["publish"]
+    F -.-> G["a .brainpatch file"]
+
+    H["Modal · local GPU · cluster<br/>(optional research backend)"] -.-> A
+
+    style G fill:#fff4e6,stroke:#d99b4a
+    style H fill:#eef2ff,stroke:#7a8ad9
+```
+
+## Offline
+
+Once the model, patch and backend are local, BrainPatch needs no network. No
+telemetry, no phone-home, no hosted dependency. `--offline` refuses network
+access outright.
+
+## How it works
+
+A forward hook on decoder block *L* adds `strength × coefficient × vector` to the
+residual stream. That is the entire mechanism.
+
+Two guarantees the test suite enforces on real hardware:
+
+- **`strength = 0` is byte-identical to baseline.** Not approximately — when the
+  resolved edit list is empty the tensor is never touched, so there is no
+  arithmetic to round. Verified: 0 applied passes, identical output.
+- **Weights are never modified.** Verified by comparing layer-18 weights before
+  and after a patched generation.
+
+## Evidence levels
+
+Every patch declares one, and the CLI prints it everywhere:
+
+`none` → `correlational` → `predictive` → `interventional` →
+`controlled_interventional` → `replicated`
+
+The top rung is deliberately **not** called "causal": passing scale-matched
+controls once, on one model at one layer with one prompt set, is evidence
+*consistent with* a causal effect, not a demonstration of causation.
+
+## Experimental evidence
+
+, and what its controls actually showed:
+
+| condition | divergence from baseline | delta norm |
+|---|---|---|
+| zero | **0.000** (6/6 byte-identical) | 0.0 |
+| positive | 0.710 | 28.5178 |
+| **random direction** | **0.847** | 28.5178 |
+
+A scale-matched random direction moved the output *further* than the real
+feature. There is no evidence of a feature-specific effect. A later audit found
+the cause: the `max_activation` selection rule picked a degenerate cluster of 32
+near-duplicate features that all fire on the same rare token.
+
+Full account, including a retracted control: [RESEARCH_LOG.md](https://github.com/blackdromeai-labs/brainpatch/blob/main/RESEARCH_LOG.md).
+
+## Create your own patch
+
+```bash
+pip install "brainpatch[research]"
+brainpatch compile my-research-patch.json --sae ./sae_latest.pt -o my.brainpatch
+```
+
+The compiler materialises SAE decoder columns into raw residual-space vectors, so
+the artifact is self-contained. Verified numerically: the compiled patch produced
+a delta norm of **28.5177** against the research pipeline's **28.5178**.
+
+Vectors from any method work — difference of means, PCA, a learned controller.
+The runtime does not care; provenance is recorded in metadata.
+
+## Research toolkit
+
+`brainpatch/research/` holds activation extraction, Top-K SAE training, feature
+discovery, causal validation and patch search. Installed only by the `research`
+extra and **never imported by the runtime**.
+
+## Reproducing our experiments with Modal
+
+This repository's experiments ran on [Modal](https://modal.com) because the
+development machine deliberately carries no ML stack. **Modal is how we build
+BrainPatch; it is not how you use it.**
+
+```bash
+pip install "brainpatch[modal,research]"
+modal run modal_app/app.py::smoke_pipeline
+modal run modal_app/app.py::test_transformers_backend
+modal run modal_app/app.py::sae_unit_tests
+```
+
+Total metered spend for the entire project to date: **$2.08**, including all
+three backend verifications and the behavioural experiment.
+
+See [docs/modal-infrastructure.md](https://github.com/blackdromeai-labs/brainpatch/blob/main/docs/modal-infrastructure.md).
+
+## Testing
+
+```bash
+pytest                                          # 601 pure-Python tests, no ML stack
+modal run modal_app/app.py::sae_unit_tests      # SAE maths (needs torch)
+modal run modal_app/app.py::test_transformers_backend   # real-model acceptance
+```
+
+## Limitations
+
+1. **One behavioural patch has replicated; none is strongly specific.**
+   `experimental-commitment` reproduced its effect on fresh data through the
+   compiled artifact, but sits at only the 95.0th percentile of 100 matched
+   random directions (empirical p = 0.0594). `experimental-feature-727`'s
+   controls are outright negative.
+2. **Behavioural claims are single-model.** Everything behavioural was measured
+   on Qwen2.5-1.5B-Instruct at one layer and one magnitude. MLX has never run on
+   Apple Silicon.
+3. **`experimental-commitment` is Transformers-only.** Its prompt-only injection
+   site is inexpressible in llama.cpp and vLLM — a capability boundary, not a
+   defect in either. The backends themselves are verified for static patches.
+4. **The vLLM adapter uses vLLM internals.** vLLM exposes no public
+   activation-hook API, so that path is version-sensitive.
+5. **Quantization is untested.** A direction fitted on bf16 is not guaranteed to
+   behave the same at Q4.
+6. **SAE features may be polysemantic**, and steering can affect unrelated
+   capabilities — the smoke test saw 9/10 → 8/10 on ten probes, far too small a
+   sample to establish degradation.
+7. Results depend on model revision and generation settings. Both are pinned.
+
+## Repository layout
+
+```
+brainpatch/
+├── patch/        format, loader, registry, compiler, validation  (no ML stack)
+├── runtime/      backend contract, capabilities, scheduling, model API
+├── backends/     transformers · llamacpp · vllm · mlx
+├── server/       OpenAI-compatible API
+├── ui/           local Gradio app
+├── schemas/      v0.1 research patch, SAE config, manifests
+├── verify/       artifact-fidelity checks and the corruption suite  (no ML stack)
+└── research/     SAE training, extraction, discovery, validation
+modal_app/        research + integration-test orchestration (optional)
+experiments/      frozen research record, including the negative results
+patchbench/       frozen evaluation scaffolding, not part of the wheel
+tests/            pure-Python tests · tests/remote/ needs torch
+```
+
+## Links
+
+- [Blackdrome AI Labs](https://github.com/blackdromeai-labs)
+- Model & SAE artifacts: [09Catho/BrainPatch-Qwen2.5-1.5B](https://huggingface.co/09Catho/BrainPatch-Qwen2.5-1.5B)
+- Feature database: [09Catho/BrainPatch-Features-Qwen2.5-1.5B](https://huggingface.co/datasets/09Catho/BrainPatch-Features-Qwen2.5-1.5B)
+
+Base model [Qwen/Qwen2.5-1.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct) (Apache-2.0), not redistributed.
+Corpus [Salesforce/wikitext](https://huggingface.co/datasets/Salesforce/wikitext) (CC BY-SA 3.0), not redistributed.
+
+Apache-2.0. Maintained by Blackdrome AI Labs.

brainpatch-1.2.0.dist-info/RECORD

@@ -0,0 +1,82 @@
+brainpatch/__init__.py,sha256=KMx-Ke8fbbo4iBiFRAwk7G_WzSfeC5q0JVojPYthuyc,2951
+brainpatch/cli.py,sha256=ZzEBzCGl5AfYXsydY5ICuN_WDcqiiUtaIIj6re6nW3A,32199
+brainpatch/config.py,sha256=nJSNajgCmmNvHGShQkl_vReP_OTlqCVEcO4V-6CsfvU,8216
+brainpatch/paths.py,sha256=p1ixQ-iaRekaJ7C2dCSggvAtJ1UuKe5NDpd3PTcpDcA,6239
+brainpatch/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+brainpatch/backends/__init__.py,sha256=3k3nf9NNvvmPjnukjc55v7PoLyBCcedTZhukZuOFnOA,830
+brainpatch/backends/llamacpp.py,sha256=wKNWymMTXq17XFBW7RJ5_KkDICIFOsxMnpRFofiHIG0,14993
+brainpatch/backends/mlx_backend.py,sha256=5DH-sQS5PPNxP_85DY4S1lV5ThT62K_ZNkDgDWwymCQ,7850
+brainpatch/backends/transformers_backend.py,sha256=299ex2tGjJG9hxDdcmQcEwrzp1faentXqYq8ZJJQVWY,17982
+brainpatch/backends/vllm_backend.py,sha256=FzZHUBz8YetL50XTqTXA-dvZN_aCI_jNLP8Y_a70o8M,12348
+brainpatch/backends/vllm_worker.py,sha256=qdRzXvrVQ1OCt8PVZ3QPKOxw--KweAQElgTeBOSHHPc,5052
+brainpatch/datasets/__init__.py,sha256=g07hPIXvualNyP7ajgjRbeKA8hoZWkKRC3-olyfT39Q,520
+brainpatch/datasets/contrast_sets.py,sha256=sA8Xdolmuhkolxwuquvkjz3J7RgcPAZgfhuEMUZjKLQ,2044
+brainpatch/evaluation/__init__.py,sha256=6g90KIRd7WET1uEAF9C5Fbs2_WEY-x5d7xHz0m61Bmg,754
+brainpatch/evaluation/metrics.py,sha256=NLpm16yYW68G8kBz7EhrjSLFR9GJ5C5UuL25mGDc_yo,8050
+brainpatch/patch/__init__.py,sha256=Nnaexec3wwtfsIn3zJWJujIbTuw3eKUBM4iJjWMGSFw,1521
+brainpatch/patch/compiler.py,sha256=Zo9qzBgjsA7X8Z5c2WZ8XLy8tp0dKdSpoZkYhl7pwH4,12183
+brainpatch/patch/format.py,sha256=rKwpc8lLF8esSYTerGhKorZ519jVolwRkmLrUhN0Njo,20352
+brainpatch/patch/loader.py,sha256=tkNMG4N6amj6kUAZWTh_ADY6cHsaw2PhnmaoRO7N6t0,12055
+brainpatch/patch/registry.py,sha256=mZO9yuR7cKQ6VpvASBNCQCXHLV7eFFBo6Z2FeVvGrXc,10593
+brainpatch/patch/tensors.py,sha256=IrGZBA1GnDeskeCvLGEKAFPUqiAJCcHGIhq1tQthTWo,8316
+brainpatch/patch/validation.py,sha256=4IEXcyW8sVgPcbifRc0fUpBBNgXyjlO5lYgCWB53qcw,5731
+brainpatch/research/__init__.py,sha256=jX-OHVZoUsuKkvPziONekgjq8r808YikN5P0dzINqzk,719
+brainpatch/research/antisycophancy.py,sha256=SAmmHN5zACHPuvd1-hRKE4jitOk5ZIPXjWyMMQN8O1E,12744
+brainpatch/research/behaviour_eval.py,sha256=MkhedfsQzat_sjmnL9YIIDGVD4tPUwzA0AG6DKmli9U,26810
+brainpatch/research/generation_eval.py,sha256=7zzU_Nm46Ko-9SNCKExRzKnKGmgDmPXcQVevDJ77PhA,13280
+brainpatch/research/stance_rubric.py,sha256=rjMgdsAFHvb6KnXOzUCHVKQiKvXxklgkHCNGNGuX2zo,5653
+brainpatch/research/sycophancy_data.py,sha256=Di_3_Z1BeA6Lr-pAg3Ulk94tabbSpLv0u-cIOADSP0Y,77943
+brainpatch/research/sycophancy_data_r1.py,sha256=c5ZqXXEmkVTV2Hh3poPiE5Q-Cre_U3xgvHpgqy3Cs6M,124488
+brainpatch/research/sycophancy_data_v2.py,sha256=1R0C0JkLSKIPS67Sjd0hf70KWVykiaH5G45JPnU0dWk,143202
+brainpatch/research/sycophancy_data_v3.py,sha256=poFnZnTNPC_FSZBnX2bv1_ZFLiDUUp7Z7Eu6pGnmfVQ,167637
+brainpatch/research/sycophancy_v2_build.py,sha256=EPRwXXCHM_-_sZBh5iPhdnsZoLeK-oB3FmquXoVf51I,13962
+brainpatch/research/sycophancy_v3_build.py,sha256=czlkjaqjEY79qFrIxAcIkHccYCw6dqpW5wJibuGx3lc,8011
+brainpatch/research/utility_probe.py,sha256=PkRYwml7ZVpAPk8FU0dxljOG8vuhoZqOWU7_n7N8IdQ,7285
+brainpatch/research/ml/__init__.py,sha256=t3o4MUwSoF0g1VVAd6pUzKjFatmMXBlNmSBaoBhm6Bo,1215
+brainpatch/research/ml/activation_store.py,sha256=OF6qNek3caTWG_xwkbCkW7ma8CxUdU2INhRJHQXKfYo,8953
+brainpatch/research/ml/causal.py,sha256=_IUS7cw94AqitxzVtfnYuo8Ky44MPnuTi334Y5ozYv0,15556
+brainpatch/research/ml/corpus.py,sha256=frOh-5JlswyyYAy623SD1s8ycEiMev_aH3X4D4Gtc6M,5584
+brainpatch/research/ml/evaluation.py,sha256=y9UkVKgoNL1fizfBO6dsWEpFudU06-G7MyzOSNGGRi4,7319
+brainpatch/research/ml/extraction.py,sha256=fP67L1L4aKsP9lvTvMjBZ-EjAfS_o5glSCZeXykMY4M,17644
+brainpatch/research/ml/feature_analysis.py,sha256=Q2hr_bRA-WJ_exomlfFwTEI2khwLG7DrI6MztPHLatc,12466
+brainpatch/research/ml/generation.py,sha256=b1W46CioijZTrkiBCypJF8q_l5o2NKxfDbRQ2AXTQEY,3967
+brainpatch/research/ml/hooks.py,sha256=TE7mB8uDbtSpBt_vTs2ek9WcwGZTnmC-98RRy0Kj4pM,6282
+brainpatch/research/ml/intervention.py,sha256=ABoS6PJQnTPFh3_4tfqc0PBIlqbBKjq5CAP77xJkPSE,10778
+brainpatch/research/ml/model.py,sha256=EtjBrXJfo3re3_n5XJT9C67h7kxYPBKoXwuNjbJ5iYk,7890
+brainpatch/research/ml/patch_search.py,sha256=Qh71C7vlRxiPvFAa04NQFxdGjY4EMwUDDbtEy8V2Lsg,12819
+brainpatch/research/ml/runtime.py,sha256=TMjuNiYKejxfNvWeM_ef-8mnVmBRPykQYc1-WAlKsok,13870
+brainpatch/research/ml/sae.py,sha256=jGdPbpjyyWYOc3qYA5mxI9-Nk14Cf2mCOAYLDdylRA4,16132
+brainpatch/research/ml/training.py,sha256=art4cKq5CQt4qzcLqOugAAAEswq_8lJM_4XVF5-M-io,14201
+brainpatch/runtime/__init__.py,sha256=D4wcPFtTfntzwPZNLu04dRuTbiNTCIp95cYWwcVJ1XU,1555
+brainpatch/runtime/auto.py,sha256=TyaLRPRjLowrJXRHz2d-CfGxvzJT1rdJTGWyaBeQaXc,5328
+brainpatch/runtime/base.py,sha256=SGIG7h1vYfiPuJcpgGaSqqrU8vpoaTdKhnvk0swrXkE,11582
+brainpatch/runtime/capabilities.py,sha256=hFF5J51XUznx6cQ4pv1Lfrbfk5yQ9XUr82LsuafKLTw,3097
+brainpatch/runtime/model.py,sha256=K1ncdejDM7KEN6u9BL39uS36pvKmqKPEA2gAcTCqAj0,8995
+brainpatch/runtime/scheduling.py,sha256=lKoZzB9dd0lwk1zk3NepTkdWloReyqBeDULqaAgmeR4,465
+brainpatch/schemas/__init__.py,sha256=pifVB4F71CD91Zr0xzBpwQ7hYPK1b8QLijdnmcwU-yA,1077
+brainpatch/schemas/contrast.py,sha256=ONKDv70xq7yCA4zS8fKfkTf9ajc6uoRg-WiiXMQwSCM,6067
+brainpatch/schemas/feature.py,sha256=FHH0mEDPgHDxF8PGdVKT4eucDiZDt7Jc5DMLospJbY0,7307
+brainpatch/schemas/manifest.py,sha256=I8MrJ4J4u8XDXMA_Z9byIfYbYFv2xMbhMTkU0MsZDko,6005
+brainpatch/schemas/patch.py,sha256=FfMowhD4cXW3u_W4nEXzQZFPI2-WyulDyEDd0urhOaw,14989
+brainpatch/schemas/patch_io.py,sha256=aiiQtG1qicOZttxjLcB4uvimmavB3R0ECsaBnAETbvk,2768
+brainpatch/schemas/sae.py,sha256=SMxeZRaMtnp1lbWpU6yV9WshSY52pOG8le6p_BAV3eI,5676
+brainpatch/server/__init__.py,sha256=HnsdCDlHmt86eAddF8wfDazW8estIcwWNkoyZ7DvZEE,321
+brainpatch/server/app.py,sha256=Fcrm3DAyI90VRA9_bZvG-aEifFGo8ot9nbTmCeurN40,10381
+brainpatch/steering/__init__.py,sha256=Rz50-LapaVMd0JNNWdty9iV-8MvSIoDIOksxYk3cF98,550
+brainpatch/steering/plan.py,sha256=7ZRSTnVCWjHS1Bw3ZEwZ0xkYqDu7ke2Roedt1NLKF3k,6499
+brainpatch/steering/schedule.py,sha256=bPyFLtFcpbafEia8I5Atl3a0aKHXlNSc6uAKtPsgvk4,5202
+brainpatch/ui/__init__.py,sha256=L-LLj3WnLtQ35fR77z_oSov050ExXQSCTMN5O73KEac,283
+brainpatch/ui/app.py,sha256=3eCXxYJ_9LzZ0GKkf7qlnNMYDcqSW5gdqP0qWmd8Gzg,8233
+brainpatch/verify/__init__.py,sha256=cOOzWax0UVBJ5Iq6hNVuPIgcQ-56yqmT8x7mz8t_7Xo,2377
+brainpatch/verify/behavioural.py,sha256=gtVKjIedL908iYdQeeTms1kxxxBdj8YVMh9kEm0wF64,6782
+brainpatch/verify/checks.py,sha256=dxMI7PusT3qrxgF4o88w_6QDGFt0KlwEOz_-Nd77TQQ,7747
+brainpatch/verify/corruptions.py,sha256=SQM4W2Zqc7M98p9tnWactDTE8Lrx4Y1jTPVIXOIuWaw,13349
+brainpatch/verify/report.py,sha256=-8NDOlMXKuUqX9mJ6i467b24V-2km5H3g-1PqpEsx2w,5120
+brainpatch/verify/vectors.py,sha256=1cV_9BGcr8lqWaA-jYVD3M1_b2bvlhLYTXysYnt_elA,3469
+brainpatch/verify/workflow.py,sha256=35RZXewK5HYSazLu9xP2KXz5dm5WACSsJHC1EJmA7lo,11812
+brainpatch-1.2.0.dist-info/licenses/LICENSE,sha256=HrlhBo8nyot06bmfjIqiKQVT3mS3XX5daLiYp9FPBxE,10768
+brainpatch-1.2.0.dist-info/METADATA,sha256=k01ETtSkZP06lmdifuDE4PLcBwPi-xaHIZQj41BN5tE,26439
+brainpatch-1.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+brainpatch-1.2.0.dist-info/entry_points.txt,sha256=qljuTSXqpXzx9dCWe6pB13qvDiVUhXRiXeAVeS_RGkA,51
+brainpatch-1.2.0.dist-info/top_level.txt,sha256=zCMHR18v_U7ox6zJCP5XjjVBi3yHvVciEe5fCnwO9l8,11
+brainpatch-1.2.0.dist-info/RECORD,,

brainpatch-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

brainpatch-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+brainpatch = brainpatch.cli:main