AbliterationPipeline

Complete API reference for the core OBLITERATUS abliteration pipeline class.

Overview

AbliterationPipeline is the core class for removing refusal directions from a HuggingFace language model. It runs a six-stage pipeline — SUMMON → PROBE → DISTILL → EXCISE → VERIFY → REBIRTH — and writes the liberated model to disk.

from obliteratus.abliterate import AbliterationPipeline

pipeline = AbliterationPipeline(
    model_name="meta-llama/Llama-3.1-8B-Instruct",
    output_dir="abliterated_llama",
    method="advanced",
)
output_path = pipeline.run()
print(f"Model saved to {output_path}")

---

Class: obliteratus.abliterate.AbliterationPipeline

Constructor

AbliterationPipeline(
    model_name,
    output_dir="abliterated",
    device="auto",
    dtype="float16",
    method="advanced",
    ...
)

Core Parameters

model_name · str · required

HuggingFace model name or local path (e.g., "meta-llama/Llama-3.1-8B-Instruct").

output_dir · str · default: "abliterated"

Directory to write the abliterated model and metadata JSON.

device · str · default: "auto"

Device to run on. "auto" uses accelerate device maps; also accepts "cuda", "cpu", "mps".

dtype · str · default: "float16"

Model dtype. One of "float16", "bfloat16", "float32".

trust_remote_code · bool · default: "False"

Pass trust_remote_code=True to AutoModelForCausalLM for models with custom architectures.

method · str · default: "advanced"

Abliteration method preset. See Methods below for all 13 presets.

Method-Override Parameters

All parameters below override the corresponding value in the chosen method preset. Pass None (default) to use the preset’s value.

n_directions · int | None · default: "None"

Number of refusal directions to extract. Preset values range from 1 (basic) to 8 (surgical/inverted).

direction_method · str | None · default: "None"

Algorithm for extracting directions. One of "diff_means", "svd", "leace".

regularization · float | None · default: "None"

Fraction of the refusal component to preserve (0.0 = full removal, 1.0 = no change). Maps to ridge alpha.

refinement_passes · int | None · default: "None"

Number of iterative PROBE → DISTILL → EXCISE loops. Higher values remove more stubborn refusal at the cost of compute.

Hub Parameters

push_to_hub · str | None · default: "None"

HuggingFace repo ID to push the finished model to (e.g., "my-org/my-model-OBLITERATED").

hub_token · str | None · default: "None"

HuggingFace API token. Falls back to HF_TOKEN environment variable.

hub_community_org · str | None · default: "None"

Org namespace for auto-generated Hub repo ID.

Data Parameters

harmful_prompts · list[str] | None · default: "None"

Custom list of harmful prompts for activation collection. Defaults to the built-in 512-pair dataset.

harmless_prompts · list[str] | None · default: "None"

Custom list of harmless prompts. Must be the same length as harmful_prompts when n_directions > 1.

jailbreak_prompts · list[str] | None · default: "None"

Custom jailbreak prompts for contrastive direction refinement (used when use_jailbreak_contrast=True).

Hardware / Memory Parameters

quantization · str | None · default: "None"

Load with quantization: "4bit" or "8bit". Requires bitsandbytes.

large_model_mode · bool · default: "False"

Conservative defaults for 120B+ models: caps n_directions at 4, n_sae_features at 4, and refinement_passes at 1 unless explicitly overridden.

max_seq_length · int | None · default: "None"

Override truncation length for all internal tokenizer calls. None uses context-dependent defaults (256 for probes, 512 for verify).

verify_sample_size · int | None · default: "30"

Number of harmful prompts tested in the VERIFY stage for refusal-rate measurement. Increase to 100 for tighter confidence intervals.

Callback Parameters

on_stage · Callable[[StageResult], None] | None · default: "None"

Callback fired on every stage status change. Receives a StageResult object — useful for progress UIs.

on_log · Callable[[str], None] | None · default: "None"

Callback fired for every log message emitted by the pipeline.

SOTA Technique Flags

use_jailbreak_contrast · bool | None · default: "None"

Refine directions by contrasting jailbroken responses against direct harmful prompts.

layer_adaptive_strength · bool | None · default: "None"

Scale projection strength per-layer based on measured refusal signal magnitude.

safety_neuron_masking · bool | None · default: "None"

Mask out the specific neurons most responsible for safety behavior before projection.

per_expert_directions · bool | None · default: "None"

Extract separate refusal directions per MoE expert (uses router profiling hooks).

attention_head_surgery · bool | None · default: "None"

Apply targeted projection to the top safety-attributable attention heads.

use_sae_features · bool | None · default: "None"

Extract and abliterate SAE-identified refusal features.

invert_refusal · bool | None · default: "None"

Reflect the refusal direction rather than project it out — makes the model actively compliant instead of neutral.

use_whitened_svd · bool | None · default: "None"

Use covariance-whitened SVD (WhitenedSVDExtractor) for cleaner direction extraction.

true_iterative_refinement · bool | None · default: "None"

Re-probe the model between refinement passes to track direction rotation.

Nuclear-Mode Parameters

reflection_strength · float | None · default: "None"

Reflection multiplier when invert_refusal=True. 2.0 = full inversion; 1.25 = tempered (nuclear default).

project_embeddings · bool | None · default: "False"

Also project refusal from the token embedding matrix.

embed_regularization · float | None · default: "None"

Regularization fraction for embedding projection.

activation_steering · bool | None · default: "False"

Install lightweight inference-time steering hooks as residual cleanup after weight editing.

steering_strength · float | None · default: "None"

Alpha for activation steering hooks.

expert_transplant · bool | None · default: "False"

Blend safety-expert weights into capability experts (nuclear mode only).

transplant_blend · float | None · default: "None"

Blend ratio for expert transplant (0.0–1.0).

n_sae_features · int | None · default: "None"

Number of SAE features to abliterate per layer.

Heretic-Inspired Parameters

winsorize_activations · bool | None · default: "None"

Clamp outlier activations by symmetric quantile before direction extraction.

winsorize_percentile · float | None · default: "None"

Quantile for winsorization (e.g., 0.01 = clamp at 1st/99th percentile).

use_kl_optimization · bool | None · default: "None"

Co-minimize refusal rate and KL divergence during Bayesian optimization.

kl_budget · float | None · default: "None"

Maximum allowed KL divergence increase. Acts as a capability-preservation constraint.

float_layer_interpolation · bool | None · default: "None"

Use continuous (float) layer indices with linear interpolation between adjacent layers’ directions.

cot_aware · bool | None · default: "None"

Detect and preserve chain-of-thought reasoning directions to maintain CoT capability.

use_wasserstein_optimal · bool | None · default: "None"

Use Wasserstein-optimal transport for direction extraction.

layer_selection · str | None · default: "None"

Layer selection strategy: "knee_cosmic" (default), "all", "all_except_first", "top_k".

rdo_refinement · bool | None · default: "None"

Refine directions via gradient-based optimization against a linear refusal probe (RDO method).

Spectral Cascade Parameters

spectral_cascade · bool | None · default: "None"

Enable DCT frequency-domain decomposition of the refusal signal across layers.

spectral_bands · int | None · default: "None"

Number of frequency bands for spectral cascade (default: 3).

spectral_threshold · float | None · default: "None"

Minimum signal power below which a frequency band is skipped.

---

Method: run()

def run(self) -> Path

Executes the full abliteration pipeline. Returns the Path to the saved model directory.

The pipeline runs six stages in sequence:

#	Stage	What happens
1	SUMMON	Load model and tokenizer into memory
2	PROBE	Run harmful and harmless prompts, collect residual-stream activations
3	DISTILL	Compute refusal directions via SVD / diff-means / LEACE
4	EXCISE	Project refusal directions out of attention and FFN weight matrices
5	VERIFY	Measure refusal rate, perplexity, coherence, and KL divergence
6	REBIRTH	Save model weights + abliteration_metadata.json

Calling run() multiple times on the same instance replaces any steering hooks installed by the previous run before starting fresh.

---

Post-Run Attributes

After run() completes, the following attributes are populated:

refusal_directions · dict[int, torch.Tensor]

Per-layer primary refusal direction. Keys are layer indices; values are (hidden_dim,) unit tensors.

_strong_layers · list[int]

Layer indices selected for weight modification (knee-detected or analysis-recommended).

_quality_metrics · dict[str, float]

Quality metrics from the VERIFY stage.

Show Fields

perplexity · float

Model perplexity on harmless text after abliteration.

coherence · float

Text coherence score (0–1).

refusal_rate · float

Fraction of harmful prompts still refused (0.0 = none refused, 1.0 = all refused).

kl_divergence · float

KL divergence between pre- and post-excision logit distributions. Lower = less capability damage.

---

StageResult — Callback Payload

The on_stage callback receives a StageResult dataclass on every status change:

@dataclass
class StageResult:
    stage: str      # e.g. "summon", "probe", "distill", "excise", "verify", "rebirth"
    status: str     # "running", "done", or "error"
    message: str    # human-readable progress message
    duration: float # elapsed seconds (populated when status == "done")
    details: dict   # stage-specific data (layer counts, metrics, etc.)

---

Pipeline Stages

The STAGES list is exported from obliteratus.abliterate:

from obliteratus.abliterate import STAGES
# STAGES is a list of PipelineStage(key, name, description)

Key	Name	Description
summon	SUMMON	Loading model into memory
probe	PROBE	Probing refusal circuits with prompt pairs
distill	DISTILL	Distilling refusal subspace via SVD decomposition
excise	EXCISE	Excising refusal directions from weights
verify	VERIFY	Verifying model coherence and measuring quality delta
rebirth	REBIRTH	Saving the liberated model

---

Methods

The METHODS dict is exported from obliteratus.abliterate. Pass the key to the method constructor argument.

Key	Label	n_dirs	dir_method	Notes
basic	Basic (Arditi et al.)	1	diff_means	Single direction, no norm preservation
advanced	Advanced	4	svd	Multi-direction + norm-preserving + regularization
aggressive	Aggressive	8	svd	Whitened SVD + jailbreak contrast + attention surgery
spectral_cascade	Spectral Cascade	6	svd	DCT frequency-domain decomposition across layers
informed	Informed	1	diff_means	Analysis-guided; use InformedAbliterationPipeline
surgical	Surgical	8	svd	Head surgery + SAE + neuron masking
inverted	Inverted	8	svd	2x reflection — inverts refusal logic
optimized	Optimized	4	svd	Bayesian-tuned per-layer strengths (50 trials)
nuclear	Nuclear	4	svd	Full combo: reflection + steering + expert transplant
failspy	FailSpy baseline	1	diff_means	Reproduction of FailSpy/abliterator
gabliteration	Gabliteration baseline	4	svd	Faithful Gülmez 2026 reproduction
heretic	Heretic baseline	1	diff_means	Bayesian LoRA ablation (p-e-w)
rdo	RDO baseline	4	svd	Gradient-refined probe-aligned directions

---

Code Examples

Basic Usage

from obliteratus.abliterate import AbliterationPipeline

pipeline = AbliterationPipeline(
    model_name="meta-llama/Llama-3.1-8B-Instruct",
    output_dir="abliterated_llama",
    method="advanced",
    device="auto",
    dtype="bfloat16",
)
output_path = pipeline.run()
print(f"Saved to: {output_path}")
print(f"Refusal rate: {pipeline._quality_metrics['refusal_rate']:.0%}")
print(f"KL divergence: {pipeline._quality_metrics['kl_divergence']:.4f}")

from obliteratus.abliterate import AbliterationPipeline, StageResult

def on_stage(result: StageResult):
    print(f"[{result.stage.upper()}] {result.status}: {result.message}")

pipeline = AbliterationPipeline(
    model_name="mistralai/Mistral-7B-Instruct-v0.3",
    output_dir="abliterated_mistral",
    method="aggressive",
    # Override preset values
    n_directions=6,
    regularization=0.05,
    refinement_passes=2,
    verify_sample_size=100,
    on_stage=on_stage,
    on_log=print,
)
output_path = pipeline.run()

from obliteratus.abliterate import AbliterationPipeline

pipeline = AbliterationPipeline(
    model_name="Qwen/Qwen2.5-7B-Instruct",
    output_dir="abliterated_qwen",
    method="surgical",
    push_to_hub="my-username/Qwen2.5-7B-OBLITERATED",
    hub_token="hf_...",
)
pipeline.run()

from obliteratus.abliterate import AbliterationPipeline

pipeline = AbliterationPipeline(
    model_name="meta-llama/Llama-3.1-70B-Instruct",
    output_dir="abliterated_llama_70b",
    method="advanced",
    quantization="4bit",
    large_model_mode=True,  # conservative memory defaults
    device="auto",
    dtype="bfloat16",
)
pipeline.run()