MAV - Model Activity Visualiser

Visualize the internal workings of Large Language Models as they generate text

🚀 Getting Started

Method 1: Using uv (Recommended)

# Run with PyPI package
uv run --with openmav mav

# Or run directly from GitHub
uv run --with git+https://github.com/attentionmech/mav mav --model gpt2 --prompt "hello mello"

Note: You can replace gpt2 with any other Hugging Face model compatible with transformers:

• HuggingFaceTB/SmolLM-135M
• gpt2-medium
• gpt2-large
• meta-llama/Llama-3.2-1B

For gated repos, ensure you have done huggingface-cli login and your environment has access to it.

Method 2: Using pip

1. Set up and activate a virtual environment
2. Install the package:

   # From PyPI
   pip install openmav
   
   # Or from GitHub
   pip install git+https://github.com/attentionmech/mav
   

3. Run the visualizer:

   mav --model gpt2 --prompt "hello mello"
   

4. Or import in your code:

   from openmav.mav import MAV
   MAV("gpt2", "Hello")
   

Method 3: Local Development

1. Clone the repository:

   git clone https://github.com/attentionmech/mav
   cd mav
   

2. Set up and activate a virtual environment
3. Install in development mode:

   pip install .
   

4. Run the visualizer:

   mav --model gpt2 --prompt "hello mello"
   

Method 4: Jupyter Notebook/Colab

📚 Documentation & Tutorials

Documentation

Check out the documentation.md file for detailed information.

Tutorials

Custom Plugin Development

Advanced Usage Examples

# Run MAV with a training loop and custom model
uv run examples/test_vis_train_loop.py

# Run with custom panel configuration
uv run --with git+https://github.com/attentionmech/mav mav \
  --model gpt2 \
  --num-grid-rows 3 \
  --selected-panels generated_text attention_entropy top_predictions \
  --max-bar-length 20 \
  --refresh-rate 0 \
  --max-new-tokens 10000

🎥 Demos

• Basic plugins
• Interactive mode
• Limit characters
• Sample with temperature
• Running with custom model
• Panel selection
• Running in Colab notebook

Note: Explore additional options using the command line help, as many sampling parameters are exposed.

👥 Contributing

Clone the repository and install the package in development mode:

git clone https://github.com/attentionmech/mav
cd mav

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

📝 Citation

@article{attentionmech2025openmav,
  title={OpenMAV: Model Activity Visualiser},
  author={attentionmech},
  year={2025}
}

🧠 Trivia

This project started from a small tweet while testing a simple terminal ui loop: tweet

⭐ Star History