Easy Debug

A comprehensive Python debugging toolkit for PyTorch and ML workflows. Easy Debug provides utilities to dump, view, and compare tensors, arrays, and other data structures during model training and inference.

Features

• 🔍 Easy Dump: Save tensors, arrays, and complex data structures with automatic format detection
• 👁️ Easy View: Inspect binary files (.pt, .npy, .json, .pkl) in a human-readable format
• ⚖️ Easy Compare: Compare dumped files or entire directories with detailed diff reports
• 🎯 Automatic Format Detection: Smart file extension detection based on data type
• 📊 Rich Statistics: Get detailed statistics for tensors and arrays
• 🔄 Flexible Configuration: Control dump behavior via environment variables

Installation

From Source

git clone https://github.com/nex-agi/easy-debug.git
cd easy-debug
pip install -e .

Using pip (once published)

pip install easy-debug

Quick Start

1. Easy Dump

Dump values during training or inference:

from easy_debug import easy_dump
import torch

# Enable dumping via environment variable
import os
os.environ["ENABLE_EASY_DUMP"] = "1"

# Dump a tensor
tensor = torch.randn(3, 4)
easy_dump(tensor, keys=["layer1", "activation"], training_step=100)

# Dump a dictionary
data = {"loss": 0.5, "accuracy": 0.95}
easy_dump(data, keys=["metrics"], training_step=100)

2. Easy View

Inspect dumped files:

# View a .pt file
python -m easy_debug.easy_view logs/default/run_*/step_*.pt

# Save output to file
python -m easy_debug.easy_view data.pt -o output.txt

# Limit recursion depth for nested structures
python -m easy_debug.easy_view data.pt --max-depth 5

3. Easy Compare

Compare two files or directories:

# Compare two files
python -m easy_debug.easy_compare file1.pt file2.pt

# Detailed comparison
python -m easy_debug.easy_compare file1.pt file2.pt --detailed

# Compare specific keys in JSON files
python -m easy_debug.easy_compare file1.json file2.json --keys loss accuracy

# Compare two directories
python -m easy_debug.easy_compare --mode=folder --source dir1 --baseline dir2

Configuration

Environment Variables

• ENABLE_EASY_DUMP: Set to "1" to enable dumping (default: "0")
• EASY_DUMP_PATH: Custom subdirectory under logs/ (default: "default")
• EASY_DUMP_ROOT: Root directory for all logs (default: "logs")

.env File

Create a .env file in your project root:

EASY_DUMP_PATH=my_experiment

Directory Structure

Dumps are organized as follows:

logs/
  <EASY_DUMP_PATH>/
    <run_id>/
      step_000100_func_forward_layer1_activation_uuid_a1b2c3.pt
      step_000100_func_backward_gradients_uuid_d4e5f6.json
      ...

Each run gets a unique ID (timestamp-based). Files are named with:

• Training step
• Calling function name
• Custom keys
• Unique UUID

File Format Auto-Detection

Easy Debug automatically selects the appropriate format:

• torch.Tensor → .pt
• numpy.ndarray → .npy
• dict/list with tensors → .pt
• dict/list (JSON-compatible) → .json
• Complex objects → .pkl
• Other types → .txt

Advanced Usage

Custom Run IDs

from easy_debug.easy_dump import set_run_id, reset_run_id

# Set custom run ID
set_run_id("experiment_v1")

# Reset to create new run
reset_run_id()

Custom Value Formatting

def my_formatter(value):
    return f"Custom format: {value}"

easy_dump(data, keys=["test"], value_formatter=my_formatter)

Programmatic Comparison

from easy_debug.easy_compare import compare_values, load_file

val1 = load_file("file1.pt")
val2 = load_file("file2.pt")

equal, message = compare_values(val1, val2, detailed=True)
if equal:
    print("Files are equal!")
else:
    print(f"Differences: {message}")

Examples

See the examples/ directory for complete examples:

• basic_usage.py: Simple dumping and viewing
• training_loop.py: Integration with PyTorch training
• comparison_workflow.py: Comparing experiment results

Requirements

• Python >= 3.8
• PyTorch >= 1.9.0
• NumPy >= 1.19.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Citation

If you use Easy Debug in your research, please cite:

@software{easy_debug,
  title = {Easy Debug: A Debugging Toolkit for PyTorch and ML Workflows},
  author = {Nex-AGI Team},
  year = {2026},
  url = {https://github.com/nex-agi/easy-debug}
}

Acknowledgments

Copyright (c) Nex-AGI. All rights reserved.