Metadata-Version: 2.2
Name: gpumesh
Version: 0.6.4
Summary: Borrow your friends' GPUs: a terminal-based distributed compute mesh in pure Python
License: MIT
Project-URL: Homepage, https://github.com/Samurai007AK/gpumesh
Project-URL: Documentation, https://github.com/Samurai007AK/gpumesh#readme
Project-URL: Repository, https://github.com/Samurai007AK/gpumesh
Project-URL: Issues, https://github.com/Samurai007AK/gpumesh/issues
Keywords: gpu,distributed,compute,mesh,ml,pytorch,cuda
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: gpu
Requires-Dist: torch; extra == "gpu"
Provides-Extra: tunnel
Requires-Dist: pyngrok; extra == "tunnel"
Provides-Extra: sysinfo
Requires-Dist: psutil; extra == "sysinfo"
Provides-Extra: notebook
Requires-Dist: cloudpickle; extra == "notebook"
Requires-Dist: pandas; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: all
Requires-Dist: gpumesh[gpu,notebook,sysinfo,tunnel]; extra == "all"

# gpumesh

Borrow your friends' GPUs. A distributed compute mesh that lets you share GPU power across machines using Python.

[![PyPI version](https://img.shields.io/pypi/v/gpumesh.svg)](https://pypi.org/project/gpumesh/)
[![Python](https://img.shields.io/pypi/pyversions/gpumesh.svg)](https://pypi.org/project/gpumesh/)
[![License](https://img.shields.io/pypi/l/gpumesh.svg)](https://github.com/Samurai007AK/gpumesh/blob/main/LICENSE)

---

## Features

- **Unified GPU pool** — See all connected GPUs as one system
- **One-line setup** — `gpumesh setup` handles everything
- **Auto-discovery** — Workers find coordinators on the same network
- **Smart scheduling** — Fast GPUs get heavy tasks, slow ones get light tasks
- **Fault tolerance** — Dead workers are detected, tasks are re-queued
- **Python API** — Distribute functions from Jupyter notebooks

---

## Installation

```bash
pip install gpumesh
```

Optional extras:

```bash
pip install gpumesh[gpu]       # GPU detection + CUDA benchmarks
pip install gpumesh[tunnel]    # ngrok for public URLs
pip install gpumesh[all]       # everything
```

Requires Python 3.9+.

---

## Quick Start

### 1. Start a coordinator (one machine)

```bash
gpumesh serve --token mySecret
```

### 2. Join a worker (another machine)

```bash
gpumesh join http://192.168.1.10:8000 --token mySecret
```

### 3. Submit a job

```bash
# Set connection (saved automatically after first join)
export GPUMESH_URL=http://192.168.1.10:8000
export GPUMESH_TOKEN=mySecret

# Run a script across all workers
gpumesh submit examples/grid_search.py --payloads examples/payloads.json --wait
```

---

## CLI Commands

| Command | Description |
|---------|-------------|
| `gpumesh setup` | Interactive setup wizard |
| `gpumesh serve` | Start coordinator |
| `gpumesh join URL` | Join as worker |
| `gpumesh submit SCRIPT --payloads FILE` | Submit a job |
| `gpumesh status JOB_ID` | Check job progress |
| `gpumesh cancel JOB_ID` | Cancel a job |
| `gpumesh kill` | Kill all tasks |
| `gpumesh workers` | List connected workers |
| `gpumesh devices` | Show all GPUs as one pool |
| `gpumesh --version` | Show version |

---

## Python API

```python
from gpumesh import GPUMesh

# Connect to coordinator
mesh = GPUMesh("http://192.168.1.10:8000", token="mySecret")

# List workers
mesh.workers()

# Distribute a function across all workers
def train(lr, epochs):
    import os
    device = os.environ.get("GPUMESH_DEVICE", "cpu")
    # Your training code here
    return {"accuracy": 0.95, "lr": lr, "device": device}

results = mesh.distribute(
    function=train,
    params=[
        {"lr": 0.01, "epochs": 100},
        {"lr": 0.05, "epochs": 200},
    ],
)
```

See [full API documentation](https://github.com/Samurai007AK/gpumesh#python-api-jupyter--colab) for Jupyter/Colab examples, closures, and error handling.

---

## Writing Task Scripts

Your script receives parameters on stdin and prints JSON on stdout:

```python
import json, sys, os

payload = json.load(sys.stdin)
device = os.environ.get("GPUMESH_DEVICE", "cpu")

result = {"answer": 42, "device": device}
print(json.dumps(result))
```

---

## Network Options

| Method | Setup | Best for |
|--------|-------|----------|
| **LAN** | None | Same Wi-Fi, fastest |
| **Tailscale** | Install Tailscale | Remote teams |
| **ngrok** | `pip install gpumesh[tunnel]` | Public access |

---

## Limitations

- **Python only** — Tasks must be Python scripts
- **No GPU memory sharing** — Each task gets its own process
- **No model sharding** — Each task runs on one machine
- **Single coordinator** — Single point of failure
- **No persistent storage** — Export results before shutdown

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `command not found` | Use `python -m gpumesh` instead |
| `401 bad token` | Check coordinator and worker tokens match |
| `coordinator unreachable` | Check firewall and that coordinator is running |
| `task timed out` | Increase `--timeout 600` or split into smaller tasks |

---

## Security

- Token authentication on all API requests
- Tokens hashed with SHA-256 before storage
- Rate limiting after 5 failed attempts
- Process isolation for all tasks

**Important:** Workers execute code from the coordinator. Only share your URL and token with people you trust.

---

## Contributing

```bash
git clone https://github.com/Samurai007AK/gpumesh.git
cd gpumesh
pip install -e ".[dev]"
pytest
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

## Links

- **GitHub**: [github.com/Samurai007AK/gpumesh](https://github.com/Samurai007AK/gpumesh)
- **PyPI**: [pypi.org/project/gpumesh](https://pypi.org/project/gpumesh)
- **Issues**: [github.com/Samurai007AK/gpumesh/issues](https://github.com/Samurai007AK/gpumesh/issues)
