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()
