VisualTorch

VisualTorch is a tool designed to visualize PyTorch neural network architectures. It supports generating several visual styles, including:

• flow: Flow-style architectures.
• graph: Graph-style architectures.
• lenet: LeNet-style architectures.

It works with both nn.Sequential and custom PyTorch models by tracing a real forward pass.

Important Limitations:

• Data-dependent control flow: Because it uses tracing, models with branches that depend on tensor values (e.g., if x > 0:) will only visualize the path taken by the specific dummy input used during the trace.
• Multiple outputs: For layers returning multiple tensors (like nn.LSTM), the node size is based on the first tensor. However, if show_dimension=True is used, the labels will display the shapes of all output tensors.

VisualTorch is a tool for visualizing Torch-based neural network architectures. It supports generating three main visualization styles:

• Flow-style architectures
• Graph-style architectures
• LeNet-style architectures

It works with both torch.nn.Sequential and custom PyTorch models. To begin using the library, you can follow the installation guide or explore usage examples for specific styles.

⚠️ Critical Security Notice

VisualTorch executes the provided source and model_expression as Python code. The worker subprocess is a reliability boundary, not a security sandbox.

Supplied code can:

• Read or modify files.
• Access the network.
• Start new processes.
• Use the current user's permissions.

Best Practices:

1. Only connect to MCP hosts you trust.
2. Review tool arguments before approving execution.
3. For high-security environments, run the MCP server inside a container, virtual machine, or a dedicated OS account with restricted access.

Once dependencies are installed, you can generate the HTML version of the documentation using the sphinx-build command. This command takes the source directory as input and outputs the built files into the build directory.

sphinx-build -b html source build

If you want to use the latest development version from the GitHub repository, install directly from the source.

git clone https://github.com/willyfh/visualtorch.git
cd visualtorch
pip install .

To set up the environment for building the VisualTorch documentation, install the required dependencies using pip from the requirements.txt file. This project uses sphinx-design and myst-parser for its documentation structure.

pip install -r requirements.txt

To report a bug or request a new feature in VisualTorch, use GitHub Issues. Before creating a new issue, search existing issues to avoid duplication.

• Bugs/Features: Create a new issue
• Discussions: For asking questions or proposing ideas, use GitHub Discussions.

Versions 1.0+ contain major breaking API changes. If your existing codebase relies on the old API, you must install version 0.2.5 or older. Documentation for the legacy version is hosted separately at https://visualtorch.readthedocs.io/en/v0.2.5/.

pip install visualtorch==0.2.5

To contribute to VisualTorch, set up a local development environment using Conda. This involves creating a dedicated environment, installing the package in editable mode with development dependencies, and configuring pre-commit hooks for automated code quality checks.

Environment Setup Steps

1. Create and activate a Conda environment:

   conda create -n visualtorch_env python=3.10
   conda activate visualtorch_env

2. Install development requirements: Install the package in editable mode including the [dev] extra:

   pip install -e .[dev]

3. Install pre-commit hooks:

   pre-commit install

Register visualtorch-mcp as a stdio server in your MCP host configuration.

If the script is on your PATH:

{
  "mcpServers": {
    "visualtorch": {
      "command": "visualtorch-mcp"
    }
  }
}

If the script is NOT on your PATH: You must use the absolute path to your Python interpreter and run the module via -m visualtorch_mcp.

{
  "mcpServers": {
    "visualtorch": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "visualtorch_mcp"]
    }
  }
}

Note: On Windows, the interpreter path typically ends in Scripts/python.exe; on POSIX, it ends in bin/python.