> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/elder-plinius/OBLITERATUS/llms.txt
> Use this file to discover all available pages before exploring further.

# Analysis-Informed Pipeline

> The ANALYZE stage runs four analysis modules during obliteration to auto-configure every parameter for surgical precision.

The `informed` method uses `InformedAbliterationPipeline` — a subclass of `AbliterationPipeline` that inserts a new **ANALYZE** stage between PROBE and DISTILL. Four analysis modules run during ANALYZE and their outputs automatically configure every downstream decision: how many directions to extract, which extraction method, how aggressive the regularization should be, which layers to target, and how many refinement passes to run.

This is the key innovation: instead of running analysis as a post-hoc investigation, OBLITERATUS closes the loop — analysis *informs* the obliteration in real time.

## The extended 7-stage pipeline

```
SUMMON  →  load model + tokenizer
PROBE   →  collect activations on harmful vs harmless prompt pairs
ANALYZE →  run 4 analysis modules, derive configuration   ← NEW
DISTILL →  extract refusal directions with analysis-tuned params
EXCISE  →  project out refusal with analysis-guided precision
VERIFY  →  perplexity + coherence + Ouroboros compensation
REBIRTH →  save model with comprehensive analysis metadata
```

Compare with the standard 6-stage pipeline used by all other methods (`SUMMON → PROBE → DISTILL → EXCISE → VERIFY → REBIRTH`).

## The 4 analysis modules in ANALYZE

### 1. Alignment Imprint Detection

**Class**: `AlignmentImprintDetector`\
**What it detects**: Whether the model was aligned via DPO, RLHF, CAI, or SFT — inferred purely from the geometry of the refusal subspace (Gini coefficient, effective rank, cross-layer smoothness, tail-layer bias).

**What it configures**: Regularization strength and projection aggressiveness

| Detected method | Configured regularization | Rationale                                                                            |
| --------------- | ------------------------- | ------------------------------------------------------------------------------------ |
| `dpo`           | 0.0                       | DPO creates concentrated refusal; aggressive removal is safe                         |
| `rlhf`          | 0.15                      | RLHF creates distributed refusal; moderate regularization prevents capability damage |
| `cai`           | 0.20                      | CAI creates recursive, high-dimensional refusal; moderate regularization required    |
| `sft`           | 0.05                      | SFT refusal concentrates in late layers; low regularization sufficient               |

If safety-capability entanglement score exceeds 0.5, regularization is increased by an additional 0.15 (capped at 0.5).

### 2. Concept Cone Geometry

**Class**: `ConceptConeAnalyzer`\
**What it detects**: Whether the refusal subspace has a linear or polyhedral geometry. A linear model has one shared direction; a polyhedral model has distinct directions for different categories (violence, illegal content, privacy, etc.) that form a cone rather than a line.

**What it configures**: Number of directions (`n_directions`) and extraction method

| Cone type          | Cone dimensionality | Configured `n_directions` | Configured method                 |
| ------------------ | ------------------- | ------------------------- | --------------------------------- |
| Linear             | ≤ 1                 | 1                         | `diff_means`                      |
| Mildly polyhedral  | 1 – 2               | 1                         | `leace` (optimal concept erasure) |
| Clearly polyhedral | > 2                 | 4 – 8 (= dim × 2)         | `svd` with whitening              |

The analyzer samples layers in the middle-to-late range (⅓ to 85% of layers) and takes a majority vote across them to determine cone type.

### 3. Cross-Layer Alignment

**Class**: `CrossLayerAlignmentAnalyzer` (with `cluster_threshold=0.85`)\
**What it detects**: How the refusal direction evolves across layers, and which layers form coherent clusters (adjacent layers where the direction is stable, cosine similarity > 0.85).

**What it configures**: Layer selection — cluster-aware instead of arbitrary top-k

The standard approach selects the top-k layers by refusal signal strength, which can select multiple layers from the same cluster (redundant). The informed pipeline instead selects one representative per cluster (the strongest layer in each), then optionally adds up to 2 more from each cluster. This produces a more diverse, non-redundant layer set.

Entanglement-gated: layers from `DefenseRobustnessEvaluator.map_entanglement().most_entangled_layers` are excluded if there are sufficient alternative layers available.

### 4. Defense Robustness Assessment

**Class**: `DefenseRobustnessEvaluator`\
**What it detects**: Self-repair risk (Ouroboros effect — whether the model will partially restore its refusal directions after removal) and safety-capability entanglement (how much the refusal subspace overlaps with general capability subspaces).

**What it configures**: Number of refinement passes

| Self-repair estimate | Configured refinement passes |
| -------------------- | ---------------------------- |
| > 0.7                | 3                            |
| 0.4 – 0.7            | 2                            |
| \< 0.4               | 1                            |

A high entanglement score also feeds back into regularization (step 1 above) and into the Bayesian optimizer's KL budget during EXCISE.

## Ouroboros compensation in VERIFY

After EXCISE, the VERIFY stage in `InformedAbliterationPipeline` runs `_verify_and_compensate()` instead of the standard `_verify()`. If the measured refusal rate exceeds `ouroboros_threshold` (default 0.5), it triggers additional targeted passes:

1. Re-probe the modified model to find where refusal has re-emerged
2. Re-distill to find the new (rotated) refusal directions
3. Re-excise at the newly identified strong layers
4. Re-verify
5. Repeat up to `max_ouroboros_passes` (default 3) times

Each pass is KL-gated: if KL divergence exceeds `kl_budget * 2.0`, or if KL is rising by more than 50% while refusal rate is still above 30%, the loop stops to prevent model damage.

The number of additional passes taken is recorded in `report.ouroboros_passes`.

## Python API

```python theme={null}
from obliteratus.informed_pipeline import InformedAbliterationPipeline

pipeline = InformedAbliterationPipeline(
    model_name="meta-llama/Llama-3.1-8B-Instruct",
    output_dir="abliterated_informed",
    # Analysis module flags (all enabled by default)
    run_cone_analysis=True,
    run_alignment_detection=True,
    run_cross_layer_analysis=True,
    run_sparse_analysis=True,
    run_defense_analysis=True,
    # Ouroboros compensation
    ouroboros_threshold=0.5,   # refusal rate threshold to trigger extra passes
    max_ouroboros_passes=3,
    # Entanglement gating
    entanglement_gate=0.8,
    # Sparse surgery
    sparse_surgery_threshold=0.5,
)

output_path, report = pipeline.run_informed()
```

### `InformedAbliterationPipeline` constructor parameters

| Parameter                  | Type    | Default                  | Description                                                        |
| -------------------------- | ------- | ------------------------ | ------------------------------------------------------------------ |
| `model_name`               | `str`   | required                 | HuggingFace model name or local path                               |
| `output_dir`               | `str`   | `"abliterated_informed"` | Directory for saved model                                          |
| `device`                   | `str`   | `"auto"`                 | Device selection                                                   |
| `dtype`                    | `str`   | `"float16"`              | Model dtype                                                        |
| `trust_remote_code`        | `bool`  | `True`                   | Trust remote code for custom architectures                         |
| `run_cone_analysis`        | `bool`  | `True`                   | Run Concept Cone Geometry analysis                                 |
| `run_alignment_detection`  | `bool`  | `True`                   | Run Alignment Imprint Detection                                    |
| `run_cross_layer_analysis` | `bool`  | `True`                   | Run Cross-Layer Alignment analysis                                 |
| `run_sparse_analysis`      | `bool`  | `True`                   | Run Refusal Sparsity Index analysis                                |
| `run_defense_analysis`     | `bool`  | `True`                   | Run Defense Robustness assessment                                  |
| `ouroboros_threshold`      | `float` | `0.5`                    | Refusal rate that triggers Ouroboros compensation                  |
| `max_ouroboros_passes`     | `int`   | `3`                      | Maximum additional refinement passes                               |
| `entanglement_gate`        | `float` | `0.8`                    | Entanglement score above which layers are skipped                  |
| `sparse_surgery_threshold` | `float` | `0.5`                    | RSI above which sparse surgery is used instead of dense projection |

### `InformedPipelineReport` fields

`pipeline.run_informed()` returns `(output_path, report)` where `report` is an `InformedPipelineReport`:

```python theme={null}
output_path, report = pipeline.run_informed()

# Alignment imprint
print(report.insights.detected_alignment_method)   # 'dpo' | 'rlhf' | 'cai' | 'sft' | 'unknown'
print(report.insights.alignment_confidence)        # 0.0 – 1.0
print(report.insights.alignment_probabilities)     # {'dpo': 0.72, 'rlhf': 0.18, ...}

# Concept cone
print(report.insights.cone_is_polyhedral)          # True | False
print(report.insights.cone_dimensionality)         # float, e.g. 2.3
print(report.insights.mean_pairwise_cosine)        # float, e.g. 0.87

# Cross-layer structure
print(report.insights.direction_clusters)          # [[3,4,5], [12,13,14,15], ...]
print(report.insights.cluster_count)               # int
print(report.insights.direction_persistence)       # float 0–1
print(report.insights.cluster_representative_layers)  # [5, 14, ...]

# Defense robustness
print(report.insights.estimated_robustness)        # 'low' | 'medium' | 'high'
print(report.insights.self_repair_estimate)        # float 0–1
print(report.insights.entanglement_score)          # float 0–1
print(report.insights.entangled_layers)            # [layer_idx, ...]
print(report.insights.clean_layers)                # [layer_idx, ...]

# Derived configuration (what the analysis actually configured)
print(report.insights.recommended_n_directions)       # int
print(report.insights.recommended_direction_method)   # 'diff_means' | 'svd' | 'leace'
print(report.insights.recommended_regularization)     # float
print(report.insights.recommended_refinement_passes)  # int
print(report.insights.recommended_layers)             # [layer_idx, ...]
print(report.insights.skip_layers)                    # [layer_idx, ...] — entanglement-gated

# Pipeline stats
print(report.ouroboros_passes)       # int — extra passes triggered by Ouroboros
print(report.final_refusal_rate)     # float — refusal rate after all passes
print(report.analysis_duration)      # float — seconds spent in ANALYZE stage
print(report.total_duration)         # float — total pipeline seconds
```

### Human-readable report

```python theme={null}
from obliteratus.informed_pipeline import InformedAbliterationPipeline

print(InformedAbliterationPipeline.format_insights(report.insights))
# Analysis-Informed Pipeline — Insights Report
# ==================================================
#
# Alignment Imprint:
#   Detected method: DPO
#   Confidence: 72.3%
#     CAI    18.1%
#     DPO    72.3%
#     RLHF    7.4%
#     SFT     2.2%
# ...
```

## CLI usage

```bash theme={null}
# Analysis-informed pipeline
obliteratus obliterate meta-llama/Llama-3.1-8B-Instruct --method informed

# With output dir
obliteratus obliterate meta-llama/Llama-3.1-8B-Instruct \
    --method informed \
    --output-dir ./informed-liberated
```

<Note>
  When using `--method informed` from the CLI, the standard `AbliterationPipeline` is used with the `informed` preset parameters. To get the full analysis-informed feedback loop (ANALYZE stage, Ouroboros compensation, analysis report), use `InformedAbliterationPipeline` from the Python API directly.
</Note>

## What gets saved

The REBIRTH stage in `InformedAbliterationPipeline` saves `abliteration_metadata.json` alongside the model weights, containing:

* All `AnalysisInsights` fields (detected alignment method, cone type, cluster structure, entanglement)
* Derived configuration (actual `n_directions`, `direction_method`, `regularization`, `refinement_passes`, layer sets used and skipped)
* Pipeline stats (analysis duration, total duration, Ouroboros passes, final refusal rate)
* Quality metrics from VERIFY
* References to the papers the techniques are based on