HwPilot — Hardware-aware ML Environment Setup & Compatibility Manager

HwPilot — Hardware-aware ML environment setup and compatibility manager.

Detect my hardware. Resolve the correct ML environment. Ask me once. Install it safely. Verify that it actually works.

---

👨‍💻 Created & Maintained By

Rudraksh Rakesh Zodage
AI / Machine Learning Engineer & Developer

• Email: rudrakshrakeshzodage@gmail.com
• GitHub: github.com/RudrakshRakeshZodage
• LinkedIn: linkedin.com/in/rudraksh-zodage-
• HuggingFace: huggingface.co/rudrakshrakeshzodage

---

💡 What is HwPilot?

HwPilot is a hardware-aware machine learning environment setup and compatibility manager created by Rudraksh Rakesh Zodage. It automatically inspects a computer's CPU, GPU, NVIDIA driver, operating system, and Python runtime to dynamically resolve, install, and verify a fully compatible PyTorch/CUDA ML software stack inside an isolated virtual environment.

Why HwPilot?

Running the same ML codebase across different machines (laptops, workstation rigs, cloud nodes) often leads to broken CUDA drivers, incompatible PyTorch wheels, or runtime kernel crashes. Manually matching NVIDIA driver minimum version matrices with PyTorch CUDA runtime builds is complex and error-prone.

HwPilot replaces manual trial-and-error with an automated, hardware-aware compatibility resolver:

• Zero Hardcoded Hardware Strings: Dynamically matches driver compute capabilities.
• Isolated Environments: Installs packages in dedicated virtual environments (./hwpilot-env).
• Safety Guarantee: Never modifies system drivers or global packages silently.
• Real GPU Verification: Performs real tensor operations on GPU to verify compute capability before declaring success.

---

⚡ Quick Start

Installation

pip install hwpilot

Basic Workflow

# 1. Inspect hardware and system specs
hwpilot detect

# 2. Check if current machine is suitable for ML workloads
hwpilot check

# 3. Preview resolved compatibility & installation plan
hwpilot plan

# 4. Execute setup (detect, resolve, confirm, install & verify)
hwpilot setup

# 5. Verify runtime environment capability
hwpilot verify

Automation / CI Mode

hwpilot setup --yes --path ./my-ml-env

---

🚀 Key Commands & CLI Reference

Command	Description
hwpilot detect	Inspect hardware (CPU, GPU, VRAM, Compute Capability, Driver, OS, Python).
hwpilot check	Evaluate whether the machine meets requirements for ML workloads.
hwpilot plan	Preview compatibility resolution and package specs without modifying system.
hwpilot setup	Complete end-to-end setup workflow (detect → resolve → confirm → venv → install → verify → manifest).
hwpilot verify	Perform real GPU matrix multiplication tensor test in an existing environment.
hwpilot doctor	Generate a comprehensive diagnostic and troubleshooting report.
hwpilot update	Refresh cached compatibility metadata from remote index.
hwpilot info	Display HwPilot version, author profiles, and metadata information.

Command Flags

• --pytorch <VER> / --torch <VER>: Suggest specific PyTorch framework version (e.g. 2.4.1, 2.3.1).
• --cuda <VER>: Suggest specific CUDA runtime build version (e.g. 12.4, 12.1, 11.8, cpu).
• --json: Output machine-readable JSON format for programmatic use.
• -y, --yes: Bypass interactive confirmation prompt.
• -p, --path <DIR>: Custom target environment path (default: ./hwpilot-env).
• --global: Install directly into current Python environment (requires explicit opt-in).
• -v, --verbose: Enable debug logging.

---

🛡️ Safety & Security Principles

1. Driver Integrity: HwPilot never modifies or replaces system graphics drivers.
2. Environment Isolation: Prefers isolated project environments (./hwpilot-env).
3. No Guessing: Uses strict declarative compatibility matrices.
4. Empirical Verification: Verifies GPU runtime with actual tensor operations.

---

📁 Environment Manifest Structure

Upon successful setup, HwPilot generates an environment audit manifest:

hwpilot-env/
├── config/
│   ├── hardware.json      # Hardware specs (CPU, GPU, Driver)
│   └── environment.json   # Resolved backend, CUDA runtime, framework versions
├── logs/
│   └── install.log        # Package installation transcript
└── manifest.json          # Environment state & verification results

---

🧪 Testing & Development

git clone https://github.com/RudrakshRakeshZodage/hwpilot.git
cd hwpilot
pip install -e .[dev]
pytest

---

📦 PyPI Publishing

pip install build twine
python -m build
twine check dist/*
twine upload dist/*

🤝 Contributing

Contributions to HwPilot are welcome! Whether you are reporting a bug, adding hardware compatibility rules, or improving documentation, please read our CONTRIBUTING.md guide.

Quick Workflow for Contributors

1. Fork and clone the repository: git clone https://github.com/RudrakshRakeshZodage/hwpilot.git
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Install development dependencies: pip install -e .[dev]
4. Ensure test suite passes: pytest
5. Open a Pull Request on GitHub.

---

👤 Author & Maintainer Profile

Created, architected, and maintained by Rudraksh Rakesh Zodage.

• Email: rudrakshrakeshzodage@gmail.com
• GitHub: github.com/RudrakshRakeshZodage
• LinkedIn: linkedin.com/in/rudraksh-zodage-
• HuggingFace: huggingface.co/rudrakshrakeshzodage

---

📜 License & Copyright

This project is licensed under the terms of the MIT License.

Copyright (c) 2026 Rudraksh Rakesh Zodage

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

For full license details, see the LICENSE file.