🧠 Neural Activation Monitor for Open WebUI

Real-time neuron firing detection and visualization for neural networks. Monitor sequential activation patterns in transformer models and deep learning architectures with an interactive dashboard.

✨ Features

• 🎯 Real-time Monitoring: Track neuron activations as they happen during inference
• 📊 Interactive Dashboard: Beautiful dark-themed UI with Chart.js visualizations
• 🔗 WebSocket Streaming: Live data updates to frontend (100ms intervals)
• 🎨 Heatmap Visualization: See which neurons are firing in real-time
• 📈 Sequential Detection: Identify patterns in neuron firing sequences
• 🔌 PyTorch Integration: Hook-based activation extraction
• 🚀 Open WebUI Compatible: Works as a custom pipeline plugin
• ⚙️ Configurable: YAML-based settings for thresholds and sampling
• 💾 Lightweight: Minimal overhead (10-30% latency impact)

📦 Installation

Prerequisites

• Python 3.8+
• pip or conda
• PyTorch 2.0+

Quick Start

# Clone the repository
git clone https://github.com/BlackCatte/neural.git
cd neural

# Install dependencies
pip install -r requirements.txt

# Run the test server
python test_server.py

Then open your browser to:

http://localhost:8000/static/dashboard.html

🚀 Usage

Standalone Mode (Development)

python test_server.py

Access:

• Dashboard: http://localhost:8000/static/dashboard.html
• API Status: http://localhost:8000/api/neural-monitor/status
• WebSocket: ws://localhost:8000/api/ws/neural-monitor

Integration with Open WebUI

1. Copy the pipeline plugin:

   docker cp src/neural_monitor_pipeline.py open-webui:/app/backend/pipelines/
   docker restart open-webui

2. Select from dropdown:

   • Open Open WebUI at http://localhost:8080
   • Go to Settings → Pipelines
   • Select "neural_monitor_pipeline" from the dropdown

Python API

from src.neural_monitor_pipeline import Pipeline
import torch

# Initialize pipeline
pipeline = Pipeline()

# Configure
pipeline.valves.activation_threshold = 0.15
pipeline.valves.max_neurons_tracked = 512

# Hook your model
model = torch.nn.Linear(768, 3072)
pipeline.register_activation_hooks(model)

# Run inference
with torch.no_grad():
    x = torch.randn(1, 768)
    output = model(x)

# Get statistics
stats = pipeline.get_activation_summary()
print(stats)

# Cleanup
pipeline.unregister_hooks()

⚙️ Configuration

Edit config.yaml to customize:

monitoring:
  layers: ["output", "hidden", "attention"]
  thresholds:
    activation_threshold: 0.1      # Minimum value to register as "firing"
    downsample_factor: 10          # Reduce data volume
    max_neurons_tracked: 256       # Cap per-layer neurons
  streaming:
    broadcast_interval_ms: 100     # WebSocket update frequency

📊 Dashboard Features

Layer Statistics

Real-time metrics for each monitored layer:

• Active neuron count
• Mean activation value
• Standard deviation

Activation Timeline

Chart showing:

• Mean activation over time
• Number of firing neurons per update

Sequential Firing Patterns

Log of recent neuron firing sequences with:

• Timestamp
• Layer name
• Firing neuron indices
• Mean/max activation values

Neuron Heatmap

Visual grid (256 neurons) showing:

• Green: Currently firing neurons
• Gray: Inactive neurons

🏗️ Architecture

┌─────────────────────────┐
│   Neural Network Model  │
│   (PyTorch/TensorFlow)  │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Forward Hooks (PyTorch) │ ◄── Capture activations
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Activation Extraction   │
│ & Sequence Detection    │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ FastAPI/WebSocket       │ ◄── Stream data
│ Real-time Endpoint      │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│ Browser Dashboard       │ ◄── Visualize
│ (HTML/JS/Chart.js)      │
└─────────────────────────┘

🔧 Performance Tips

• Reduce neurons tracked: Lower max_neurons_tracked for faster updates
• Increase downsample factor: Skip more data points with downsample_factor: 20
• Monitor fewer layers: Specify only critical layers in monitor_layers
• Adjust broadcast interval: Increase broadcast_interval_ms to 200+ if network is saturated

📚 API Reference

Pipeline Class

class Pipeline:
    class Valves:
        enable_monitoring: bool
        monitor_layers: List[str]
        downsample_factor: int
        activation_threshold: float
        max_neurons_tracked: int
    
    def register_activation_hooks(model: torch.nn.Module) -> None
    def get_activation_summary() -> Dict[str, Any]
    def unregister_hooks() -> None

REST Endpoints

GET /api/neural-monitor/status

{
  "timestamp": "2026-05-17T20:01:46.123Z",
  "total_sequences_detected": 1024,
  "layers_monitored": ["layer1", "layer2"],
  "layer_statistics": {
    "layer1": {
      "mean_activation": 0.324,
      "std_activation": 0.156,
      "active_neurons": 128
    }
  }
}

WebSocket Events

Connection → Server sends config event

{
  "type": "config",
  "monitor_layers": ["output"],
  "timestamp": "2026-05-17T20:01:46.123Z"
}

Updates → Server sends activation_update every 100ms

{
  "type": "activation_update",
  "timestamp": "2026-05-17T20:01:46.123Z",
  "sequences_count": 1024,
  "layer_stats": { /* layer statistics */ },
  "recent_firing": [ /* last 10 firing sequences */ ]
}

🔍 Troubleshooting

WebSocket connection refused

• Ensure server is running: python test_server.py
• Check port 8000 is available: lsof -i :8000
• Try different port: Edit test_server.py line (uvicorn.run port parameter)

No data appearing in dashboard

• Wait 5-10 seconds for data to accumulate
• Check browser console for errors (F12)
• Verify WebSocket connection in Network tab
• Check server logs for errors

High latency/memory usage

• Increase downsample_factor to 20 or higher
• Lower max_neurons_tracked to 128
• Reduce monitored layers
• Increase broadcast_interval_ms to 200

ModuleNotFoundError

• Ensure all dependencies installed: pip install -r requirements.txt
• Check Python path includes src/: export PYTHONPATH=$PWD/src:$PYTHONPATH

📖 Examples

Monitor a Transformer Model

from transformers import AutoModel, AutoTokenizer
from src.neural_monitor_pipeline import Pipeline
import torch

# Load model
model = AutoModel.from_pretrained("bert-base-uncased")
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")

# Setup monitor
pipeline = Pipeline()
pipeline.valves.monitor_layers = ["encoder", "attention"]
pipeline.register_activation_hooks(model)

# Run inference
inputs = tokenizer("Hello world!", return_tensors="pt")
with torch.no_grad():
    outputs = model(**inputs)

# View results
print(pipeline.get_activation_summary())

Custom Integration

from fastapi import FastAPI
from src.neural_stream_endpoint import router, setup_neural_monitoring

app = FastAPI()
setup_neural_monitoring(app)

# Your custom endpoints here...

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, port=8000)

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -am 'Add feature'
4. Push to branch: git push origin feature/your-feature
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details

👤 Author

BlackCatte - GitHub

🙏 Acknowledgments

• PyTorch for excellent hooks API
• FastAPI for async WebSocket support
• Chart.js for beautiful visualizations
• Open WebUI for plugin architecture

---

Questions? Open an issue on GitHub! 🚀