How mherick/heretic works
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: main.py CLI workflow · plugin.py Plugin runtime · evaluator.py Scorer evaluator · keyword_rate.py Keyword refusal score
Components 18
Run orchestration
- CLI workflow
src/heretic/main.py - Settings
src/heretic/config.py - Hardware detection
src/heretic/system.py - Progress display
src/heretic/progress.py
Model processing
- Transformer model
src/heretic/model.py - Hugging Face models
Evaluation and optimization
- TPE optimizer
src/heretic/main.py - Scorer evaluator
src/heretic/evaluator.py - Plugin runtime
src/heretic/plugin.py - Scorer interface
src/heretic/scorer.py - Keyword refusal score
src/heretic/scorers/keyword_rate.py - KL score
src/heretic/scorers/kl_divergence.py - Prompt datasets
Results and research
- Residual analysis
src/heretic/analyzer.py - Reproduction checks
src/heretic/reproduce.py - Model output actions
src/heretic/main.py - Hugging Face Hub
Other components
- CLI user
Connections 22
- 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