TAU-HOME.COM
LOADING

Heretic: Open-Source Training-Free Weight Modification for Language Models

Explore Heretic, an open-source CLI tool that alters LLM behavior—suppressing censorship, sycophancy, and slop—using mathematical weight modification and Optuna

tau · November 15, 2026

#LLM #Abliteration #OpenSource #ModelAlignment #Python

Heretic: Open-Source Training-Free Weight Modification for Language Models

Modifying safety refusals or repetitive sycophancy in large language models historically required complete fine-tuning pipelines backed by massive compute clusters and curated contrastive datasets. Heretic, an open-source tool licensed under GNU AGPLv3 that released v2.1.0 on November 8, 2026, bypasses retraining entirely. It relies on mathematical activation ablation to reshape model behavior directly on consumer-grade hardware.

Heretic CLI terminal execution interface showing language model weight optimization and scoring progress

Image source: p-e-w/heretic (GitHub README)

With over 40,463 GitHub stars and 4,637 forks, Heretic has emerged as a widely watched project in post-training model alignment. Below is a breakdown of its core mechanics, modifier plugins, and end-to-end execution path.

How It Works: ARA and Directional Ablation Without Retraining

Instead of performing gradient descent over token batches, Heretic targets the internal representation space of transformer models.

Language models represent concepts—such as refusal patterns, stylistic filler, or uncritical user agreement—along identifiable directional vectors across hidden layers. Heretic steers model outputs by isolating and mathematically removing these specific vector components from the weight matrices.

  • Arbitrary-Rank Ablation (ARA): The default modifier developed specifically for Heretic. Rather than isolating a single 1D directional vector, ARA identifies and extracts multi-dimensional subspaces associated with unwanted behavior across model layers.
  • Directional Ablation (Abliteration): The established technique that computes a mean difference vector between contrastive prompts (e.g., harmful vs. benign requests) and ablates that direction from weight matrices. Heretic implements layer-wise weight kernels alongside projected abliteration and norm-preserving bi-projection (MPOA).

Heretic couples these modifiers with Optuna's Tree-structured Parzen Estimator (TPE) hyperparameter optimizer. During a processing run, the optimizer searches for parameter configurations that maximize or minimize defined behavioral targets while keeping Kullback-Leibler (KL) divergence low, ensuring the base model retains general reasoning and language quality.

Steering Model Behavior via Preset Configurations

Users do not need to construct internal ablation math manually. Heretic uses modular TOML configuration files to govern the optimization objective. The standard configuration (config.default.toml) suppresses refusal activations, effectively removing safety guardrail interventions.

Alternative behavior adjustments require only pointing to a different config profile:

  • config.noslop.toml: Penalizes common AI filler phrases, boilerplate rhetorical structures, and formulaic clichés.
  • config.nosyco.toml: Reduces sycophancy, steering models away from reflexive agreement with user errors or leading questions.
  • config.nohumor.toml: Suppresses evasive humorous replies and conversational banter.
  • config.emotions.toml: Adjusts the model's emotional alignment and sentiment tone.
  • config.terse.toml: Enforces strict brevity by penalizing unnecessary introductory filler and conversational pleasantries.

Custom metrics integrate through a Scorer plugin interface. Developers can subclass the abstract base class in scorer.py to write custom evaluation logic alongside default scorers like refusal keyword matching (keyword_rate.py) and KL divergence tracking (kl_divergence.py). Plugins can be referenced directly by Python file path in the config without modifying package source code.

Installation and Processing Workflow

Heretic requires a Python 3.10+ environment with PyTorch 2.6+ configured for available acceleration hardware. Installation is handled via PyPI:

pip install -U heretic-llm
heretic Qwen/Qwen3-4B-Instruct-2507

Upon launch, Heretic automatically benchmarks the host system to determine the maximum stable batch size. On a workstation equipped with an Nvidia GeForce RTX 3090, processing the Qwen3-4B-Instruct-2507 base model under default refusal suppression settings takes approximately 30 to 40 minutes.

For hardware configurations constrained by VRAM capacity, Heretic integrates on-the-fly 4-bit model quantization via bitsandbytes (quantization = "bnb_4bit"). This reduces memory overhead to standard 4-bit inference requirements, though users should evaluate outputs for minor accuracy degradation.

Once optimization completes, the CLI offers options to export weights locally, publish the modified artifact directly to the Hugging Face Hub, launch an interactive chat shell for immediate inspection, or run automated benchmark evaluations across MMLU and GSM8K.

Deterministic Reproducibility via 9KB Manifests

Because PyTorch operations can vary across differing GPU architectures, driver versions, and library revisions, Heretic includes an automated reproducibility protocol. When uploading an ablated model to Hugging Face, users can generate a lightweight reproduce/ directory containing execution parameters and a 9KB machine-readable reproduce.json manifest.

Anyone working in an identical hardware and software environment can reproduce the exact byte-for-byte model output using the reproduction flag:

heretic --reproduce path/to/reproduce.json

Key operational constraints remain: configuration files written for Heretic 1.x are incompatible with 2.x releases and must be updated according to docs/migration_v1_to_v2.md. Additionally, while the configuration setting name modifiers is plural, Heretic currently supports selecting only one modifier (ARA or Directional Ablation) per optimization execution.

For teams and independent researchers seeking to audit, de-censor, or stylistically align local foundation models without multi-GPU training budgets, Heretic offers a structured, mathematically driven alternative.

Sources

Impact-Site-Verification: 9b3ebd10-6c45-44cf-a014-5b8c19b7b285