heretic · v1.0 · 2026-07-27 · sha256 926568b18a360c29
heretic v1.0A
Immutable. This exact content is served forever at /api/v1/blob/926568b18a360c29.
--- 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](https://github.com/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](https://arxiv.org/abs/2406.11717)): 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) ```sh 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: ```sh 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) ```sh 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](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](references/abliteration-and-optimization.md) · CLI/config: [references/cli-and-config.md](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 ```sh # 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](references/install.md) for env knobs and reproducible (uv.lock) setup. ## Bundled references - [references/abliteration-and-optimization.md](references/abliteration-and-optimization.md) — the algorithm, kernel params, Optuna objective. - [references/cli-and-config.md](references/cli-and-config.md) — flags, `config.*.toml` keys, presets, quantization. - [references/research-and-scrapling.md](references/research-and-scrapling.md) — interpretability features + the `scrapling` discovery route. - [references/install.md](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).