Heretic

Heretic is a command-line tool that removes censorship ("safety alignment") from transformer-based language models. It's built for people who run local LLMs and want a model that answers prompts without refusals, without doing expensive post-training or manually tuning ablation parameters. If you know how to run a command-line program, you can use it, no knowledge of transformer internals required.

Under the hood, Heretic combines directional ablation (also called abliteration) with a TPE-based parameter optimizer from Optuna. It automatically searches for ablation parameters that minimize refusals while keeping KL divergence from the original model as low as possible, which means less damage to the model's general capabilities compared to hand-tuned abliterations.

Key features

• Fully automatic operation: no configuration is required by default; Heretic benchmarks your hardware, computes residual directions, and optimizes ablation parameters on its own.
• Parameter optimization: uses Optuna's TPE sampler to co-minimize refusal rate and KL divergence, producing decensored models that stay closer to the original model's behavior than many manual abliterations.
• Broad architecture support: works with most dense models, many multimodal models, several MoE architectures, and some hybrid models like Qwen3.5. Pure state-space models and some research architectures aren't supported yet.
• Flexible ablation kernel: per-component ablation weight shapes (attention out-projection vs. MLP down-projection) and a continuous (float) residual direction index that interpolates between layer directions instead of restricting you to a fixed integer layer.
• Built-in evaluation and workflow: after decensoring, you can save the model, upload it to Hugging Face, chat with it to test quality, or run standard benchmarks, all from the same run.
• Quantization support: works with bitsandbytes quantization (bnb_4bit) to cut VRAM requirements for large models.
• Research tooling: optional extras add residual vector plotting (PaCMAP projections, layer-by-layer animations) and detailed residual geometry metrics for interpretability research.

Ideal use cases

Heretic fits people running open-weight LLMs locally who want a decensored variant without manual layer-by-layer tuning or a fine-tuning pipeline. It's a good fit if you already have a GPU capable of running the target model and just want an automated, reproducible abliteration process, including for models the community hasn't already abliterated. It's also useful for interpretability researchers who want to inspect residual geometry and directional structure across layers, thanks to the research extras.

It's not the right tool if you need a model behavior change that isn't refusal removal (e.g., style transfer, knowledge injection) since ablation only targets the refusal direction, not general fine-tuning. It also isn't suited to state-space or other unsupported architectures, and it won't help if you lack the hardware to load the target model in the first place; decensoring a 12B+ model still needs meaningful VRAM even with quantization. If you need guaranteed quality parity with the original model, understand that ablation is a form of intervention and some capability loss, even if minimized, is possible.

Installation

Heretic requires a Python 3.10+ environment with PyTorch 2.2+ (2.6+ recommended for some quantized formats like gpt-oss's MXFP4).

Install and run:

pip install -U heretic-llm
heretic Qwen/Qwen3-4B-Instruct-2507

Replace the model name with whatever Hugging Face model you want to decensor. For research features (residual plotting, residual geometry metrics), install the extra:

pip install -U 'heretic-llm[research]'

Heretic uses uv for dependency management and ships a uv.lock file. If you already use uv, clone the repo and run:

uv run heretic

This pins dependencies to the exact versions used by the developers. To reduce VRAM usage on larger models, set the quantization option to bnb_4bit in the config or via command-line flags. Configuration options are documented via heretic --help or in config.default.toml, though the default run requires no configuration at all.