* fix: rename reproduce checksum file to SHA256SUMS.txt
Hugging Face renders relative links without a file extension as
directory links (/tree/), so the SHA256SUMS link in the reproduce
README opened a 404. Giving the file a .txt extension keeps the link
relative while making it open as a file, like the other reproduce
assets. The verification instruction becomes sha256sum -c SHA256SUMS.txt.
Fixes#463
* test: remove reproduce folder tests
* perf(ara): compute closure outputs via low-rank update instead of dense weight
ARA's modify_model rebuilt the full dense effective weight (W_base + B@A)
and ran a full input @ W_eff.T on every L-BFGS closure evaluation, which
dominates the per-trial cost.
Since input @ W_base.T equals the captured module output (minus bias) and
is constant across closures, and the LoRA update is low-rank, the closure
output is input_output_base + (input @ A.T) @ B.T. This avoids both the
dense [d_out x d_in] weight materialization and the full dense matmul; only
the rank-r term is recomputed. With preserve_row_magnitudes, row
normalization becomes a per-output-row diagonal rescale applied to the
outputs, so the identity holds there too.
Algebraically exact (rel err ~1e-5); not bit-identical due to changed
float summation order. modify-step speedup ~1.4x (gemma-2-2b/H100) to
~3.2x (Qwen2.5-7B/H100), scaling with layer size; final-model Pareto
front is preserved.
* test: assert low-rank ARA closure equals the dense formulation
Adds an equivalence test that runs both the original dense closure
(build W_eff, multiply) and the low-rank reformulation on the same
inputs and asserts they match to float tolerance, with and without
preserve_row_magnitudes. This guards the reformulation's correctness
directly, rather than relying on bit-identical output hashes (which
necessarily change under any FLOP-reordering optimization).
* simplify: assume bias-free linear modules in ARA closure
The dense formulation already matches the raw weight product (input @
W.T) against the captured output, so a biased module was a pre-existing
apples-to-oranges comparison. Rather than reconstruct the bias-free base
from the captured output, assert the modules are bias-free (true for the
o_proj / down_proj modules ARA targets across essentially all current
LLMs). The captured output is then exactly input @ W_base.T, so the
closure uses it directly and the separate *_base variables are gone.
No behavior change for the bias-free modules ARA runs on.
* fix(ara): handle linear modules with a bias term
The captured module output is input @ W_base.T + bias, but ARA only modifies
the weight. Instead of asserting that no bias is present (which fails on
gpt-oss), subtract the bias to get the bias-free product, add the low-rank
update and apply the row-norm rescale to that, then add the bias back. This
also fixes the original dense closure, which compared input @ W_eff.T against
a bias-inclusive output for such models. Bias-free modules are unchanged.
Extend the equivalence test to cover modules with a bias, with and without
row normalization.
* test: update ARA output hashes for the low-rank closure
Only the two ARA tests (gpt-oss, seed-oss) change. Hashes taken from CI on
ubuntu-latest: gpt-oss is identical on Python 3.10-3.13; seed-oss has one hash
for 3.10-3.12 (SHA256SUMS.ci) and another for 3.13 (SHA256SUMS.ci2).
* fix(ara): compute the base product in float32 instead of reusing the captured output
The low-rank closure used the hook's captured module output as the constant
input @ W_base.T term. That output was computed in the model's dtype (e.g.
bfloat16), which is about 3e-3 relative off from the float32 product the
original dense closure used, so the optimizer saw a different objective.
Compute input @ W_base.T once per module from the float32 weight instead. This
matches the dense closure to float32 rounding (about 1e-6 relative on
gemma-3-270m) while keeping the low-rank speedup.
* test: update ARA output hashes for the float32 base product
* ci: update hash for deepseek-v4-ara test
* ci: update hash for deepseek-v4-ara test
* fix: support flattened hyper-connection residual streams
Qwen4-Exp flattens its hc_count residual streams into the component
dimension, so its hidden states have shape (prompt, position, streams *
hidden_size) instead of the 4D layout handled by #519. Collapse the flattened
streams to their mean before stacking residuals.
* fix: collect Qwen4-Exp shared experts as ablation targets
Qwen4-Exp uses the singular mlp.shared_expert spelling, while DeepSeek and
GLM use the plural mlp.shared_experts spelling. Collect both.
Co-authored-by: umran666 <shaikumran666@gmail.com>
* test: update qwen3.5-moe hashes for shared experts
Collecting mlp.shared_expert.down_proj adds it to the abliterable modules
for Qwen3.5-MoE, so the merged model changes. Add the new Linux and
Python 3.10 CI hashes.
---------
Co-authored-by: umran666 <shaikumran666@gmail.com>
* fix: Handle the default thinking behavior
Some chat-templates insert full CoT block when thinking is *disabled* by Default like Qwen3.5-2B. And some models by Default only insert the CoT initializer (somtimes possibly with whitespaces) like Qwen3.5-4B when thinking is *enabled*.
Co-authored-by: benthecarman <benthecarman@live.com>
* chore: Update CI test hashes
Removing $ from pattern_initializer broke the test model mistral-3, which was expected
* fix: Several fixes, docs update, cleanup
* chore: Update Windows test hash
very much expected, and looks good to me
* chore: Update CI test hashes
* chore: Update CI test hash (alternate)
good to see that it caught the third hash as well. Anyway, the GitHub CI remains terrible for such tests
* fix: minor change
* fix: Override the system prompt for the dummy_prompt case
This is correct for models which insert instructions about 'How to think' in the system prompt, which can cause false-positives when searching the dummy_prompt
* chore: Update CI test hashes
* chore: Update CI test hashes
* fix: minor change
* fix: Add alternate CI test hash
I'm not liking having a fourth hash btw
---------
Co-authored-by: benthecarman <benthecarman@live.com>
DeepSeek V4 and GLM 5.3 have several residual streams per token instead
of one, so their hidden states have an extra dimension. Heretic crashed
computing refusal directions for GLM 5.3, and found no modules to
abliterate in DeepSeek V4.
Use the mean of the streams as the residual. The streams are mixed with
each other by a doubly stochastic matrix, so their mean only changes by
what the blocks add to it, like an ordinary residual.
Also abliterate DeepSeek V4's attention output (o_b_proj) and the shared
experts of MoE models. Both models fuse their routed experts into one
module, so the shared experts are the only MLP weights Heretic can edit.
Models like Gemma 2 and its fine-tunes reject the system role in their
chat template. generate() always prepends a system message, so the
template raises 'System role not supported' and the dtype loop gives up,
making these models impossible to load.
Detect once (right after the tokenizer loads) whether the template
accepts a system role, by rendering a probe chat and checking a sentinel
system message survives in the output (this catches both templates that
raise and templates that silently drop the role). When the role isn't
supported, fold every system message into the following user message
(dropping empty system prompts), so a system role anywhere in the chat
is removed before rendering, not just a leading one. Templates that
support the system role are unaffected, so their rendered chats and
resulting weights are unchanged.
Supersedes #483.
Co-authored-by: jayhemnani9910 <jayhemnani9910@users.noreply.github.com>
* fix: restore stored plugin settings as they are on reproduce and resume
Settings.model_validate still reads config.toml, environment variables and
the command line, and merges plugin tables key by key. A [modifier.X] or
[scorer.X] key in the local config.toml that the stored settings don't have
was added to a --reproduce run or a resumed study, so a reproduction could
build a different model (hash mismatch).
* fix: restore every stored table, not just plugin tables
Stored values already win over config.toml, but pydantic-settings merges
tables key by key, so max_memory picked up local keys too, and a plugin
table that only exists in config.toml was added to the run. Restore each
stored table as it is and drop tables that weren't stored.
* fix: restore stored settings without reading other sources
Validate stored settings through StoredSettings, whose only source is
the values passed in, instead of letting config.toml, the environment
and the command line merge into them and overwriting afterwards. Fields
that are never stored (exclude=True) are copied from the settings this
run was started with.
* refactor: restore stored settings on top of the current ones
Validate the current settings' fields with the stored values laid over
them, instead of copying fields with exclude=True one by one. Fields
that are never stored keep the values this run was started with, and
plugin tables still come only from the stored values.
* fix: take only never-stored settings from the current run
* refactor: rename from_stored to model_validate_init_only
Text such as `[/INST]` in a prompt or response was parsed as Rich markup, which crashed the run with a MarkupError. Other bracketed text like `[bird migration]` was silently removed from the output.
* Cap ARA's neighbor count at the number of prompts
The nearest neighbors are selected from the outputs for the good and
bad prompts, which have one row per prompt. With fewer than 15 prompts
in either dataset, the optimizer could pick a neighbor count larger
than that, and torch.topk would crash with "selected index k out of
range". Bounding the search range instead of clamping the value keeps
the optimizer from wasting trials on counts that would all behave the
same.
* Render chat templates with a fixed date
Some chat templates, including gpt-oss's, put the current date in the
system prompt. That makes the residuals, and with them the modified
model, depend on the day Heretic runs, so a model could not be
reproduced on a different day. It also made the gpt-oss test's hash
change daily once ARA started modifying the model.
Prompts used for computing residuals and for evaluation are now
rendered with a fixed date. Interactive chat keeps the real one.
* Prevent ARA from sampling an empty layer range
The start index was sampled from [0, L//2] and the exclusive end index
from [L//2, L], so both could land on L//2 and leave no layers to
modify, wasting the trial. Starting the end range at L//2 + 1 rules
this out while keeping the bounds fixed, as multivariate TPE requires.
On the 2-layer test models, every ARA trial had picked this empty
range, so the seed-oss and gpt-oss tests never ran the optimization.
They now modify layer 1, which changes their expected hashes. The
seed-oss output also differs between the CPUs of GitHub's runners,
because L-BFGS amplifies small floating-point differences, so it gets
CI hashes as well.
* Re-initialize ARA's lora_A deterministically
ARA optimizes both LoRA matrices in place, but the model reset between
trials only zeroes lora_B. Each trial therefore started its
optimization from whatever lora_A the previous trial left behind.
Restoring a trial after the study re-optimized it from a different
starting point, so the exported model was not the one that earned the
trial's scores, and reproduction could not match hashes.
Re-initialize lora_A for every optimized module from a generator
seeded with the run seed. This makes the starting point independent of
trial history, the device and the global RNG state.
* Zero lora_A when resetting the model
The fast reset path only zeroed lora_B, and a fresh adapter gets lora_A
from PEFT's random init. Modules a trial doesn't modify therefore kept
whatever lora_A an earlier trial left, or a random one. The model is
unaffected since B is zero, but saved adapters differed byte-for-byte
depending on trial history, breaking hash verification for adapter
exports.
Zero lora_A as well, both on reset and right after applying LoRA.
* feat: add modifier base class
* feat: re-implement abliteration as a modifier plugin
* fix: adjust good/bad prompts hack to match tests
* feat: support dataset specifications containing multiple individual datasets
* feat: re-implement ARA as a modifier plugin
Arbitrary-Rank Ablation (ARA) (Weidmann 2026) was originally introduced by @p-e-w in #211
Co-authored-by: kabachuha <artemkhrapov2001@yandex.ru>
Co-authored-by: joninco <joninco@bullpoint.org>
Co-authored-by: Ashar <coder3101@users.noreply.github.com>
* feat: add tests for ARA
* feat: reduce default number of trials
* ci: remove broken "semantic-pull-request" workflow
* ci: add yet another alternative model hash
---------
Co-authored-by: kabachuha <artemkhrapov2001@yandex.ru>
Co-authored-by: joninco <joninco@bullpoint.org>
Co-authored-by: Ashar <coder3101@users.noreply.github.com>
* fix: Check response prefix.
In case if the model adds <think> at the end of user prompt and only generates </think> end, then the detection goes wrong.
* fix: Handle whitespace in CoT, remove redundant checks
* fix: Type checker
* fix: try looking at tag positions, not text end
regex
* ruff, fix import sorting
* fix: rich markup
* fix: I missed other ones
* feat: Update SHA256SUMS file hashes in the tests.
A major change that affects reproducibility.
* fix: It is now sensible to also update the extra SHA256SUMS.ci2 file.
* fix: Only consider whitespace, no other text or instructions.
because mistral-3 as additional reasoning instructions in its chat template. And I suppose many other models can have it too.
* fix: Update windows hashes.
* fix: Update CI hashes too
* as always update case two of mistral-3 (ci2 hash)
* docs: update comment
* feat: Handle the edge case for models having additional instructions.
* fix: Update windows hash for mistral-3
* docs: remove a line from the comments
because I'm not sure about GPT-OSS models' thinking tags and it cannot be confirmed using an untrained tiny GPT-OSS model. And inference fallback would of course generate gibberish as the model cannot understand additional instructions about 'how to generate response and how to think' from the chat_template.
* fix: a few things.
* fix: Update hash for qwen3.5 after the whitespace fix for its response prefix.
* docs: Update comment
* fix: Update qwen3.5 hash for CI
* fix: Remove Case 2 which only serves tests
unnecessary
* fix: Hash
* fix: concern is valid enough, so we use a small text.
add a comment too
* docs: minor
* feat: Allow specifying a specific config/subset name for the datasets.
This would be useful for using a single dataset that has harmful/harmless prompt pairs in different languages stored in different configs/subsets.
* fix: setting config/subset value when loading the dataset.
* fix: minor changes
* feat: add `reproducible` property to plugins
* feat: hard stop reproducibility and actually check `reproducible` field in the evaluator
* chore: flip default
* fix: check if plugin is built-in in repro gate
* fix: ruff
* fix: kld should be reproducible
* feat: move reproducible field to scorer level
* chore: move reproducible field back to plugin level
---------
Co-authored-by: mad-cat-lon <113548315+mad-cat-lon@users.noreply.github.com>
* fix: validate scorer instance names in config
* fix: run scorer config tests in CI
* fix: drop redundant UV_PYTHON env and quote unittest pattern
* fix: report precise scorer name validation errors
* fix: minor change
use `W_org` matrix where needed...
* Update model.py
* Update model.py
* fix: Windows hash, remove BOM marker
* docs: Add info about test cases
* feat: Tests for row_normalization PRE & NONE
* feat: CI hash files for row_normalization PRE & NONE models
* feat: Documentation instructions about test suite
* add recommendation
* fix: remove notebook input shims
Closes#280
* feat: support headless operation (no interactive input)
* fix: prevent infinite loops
* feat: add end-to-end tests
* ci: run tests in CI
* ci: fix test output ordering
* fix: replace home-cooked `set_seed` function with Transformers builtin
* feat: print PyTorch config when running tests
* feat: print additional information
* experiment: try to standardize test environment
* fix: revert environment changes
* feat: support multiple valid hashes for each output file
* feat: add test output hashes for CI
* feat: add test output hashes for CI (alternative environment)
* feat: add hashes for Windows (#394)
* fix: Hash on windows
* trigger ci
* fix: prefer .yaml (used widely than .toml for model configs)
* use removeprefix
* docs: restore commet
* use removeprefix again
* tests: Add windows hash files for all test models
* trigger ci
* fix: minor cleanup
* clean merge mismatch
* remove unnecessary CRLF replace, now that we support more SUMS files
* fix: use binary mode for hashes everywhere
---------
Co-authored-by: Vinay Umrethe <umrethevinay@gmail.com>
* fix: ensure utf-8 encoding for standard output and error to prevent UnicodeEncodeError on Windows
* fix: address bot review feedback
* refactor: deduplicate stream reconfiguration loop
* feat: let the optimizer disable MLP ablation via a 0 max_weight floor
The MLP max_weight lower bound was 0.8 for every component, so the optimizer
always applied at least 0.8x MLP ablation and could never turn it off, even
when ablating the MLP is pure collateral damage. Give the MLP a 0 lower bound
so the optimizer can disable it per model; attention keeps the 0.8 floor.
See #202.
* perf: skip the abliteration decomposition when the weight is 0
With a 0 max_weight the component's ablation is a no-op, and reset_model()
has already left the adapter at identity. Abort that layer/component before
the decomposition, which avoids the wasted work (and the degenerate
zero-matrix decomposition raised in review on #387).
* fix: clamp a negative MLP max_weight floor so 0 is reachable
A continuous suggest_float never samples exactly 0, so a 0 lower bound could
not actually disable the MLP. Use a small negative lower bound and clamp with
max(0, ...), which puts finite probability mass on exactly 0.
When a study is cancelled mid-way and the user selects 'Run additional
trials', settings.n_trials was incremented by n_additional_trials,
accumulating the original total into the new count. E.g. cancelling 200
trials at 30 and adding 10 gave n_trials=210 instead of 40, causing
'Running trial 31 of 210...' and planning 180 more trials instead of 10.
Fix by recalculating n_trials from actual completed trials + additional,
so the total reflects the new intended target, not the old one.
Fixes#379
Co-authored-by: Claude <noreply@anthropic.com>
Philipp Emanuel Weidmann