# elder-plinius/obliteratus architecture

> Architecture diagram of the GitHub repository elder-plinius/obliteratus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elder-plinius/obliteratus
- Repository: https://github.com/elder-plinius/obliteratus

## Overview

#### 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`.

Main entry points: [`obliteratus/abliterate.py`](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/abliterate.py) (Abliteration Pipeline), [`obliteratus/informed_pipeline.py`](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/informed_pipeline.py) (Informed Pipeline), [`obliteratus/runner.py`](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/runner.py) (Study Runner), [`obliteratus/models/loader.py`](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/models/loader.py) (Model Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>Python entrypoint<br/>[cli.py]"]
  node_gradio["Local Gradio UI<br/>[local_ui.py]"]
end

subgraph group_pipelines["Pipelines &amp; Studies"]
  node_standard_pipeline["Abliteration Pipeline<br/>[abliterate.py]"]
  node_informed_pipeline["Informed Pipeline<br/>adaptive pipeline"]
  node_study_runner["Study Runner<br/>experiment runner<br/>[runner.py]"]
  node_study_config["Study Config &amp; Presets<br/>YAML configuration<br/>[config.py]"]
end

subgraph group_model["Model Runtime"]
  node_model_loader["Model Loader<br/>model access<br/>[loader.py]"]
  node_device_runtime["Device Placement<br/>hardware runtime<br/>[device.py]"]
  node_remote_runtime["Remote Execution<br/>SSH/SCP boundary<br/>[remote.py]"]
  node_hf_models[("Hugging Face Hub &amp; Models<br/>external model service")]
end

subgraph group_analysis["Analysis &amp; Intervention"]
  node_analysis_suite["Mechanistic Analysis<br/>pluggable analysis"]
  node_robustness["Defense Robustness<br/>robustness analysis"]
  node_steering["Inference Steering<br/>reversible intervention"]
  node_strategy_registry["Ablation Strategies<br/>strategy registry<br/>[registry.py]"]
end

subgraph group_evaluation["Evaluation &amp; Sharing"]
  node_evaluator["Evaluator &amp; Metrics<br/>benchmark evaluation<br/>[evaluator.py]"]
  node_reporting["Reporting &amp; Tournaments<br/>results comparison<br/>[report.py]"]
  node_community[("Telemetry &amp; Community<br/>data sharing<br/>[telemetry.py]")]
end

node_cli -->|"runs"| node_standard_pipeline
node_gradio -->|"invokes"| node_standard_pipeline
node_study_config -->|"configures"| node_study_runner
node_study_runner -->|"selects"| node_strategy_registry
node_study_runner -->|"executes trials"| node_standard_pipeline
node_standard_pipeline -->|"loads model"| node_model_loader
node_model_loader -->|"places model"| node_device_runtime
node_model_loader -->|"retrieves / exports"| node_hf_models
node_remote_runtime -.->|"runs remotely"| node_standard_pipeline
node_standard_pipeline -->|"derives directions"| node_steering
node_standard_pipeline -->|"evaluates intervention"| node_evaluator
node_informed_pipeline -->|"extends lifecycle"| node_standard_pipeline
node_informed_pipeline -->|"uses decision inputs"| node_analysis_suite
node_informed_pipeline -->|"checks residuals"| node_robustness
node_robustness -.->|"triggers iteration"| node_informed_pipeline
node_strategy_registry -->|"applies weight ablations"| node_standard_pipeline
node_evaluator -->|"produces results"| node_reporting
node_reporting -.->|"publishes aggregates"| node_community
node_standard_pipeline -.->|"emits run metadata"| node_community

click node_cli "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/cli.py"
click node_gradio "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/local_ui.py"
click node_standard_pipeline "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/abliterate.py"
click node_informed_pipeline "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/informed_pipeline.py"
click node_study_runner "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/runner.py"
click node_study_config "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/config.py"
click node_model_loader "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/models/loader.py"
click node_device_runtime "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/device.py"
click node_remote_runtime "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/remote.py"
click node_analysis_suite "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/analysis/activation_probing.py"
click node_robustness "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/analysis/defense_robustness.py"
click node_steering "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/analysis/steering_vectors.py"
click node_strategy_registry "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/strategies/registry.py"
click node_evaluator "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/evaluation/evaluator.py"
click node_reporting "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/reporting/report.py"
click node_community "https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/telemetry.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_gradio toneBlue
class node_standard_pipeline,node_informed_pipeline,node_study_runner,node_study_config toneAmber
class node_model_loader,node_device_runtime,node_remote_runtime,node_hf_models toneMint
class node_analysis_suite,node_robustness,node_steering,node_strategy_registry toneRose
class node_evaluator,node_reporting,node_community toneIndigo
```

## Components

### Interfaces

- [CLI](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/cli.py): Python entrypoint · `obliteratus/cli.py`
- [Local Gradio UI](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/local_ui.py): UI · `obliteratus/local_ui.py`

### Pipelines & Studies

- [Abliteration Pipeline](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/abliterate.py): pipeline · Runs collection, direction extraction, projection, evaluation, and persistence. · `obliteratus/abliterate.py`
- [Informed Pipeline](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/informed_pipeline.py): adaptive pipeline · Uses analysis and robustness feedback to guide iterative intervention. · `obliteratus/informed_pipeline.py`
- [Study Runner](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/runner.py): experiment runner · `obliteratus/runner.py`
- [Study Config & Presets](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/config.py): YAML configuration · `obliteratus/config.py`

### Model Runtime

- [Model Loader](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/models/loader.py): model access · Loads Hugging Face models and tokenizers with dtype and quantization choices. · `obliteratus/models/loader.py`
- [Device Placement](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/device.py): hardware runtime · Controls device maps and multi-GPU placement. · `obliteratus/device.py`
- [Remote Execution](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/remote.py): SSH/SCP boundary · Provisions remote runs and synchronizes outputs. · `obliteratus/remote.py`
- **Hugging Face Hub & Models**: external model service

### Analysis & Intervention

- [Mechanistic Analysis](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/analysis/activation_probing.py): pluggable analysis · Measures activations, geometry, probes, causal effects, and cross-layer alignment. · `obliteratus/analysis/activation_probing.py`
- [Defense Robustness](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/analysis/defense_robustness.py): robustness analysis · Detects residual refusal behavior after intervention. · `obliteratus/analysis/defense_robustness.py`
- [Inference Steering](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/analysis/steering_vectors.py): reversible intervention · `obliteratus/analysis/steering_vectors.py`
- [Ablation Strategies](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/strategies/registry.py): strategy registry · Registers configurable layer, head, FFN, and embedding ablations. · `obliteratus/strategies/registry.py`

### Evaluation & Sharing

- [Evaluator & Metrics](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/evaluation/evaluator.py): benchmark evaluation · Measures refusal and capability preservation metrics. · `obliteratus/evaluation/evaluator.py`
- [Reporting & Tournaments](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/reporting/report.py): results comparison · Renders results and coordinates sweeps and comparisons. · `obliteratus/reporting/report.py`
- [Telemetry & Community](https://github.com/elder-plinius/obliteratus/blob/main/obliteratus/telemetry.py): data sharing · Shares aggregate run metadata and results outside core execution. · `obliteratus/telemetry.py`

## Connections

- CLI → Abliteration Pipeline: runs
- Local Gradio UI → Abliteration Pipeline: invokes
- Study Config & Presets → Study Runner: configures
- Study Runner → Ablation Strategies: selects
- Study Runner → Abliteration Pipeline: executes trials
- Abliteration Pipeline → Model Loader: loads model
- Model Loader → Device Placement: places model
- Model Loader → Hugging Face Hub & Models: retrieves / exports
- Remote Execution → Abliteration Pipeline: runs remotely
- Abliteration Pipeline → Inference Steering: derives directions
- Abliteration Pipeline → Evaluator & Metrics: evaluates intervention
- Informed Pipeline → Abliteration Pipeline: extends lifecycle
- Informed Pipeline → Mechanistic Analysis: uses decision inputs
- Informed Pipeline → Defense Robustness: checks residuals
- Defense Robustness → Informed Pipeline: triggers iteration
- Ablation Strategies → Abliteration Pipeline: applies weight ablations
- Evaluator & Metrics → Reporting & Tournaments: produces results
- Reporting & Tournaments → Telemetry & Community: publishes aggregates
- Abliteration Pipeline → Telemetry & Community: emits run metadata