zpower 1.0.0__tar.gz

zpower-1.0.0/PKG-INFO

@@ -0,0 +1,157 @@
+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.

zpower-1.0.0/README.md

@@ -0,0 +1,128 @@
+# 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.

zpower-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires      = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name        = "zpower"
+version     = "1.0.0"
+description = "Intelligence layer for AI/ML — stabilization, selective memory, weight surgery"
+readme      = "README.md"
+license     = { text = "MIT" }
+authors     = [{ name = "NNN Bhoi" }]
+requires-python = ">=3.10"
+dependencies    = ["numpy>=1.24"]
+
+[project.optional-dependencies]
+torch = ["torch>=2.0"]
+hf    = ["transformers>=4.35", "torch>=2.0"]
+audio = ["torch>=2.0", "torchaudio>=2.0"]
+full  = ["torch>=2.0", "transformers>=4.35", "pandas>=2.0",
+         "scikit-learn>=1.3", "torchaudio>=2.0"]
+dev   = ["pytest>=7.0", "black", "mypy"]
+
+[project.urls]
+Homepage = "https://github.com/nnbhoi/zpower"
+
+[tool.setuptools.packages.find]
+where   = ["."]
+include = ["zpower*"]
+
+[tool.pytest.ini_options]
+testpaths    = ["tests"]
+addopts      = "-v --tb=short"

zpower-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zpower-1.0.0/tests/test_integration.py

@@ -0,0 +1,121 @@
+# tests/test_integration.py  —  Full pipeline, no torch required
+import numpy as np
+import pytest
+import zpower as zp
+from zpower.memory.otux             import OtuxStore
+from zpower.stabilize.model_stabilizer import ModelStabilizer
+from zpower.monitor.nipgraph        import NipGraph
+from zpower.weights.vault           import WeightVault
+from zpower.weights.surgeon         import WeightSurgeon
+from zpower.compute.safe_math       import safe_loss, safe_divide
+
+
+def test_import_and_version():
+    assert zp.__version__ == "1.0.0"
+    assert zp.__author__  == "NNN Bhoi"
+
+
+def test_info_no_crash(capsys):
+    zp.info()
+    captured = capsys.readouterr()
+    assert "ZPower" in captured.out
+
+
+# ── Full numpy pipeline ────────────────────────────────────────────────────
+
+def test_full_otux_pipeline():
+    store = OtuxStore(dim=16, mode="selective")
+    rng   = np.random.default_rng(0)
+
+    # Write several entries
+    for i in range(20):
+        v = rng.standard_normal(16).astype(np.float32)
+        store.write(f"entry_{i}", v, x=i, y=i % 3, z=i % 5, reward=rng.uniform(0, 1))
+
+    stats = store.filter_stats()
+    assert stats["total_seen"] == 20
+    assert stats["currently_stored"] <= 20
+
+
+def test_full_stabilizer_pipeline():
+    ms = ModelStabilizer()
+    ng = NipGraph(variables=["loss", "grad_norm"])
+    ms._nipgraph = ng
+    ms.stability_core._nipgraph = ng
+
+    losses = [3.0, 2.5, 2.0, 1.8, 1.5, 1.3, 1.2, 1.1, 1.05, 1.02]
+    for L in losses:
+        info = ms.on_loss(L)
+        assert "state" in info
+
+    # Gradient shield
+    g_healthy   = np.ones(4, dtype=np.float32) * 0.5
+    g_exploding = np.ones(4, dtype=np.float32) * 100.0
+    assert ms.grad_shield.check(g_healthy)   == "healthy"
+    assert ms.grad_shield.check(g_exploding) == "exploding"
+
+    shielded = ms.grad_shield.shield(g_exploding)
+    assert float(np.linalg.norm(shielded)) <= 5.0 + 1e-4
+
+
+def test_vault_and_surgeon_pipeline():
+    rng = np.random.default_rng(42)
+
+    class FakeModel:
+        def __init__(self, seed):
+            _rng = np.random.default_rng(seed)
+            self.fc1 = _rng.standard_normal((8, 4)).astype(np.float32)
+            self.fc2 = _rng.standard_normal((4, 2)).astype(np.float32)
+
+    # Vault: record good model
+    vault = WeightVault(vault_threshold=0.0)
+    vault.record(FakeModel(0), {
+        "loss": 0.1, "loss_reference": 2.0,
+        "val_accuracy": 0.95, "confidence": 0.90,
+        "grad_health": "healthy", "curvature": "flat",
+    })
+    assert vault.summary()["total_snapshots"] > 0
+
+    # Surgeon: merge two models
+    surgeon = WeightSurgeon(conflict_resolution="highest_performer")
+    sd1 = {"fc1": FakeModel(0).fc1, "fc2": FakeModel(0).fc2}
+    sd2 = {"fc1": FakeModel(1).fc1, "fc2": FakeModel(1).fc2}
+    surgeon.add_source(sd1, label="model_a", perf_score=0.6)
+    surgeon.add_source(sd2, label="model_b", perf_score=0.9)
+    best = surgeon.select_best()
+    assert "fc1" in best
+    assert "fc2" in best
+
+
+def test_safe_math_pipeline():
+    # Normal loss
+    p = np.array([0.3, 0.3, 0.4])
+    t = np.array([0.0, 0.0, 1.0])
+    loss = safe_loss(p, t, "mse")
+    assert loss > 0
+
+    # Recurring division
+    token = safe_divide(1, 3)
+    assert abs(float(token) - 1/3) < 1e-9
+
+    # Deduplication
+    token2 = safe_divide(1, 3)
+    assert token.name == token2.name
+
+
+def test_nipgraph_training_simulation():
+    ng = NipGraph(variables=["loss", "accuracy"])
+
+    # Simulate healthy training
+    for i in range(30):
+        loss = 2.0 * np.exp(-0.1 * i) + 0.01 * np.random.default_rng(i).standard_normal()
+        acc  = 1.0 - loss / 2.0
+        ng.update("loss",     max(loss, 0.01))
+        ng.update("accuracy", min(max(acc, 0.0), 1.0))
+
+    state = ng.check()
+    assert "loss" in state
+    assert "accuracy" in state
+    # No alerts expected in healthy training
+    # (may or may not converge depending on values — just check no crash)
+    assert isinstance(state["loss"]["track"], str)

zpower-1.0.0/tests/test_nipgraph.py

@@ -0,0 +1,102 @@
+# tests/test_nipgraph.py
+import pytest
+from zpower.monitor.nipgraph import NipGraph
+
+
+def test_basic_update_no_alert():
+    ng = NipGraph(variables=["loss"], band_width=0.5)
+    for i in range(5):
+        ng.update("loss", 1.0 - i * 0.05)
+    state = ng.check()
+    assert "loss" in state
+    assert state["loss"]["alert"] is False
+
+
+def test_track_classification_positive_stable():
+    ng = NipGraph(variables=["loss"], band_width=0.5)
+    for _ in range(10):
+        ng.update("loss", 1.0)
+    state = ng.check()
+    assert state["loss"]["track"] in ("x_M", "x_W")
+
+
+def test_alert_fires_on_bad_jump():
+    ng = NipGraph(variables=["loss"], band_width=0.05)
+    # Establish stable positive trend
+    for _ in range(10):
+        ng.update("loss", 1.0)
+    # Sudden negative spike (EMA positive, value hugely negative)
+    ng.update("loss", -100.0)
+    state = ng.check()
+    # Track should have jumped to Y_W territory
+    alerts = ng.alerts()
+    # Either direct alert or track is Y_W
+    assert state["loss"]["track"] in ("Y_M", "Y_W") or len(alerts) > 0
+
+
+def test_convergence_detection():
+    ng = NipGraph(variables=["loss"], band_width=0.5)
+    # Feed very stable values — should converge
+    for _ in range(25):
+        ng.update("loss", 0.001)
+    assert ng.is_converged() is True
+
+
+def test_not_converged_with_variance():
+    ng = NipGraph(variables=["loss"])
+    import random
+    rng = random.Random(42)
+    for _ in range(25):
+        ng.update("loss", rng.uniform(0.5, 5.0))
+    assert ng.is_converged() is False
+
+
+def test_multiple_variables():
+    ng = NipGraph(variables=["loss", "grad_norm", "accuracy"])
+    ng.update("loss",      2.0)
+    ng.update("grad_norm", 0.5)
+    ng.update("accuracy",  0.8)
+    state = ng.check()
+    assert set(state.keys()) == {"loss", "grad_norm", "accuracy"}
+
+
+def test_auto_add_new_variable():
+    ng = NipGraph(variables=["loss"])
+    ng.update("new_metric", 1.0)   # not in initial list
+    state = ng.check()
+    assert "new_metric" in state
+
+
+def test_clear_alerts():
+    ng = NipGraph(variables=["loss"], band_width=0.01)
+    for _ in range(5):
+        ng.update("loss", 1.0)
+    ng.update("loss", -999.0)
+    ng.clear_alerts()
+    assert ng.alerts() == []
+
+
+def test_locate_fault_no_anomaly():
+    ng = NipGraph(variables=["loss"])
+    ng.update("loss", 1.0)
+    msg = ng.locate_fault("loss")
+    assert "No anomaly" in msg
+
+
+def test_render_panels_no_crash(capsys):
+    ng = NipGraph(variables=["loss", "accuracy"])
+    for _ in range(3):
+        ng.update("loss",     1.0)
+        ng.update("accuracy", 0.9)
+    ng.render_panels()
+    captured = capsys.readouterr()
+    assert "NipGraph" in captured.out
+
+
+def test_status_keys():
+    ng = NipGraph(variables=["loss"])
+    s = ng.status()
+    assert "step" in s
+    assert "variables" in s
+    assert "converged" in s
+    assert "alerts" in s

zpower-1.0.0/tests/test_otux.py

@@ -0,0 +1,134 @@
+# tests/test_otux.py
+import numpy as np
+import pytest
+from zpower.memory.otux import OtuxStore, ImportanceWeights
+
+
+def make_vec(dim=256, seed=None):
+    rng = np.random.default_rng(seed)
+    v   = rng.standard_normal(dim).astype(np.float32)
+    return v / (np.linalg.norm(v) + 1e-10)
+
+
+# ── ImportanceWeights ──────────────────────────────────────────────────────
+
+def test_weights_sum_to_one():
+    w = ImportanceWeights(0.35, 0.30, 0.20, 0.15)
+    assert abs(w.novelty + w.reward + w.context_fit + w.recurrence - 1.0) < 1e-5
+
+
+def test_weights_bad_sum():
+    with pytest.raises(ValueError):
+        ImportanceWeights(0.5, 0.5, 0.5, 0.5)
+
+
+# ── OtuxStore basic ────────────────────────────────────────────────────────
+
+def test_store_and_len():
+    store = OtuxStore(dim=8, mode="full")
+    store.write("hello", make_vec(8, 0))
+    store.write("world", make_vec(8, 1))
+    assert len(store) == 2
+
+
+def test_query_returns_results():
+    store = OtuxStore(dim=8, mode="full")
+    v = make_vec(8, 42)
+    store.write("alpha", v)
+    results = store.query(v, top_k=1)
+    assert len(results) == 1
+    assert results[0]["token"] == "alpha"
+    assert results[0]["sim"] > 0.99
+
+
+def test_query_empty_store():
+    store = OtuxStore(dim=8)
+    results = store.query(make_vec(8), top_k=5)
+    assert results == []
+
+
+def test_coord_retrieval():
+    store = OtuxStore(dim=8, mode="full")
+    store.write("deep",    make_vec(8, 0), x=0, y=0, z=3)
+    store.write("surface", make_vec(8, 1), x=0, y=0, z=0)
+    deep_results = store.query_by_coord(z=3, tol=0.1)
+    assert len(deep_results) == 1
+    assert deep_results[0].token == "deep"
+
+
+def test_force_write_bypasses_gate():
+    store = OtuxStore(dim=8, mode="selective", importance_threshold=0.99)
+    result = store.write("forced", make_vec(8, 0), reward=0.0, force=True)
+    assert result == "forced"
+    assert len(store) == 1
+
+
+# ── Importance gate ────────────────────────────────────────────────────────
+
+def test_discard_low_reward():
+    store = OtuxStore(
+        dim=8,
+        mode="selective",
+        importance_threshold=0.65,
+        forget_threshold=0.30,
+        weights={"novelty": 0.35, "reward": 0.30, "context_fit": 0.20, "recurrence": 0.15},
+    )
+    # reward=0.0, no context → score will be low → discard
+    result = store.write("junk", make_vec(8, 99), reward=0.0)
+    # First entry: novelty=1.0, reward=0.0, context=0.5, recurrence=log(2)/5
+    # score = 0.35*1.0 + 0.30*0.0 + 0.20*0.5 + 0.15*~0.14 ≈ 0.47 → below 0.65
+    # Could be buffered or discarded — just not stored immediately
+    assert result in ("discarded", "buffered")
+
+
+def test_high_reward_stored():
+    store = OtuxStore(dim=8, mode="selective", importance_threshold=0.65)
+    result = store.write("important", make_vec(8, 1), reward=1.0)
+    # novelty=1.0 (first entry), reward=1.0 → score ≈ 0.35+0.30+0.10+0.02 = 0.77 → stored
+    assert result == "stored"
+
+
+def test_buffer_three_strikes():
+    store = OtuxStore(
+        dim=8, mode="selective",
+        importance_threshold=0.90,   # high threshold → most go to buffer
+        forget_threshold=0.05,
+        buffer_strikes=3,
+    )
+    v = make_vec(8, 7)
+    for _ in range(3):
+        store.write("repeat", v, reward=0.4)
+    # After 3 strikes → promoted to store
+    assert len(store) >= 1
+
+
+# ── Filter stats ───────────────────────────────────────────────────────────
+
+def test_filter_stats_keys():
+    store = OtuxStore(dim=8, mode="full")
+    store.write("a", make_vec(8, 0))
+    s = store.filter_stats()
+    assert "stored" in s
+    assert "discarded" in s
+    assert "compression_ratio" in s
+    assert "currently_stored" in s
+
+
+def test_clear():
+    store = OtuxStore(dim=8, mode="full")
+    store.write("x", make_vec(8))
+    store.clear()
+    assert len(store) == 0
+
+
+# ── Vector validation ──────────────────────────────────────────────────────
+
+def test_wrong_dim_raises():
+    store = OtuxStore(dim=8)
+    with pytest.raises(ValueError):
+        store.write("bad", np.ones(16, dtype=np.float32))
+
+
+def test_repr():
+    store = OtuxStore(dim=8, mode="full")
+    assert "OtuxStore" in repr(store)