elder-plinius/obliteratus

Purpose and Entry Points

OBLITERATUS is a Python research toolkit for locating, analyzing, and modifying transformer representations associated with refusal behavior. Primary interfaces are the package CLI (obliteratus/__main__.py, obliteratus/cli.py), programmatic pipelines (obliteratus/abliterate.py, obliteratus/informed_pipeline.py), and Gradio application (app.py, obliteratus/local_ui.py).

Pipeline Orchestration

AbliterationPipeline owns the standard lifecycle: load a Hugging Face model/tokenizer, collect contrastive activations, extract refusal directions, project them from model weights, evaluate outcomes, and persist the modified model and metadata. The analysis-informed variant inserts adaptive analysis before intervention and can iterate when robustness checks detect residual behavior.

Paths: obliteratus/abliterate.py, obliteratus/informed_pipeline.py, obliteratus/runner.py.

Model Loading and Hardware Boundary

Model access is abstracted behind loaders and device utilities, supporting Hugging Face transformer architectures, dtype/quantization choices, and multi-GPU device_map sharding. Remote execution is a separate SSH/SCP boundary that can provision/run remotely and synchronize outputs.

Paths: obliteratus/models/loader.py, obliteratus/device.py, obliteratus/remote.py, obliteratus/mlx_backend.py.

Intervention Engines

Two related intervention paths exist: permanent weight surgery and reversible inference-time steering. Weight projection logic is centered in the abliteration pipeline; configurable ablation studies independently mutate layers, heads, FFNs, or embedding dimensions, measure effects, and restore state between trials. Strategy registration decouples study definitions from execution.

Paths: obliteratus/abliterate.py, obliteratus/strategies/base.py, obliteratus/strategies/registry.py, obliteratus/analysis/steering_vectors.py.

Mechanistic Analysis Layer

The analysis package provides pluggable measurements over captured activations and model internals: cross-layer alignment, probing, causal tracing, residual-stream decomposition, geometry, robustness, sparse surgery, and transfer. These modules are both research-facing APIs and decision inputs to InformedAbliterationPipeline.

Paths: obliteratus/analysis/activation_probing.py, obliteratus/analysis/concept_geometry.py, obliteratus/analysis/defense_robustness.py, obliteratus/analysis/cross_layer.py.

Evaluation and Reporting

Evaluation separates benchmark/metric computation from intervention logic, covering refusal behavior and capability-preservation signals such as perplexity, coherence, KL divergence, and advanced metrics. Reporting renders run results; tournament/sweep modules coordinate comparisons and parameter exploration.

Paths: obliteratus/evaluation/evaluator.py, obliteratus/evaluation/metrics.py, obliteratus/reporting/report.py, obliteratus/tourney.py.

Study Configuration and Community Data

YAML-driven studies flow through configuration, presets, and the runner to execute repeatable ablation experiments. Telemetry and community modules form a data-sharing boundary: aggregate run metadata/results can be submitted or loaded without embedding core pipeline behavior in UI/CLI code.

Paths: obliteratus/config.py, obliteratus/study_presets.py, obliteratus/telemetry.py, obliteratus/community.py.

Runtime and External Services

The project runs on Python with PyTorch/Hugging Face model infrastructure; Gradio powers the local and Hugging Face Spaces UI. It integrates with Hugging Face Hub for model retrieval/export, CUDA/Accelerate and bitsandbytes for GPU placement/quantization, optional Apple MLX support, and SSH-capable remote GPU hosts. Packaging and runtime dependencies are defined in pyproject.toml, requirements.txt, and Dockerfile.