jambu-gpu 0.2.0__tar.gz → 0.3.0__tar.gz

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/.gitignore

@@ -5,6 +5,7 @@ venv/
 dist/
 build/
 *.egg-info/
+.gpu/
 .jambu/
 .env
 .env.*

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/CONTRIBUTING.md

@@ -62,9 +62,9 @@ job queues, a web dashboard. See [docs/ACCEPTANCE.md](docs/ACCEPTANCE.md).
 
 ## Secrets
 
-Never commit credentials, `.env`, `.jambu/state.json`, or provider instance
+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 `~/.jambu/credentials`. `.env.example` ships with empty values only.
+or `~/.gpu/credentials`. `.env.example` ships with empty values only.
 
 ## Pull requests
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jambu-gpu
-Version: 0.2.0
+Version: 0.3.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
@@ -49,7 +49,7 @@ From an application in any language: `gpu --json setup` returns the OpenAI-compa
 
 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 `~/.jambu/credentials`. It never goes in the manifest.
+The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
 
 ## Declare
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/README.md

@@ -26,7 +26,7 @@ From an application in any language: `gpu --json setup` returns the OpenAI-compa
 
 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 `~/.jambu/credentials`. It never goes in the manifest.
+The API key is read from the environment, a project `.env`, or `~/.gpu/credentials`. It never goes in the manifest.
 
 ## Declare
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/docs/ACCEPTANCE.md

@@ -4,7 +4,7 @@ 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 `.jambu/runtime.lock` | `test_engine.py::test_setup_twice_does_not_create_two_instances`, `::test_setup_refuses_to_reuse_an_incompatible_instance` |
+| 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` |
@@ -19,7 +19,7 @@ Eighteen guarantees, mapped to the code and the test that holds each one.
 | 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 `~/.jambu/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 `~/.jambu/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` |
+| 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` |
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/docs/CONFIG.md

@@ -89,7 +89,7 @@ each number comes from.
 | `disk_gb` | `80` | Disk. Must fit the model weights plus the container. |
 | `region` | – | Comma-separated geolocations. |
 | `spot` | `false` | Use interruptible/bid capacity where supported. |
-| `host_attempts` | `3` | How many machines `setup` tries. A host that fails to boot (the provider reports it failed, it vanishes, or it is not running within `health.boot_timeout`) is destroyed, replaced from fresh offers (each held to the budget), and remembered in `$JAMBU_HOME/bad_hosts.json` so no setup rents it again for 24h. A model server that dies once its container runs fails at once, since the same config would fail on any machine, unless its log shows the host's network failed it (a dropped connection or timeout while downloading weights): that counts as a host failure too. Needs `lifecycle.cleanup_on_setup_failure`; without it the first failed host is kept for inspection. |
+| `host_attempts` | `3` | How many machines `setup` tries. A host that fails to boot (the provider reports it failed, it vanishes, or it is not running within `health.boot_timeout`) is destroyed, replaced from fresh offers (each held to the budget), and remembered in `$GPU_HOME/bad_hosts.json` so no setup rents it again for 24h. A model server that dies once its container runs fails at once, since the same config would fail on any machine, unless its log shows the host's network failed it (a dropped connection or timeout while downloading weights): that counts as a host failure too. Needs `lifecycle.cleanup_on_setup_failure`; without it the first failed host is kept for inspection. |
 | `image` | – | Override the runtime's container image. vLLM's default is `vllm/vllm-openai:v0.32.0`. Pin a tag: `validate` warns on `latest` or an untagged image, because the CUDA it needs can change under you. On Vast, `vastai/vllm:v0.32.0-cuda-13.0` (the same vLLM, packaged by Vast) is often cached on the host and boots in minutes where a 12 GB Docker Hub pull can stall. |
 
 ---

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/docs/INTEGRATION.md

@@ -15,16 +15,17 @@ The app never has to stop the GPU. The watchdog on the machine stops it once not
 pipx install jambu-gpu            # or: uv tool install jambu-gpu / pip install jambu-gpu
 cd /srv/my-app                    # the directory the app runs gpu from
 gpu init --model Qwen/Qwen2.5-7B-Instruct
-echo "VAST_API_KEY=..." >> .env   # or export it, or ~/.jambu/credentials
+echo "VAST_API_KEY=..." >> .env   # or export it, or ~/.gpu/credentials
 gpu validate                      # fails here, not in production, on a bad config
 gpu sweep --install-timer         # optional safety net, see USAGE.md
 ```
 
 Requirements:
 
-- `jambu-gpu` 0.2.0 or later, on Python 3.10+. The app can be in any language.
-- The directory holding `jambu.yaml` must be **persistent**. `gpu` keeps what it rented in `.jambu/state.json` next to it. In a container, mount it as a volume: a container that loses `.jambu/` forgets its instance, rents a second one, and leaves the first to the watchdog and the sweep.
-- `.jambu/state.json` holds the endpoint key and the watchdog token. It is written `0600`. Add `.jambu/` and `.env` to `.gitignore` and keep them out of images.
+- `jambu-gpu` 0.3.0 or later, on Python 3.10+. The app can be in any language.
+- The directory holding `jambu.yaml` must be **persistent**. `gpu` keeps what it rented in `.gpu/state.json` next to it. In a container, mount it as a volume: a container that loses `.gpu/` forgets its instance, rents a second one, and leaves the first to the watchdog and the sweep.
+- Before 0.3.0 these directories were `.jambu/` and `~/.jambu`. The first command after an upgrade renames them, so an instance already rented is kept, not rented again.
+- `.gpu/state.json` holds the endpoint key and the watchdog token. It is written `0600`. Add `.gpu/` and `.env` to `.gitignore` and keep them out of images.
 
 Tune the lifecycle in `jambu.yaml` for the app. For a service with bursty traffic, a longer idle timeout avoids paying a restart on every burst:
 
@@ -218,7 +219,7 @@ Run `gpu --json setup` as a subprocess, parse the JSON, and point the language's
 - **The endpoint requires a key.** Unless `runtime.api_key` is set, `setup` generates one per machine (43 random URL-safe characters) and starts vLLM with it. Requests without it get `401`. `/health` and `/metrics` stay open: they reveal no data and the watchdog reads `/metrics`. Instances provisioned before this existed run without a key until they are recreated.
 - **The endpoint is plain HTTP** on a public IP and port. The key and the prompts travel unencrypted. For sensitive data, put the app and the GPU on a private network or a tunnel, or front the endpoint with a TLS proxy.
 - **The watchdog holds the provider key** on the instance so it can stop its own machine. A restricted key is the safer choice; see [LIFECYCLE.md](LIFECYCLE.md).
-- `jambu.yaml` never holds credentials. `.env` and `.jambu/` do not belong in version control.
+- `jambu.yaml` never holds credentials. `.env` and `.gpu/` do not belong in version control.
 
 ## 6. Troubleshooting
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/docs/LIFECYCLE.md

@@ -105,7 +105,7 @@ gpu
     │
     ├── Lifecycle    core/policy.py     the only shutdown rule
     ├── Runtime      runtime/vllm.py    how the model runs
-    └── State        core/state.py      .jambu/state.json
+    └── State        core/state.py      .gpu/state.json
                 │
         Provider contract   providers/base.py
                 │

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/docs/USAGE.md

@@ -111,9 +111,9 @@ Vast.ai instances
 
 ### Every project by its own rules
 
-`gpu setup` (and `gpu run`, which can provision) registers the project's absolute config path in `~/.jambu/projects.json` (`$JAMBU_HOME` overrides `~/.jambu`). `gpu sweep` then works in two steps:
+`gpu setup` (and `gpu run`, which can provision) registers the project's absolute config path in `~/.gpu/projects.json` (`$GPU_HOME` overrides `~/.gpu`; a `~/.jambu` from before 0.3.0 is renamed to `~/.gpu` on first use, and `$JAMBU_HOME` is still read). `gpu sweep` then works in two steps:
 
-1. **Tracked instances.** For every registered project whose config still loads, it runs that project's own `gpu guard`: its own `jambu.yaml` and `.jambu/state.json`, so its own `max_lifetime`, lock, session start, `stopped_ttl` and budget. The project's events land in its own log. A registered project whose config file is gone is dropped from the registry. The project in the current directory, or the one given with `--config`, is guarded too for that run.
+1. **Tracked instances.** For every registered project whose config still loads, it runs that project's own `gpu guard`: its own `jambu.yaml` and `.gpu/state.json`, so its own `max_lifetime`, lock, session start, `stopped_ttl` and budget. The project's events land in its own log. A registered project whose config file is gone is dropped from the registry. The project in the current directory, or the one given with `--config`, is guarded too for that run.
 2. **Orphans.** An instance no project tracks has no known policy and nobody knows whether it is in use, so the rules are blunt but never destroy a running machine:
 
 | Orphan | Rule | Action |
@@ -134,7 +134,7 @@ $ gpu sweep
 ! 1 action(s) pending; re-run with --apply
 ```
 
-Providers do not report when an instance stopped, so the sweep keeps the time it first saw each orphan stopped in `~/.jambu/sweep.json`. An entry goes away when the instance runs again, disappears, or is tracked by a project. `stopped_ttl` for an orphan therefore counts from the first sweep that saw it stopped, never from a project's state. Every orphan action is recorded as a `sweep_action` event with its reason in `~/.jambu/logs/events.jsonl`. Credentials for the orphan step resolve the usual way (the environment, `.env` in the working directory, `~/.jambu/credentials`), then from the `.env` of registered projects.
+Providers do not report when an instance stopped, so the sweep keeps the time it first saw each orphan stopped in `~/.gpu/sweep.json`. An entry goes away when the instance runs again, disappears, or is tracked by a project. `stopped_ttl` for an orphan therefore counts from the first sweep that saw it stopped, never from a project's state. Every orphan action is recorded as a `sweep_action` event with its reason in `~/.gpu/logs/events.jsonl`. Credentials for the orphan step resolve the usual way (the environment, `.env` in the working directory, `~/.gpu/credentials`), then from the `.env` of registered projects.
 
 ### Run it on a timer
 
@@ -143,9 +143,9 @@ gpu sweep --install-timer            # every 5m; --every 15m to change
 systemctl --user daemon-reload && systemctl --user enable --now jambu-gpu-sweep.timer
 ```
 
-`--install-timer` writes `~/.config/systemd/user/jambu-gpu-sweep.service` and `.timer`, and registers the current project if there is one. The service is a single `ExecStart=<python> -m jambu_gpu sweep --apply` with the interpreter that installed it, run from `~`: which projects get guarded comes from the registry, not from the working directory, so installing from a second project changes nothing in the unit. The oneshot has a 10 minute start timeout, a failing sweep shows as a failed unit, and `JAMBU_HOME` is passed through when it is set. A unit written by an older version, with one `guard` line per project, is rewritten and those projects are registered.
+`--install-timer` writes `~/.config/systemd/user/jambu-gpu-sweep.service` and `.timer`, and registers the current project if there is one. The service is a single `ExecStart=<python> -m jambu_gpu sweep --apply` with the interpreter that installed it, run from `~`: which projects get guarded comes from the registry, not from the working directory, so installing from a second project changes nothing in the unit. The oneshot has a 10 minute start timeout, a failing sweep shows as a failed unit, and `GPU_HOME` is passed through when it is set. A unit written by an older version, with one `guard` line per project, is rewritten and those projects are registered.
 
-A user unit does not inherit your shell's environment. `--install-timer` therefore refuses unless the provider key is in a file: the project `.env` or `~/.jambu/credentials`. A key that is only exported in your shell is not enough. A user timer needs no root, but it stops at logout unless lingering is on (`loginctl enable-linger $USER`).
+A user unit does not inherit your shell's environment. `--install-timer` therefore refuses unless the provider key is in a file: the project `.env` or `~/.gpu/credentials`. A key that is only exported in your shell is not enough. A user timer needs no root, but it stops at logout unless lingering is on (`loginctl enable-linger $USER`).
 
 ```bash
 gpu sweep --uninstall-timer

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/examples/typescript-client/README.md

@@ -6,7 +6,7 @@ Any Node/TypeScript application using a GPU that `gpu` rents and guards, through
 
 ## Run it
 
-From the directory that holds `jambu.yaml` and `VAST_API_KEY` (in `.env` or the environment), with `jambu-gpu` 0.2.0 or later on `PATH`:
+From the directory that holds `jambu.yaml` and `VAST_API_KEY` (in `.env` or the environment), with `jambu-gpu` 0.3.0 or later on `PATH`:
 
 ```bash
 npm --prefix examples/typescript-client install

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/__init__.py

@@ -1,5 +1,5 @@
 """gpu: provider-agnostic GPU runtime provisioning and lifecycle CLI."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = ["__version__"]

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/cli/_common.py

@@ -118,7 +118,7 @@ def fmt_money(value: Optional[float], suffix: str = "") -> Optional[str]:
 
 
 def register_project(context: Context) -> None:
-    """Put this project in $JAMBU_HOME/projects.json so `gpu sweep` guards it.
+    """Put this project in $GPU_HOME/projects.json so `gpu sweep` guards it.
 
     Done before provisioning: a setup that dies halfway must still leave an
     instance the sweep judges by this project's policy, not as an orphan.

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/cli/account.py

@@ -57,7 +57,7 @@ class Account:
 
 
 def account_credentials(project_dir: Path, profile: str = "default") -> CredentialResolver:
-    """The environment, ./.env, ~/.jambu/credentials, then registered projects' .env.
+    """The environment, ./.env, ~/.gpu/credentials, then registered projects' .env.
 
     The timer runs from ~ without the shell's environment; a key kept only in
     a project's .env must still reach the account-wide orphan sweep.
@@ -196,7 +196,7 @@ def _require_file_credentials(context: Context) -> None:
             raise ConfigError(
                 f"{name} is {where}, so the timer could not use it for {who}: a systemd "
                 f"user unit does not inherit your shell. Put `{name}=...` in "
-                "~/.jambu/credentials (chmod 600), then re-run --install-timer."
+                "~/.gpu/credentials (chmod 600), then re-run --install-timer."
             )
 
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/cli/main.py

@@ -19,7 +19,7 @@ app = typer.Typer(
     name="gpu",
     help=(
         "Provider-agnostic CLI for provisioning and managing temporary GPU runtimes.\n\n"
-        "jambu.yaml is the desired-state source of truth; .jambu/state.json is what "
+        "jambu.yaml is the desired-state source of truth; .gpu/state.json is what "
         "was last observed."
     ),
     no_args_is_help=True,

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/cli/timer.py

@@ -1,9 +1,9 @@
 """systemd *user* units that run `gpu sweep --apply` on a timer.
 
 One ``ExecStart`` covers every project: the sweep guards each project in
-``$JAMBU_HOME/projects.json`` with its own config, so the unit does not depend
+``$GPU_HOME/projects.json`` with its own config, so the unit does not depend
 on its working directory. A user unit needs no root, but it does not inherit
-the shell's environment: credentials must live in ``~/.jambu/credentials`` or
+the shell's environment: credentials must live in ``~/.gpu/credentials`` or
 the project ``.env``. Writing the files is all this module does; enabling them
 is left to the printed ``systemctl`` command.
 """
@@ -64,7 +64,7 @@ def render_units(
         f"TimeoutStartSec={START_TIMEOUT}",
     ]
     if jambu_home:
-        lines.append(_environment("JAMBU_HOME", jambu_home))
+        lines.append(_environment("GPU_HOME", jambu_home))
     # No "-" prefix: a failing sweep must show up as a failed unit.
     lines.append("ExecStart=" + " ".join(_quote(a) for a in [python, "-m", "jambu_gpu", "sweep", "--apply"]))
     lines.append("")
@@ -115,7 +115,9 @@ def install_timer(every_s: float, python: Optional[str] = None) -> dict:
     service_path, timer_path = unit_paths()
     legacy = legacy_guard_configs(service_path)
     service, timer = render_units(
-        every_s=every_s, python=python, jambu_home=os.environ.get("JAMBU_HOME") or None
+        every_s=every_s,
+        python=python,
+        jambu_home=os.environ.get("GPU_HOME") or os.environ.get("JAMBU_HOME") or None,
     )
     service_path.parent.mkdir(parents=True, exist_ok=True)
     service_path.write_text(service)

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/core/config.py

@@ -33,12 +33,12 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 from .durations import parse_duration
 from .errors import ConfigError
+from .paths import project_state_dir
 
 # jambu.yaml (namespaced, shared with other Jambu Lab tools) is searched
 # first; config.yml (flat, gpu-runtime-only) is the legacy fallback.
 CONFIG_FILENAMES = ("jambu.yaml", "jambu.yml", "config.yml", "config.yaml")
 GPU_RUNTIME_KEY = "gpu_runtime"
-STATE_DIRNAME = ".jambu"
 
 # The model catalog (spec: "Choosing a model" doc) - a project's jambu.yaml
 # references one entry by name instead of redeclaring the whole model/compute/
@@ -319,7 +319,7 @@ class RuntimeConfig(_Base):
 
     @property
     def state_dir(self) -> Path:
-        return self.project_dir / STATE_DIRNAME
+        return project_state_dir(self.project_dir)
 
     def fingerprint(self) -> str:
         """Identity of the *desired* runtime.

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/core/credentials.py

@@ -1,7 +1,7 @@
 """Credential resolution (spec section 5).
 
 Credentials never live in jambu.yaml. They are resolved from, in order:
-environment variables, a project-local ``.env``, then ``~/.jambu/credentials``.
+environment variables, a project-local ``.env``, then ``~/.gpu/credentials``.
 The resolution strategy can grow (keychain, secret managers, CI secrets)
 without touching jambu.yaml or any adapter.
 """
@@ -12,6 +12,8 @@ import os
 from pathlib import Path
 from typing import Optional
 
+from .paths import gpu_home
+
 _DOTENV_CACHE: dict[Path, dict[str, str]] = {}
 
 
@@ -46,7 +48,7 @@ class CredentialResolver:
         self.profile = profile
         self.sources: list[tuple[str, Path]] = [
             ("project .env", self.project_dir / ".env"),
-            ("user credentials", Path.home() / ".jambu" / "credentials"),
+            ("user credentials", gpu_home() / "credentials"),
             *(extra_sources or []),
         ]
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/core/events.py

@@ -1,6 +1,6 @@
 """Structured lifecycle events (spec section 24).
 
-Every lifecycle action appends one JSON object to ``.jambu/logs/events.jsonl``
+Every lifecycle action appends one JSON object to ``.gpu/logs/events.jsonl``
 so unexpected GPU cost can always be traced back to a decision and a reason.
 """
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/core/hosts.py

@@ -2,7 +2,7 @@
 
 A host that could not pull the image or reach the network fails the next
 setup the same way, and the cheapest-offer search keeps picking it. Each
-failure is kept for ``BAD_HOST_TTL_S`` in ``$JAMBU_HOME/bad_hosts.json``.
+failure is kept for ``BAD_HOST_TTL_S`` in ``$GPU_HOME/bad_hosts.json``.
 """
 
 from __future__ import annotations

jambu_gpu-0.3.0/jambu_gpu/core/paths.py

@@ -0,0 +1,42 @@
+"""Where gpu keeps its files: ``.gpu/`` in a project, ``~/.gpu`` per user.
+
+Both were named ``.jambu`` before 0.3.0. A legacy directory is renamed in
+place the first time it is needed, so an instance a project already tracks
+is never forgotten (and never rented twice) after an upgrade.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+STATE_DIRNAME = ".gpu"
+LEGACY_STATE_DIRNAME = ".jambu"
+
+
+def adopt_legacy(path: Path, legacy: Path) -> Path:
+    """``path``, after moving ``legacy`` there when only the legacy one exists."""
+    if not path.exists() and legacy.is_dir():
+        try:
+            legacy.rename(path)
+        except OSError:
+            # Read-only or racing another gpu process: keep using the old one.
+            return path if path.exists() else legacy
+    return path
+
+
+def project_state_dir(project_dir: Path) -> Path:
+    project_dir = Path(project_dir)
+    return adopt_legacy(project_dir / STATE_DIRNAME, project_dir / LEGACY_STATE_DIRNAME)
+
+
+def gpu_home() -> Path:
+    """Per-user files: the project registry, sweep sightings, bad hosts, credentials.
+
+    ``$GPU_HOME`` overrides it (``$JAMBU_HOME`` is still honored).
+    """
+    override = os.environ.get("GPU_HOME") or os.environ.get("JAMBU_HOME")
+    if override:
+        return Path(override).expanduser()
+    home = Path.home()
+    return adopt_legacy(home / STATE_DIRNAME, home / LEGACY_STATE_DIRNAME)

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/core/state.py

@@ -1,6 +1,6 @@
 """Observed runtime state (spec section 9).
 
-jambu.yaml is the desired-state SoT; ``.jambu/state.json`` is what we last
+jambu.yaml is the desired-state SoT; ``.gpu/state.json`` is what we last
 observed. This module owns reading/writing it atomically, plus the on-disk
 process lock that keeps two CLI invocations from provisioning twice.
 """
@@ -312,7 +312,7 @@ class RuntimeState:
 
 
 class StateStore:
-    """Atomic reader/writer for ``.jambu/state.json``."""
+    """Atomic reader/writer for ``.gpu/state.json``."""
 
     def __init__(self, state_dir: Path) -> None:
         self._depth = 0  # flock is per-open-file-description: keep it reentrant

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/jambu_gpu/core/sweep.py

@@ -4,7 +4,7 @@ The watchdog guards one instance from the inside and `gpu guard` guards the
 one instance a project tracks. The sweep covers every project on this machine
 and whatever is left over:
 
-- every project registered in ``$JAMBU_HOME/projects.json`` (by `gpu setup`)
+- every project registered in ``$GPU_HOME/projects.json`` (by `gpu setup`)
   gets its own ``Engine.guard_tick``, with its own config and state: its own
   max_lifetime, lock, session and stopped_ttl. Those instances are *tracked*;
 - an instance no project tracks is an *orphan*. Nobody knows its policy or
@@ -14,7 +14,7 @@ and whatever is left over:
   ago is destroyed.
 
 Providers do not report when an instance stopped, so the first time the sweep
-saw each orphan stopped is kept in ``$JAMBU_HOME/sweep.json``.
+saw each orphan stopped is kept in ``$GPU_HOME/sweep.json``.
 """
 
 from __future__ import annotations
@@ -30,7 +30,8 @@ from typing import Any, Callable, Iterator, Optional
 
 from . import events as ev
 from . import policy
-from .config import STATE_DIRNAME, load_config
+from .config import load_config
+from .paths import gpu_home, project_state_dir
 from .errors import JambuError, ProviderError
 from .events import EventLog
 from .models import Instance, InstanceState, is_jambu_label
@@ -46,8 +47,7 @@ SWEEP_ACTION = "sweep_action"
 
 
 def jambu_home() -> Path:
-    override = os.environ.get("JAMBU_HOME")
-    return Path(override).expanduser() if override else Path.home() / ".jambu"
+    return gpu_home()
 
 
 class SweepRegistry:
@@ -198,7 +198,7 @@ class ProjectGuard:
 
 def _state_beside(config_path: Path) -> Optional[RuntimeState]:
     """The project's state read straight from disk (no API call)."""
-    store = StateStore(Path(config_path).parent / STATE_DIRNAME)
+    store = StateStore(project_state_dir(Path(config_path).parent))
     try:
         return store.load() if store.exists() else None
     except JambuError:

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jambu-gpu"
-version = "0.2.0"
+version = "0.3.0"
 description = "Provider-agnostic CLI for provisioning and managing temporary GPU runtimes"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -36,7 +36,7 @@ gpu = "jambu_gpu.cli.main:main"
 packages = ["jambu_gpu"]
 
 [tool.hatch.build.targets.sdist]
-exclude = ["/.env", "/.venv", "/.jambu"]
+exclude = ["/.env", "/.venv", "/.gpu", "/.jambu"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/tests/conftest.py

@@ -29,9 +29,10 @@ BASE_CONFIG = {
 
 @pytest.fixture(autouse=True)
 def jambu_home(tmp_path, monkeypatch):
-    """Keep the project registry and sweep state out of the real ~/.jambu."""
-    home = tmp_path / "jambu-home"
-    monkeypatch.setenv("JAMBU_HOME", str(home))
+    """Keep the project registry and sweep state out of the real ~/.gpu."""
+    home = tmp_path / "gpu-home"
+    monkeypatch.setenv("GPU_HOME", str(home))
+    monkeypatch.delenv("JAMBU_HOME", raising=False)
     return home
 
 

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/tests/test_config.py

@@ -100,7 +100,7 @@ def test_fingerprint_tracks_runtime_identity(write_config):
 
 
 def test_state_dir_sits_next_to_the_config(config):
-    assert config.state_dir == config.source_path.parent / ".jambu"
+    assert config.state_dir == config.source_path.parent / ".gpu"
 
 
 # -- jambu.yaml shared-manifest namespacing ----------------------------------

jambu_gpu-0.3.0/tests/test_paths.py

@@ -0,0 +1,50 @@
+"""Files live in .gpu/ and ~/.gpu; a legacy .jambu is adopted, never forgotten."""
+
+from __future__ import annotations
+
+from jambu_gpu.core.paths import gpu_home, project_state_dir
+from jambu_gpu.core.state import RuntimeState, StateStore
+
+
+def test_a_new_project_keeps_its_state_in_dot_gpu(tmp_path):
+    assert project_state_dir(tmp_path) == tmp_path / ".gpu"
+
+
+def test_a_project_from_before_0_3_keeps_its_instance(tmp_path):
+    StateStore(tmp_path / ".jambu").save(RuntimeState(provider="vast", instance_id="42", state="ready"))
+
+    state_dir = project_state_dir(tmp_path)
+
+    assert state_dir == tmp_path / ".gpu"
+    assert not (tmp_path / ".jambu").exists()
+    assert StateStore(state_dir).load().instance_id == "42"
+
+
+def test_both_present_means_dot_gpu_wins_and_the_legacy_is_left_alone(tmp_path):
+    (tmp_path / ".gpu").mkdir()
+    (tmp_path / ".jambu").mkdir()
+    assert project_state_dir(tmp_path) == tmp_path / ".gpu"
+    assert (tmp_path / ".jambu").is_dir()
+
+
+def test_the_user_home_moves_from_dot_jambu(tmp_path, monkeypatch):
+    monkeypatch.delenv("GPU_HOME", raising=False)
+    monkeypatch.delenv("JAMBU_HOME", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path))
+    (tmp_path / ".jambu").mkdir()
+    (tmp_path / ".jambu" / "projects.json").write_text("[]")
+
+    assert gpu_home() == tmp_path / ".gpu"
+    assert (tmp_path / ".gpu" / "projects.json").read_text() == "[]"
+
+
+def test_gpu_home_and_the_legacy_jambu_home_override_it(tmp_path, monkeypatch):
+    monkeypatch.delenv("GPU_HOME", raising=False)
+    monkeypatch.setenv("JAMBU_HOME", str(tmp_path / "old"))
+    assert gpu_home() == tmp_path / "old"
+    monkeypatch.setenv("GPU_HOME", str(tmp_path / "new"))
+    assert gpu_home() == tmp_path / "new"
+
+
+def test_a_config_resolves_its_state_dir_to_dot_gpu(config):
+    assert config.state_dir == config.project_dir / ".gpu"

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/tests/test_state.py

@@ -11,7 +11,7 @@ from jambu_gpu.core.state import RuntimeState, StateStore, WorkloadRecord, utc_n
 
 @pytest.fixture
 def store(tmp_path) -> StateStore:
-    return StateStore(tmp_path / ".jambu")
+    return StateStore(tmp_path / ".gpu")
 
 
 def test_empty_state_is_not_an_error(store):

{jambu_gpu-0.2.0 → jambu_gpu-0.3.0}/tests/test_sweep.py

@@ -549,8 +549,8 @@ def home(tmp_path, monkeypatch):
 
 
 @pytest.fixture
-def credentials_file(home):
-    path = home / ".jambu" / "credentials"
+def credentials_file(home, jambu_home):
+    path = jambu_home / "credentials"
     path.parent.mkdir(parents=True)
     path.write_text("VAST_API_KEY=from-file\n")
     return path
@@ -570,7 +570,7 @@ def test_install_timer_writes_one_unit_independent_of_the_project(
     assert execs == [f"ExecStart={sys.executable} -m jambu_gpu sweep --apply"]  # no "-"
     assert "WorkingDirectory=~" in service
     assert "TimeoutStartSec=10min" in service
-    assert f'Environment="JAMBU_HOME={jambu_home}"' in service
+    assert f'Environment="GPU_HOME={jambu_home}"' in service
     assert "Type=oneshot" in service
     assert "OnUnitActiveSec=600s" in timer
     assert "WantedBy=timers.target" in timer
@@ -623,7 +623,7 @@ def test_install_timer_refuses_a_key_only_in_the_shell_environment(config, home,
     result = runner.invoke(app, ["sweep", "--install-timer"])
     assert result.exit_code == 2
     message = " ".join(result.output.split())
-    assert "~/.jambu/credentials" in message and "VAST_API_KEY" in message
+    assert "~/.gpu/credentials" in message and "VAST_API_KEY" in message
     assert not (home / ".config/systemd/user/jambu-gpu-sweep.service").exists()
 
 
@@ -641,7 +641,7 @@ def test_unit_values_escape_percent_and_dollar_and_quote_spaces():
         every_s=300, python="/opt/my env/100%/py$thon", jambu_home="/data/50% \"x\""
     )
     assert 'ExecStart="/opt/my env/100%%/py$$thon" -m jambu_gpu sweep --apply' in service
-    assert 'Environment="JAMBU_HOME=/data/50%% \\"x\\""' in service
+    assert 'Environment="GPU_HOME=/data/50%% \\"x\\""' in service
     assert "Environment" not in timer_mod.render_units(every_s=300, python="/p")[0]