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

# Quickstart

> Get OBLITERATUS running and obliterate your first model in minutes.

## Choose your path

Three ways to get started — pick the one that fits your setup.

<CardGroup cols={3}>
  <Card title="HuggingFace Spaces" icon="rocket" href="/usage/huggingface-spaces">
    Zero install. Runs on ZeroGPU with a free daily quota. Open the Space and click Obliterate.
  </Card>

  <Card title="Google Colab" icon="notebook" href="/usage/colab">
    Free T4 GPU for models up to \~8B parameters. Open the notebook and hit Run All.
  </Card>

  <Card title="Local install" icon="terminal">
    Full control on your own hardware. Follow the steps below.
  </Card>
</CardGroup>

## Local quickstart

<Steps>
  <Step title="Install OBLITERATUS">
    Install from PyPI or directly from the repository.

    <CodeGroup>
      ```bash pip install theme={null}
      pip install obliteratus
      ```

      ```bash editable install (from source) theme={null}
      git clone https://github.com/elder-plinius/OBLITERATUS
      cd OBLITERATUS
      pip install -e .
      ```
    </CodeGroup>

    <Note>
      Python 3.10 or higher is required. See [Installation](/installation) for platform-specific instructions, Docker usage, and hardware requirements.
    </Note>
  </Step>

  <Step title="Obliterate your first model">
    Run the `obliterate` command with a model from HuggingFace Hub. The `advanced` method is the default and the recommended starting point for most models.

    ```bash theme={null}
    obliteratus obliterate meta-llama/Llama-3.1-8B-Instruct --method advanced
    ```

    OBLITERATUS prints a live progress display tracking all six pipeline stages as they run. The obliterated model is saved to `abliterated/meta-llama_Llama-3.1-8B-Instruct/` by default.

    To save to a custom location:

    ```bash theme={null}
    obliteratus obliterate meta-llama/Llama-3.1-8B-Instruct \
        --method advanced \
        --output-dir ./my-liberated-model
    ```

    <Tip>
      Not sure which model to try? Run `obliteratus models` to browse 116 curated targets organized by VRAM requirement, or `obliteratus models --tier small` to filter to 4-8 GB models.
    </Tip>
  </Step>

  <Step title="Understand the six pipeline stages">
    Every obliteration run — regardless of method — passes through six stages:

    | Stage       | What happens                                                                                         |
    | ----------- | ---------------------------------------------------------------------------------------------------- |
    | **SUMMON**  | Load the model and tokenizer from HuggingFace Hub or a local path                                    |
    | **PROBE**   | Collect hidden-state activations on a set of restricted and unrestricted prompts                     |
    | **DISTILL** | Extract refusal directions from the activation contrast via SVD decomposition                        |
    | **EXCISE**  | Project the refusal subspace out of the model's weight matrices (norm-preserving)                    |
    | **VERIFY**  | Run perplexity, coherence, refusal rate, and KL divergence checks to confirm capabilities are intact |
    | **REBIRTH** | Save the liberated model weights and a `abliteration_metadata.json` file                             |

    The `informed` method adds an **ANALYZE** stage between PROBE and DISTILL that runs four analysis modules and uses their output to auto-configure every downstream decision.

    <Note>
      VERIFY runs automatically after every obliteration. If the Ouroboros effect is detected — meaning the model's guardrails partially reassemble after excision — additional targeted passes fire automatically at the compensating layers.
    </Note>
  </Step>

  <Step title="Use the Python API">
    For programmatic control, import `AbliterationPipeline` directly.

    ```python theme={null}
    from obliteratus.abliterate import AbliterationPipeline

    pipeline = AbliterationPipeline(
        model_name="meta-llama/Llama-3.1-8B-Instruct",
        method="advanced",
        output_dir="abliterated",
    )
    result_path = pipeline.run()
    ```

    After the run, intermediate artifacts are available on the pipeline object:

    ```python theme={null}
    # Refusal directions extracted per layer
    directions = pipeline.refusal_directions    # {layer_idx: tensor}

    # Layers with the strongest refusal signal
    strong_layers = pipeline._strong_layers

    # Post-obliteration evaluation metrics
    metrics = pipeline._quality_metrics
    # Keys: perplexity, coherence, refusal_rate, kl_divergence
    ```

    For analysis-informed obliteration that auto-tunes every parameter:

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

    pipeline = InformedAbliterationPipeline(
        model_name="meta-llama/Llama-3.1-8B-Instruct",
        output_dir="abliterated_informed",
    )
    output_path, report = pipeline.run_informed()

    print(f"Detected alignment: {report.insights.detected_alignment_method}")
    print(f"Auto-configured directions: {report.insights.recommended_n_directions}")
    print(f"Ouroboros passes needed: {report.ouroboros_passes}")
    ```
  </Step>
</Steps>

## What you get after obliteration

The output directory contains:

* **Model weights** — standard HuggingFace `safetensors` format, loadable with `AutoModelForCausalLM.from_pretrained(output_dir)`
* **Tokenizer files** — copied from the source model unchanged
* **`abliteration_metadata.json`** — method used, number of directions extracted, layers modified, VERIFY stage metrics (refusal rate, perplexity, coherence, KL divergence), and timestamps

```python theme={null}
from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("./abliterated/meta-llama_Llama-3.1-8B-Instruct")
tokenizer = AutoTokenizer.from_pretrained("./abliterated/meta-llama_Llama-3.1-8B-Instruct")
```

<Tip>
  Add `--contribute` to your obliterate command to save an anonymous benchmark record to the community dataset. Your run contributes refusal rate, perplexity, and coherence scores — no prompts, outputs, or identifying information.
</Tip>

## Next steps

<CardGroup cols={3}>
  <Card title="CLI reference" icon="terminal" href="/usage/cli">
    All commands, flags, and options for headless and scripted usage.
  </Card>

  <Card title="Python API" icon="code" href="/usage/python-api">
    Full programmatic control over the pipeline and all intermediate artifacts.
  </Card>

  <Card title="Methods overview" icon="flask" href="/methods/overview">
    Compare all seven obliteration methods and choose the right one for your model.
  </Card>
</CardGroup>