Metadata-Version: 2.4
Name: hypernix
Version: 0.71.4.post3
Summary: Download and quantize the HyperNix PyTorch model to GGUF (fp32/fp16/Q8_0/Q6_K/Q4_K_M).
Home-page: https://github.com/minerofthesoal/hypernix-pip
Author: HyperNix contributors
License: LLU-0.1
Project-URL: Homepage, https://minerofthesoal.github.io/HyperNix-pip/
Project-URL: Source, https://github.com/minerofthesoal/hypernix-pip
Project-URL: Issues, https://github.com/minerofthesoal/hypernix-pip/issues
Project-URL: Logo, https://raw.githubusercontent.com/minerofthesoal/hypernix-pip/main/assets/logo.png
Keywords: hypernix,gguf,quantization,llama.cpp,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<3,>=1.13
Requires-Dist: numpy<3,>=1.26
Requires-Dist: safetensors>=0.4.3
Requires-Dist: huggingface-hub>=0.24
Requires-Dist: gguf>=0.10.0
Requires-Dist: tqdm>=4.66
Requires-Dist: rich==14.3.4
Requires-Dist: sentencepiece>=0.2.1
Provides-Extra: llama-cpp
Requires-Dist: llama-cpp-python>=0.2.90; extra == "llama-cpp"
Provides-Extra: train
Requires-Dist: transformers>=4.44; extra == "train"
Requires-Dist: accelerate>=0.33; extra == "train"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Provides-Extra: security
Requires-Dist: cryptography>=42; extra == "security"
Provides-Extra: legacy-torch
Requires-Dist: numpy<2,>=1.21; extra == "legacy-torch"
Requires-Dist: safetensors>=0.3.1; extra == "legacy-torch"
Requires-Dist: huggingface-hub>=0.16; extra == "legacy-torch"
Requires-Dist: tqdm>=4.64; extra == "legacy-torch"
Requires-Dist: sentencepiece>=0.1.99; extra == "legacy-torch"
Provides-Extra: gui-qt
Requires-Dist: PySide6>=6.6; extra == "gui-qt"
Provides-Extra: gui-gtk
Requires-Dist: PyGObject>=3.48; extra == "gui-gtk"
Provides-Extra: gui
Requires-Dist: hypernix[gui-qt]; extra == "gui"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/minerofthesoal/hypernix-pip/2d5eb37/assets/logo.png" alt="hypernix logo" width="240" />
</p>

# hypernix

[![PyPI](https://img.shields.io/pypi/v/hypernix.svg)](https://pypi.org/project/hypernix/)
[![Python](https://img.shields.io/pypi/pyversions/hypernix.svg)](https://pypi.org/project/hypernix/)
[![License](https://img.shields.io/pypi/l/hypernix.svg)](https://github.com/minerofthesoal/hypernix-pip/blob/main/LICENSE)

**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
See changlog.md
## Table of contents

- [What's fixed in this update](#whats-fixed-in-this-update)
- [Module reference](#module-reference)
- [What's new in v0.70.5](#whats-new-in-v0705)
- [What's new in v0.70.4](#whats-new-in-v0704)
- [Install](#install)
- [Quickstart](#quickstart)
- [Python API tour](#python-api-tour)
- [CLI reference](#cli-reference)
- [Supported model families](#supported-model-families)
- [Examples](#examples)
- [Wiki / deep dives](#wiki--deep-dives)
- [How the GGUF pipeline works](#how-the-gguf-pipeline-works)
- [Platform notes](#platform-notes)
- [Build / release](#build--release)
- [Usage & Documentation](#usage--documentation)
- [License](#license)


Cross-platform: Linux, macOS, Windows. Python 3.10 - 3.14.

## Module reference

Click a category below to expand it.

<details>
<summary><strong>Models & Training</strong> &nbsp;(12 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.download` | Pull snapshots from the Hub (short-name resolution, gated repos, offline cache). |
| `hypernix.train` | `HyperNixConfig`, `HyperNixModel`, `init_from_scratch`, `expand_checkpoint`, `train`. Non-HyperNix archs route through `AutoModelForCausalLM`. |
| `hypernix.brewer` | `hyperNix0x-v2` architecture preset family — `Brewer(config).build()` for a from-scratch `BrewerModel`. GPU-oriented presets `33m` / `micro` / `small` / `medium` / `large` (33.6M-3.5B params), plus `cpu-nano` / `cpu-tiny` / `cpu-small` (2.1M/9.2M/26.5M params) sized for CPU-only training and inference. `custom_arch(**kwargs)` for a fully bespoke config. Also available as `hypernix brew new --preset <name>`. |
| `hypernix.instant_pot` | `brew(recipe)` — one-shot end-to-end pipeline. Also available as `hypernix brew recipe.json`. |
| `hypernix.coffee_maker` | 3 tiers (drip / french-press / percolator) + `cold_brew` type for long checkpointed runs. |
| `hypernix.deep_fryer` | 2-tier model-weight perturbation: `LightFry` (regulariser) / `HeavyFry` (severe, for bad-model negatives). In-place, reversible via snapshot. |
| `hypernix.abbicus` | Automatic token regulation and curriculum tuning. **`Abbicus`** (linear) dynamically modifies max sequence length based on model size (0.5B-72B), global step, and dataset type. `TurboAbbicus` (exponential) adds sine-wave oscillation and a hard VRAM safeguard. |
| `hypernix.compute_framework` | Hardware-agnostic multi-device training. Abstracts CUDA, MPS, CPU, TPU backends with automatic DDP/ZeRO wrapping. `ComputeFramework` handles PyTorch DDP initialization, device placement, and gradient sync without manual `torch.distributed` boilerplate. |
| `hypernix.workshop` | Model frameworks and TTS/ASR pipelines. `WorkshopFramework` base class with `FrameworkConfig` for TTS, ASR, LLM, Vision models. Pre-built templates for the ray0rf1re/nano-nano collection plus 30+ third-party architectures. |
| `hypernix.whisk` | Checkpoint averaging — `swa_average` (uniform mean), `ema` (exponential), `geometric_mean`. Accepts state dicts or paths to `.pt` / `.safetensors`. `whisk_to_snapshot` writes the merged weights back out as a loadable HyperNix snapshot. |
| `hypernix.recipe_book` | Named-config registry. `RecipeBook` with `add` / `get` / `save` / `load` / `cook(name, **overrides)`. `cook` dispatches by `kind` (`instant_pot` / `cold_brew` / `espresso`) so a saved recipe runs the matching pipeline directly. |
| `hypernix.mtp` | *(v0.70.5)* Multi-Token Prediction — predict multiple future tokens for 1.5-3x training efficiency + speculative decoding. `MTPConfig`, `MTPHead`, `MTPTrainer`. |

</details>

<details>
<summary><strong>Optimizers</strong> &nbsp;(3 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.pressure_cooker` | Custom AdamW optimizer in 5 tiers: base `PressureCooker` + CPU (`StovetopCooker`, `ElectricCooker`) + GPU (`InductionCooker`, `ProCooker`) + `universal_cooker` selector that picks a tier automatically from the detected device. |
| `hypernix.pressure_cooker_v3` | ZeRO-optimized V3 optimizer with FP8 support. `QuantDtype` enum (FP8/FP16/FP32/FP64/Q8/Q6/Q5_5/Q4M) and `QuantConfig` dataclass. `PressureCookerV3` / `PressureCookerV3Plus` classes with ZeRO-1/2 sharding, plus `StovetopV3Cooker` / `StovetopV3CookerPlus` CPU-tuned variants. |
| `hypernix.pressure_cooker_v5` | *(v0.70.5 / v0.70.6)* ORCP optimizer family with int8-quantized momentum, factored curvature, QAT (Q4/Q5/Q6/Q8), Multi-Token Prediction, and EMA shadowing. `PressureCookerV5` + `PressureCookerV5Plus`, plus the ground-up 3D-ORCP `PressureCookerV5S`. Pascal-safe variants: `Agedcookerv5`, `ULTRAagedcookerv5`, `Agedcookerv5s`. See the [efficiency paper](pressure_cooker_v5_v5s_paper.md). |

</details>

<details>
<summary><strong>Memory / VRAM</strong> &nbsp;(4 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.old_fridge` | Memory housekeeping: `freeze`, `unfreeze`, `parameter_stats`, `offload_to_cpu`, `chill_cache`. |
| `hypernix.freezer` | VRAM manager: `OldFreezer` (8-10 GB, conservative batches, bf16/fp16), `NewFreezer` (11 GB+, fp32-preferred), `FlashFreezer` (OOM-safe retry wrapper around either). Pascal (sm_61 / CUDA 6.1) helpers + 60 CPU presets (Intel i5/i7/i9 7th-14th gen, Core Ultra Series 1/2, AMD Ryzen 5000/7000/9000 series) via `auto_freezer()`. |
| `hypernix.cake_pan` | Hybrid CPU + GPU training guard with NaN/Inf detection, wall-time watchdog, memory-pressure offload, and pristine-state rollback via `BakeOff`. |
| `hypernix.stml` | *(v0.70.4)* **Short Term Memory Loss** — two tools. `calculate_vram_context(vram_gb, params, batch_size, precision)` estimates the max safe trained context given your hardware. The `STML` context manager folds long sequences into batch segments to keep the *untrained* context length bounded during training. |

</details>

<details>
<summary><strong>Data Pipeline</strong> &nbsp;(9 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.pans` | 5-tier data preprocessing: `FryingPan` → `SaucePan` → `Skillet` → `GrillPan` → `Wok`. Pair with `sink.Sink.pour` to write the output to disk. |
| `hypernix.blender` | 4-tier multi-source mixing: `HandBlender` / `PersonalBlender` / `CountertopBlender` / `HighPowerBlender`. |
| `hypernix.toaster` | 4-tier per-line formatting: `TwoSliceToaster` / `FourSliceToaster` / `ConveyorToaster` / `ToasterOven`. |
| `hypernix.food_processor` | 4-tier bulk chunking: `ChopBlade` / `SliceBlade` / `ShredBlade` / `PureeBlade`. |
| `hypernix.salt_shaker` | 3-tier gentle data augmentation: `FromTheBag` / `HandCrusher` / `PoshSaltDish`. |
| `hypernix.pepper_shaker` | 3-tier sharp perturbations: `SmallShaker` (MLM-style mask) / `Dish` (typos) / `TallHandmade` (negation). |
| `hypernix.qa` | *(v0.70.4)* **`QAProcessor`** — turns structured datasets (JSONL, `list[dict]`, plain text) into causal LM training strings. Two modes: `question_answer` (`Question: {q}\nAnswer: {a}`) and plain completion, with optional integrated `salt_shaker` / `pepper_shaker` seasoning. |
| `hypernix.cutting_board` | Train / val / test splitting. `CuttingBoard` (deterministic random) + `StratifiedBoard` (preserves class distribution on labelled records). Renormalises ratios that don't sum to 1; writes per-split files or returns in-memory lists. |
| `hypernix.lunchbox` | Consistent-schema dataset packager. `Lunchbox.for_eval()` pre-loads the recommended eval-results columns; `pack(path)` / `push_to_hub(repo_id)` routes through `datasets.Dataset` so column-schema mismatches fail fast instead of at upload time. |

</details>

<details>
<summary><strong>Inference & Chat</strong> &nbsp;(7 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.old_oven` | `CodeOven` — ready-to-use wrapper around a snapshot: `.complete()`, `.chat()`, `.fill()`, `.save_pt()`. `new_oven()` spins a fresh one from the [ARCH_PRESETS](#arch_presets-seeds-for-new_oven) seed list instead of downloading a snapshot. |
| `hypernix.microwave` | 5-tier throwaway inference: `defrost` → `low_zap` → `zap` → `high_zap` → `chat_zap`, plus `reheat` for continuing a prior output. |
| `hypernix.cookbook` | Chat-template registry. Built-in templates for `chatml` / `hyper-nix.2` / `llama3` / `llama2` / `alpaca` / `vicuna` / `plain`. `for_model(repo_id)` picks the right one automatically from the repo's config; wired into `old_oven` and `countertop` by default. |
| `hypernix.countertop` | Multi-turn chat session. `Countertop(oven, system=…)` with `say(user)` / `reset()` / `save(path)` / `load(path)`. Auto-trims long histories; optional `bell=` for token-by-token streaming, `flour=` for output cleanup, `t1_key=` for HNX1/T1-backed remote models. |
| `hypernix.menu` | Named system-prompt registry: `default` / `concise` / `code-helper` / `judge` / `creative` / `chef` / `hyper-nix`. Pair with `countertop(oven, persona="…")` to pick a system prompt by name instead of writing one out each time. |
| `hypernix.bell` | Streaming-token + done-notification primitive. `Bell.iter_chat(oven, messages)` yields tokens; `stream_chat` collects and fires callbacks. `stdout_bell()` / `file_bell(path)` ship as ready-made done-callbacks; `silent_bell()` disables notifications. |
| `hypernix.flour` | Chat-quality logits processor — repetition penalty, frequency / presence penalty, no-repeat n-gram, bad-word suppression, role-leak suppression (cuts hallucinated `user:`-style follow-on turns a base-model-flavoured checkpoint sometimes emits). |

</details>

<details>
<summary><strong>Monitoring & CLI</strong> &nbsp;(5 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.smoke_alarm` | Training-step planner & monitor. `RadsAlarm` (constants, lightest), `GasAlarm` (CPU/GPU presets), `ModernAlarm` (warmup-measured), `AutoAlarm` (selector). Plus `storage_warning()` for disk-space checks before a long run. |
| `hypernix.table` | Dead-simple tabular viewer: `from_training_log`, `from_judge_corpus`, `filter`, `select`, `show`. |
| `hypernix.tvtop` | Backwards-compatibility shim — all functionality moved to `hypernix.tv`. Re-exports everything so `import hypernix.tvtop` continues to work. Console script `tvtop` now launches the `tvtop_plus_plus` dashboard by default; use `tvtop-old` for the classic view. |
| `hypernix.wiki_cli` | *(v0.70.5)* `hnx` / `hypenix` command — auto-generating wiki from source docstrings. `hnx`, `hnx -q`, `hnx -b`. |
| `hypernix.vera` | *(v0.70.5)* Module verification — syntax, docstrings, types, smoke tests. `hnx vera <file>` / `hnx vera --all`. |

</details>

<details>
<summary><strong>Datasets & Judging</strong> &nbsp;(6 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.mediocre_fridge` | Judge-training dataset generation — `synthesize_judge_corpus`, `collect_responses_from`. |
| `hypernix.new_fridge` | Training-curve graphing — `parse_training_log`, `plot_loss_curve`, `plot_score_distribution`. Matplotlib installed lazily. |
| `hypernix.new_range` / `old_range` / `industrial_range` | Labeling rubrics for `mediocre_fridge.collect_responses_from`: `new_range` is a zero-dep first-fail rubric, `old_range` is a scored rubric with per-rule weights and explainable [0, 1] scores, and `industrial_range` uses any `CodeOven`-compatible model as an LLM judge (including pairwise comparison for preference pairs). |
| `hypernix.espresso_maker` | 4-tier evaluation: `Ristretto` / `SingleShot` / `DoubleShot` / `Lungo` — run a prompt battery, score, return shots. |
| `hypernix.smoker` | 4-tier training quality: `UseableSmoker` / `GoodSmoker` / `CommercialSmoker` / `HighQualitySmoker`. |
| `hypernix.scavenger` | *(v0.70.5)* HuggingFace dataset discovery engine. Keyword search, storage budgets, quality filtering, relevance scoring. `ScavengerCriteria` + `Scavenger.hunt()`. |

</details>

<details>
<summary><strong>Quantize & Export</strong> &nbsp;(3 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.convert` | Safetensors → GGUF at fp32/fp16. Architecture-agnostic tensor naming. |
| `hypernix.quantize` | `llama-quantize` driver. v0.51.3 ships a 30-type `QUANT_CATALOG` (`QuantSpec` dataclass per type with bits-per-weight, category, recommendation) covering floats (`F32` / `F16` / `BF16`), legacy k-quants (`Q4_0`…`Q5_1`), K-quants (`Q2_K`…`Q6_K`), and importance-matrix quants (`IQ1_S`…`IQ4_XS`); see the alias table below. |
| `hypernix.upload` | Push the produced artifacts back to a HuggingFace repo. |

</details>

<details>
<summary><strong>Utilities</strong> &nbsp;(3 modules)</summary>

| Subsystem | What it does |
|---|---|
| `hypernix.sink` | Append-only file sink with optional rotation + dedupe. |
| `hypernix.apron` | RNG-state guard. `apron(seed=…)` context manager snapshots Python `random`, NumPy (if installed), torch CPU and every CUDA device's RNG, optionally seeds all of them, and restores the original state on exit. |
| `hypernix.torch_compat` | Portability shim (RMSNorm + SDPA) for running on old Intel Macs with torch 1.13. See [`wiki/macOS-legacy.md`](wiki/macOS-legacy.md). |

</details>

---

## 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](pressure_cooker_v5_v5s_paper.md)), 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](wiki/Pressure-Cooker-V5.md), [MTP](wiki/MTP.md), [Scavenger](wiki/Scavenger.md)
- **Kitchen.md updated** — Added scavenger, MTP, and QAT sections
- **Training benefits chart** — See below

### Training Benefits vs Complexity

![HyperNix Training Features](docs/public/training-benefits-chart.png)

> **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](pressure_cooker_v5_v5s_paper.md) 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`** — Now launches the premium `tvtop_plus_plus` dashboard by default; use `tvtop-old` for the classic view

## Install

From PyPI:

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

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

```bash
# 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]'
```

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`](wiki/macOS-legacy.md) for the full story.

Sanity-check the environment:

```bash
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

```bash
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](#supported-model-families).

### Convert a snapshot to GGUF

```bash
# 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

```bash
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`](wiki/Pascal.md) for the full Pascal playbook.

### Build a HyperNix 0.1.5 evaluator

```bash
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

```python
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 <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)
  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
  hyped+ / hyped-pro    Node.js TUI agent CLI w/ real cloud+local model dispatch, /gui desktop mode
  stml                  VRAM trained context length calculator
```

`train run` accepts curriculum / context management flags:

```bash
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):

| Alias | llama.cpp enum | bpw | Recommended? |
|---|---|---|---|
| `fp32`, `f32` | F32 | 32.0 | reference |
| `fp16`, `f16` | F16 | 16.0 | ✓ baseline |
| `bf16` | BF16 | 16.0 |  |
| `q4_0`, `q4_1`, `q5_0`, `q5_1` | Q4_0 / Q4_1 / Q5_0 / Q5_1 | 4.5 – 6.0 | legacy |
| `q8`, `q8_0` | Q8_0 | 8.5 | ✓ near-lossless |
| `q2_k`, `q2_k_s`, `q3_k_s`, `q3_k_m`, `q3_k_l` | Q2_K … Q3_K_L | 2.5 – 4.0 |  |
| `q4_k_s`, `q4km`, `q4_k_m` | Q4_K_S, Q4_K_M | 4.5, 4.83 | ✓ chat sweet spot |
| `q5_k_s`, `q5km`, `q5_k_m` | Q5_K_S, Q5_K_M | 5.5, 5.83 | ✓ |
| `q6`, `q6_k` | Q6_K | 6.56 | ✓ near-fp16 |
| `iq1_s`, `iq1_m`, `iq2_*`, `iq3_*`, `iq4_nl`, `iq4_xs` | IQ1_S … IQ4_XS | 1.56 – 4.5 | imatrix-friendly |

## Supported model families

### Short names (CLI & Python)

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

| Family | Short names |
|---|---|
| **HyperNix** | `hyper-nix.1`, `hyper-nix`, `hypernix`, `nano-nano-v4`, `nano-mini-6.99-v2`, `nano-nano-927-v3` |
| **Nix** (ray0rf1re/nix collection) | `nix`, `nix2.5`, `nix2.6-m`, `nix2.6-mm`, `nix-2.7a`, `nix2.7`, `nix2.6` |
| **Llama 3.x** | `llama-3.1-8b`, `llama-3.1-8b-instruct`, `llama-3.2-1b`, `llama-3.2-3b`, `llama-3.3-70b-instruct` |
| **Qwen 2.5 / 3 / 3.5 / 3.6** | `qwen2.5-*`, `qwen3-0.6b`, `qwen3-8b`, `qwen3.5-{0.8b,2b,4b,9b,27b,35b-a3b,122b-a10b,397b-a17b}`, `qwen3.6-35b-a3b` |
| **Gemma 2 / 3 / 4** | `gemma-2-{2b,9b,27b}`, `gemma-3-{1b,4b}`, `gemma-4-{e2b,e4b,26b-a4b,31b}` |
| **Phi 3 / 3.5 / 4** | `phi-3-mini`, `phi-3.5-mini`, `phi-4` |
| **DeepSeek** | `deepseek-r1-distill-llama-8b`, `deepseek-r1-distill-qwen-7b`, `deepseek-v2-lite`, `deepseek-v3` |
| **GLM 4 / 5 / 5.1** | `glm-4-9b-chat`, `glm-4.1v`, `glm-5`, `glm-5.1`, `glm-5.1-fp8` |
| **Mistral / Mixtral** | `mistral-7b-instruct`, `mixtral-8x7b-instruct` |
| **NVIDIA** | `nemotron-4-15b`, `llama-3.1-nemotron-70b-instruct`, `mistral-nemo-12b` |
| **OpenAI gpt-oss** | `gpt-oss-20b`, `gpt-oss-120b` |

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`](examples/quickstart.py) — 5-line Python API demo.
- [`examples/custom_arch.py`](examples/custom_arch.py) — arbitrary-size HyperNix.
- [`examples/upload_to_hub.py`](examples/upload_to_hub.py) — publish to the Hub.
- [`examples/train_hypernix_0_1_5_evaluator.py`](examples/train_hypernix_0_1_5_evaluator.py) — tiny evaluator demo wiring ovens + all three fridges.
- [`examples/train_hypernix_1_5_gtx1080.py`](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`](wiki/Home.md) — index
- [`wiki/Ovens.md`](wiki/Ovens.md) — `old_oven` / `new_oven` reference
- [`wiki/Fridges.md`](wiki/Fridges.md) — `old_fridge` / `mediocre_fridge` / `new_fridge`
- [`wiki/Ranges.md`](wiki/Ranges.md) — `new_range` / `old_range` / `industrial_range` (labeling rubrics)
- [`wiki/Freezer.md`](wiki/Freezer.md) — VRAM manager (OldFreezer / NewFreezer / FlashFreezer)
- [`wiki/Alarms.md`](wiki/Alarms.md) — smoke alarms (Rads / Gas / Modern / Auto) + CPU / GPU preset tables
- [`wiki/Kitchen.md`](wiki/Kitchen.md) — pans / microwave / table / sink / instant pot / coffee maker / pressure cooker / qa
- [`wiki/Abbicus.md`](wiki/Abbicus.md) — Abbicus (linear) and TurboAbbicus (exponential + sine oscillation)
- [`wiki/STML.md`](wiki/STML.md) — Short Term Memory Loss context manager and VRAM calculator
- [`wiki/Pascal.md`](wiki/Pascal.md) — CUDA 6.1 / GTX 1080 playbook
- [`wiki/Architectures.md`](wiki/Architectures.md) — ARCH_PRESETS and KNOWN_MODELS
- [`wiki/Training.md`](wiki/Training.md) — scratch training, expansion, and fine-tuning flows
- [`wiki/CLI.md`](wiki/CLI.md) — full CLI cheat sheet
- [`wiki/Quantization.md`](wiki/Quantization.md) — GGUF conversion + k-quant pipeline
- [`wiki/Changelog.md`](wiki/Changelog.md) — full per-release version history
- [`wiki/Pressure-Cooker-V5.md`](wiki/Pressure-Cooker-V5.md) — Pressure Cooker V5 / V5+ / V5S with QAT and MTP
- [`wiki/MTP.md`](wiki/MTP.md) — Multi-Token Prediction guide
- [`wiki/Scavenger.md`](wiki/Scavenger.md) — HuggingFace dataset discovery

## 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.

## Build / release

```bash
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:

| Document | Description |
|---|---|
| [**pressure_cooker_v5_v5s_paper.md**](pressure_cooker_v5_v5s_paper.md) | PressureCookerV5 / V5S architecture, math, and measured efficiency numbers (memory + step-time), reproducible from the scripts below. |
| [**01_ram_and_training_time.pdf**](01_ram_and_training_time.pdf) | RAM usage patterns and training time impact analysis. |
| [**02_optimizer_speed_and_memory.pdf**](02_optimizer_speed_and_memory.pdf) | Optimizer performance comparison and memory optimization strategies. |
| [**03_gpu_utilization_and_vram.pdf**](03_gpu_utilization_and_vram.pdf) | GPU utilization patterns and VRAM management best practices. |
| [**04_architecture_and_pipeline.pdf**](04_architecture_and_pipeline.pdf) | Detailed architecture documentation and training pipeline information. |

```bash
# 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

LLU-0.1
