jambu-gpu 0.4.0__tar.gz → 0.5.0__tar.gz

jambu_gpu-0.5.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.5
+Name: jambu-gpu
+Version: 0.5.0
+Summary: Renamed to gpu4agents (GPU for Agents). This release installs gpu4agents.
+Project-URL: Homepage, https://gpu4agents.jambu.ai
+Project-URL: Repository, https://github.com/jambuai/gpu4agents
+Author: Jambu.ai
+Author-email: João Gabriel Lima <joao.gabriel@jambu.ai>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 7 - Inactive
+Requires-Python: >=3.10
+Requires-Dist: gpu4agents>=0.5.0
+Description-Content-Type: text/markdown
+
+# jambu-gpu is now gpu4agents
+
+This project was renamed to **GPU for Agents**: [`gpu4agents`](https://pypi.org/project/gpu4agents/).
+
+This release has no code; it installs `gpu4agents`, which provides the same `gpu` command, reads the same `jambu.yaml` and finds the same machines.
+
+```bash
+pipx uninstall jambu-gpu && pipx install gpu4agents
+# or: pip install -U gpu4agents
+```
+
+Website: https://gpu4agents.jambu.ai · Code: https://github.com/jambuai/gpu4agents

jambu_gpu-0.5.0/README.md

@@ -0,0 +1,12 @@
+# jambu-gpu is now gpu4agents
+
+This project was renamed to **GPU for Agents**: [`gpu4agents`](https://pypi.org/project/gpu4agents/).
+
+This release has no code; it installs `gpu4agents`, which provides the same `gpu` command, reads the same `jambu.yaml` and finds the same machines.
+
+```bash
+pipx uninstall jambu-gpu && pipx install gpu4agents
+# or: pip install -U gpu4agents
+```
+
+Website: https://gpu4agents.jambu.ai · Code: https://github.com/jambuai/gpu4agents

jambu_gpu-0.5.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jambu-gpu"
+version = "0.5.0"
+description = "Renamed to gpu4agents (GPU for Agents). This release installs gpu4agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Jambu.ai" },
+    { name = "João Gabriel Lima", email = "joao.gabriel@jambu.ai" },
+]
+dependencies = ["gpu4agents>=0.5.0"]
+classifiers = ["Development Status :: 7 - Inactive"]
+
+[project.urls]
+Homepage = "https://gpu4agents.jambu.ai"
+Repository = "https://github.com/jambuai/gpu4agents"
+
+[tool.hatch.build.targets.wheel]
+bypass-selection = true

jambu_gpu-0.4.0/.env.example

@@ -1,11 +0,0 @@
-# Credentials are resolved from the environment, this file, or
-# ~/.jambu/credentials - never from jambu.yaml.
-
-# Required by the vast provider.
-VAST_API_KEY=
-
-# Optional: needed for gated HuggingFace models.
-HF_TOKEN=
-
-# Optional: per-profile override, used when provider.profile: staging
-# VAST_API_KEY__staging=

jambu_gpu-0.4.0/.gitignore

@@ -1,17 +0,0 @@
-__pycache__/
-*.py[cod]
-.venv/
-venv/
-dist/
-build/
-*.egg-info/
-.gpu/
-.jambu/
-.env
-.env.*
-!.env.example
-.pytest_cache/
-.coverage
-node_modules/
-*.tsbuildinfo
-.claude/

jambu_gpu-0.4.0/CONTRIBUTING.md

@@ -1,75 +0,0 @@
-# Contributing
-
-`jambu-gpu` provisions a temporary GPU runtime and guarantees it stops billing
-when nothing is using it. Contributions are welcome. By submitting a change you
-agree it is licensed under the [MIT License](LICENSE).
-
-## Command name
-
-The published command is `gpu`. The package name stays `jambu-gpu`.
-
-Do not add a second console script. One command, in `pyproject.toml`:
-
-```toml
-[project.scripts]
-gpu = "jambu_gpu.cli.main:main"
-```
-
-## Setup
-
-```bash
-python3 -m venv .venv
-.venv/bin/pip install -e ".[dev]"
-```
-
-Python 3.10 or newer. Tests do not need `VAST_API_KEY`, a GPU, or network access.
-
-## Tests
-
-```bash
-.venv/bin/pytest
-.venv/bin/pytest tests/test_policy.py       # shutdown rule
-.venv/bin/pytest tests/test_watchdog.py     # generated guard, as a real process
-.venv/bin/pytest tests/test_integration.py  # setup -> boot -> run -> auto-stop
-```
-
-A change to lifecycle behaviour needs a test that fails before the change and
-passes after it. The policy in `jambu_gpu/core/policy.py` and the watchdog that
-runs on the instance must keep agreeing: the watchdog inlines that module at
-provision time.
-
-`tests/test_integration.py` does not mock the boot. It runs the onstart script
-the engine generated, starts the real watchdog, waits on a real health endpoint,
-runs a workload with real heartbeats, and asserts the guard stops the instance
-with the right reason.
-
-## What you may change
-
-| Change | Where it goes |
-| --- | --- |
-| New provider | `jambu_gpu/providers/<name>/` plus one registry line. See [docs/ADDING_A_PROVIDER.md](docs/ADDING_A_PROVIDER.md). |
-| Shutdown rule | `jambu_gpu/core/policy.py` and `tests/test_policy.py`. |
-| How the model server starts | `jambu_gpu/runtime/`. |
-| CLI surface | `jambu_gpu/cli/`. Keep `--json` and `--config` on every command. |
-
-The core must not branch on a provider name. Branch on `provider.capabilities`.
-If a provider feature requires an `if provider == "..."` in `core/`, the contract
-is wrong — extend the contract instead.
-
-Out of scope: multi-instance scheduling, multi-GPU
-orchestration, Kubernetes, distributed inference, automatic provider selection,
-job queues, a web dashboard. See [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md).
-
-## Secrets
-
-Never commit credentials, `.env`, `.gpu/state.json`, or provider instance
-ids from a real run. Keys are read from the environment, a gitignored `.env`,
-or `~/.gpu/credentials`. `.env.example` ships with empty values only.
-
-## Pull requests
-
-- Explain why the behaviour should change, not only what moved.
-- Run `.venv/bin/pytest` and report the result.
-- Keep commits focused. A provider adapter and a policy change are two PRs.
-- Match the surrounding style: English identifiers and docs, type hints on new
-  public functions, no new dependency unless the standard library cannot do the job.

jambu_gpu-0.4.0/PKG-INFO

@@ -1,90 +0,0 @@
-Metadata-Version: 2.5
-Name: jambu-gpu
-Version: 0.4.0
-Summary: Provider-agnostic CLI for provisioning and managing temporary GPU runtimes
-Project-URL: Homepage, https://github.com/jambuai/jambu-gpu
-Project-URL: Repository, https://github.com/jambuai/jambu-gpu
-Project-URL: Issues, https://github.com/jambuai/jambu-gpu/issues
-Author: Jambu.ai
-Author-email: João Gabriel Lima <joao.gabriel@jambu.ai>
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: pydantic>=2.6.0
-Requires-Dist: pyyaml>=6.0.1
-Requires-Dist: rich>=13.7.0
-Requires-Dist: typer>=0.12.0
-Provides-Extra: dev
-Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
-Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Requires-Dist: respx>=0.21.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# gpu
-
-Temporary GPU runtimes that stop billing when the work stops.
-
-You declare the model and how long it may live. `gpu` provisions a machine, starts the model server, and runs your job against it. Shutdown happens on the instance, so closing the laptop does not leave the GPU billing.
-
-Vast.ai is the first provider. Another provider is a new adapter. The lifecycle rule stays the same.
-
-## Run
-
-```bash
-pip install jambu-gpu
-
-cd your-experiment
-gpu init --model empero-ai/Qwythos-9B-v2
-export VAST_API_KEY=...
-
-gpu validate
-gpu setup
-gpu run python experiment.py
-```
-
-When you are finished, `gpu destroy`. If you walk away, the idle timeout does it.
-
-From an application in any language: `gpu --json setup` returns the OpenAI-compatible `base_url`, `api_key` and `model`, and the app uses any OpenAI SDK. See [Integrating gpu into an application](docs/INTEGRATION.md), with a ready TypeScript client.
-
-From a coding agent: `gpu agent install` gives Claude Code (or `-t cursor`, `-t desktop`) a skill and local MCP tools to rent a GPU, run the experiment and shut it down. See [Letting a coding agent rent GPUs](docs/AGENTS.md).
-
-As a last line of defense, `gpu ls` shows every jambu instance in the account and `gpu sweep --install-timer` sets up a systemd user timer that guards every project on the machine by its own rules and cleans up the orphans no project tracks. See [Keeping the account clean](docs/USAGE.md#keeping-the-account-clean).
-
-The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
-
-## Declare
-
-```yaml
-gpu_runtime:
-  provider: {name: vast}
-  model_profile: qwythos-9b
-  lifecycle:
-    idle_timeout: 15m
-    max_lifetime: 6h
-  budget:
-    max_hourly_cost_usd: 1.50
-```
-
-The file is `jambu.yaml`. This tool reads only the `gpu_runtime:` key, so other Jambu tools can share the same file. A full example is [`jambu.example.yaml`](jambu.example.yaml).
-
-## Docs
-
-- [Integrating into an application (any language)](docs/INTEGRATION.md)
-- [Letting a coding agent rent GPUs (Claude Code, Cursor, Claude Desktop)](docs/AGENTS.md)
-- [Commands, workloads, and agents](docs/USAGE.md)
-- [Every config field](docs/CONFIG.md)
-- [Choosing a model](docs/CHOOSING_A_MODEL.md)
-- [How shutdown works](docs/LIFECYCLE.md)
-- [Adding a provider](docs/ADDING_A_PROVIDER.md)
-- [Contributing](CONTRIBUTING.md)
-
-## License
-
-[MIT](LICENSE).
-
-<p align="center">
-  <a href="https://jambu.ai">
-    <img src="docs/assets/jambu-logo.jpg" alt="Jambu.ai — Applied Intelligence Lab" width="280">
-  </a>
-</p>

jambu_gpu-0.4.0/README.md

@@ -1,67 +0,0 @@
-# gpu
-
-Temporary GPU runtimes that stop billing when the work stops.
-
-You declare the model and how long it may live. `gpu` provisions a machine, starts the model server, and runs your job against it. Shutdown happens on the instance, so closing the laptop does not leave the GPU billing.
-
-Vast.ai is the first provider. Another provider is a new adapter. The lifecycle rule stays the same.
-
-## Run
-
-```bash
-pip install jambu-gpu
-
-cd your-experiment
-gpu init --model empero-ai/Qwythos-9B-v2
-export VAST_API_KEY=...
-
-gpu validate
-gpu setup
-gpu run python experiment.py
-```
-
-When you are finished, `gpu destroy`. If you walk away, the idle timeout does it.
-
-From an application in any language: `gpu --json setup` returns the OpenAI-compatible `base_url`, `api_key` and `model`, and the app uses any OpenAI SDK. See [Integrating gpu into an application](docs/INTEGRATION.md), with a ready TypeScript client.
-
-From a coding agent: `gpu agent install` gives Claude Code (or `-t cursor`, `-t desktop`) a skill and local MCP tools to rent a GPU, run the experiment and shut it down. See [Letting a coding agent rent GPUs](docs/AGENTS.md).
-
-As a last line of defense, `gpu ls` shows every jambu instance in the account and `gpu sweep --install-timer` sets up a systemd user timer that guards every project on the machine by its own rules and cleans up the orphans no project tracks. See [Keeping the account clean](docs/USAGE.md#keeping-the-account-clean).
-
-The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
-
-## Declare
-
-```yaml
-gpu_runtime:
-  provider: {name: vast}
-  model_profile: qwythos-9b
-  lifecycle:
-    idle_timeout: 15m
-    max_lifetime: 6h
-  budget:
-    max_hourly_cost_usd: 1.50
-```
-
-The file is `jambu.yaml`. This tool reads only the `gpu_runtime:` key, so other Jambu tools can share the same file. A full example is [`jambu.example.yaml`](jambu.example.yaml).
-
-## Docs
-
-- [Integrating into an application (any language)](docs/INTEGRATION.md)
-- [Letting a coding agent rent GPUs (Claude Code, Cursor, Claude Desktop)](docs/AGENTS.md)
-- [Commands, workloads, and agents](docs/USAGE.md)
-- [Every config field](docs/CONFIG.md)
-- [Choosing a model](docs/CHOOSING_A_MODEL.md)
-- [How shutdown works](docs/LIFECYCLE.md)
-- [Adding a provider](docs/ADDING_A_PROVIDER.md)
-- [Contributing](CONTRIBUTING.md)
-
-## License
-
-[MIT](LICENSE).
-
-<p align="center">
-  <a href="https://jambu.ai">
-    <img src="docs/assets/jambu-logo.jpg" alt="Jambu.ai — Applied Intelligence Lab" width="280">
-  </a>
-</p>

jambu_gpu-0.4.0/docs/ACCEPTANCE.md

@@ -1,85 +0,0 @@
-# Acceptance criteria — where each one is implemented and tested
-
-Eighteen guarantees, mapped to the code and the test that holds each one.
-
-| # | Guarantee | Implementation | Test |
-| --- | --- | --- | --- |
-| 1 | Repeated `setup` does not duplicate infrastructure | `core/engine.py::Engine.setup` reconciles first, compares `config.fingerprint()`, and holds an exclusive `.gpu/runtime.lock` | `test_engine.py::test_setup_twice_does_not_create_two_instances`, `::test_setup_refuses_to_reuse_an_incompatible_instance` |
-| 2 | Provider APIs do not leak into core orchestration | `providers/base.py` contract; all Vast wire format confined to `providers/vast/{client,mapper}.py` | `test_engine.py::test_the_core_never_branches_on_a_provider_name` (greps `core/`) |
-| 3 | Missing credentials fail before provisioning | `VastProvider.validate` returns before any API call; `CredentialResolver` never reads jambu.yaml | `test_vast_provider.py::test_validate_fails_before_provisioning_without_a_key` (asserts zero HTTP calls) |
-| 4 | Failed provisioning cleans up | `Engine.setup` persists state *before* the long wait, then destroys on failure when `cleanup_on_setup_failure` | `test_engine.py::test_failed_setup_cleans_up_partially_created_resources` |
-| 5 | Active workloads are never stopped by the idle guard | `core/policy.py::evaluate` returns `workload_active` before any idle check | `test_policy.py::test_active_workload_is_never_stopped_by_the_idle_guard`, `test_watchdog.py::test_a_heartbeating_workload_is_never_stopped` |
-| 6 | An idle unlocked instance stops within `idle_timeout + watchdog_interval` | remote watchdog loop, `watchdog/agent_body.py::guard_loop` | `test_watchdog.py::test_idle_instance_is_stopped_with_a_recorded_reason` (real subprocess) |
-| 7 | `max_lifetime` bounds forgotten instances | `policy.evaluate` checks age before activity | `test_policy.py::test_max_lifetime_stops_even_when_busy`, `test_watchdog.py::test_max_lifetime_stops_a_busy_instance` |
-| 8 | Locks prevent shutdown until expiry | `policy.Snapshot.lock_active` / `lock_expired`; TTL required unless `allow_indefinite_lock` | `test_policy.py::test_expired_lock_stops_protecting`, `test_watchdog.py::test_a_lock_prevents_shutdown_until_it_expires` |
-| 9 | A crashed CLI does not disable protection | the guard runs *on the instance*; heartbeats go stale after `heartbeat_grace` | `test_watchdog.py::test_a_vanished_heartbeat_falls_back_to_idle`, `::test_startup_grace_expires_when_the_cli_never_confirms` |
-| 10 | Remote state is reconciled | `Engine._reconcile` merges provider truth + watchdog truth and repairs local state | `test_engine.py::test_status_repairs_state_when_the_instance_vanished` |
-| 11 | A new provider needs only the contract | `providers/registry.py`; the engine is driven end to end by `tests/fakes.py::FakeProvider` | `test_engine.py::test_a_new_provider_needs_only_the_contract` |
-| 12 | Every automatic shutdown records its reason | `lifecycle_guard_triggered` + `instance_stopped` events carry `reason`, locally and on the instance | `test_engine.py::test_guard_stops_an_idle_unlocked_instance_and_records_the_reason`, `test_watchdog.py::test_idle_instance_is_stopped_with_a_recorded_reason` |
-| 13 | A restarted instance stays guarded | `Engine._reconcile` takes running/stopped from the provider; the watchdog's `terminated` flag only counts when the provider cannot tell. `RuntimeState.session_started_at` restarts on every start, and `max_lifetime` and the session budget are measured from it | `test_engine_sessions.py::test_reconcile_trusts_the_provider_over_a_stale_terminated_flag`, `::test_a_stale_terminated_flag_does_not_disable_the_guard`, `::test_restarting_a_stopped_instance_starts_a_new_session`, `::test_guard_budget_resets_with_a_new_session`; watchdog-side session tests in `test_policy.py` / `test_watchdog.py` |
-| 14 | Traffic on the model endpoint is activity | `VllmRuntime.activity_probe` hands the watchdog vLLM's `/metrics` gauges and counters; `lifecycle.traffic_counts_as_activity` turns it off | `test_engine_sessions.py::test_the_watchdog_is_told_how_to_read_vllm_traffic`, `::test_traffic_can_be_excluded_from_activity`, `test_runtime_vllm.py::test_activity_probe_reads_vllm_metrics_on_loopback`; the watchdog's metrics-reading tests in `test_watchdog.py` |
-| 15 | A stopped instance does not bill storage forever | `lifecycle.stopped_ttl` -> `PolicyConfig.stopped_ttl_s`; `RuntimeState.stopped_since`; `Engine.guard_tick` destroys with reason `stopped_ttl`; `validate` warns when nothing would remove it | `test_engine_sessions.py::test_guard_destroys_an_instance_stopped_longer_than_stopped_ttl`, `::test_validate_warns_when_nothing_removes_a_billing_stopped_instance`; the stopped-TTL policy tests in `test_policy.py` |
-| 16 | Orphans are found account-wide, each project keeps its own rules, and nothing else is touched | `GPUProvider.list_instances` (capability `list_instances`) returns only `jambu-` labels; `gpu setup` registers the project in `~/.gpu/projects.json`; `core/sweep.py::guard_projects` runs each registered project's own `Engine.guard_tick`; only untracked instances are orphans: running past `--orphan-max-age` is stopped (never destroyed), stopped past `--stopped-ttl` (from the sweep's own first sighting in `~/.gpu/sweep.json`) is destroyed; `gpu sweep --install-timer` schedules one working-directory-independent unit and refuses a key that is only in the shell | `test_sweep.py::test_vast_lists_only_jambu_labelled_instances`, `::test_non_jambu_instances_are_never_touched`, `::test_another_projects_restarted_and_locked_instance_is_not_destroyed`, `::test_each_project_is_judged_by_its_own_max_lifetime`, `::test_a_running_orphan_past_orphan_max_age_is_stopped_never_destroyed`, `::test_a_stopped_orphan_is_destroyed_once_seen_stopped_past_stopped_ttl`, `::test_install_timer_writes_one_unit_independent_of_the_project`, `::test_install_timer_refuses_a_key_only_in_the_shell_environment` |
-| 17 | The CLI guard never stops a serving endpoint it cannot see | `Engine._idle_blind`: with the watchdog enabled and installed but unreachable, `guard_tick` evaluates without `idle_timeout` and records `idle_skipped`; `max_lifetime`, budget and `stopped_ttl` still apply | `test_engine_sessions.py::test_guard_leaves_idle_to_an_unreachable_watchdog`, `::test_max_lifetime_still_applies_when_the_watchdog_is_unreachable` |
-| 18 | A fresh stop or a short API outage never costs the disk | `RuntimeState.mark_stopped` restarts `stopped_since` on evidence the instance ran since; the watchdog escalates a failing stop to destroy only after `escalate_after_s` (30m) of continuous failure and resets on renewed use | `test_engine_sessions.py::test_a_stale_stopped_since_does_not_destroy_a_fresh_stop`, `test_watchdog.py::test_an_api_blip_does_not_destroy_the_disk`, `::test_failures_reset_when_the_instance_is_back_in_use` |
-
-## Validated on real hardware
-
-On 2026-10-24 the lifecycle ran end to end on Vast.ai (RTX 3090, Qwen2.5-0.5B, `idle_timeout: 4m`, `stopped_ttl: 5m`), for $0.35 of Vast credit in total across every attempt:
-
-| What was checked | What happened |
-| --- | --- |
-| Traffic is activity | 10 requests sent straight to the endpoint over 7.5 minutes, none through `gpu run`. The machine stayed up past the 4-minute idle timeout. |
-| Idle stops | 269 s after the last request the watchdog stopped its own machine (`idle_timeout`). Vast showed it `exited`. |
-| A restart is guarded | `gpu run` restarted it. The watchdog logged `session_started` with `terminated: false` and measured `max_lifetime` from the restart. After the workload it stopped the machine again on its own. |
-| Stopped storage is reclaimed | 334 s after the stop, `gpu guard` destroyed it (`stopped_ttl`). |
-| Failed setups leave nothing | An image built for a newer CUDA, a model server that died at import, a host whose network dropped the weights download, a 30-minute image pull, and a Ctrl-C each ended with the instance destroyed. |
-| Bad hosts are skipped | Hosts that could not pull the image were destroyed, excluded and replaced, with never two instances alive at once. |
-
-The run also found what unit tests could not, and each of these is fixed and covered by a test:
-- the boot script was over Vast's 16 KB onstart limit;
-- `latest` had moved to CUDA 13;
-- the `-cu129` image variant could not load torchcodec;
-- a 15-minute boot timeout was too short for a 12 GB pull;
-- Ctrl-C did not clean up;
-- a fresh contract was reported `READY`.
-
-### Application integration (0.2.0)
-
-Driven end to end by [`examples/typescript-client`](../examples/typescript-client/) through the OpenAI SDK, on an RTX 3090 with Qwen2.5-0.5B:
-
-| Check | Result |
-| --- | --- |
-| `ensureGpu()` on an empty account | Two bad hosts (weights download cut by the host's network; image pull stalled 30 minutes) were destroyed and replaced; the third served. 37 minutes in all, one instance alive at a time. |
-| The endpoint requires its key | No key: `401`. Wrong key: `401`. The key from `gpu --json setup`: `200`. `/health` without a key: `200`. |
-| Chat through the SDK | Answered. |
-| Healing after a stop | `stopGpu()`, then a call on the stale connection: it failed to connect, `gpu setup` restarted the same instance, and the retry answered 41 s later with the same key. |
-
-It found two more bugs, both fixed and tested: Vast reports a stopping instance as `running` for a few seconds, which made a setup right after a stop skip the restart; and a Vast rate limit (`429`) failed setup instead of being waited out.
-
-## A coding agent driving it (0.4.0)
-
-On 2026-10-25 a headless Claude Code with no prior context (`claude -p`) was given a fresh directory holding only `gpu agent install`'s skill and `.mcp.json`, plus `VAST_API_KEY` in `.env`. It was asked in one sentence to test Qwen2.5-0.5B on a rented GPU, ask it the capital of Brazil, report time and cost, and destroy the machine. It loaded the `gpu` skill by itself and called `gpu_init` (with the cap and VRAM from the request), `gpu_validate`, `gpu_offers`, then `gpu_setup` until ready, `curl` for the question, `gpu_status`, `gpu_destroy` and `gpu_ls`. The model answered "Brasília", the account was empty at the end, and the agent reported setup time and cost correctly, noting that `session_cost_usd` leaves out the replaced host.
-
-| What was checked | What happened |
-| --- | --- |
-| Setup longer than any tool timeout | `gpu_setup` returned `running` every 300 s for 42 minutes and re-attached to the same background job each time: one machine at a time, never a second setup. |
-| Bad hosts | The first host could not pull the image for 30 minutes; setup destroyed it and rented another, which served. |
-| Cancel | Over MCP (official Python SDK client), `gpu_destroy` during a setup interrupted it like Ctrl-C: the booting machine was destroyed and `gpu_ls` came back empty, 2.3 s after the call. |
-| Protocol | The official MCP Python SDK (2.3.0) client initializes, lists the 13 tools and calls them. |
-
-The first attempt found what the unit tests had not, each fixed and tested:
-- during a setup, `gpu status`, `gpu logs`, `gpu stop` and `gpu destroy` failed on the project lock (reported as "no instance"). Now `status` and `logs` report the last saved state with `busy: true`, the MCP `gpu_stop` / `gpu_destroy` cancel the setup first, and a held lock is its own exit code, 12;
-- the host that failed last when setup gave up was not remembered as bad, so the next setup rented it again;
-- on Vast, three hosts in a row stalled 30 minutes each pulling the 12 GB Docker Hub image, and setup gave up after 90 minutes with nothing left billing. Vast now defaults to `vastai/vllm:v0.32.0-cuda-13.0`, the same vLLM that Vast's hosts cache: in the cancel test the container was running within a minute.
-
-## The MVP command surface
-
-`jambu.yaml` schema, CLI, provider contract, provider registry, Vast.ai adapter,
-vLLM runtime, `setup`, `run`, `status`, `stop`, `destroy`, `lock`/`unlock`, idle
-timeout, max lifetime, remote watchdog, structured logs — all present. On top of
-it, `ls` and `sweep` for account-wide orphan control.
-
-Deliberately not implemented: multi-instance scheduling, multi-GPU
-orchestration, Kubernetes, distributed inference, provider optimization, automatic
-provider selection, job queues, web dashboard.

jambu_gpu-0.4.0/docs/ADDING_A_PROVIDER.md

@@ -1,132 +0,0 @@
-# Adding a provider
-
-Adding a provider means adding `jambu_gpu/providers/<name>/` and one line in the
-registry. **No lifecycle, execution or CLI code changes.** If you find yourself
-editing `core/`, the contract is leaking.
-
-## 1. Implement the contract
-
-```python
-# jambu_gpu/providers/runpod/provider.py
-from ...core.models import ProviderCapabilities
-from ..base import GPUProvider, WatchdogSpec
-
-
-class RunpodProvider(GPUProvider):
-    name = "runpod"
-    display_name = "RunPod"
-    required_credentials = ["RUNPOD_API_KEY"]
-    capabilities = ProviderCapabilities(
-        stop=True,
-        destroy=True,
-        ssh=True,
-        public_ports=True,
-        gpu_selection=True,
-        pricing_query=True,
-        remote_exec=True,
-        logs=True,
-        stop_eliminates_billing=True,
-    )
-
-    def validate(self, config): ...
-    def setup(self, spec): ...
-    def start(self, instance): ...
-    def run(self, instance, workload): ...
-    def status(self, instance): ...
-    def stop(self, instance): ...
-    def destroy(self, instance): ...
-    def logs(self, instance): ...
-```
-
-Suggested layout, mirroring the Vast adapter:
-
-```
-providers/runpod/
-├── provider.py   the contract implementation
-├── client.py     raw HTTP; the ONLY place that knows the wire format
-├── mapper.py     payloads <-> normalized models, state mapping
-└── config.py     provider.options schema and constants
-```
-
-## 2. Declare capabilities honestly
-
-The core never branches on `provider.name` — only on `provider.capabilities`. Set
-`stop_eliminates_billing=False` if a stopped instance still costs money; the policy
-then knows it may need to escalate to destroy, and `lifecycle.stopped_ttl` applies.
-
-Set `list_instances=True` and implement `list_instances()` if the API can enumerate
-the account. Return only instances whose label starts with `JAMBU_LABEL_PREFIX`
-(`core/models.py`); `gpu ls` and `gpu sweep` are built on it and stay unavailable
-otherwise.
-
-## 3. Normalize state and errors
-
-Map every provider status onto `InstanceState`
-(`provisioning / starting / ready / busy / idle / stopped / failed / destroyed`),
-and raise only the normalized errors from `core/errors.py`:
-`AuthenticationError`, `CapacityUnavailableError`, `ProvisioningError`,
-`ProviderTimeoutError`, `UnsupportedCapabilityError`. CLI behaviour must be
-identical across providers.
-
-Report a machine that will not boot as `failed` rather than leaving it in
-`starting`: `setup` then destroys it at once and rents another machine
-(`compute.host_attempts`). Set `Offer.host_id` and `Instance.host_id` to the
-physical machine when the API exposes it, and leave out offers whose `host_id` is
-in `ComputeSpec.exclude_hosts`, or `setup` may rent the same bad machine again.
-
-## 4. Supply the watchdog actions
-
-The lifecycle *policy* is the core's; the adapter contributes only the two calls
-that shut the machine down from inside itself:
-
-```python
-WATCHDOG_ACTIONS = '''
-def provider_stop(ctx):
-    ...   # stdlib only: urllib, json, os
-
-def provider_destroy(ctx):
-    ...
-'''
-
-def watchdog_spec(self, spec_or_instance=None):
-    return WatchdogSpec(
-        actions_source=WATCHDOG_ACTIONS,
-        env={"RUNPOD_API_KEY": self.credentials.get("RUNPOD_API_KEY") or ""},
-        context={"provider": self.name},
-    )
-```
-
-The instance id may not exist when the boot script is generated. Either resolve it
-from the container's own environment (as the Vast adapter does with
-`VAST_CONTAINERLABEL`), or rely on the CLI's `/identify` call — support both if you
-can, so the guard works even if the CLI never reconnects.
-
-Return `None` only if the provider genuinely cannot self-terminate; users then have
-to run `gpu guard` externally, and `validate` will warn.
-
-## 5. Publish the ports
-
-`ComputeSpec.ports` lists the container ports the core needs published. Map them to
-`Instance.endpoints` under the names `model` and `watchdog`. Without a published
-watchdog port the remote guard is unreachable.
-
-## 6. Register it
-
-```python
-# providers/registry.py
-def load_builtin_providers():
-    from .vast.provider import VastProvider
-    from .runpod.provider import RunpodProvider
-
-    registry.register(VastProvider)
-    registry.register(RunpodProvider)
-    return registry
-```
-
-## 7. Test it
-
-Copy `tests/test_vast_provider.py` and swap the mocked payloads. Then check the
-adapter really is swappable — `tests/test_engine.py` drives the whole engine
-through `tests/fakes.py::FakeProvider` with zero core changes, and
-`test_the_core_never_branches_on_a_provider_name` fails the build if `core/` learns
-a provider's name.

jambu_gpu-0.4.0/docs/AGENTS.md

@@ -1,56 +0,0 @@
-# Letting a coding agent rent GPUs
-
-`gpu` ships a skill and a local MCP server, so Claude Code, Cursor or Claude Desktop can rent a GPU, serve a model, run an experiment against it and shut it down, from a request like "compare Qwen 7B and Llama 8B on these 50 prompts".
-
-The watchdog on the machine is what makes this safe to hand to an agent: a machine the agent forgets, or a conversation that ends mid-experiment, stops by itself after `lifecycle.idle_timeout`.
-
-## Install
-
-```bash
-pipx install jambu-gpu            # or: uv tool install jambu-gpu
-cd your-project
-echo "VAST_API_KEY=..." >> .env   # or ~/.gpu/credentials; never in jambu.yaml
-gpu agent install                 # Claude Code
-gpu agent install -t cursor       # Cursor
-gpu agent install -t desktop      # Claude Desktop
-```
-
-| Target | Skill | MCP server |
-| --- | --- | --- |
-| `claude` (default) | `.claude/skills/gpu/SKILL.md` | `.mcp.json` (Claude Code asks once to approve it) |
-| `cursor` | the same `.claude/skills/gpu/` (Cursor reads Claude's skill directories) | `.cursor/mcp.json`, with `--project ${workspaceFolder}` |
-| `desktop` | `~/.gpu/gpu-skill.zip`, to upload under Settings > Capabilities > Skills | `claude_desktop_config.json`, pinned to this project |
-
-`--global` installs for every project of the user instead: the skill in `~/.claude/skills/gpu/`, the MCP server through `claude mcp add --scope user` and in `~/.cursor/mcp.json`. Existing config files are merged; only the `gpu` entry is written. Re-running is safe.
-
-Claude Desktop and Cursor do not get your shell's environment. Keep `VAST_API_KEY` in the project `.env` or `~/.gpu/credentials`, not only in an `export`.
-
-Another agent that reads `SKILL.md` files: `gpu agent skill > path/to/skills/gpu/SKILL.md`. Any MCP client: run `gpu mcp --project /path/to/project` over stdio.
-
-## The MCP tools
-
-| Tool | Does | Costs money |
-| --- | --- | --- |
-| `gpu_init` | write `jambu.yaml` for a model, with an optional price cap and VRAM | no |
-| `gpu_validate` | check the config and credentials | no |
-| `gpu_offers` | cheapest matching machines and their price | no |
-| `gpu_setup` | rent / restart and wait for the model; returns `base_url`, `api_key`, `model` | yes |
-| `gpu_status` | state, cost so far, idle time, the watchdog's next move, setup progress | no |
-| `gpu_connection` | `base_url`, `api_key`, `model` without starting anything | no |
-| `gpu_run` | run a local command with `OPENAI_BASE_URL` / `OPENAI_API_KEY` / `JAMBU_MODEL_ID` set | yes, if it has to start the machine |
-| `gpu_logs` | runtime, onstart, watchdog or provider log | no |
-| `gpu_lock` / `gpu_unlock` | keep the machine up through a quiet period | while locked |
-| `gpu_stop` | stop now; disk kept, restart takes about a minute | ends billing for compute |
-| `gpu_destroy` | delete; needs `confirm=true` | ends all billing |
-| `gpu_ls` | every machine in the account, from any project | no |
-
-Each tool runs the `gpu` CLI with `--json` in the project directory, so errors carry the same `exit_code` as the [application contract](INTEGRATION.md#exit-codes), plus `meaning` and `next` for the agent. A tool takes an optional `project_dir`; by default it is the server's `--project`, `$GPU_PROJECT_DIR`, or the directory the client started it in.
-
-`gpu_setup` would outlast any client's tool timeout on a first rent (5–15 minutes). It starts setup as a background job, waits up to `wait_seconds` (45 by default), and reports `status: "running"` until the model answers. Calling it again re-attaches to the same job; it never starts a second machine. The job outlives the MCP server, so a client restarted mid-setup finds it again through `gpu_setup` or `gpu_status`, which answers during setup with `"busy": true` and the job's progress. `gpu_stop` and `gpu_destroy` cancel a setup in progress the way Ctrl-C does: the machine still booting is destroyed.
-
-## What keeps the agent in line
-
-- **The skill** tells the agent to show the price and ask before renting, wait out a slow setup instead of starting over, never touch `VAST_API_KEY`, and offer stop or destroy (and check `gpu_ls`) when done.
-- **The server's tool annotations** mark `gpu_destroy` destructive and the read-only tools read-only, so a client can let `gpu_status` run freely and ask for every `gpu_setup` and `gpu_destroy`. In Claude Code that is the `permissions` list in `.claude/settings.json`, e.g. `"allow": ["mcp__gpu__gpu_status", "mcp__gpu__gpu_offers", "mcp__gpu__gpu_ls"]`.
-- **`jambu.yaml`** holds the hard limits the agent cannot exceed without editing the file: `budget.max_hourly_cost_usd`, `budget.max_session_cost_usd`, `lifecycle.max_lifetime`.
-- **The watchdog** stops the machine after `idle_timeout` whatever the agent does, and `gpu sweep --install-timer` catches anything left behind.