Primary question: Does automated parameter search really preserve more capability than hand-tuned abliterations (KL 0.16 vs 0.45–1.04 on the same model), and is decensoring something you should run at all?
RepoDaily adoption score
RepoDaily rates this as 84/100 (strong) for adoption: evidence, installation path, production risk, differentiation, license clarity, and AI/agent fit are scored from the article sources and adoption notes.
6 source(s) across 5 source category/categories, plus a RepoDaily-specific evidence module when available.
5 workflow step(s), 5 next-action step(s), and 1 command/install signal(s) were detected.
Trending momentum is +536 stars, with maintenance/release/issue signals counted when present.
Risk is marked high, with 5 security note(s) and 4 explicit skip condition(s).
3 opportunity lens item(s), 4 alternative(s), and 3 type-specific section(s) support differentiation.
License source or license wording is present.
4 AI/agent-related signal(s) were detected in the article text and metadata.
Project overview
Heretic is a Python command-line tool that removes censorship — the README's own parenthetical is 'safety alignment' — from transformer-based language models without expensive post-training. Mechanically, it pairs an advanced implementation of directional ablation, the technique the community calls abliteration, with a TPE-based parameter optimizer built on Optuna. The README pins the lineage precisely: Arditi et al. 2024 (arXiv:2406.11717) for the core refusal-direction method, plus Lai 2025's projected and norm-preserving biprojected abliteration variants. The stated goal is total automation — the tool searches for abliteration parameters that co-minimize the number of refusals and the KL divergence from the original model, and the README claims anyone who knows how to run a command-line program can use it.
The evidence on offer is a comparison table the author invites you to reproduce. On google/gemma-3-12b-it, the original model refuses 97 of 100 'harmful' prompts. The Heretic output, p-e-w/gemma-3-12b-it-heretic, drops that to 3/100 while holding KL divergence on 'harmless' prompts at 0.16. The two community reference abliterations sit at the same 3/100 refusal suppression but with 0.45 (huihui-ai) and 1.04 (mlabonne v2) KL — meaning noticeably more drift from the base model. The table was compiled with PyTorch 2.8 on an RTX 5090, and the README flags the exact values as platform- and hardware-dependent. The reproduction command is documented in full: `heretic --model google/gemma-3-12b-it --evaluate-model p-e-w/gemma-3-12b-it-heretic`.
Architecture coverage is where the tool tries to outgrow the notebook era of abliteration. Supported out of the box: most dense models, many multimodal models, several MoE architectures, and hybrid designs like Qwen3.5. Explicitly not supported: pure state-space models and certain other research architectures. That is a wider net than most hand-rolled abliteration code, which typically handles one dense checkpoint at a time.
We file this under Learning / Curriculum deliberately. Heretic works as a runnable syllabus for how refusal behavior is encoded and removed: a theory anchor (the two cited papers), an optimization anchor (TPE search over ablation parameters instead of hand tuning), a metric anchor (refusal counts plus KL divergence), and a grading harness (the built-in evaluation mode). It also models scientific honesty for students — the README warns that mathematical metrics and automated benchmarks 'never tell the whole story' and are 'no substitute for human evaluation'.
Packaging facts frame the risk side. The distribution is heretic-llm at version 2.0.0.dev0 — a pre-release, with the 'Development Status :: 4 - Beta' classifier. The license is AGPL-3.0-or-later, and the LICENSE file is the full GNU Affero GPL v3 text, whose network-use clause requires source disclosure for modified versions run as a service. Python >=3.10 is required (classifiers list 3.10–3.12), torch and torchvision are deliberately version-unspecified, and the stack pulls transformers[kernels]~=5.6, accelerate~=1.13, bitsandbytes~=0.49, peft~=0.19, optuna~=4.7, and lm-eval[hf]~=0.4.
Why it is trending now
- 536 stars in the window at trending rank 9, plus a Trendshift '#1 Repository of the Day' badge displayed at the top of the README.
- It collapses a task previously owned by experts into one command; the README explicitly says users need no understanding of transformer internals.
- The comparison table is blunt: same 3/100 refusal suppression as manual releases on gemma-3-12b-it, but KL divergence of 0.16 versus 0.45 (huihui-ai) and 1.04 (mlabonne v2).
- Coverage where notebooks usually stop: several MoE architectures, many multimodal models, and hybrids like Qwen3.5.
- Unusually wide community surface for a 2.0.0.dev0 tool: Discord, Matrix room #heretic:matrix.org, a Hugging Face org (heretic-org), and a Codeberg mirror at codeberg.org/p-e-w/heretic.
Problem it solves
- Manual abliteration requires fluency in transformer internals — activation editing, layer selection, and refusal-direction estimation.
- Hand-picked parameters over-suppress: the README's own table shows community abliterations of the same 12B model at 0.45 and 1.04 KL versus 0.16 for the automated run.
- Refusal benchmarks and KL harnesses are nontrivial to stand up; the lm-eval-based harness Heretic ships is not something most practitioners have preconfigured.
- Architecture diversity means one notebook rarely transfers across model families; MoE and multimodal cases need handling that generic code does not provide.
How it works
- Start from directional ablation theory as cited in the README: Arditi et al. 2024 (arXiv:2406.11717) plus Lai 2025's projected and norm-preserving biprojected extensions.
- Estimate refusal directions in the model's activations and project them out — weight-space edits, not post-training.
- Let Optuna's TPE sampler propose abliteration parameter sets instead of a human guessing them.
- Score each candidate by co-minimizing refusal count on harmful prompts and KL divergence from the original model on harmless prompts.
- Verify with the built-in evaluation mode: `heretic --model <base> --evaluate-model <candidate>` reprints both numbers so any model, not just Heretic's output, can be graded.
What this repo teaches, in order
- Theory anchor: directional ablation ('abliteration') as defined in Arditi et al. 2024 (arXiv:2406.11717) and extended by Lai 2025's projected and norm-preserving biprojected variants.
- Metric anchor: refusal count on 100 harmful prompts plus KL divergence on harmless prompts — the two numbers every abliteration should be asked to report.
- Optimization anchor: a TPE search over ablation parameters via Optuna, replacing the hand tuning that made abliteration an expert craft.
- Practice anchor: run the documented command on google/gemma-3-12b-it and match your output to the README table (3/100, KL 0.16) before touching any other model.
Command surface: what you actually type
- Entry point is `heretic`, wired in pyproject as `[project.scripts] heretic = 'heretic.main:main'`; the installable package name is heretic-llm at version 2.0.0.dev0.
- The one fully documented invocation: `heretic --model google/gemma-3-12b-it --evaluate-model p-e-w/gemma-3-12b-it-heretic` reproduces the README's refusal/KL table.
- Console UX comes from rich~=14.3 and questionary~=2.1 in the dependency list; benchmarking pulls lm-eval[hf]~=0.4.
- Reference hardware is stated: PyTorch 2.8 on an RTX 5090, with exact values flagged as platform- and hardware-dependent — so treat your own numbers as relative, not absolute.
- Python floor is >=3.10, with classifiers covering 3.10, 3.11, and 3.12.
Architecture read: ablation math plus a search loop
- Core: what the README calls an 'advanced implementation' of directional ablation — projecting out refusal directions rather than fine-tuning weights.
- Search: an Optuna-powered TPE optimizer proposes parameters; the objective co-minimizes refusal count and KL divergence from the original model.
- Runtime stack from pyproject: transformers[kernels]~=5.6, accelerate~=1.13, bitsandbytes~=0.49, peft~=0.19, with torch and torchvision deliberately unpinned.
- Coverage: most dense models, many multimodal models, several MoE architectures, and hybrids like Qwen3.5; pure state-space models are excluded out of the box.
- An optional `research` dependency group (geom-median, imageio, matplotlib, pacmap, scikit-learn) hints at the visualization toolkit for studying directions directly.
Maintenance read: signals to check before depending on it
- Version 2.0.0.dev0 with the 'Development Status :: 4 - Beta' classifier — this is a pre-release.
- A single named author in pyproject: Philipp Emanuel Weidmann (pew@worldwidemann.com).
- Distribution surface is broad: GitHub plus a Codeberg mirror (codeberg.org/p-e-w/heretic), a Hugging Face org (heretic-org), Discord, and Matrix #heretic:matrix.org.
- Changelog is declared at github.com/p-e-w/heretic/releases and documentation at heretic-project.org/tutorial via pyproject's URL block.
- Build is uv-based (uv_build backend, `exclude-newer = 7 days` under [tool.uv]); dev tooling is ruff>=0.14.5 and ty>=0.0.5.
Who should pay attention?
Good fit if
- Interpretability students who want refusal-direction theory backed by a runnable CLI and a reproducible scoreboard.
- Local-model practitioners who want their own abliteration of a dense, multimodal, MoE, or hybrid (Qwen3.5-class) model instead of downloading someone else's.
- Researchers who need refusal-rate and KL numbers and want the exact harness that produced the README table.
Skip for now if
- Anyone serving the public through an API: AGPL-3.0-or-later plus intentionally removed safety alignment is a compliance combination to treat very carefully.
- Deployments that must honor upstream model licenses or provider terms prohibiting alignment changes.
- Users targeting pure state-space models — explicitly unsupported out of the box.
- Machines without a serious GPU; the reference numbers came from an RTX 5090.
Risks and cautions
The tool's entire purpose is removing safety alignment, its outputs may conflict with base-model licenses, and AGPL-3.0 adds source-disclosure duties for hosted use of modified versions.
- LICENSE is the full GNU AGPL v3 text and pyproject declares AGPL-3.0-or-later; running a modified version as a network service triggers source-disclosure obligations.
- Decensoring outputs may violate the base model's license or a provider's terms; that exposure sits with the operator.
- Version 2.0.0.dev0 and the Beta classifier mean the interface and results can shift before a stable 2.0.
- torch and torchvision are deliberately unpinned in pyproject, so reproducibility depends on the environment you construct.
- The README itself warns that automated metrics are 'no substitute for human evaluation', yet the tool invites unsupervised use.
- License: AGPL-3.0-or-later (LICENSE file; pyproject classifiers confirm GNU Affero General Public License v3 or later).
- The artifact produced is a decensored model; hosting or redistributing it can breach upstream model licenses and provider usage terms.
- Heavy, partly unpinned dependency surface: transformers[kernels]~=5.6 and bitsandbytes~=0.49 pull native code, and torch/torchwright versions are left to you — pin and audit before running on shared infrastructure.
- pyproject marks the intended audience as Science/Research and the environment as Console plus GPU; outputs should be treated as research artifacts, not deployment-ready checkpoints.
- Decensored models can produce harmful content on demand; the operator owns downstream usage, hosting, and legal exposure.
Alternatives to compare
| Approach | When to use | Trade-off |
|---|---|---|
Pre-made abliterated models (mlabonne, huihui-ai) | You just want a decensored gemma-3-12b-it today and can accept higher KL drift (0.45–1.04 per the README table). | Free on Hugging Face |
FailSpy/abliterator | You want to hand-tune refusal directions yourself and learn the mechanics layer by layer. | Free, open source |
| You would rather change model behavior through fine-tuning (LoRA/QLoRA) than weight-space ablation. | Free, open source | |
Stock model plus targeted prompting | Your real blocker is over-refusal on benign prompts and you must stay inside provider terms. | Free |
What this trend reveals
Reproducible refusal benchmarks on demand
The built-in evaluation mode turns refusal-rate plus KL checks into a two-flag CLI step, which is exactly the missing piece when comparing abliterations from different sources.
Run `heretic --model google/gemma-3-12b-it --evaluate-model p-e-w/gemma-3-12b-it-heretic` and compare your refusal count and KL against the README's 3/100 and 0.16 on your hardware.
A teaching lab for interpretability
The README's citations (arXiv:2406.11717 and Lai 2025's two Hugging Face posts), the tutorial at heretic-project.org/tutorial, and the optional research extras (matplotlib, pacmap, scikit-learn) form a compact course on refusal directions.
Pair the tutorial with the `research` dependency group from pyproject and attempt to visualize the refusal direction before and after ablation.
Coverage gap: state-space architectures
Pure state-space models are explicitly unsupported out of the box, which defines the clearest boundary of the current implementation.
Check the README's supported-models statement before planning any Mamba-family decensoring run.
RepoDaily verdict
Heretic replaces expert abliteration craft with an Optuna-driven search and ships the harness to grade the result — the 0.16 KL versus 0.45–1.04 comparison is the whole pitch. Learn from it and reproduce it; then decide, deliberately and with counsel where needed, whether removing safety alignment is something you should be running at all.