rungpu 0.1.0__tar.gz

rungpu-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.3
+Name: rungpu
+Version: 0.1.0
+Summary: Run a Python/ML job on the cheapest suitable GPU without thinking about cloud infrastructure.
+Keywords: gpu,machine-learning,vast-ai,cloud,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: asyncssh>=2.24.0
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: requests>=2.33.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tenacity>=9.1.4
+Requires-Dist: typer>=0.27.2
+Requires-Dist: vastai>=1.7.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# rungpu
+
+Run a Python/ML job on the cheapest suitable GPU without thinking about cloud infrastructure.
+
+```bash
+gpu run "python train.py" --vram 24 --max-price 0.50
+```
+
+That one command finds a GPU, rents it, uploads your project, installs dependencies, streams the
+output, brings your results back and destroys the instance. You never open a cloud console or
+configure SSH.
+
+![A `gpu run` session from search to destroying the instance](docs/demo.gif)
+
+<sub>A replay of a real run, sped up, with two lines of noise removed.</sub>
+
+> **Status: early MVP.** Vast.ai is the only provider. The full flow works on real rented GPUs,
+> but only on demo projects so far. See [Limitations](#limitations).
+
+## Quick start
+
+You need a [Vast.ai](https://vast.ai) account with credit and an
+[API key](https://console.vast.ai/manage-keys/). You pay Vast.ai directly.
+
+rungpu needs Python 3.13. [uv](https://docs.astral.sh/uv/) installs it for you:
+
+```bash
+uv tool install rungpu
+```
+
+With Python 3.13 already installed, `pip install rungpu` works too. The command is `gpu`:
+
+```bash
+export VAST_API_KEY=...          # or put it in a .env file
+gpu search --vram 24 --max-price 0.50
+```
+
+Then, from your project directory:
+
+```bash
+gpu run "python train.py" --vram 24 --max-price 0.50
+```
+
+## Commands
+
+### `gpu search`
+
+Shows matching offers, best value first.
+
+```bash
+gpu search --vram 24 --max-price 0.50 --gpus 1 --limit 10
+```
+
+### `gpu run`
+
+| Option | Meaning | Default |
+|---|---|---|
+| `--vram` | Minimum VRAM per GPU, in GB | 24 |
+| `--max-price` | Maximum $/hour. Without it, you are asked to confirm | none |
+| `--gpus` | Number of GPUs | 1 |
+| `--mode` | What matters most: `cheap`, `balanced` or `fast` | `cheap` |
+| `--disk` | Disk size, in GB | 30 |
+| `--min-reliability` | From 0 to 1 | 0.99 |
+| `--artifacts`, `-a` | Path to bring back. Repeatable | `runs` |
+| `--env`, `-e` | `KEY=VALUE`, or `KEY` to copy it from your shell. Repeatable | none |
+| `--image` | Docker image | `vastai/pytorch` |
+| `--setup` | Replaces the automatic dependency install | detected |
+| `--no-setup` | Skip dependency install | off |
+| `--max-hours` | Stop the command after this long | none |
+| `--yes`, `-y` | Don't ask to confirm the rental | off |
+
+`gpu run` exits with your command's exit code, so it works in scripts. Exit code `3` means an
+instance could not be confirmed destroyed. `130` means it was interrupted.
+
+### Choosing what matters
+
+`--mode` works with `gpu search` and `gpu run`.
+
+| Mode | Picks | Good for |
+|---|---|---|
+| `cheap` | The lowest expected cost of the job, not the lowest hourly price | Long jobs on a budget |
+| `balanced` | A big speed gain for a small extra cost | Most jobs |
+| `fast` | The fastest GPU within `--max-price` | When time matters more than money |
+
+```bash
+gpu run "python train.py" --vram 24 --max-price 1.00 --mode fast
+```
+
+When the choice isn't the best value offer, `gpu run` shows the trade-off:
+
+```text
+vs best value (RTX PRO 4000): about 1.9x faster, about 4% more per job (DLPerf estimate)
+```
+
+This is a rough estimate. Modes compare GPUs using DLPerf, a general benchmark that knows nothing
+about your model, so it can't predict how long your job will take. If your job is limited by its
+disk or CPU, a faster GPU may just sit idle. When one offer is both the fastest and the best
+value, all three modes pick it. Vast's search doesn't return every offer on every call, so the
+choice is the best one seen, not a guaranteed market best.
+
+### `gpu jobs`
+
+Lists recent jobs and warns about instances that are still running.
+
+### `gpu destroy <instance-id>`
+
+For emergencies. `gpu run` destroys instances by itself.
+
+## How your project is handled
+
+**What gets uploaded.** The current directory, except for `.git`, virtual environments, caches,
+everything in `.gitignore`, and secrets: `.env`, `*.pem`, `*.key` and SSH keys.
+
+**Your dataset may be gitignored.** If so, it won't be uploaded and your job won't find it. Add a
+`.gpuignore` file, which uses the `.gitignore` syntax and takes priority:
+
+```gitignore
+!data/
+*.ckpt
+```
+
+**Dependencies** come from `requirements.txt`, or otherwise from `[project].dependencies` in
+`pyproject.toml`.
+
+**Results** are copied into the same relative path locally, overwriting files with the same name.
+They are also downloaded when your command fails, because logs and checkpoints matter most then.
+
+## Safety
+
+The instance is destroyed after an exception, a training crash, an SSH failure or Ctrl+C, including
+an impatient second Ctrl+C. After destroying it, the tool reads it back to confirm. It then looks
+for any other instance carrying the job's label, which catches an instance whose id was lost
+because of an interruption mid-request.
+
+If destruction can't be confirmed, you get a red panel with the exact command to run, and exit code
+3.
+
+If your computer dies, `gpu` can't clean up. So each instance watches for a heartbeat from your
+computer, and destroys itself after 10 minutes of silence, using a key that only works for that
+instance. Your account key never leaves your computer. To change the timeout, set
+`GPU_WATCHDOG_TIMEOUT_SECONDS`, where `0` turns this off.
+
+**Marketplace hosts are third parties.** Whoever owns the machine can technically see your code,
+your data and any variables you pass with `--env`. Don't run anything there that you couldn't show
+them. Prefer `--env` over uploading `.env`, and scoped tokens over personal ones. Output is masked
+for `--env` values and common token formats, but this is best effort.
+
+## Limitations
+
+- **The dead-man switch has a limit.** After `kill -9`, a power cut or a lost network, the instance
+  destroys itself after 10 minutes without a heartbeat. If the instance never finishes starting,
+  the switch can't run, so check `gpu jobs` after a crash. If it can't arm itself, you get a warning.
+- **Don't let your laptop sleep during a job.** A sleeping computer sends no heartbeats, so the
+  instance is destroyed.
+- **A network outage of more than about 3 minutes ends the job,** because the command runs inside
+  the SSH session. Reconnection is planned.
+- **The cost shown excludes traffic and storage during startup.** Traffic prices vary by a factor
+  of about 15 between hosts. On a first real job, the final charge was about 2.5 times the estimate.
+- DLPerf is a proxy. It doesn't know your workload, so `--mode` ranks GPUs but can't predict
+  your job's runtime or cost. A lone offer for its GPU model can't be checked for an inflated
+  benchmark, which matters most with `--mode fast`.
+- On-demand instances on a single node only.
+
+## Development
+
+```bash
+git clone https://github.com/MikhailSeliakov/rungpu.git
+uv sync
+uv run pytest                    # Unit tests. Never touches the network.
+uv run ruff check .
+uv run pytest -m integration     # Real Vast API. Free and read-only.
+```
+
+The end-to-end test **rents a real GPU** and needs a second, explicit switch:
+
+```bash
+GPU_E2E_ALLOW_SPEND=1 uv run pytest -m e2e
+```

rungpu-0.1.0/README.md

@@ -0,0 +1,178 @@
+# rungpu
+
+Run a Python/ML job on the cheapest suitable GPU without thinking about cloud infrastructure.
+
+```bash
+gpu run "python train.py" --vram 24 --max-price 0.50
+```
+
+That one command finds a GPU, rents it, uploads your project, installs dependencies, streams the
+output, brings your results back and destroys the instance. You never open a cloud console or
+configure SSH.
+
+![A `gpu run` session from search to destroying the instance](docs/demo.gif)
+
+<sub>A replay of a real run, sped up, with two lines of noise removed.</sub>
+
+> **Status: early MVP.** Vast.ai is the only provider. The full flow works on real rented GPUs,
+> but only on demo projects so far. See [Limitations](#limitations).
+
+## Quick start
+
+You need a [Vast.ai](https://vast.ai) account with credit and an
+[API key](https://console.vast.ai/manage-keys/). You pay Vast.ai directly.
+
+rungpu needs Python 3.13. [uv](https://docs.astral.sh/uv/) installs it for you:
+
+```bash
+uv tool install rungpu
+```
+
+With Python 3.13 already installed, `pip install rungpu` works too. The command is `gpu`:
+
+```bash
+export VAST_API_KEY=...          # or put it in a .env file
+gpu search --vram 24 --max-price 0.50
+```
+
+Then, from your project directory:
+
+```bash
+gpu run "python train.py" --vram 24 --max-price 0.50
+```
+
+## Commands
+
+### `gpu search`
+
+Shows matching offers, best value first.
+
+```bash
+gpu search --vram 24 --max-price 0.50 --gpus 1 --limit 10
+```
+
+### `gpu run`
+
+| Option | Meaning | Default |
+|---|---|---|
+| `--vram` | Minimum VRAM per GPU, in GB | 24 |
+| `--max-price` | Maximum $/hour. Without it, you are asked to confirm | none |
+| `--gpus` | Number of GPUs | 1 |
+| `--mode` | What matters most: `cheap`, `balanced` or `fast` | `cheap` |
+| `--disk` | Disk size, in GB | 30 |
+| `--min-reliability` | From 0 to 1 | 0.99 |
+| `--artifacts`, `-a` | Path to bring back. Repeatable | `runs` |
+| `--env`, `-e` | `KEY=VALUE`, or `KEY` to copy it from your shell. Repeatable | none |
+| `--image` | Docker image | `vastai/pytorch` |
+| `--setup` | Replaces the automatic dependency install | detected |
+| `--no-setup` | Skip dependency install | off |
+| `--max-hours` | Stop the command after this long | none |
+| `--yes`, `-y` | Don't ask to confirm the rental | off |
+
+`gpu run` exits with your command's exit code, so it works in scripts. Exit code `3` means an
+instance could not be confirmed destroyed. `130` means it was interrupted.
+
+### Choosing what matters
+
+`--mode` works with `gpu search` and `gpu run`.
+
+| Mode | Picks | Good for |
+|---|---|---|
+| `cheap` | The lowest expected cost of the job, not the lowest hourly price | Long jobs on a budget |
+| `balanced` | A big speed gain for a small extra cost | Most jobs |
+| `fast` | The fastest GPU within `--max-price` | When time matters more than money |
+
+```bash
+gpu run "python train.py" --vram 24 --max-price 1.00 --mode fast
+```
+
+When the choice isn't the best value offer, `gpu run` shows the trade-off:
+
+```text
+vs best value (RTX PRO 4000): about 1.9x faster, about 4% more per job (DLPerf estimate)
+```
+
+This is a rough estimate. Modes compare GPUs using DLPerf, a general benchmark that knows nothing
+about your model, so it can't predict how long your job will take. If your job is limited by its
+disk or CPU, a faster GPU may just sit idle. When one offer is both the fastest and the best
+value, all three modes pick it. Vast's search doesn't return every offer on every call, so the
+choice is the best one seen, not a guaranteed market best.
+
+### `gpu jobs`
+
+Lists recent jobs and warns about instances that are still running.
+
+### `gpu destroy <instance-id>`
+
+For emergencies. `gpu run` destroys instances by itself.
+
+## How your project is handled
+
+**What gets uploaded.** The current directory, except for `.git`, virtual environments, caches,
+everything in `.gitignore`, and secrets: `.env`, `*.pem`, `*.key` and SSH keys.
+
+**Your dataset may be gitignored.** If so, it won't be uploaded and your job won't find it. Add a
+`.gpuignore` file, which uses the `.gitignore` syntax and takes priority:
+
+```gitignore
+!data/
+*.ckpt
+```
+
+**Dependencies** come from `requirements.txt`, or otherwise from `[project].dependencies` in
+`pyproject.toml`.
+
+**Results** are copied into the same relative path locally, overwriting files with the same name.
+They are also downloaded when your command fails, because logs and checkpoints matter most then.
+
+## Safety
+
+The instance is destroyed after an exception, a training crash, an SSH failure or Ctrl+C, including
+an impatient second Ctrl+C. After destroying it, the tool reads it back to confirm. It then looks
+for any other instance carrying the job's label, which catches an instance whose id was lost
+because of an interruption mid-request.
+
+If destruction can't be confirmed, you get a red panel with the exact command to run, and exit code
+3.
+
+If your computer dies, `gpu` can't clean up. So each instance watches for a heartbeat from your
+computer, and destroys itself after 10 minutes of silence, using a key that only works for that
+instance. Your account key never leaves your computer. To change the timeout, set
+`GPU_WATCHDOG_TIMEOUT_SECONDS`, where `0` turns this off.
+
+**Marketplace hosts are third parties.** Whoever owns the machine can technically see your code,
+your data and any variables you pass with `--env`. Don't run anything there that you couldn't show
+them. Prefer `--env` over uploading `.env`, and scoped tokens over personal ones. Output is masked
+for `--env` values and common token formats, but this is best effort.
+
+## Limitations
+
+- **The dead-man switch has a limit.** After `kill -9`, a power cut or a lost network, the instance
+  destroys itself after 10 minutes without a heartbeat. If the instance never finishes starting,
+  the switch can't run, so check `gpu jobs` after a crash. If it can't arm itself, you get a warning.
+- **Don't let your laptop sleep during a job.** A sleeping computer sends no heartbeats, so the
+  instance is destroyed.
+- **A network outage of more than about 3 minutes ends the job,** because the command runs inside
+  the SSH session. Reconnection is planned.
+- **The cost shown excludes traffic and storage during startup.** Traffic prices vary by a factor
+  of about 15 between hosts. On a first real job, the final charge was about 2.5 times the estimate.
+- DLPerf is a proxy. It doesn't know your workload, so `--mode` ranks GPUs but can't predict
+  your job's runtime or cost. A lone offer for its GPU model can't be checked for an inflated
+  benchmark, which matters most with `--mode fast`.
+- On-demand instances on a single node only.
+
+## Development
+
+```bash
+git clone https://github.com/MikhailSeliakov/rungpu.git
+uv sync
+uv run pytest                    # Unit tests. Never touches the network.
+uv run ruff check .
+uv run pytest -m integration     # Real Vast API. Free and read-only.
+```
+
+The end-to-end test **rents a real GPU** and needs a second, explicit switch:
+
+```bash
+GPU_E2E_ALLOW_SPEND=1 uv run pytest -m e2e
+```

rungpu-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "rungpu"
+version = "0.1.0"
+description = "Run a Python/ML job on the cheapest suitable GPU without thinking about cloud infrastructure."
+readme = "README.md"
+requires-python = ">=3.13"
+keywords = [
+    "gpu",
+    "machine-learning",
+    "vast-ai",
+    "cloud",
+    "cli",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "asyncssh>=2.24.0",
+    "pathspec>=0.12.1",
+    "pydantic>=2.13.5",
+    "pydantic-settings>=2.6.0",
+    "requests>=2.33.0",
+    "rich>=15.0.0",
+    "tenacity>=9.1.4",
+    "typer>=0.27.2",
+    "vastai>=1.7.0",
+]
+
+[project.scripts]
+gpu = "gpu.cli.app:main"
+
+[dependency-groups]
+dev = [
+    "black>=26.5.1",
+    "pytest>=8.3.0",
+    "ruff>=0.16.7",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "gpu"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not integration and not e2e' --strict-markers"
+markers = [
+    "integration: free read-only calls to the real provider API (pytest -m integration)",
+    "e2e: rents a real, paid instance; also requires GPU_E2E_ALLOW_SPEND=1 (pytest -m e2e)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "S",
+    "SIM",
+    "RUF",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "S104",
+    "S105",
+    "S106",
+    "S108",
+]

rungpu-0.1.0/pyproject.toml.orig

@@ -0,0 +1,61 @@
+[project]
+name = "rungpu"
+version = "0.1.0"
+description = "Run a Python/ML job on the cheapest suitable GPU without thinking about cloud infrastructure."
+readme = "README.md"
+requires-python = ">=3.13"
+keywords = ["gpu", "machine-learning", "vast-ai", "cloud", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "asyncssh>=2.24.0",
+    "pathspec>=0.12.1",
+    "pydantic>=2.13.5",
+    "pydantic-settings>=2.6.0",
+    "requests>=2.33.0",
+    "rich>=15.0.0",
+    "tenacity>=9.1.4",
+    "typer>=0.27.2",
+    "vastai>=1.7.0",
+]
+
+[project.scripts]
+gpu = "gpu.cli.app:main"
+
+[dependency-groups]
+dev = [
+    "black>=26.5.1",
+    "pytest>=8.3.0",
+    "ruff>=0.16.7",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "gpu"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not integration and not e2e' --strict-markers"
+markers = [
+    "integration: free read-only calls to the real provider API (pytest -m integration)",
+    "e2e: rents a real, paid instance; also requires GPU_E2E_ALLOW_SPEND=1 (pytest -m e2e)",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "S", "SIM", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S104", "S105", "S106", "S108"]