heretic

name	heretic
description	Runs directional ablation and refusal-direction analysis for open-weight models the user may modify; use to reduce benign over-refusal or measure refusal/KL trade-offs, not for training.
allowed-tools	Bash Read Write Edit Glob Grep WebFetch
compatibility	Requires Python 3.10+ with PyTorch 2.2+ (2.6+ for MXFP4-quantized models such as gpt-oss) installed for your hardware; a CUDA GPU is strongly recommended (an RTX 3090 decensors a 4B model in ~20-30 min). Install with `pip install -U heretic-llm` (or `uv run heretic`); the `[research]` extra adds PaCMAP/matplotlib for residual plots. bitsandbytes enables 4-bit quantization to fit larger models. Model discovery / dataset / benchmark web research uses the `scrapling` skill.
license	AGPL-3.0-or-later
metadata	{"tags":"heretic, abliteration, directional-ablation, decensor, refusal-direction, interpretability, residual-geometry, llm-safety-research, optuna, scrapling","version":"1.0","source":"https://github.com/p-e-w/heretic"}

heretic — Automatic Abliteration & Refusal-Direction Interpretability

Keyword: heretic · abliterate · decensor a model · remove refusals · refusal direction · plot residuals

Responsible use. Heretic is AGPL-3.0 software for research and for customizing models you have the right to modify. Respect each base model's license and every platform's Terms of Service when downloading, modifying, uploading, or serving weights. Abliteration lowers a model's refusal rate on all topics, including genuinely harmful ones — do not use it to produce a model for illegal content (e.g. CSAM, weapons-of-mass-destruction uplift, targeted harassment) or to evade safety controls you are contractually bound by. Legitimate uses include interpretability/alignment research, red-teaming, reducing benign over-refusal, and running uncensored models on your own hardware for lawful work.

heretic packages the p-e-w/heretic tool (AGPL-3.0) as an installable jeo-skills plugin. Heretic implements a parametrized variant of directional ablation (abliteration, after Arditi et al. 2024): it computes a per-layer "refusal direction" as the difference-of-means between first-token residuals for harmful and harmless prompts, then orthogonalizes the attention out-projection and MLP down-projection matrices against it — inhibiting refusals without any fine-tuning or post-training. A TPE optimizer (Optuna) searches the ablation kernel to minimize refusals while keeping KL-divergence from the original model low, so the process is fully automatic and needs no configuration.

This skill is routing-first: pick the smallest workable mode for the request, keep the responsible-use guardrails above in view, and route web-based discovery/research through scrapling.

---

When to use / not use

Use heretic when the user wants to:

• Decensor / abliterate / un-refuse an open-weight model (Qwen, Llama, Gemma, gpt-oss, Mistral, …).
• Reduce benign over-refusal while preserving capability (low KL-divergence).
• Tune the ablation: trial budget, KL target, quantization to fit VRAM, chat/evaluate/upload after.
• Measure a model: refusal count on harmful prompts + KL-divergence vs the original.
• Do interpretability research: refusal-direction geometry, residual-geometry metrics, PaCMAP plots.

Do NOT route here (answer directly or elsewhere):

• "Recommend an already-uncensored model to download" → answer directly (point at HF ?other=heretic).
• General LLM fine-tuning / RLHF / DPO → that is training, not ablation (different tools).
• Requests whose only plausible purpose is producing genuinely illegal/harmful content → decline.

---

Modes (pick the smallest that satisfies the request)

Mode	Trigger	Command / action
decensor (default)	"abliterate / decensor <model>"	heretic <model> — fully automatic; then choose save / upload / chat / evaluate
configure	"fit in 16GB", "more trials", "less brain damage"	edit config.*.toml or pass flags (--quantization bnb_4bit, --n-trials, --kl-divergence-target)
evaluate	"how censored is it / did it work"	heretic --model <orig> --evaluate-model <candidate> → refusals + KL
research	"plot residuals", "refusal geometry"	pip install -U 'heretic-llm[research]'; --plot-residuals / --print-residual-geometry
discover (scrapling)	"find a base model / existing heretic model / benchmarks"	route web extraction through scrapling (see below)

Start narrow: an evaluate or discover request must not kick off a full multi-hour decensor run.

decensor (default)

pip install -U heretic-llm          # or: uv run heretic  (pins uv.lock for reproducibility)
heretic Qwen/Qwen3-4B-Instruct-2507 # replace with any model you have the right to modify

The run is fully automatic: Heretic benchmarks the hardware to pick a batch size, computes refusal directions, then runs the Optuna TPE optimizer (default n_trials = 200, n_startup_trials = 60) to co-minimize (a) refusals on harmful prompts and (b) KL-divergence from the original on harmless prompts. When it finishes you are offered: save, upload to Hugging Face, chat (test), and run benchmarks — any combination. Checkpoints land in checkpoints/ so a run can resume.

configure

Fully automatic already works; reach for config only for hardware/quality control. Common knobs (see config.default.toml, or the bundled presets config.nohumor.toml / config.noslop.toml):

• quantization = "bnb_4bit" — bitsandbytes 4-bit to fit larger models in less VRAM.
• kl_divergence_target (default 0.01) — raise to allow deeper ablation, lower to protect capability.
• n_trials (default 200) — more trials = better compliance/quality tradeoff, longer runtime.
• dtypes, device_map, max_batch_size, max_response_length, refusal_markers.

Run heretic --help for all CLI flags; any TOML key is also a --kebab-case flag.

evaluate

Reproduce the metric table (refusals for harmful prompts / KL-divergence for harmless prompts) without re-abliterating — e.g. to compare your output against an existing community model:

heretic --model google/gemma-3-12b-it --evaluate-model p-e-w/gemma-3-12b-it-heretic

Report both numbers: lower refusals = less censored; lower KL = less capability damage. A good abliteration matches others' refusal suppression at a much lower KL (Heretic's headline result).

research (interpretability)

pip install -U 'heretic-llm[research]'
heretic <model> --print-residual-geometry   # metrics table: cosine sims, norms, silhouette
heretic <model> --plot-residuals            # PaCMAP projection PNG per layer + animated GIF

--print-residual-geometry prints per-layer S(g,b), S(g*,b*), refusal-direction norms and the silhouette coefficient of the harmful/harmless clusters (g=good/harmless mean, b=bad/harmful mean, *=geometric median, r = b − g = refusal direction). --plot-residuals runs a PaCMAP projection (CPU-heavy — an hour+ for large models) and renders a layer-by-layer residual animation.

discover (route through scrapling)

For anything requiring the live web — locating a base model, checking whether a heretic/abliterated version already exists, or pulling benchmark/prior-art numbers — route to the scrapling skill and pick its lightest workable mode. See references/research-and-scrapling.md.

---

How Heretic works (one screen)

1. Refusal directions. For each layer, mean first-token residual for harmful prompts minus that for harmless prompts (r = b − g). A float direction_index interpolates between adjacent layers' directions, unlocking directions no single layer provides.
2. Ablation. Orthogonalize attention out-projection and MLP down-projection against r. A flexible per-component weight kernel (max_weight, max_weight_position, min_weight, min_weight_distance) shapes how strongly each layer is ablated.
3. Optimize. Optuna TPE searches kernel + direction params to minimize refusals and KL-divergence simultaneously. Attention and MLP get separate parameters (MLP interventions are more damaging).

Detail: references/abliteration-and-optimization.md · CLI/config: references/cli-and-config.md.

---

Workflow

1. Classify the request → mode (decensor / configure / evaluate / research / discover). Recommendation-only or clearly-illegal-purpose requests do not launch a run.
2. Confirm rights & hardware. The model must be one the user may modify; confirm a GPU + enough VRAM (offer --quantization bnb_4bit when tight). Warn on multi-hour runtimes / PaCMAP cost.
3. Discover (if needed) via scrapling — base model, existing heretic version, benchmark baselines.
4. Install & run the smallest command for the mode. Prefer uv run heretic for reproducibility.
5. Report metrics — refusals + KL, checkpoint/plot paths — and the follow-up options (save / upload / chat / evaluate / benchmark).

---

Error handling & gotchas

• torch.accelerator / MXFP4 errors (e.g. gpt-oss) → PyTorch 2.6+ required; upgrade torch.
• CUDA OOM → set quantization = "bnb_4bit", lower max_batch_size, or pick a smaller model.
• PaCMAP is slow → it runs on CPU; an hour+ for large models is expected, not a hang.
• Research features missing → install the [research] extra (pip install -U 'heretic-llm[research]').
• Non-deterministic metrics → refusal/KL numbers are platform- and hardware-dependent; report the env.
• Over-ablation (broken/incoherent model) → lower kl_divergence_target, raise n_trials, or reduce MLP ablation weights; re-evaluate before shipping.

Follow-ups

• "Fit it in my VRAM" → --quantization bnb_4bit + lower batch size (configure).
• "It's still refusing" → raise kl_divergence_target / n_trials, or check the refusal markers (configure).
• "Prove it works" → --evaluate-model against the original + a known-good community model (evaluate).
• "Show me the refusal geometry" → [research] extra + --print-residual-geometry / --plot-residuals.
• "Is there already a heretic version?" → scrapling HuggingFace ?other=heretic search (discover).

---

Install

# As a jeo-skills plugin (routing skill):
npx skills add https://github.com/akillness/jeo-skills --skill heretic

Install the Heretic tool itself into a Python env (PyTorch 2.2+ preinstalled):

bash scripts/install.sh # pip install -U heretic-llm (+ [research] with RESEARCH=1) RESEARCH=1 bash scripts/install.sh # include interpretability extras UV=1 bash scripts/install.sh # clone repo + uv sync for pinned, reproducible deps

See references/install.md for env knobs and reproducible (uv.lock) setup.

Bundled references

• references/abliteration-and-optimization.md — the algorithm, kernel params, Optuna objective.
• references/cli-and-config.md — flags, config.*.toml keys, presets, quantization.
• references/research-and-scrapling.md — interpretability features + the scrapling discovery route.
• references/install.md — pip vs uv, PyTorch/CUDA/bitsandbytes prerequisites, responsible-use.

Upstream: https://github.com/p-e-w/heretic (AGPL-3.0-or-later, © 2025-2026 Philipp Emanuel Weidmann + contributors).