Metadata-Version: 2.4
Name: gradexp
Version: 0.1.28
Summary: Gradient Explorer Python Client Library
Author-email: Misha Obu <misha@parallel-ocean.xyz>
Requires-Python: >=3.7
Requires-Dist: appdirs
Requires-Dist: click
Requires-Dist: numpy
Requires-Dist: requests
Description-Content-Type: text/markdown

# gradexp

Like wandb, but for tensors.

`gradexp` logs tensors from Python and lets you inspect them in Gradient Explorer, either in the hosted app or a local viewer.

## Quickstart

```bash
pip install gradexp
gradexp login
# For local mode:
gradexp local open
```

Example:

```python
import gradexp
import numpy as np

gradexp.init(project_name="examples", run_name="hello-gradexp")

for step in range(10):
    tensor = np.random.randn(224, 224, 3).astype(np.float32)
    gradexp.log(tensor, name="tensor")
```

When `gradexp.init()` succeeds, it prints a run URL. If a local instance is running, data is routed there automatically.

> **Note:** tensor names are immutable once a tensor is created — they're keys
> into per-tensor stats and shape metadata. Choose names carefully on the
> first `log` call. Project and run names can be renamed in the explorer UI;
> tensor names cannot.

## Semantic Model Tensor Views

`gradexp.log_model_tensors(model)` and `gradexp.log_gradient_stats(model)` log `model.named_parameters()` by default. Models that store several logical layers in one banked parameter can provide a semantic view by defining:

```python
def gradexp_unbank_state_dict(self, state_dict):
    ...
```

The method receives a mapping of raw parameter names to tensors and returns a mapping of semantic names to tensors. Gradexp calls it automatically when present, for both weights and gradients:

```python
class GPT(nn.Module):
    def gradexp_unbank_state_dict(self, state_dict):
        return _unbank_state_dict(state_dict, self.num_layers)
```

Use `semantic=False` or `semantic="raw"` to force raw PyTorch parameter names.

## Common CLI Commands

```bash
gradexp login
gradexp local open
gradexp local start
gradexp local status
gradexp local stop
gradexp local sync
```
