# mherick/heretic architecture

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

- Interactive diagram: https://gitdiagram.com/mherick/heretic
- Repository: https://github.com/mherick/heretic
- Video tour (about a minute): https://gitdiagram.com/mherick/heretic/video

## Overview

Heretic is a command-line tool that automatically decensors transformer models by measuring harmful and harmless prompt behavior, optimizing abliteration parameters against refusal and KL-divergence scores, and applying the selected transformation. The main workflow is initiated and coordinated in `main.py`; `model.py` handles model operations, while the evaluator and scorer plugins provide optimization objectives. Results can be saved, uploaded, chatted with, or benchmarked. The README also documents residual-analysis research features. Some subsystem wiring is inferred only from documented capabilities because the main entry-point excerpt is incomplete.

Main entry points: [`src/heretic/main.py`](https://github.com/mherick/heretic/blob/master/src/heretic/main.py) (CLI workflow), [`src/heretic/plugin.py`](https://github.com/mherick/heretic/blob/master/src/heretic/plugin.py) (Plugin runtime), [`src/heretic/evaluator.py`](https://github.com/mherick/heretic/blob/master/src/heretic/evaluator.py) (Scorer evaluator), [`src/heretic/scorers/keyword_rate.py`](https://github.com/mherick/heretic/blob/master/src/heretic/scorers/keyword_rate.py) (Keyword refusal score)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run orchestration"]
  node_main["CLI workflow<br/>[main.py]"]
  node_config["Settings<br/>[config.py]"]
  node_system["Hardware detection<br/>[system.py]"]
  node_progress["Progress display<br/>[progress.py]"]
end

subgraph group_modeling["Model processing"]
  node_model["Transformer model<br/>[model.py]"]
  node_hfmodels["Hugging Face models"]
end

subgraph group_scoring["Evaluation and optimization"]
  node_optimizer["TPE optimizer<br/>[main.py]"]
  node_evaluator["Scorer evaluator<br/>[evaluator.py]"]
  node_plugin["Plugin runtime<br/>[plugin.py]"]
  node_scorerbase["Scorer interface<br/>[scorer.py]"]
  node_keyword["Keyword refusal score<br/>[keyword_rate.py]"]
  node_kl["KL score<br/>[kl_divergence.py]"]
  node_datasets["Prompt datasets"]
end

subgraph group_outputs["Results and research"]
  node_analyzer["Residual analysis<br/>[analyzer.py]"]
  node_reproduce["Reproduction checks<br/>[reproduce.py]"]
  node_output["Model output actions<br/>[main.py]"]
  node_hub["Hugging Face Hub"]
end

node_user(("CLI user"))

node_user -->|"runs"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"detects hardware"| node_system
node_main -->|"reports progress"| node_progress
node_main -->|"orchestrates"| node_model
node_model -->|"loads model"| node_hfmodels
node_main -->|"optimizes parameters"| node_optimizer
node_optimizer -->|"requests scores"| node_evaluator
node_evaluator -->|"loads plugins"| node_plugin
node_evaluator -->|"runs scorers"| node_scorerbase
node_plugin -->|"provides context"| node_keyword
node_plugin -->|"provides context"| node_kl
node_keyword -->|"loads prompts"| node_datasets
node_kl -->|"loads prompts"| node_datasets
node_keyword -->|"gets responses"| node_plugin
node_kl -->|"gets logits"| node_plugin
node_plugin -->|"accesses inference"| node_model
node_main -.->|"analyzes residuals"| node_analyzer
node_main -->|"checks reproduction"| node_reproduce
node_main -->|"offers result actions"| node_output
node_output -.->|"uploads model"| node_hub
node_reproduce -->|"reads model metadata"| node_hub

click node_main "https://github.com/mherick/heretic/blob/master/src/heretic/main.py"
click node_config "https://github.com/mherick/heretic/blob/master/src/heretic/config.py"
click node_system "https://github.com/mherick/heretic/blob/master/src/heretic/system.py"
click node_progress "https://github.com/mherick/heretic/blob/master/src/heretic/progress.py"
click node_model "https://github.com/mherick/heretic/blob/master/src/heretic/model.py"
click node_optimizer "https://github.com/mherick/heretic/blob/master/src/heretic/main.py"
click node_evaluator "https://github.com/mherick/heretic/blob/master/src/heretic/evaluator.py"
click node_plugin "https://github.com/mherick/heretic/blob/master/src/heretic/plugin.py"
click node_scorerbase "https://github.com/mherick/heretic/blob/master/src/heretic/scorer.py"
click node_keyword "https://github.com/mherick/heretic/blob/master/src/heretic/scorers/keyword_rate.py"
click node_kl "https://github.com/mherick/heretic/blob/master/src/heretic/scorers/kl_divergence.py"
click node_analyzer "https://github.com/mherick/heretic/blob/master/src/heretic/analyzer.py"
click node_reproduce "https://github.com/mherick/heretic/blob/master/src/heretic/reproduce.py"
click node_output "https://github.com/mherick/heretic/blob/master/src/heretic/main.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_main,node_config,node_system,node_progress,node_user toneBlue
class node_model,node_hfmodels toneAmber
class node_optimizer,node_evaluator,node_plugin,node_scorerbase,node_keyword,node_kl,node_datasets toneMint
class node_analyzer,node_reproduce,node_output,node_hub toneRose
```

## Components

### Run orchestration

- [CLI workflow](https://github.com/mherick/heretic/blob/master/src/heretic/main.py): `src/heretic/main.py`
- [Settings](https://github.com/mherick/heretic/blob/master/src/heretic/config.py): `src/heretic/config.py`
- [Hardware detection](https://github.com/mherick/heretic/blob/master/src/heretic/system.py): `src/heretic/system.py`
- [Progress display](https://github.com/mherick/heretic/blob/master/src/heretic/progress.py): `src/heretic/progress.py`

### Model processing

- [Transformer model](https://github.com/mherick/heretic/blob/master/src/heretic/model.py): `src/heretic/model.py`
- **Hugging Face models**

### Evaluation and optimization

- [TPE optimizer](https://github.com/mherick/heretic/blob/master/src/heretic/main.py): `src/heretic/main.py`
- [Scorer evaluator](https://github.com/mherick/heretic/blob/master/src/heretic/evaluator.py): `src/heretic/evaluator.py`
- [Plugin runtime](https://github.com/mherick/heretic/blob/master/src/heretic/plugin.py): `src/heretic/plugin.py`
- [Scorer interface](https://github.com/mherick/heretic/blob/master/src/heretic/scorer.py): `src/heretic/scorer.py`
- [Keyword refusal score](https://github.com/mherick/heretic/blob/master/src/heretic/scorers/keyword_rate.py): `src/heretic/scorers/keyword_rate.py`
- [KL score](https://github.com/mherick/heretic/blob/master/src/heretic/scorers/kl_divergence.py): `src/heretic/scorers/kl_divergence.py`
- **Prompt datasets**

### Results and research

- [Residual analysis](https://github.com/mherick/heretic/blob/master/src/heretic/analyzer.py): `src/heretic/analyzer.py`
- [Reproduction checks](https://github.com/mherick/heretic/blob/master/src/heretic/reproduce.py): `src/heretic/reproduce.py`
- [Model output actions](https://github.com/mherick/heretic/blob/master/src/heretic/main.py): `src/heretic/main.py`
- **Hugging Face Hub**

### Other components

- **CLI user**

## Connections

- CLI user → CLI workflow: runs
- CLI workflow → Settings: loads settings
- CLI workflow → Hardware detection: detects hardware
- CLI workflow → Progress display: reports progress
- CLI workflow → Transformer model: orchestrates
- Transformer model → Hugging Face models: loads model
- CLI workflow → TPE optimizer: optimizes parameters
- TPE optimizer → Scorer evaluator: requests scores
- Scorer evaluator → Plugin runtime: loads plugins
- Scorer evaluator → Scorer interface: runs scorers
- Plugin runtime → Keyword refusal score: provides context
- Plugin runtime → KL score: provides context
- Keyword refusal score → Prompt datasets: loads prompts
- KL score → Prompt datasets: loads prompts
- Keyword refusal score → Plugin runtime: gets responses
- KL score → Plugin runtime: gets logits
- Plugin runtime → Transformer model: accesses inference
- CLI workflow → Residual analysis: analyzes residuals
- CLI workflow → Reproduction checks: checks reproduction
- CLI workflow → Model output actions: offers result actions
- Model output actions → Hugging Face Hub: uploads model
- Reproduction checks → Hugging Face Hub: reads model metadata