Pinned Heretic configs and lockfiles live in sources/heretic-tools/.
They are immutable reference copies — refresh from upstream, do not hand-edit the pinned files.
| Need | File / doc |
|---|---|
| Upstream default config | sources/heretic-tools/config.default.toml |
| 8 GB GPU profile | sources/heretic-tools/config.low-vram.toml |
| 12–24 GB agent profile | sources/heretic-tools/config.production.toml |
| Thinking / CoT models | sources/heretic-tools/config.thinking-model.toml |
| Factory bench domain | sources/heretic-tools/config.factory-qa.toml |
| Slop / filler reduction | sources/heretic-tools/config.noslop.toml |
| Humor / tone reduction | sources/heretic-tools/config.nohumor.toml |
| Dependency pins | pyproject.toml.reference, uv.lock.reference |
| Sync manifest (sha256) | UPSTREAM.json |
| Import / refresh guide | sources/heretic-tools/IMPORT.md |
| HF models attempted | heretic-models-registry.md |
Upstream source of truth#
| Artifact | URL |
|---|---|
| Pin | heretic-llm 1.4.0 · git tag v1.4.0 (2026-06-14) |
| Repository | github.com/p-e-w/heretic — fetch tag, never silent master |
| Mirror | codeberg.org/p-e-w/heretic |
| PyPI package | heretic-llm==1.4.0 |
| Live docs | heretic-project.org/tutorial |
| Mintlify (may be stale) | p-e-w-heretic.mintlify.app — generated ~Mar 2026; prefer the live tutorial |
Where to update from: run npm run fetch:heretic (or node scripts/fetch-heretic-tools.mjs).
That script pulls raw files from tag v1.4.0 (not master) and writes sha256 timestamps into UPSTREAM.json. Post-1.4.0 master uses a plugin scorer schema that breaks handbook factory/thinking profiles.
Handbook-only profiles (config.low-vram.toml, config.production.toml) are edited in this repo — not overwritten by fetch.
Upstream optional profiles (config.noslop.toml, config.nohumor.toml) are pinned from the v1.4.0 tag via npm run fetch:heretic.
Optional profiles (style, not refusal)#
| Profile | Use when | Notes |
|---|---|---|
config.noslop.toml | Model outputs purple prose / sycophantic filler | Uses slop-inducing vs clean prompt pairs; distinct from uncensoring — see comparative-abliteration-benchmarks.md |
config.nohumor.toml | Tone is inappropriately jokey for agent tasks | Smaller prompt set; pair with eval on your deploy corpus |
cp sources/heretic-tools/config.noslop.toml config.toml
heretic ./models/YourModel-InstructQuick use#
# Low VRAM (8–12 GB)
cp sources/heretic-tools/config.low-vram.toml config.toml
heretic ./models/Qwen2.5-1.5B-Instruct
# Upstream defaults unchanged
cp sources/heretic-tools/config.default.toml config.tomlInstall helpers: sources/heretic-tools/install.ps1 (Windows) · install.sh (Linux/macOS).
Refresh everything (docs + pins + HF registry)#
cd abliteration
npm install # once
npx playwright install chromium firefox # once
npm run fetch:all
# or step by step:
npm run fetch:heretic
npm run fetch:docs
npm run fetch:hf-models:firefox # preferred on Windows if Chromium resets
npm run build:heretic-models-docWhy headless Chromium / Firefox?#
Hugging Face blocks bare curl / fetch from CI and some networks (ERR_CONNECTION_RESET).
scripts/fetch-hf-heretic-models.mjs opens the public model list in Playwright, then calls the HF API inside the browser so cookies and TLS fingerprint match a real session.
| Script | Browser | Output |
|---|---|---|
fetch-hf-heretic-models.mjs | Chromium (auto-fallback → Firefox) | data/heretic-models-hf-snapshot.json |
fetch-hf-heretic-models.mjs --firefox | Firefox | same |
fetch-docs.mjs | Chromium / --firefox | sources/fetched/*.txt |
Model registry#
Open-weight models tagged heretic or abliterated on Hugging Face:
- Machine-readable:
data/heretic-models-registry.jsonl - Human table: heretic-models-registry.md
- Handbook seeds:
data/heretic-models-registry.seed.jsonl
Browse live: huggingface.co/models?other=heretic
Related#
- abliteration-tooling.md — full tooling catalog
- ../../instructions/heretic-workflow.md — run Heretic end-to-end
- ../../instructions/low-vram-abliteration.md — 8 GB path