gipper 0.3.0__py3-none-any.whl

gipper-0.3.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: gipper
+Version: 0.3.0
+Summary: Run GPU jobs across cloud markets with cost estimates, verified teardown, and an append-only ledger
+Author: Marc Lavallee
+License-Expression: MIT
+Project-URL: Homepage, https://lavallee.github.io/gipper/
+Project-URL: Documentation, https://lavallee.github.io/gipper/guides/quickstart.html
+Project-URL: Repository, https://github.com/lavallee/gipper
+Project-URL: Issues, https://github.com/lavallee/gipper/issues
+Project-URL: Changelog, https://github.com/lavallee/gipper/blob/main/CHANGELOG.md
+Keywords: gpu,runpod,vast,cloud,batch
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# gipper
+
+[Website](https://lavallee.github.io/gipper/) · [Quickstart](https://lavallee.github.io/gipper/guides/quickstart.html) · [Python API](https://lavallee.github.io/gipper/guides/clients.html)
+
+gipper runs jobs on rented NVIDIA GPUs. Describe the hardware, command, input
+files, outputs, and budget in a TOML file; gipper compares cloud offers, rents a
+machine, checks it, runs the job, collects results, and verifies teardown.
+
+Use it for model training and fine-tuning, batch inference, rendering, or other
+GPU workloads that run from a Linux shell. Your job supplies its own software
+and dependencies. The same CLI and Python API work across Runpod and Vast.ai.
+
+Placement considers the whole job: startup, setup, transfers, compute, bandwidth
+fees, and host failures. An append-only local ledger records runs and costs;
+future estimates learn from **your own** workloads and provider history. A fresh
+installation starts with stated defaults, not someone else's rental history.
+
+**Status: 0.3.0, alpha.** Linux client, CLI and Python API, no daemon. Runpod and
+Vast have live-run validation; Shadeform is experimental and has not had a live
+smoke test. See the [roadmap](ROADMAP.md) for planned features and
+[SECURITY.md](SECURITY.md) for trust and billing limits. Licensed under [MIT](LICENSE).
+
+## Install
+
+Requires Linux, Python 3.12+, OpenSSH (`ssh`, `ssh-keygen`), and `tar` with
+gzip support. `ping` is optional for interactive placement. The Python runtime
+has no third-party dependencies. Remote machines need a Linux shell, `tar`,
+`timeout`, `curl`, and NVIDIA tools; the bootstrap installs `uv` if needed.
+
+Install from source (no PyPI release is assumed):
+
+```sh
+git clone https://github.com/lavallee/gipper.git
+cd gipper
+uv tool install .
+gipper --help
+```
+
+Use `pip install .` in a virtual environment if you do not use `uv`.
+For development, use `uv sync --extra test` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
+
+Configure only the providers you intend to use:
+
+```sh
+mkdir -p ~/.config/gipper
+(umask 077; cp -n .env.example ~/.config/gipper/.env)
+chmod 600 ~/.config/gipper/.env
+# Edit ~/.config/gipper/.env to add your provider keys.
+```
+
+Keys can also come from environment variables: `RUNPOD_API_KEY`, `VAST_API_KEY`,
+`SHADEFORM_API_KEY`. Environment variables take precedence. `GIPPER_ENV` selects
+an exclusive dotenv file; otherwise the user-config dotenv overrides the legacy
+checkout `.env`. A provider without a key is skipped when renting. Keys travel
+in API request headers and are scrubbed from receipts and API error bodies.
+Machines get gipper's own SSH key (`~/.config/gipper/id_ed25519`).
+
+Check estimates before paying for a smoke run:
+
+```sh
+gipper pod estimate examples/smoke.toml --provider vast
+gipper pod run examples/smoke.toml --provider vast --dry-run
+# The following command spends money:
+gipper pod run examples/smoke.toml --provider vast
+gipper pod ls
+```
+
+A dry run contacts provider APIs but does not rent. Set provider-side spending
+alerts too: estimates and client-side caps cannot guarantee a final bill.
+
+Install the cleanup timer on the machine that runs jobs (recommended):
+
+```sh
+mkdir -p ~/.config/systemd/user
+cp deploy/gipper-reap.* ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now gipper-reap.timer
+systemctl --user list-timers gipper-reap.timer
+```
+
+The service expects `~/.local/bin/gipper`; adjust `ExecStart` if installed
+elsewhere. A service cannot see keys exported only in an interactive shell; use
+the user-config dotenv above. User timers require a running user manager. If
+jobs must outlive logout, configure user lingering or an equivalent scheduler.
+See [SECURITY.md](SECURITY.md) for host trust and cleanup limitations.
+
+### Local configuration and data
+
+| Path / override | Purpose |
+|---|---|
+| `~/.config/gipper/config.toml` / `GIPPER_CONFIG` | Settings such as `daily_cap_usd = 5.0`; see [`config.DEFAULTS`](gipper/config.py) |
+| `.env` beside the config file / `GIPPER_ENV` | Provider keys (simple `NAME=value`, no shell expansion) |
+| `~/.config/gipper/` / `GIPPER_KEYS` | SSH key directory |
+| `~/.local/share/gipper/` / `GIPPER_DATA` | Append-only receipts used for history and spend |
+
+Keep the ledger on durable storage and restrict access to it. Separate installs
+sharing a provider account should coordinate: the reaper owns the `gipper-*`
+namespace, not just the machines in one local ledger.
+
+## Use
+
+```
+gipper pod gpus --min-mem 24 --region US,CA [--udp]   # what's on offer, scored for a 30-minute job
+gipper pod estimate job.toml                          # how long and how much, offer by offer
+gipper pod run job.toml [--dry-run] [--provider vast] [--gpu "RTX 4090"]
+gipper pod hosts                                      # what gipper has learned about providers and machines
+gipper pod cost [--since 2026-10-27]                  # per job: computed and billed
+gipper pod ls | reap [--dry-run] | reconcile | account
+gipper ledger [--since ...] [--job ID]                # raw receipts
+```
+
+A job ([`examples/smoke.toml`](examples/smoke.toml); every field in
+[`gipper/job.py`](gipper/job.py) and [`gipper/placement.py`](gipper/placement.py)):
+
+```toml
+name = "my-gpu-job"
+workload = "my-workload"          # jobs with the same workload share a memory of compute times
+
+[gpu]
+min_mem_gb = 24
+prefer = ["RTX 4090", "RTX A6000"]    # in order; names match across providers
+regions = ["US", "CA"]                # ISO country codes; default anywhere
+providers = ["vast", "runpod"]        # default: every provider with a key
+
+[pod]
+ports = ["5004/udp"]                  # published; UDP rules out Runpod
+
+[[inputs]]
+src = "~/gpu-project"
+dst = "project"
+exclude = [".git", "runs"]
+
+[[outputs]]
+src = "out"
+dst = "~/gpu-project/runs/x/out"
+
+[run]
+command = "python project/main.py"
+checkpoint = { src = "out", every_s = 300 }
+
+[budget]
+max_usd = 1.0
+max_hours = 2.0
+
+[placement]                           # optional, and better than memory's guess
+compute_s = 900
+setup_download_gb = 5                 # weights and wheels the job fetches itself
+```
+
+## How gipper chooses
+
+Every offer is judged on the whole run, not its hourly price
+([docs/placement.md](docs/placement.md) has the details):
+
+- **Time:** machine ready + setup + upload + the job's own downloads + compute +
+  output download. Each figure comes from the job's `[placement]` hints, from
+  memory, from what the provider advertises (Vast publishes host link speeds),
+  or from a stated default, and `estimate` says which.
+- **Dollars:** rental for that time, plus Vast's bandwidth fees, times what this
+  provider has billed compared with rate × lifetime in your ledger. Without
+  qualifying history, the billing factor is 1.0; storage and rounding can make
+  the final bill differ.
+- **Risk:** the chance the host turns out bad, from memory: the machine's own
+  record, pulled towards its provider's, pulled towards 10% for a stranger.
+  A failure costs `failure_cost_usd` ($1) plus the time and rent it wastes.
+- **Score** = dollars + risk + waiting, with an hour of waiting worth
+  `hour_value_usd` ($3).
+
+For short jobs, startup time and the cost of a failed host can outweigh a lower
+hourly price. For long jobs, the hourly rate has more influence. Provider names
+do not determine the winner: the ranking follows the job and available history.
+`prefer` comes first, and an offer whose expected cost exceeds `max_usd` is
+left out. `[placement] objective = "cost"` removes the value of waiting while
+still pricing failures; `"time"` values waiting at $50/h. For latency-sensitive
+services, `profile = "interactive"` probes candidate hosts and ranks by round
+trip first. Batch jobs account for transfer time without preferring nearby hosts.
+
+Memory is the ledger itself. A rental is *good* once its job started, and *bad*
+if the host was broken (busy GPU, CUDA that won't initialise, ssh that never came
+up, a failed probe) or the connection was lost. A host that works but doesn't
+suit the job (`run.Unsuitable`), a job that fails on a working host, and an
+error on this side count against nobody.
+
+## Run lifecycle and safeguards
+
+- **The machine is given back, and gipper checks.** Teardown runs in `finally`
+  after success, failure, Ctrl-C or a cap, and counts as done only when the
+  provider stops listing the machine. Until then it stays
+  `pod.termination_pending`, gipper rents no replacement, and the reaper (every
+  15 minutes) retries it first. The reaper also ends any `gipper-*` machine the
+  ledger forgot or that passed its deadline, on every provider. The job runs
+  detached under `timeout max_hours`. This limits the command, not the rental;
+  the reaper must still terminate a machine if the client dies.
+- **Hosts are checked before anything is uploaded:** the GPU is idle,
+  `cuInit` succeeds (with one retry without CUDA forward-compat libraries on
+  error 804), the compute capability meets the job's floor, and optionally a
+  measured transfer probe passes. A bad host is replaced, up to 3 times.
+- **Caps:** per job (`max_usd`, `max_hours`, `[gpu] max_usd_per_h`) and per day
+  (`daily_cap_usd` in `~/.config/gipper/config.toml`, default $5). Daily spend
+  uses providers' bills where reconciled.
+- **Outputs** sync down every `checkpoint.every_s` and are salvaged on failure.
+- **Environment:** each provider's default image unless `[pod] image` says
+  otherwise. Each job sources a bootstrap providing `uv` and
+  `GIPPER_TORCH_INDEX`, the PyTorch wheel index for the host's driver. Published
+  ports arrive as `GIPPER_PUBLIC_IP` and `GIPPER_PORT_<n>_<PROTO>` (the outside
+  port, which on Vast differs from the inside one).
+
+## Markets
+
+| | Runpod | Vast.ai | Shadeform (unused) |
+|---|---|---|---|
+| You rent | container, root | container on someone's machine, root | VM on one of 30+ clouds, user `shadeform` |
+| Good for | secure cloud, network volumes | consumer GPUs everywhere, cheap, UDP | datacenter cards with one bill |
+| Ports | TCP/HTTP, **no UDP** | TCP and UDP, random outside port | TCP and UDP (UFW; the cloud may filter) |
+| Bills | per pod per day | itemised: GPU, disk, bandwidth | no billing API |
+
+An RTC job that must stay on Runpod can relay media through Cloudflare's TURN
+over TCP/TLS on 443, at some latency cost.
+
+## Python API
+
+The CLI is the simplest surface. From Python (gipper is stdlib-only):
+
+```python
+from gipper import run, ledger
+from gipper.job import load
+from gipper.providers import load as provider
+
+job = load("job.toml")
+offers, ceiling, notes = run.plan(job, provider="vast")   # ranked; each has .estimate
+run_id, outcome = run.run(job, provider="vast", log_dir="runs/x")
+provider("vast").list_ours()                              # for your own guards
+```
+
+`run.preflight(remote)` can be wrapped to add host checks of your own: raise
+`run.Unsuitable` when the host works but doesn't suit the job, and `run.BadHost`
+when it's broken. Both replace the host, but only `BadHost` counts against it in
+memory. To move a job between providers, check [docs/clients.md](docs/clients.md).
+
+## More
+
+- [docs/placement.md](docs/placement.md): the cost model, memory and every `[placement]` field
+- [docs/clients.md](docs/clients.md): writing jobs that run on any provider; the Python surface
+- [docs/lessons.md](docs/lessons.md): operational behavior and troubleshooting
+- [CONTRIBUTING.md](CONTRIBUTING.md): development and tests
+- [SECURITY.md](SECURITY.md): trust model and vulnerability reports
+- [RELEASING.md](RELEASING.md): release checklist
+- [CHANGELOG.md](CHANGELOG.md)

gipper-0.3.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+gipper/__init__.py,sha256=GytsdGOtDCT-V4wIT2Kk05HAeO1H1jz1wOzfQZdD6BY,67
+gipper/billing.py,sha256=WiCCiP_3-bzclbgWvn0fojBOi-x_LFAZFmuagqFG0VQ,4002
+gipper/bootstrap.sh,sha256=0shx8CpHX3tNZIP_f7vwy8pj3AZ2rMpOm6tvVPEFFxc,1389
+gipper/cli.py,sha256=Q0i4g1ez9fiKhvqMkKJffiQWoALlUAOnl84hXSoqvws,10785
+gipper/config.py,sha256=a8tpjvYkvFzKQhEb-Kf0G24KnJ-e1TIpuF0cuHzSi80,3541
+gipper/costs.py,sha256=etVTLmMVk_rxPvXY1lD92IbMMl5c8nX0XJaNyPzDr9k,7330
+gipper/cuda_probe.py,sha256=HXIMRUaNINi1zZ73F4OzfkJUsO_9Do-8wGS03YezZvc,3658
+gipper/history.py,sha256=Ez2tMFAdQoSSijUC2CO6Z0aRYICyU-lwbOz6GR4BKXk,12022
+gipper/http.py,sha256=kHb5EJXXcNbZ3-HaeQRW24vbz2SEE_97aQgQ0B8YiNU,1806
+gipper/job.py,sha256=y_YJaobyHkZAU8JKSY1WeMinNvjKTLeJc7tmCxKp6uk,6509
+gipper/latency.py,sha256=R5Hvxg3UDfaeL1NicXFNmr0P9qRtbD7yY66LjdO1Ig8,2078
+gipper/ledger.py,sha256=M9p95ikhqZenZrnUOTDaCPwHpMFWo5wYXuWrYj6sWjE,2190
+gipper/lifecycle.py,sha256=A6uPiHdKaV5vBADWn5ulXEeKLwmpgENgi6pYXnbzBi4,3131
+gipper/market.py,sha256=BU-2nlQ5xslVVyZtCSyVi5kd59lpXp7Bb2VsqB5knuE,8345
+gipper/network_probe.py,sha256=BZaUQ34ObYMTj6CFoXsiUc61hSNqCdNP4SDziFH3Nwk,4255
+gipper/placement.py,sha256=3NsaLTThMWZTa5os4n9-yK8sj37nwr2DagoWN7D5-c0,10882
+gipper/reap.py,sha256=0l8YjqnJSldg1Ek4Et6Ck6wDknh4xphL8bkLo2LjTJ4,4136
+gipper/run.py,sha256=6bR4kW1acqBMyKRJunrqrnuIX4kiattsBxxo79LjfYc,19391
+gipper/ssh.py,sha256=ysv7jOJUL24L6g1gXAjmDYZTxBcDGC32qnM_ygRSpuk,3820
+gipper/providers/__init__.py,sha256=flknxIqVbGkZNUhso9bUMnX9yktMaNRP6B-DFWyy6e8,1756
+gipper/providers/runpod.py,sha256=OS3kgvZgdF7NU5nemJIh9DldW03WwqbuZGA-P-UE9-s,10284
+gipper/providers/shadeform.py,sha256=N2MnDaHDd8t3JZN4hmBoLS668eYHk-vrGIo9ie7NNKo,7004
+gipper/providers/vast.py,sha256=pgOEO_c_Ye-7UNT8fZjPVFhidf1R2MpNwPYSGz7oZJ8,8894
+gipper/runpod/__init__.py,sha256=Nd0UaTXt3t9KwTzrbmp7TCdsBX1lAiKp50ZP6Rvv0Lo,158
+gipper/runpod/api.py,sha256=T_IDAneCkyP-jn89oBgklRrZmC_hMdg6XnOFZHZ3CII,462
+gipper/runpod/run.py,sha256=PFZ-HWRii8GuvDaRzdydUm5MsZkNlwn4uQyW-GENtAA,1049
+gipper-0.3.0.dist-info/licenses/LICENSE,sha256=ejGHbhxV78Yi2fC6LlbhPd2CTilC3dSHe8RtYUD0rKg,1070
+gipper-0.3.0.dist-info/METADATA,sha256=8rlHg2B1PyfNv5jdAN6VfVf3LuXPExGtF_X8l7yw4Vk,12680
+gipper-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+gipper-0.3.0.dist-info/entry_points.txt,sha256=0LXGEgrZZgmEkszhxQ_VCqNCY6xznItA7eQF9ziQv8c,43
+gipper-0.3.0.dist-info/top_level.txt,sha256=koikgT0LIh_xq_uSwxUJB4zsc5xqEBTPUyaodgdG4Mg,7
+gipper-0.3.0.dist-info/RECORD,,

gipper-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gipper-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gipper = gipper.cli:main

gipper-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Lavallee
+
+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.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gipper-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gipper