npguard 0.1.0__tar.gz

npguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Priyanshu Rauth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npguard-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: npguard
+Version: 0.1.0
+Summary: NumPy memory observability and explanation tool
+Author: Priyanshu Rauth
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/npguard
+Project-URL: Issues, https://github.com/yourusername/npguard/issues
+Keywords: numpy,memory,profiling,performance,scientific-computing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: license-file
+
+# npguard
+
+**npguard** is a NumPy memory observability and explanation tool.
+
+It helps developers understand *why* NumPy memory usage spikes by detecting
+temporary allocations and explaining their causes, with safe, opt-in suggestions
+to reduce memory pressure.
+
+## Features
+
+- Watch NumPy-heavy code blocks
+- Detect memory pressure and hidden temporaries
+- Explain causes (chained ops, broadcasting)
+- Provide safe optimization suggestions
+- No monkey-patching, no unsafe automation
+
+## What npguard does not do
+- Does not modify NumPy behavior
+- Does not automatically reuse buffers
+- Does not rewrite code
+
+## Example
+
+```python
+import numpy as np
+import npguard as ng
+
+with ng.memory_watcher("matrix_pipeline"):
+    a = np.random.rand(10_000, 100)
+    ng.register_array(a, "a")
+
+    b = a * 2 + a.mean(axis=0) - 1
+    ng.register_array(b, "b")
+
+    c = np.ascontiguousarray(b.T)
+    ng.register_array(c, "c")
+
+ng.report()
+ng.suggest()

npguard-0.1.0/README.md

@@ -0,0 +1,39 @@
+# npguard
+
+**npguard** is a NumPy memory observability and explanation tool.
+
+It helps developers understand *why* NumPy memory usage spikes by detecting
+temporary allocations and explaining their causes, with safe, opt-in suggestions
+to reduce memory pressure.
+
+## Features
+
+- Watch NumPy-heavy code blocks
+- Detect memory pressure and hidden temporaries
+- Explain causes (chained ops, broadcasting)
+- Provide safe optimization suggestions
+- No monkey-patching, no unsafe automation
+
+## What npguard does not do
+- Does not modify NumPy behavior
+- Does not automatically reuse buffers
+- Does not rewrite code
+
+## Example
+
+```python
+import numpy as np
+import npguard as ng
+
+with ng.memory_watcher("matrix_pipeline"):
+    a = np.random.rand(10_000, 100)
+    ng.register_array(a, "a")
+
+    b = a * 2 + a.mean(axis=0) - 1
+    ng.register_array(b, "b")
+
+    c = np.ascontiguousarray(b.T)
+    ng.register_array(c, "c")
+
+ng.report()
+ng.suggest()

npguard-0.1.0/npguard/__init__.py

@@ -0,0 +1,13 @@
+from .core import (
+    memory_watcher,
+    register_array,
+    report,
+    suggest,
+)
+
+__all__ = [
+    "memory_watcher",
+    "register_array",
+    "report",
+    "suggest",
+]

npguard-0.1.0/npguard/core.py

@@ -0,0 +1,203 @@
+"""
+npguard.py
+
+NumPy Memory Guard (v1)
+
+A NumPy memory observability and explanation tool.
+
+Features:
+1. Watch NumPy memory behavior
+2. Notify users about memory pressure & temporaries
+3. Suggest opt-in ways to reduce memory pressure
+
+This module does NOT modify NumPy internals.
+It only observes and explains memory behavior.
+"""
+
+import numpy as np
+import tracemalloc
+import gc
+import inspect
+from collections import defaultdict
+from contextlib import contextmanager
+
+# ---------------------------
+# Global State (v1)
+# ---------------------------
+
+ArrayRegistry = {}
+Alloc_Tracker = defaultdict(int)
+_last_observation = {}
+
+# ---------------------------
+# Helpers
+# ---------------------------
+
+def array_size(arr: np.ndarray) -> int:
+    return arr.nbytes
+
+
+def register_array(arr: np.ndarray, label: str = "array"):
+    key = id(arr)
+    ArrayRegistry[key] = {
+        "label": label,
+        "size": arr.nbytes,
+        "shape": arr.shape,
+        "dtype": str(arr.dtype),
+        "owndata": arr.flags["OWNDATA"],
+        "contiguous": arr.flags["C_CONTIGUOUS"],
+    }
+    Alloc_Tracker[label] += arr.nbytes
+
+
+def _cleanup_dead_arrays():
+    live_ids = {id(obj) for obj in gc.get_objects() if isinstance(obj, np.ndarray)}
+    dead = set(ArrayRegistry) - live_ids
+    for k in dead:
+        del ArrayRegistry[k]
+
+
+def _find_user_frame():
+    for frame_info in inspect.stack():
+        fname = frame_info.filename
+        if "npguard" not in fname and "contextlib" not in fname:
+            return frame_info
+    return None
+
+
+# ---------------------------
+# Watcher (core feature)
+# ---------------------------
+
+@contextmanager
+def memory_watcher(tag="block", warn_threshold_mb=10):
+    tracemalloc.start()
+    start_current, _ = tracemalloc.get_traced_memory()
+    start_snapshot = set(ArrayRegistry.keys())
+
+    yield
+
+    _cleanup_dead_arrays()
+    current, peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+
+    python_peak_mb = (peak - start_current) / 1024 / 1024
+    python_cur_mb = (current - start_current) / 1024 / 1024
+
+    new_arrays = len(set(ArrayRegistry.keys()) - start_snapshot)
+
+    numpy_live_mb = sum(info["size"] for info in ArrayRegistry.values()) / 1024 / 1024
+    temp_estimate_mb = max(0.0, python_peak_mb - numpy_live_mb)
+
+    _last_observation.update({
+        "tag": tag,
+        "python_peak_mb": python_peak_mb,
+        "python_current_mb": python_cur_mb,
+        "numpy_live_mb": numpy_live_mb,
+        "temp_estimate_mb": temp_estimate_mb,
+        "new_arrays": new_arrays,
+    })
+
+    print(f"\n[npguard] Memory Watch: {tag}")
+    print(f"  Python peak diff:    {python_peak_mb:.2f} MB")
+    print(f"  Python current diff: {python_cur_mb:.2f} MB")
+    print(f"  NumPy live arrays:   {numpy_live_mb:.2f} MB")
+    print(f"  Estimated temporaries: {temp_estimate_mb:.2f} MB")
+
+    if python_peak_mb > warn_threshold_mb:
+        _emit_warning()
+
+
+# ---------------------------
+# Warning & Explanation
+# ---------------------------
+
+def _emit_warning():
+    obs = _last_observation
+    frame = _find_user_frame()
+    location = f"{frame.filename}:{frame.lineno}" if frame else "<unknown>"
+
+    print("\n⚠️  Memory pressure detected")
+    print(f"  Location: {location}")
+    print(f"  Peak memory increase: {obs['python_peak_mb']:.2f} MB")
+
+    if obs["temp_estimate_mb"] > 5:
+        print(f"  Likely temporary allocations: ~{obs['temp_estimate_mb']:.2f} MB")
+        print("  Cause: chained NumPy operations or broadcasting")
+
+
+# ---------------------------
+# Suggestions (educational)
+# ---------------------------
+
+def _same_shape_groups():
+    groups = defaultdict(list)
+    for info in ArrayRegistry.values():
+        groups[(info["shape"], info["dtype"])].append(info)
+    return groups
+
+
+def _forced_copy_detected():
+    for info in ArrayRegistry.values():
+        if info["owndata"] and not info["contiguous"]:
+            return True
+    return False
+
+def suggest(temp_threshold_mb=5):
+    print("\n[npguard] Suggestions:")
+
+    obs = _last_observation
+    if not obs:
+        print("  No observation data available.")
+        return
+
+    temp_mb = obs["temp_estimate_mb"]
+
+    if temp_mb < temp_threshold_mb:
+        print("  No significant temporary allocations detected.")
+        return
+
+    print(f"  This block allocated ~{temp_mb:.2f} MB in temporary arrays.")
+
+    # 1 Chained expression detection
+    if temp_mb > obs["numpy_live_mb"] * 2:
+        print(
+            "  • Likely cause: chained NumPy expressions creating intermediate arrays."
+        )
+        print(
+            "    Suggestion: split expressions into steps or use ufuncs with `out=`."
+        )
+
+    # 2️ Same-shape allocation reuse hint
+    shape_groups = _same_shape_groups()
+    for (shape, dtype), items in shape_groups.items():
+        if len(items) >= 2:
+            print(
+                f"  • Detected {len(items)} arrays with same shape {shape} and dtype {dtype}."
+            )
+            print(
+                "    Suggestion: consider reusing a preallocated buffer for these arrays."
+            )
+            break  # avoid spam
+
+    # 3️ Forced copy hint
+    for info in ArrayRegistry.values():
+        if info["owndata"] and info["contiguous"]:
+            continue
+        if info["owndata"]:
+            print(
+                f"  • Array '{info['label']}' appears to be a forced copy."
+            )
+            print(
+                "    Suggestion: avoid operations that require contiguity (e.g. ascontiguousarray) if possible."
+            )
+            break
+
+# ---------------------------
+# Reporting
+# ---------------------------
+
+def report():
+    print("\n[npguard] Allocation Summary (cumulative)")
+    for label, size in Alloc_Tracker.items():
+        print(f"  {label:<12}: {size/1024/1024:.2f} MB")

npguard-0.1.0/npguard.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: npguard
+Version: 0.1.0
+Summary: NumPy memory observability and explanation tool
+Author: Priyanshu Rauth
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/npguard
+Project-URL: Issues, https://github.com/yourusername/npguard/issues
+Keywords: numpy,memory,profiling,performance,scientific-computing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: license-file
+
+# npguard
+
+**npguard** is a NumPy memory observability and explanation tool.
+
+It helps developers understand *why* NumPy memory usage spikes by detecting
+temporary allocations and explaining their causes, with safe, opt-in suggestions
+to reduce memory pressure.
+
+## Features
+
+- Watch NumPy-heavy code blocks
+- Detect memory pressure and hidden temporaries
+- Explain causes (chained ops, broadcasting)
+- Provide safe optimization suggestions
+- No monkey-patching, no unsafe automation
+
+## What npguard does not do
+- Does not modify NumPy behavior
+- Does not automatically reuse buffers
+- Does not rewrite code
+
+## Example
+
+```python
+import numpy as np
+import npguard as ng
+
+with ng.memory_watcher("matrix_pipeline"):
+    a = np.random.rand(10_000, 100)
+    ng.register_array(a, "a")
+
+    b = a * 2 + a.mean(axis=0) - 1
+    ng.register_array(b, "b")
+
+    c = np.ascontiguousarray(b.T)
+    ng.register_array(c, "c")
+
+ng.report()
+ng.suggest()

npguard-0.1.0/npguard.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+npguard/__init__.py
+npguard/core.py
+npguard.egg-info/PKG-INFO
+npguard.egg-info/SOURCES.txt
+npguard.egg-info/dependency_links.txt
+npguard.egg-info/requires.txt
+npguard.egg-info/top_level.txt

npguard-0.1.0/npguard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

npguard-0.1.0/npguard.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy

npguard-0.1.0/npguard.egg-info/top_level.txt

@@ -0,0 +1 @@
+npguard

npguard-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "npguard"
+version = "0.1.0"
+description = "NumPy memory observability and explanation tool"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+
+authors = [
+  { name = "Priyanshu Rauth" }
+]
+
+keywords = [
+  "numpy",
+  "memory",
+  "profiling",
+  "performance",
+  "scientific-computing"
+]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Debuggers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only"
+]
+
+dependencies = [
+  "numpy"
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/npguard"
+Issues = "https://github.com/yourusername/npguard/issues"

npguard-0.1.0/setup.cfg

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