hypernix 0.72.7

End-to-end toolkit for training ai models on modern or old devices, originaly for converting hypernix.1 into gguf, now for all around training

What's fixed in this update

The first section below covers the 0.72.6 line (published as 0.72.5.post14 to post17, 0.72.6.rc1 to rc3, 0.72.6, and the patches 0.72.6.post1 onward), and the one after it covers 0.72.5. wiki/Changelog.md is the canonical per-release history, and wiki/Roadmap.md says what is next.

Table of contents

• What's fixed in this update
• What's new: 0.72.6 — daily keys, conceal, and a quicker waiter
• What's new: 0.72.5 — drafts, bundles, accounts, and a car
• What's new: 0.72.3.post2 — sub-bit models you can actually run
• What's new: 0.72.3 — T1 v1.0.2026.8.1.1
• Package layout
• Module reference
• What's new in v0.70.5
• What's new in v0.70.4
• Install
• Quickstart
• Python API tour
• CLI reference
• Supported model families
• Examples
• Wiki / deep dives
• How the GGUF pipeline works
• Platform notes
• CI autofix
• Build / release
• Usage & Documentation
• License

Cross-platform: Linux, macOS, Windows. hyperNix-pip requires Python 3.12 or newer and officially supports Python 3.12, 3.13, 3.14, and 3.15.

Python 3.15 modernization

0.72.7 moves the floor to 3.12 and adds 3.15, using four of its features where they measurably help and nowhere they would break 3.12–3.14: PEP 810 lazy imports (__lazy_modules__), PEP 798 unpacking in comprehensions (behind hypernix._compat), PEP 799's profiling package (hypernix._profiling) and PEP 831 frame pointers in native builds. The dependency audit, benchmarks and the tested matrix are on the Python 3.12–3.15 wiki page. On 3.15, PyTorch has no wheel yet; everything that does not need torch runs.

What's new: 0.72.6 — daily keys, conceal, and a quicker waiter

v2.1 keys change every day. gkey create -v v2.1 mints a T2C_ key and a T2CK_ kit. The client keeps the kit and sends only that day's key, sealed for the server's RSA key and again under a per-device daily key. The server accepts the day either side and nothing else, and binds each device to one key. The sealing is Rotorvault (hypernix.security.rotorvault): Blowfish, Twofish, an Enigma-style rotor stage wired by xoshiro256++, AES-256-GCM, inversion and base64url. Its security comes from the AES-GCM stage, and the module says so. T1 API → v2.1 keys.

gkey create -v v2.1 --level 4          # T2C_…-4, and the T2CK_ kit that makes it
waiter serv -AEK "T2_…" -I https://myserver.ts.net   # seal an existing key as v2.1

Conceal mode. waiter serv -c (a key at access level 3 or higher) asks the server to keep less about you. Your address is kept only as a /24 or /48, except on security records. What you made more than 36 hours ago (messages, files, finished jobs, ordinary audit records) is deleted. Memories, preferences and usage counts stay. It limits what the T1 server keeps, not what the network or a proxy in front of it records. T1 API → Conceal mode.

waiter serv letters group. waiter serv -ArEK <key> -I <ip> sets up, refreshes, seals and checks in one go. -b works out bare strings (waiter serv -Ab T1_… https://host 8000) and refuses to guess between blocking and allowing a range. There are new letters too:

Waiter TUI → serv flags.

tvtop-max: the machine, and the run on it. tvtop-pro on OpenTUI, with ten panels, each toggled by its number key. Besides CPU, memory, GPU and training progress, it shows:

• which HyperNix modules and libraries the training script uses, with versions and deprecations;
• the model architecture it builds;
• its Pressure Cooker and arguments;
• the log;
• a warnings panel covering the script and the log.

It finds the busiest Python run, its script and its log by itself, and it reads the script without running it. tvtop-max -s lays it out for a phone. TvTopMax.

The T1 server in the 0.72.6 patches. The T1 contract is still v1.1.26.9.0.0; these add to it.

• HyperLink on the web. The server hosts a site that works like the app, at http://127.0.0.1:37965 and on its Tailscale address, and since post3 also at / on the API's own port. Never on the LAN. T1 API.
• hypernix-t1 upgrade upgrades HyperNix in the Python the server actually runs on, its private venv, and restarts it; status and start warn when that has fallen behind. If an upgrade seemed to do nothing, hypernix-t1 version shows why.
• Model sync. T1_MODEL_SYNC=1 mirrors ~/.hypernix/models into the server's own ~/.hypernix/t1api/models, one symlink per file, and serves from it; hypernix-sync does it by hand. T1 API.
• Brewer models run in llama.cpp. brew export --format gguf wrote a file no llama.cpp could open; it now writes a real GGUF (as llama), and hnx brew gguf <folder> converts HyperNix.3-mini or anything brewed. The runner serves brewed models through llama.cpp when it has a build. Training guide.
• Safer by default: checkpoints never unpickled, MCP errors that keep their details on the server, key files confined to the key store. The security checklist now covers every opt-in feature.

Also in 0.72.6:

• HyperLink's default system prompt. When a reply comes from HyperNix's own runner (hyperchat), the model is told where it runs, that it is read on a phone, and not to invent tool results. Anything the person wrote comes after it and wins. T1 API.
• Siri can name chats and models. "Load Gemma 4 in HyperLink" and "Read Groceries in HyperLink" work, because the app now has App Intents entities.
• hnx-t1 is the short name for hypernix-t1.
• hyped-pro finds your T1 server. It looks through waiter's saved server and hypernix-t1's .env before giving up. If nothing answers, it says where the address came from and what to run.
• Earlier 0.72.6 batches: elements (magnesium, carbon), error codes, tool calling for local models, HyperLink on-device models, and hyped-pro on OpenTUI with git and a file editor. See the Changelog.

What's new: 0.72.5 — drafts, bundles, accounts, and a car

Speculative decoding, in both shapes. hyprslug produced a quantised model and dflash2 could attach a draft somebody else had made. Now it makes the draft:

dflash2 attach model.gguf -o model+draft.gguf --quant q4_m   # embedded, one file
dflash1        model.gguf -o draft.gguf       --quant int8   # for --model-draft

dflash2 writes the draft into the base GGUF under a dflash2. prefix, which is where the speed-up is: one file, one download, and a runtime that has never heard of Dflash2 reads the base model straight through. dflash1 writes it as its own file for llama-cli --model-draft, renumbering the kept blocks from zero and rewriting <arch>.block_count to match — a draft that claims 32 blocks and ships 6 loads, and then reads past the end of its own tensor table. It refuses a base with no tokenizer rather than writing a draft nothing can sample from.

Both take nine targets: q8, int8, fp16, bf16, fp32, IQ0.5, Q6_K, Q4_M, int2 — and anything else hyprslug writes, because they plan through it rather than keeping their own list. A draft at a given tier is the same packing as a model at it.

Several quantisations in one GGUF.

hnx-bundle build model.gguf q8,q4_m,iq0.5 -o all.gguf
hnx-bundle list all.gguf
hnx-bundle extract all.gguf q4_m -o just-q4m.gguf

Variants live under hnxq.<slug>., and the default one keeps the ordinary tensor names — a stock llama.cpp opens the file and runs it with nothing unusual happening. A bundle is roughly its variants added together: what is stored once is the tensors every variant left untouched byte for byte, which for most tiers is the 1-D norms rather than the bulk. The point is not compression — it is one download instead of five, one page cache instead of five, and switching tiers on a served model without fetching anything.

Five new quant targets. INT8 and INT2 join the fixed-codebook family; FP32 / FP16 / BF16 are element widths and take their own path. BF16 rounds to nearest even. FP16 saturates an overflow to 65504 only when the input was finite, so an infinity stays an infinity instead of quietly becoming a large number that looks like data.

INT2 was expected to lose to FP2 and does not — 0.384 relRMS against 0.397 over twelve seeds, because ~40% of a weight tensor sits near zero and INT2 spends a codeword there. Measurement in LowBit.

tvtoppro gets an intro, modules, and a watchdog. tvtop-older's animated "decoding" startup text and the spinner, in tvtoppro's presentation; a module system, so a new stat is a file that registers itself rather than a patch to the renderer; and a stall detector — train.log untouched for over a week means the run being watched is not the run that is happening, so it finds the busiest Python process on the machine and reads its logs and progress instead.

tvtoppro --find-run          # go looking, rather than waiting on a dead log

cctvtop's Remote Desktop panel works. It called a session live whenever something held the port. The probe completes an RFB handshake now, so a stale listener, a tunnel with nothing behind it and a real desktop are three different answers — and when there is no session it says which of four reasons applies rather than "unavailable".

noodle runs inside hyped-pro. /noodle in the TUI. It adopts vendor keys already stored in the HyperNix config, with the environment always winning over the stored copy, so a session that works in hyped is not configured twice.

The hypernix CLI says what was wrong. An unknown subcommand used to print usage and exit 0. It now goes to stderr, exits 2, and suggests the nearest real command:

$ hypernix quantise
hypernix: unknown command 'quantise'

  You want:  hypernix quantize

  hypernix --help   every subcommand

T1 v1.0.26.9.2.3 — an account without already having a key. Sign-up and browser sign-in, served four ways: from localhost, over Tailscale, from the operator's own site, or from a prebuilt Cloudflare site hosted by the API host.

t1-accounts create mason --admin     # password prompted, never an argument
t1-accounts modes                    # what the four are, and what each needs

T1_ACCOUNTS_ENABLED=1 T1_ACCOUNTS_MODE=tailscale hypernix-t1 start

scrypt for passwords, constant-time comparison, CSRF on every form, SameSite cookies, lockout after repeated failures, and Secure coupled to whether the connection is actually TLS. A keyless caller never gets administrator rights, in any of the four modes.

Two security fixes. The config file holding API keys was world-readable; it is now written 0600 into a 0700 directory through a temporary file and os.replace, and an existing file is tightened on load. And key authentication compared key strings, in a loop whose position depended on the prefix — a timing oracle for the stored keys. Keys are indexed by digest and compared with hmac.compare_digest; the measured 60x spread across probe keys is flat.

HyperLink in a car, and out loud. The iOS app gets a CarPlay scene, four Siri intents, eight themes, an attachment menu that offers all four ways in, and renaming.

• CarPlay shows a conversation list, CPVoiceControlTemplate dictation and six canned replies — and a keyboard only when the car reports it will allow one, read from CPSessionConfiguration.limitedUserInterfaces on every use and rebuilt from its delegate, because the answer changes while the app is running.
• "Siri, ask HyperLink" (it then asks for your question), "Siri, load Gemma 4 E2B in HyperLink", "Siri, read me the HyperLink chat". None of the four intents opens the app; the point of asking from a car dock is that the phone stays where it is. The question is never part of the first sentence: see Siri.
• Every theme's text clears WCAG AA against its own bubble, the two bubbles are told apart by luminance, and so are "connected" and "failed" — checked in tests/ios/test_hyperlink_ios_wiring.py, which found three that were not.
• A chat can be renamed. The server has taken a title on PATCH /hyperlink/sessions/{id} since HyperLink shipped, and nothing on the phone ever sent one.

CarPlay needs com.apple.developer.carplay-communication, which Apple grants per app on request rather than with a paid account. Everything else builds and runs without it.

Docs. Issue templates for bugs and for feature requests, and Model-Training-Guide — which of these do I use, and in what order. Every API in that guide was run against the package rather than written from memory; six were wrong.

What's new: 0.72.3.post2 — sub-bit models you can actually run

The error this release is about. LM Studio, opening a model this package produced:

llama_model_loader: failed to load model from Qwen3.8-2B-IQ0.9_L.gguf

That error is correct, and no header fixes it: the GGML type id at 200 is how the loader noticed, but the missing dequantisation kernel is why it stopped. So there are three real ways out, and hypernix hyprslug-headers leads with which is which.

hypernix hyprslug-headers install                        # find what needs it
hypernix hyprslug-headers serve model.iq09.gguf          # keep the tier, talk HTTP
hypernix hyprslug-headers wrap  model.iq09.gguf -o ok.gguf   # open anywhere, bigger
hypernix hyprslug-headers stamp model.iq09.gguf          # make it self-describing

serve puts HnxRun behind /v1/chat/completions, so LM Studio and Bionic reach a 0.9-bit model without converting it. wrap re-encodes to a stock type and says, in the report, that the result is a Q2_K copy of a IQ0.9_L model rather than the original — verified against the reference gguf reader. See HyprSlug-Headers.

Five new quant types. IQ0.25_UXL at a quarter of a bit exactly, INT1, FP2, INT4, and Q4M as a spelling of Q4_K_M that used to be rejected. FP2's scale is searched, not fitted to the block peak — the obvious fit scored worse than one bit, and a 2-bit format that loses to a 1-bit format is not a format. Full table and the measurement in LowBit.

tvtoppro — tvtop++'s stats under a btop++ presentation, with themes. Braille graphs, gradient meters, titles in the box border, and btop's own .theme files loading unchanged.

tvtoppro --theme gruvbox-dark
tvtoppro --theme ~/.config/btop/themes/nord.theme

Seven themes built in and exported to examples/tvtoppro/. See TvTopPro.

hypernix-t1 fixes. create --host/--port failed from a checkout (the documented flags reached install-t1.sh, which had never heard of them), and hypernix-t1 start started uvicorn on a different port from the one the installer configured, because the bind address only ever went into start-t1.sh. Both paths agree now.

What's new: 0.72.3 — T1 v1.0.2026.8.1.1

A new server can be set up without knowing anything. It issues itself one admin key on first start, prints it once, and that key works only from the machine that made it and only for three days. That is enough to point waiter at it and mint a real one.

./install-t1.sh                 # interactive setup, or:
hypernix-t1 start               # start / stop / restart / status / logs
hypernix-t1 test                # health, status, and a real end-to-end probe
hypernix-t1 autostart on        # a systemd user service

HyperLink connects. Three separate bugs each produced the same symptom — the app times out and the server log is empty, because nothing ever arrived. The server advertised port 8000 whatever port it was on; iOS blocked tailnet addresses before sending, since Tailscale's 100.64.0.0/10 is not one of the RFC 1918 ranges ATS exempts; and when Tailscale was missing the server said nothing about why. All three fixed, and the app now takes a T2S key as well as a pairing code.

Keys can pay for themselves. A T2P key carries a billing binding — provider references, a spend cap, a currency — so it can be issued to someone who pays for their own usage. No card data reaches the server, and the binding is not in the credential. A server can refuse them outright and point at its own payment page, or require payment on a separate key, so the credential that identifies a caller and the one that spends money have different lifetimes.

gkey mints every format. -v v1|v2|v2short (and, since 0.72.6, v2.1), plus gkey version for what this build can issue.

gkey create -v v2 --level 5            # T2_…-5
gkey create -v v2short                 # T2S_…  for HyperLink
gkey version                           # package, T1 API, key formats

The AI agent asks before it runs anything. Tool calls are parsed out of the model's own reply, so anything that can influence that reply — a file it read, a web result, a page it fetched — could previously execute shell commands with no prompt. Side-effecting tools now require consent; HYPERNIX_TOOL_POLICY=ask|deny|allow, and "ask" with no terminal means deny.

More fits on the same card. hypernix.system.vram — allocator tuning so a long run stops fragmenting, activation checkpointing so sequence length stops costing activation memory, an optimizer that steps during backward so the gradients are never all held at once, and a way to measure whether any of it worked. Nothing is applied for you and nothing changes a default.

hypernix train run ... --gradient-checkpointing --tune-allocator

Releases are gated on a live server. After the tests, two jobs each mint a T2 key, start a real API, chat through a fake model, drive an iPhone simulator, then delete every key they made. Nothing publishes until both pass.

Package layout

Modules are grouped by what they do rather than sitting in one flat directory:

Counts are .py files excluding __init__.py, as of 0.72.5.

Every module keeps its old import path. hypernix.timer and hypernix.timing.timer return the same module object, so nothing that imported a module before the move needs to change:

from hypernix.timer import KitchenTimer          # always worked, still works
from hypernix.timing.timer import KitchenTimer   # where the file actually is
import hypernix; hypernix.timer is hypernix.timing.timer   # True

hypernix.MODULE_CATEGORIES (and its reverse, hypernix.CATEGORY_OF) is the one place the layout is written down — the lazy loader, the alias finder, the hnx wiki browser and the scripts/autofix-* tooling all read it, so moving a module between categories is a one-line change.

Module reference

Click a category below to expand it.

What's new in v0.70.5

Eleven major additions:

• hnx / hypenix Wiki CLI — Auto-generating documentation browser. hnx shows all modules; hnx <module> shows docs; hnx -q <module> streams quick mode; hnx -b opens in browser. Docs regenerate from source docstrings, so they can't drift out of sync with the code.
• hnx vera — Module verification: syntax check, docstring coverage, type annotations, smoke test. hnx vera <file> or hnx vera --all.
• pressure_cooker_v5 — ORCP optimizer family with int8-quantized momentum (~75% smaller than fp32, ~87% smaller total optimizer state than AdamW -- see the efficiency paper), QAT (Q4/Q5/Q6/Q8), Multi-Token Prediction, EMA shadowing, and the ground-up 3D-ORCP PressureCookerV5S variant (v0.70.6).
• mtp — Multi-Token Prediction for 1.5-3x training efficiency. Sequential/independent modes, shared/independent heads, native workshop integration.
• scavenger — HuggingFace dataset discovery with keyword search, storage budgets, quality filtering (likes/downloads/age), and relevance scoring.
• Freezer QAT support — suggest_qat_batch_size(), prepare_for_qat(), per-bit-width VRAM multiplier profiles.
• Workshop native MTP — attach_mtp_head() and compute_mtp_loss() built into WorkshopFramework.
• tvtop++ fixes — Eliminated border flicker (layout built once), added _block_history_bar re-export, implemented small_mode, fixed self-process filtering.
• New wiki pages — Pressure-Cooker-V5, MTP, Scavenger
• Kitchen.md updated — Added scavenger, MTP, and QAT sections

Training Benefits vs Complexity

Key insight: MTP + Speculative Decoding offer the highest benefit-to-cost ratio. Int8-quantized momentum cuts the momentum buffer's own memory by 75% versus fp32, and PressureCookerV5/V5S's factored curvature keeps the rest of the optimizer state small too -- measured optimizer-state memory lands around 12-13% of AdamW's (see the efficiency paper for the exact numbers and methodology). The trade-offs -- including step-time overhead on some hardware -- are real and are covered in the paper rather than summarized as a single percentage here.

What's new in v0.70.4

Seven additions in the 0.70.4 series:

• qa — QAProcessor formats Q&A datasets into causal LM training strings with optional salt/pepper seasoning
• stml — Short Term Memory Loss: STML context manager (segment folding, untrained hard cap) + calculate_vram_context VRAM calculator with CLI
• TurboAbbicus — exponential curriculum regulator with configurable hard cap, sine-wave oscillation (CPU-adjusted, never GPU), and VRAM safeguard
• tvtop++ fixes — layout tree bug (border shifting on refresh), colors matching original tvtop (CPU=green, RAM=magenta, GPU=red), dynamic console resizing, dynamic graph/log widths
• hypernix stml CLI subcommand — VRAM context calculator from the shell
• hypernix train run new flags — --use-abbicus, --use-turbo-abbicus, --use-stml, --untrained-max-context, --segment-length
• CodeOven.train() new kwargs — use_turbo_abbicus, use_stml, untrained_max_context, segment_length

Earlier: v0.70.0

Five new modules + major optimizer rewrites:

• abbicus — Automatic token regulation and curriculum tuning for model sizes 0.5B–72B
• compute_framework — Hardware-agnostic multi-device training with auto DDP/ZeRO wrapping (CUDA/MPS/CPU/TPU)
• pressure_cooker V2 — Quantization-aware training with fp16/bf16/fp64 mixed-precision, QAT hooks for Q8/Q6/Q5.5/Q4M, plus 10 upgrades (mixed-precision autodetect, QAT hooks, gradient-checkpointing integration, adaptive per-layer gradient clipping, EMA weight shadowing, DDP/FSDP-aware distributed training, dynamic loss scaling with overflow backoff, parameter freeze/unfreeze callbacks, an LR finder, and metrics streaming to tvtop)
• pressure_cooker_v3 — ZeRO-1/2 optimizations, FP8 support, QuantDtype enum + QuantConfig dataclass
• workshop — Model frameworks for TTS/ASR/LLM/Vision with pre-built templates, nano-nano collection support, 30+ architectures (LiquidAI LFM2.5, MiniCPM5, Gemma 4, Qwen3.5, Phi-4, DeepSeek-V2.x, and others)
• tvtop — Runs cctvtop (tvtop++ plus hardware metrics and a remote-desktop panel); tvtop-old is tvtop++ and tvtop-older the original. See Dashboards

Install

From PyPI:

pip install "hypernix[llama-cpp]"     # + bundled llama-cpp-python
pip install "hypernix[train]"         # + transformers, accelerate
pip install hypernix                  # core only

Nightly builds, when the maintainers have them switched on, are the rolling nightly prerelease: the branch as of last night, after lint, the full test suite and the live integration jobs, and nothing more. Install the wheel by its URL: pip install https://github.com/trail-b1az3r/HyperNix-pip/releases/download/nightly/<wheel>. hypernix --version then reads something like 0.72.6.post3+nightly.20260930.1a2b3c4.

Setting up the T1 API server specifically? ./install-t1.sh is a guided installer — it asks what kind of deployment this is (bind address, key policy, allowlist, rate limits, cost accounting, models, HyperLink, the waiter manager TUI) and writes a matching configuration, an admin key, and a start script. --dry-run shows what it would do without writing anything. See T1-API.md.

Need a specific torch build? Install torch first; pip will reuse it rather than replace it:

# CUDA 11.8 — old drivers, Pascal GPUs (GTX 1080 et al.)
pip install --index-url https://download.pytorch.org/whl/cu118 torch
pip install hypernix

# CUDA 12.x — modern default
pip install --index-url https://download.pytorch.org/whl/cu124 torch
pip install hypernix

# CPU-only
pip install --index-url https://download.pytorch.org/whl/cpu torch
pip install hypernix

# Old Intel Mac / torch 1.13 — the compat shim takes over.
pip install --index-url https://download.pytorch.org/whl/cpu 'torch==1.13.1'
pip install 'hypernix[legacy-torch]'

hypernix: command not found

The console scripts land in your interpreter's scripts directory, which on a lot of systems isn't on PATH — pip install --user puts them in ~/.local/bin, and Debian/Ubuntu only add that at login if it already existed. HyperNix fixes this itself the first time you run it, printing what it changed. To do it explicitly:

python -m hypernix path            # what would change (writes nothing)
python -m hypernix path --apply    # write the block into your shell profile
python -m hypernix path --undo     # take it back out

It writes one marked, reversible block into the startup file your shell actually reads, and refuses to do anything inside a virtualenv or conda env — that directory belongs to the environment and is only meant to be on PATH while it's activated. Set HYPERNIX_NO_PATH_SETUP=1 to turn the automatic version off entirely.

The main install_requires is torch>=1.13,<3 — 2.7+ is the recommended version (native nn.RMSNorm, fused SDPA), but 1.13+ works via hypernix.torch_compat. See wiki/macOS-legacy.md for the full story.

Sanity-check the environment:

hypernix doctor          # report
hypernix doctor --fix    # install missing runtime deps

Automatic dependency management can be disabled with HYPERNIX_AUTO_INSTALL=0.

Quickstart

Chat with any supported model

hypernix chat --repo-id nix2.5 --message "hello"
hypernix chat --repo-id qwen3.5-4b --message "explain rotary embeddings"
hypernix chat --repo-id gemma-4-e4b --message "write a haiku"

Short names resolve via KNOWN_MODELS; see Supported model families.

Convert a snapshot to GGUF

# Default: fp32 + fp16
hypernix --repo-id ray0rf1re/hyper-nix.1 --output-dir ./out

# Opt in to k-quants (needs llama-quantize)
hypernix --repo-id ray0rf1re/hyper-nix.1 --output-dir ./out \
    --quants fp32 fp16 q8_0 q6_k q4_k_m

Train HyperNix 1.5 (~92.1 M params) on a GTX 1080

python examples/train_hypernix_1_5_gtx1080.py \
    --dataset corpus.txt \
    --tokenizer-source ./hyper-nix-v1 \
    --out-dir ./hypernix-1.5 \
    --steps 2000 --batch-size 1 --context-length 1024

Auto-detects compute capability 6.x, forces fp16 (Pascal has no native bf16), disables TF32 / SDPA / torch.compile, and wraps the training loop in a FlashFreezer so OOMs pause-and-halve rather than crash. See wiki/Pascal.md for the full Pascal playbook.

Build a HyperNix 0.1.5 evaluator

python examples/train_hypernix_0_1_5_evaluator.py --out-dir ./eval

Synthesizes a judge-training corpus with mediocre_fridge, freezes embeddings with old_fridge, trains via oven.train, reloads with the other oven, plots the loss curve with new_fridge. Self-contained smoke test for every subsystem.

Python API tour

import hypernix
from hypernix import freezer, old_oven, old_fridge, mediocre_fridge, new_fridge

# 1) Auto-pick a VRAM strategy.  On a GTX 1080 this returns OldFreezer(fp16);
#    on a 3090 it returns NewFreezer(fp32 / bf16 on Ampere).
fz = freezer.flash_freezer(base=freezer.auto_freezer(), slow=True)

# 2) Preheat an oven from a short name (downloads on first call).
oven = old_oven.preheat(repo_id="nix2.5", device="cuda", dtype="float16")

# 3) Memory hygiene.
old_fridge.freeze(oven.model, patterns=("embed_tokens",))
print(old_fridge.parameter_stats(oven.model))

# 4) Training data.
dataset = mediocre_fridge.synthesize_judge_corpus(n=1024, out_path="judge.txt")

# 5) Train inside a FlashFreezer so OOMs don't blow up the run.
fz.guard(lambda: oven.train(dataset, "./trained", steps=500, batch_size=1))

# 6) Graph.
import pathlib
log = pathlib.Path("./trained/train.log").read_text()
new_fridge.plot_loss_curve(new_fridge.parse_training_log(log), "loss.png")

CLI reference

hypernix --help prints the authoritative list — this is the shape of it. An unknown subcommand exits 2 on stderr and suggests the nearest real one rather than printing usage and claiming success.

hypernix <subcommand> [options]

  all                   download -> convert -> [quantize]   (default)
  download              fetch a HuggingFace snapshot
  convert               produce fp32 / fp16 GGUF from a snapshot
  quantize              run llama-quantize on an fp16 / fp32 GGUF
  verify                read-validate a GGUF and print headers
  info                  package + optional GGUF header summary
  upload                push files to a HuggingFace repo
  doctor                environment diagnostic  (pass --fix to install deps)
  path                  put the console scripts on your PATH  (--apply / --undo)
  fetch-llama-quantize  pre-seed the llama-quantize cache
  train init            create a fresh HyperNix snapshot
  train expand          warm-start a bigger model from a smaller one
  train run             minimal causal-LM training loop
  generate              sample text from a local snapshot
  oven                  code-generation wrapper (preheat + complete / fill)
  chat                  interactive chat REPL against any supported model
  brew                  custom architecture builder and training suite
  fizzle                fuse models and LoRAs                        (fiz)
  fusebox               GPU thermal governor: pace a run, trip on heat
  devices               what accelerators this machine has, and what they do
  wakeup                train a trigger phrase, then listen for it
  websearch             the search backend behind chat and the assistant
  gather                crawl a site into a corpus (robots-aware)
  runtime               use HyperNix's llama.cpp from LM Studio and friends
  hyprslug-headers      self-describing GGUF headers, and the sub-bit server
  stml                  VRAM trained context length calculator

The rest are their own console scripts, because each is a program rather than a step in the pipeline:

train run accepts curriculum / context management flags:

hypernix train run --model-dir ./snap --dataset data.txt --out-dir ./out \
    --use-turbo-abbicus \        # exponential curriculum (--use-abbicus for linear)
    --use-stml \                 # fold long sequences into batch segments
    --untrained-max-context 16384 \
    --segment-length 512

Quant aliases accepted by --quants and hypernix quantize (v0.51.3 ships 49 aliases mapping to 30 distinct quant types — the table below shows the headline subset; hypernix.quant_list_types() returns the full list at runtime, and hypernix.QUANT_CATALOG[name] gives you the full QuantSpec for any one):

Supported model families

Short names (CLI & Python)

Pass any of these to hypernix chat --repo-id, old_oven.preheat, download_model, etc.

The full registry lives in hypernix.KNOWN_MODELS.

ARCH_PRESETS (seeds for new_oven)

new_oven(arch="...", ...) spins a fresh, parametric model in the shape of any of these families:

• hypernix, llama, llama3, llama3.1, llama3.2, llama3.3, llama4
• qwen2, qwen2.5, qwen3, qwen3.5, qwen3.6
• gemma, gemma2, gemma3, gemma4
• mistral, phi3, phi4
• glm4, glm5, glm5.1
• deepseek, deepseek-r1, nemotron, gpt-oss / gptoss
• nix, nix2

Presets are seeds for brand-new parametric models. Loading a pretrained checkpoint for any of these families works without a matching preset because non-HyperNix model_type values route through transformers.AutoModelForCausalLM.

Examples

• examples/quickstart.py — 5-line Python API demo.
• examples/custom_arch.py — arbitrary-size HyperNix.
• examples/upload_to_hub.py — publish to the Hub.
• examples/train_hypernix_0_1_5_evaluator.py — tiny evaluator demo wiring ovens + all three fridges.
• examples/train_hypernix_1_5_gtx1080.py — production-shape 92.1 M model trained on an 8 GB Pascal card.

Wiki / deep dives

Topic-focused reference guides live in the wiki/ directory:

• wiki/Home.md — index
• wiki/Ovens.md — old_oven / new_oven reference
• wiki/Fridges.md — old_fridge / mediocre_fridge / new_fridge
• wiki/Ranges.md — new_range / old_range / industrial_range (labeling rubrics)
• wiki/Freezer.md — VRAM manager (OldFreezer / NewFreezer / FlashFreezer)
• wiki/Alarms.md — smoke alarms (Rads / Gas / Modern / Auto) + CPU / GPU preset tables
• wiki/Kitchen.md — pans / microwave / table / sink / instant pot / coffee maker / pressure cooker / qa
• wiki/Abbicus.md — Abbicus (linear) and TurboAbbicus (exponential + sine oscillation)
• wiki/STML.md — Short Term Memory Loss context manager and VRAM calculator
• wiki/Pascal.md — CUDA 6.1 / GTX 1080 playbook
• wiki/Architectures.md — ARCH_PRESETS and KNOWN_MODELS
• wiki/Training.md — scratch training, expansion, and fine-tuning flows
• wiki/CLI.md — full CLI cheat sheet
• wiki/Quantization.md — GGUF conversion + k-quant pipeline
• wiki/Changelog.md — full per-release version history
• wiki/Pressure-Cooker-V5.md — Pressure Cooker V5 / V5+ / V5S with QAT and MTP
• wiki/MTP.md — Multi-Token Prediction guide
• wiki/Scavenger.md — HuggingFace dataset discovery
• wiki/Model-Training-Guide.md — which of these do I use, and in what order
• wiki/HyprSlug.md — the sub-bit quantiser
• wiki/HyprSlug-Headers.md — self-describing headers, the compat export, the sub-bit server
• wiki/LowBit.md — the fixed-codebook tiers and the measurements behind them
• wiki/Dflash2.md — speculative-decoding drafts
• wiki/TvTopPro.md — the dashboard, its themes and its modules
• wiki/TvTopMax.md — tvtop-max: the run's script, model, optimizer, logs and warnings
• wiki/T1-API.md — the T1 API server
• wiki/HyperLink-Sync.md — the phone app and what it talks to
• wiki/Roadmap.md — what is planned, and what landed

How the GGUF pipeline works

1. huggingface_hub.snapshot_download pulls weights + tokenizer files.
2. The converter loads the state dict, infers dimensions from tensor shapes (so any HyperNix size works), and maps tensor names onto llama.cpp's canonical GGUF layout when a recognizable pattern matches (Llama, GPT-NeoX, GPT-2, nanoGPT). Unknown names round-trip verbatim.
3. llama-quantize consumes the fp16 GGUF to produce each k-quant.

The CLI emits exactly one fp16 intermediate and reuses it for every k-quant in the plan.

Platform notes

• Linux: full support, every distro tested on: (Ubuntu, Debian, Arch.)
• macOS: Metal for inference, Homebrew for llama-quantize. (untested)
• Windows: native support; doctor accepts Windows; llama-quantize auto-downloads Windows binaries; use scoop / chocolatey for system deps. (untested)
• Pascal (GTX 1080 / 1080 Ti / Titan Xp): install torch from the CUDA 11.8 index first (see above). Use OldFreezer or auto_freezer(); pascal_safe_dtype() picks fp16. hypernix.freezer.pascal_mode_hints() returns a dict of recommended settings (batch size, dtype, TF32/SDPA toggles) for the detected card.

CI autofix

Three scripts in scripts/, each owning one failure class, plus a router that reads a CI log and runs the right one:

scripts/autofix                      # reproduce the failure, classify, fix
scripts/autofix --log ci-output.txt  # classify an existing CI log
scripts/autofix-F --dry-run          # timer-test repair, without writing

autofix-F engages only when some but not all of the timing tests fail — the signature of a wall-clock assertion that lost a race, which is the one thing it can fix. It widens the margins in those tests by scaling every time constant in them uniformly, re-runs only what it changed, and commits with an Autofix-Scope: trailer. CI reads that trailer and verifies just those tests instead of re-running the 4-OS x 4-Python matrix. Failures it can't honestly fix — a renamed symbol, a changed signature, a real regression — are reported and left alone.

See scripts/README.md for the full picture.

Build / release

pip install build twine
python -m build
twine check --strict dist/*

Release tags (vX.Y.Z) fire .github/workflows/release.yml which publishes to PyPI via Trusted Publishing and attaches the wheel + sdist + an examples-scripts tarball + SHA256SUMS to a GitHub Release.

Usage & Documentation

Comprehensive performance analysis and training guides available in the following PDFs:

# Reproduce the optimizer benchmarks yourself:
python scripts/benchmark_v5.py              # AdamW vs PressureCookerV5, step time + peak mem
python scripts/benchmark_v5s.py             # AdamW vs V5 vs V5S, step time + peak mem
python scripts/measure_optimizer_memory.py  # exact optimizer-state bytes per parameter tensor

License

HyperNix is dual-licensed — recipients choose one of the two options below (see the full text in LICENSE):

• LLU-0.1 — the HyperNix OpenCode Light Limited Use License, Version 0.1. Source-available, with a same-license requirement for forks and a §12 field-of-use restriction (it does not meet the OSI Open Source Definition because of that restriction). This is the default if you don't make an active choice.
• HOS-1.0 — the HyperNix Open Source License, Version 1.0. An OSI-compliant open-source license with no field-of-use restrictions.

You must pick one license and follow its terms — you can't mix terms from both. Large trained models (29.1B+ parameters) that are shared publicly carry a transparency requirement (disclosing training-data sources or a data composition summary) under either license; see LICENSE §7–8 (LLU-0.1) / the equivalent HOS-1.0 sections for specifics. hypernix is not Apache-2.0, MIT, or any other stock license.

Full detail in the Changelog.