zpower 1.1.0

Intelligence layer for AI/ML — stabilization, selective memory, weight surgery

ZPower (zp) — v1

Intelligence layer for AI/ML systems.
Works with PyTorch and HuggingFace — not against them.

Stabilize training. Protect good weights. Detect anomalies. Reduce wasted compute.

---

Install

pip install zpower                # numpy only (core features)
pip install zpower[torch]         # + PyTorch support
pip install zpower[hf]            # + HuggingFace Transformers
pip install zpower[full]          # everything

---

Quick Start

Mode A — Pre-trained model (attach ZPower)

import zpower as zp

# Any PyTorch or HuggingFace model
zp_model = zp.attach(
    my_model,
    stabilize    = True,   # GradShield + StabilityCore
    monitor      = True,   # NipGraph anomaly detection
    weight_vault = True,   # Record best weight checkpoints
)

# Forward pass — completely unchanged
output = zp_model(input_tensor)

# After loss + backward — ZPower hooks are active automatically
loss.backward()

Mode B — Training from scratch

import zpower as zp

trainer = zp.Trainer(
    my_model,
    stabilize    = True,
    weight_vault = True,
    weight_guard = False,   # enable after first good run
)

trainer.fit(train_loader, epochs=20, lr=1e-3)

print(trainer.weight_report())
# { layers_vaulted: 12, total_snapshots: 47, overall_vault_score: 0.84 }

trainer.render_monitor()
# NipGraph ASCII dashboard

Multi-model weight selection

from zpower.weights import WeightSurgeon

surgeon = WeightSurgeon(conflict_resolution="highest_performer")
surgeon.add_source("run_jan.pt",  label="jan", perf_score=0.72)
surgeon.add_source("run_mar.pt",  label="mar", perf_score=0.89)
surgeon.add_source("run_may.pt",  label="may", perf_score=0.81)

best_weights = surgeon.select_best()
new_model.load_state_dict(best_weights)

print(surgeon.selection_report())
# { 'transformer.layer.0.attn': 'mar', 'transformer.layer.1.ffn': 'may', ... }

---

Module Overview

Module	Purpose
zp.memory.OtuxStore	Selective context-aware memory — stores only important information
zp.stabilize.GradShield	Real-time gradient health: detects vanishing / exploding
zp.stabilize.StabilityCore	Loss EMA + plateau detection + LR signal
zp.stabilize.ModelStabilizer	Unified stabilization API
zp.monitor.NipGraph	Parity-aware training anomaly detection
zp.weights.WeightVault	Performance-gated weight snapshots
zp.weights.WeightSurgeon	Multi-model best weight selection (Fisher-guided)
zp.weights.WeightGuard	EWC-style catastrophic forgetting prevention
zp.compute.safe_loss	NaN-safe loss computation with rational fallback
zp.compute.safe_divide	Exact fraction arithmetic for recurring decimals
zp.compat.ZPowerModel	PyTorch model wrapper
zp.compat.augment	HuggingFace model augmentation

---

How ZPower Reduces Load

Problem	ZPower Solution	Effect
NaN crash mid-training	GradShield clips before NaN	No wasted restart
Plateau wastes epochs	StabilityCore signals LR reduction	Converges faster
Catastrophic forgetting	WeightGuard EWC penalty	Retains good knowledge
Starting training from scratch	WeightSurgeon merges best of past runs	Better initialization
Storing all context blindly	OTUX-S importance gate	70%+ memory reduction
Anomaly found too late	NipGraph detects at first sign	Early intervention

---

Research Origins

All core systems are original research by NNN Bhoi:

• OTUX-S — from PERATHINK research paper (selective 3D coordinate memory)
• NipGraph — from NipGraph research paper (parity-aware state tracking)
• GradShield + StabilityCore — from MUSAI vGPU engine (M2 + M4)
• WeightVault / Surgeon / Guard — original ZPower research

---

License

MIT — free to use in any project.