Metadata-Version: 2.4
Name: neuralveil
Version: 1.0.0
Summary: NeuralVeil CLI — part of the NeuralVeil Tensor Shape Debugger. Graph any PyTorch model architecture in one command using torch.fx and forward hooks. Captures real tensor shapes locally — no server, no code upload, works in air-gapped environments.
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: torch>=1.8
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: torchvision; extra == "dev"

# neuralveil

**Graph your PyTorch model architecture in one command.**

```bash
pip install neuralveil
neuralveil parse model.py
```

Drop the output into [neuralveil.dev](https://neuralveil.dev) and see your model as an interactive graph — layers, tensor shapes, parameter counts — all verified by actually running your code.

---

## How it works

```
your model.py  ──▶  neuralveil parse  ──▶  your local PyTorch
                                                    │
                                         torch.fx trace / forward hooks
                                                    │
                          neuralveil_output.json  ◀─┘
                                    │
                        drop into neuralveil.dev  ──▶  interactive graph
```

The CLI tries two capture strategies, in order:

**1. `torch.fx` symbolic trace (preferred)**
PyTorch's official graph capture API. Traces `forward()` into a structured FX graph IR with typed nodes, operator types, and shapes. Handles VGG, ResNet, DenseNet, and most CNN families cleanly.

**2. `register_forward_hook` (fallback)**
For models with dynamic control flow that `torch.fx` can't symbolically trace. Runs a dummy forward pass with hooks on every named submodule, capturing real input/output shapes and parameter counts. Works on virtually any valid PyTorch model.

---

## Installation

```bash
pip install neuralveil
```

PyTorch is listed as an optional dependency — ML engineers already have it. If you're setting up a fresh environment:

```bash
pip install "neuralveil[torch]"
```

**Requirements:** Python ≥ 3.9

---

## Usage

```bash
# basic
neuralveil parse model.py

# specify input shape
neuralveil parse model.py --input 1,3,224,224

# custom output path
neuralveil parse model.py --output my_graph.json
```

If the file defines multiple `nn.Module` subclasses, the CLI will prompt you to pick one.

### Python API

```python
import neuralveil

graph = neuralveil.parse_model("model.py", input_shape=(1, 3, 224, 224))
print(graph["nodes"])
```

---

## Security model

The CLI runs entirely on your machine. There is no server, no code upload, no API key, no rate limit.

- Your code never leaves your environment
- Works fully offline and in air-gapped environments
- Execution timeout: 15 seconds (SIGKILL after)

---

## Contributing

Issues and PRs welcome. Built by [Gyan Shresth](https://github.com/gyan) · Apache 2.0
