This document outlines the complete implementation plan for the Mohawk Inference Engine GUI, building upon the existing SDK foundation. The GUI will provide an intuitive interface for managing multi-device inference sessions, monitoring performance metrics, and configuring secure worker connections.
- Primary Framework: Python + PyQt6 (or Tkinter for lightweight deployment)
- Backend Integration: Existing
mohawk-sdklibrary - Data Visualization: Matplotlib/PyQtGraph for real-time metrics
- Network Communication: WebSocket + REST API integration
- Security: TLS/SSL for GUI-server communication
- Modular Architecture: Separate components for dashboard, configuration, monitoring, and session management
- Responsive UI: Adapts to different screen sizes and device types
- Real-time Updates: WebSocket-based live metrics streaming
- Security First: Encrypted connections, authentication, and secure credential handling
class MohawkGUI(QMainWindow):
"""Main application window with integrated dashboard."""
def __init__(self):
# Layout: Sidebar navigation + Main content area
# Sections:
# - Dashboard Overview (health, metrics summary)
# - Active Sessions (real-time monitoring)
# - Worker Management (add/remove workers)
# - Configuration (settings, credentials)
# - Logs & Events (system and inference logs)Key Features:
- Health status indicators for all workers
- Real-time metrics visualization (latency, throughput, GPU utilization)
- Session lifecycle management (create, monitor, terminate)
- Worker provisioning interface
- Configuration persistence (TOML/JSON)
class ConnectionManager:
"""Manages connections to Mohawk workers."""
async def connect(self, host, port, ssl_context=None):
"""Establish secure connection to worker."""
async def disconnect_all(self):
"""Gracefully close all active connections."""
async def health_check(self):
"""Poll worker health status."""Features:
- Automatic reconnection on failure
- Connection pooling for high-concurrency scenarios
- SSL/TLS certificate validation
- Keep-alive probes
class SessionManager:
"""Manages inference sessions with device mapping."""
def create_session(self, model_path, device_map):
"""Create new session with specified configuration."""
async def monitor_session(self, session_id):
"""Stream real-time metrics for session."""
async def terminate_session(self, session_id):
"""Gracefully stop inference session."""UI Components:
- Session list view (tree widget)
- Session details panel
- Device utilization heatmap
- Throughput charts (requests/sec, tokens/sec)
- Latency distribution histograms
class WorkerManager:
"""Manages worker provisioning and lifecycle."""
async def add_worker(self, host, port, model_spec):
"""Register new worker node."""
async def remove_worker(self, worker_id):
"""Remove worker from cluster."""
async def sync_model(self, worker_id, model_path):
"""Distribute model to worker."""Features:
- Worker status dashboard (online/offline/load)
- Model synchronization progress bars
- Resource utilization monitoring
- Automatic scaling suggestions
class MetricsPanel(QWidget):
"""Real-time metrics visualization."""
def update_metrics(self, metrics_data):
"""Update charts with new data."""
def render_latency_chart(self):
"""Render p50/p95/p99 latency distribution."""
def render_throughput_chart(self):
"""Render throughput over time."""Chart Types:
- Line charts: Throughput trends, latency percentiles
- Heatmaps: Device utilization across workers
- Histograms: Request size distribution
- Gauges: GPU/CPU/memory utilization
- Tables: Detailed metrics with sortable columns
mohawk-gui/
├── mohawk_gui/
│ ├── __init__.py
│ ├── main_window.py # Main application window
│ ├── connection_manager.py # Network layer
│ ├── session_manager.py # Session lifecycle
│ ├── worker_manager.py # Worker management
│ ├── metrics_panel.py # Visualization
│ ├── config_loader.py # TOML/JSON config
│ └── utils/
│ ├── logger.py # Logging infrastructure
│ ├── security.py # TLS/SSL helpers
│ └── tensor_utils.py # Tensor operations
├── resources/
│ ├── icons/ # Application icons
│ └── themes/ # QSS stylesheets
├── tests/
│ ├── test_connection.py
│ ├── test_session.py
│ └── test_metrics.py
└── requirements.txt
# setup_gui.py
def install_dependencies():
"""Install GUI dependencies."""
packages = [
"PyQt6>=6.5.0",
"matplotlib>=3.7.0",
"numpy>=1.24.0",
"pandas>=2.0.0",
"websockets>=11.0"
]
subprocess.check_call([sys.executable, "-m", "pip", "install"] + packages)- Worker connection status indicators
- Latency monitoring (ping tests)
- SSL certificate expiration warnings
- Network topology visualization
class SessionWizard(QWizard):
"""Step-by-step session creation."""
def step1_select_model(self):
"""Choose ONNX/TorchScript model file."""
def step2_configure_devices(self):
"""Select devices and partition strategy."""
def step3_set_batch_params(self):
"""Configure batch size, concurrency."""
def step4_review_and_start(self):
"""Review configuration and launch session."""- WebSocket connection to worker metrics endpoint
- Buffer management for high-frequency updates
- Chart auto-scaling and zoom features
- Export functionality (CSV/PNG)
class AlertManager:
"""Manages system alerts and notifications."""
def register_alert(self, condition, severity):
"""Register alert condition."""
def check_alerts(self):
"""Poll for alert conditions."""Alert Types:
- Worker offline
- Latency threshold exceeded
- Memory pressure warning
- SSL certificate expiry
- Model loading failure
- TOML/JSON config editor
- Credential vault integration
- Environment variable management
- Backup/restore functionality
- TLS certificate management
- Mutual authentication setup
- Session token generation
- Audit logging
- Automated benchmark runs
- Comparative analysis across workers
- Efficiency metrics (tokens/sec/Watt)
- Cost estimation models
- Session summary reports
- Performance trend analysis
- Capacity planning suggestions
- Export to PDF/HTML
# gui/sdk_adapter.py
class SDKAdapter:
"""Bridges MohawkGUI with mohawk-sdk library."""
def __init__(self, host="localhost", port=8003):
self.client = MohawkClient(host=host, port=port)
self.session_counter = 0
async def create_session(self, model_path: str, device_map: dict):
"""Create inference session using SDK."""
with self.client.load_model(model_path) as session:
session_id = f"sess_{self.session_counter}"
return await self.session_manager.create(session_id, session)
async def infer(self, session_id: str, input_tensor):
"""Run inference on session."""
# Delegate to SDK client
pass
async def get_metrics(self, session_id: str):
"""Retrieve metrics for session."""
return await self.client.get_metrics(session_id)# gui/metrics_stream.py
class MetricsStream:
"""WebSocket-based metrics streaming."""
async def connect(self, ws_url):
"""Connect to worker metrics endpoint."""
async def subscribe(self, session_id: str):
"""Subscribe to session metrics."""
async def unsubscribe(self, session_id: str):
"""Unsubscribe from metrics."""
def on_metrics_received(self, metrics):
"""Callback for incoming metrics."""
self.metrics_panel.update(metrics)Metrics Payload Format:
{
"timestamp": 1699900000.123,
"session_id": "sess_abc123",
"metrics": {
"latency_p50_ms": 12.5,
"latency_p95_ms": 45.2,
"latency_p99_ms": 78.9,
"throughput_rps": 1250.0,
"gpu_utilization": 68.5,
"memory_mb": 4096.0,
"active_requests": 32
}
}┌─────────────────────────────────────────────────────────────┐
│ Mohawk Inference Engine │
├──────────┬──────────────────────────────────────────────────┤
│ │ │
│ Sidebar │ Dashboard Content │
│ │ │
│ [Home] │ ┌─────────────────────────────────────────┐ │
│ [Workers]│ │ Health Status: All Systems OK │ │
│ [Sessions]│ ├─────────────────────────────────────────┤ │
│ [Config] │ │ Active Sessions (2) │ │
│ [Logs] │ │ ┌─────────────┐ ┌───────────────────┐ │ │
│ │ │ │ Session A │ │ Session B │ │ │
│ │ │ │ [Monitor] │ │ [Monitor] │ │ │
│ │ │ └─────────────┘ └───────────────────┘ │ │
│ │ └─────────────────────────────────────────┘ │
│ │ │
│ │ ┌─────────────────────────────────────────┐ │
│ │ │ Real-time Metrics │ │
│ │ │ [Throughput Chart] [Latency Chart] │ │
│ │ └─────────────────────────────────────────┘ │
│ │ │
├──────────┴──────────────────────────────────────────────────┤
│ Status Bar: Connected to worker@localhost:8003 | v1.0.0 │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────┐
│ Session: sess_abc123 │
├─────────────────────────────────────────┤
│ Model: model.onnx │
│ Size: 4.2 GB │
│ Devices: GPU[0], GPU[1] │
│ │
│ ┌───────────────────────────────────┐ │
│ │ Throughput (req/sec) │ │
│ │ [██████░░░░] 1,250 │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────┐ │
│ │ Latency Distribution │ │
│ │ p50: 12ms | p95: 45ms | p99: 78ms│ │
│ └───────────────────────────────────┘ │
│ │
│ [Terminate Session] │
└─────────────────────────────────────────┘
[mohawk]
host = "localhost"
port = 8003
ssl_enabled = true
ssl_cert = "certs/client.crt"
ssl_key = "certs/client.key"
[workers]
enabled = true
auto_discover = false
timeout_ms = 5000
[sessions]
max_concurrent = 10
default_batch_size = 32
[metrics]
sampling_rate = 0.1
export_interval_s = 60
[logging]
level = "INFO"
file = "logs/mohawk_gui.log"- Connection manager mock tests
- Session lifecycle tests
- Metrics parsing validation
- Configuration loading tests
- End-to-end session creation
- Worker registration flow
- Metrics streaming verification
- Alert system triggers
- Widget layout verification
- Tooltips and help text
- Keyboard shortcuts
- Theme switching
# pyproject.toml
[build-system]
requires = ["setuptools", "wheel"]
[project]
name = "mohawk-gui"
version = "1.0.0"
dependencies = [
"PyQt6>=6.5.0",
"matplotlib>=3.7.0",
"numpy>=1.24.0",
"mohawk-sdk>=1.0.0",
]
[project.scripts]
mohawk-gui = "mohawk_gui.main:main"FROM python:3.10-slim
WORKDIR /app
COPY mohawk-gui/ ./mohawk-gui/
RUN pip install -r requirements.txt
CMD ["mohawk-gui"]- Mutual TLS authentication for GUI-worker communication
- Credential vault integration (HashiCorp Vault or similar)
- Session token refresh mechanism
- Audit trail for all GUI operations
- Input sanitization to prevent injection attacks
- WebSocket connection pooling for high-concurrency
- Metrics data buffering strategy (avoid memory leaks)
- Chart rendering optimization for large datasets
- Background thread management for non-blocking UI
- Graceful degradation when workers go offline
- Automatic reconnection with exponential backoff
- Session state persistence across GUI restarts
- Rollback mechanism for failed operations
- Lazy loading of charts and visualizations
- Metrics data downsampling for long-term trends
- Efficient memory management for tensor operations
- Parallel model loading for multi-worker setup
- Context-sensitive help system
- Keyboard shortcuts documentation
- Dark/light theme support
- Accessibility compliance (WCAG 2.1)
- Multi-language support (i18n)
- Secure WebSocket connections (TLS 1.3+)
- Session management with proper cleanup
- Real-time metrics visualization
- Worker health monitoring
- Automated benchmarking suite
- Comprehensive error messages
- Configuration backup/restore
- Plugin architecture for extensibility
- REST API for programmatic control
- Web-based alternative (Flask/FastAPI frontend)
- Kubernetes integration (Helm charts)
- Grafana dashboard integration
- Slack/Teams notifications
- Model registry integration
- User guide with screenshots
- API reference documentation
- Troubleshooting FAQ
- Deployment guides (Docker, bare metal)
- Security best practices guide
- Implement comprehensive error handling with user-friendly messages
- Add metrics data buffering to prevent memory issues during long sessions
- Create automated testing suite covering all critical paths
- Document all configuration options with examples
- Implement graceful shutdown procedures
- Add WebSocket connection pooling
- Implement session state persistence
- Create deployment automation scripts
- Build monitoring dashboard for GUI health
- Develop rollback procedures
- Web-based alternative using React/Vue
- Kubernetes operator for cluster management
- MLflow/Weights & Biases integration
- Plugin system for custom metrics
- Multi-tenant support with isolation
The Mohawk Inference Engine GUI provides a comprehensive interface for managing multi-device inference sessions, monitoring performance, and configuring secure worker connections. The implementation plan outlined above addresses all core functionality while identifying critical gaps that must be addressed before production deployment.
Key Success Factors:
- Security-first architecture with proper TLS/SSL implementation
- Robust error handling and recovery mechanisms
- Scalable design for high-concurrency scenarios
- Comprehensive testing coverage
- Clear documentation for users and administrators
The GUI will significantly enhance the usability of the Mohawk Inference Engine, making advanced distributed inference accessible to both technical and non-technical users.