Metadata-Version: 2.4
Name: zpower
Version: 1.0.0
Summary: Intelligence layer for AI/ML — stabilization, selective memory, weight surgery
Author: NNN Bhoi
License: MIT
Project-URL: Homepage, https://github.com/nnbhoi/zpower
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: hf
Requires-Dist: transformers>=4.35; extra == "hf"
Requires-Dist: torch>=2.0; extra == "hf"
Provides-Extra: audio
Requires-Dist: torch>=2.0; extra == "audio"
Requires-Dist: torchaudio>=2.0; extra == "audio"
Provides-Extra: full
Requires-Dist: torch>=2.0; extra == "full"
Requires-Dist: transformers>=4.35; extra == "full"
Requires-Dist: pandas>=2.0; extra == "full"
Requires-Dist: scikit-learn>=1.3; extra == "full"
Requires-Dist: torchaudio>=2.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# 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

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

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

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

```python
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.
