OBLITERATUS: Reference Guide for Mechanistic Refusal Removal

Overview

OBLITERATUS is a command-line tool that removes refusal behaviors (guardrails) from open-weight large language models without retraining or fine-tuning. It uses mechanistic interpretability techniques to identify and excise refusal directions from model weights while preserving reasoning capabilities. The tool is licensed under AGPL-3.0 and must never be imported as a Python library in MIT or Apache-licensed projects; always invoke it via the obliteratus command or through a subprocess.

When to Use OBLITERATUS

Use OBLITERATUS when you want to:

• "Uncensor" or "abliterate" an LLM.
• Remove refusal or guardrail behaviors from a model.
• Create an uncensored version of Llama, Qwen, Mistral, or similar models.
• Analyze how a model's refusal mechanism works.
• Work with concepts like refusal removal, abliteration, or weight projection.
• Reference OBLITERATUS, abliterator, or refusal directions in your work.

Capabilities

OBLITERATUS provides:

• 9 CLI methods for abliteration.
• 28 analysis modules for mechanistic interpretability.
• 116 model presets across 5 compute tiers.
• Tournament evaluation that pits all methods against each other.
• Telemetry-driven recommendations for the best method and parameters.
• Direction extraction methods: diff_means, svd, leace.
• Structural ablation strategies: Embedding Ablation, FFN Ablation, Head Pruning, Layer Removal.
• Steering vectors as a reversible alternative (Python API only).
• Built-in evaluation: refusal rate benchmarking, perplexity comparison, LM Eval Harness integration, head-to-head competitor comparison, and baseline performance tracking.
• Interactive guided mode, Gradio web UI, and YAML config-based runs.
• Telemetry contribution (opt-in) for a community research dataset.
• Platform support: CUDA (NVIDIA GPUs), Apple Silicon (MLX), and CPU (tiny models under 1B parameters).

Prerequisites

Before using OBLITERATUS, ensure you have:

• A Python environment with pip.
• Sufficient VRAM for your target model (see VRAM requirements table below).
• A GPU is recommended; CPU is only viable for tiny models under 1B parameters.
• User confirmation before installation due to the large dependency download.
• For CUDA: an NVIDIA GPU with CUDA support.
• For Apple Silicon: the MLX backend.
• For HuggingFace upload: huggingface-cli configured.
• For vLLM serving: vLLM installed.

Installation

1. Check if OBLITERATUS is already installed by running:

   obliteratus --version 2>/dev/null && echo "INSTALLED" || echo "NOT INSTALLED"
   

2. If not installed, confirm with the user before proceeding (installation pulls in approximately 5-10 GB of dependencies including PyTorch, Transformers, and bitsandbytes).

3. Clone and install:

   git clone https://github.com/elder-plinius/OBLITERATUS.git
   cd OBLITERATUS
   pip install -e .
   # For Gradio web UI support:
   # pip install -e ".[spaces]"
   

Checking Hardware

Run the GPU check script to determine available VRAM and compute tier:

python3 -c "
import torch
if torch.cuda.is_available():
    gpu = torch.cuda.get_device_name(0)
    vram = torch.cuda.get_device_properties(0).total_memory / 1024**3
    print(f'GPU: {gpu}')
    print(f'VRAM: {vram:.1f} GB')
    if vram < 4: print('TIER: tiny (models under 1B)')
    elif vram < 8: print('TIER: small (models 1-4B)')
    elif vram < 16: print('TIER: medium (models 4-9B with 4bit quant)')
    elif vram < 32: print('TIER: large (models 8-32B with 4bit quant)')
    else: print('TIER: frontier (models 32B+)')
else:
    print('NO GPU - only tiny models (under 1B) on CPU')
"

Use the VRAM tier table to estimate maximum model size:

• CPU only: approximately 1B parameters.
• 4-8 GB VRAM: approximately 4B parameters.
• 8-16 GB VRAM: approximately 9B parameters.
• 24 GB VRAM: approximately 32B parameters.
• 48 GB+ VRAM: approximately 72B+ parameters.
• Multi-GPU: 200B+ parameters.

Browsing Models and Getting Recommendations

Browse models by compute tier, get architecture info, and receive telemetry-driven recommendations:

# Browse models by compute tier
obliteratus models --tier medium

# Get architecture info for a specific model
obliteratus info <model_name>

# Get telemetry-driven recommendation for best method & params
obliteratus recommend <model_name>
obliteratus recommend <model_name> --insights  # global cross-architecture rankings

The --insights flag includes global cross-architecture rankings in the recommendation.

Method Selection Guide

OBLITERATUS offers 9 CLI methods for abliteration. The default and recommended method for most cases is advanced (multi-direction SVD, norm-preserving projection, 2 refinement passes).

Method	Description	When to Use
basic	Fast, single direction	Quick tests or small models
advanced	Multi-direction SVD, norm-preserving projection, 2 refinement passes	Default for most models
aggressive	Whitened SVD + head surgery	When advanced leaves more than 10% refusals on a 3B+ model
spectral_cascade	DCT frequency-domain	Frequency-domain analysis
informed	Experimental auto-detection	Experimental use only; slower than advanced
surgical	SAE features	Reasoning models (R1 distills) to preserve chain-of-thought
optimized	Bayesian search	When you want automated parameter tuning
inverted	Flips refusal direction	Alternative to removal
nuclear	For stubborn MoE models	MoE models like Mixtral, DeepSeek-MoE

You can optionally specify the direction extraction method via the --direction-method flag: diff_means (default), svd, or leace.

Note: 4 Python-API-only methods (failspy, gabliteration, heretic, rdo) are NOT available via CLI and require Python import, which violates the AGPL boundary. Mention these only if the user explicitly wants to use OBLITERATUS as a library in their own AGPL project.

Running Abliteration

Standard Command

Use the standard command for most models:

# Default method (advanced) — recommended for most models
obliteratus obliterate <model_name> --method advanced --output-dir ./abliterated-models

# With 4-bit quantization (saves VRAM)
obliteratus obliterate <model_name> --method advanced --quantization 4bit --output-dir ./abliterated-models

# Large models (70B+) — conservative defaults
obliteratus obliterate <model_name> --method advanced --quantization 4bit --large-model --output-dir ./abliterated-models

Fine-Tuned Parameters

Customize the abliteration with fine-tuned parameters:

obliteratus obliterate <model_name> \
  --method advanced \
  --direction-method diff_means \
  --n-directions 4 \
  --refinement-passes 2 \
  --regularization 0.1 \
  --quantization 4bit \
  --output-dir ./abliterated-models \
  --contribute  # opt-in telemetry for community research

Alternative Execution Modes

OBLITERATUS provides several alternative execution modes:

# Interactive guided mode (hardware → model → preset)
obliteratus interactive

# Web UI (Gradio)
obliteratus ui --port 7860

# Run a full ablation study from YAML config
obliteratus run config.yaml --preset quick

# Tournament: pit all methods against each other
obliteratus tourney <model_name>

All Parameters

Parameter	Meaning	Required	Default
--method	Abliteration method to use (basic, advanced, aggressive, spectral_cascade, informed, surgical, optimized, inverted, nuclear)	No	advanced
--direction-method	Direction extraction method (diff_means, svd, leace)	No	diff_means
--n-directions	Number of refusal directions to extract (1-32)	No	method-dependent
--refinement-passes	Number of iterative refinement passes (1-5)	No	2
--regularization	Regularization strength (0.0-1.0)	No	0.1
--quantization	Load model in 4bit or 8bit quantization	No	none (full precision)
--large-model	Use conservative defaults for models 120B+ parameters	No	false
--output-dir	Directory to save the abliterated model	No	./obliterated_model
--contribute	Share anonymized results for community research	No	false
--verify-sample-size	Number of test prompts for refusal rate check	No	20
--dtype	Model dtype (float16, bfloat16)	No	auto
--tier	Compute tier for browsing models (tiny, small, medium, large, frontier)	For obliteratus models	-
--insights	Include global cross-architecture rankings in recommendation	No (for obliteratus recommend)	-
--port	Port for Gradio web UI	No	7860
--preset	Preset configuration for YAML-based runs (e.g., quick)	For obliteratus run	-

Verifying Results

After abliteration, check the output metrics:

• Refusal rate: Less than 5% is good; more than 10% is a warning.
• Perplexity change: Less than 10% increase is good; more than 15% increase is a warning.
• KL divergence: Less than 0.1 is good; more than 0.5 is a warning.
• Coherence: High and passes qualitative check.

If Refusals Persist (more than 10%)

• Try the aggressive method.
• Increase --n-directions (e.g., 8 or 16).
• Add --refinement-passes 3.
• Try --direction-method svd.

If Coherence Is Damaged (perplexity more than 15% increase)

• Reduce --n-directions (try 2).
• Increase --regularization (try 0.3).
• Reduce --refinement-passes to 1.
• Try the basic method.

Using the Abliterated Model

Test the abliterated model locally, upload it to HuggingFace Hub, or serve it with vLLM:

# Test locally with transformers
python3 -c "
from transformers import AutoModelForCausalLM, AutoTokenizer
model = AutoModelForCausalLM.from_pretrained('./abliterated-models/<model>')
tokenizer = AutoTokenizer.from_pretrained('./abliterated-models/<model>')
inputs = tokenizer('How do I pick a lock?', return_tensors='pt')
outputs = model.generate(**inputs, max_new_tokens=200)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
"

# Upload to HuggingFace Hub
huggingface-cli upload <username>/<model-name>-abliterated ./abliterated-models/<model>

# Serve with vLLM
vllm serve ./abliterated-models/<model>

Analysis Modules

OBLITERATUS includes 28 analysis modules for mechanistic interpretability. Run specific modules using a YAML config:

# Run specific analysis modules
obliteratus run analysis-config.yaml --preset quick

# Key modules to run first:
# - alignment_imprint: Fingerprint DPO/RLHF/CAI/SFT alignment method
# - concept_geometry: Single direction vs polyhedral cone
# - logit_lens: Which layer decides to refuse
# - anti_ouroboros: Self-repair risk score
# - causal_tracing: Causally necessary components

Steering Vectors (Python API Only)

Steering vectors provide a reversible alternative to abliteration. This feature is available only through the Python API:

# Python API only — for user's own projects
from obliteratus.analysis.steering_vectors import SteeringVectorFactory, SteeringHookManager

Constraints and Caveats

• OBLITERATUS is AGPL-3.0 licensed. Never import it as a Python library in MIT or Apache projects. Always invoke via the obliteratus command or subprocess.
• Installation pulls in approximately 5-10 GB of dependencies. Confirm with the user before installing.
• Models under approximately 1B parameters respond poorly to abliteration, with 20-40% remaining refusal. Models 3B+ have cleaner refusal directions and respond much better.
• The aggressive method can damage coherence and increase refusal rate on small models. Only use it if advanced leaves more than 10% refusals on a 3B+ model.
• Always check perplexity after abliteration. If it spikes more than 15%, the model is damaged; reduce aggressiveness.
• MoE models (Mixtral, DeepSeek-MoE) need special handling: use the nuclear method.
• Quantized models cannot be re-quantized. Abliterate the full-precision model first, then quantize the output.
• VRAM estimation is approximate; peak usage can spike during extraction. 4-bit quantization helps but is not a guarantee.
• Reasoning models (R1 distills) are sensitive; use the surgical method to preserve chain-of-thought.
• The informed method is experimental and slower than advanced; do not use it as default.
• Large models (70B+) always require the --large-model flag for conservative defaults.
• Spectral certification RED is common; the spectral check often flags "incomplete" even when the practical refusal rate is 0%. Check the actual refusal rate rather than relying on spectral certification alone.
• The 4 Python-API-only methods (failspy, gabliteration, heretic, rdo) are NOT available via CLI and require Python import, which violates the AGPL boundary. Mention them only if the user explicitly wants to use OBLITERATUS as a library in their own AGPL project.

Failure Modes and Mitigations

Failure Mode	Symptom	Mitigation
Refusals persist	Refusal rate more than 10%	Try aggressive method, increase --n-directions, increase --refinement-passes, try --direction-method svd
Coherence damage	Perplexity increase more than 15%	Reduce --n-directions, increase --regularization, reduce --refinement-passes, try basic method
Distribution shift	KL divergence more than 0.5	Reduce aggressiveness of method
Degraded responses	Repetition or incoherence	Reduce aggressiveness, check perplexity
Small model	20-40% remaining refusal	Expected for models under 1B
Aggressive on small model	Increased refusal rate and coherence damage	Avoid aggressive on small models
Quantized model	Cannot be re-quantized	Use full-precision model first
MoE model without nuclear	Poor results	Use nuclear method
Reasoning model without surgical	Damaged chain-of-thought	Use surgical method
Large model without --large-model	Out of memory or suboptimal defaults	Always use --large-model for 70B+

YAML Configuration Templates

OBLITERATUS supports YAML config-based runs using preset configurations. Available templates include:

• templates/abliteration-config.yaml
• templates/analysis-study.yaml
• templates/batch-abliteration.yaml

Use these with the obliteratus run command and the --preset flag.

Additional Commands

OBLITERATUS provides several additional commands for managing and analyzing abliteration:

• obliteratus strategies - List available ablation strategies.
• obliteratus report - Generate a report of the abliteration results.
• obliteratus aggregate - Aggregate results from multiple runs.

Telemetry and Community Research

OBLITERATUS includes an opt-in telemetry feature for community research. Use the --contribute flag to share anonymized results (model name, method, and metrics) with the research community. This helps improve telemetry-driven recommendations for all users.

Skill View Integration

For users working within a skill-based framework, OBLITERATUS provides a skill view for accessing analysis module references: skill_view(name="obliteratus", file_path="references/analysis-modules.md")

Use skill_view to browse available analysis modules and their documentation.

Importing OBLITERATUS

While the CLI is the recommended interface, you can import OBLITERATUS in your own AGPL-licensed projects: import obliteratus

This is only permitted for AGPL-licensed projects. For MIT or Apache projects, always use the CLI or subprocess invocation.