jambu-gpu 0.1.0__py3-none-any.whl

jambu_gpu/watchdog/builder.py

@@ -0,0 +1,178 @@
+"""Assembles the remote watchdog into a single self-contained script.
+
+The lifecycle *policy* is owned by the core and inlined verbatim from
+``core/policy.py`` so the remote guard and `gpu status` can never
+disagree. The *provider actions* are injected by the adapter. Neither side
+knows about the other.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import zlib
+import secrets
+from pathlib import Path
+from typing import Optional
+
+from ..core import policy as policy_module
+from ..providers.base import WatchdogSpec
+
+AGENT_REMOTE_PATH = "/opt/jambu/watchdog.py"
+CONFIG_REMOTE_PATH = "/etc/jambu/watchdog.json"
+STATE_REMOTE_PATH = "/var/lib/jambu/activity.json"
+EVENTS_REMOTE_PATH = "/var/log/jambu/events.jsonl"
+WATCHDOG_LOG_PATH = "/var/log/jambu/watchdog.log"
+
+_HEADER = """#!/usr/bin/env python3
+# Generated by jambu-gpu. Do not edit on the instance.
+# Lifecycle policy is inlined from jambu_gpu/core/policy.py.
+from __future__ import annotations
+"""
+
+_FUTURE_IMPORT = "from __future__ import annotations"
+
+_FALLBACK_ACTIONS = '''
+def provider_stop(ctx):
+    raise RuntimeError("this provider supplied no stop action")
+
+
+def provider_destroy(ctx):
+    raise RuntimeError("this provider supplied no destroy action")
+'''
+
+
+def generate_token() -> str:
+    """Shared secret protecting the watchdog's public control port."""
+    return secrets.token_urlsafe(32)
+
+
+def _strip_future(source: str) -> str:
+    return "\n".join(
+        line for line in source.splitlines() if line.strip() != _FUTURE_IMPORT
+    )
+
+
+def build_agent_source(actions_source: Optional[str] = None) -> str:
+    """Return the full stdlib-only watchdog script."""
+    policy_source = _strip_future(Path(policy_module.__file__).read_text())
+    body_source = _strip_future((Path(__file__).parent / "agent_body.py").read_text())
+    actions = _strip_future(actions_source) if actions_source else _FALLBACK_ACTIONS
+    return "\n\n".join(
+        [
+            _HEADER,
+            "# --- inlined: jambu_gpu/core/policy.py ---",
+            policy_source,
+            "# --- injected: provider actions ---",
+            actions,
+            "# --- inlined: jambu_gpu/watchdog/agent_body.py ---",
+            body_source,
+        ]
+    )
+
+
+def build_agent_config(
+    *,
+    provider: str,
+    instance_id: str,
+    token: str,
+    port: int,
+    interval_s: float,
+    startup_grace_s: float,
+    policy: "policy_module.PolicyConfig",
+    created_at: float,
+    watchdog_spec: Optional[WatchdogSpec] = None,
+) -> dict:
+    return {
+        "provider": provider,
+        "instance_id": instance_id,
+        "token": token,
+        "port": int(port),
+        "interval_s": float(interval_s),
+        "startup_grace_s": float(startup_grace_s),
+        "created_at": float(created_at),
+        "policy": policy.to_dict(),
+        "env": dict(watchdog_spec.env) if watchdog_spec else {},
+        "provider_context": dict(watchdog_spec.context) if watchdog_spec else {},
+    }
+
+
+def _b64(text: str) -> str:
+    return base64.b64encode(text.encode()).decode()
+
+
+def _b64_gz_block(text: str, width: int = 76) -> str:
+    """Compressed, line-wrapped payload.
+
+    The boot script travels inside a provider API field, so the ~29 KB agent is
+    deflated to ~9 KB and wrapped, instead of riding on one enormous line.
+    """
+    blob = base64.b64encode(zlib.compress(text.encode(), 9)).decode()
+    return "\n".join(blob[i : i + width] for i in range(0, len(blob), width))
+
+
+def build_onstart_script(
+    *,
+    agent_source: str,
+    agent_config: dict,
+    runtime_start_command: str,
+    runtime_env: Optional[dict] = None,
+    watchdog_enabled: bool = True,
+) -> str:
+    """Bash executed on the instance right after the container comes up.
+
+    Order matters: the watchdog starts FIRST so an instance whose model server
+    fails to boot is still protected by idle/max_lifetime rules.
+    """
+    lines = [
+        "#!/bin/bash",
+        "# Generated by jambu-gpu",
+        "set -u",
+        # mkdir first: a failed `exec` redirect would kill a non-interactive shell.
+        "mkdir -p /etc/jambu /var/lib/jambu /var/log/jambu /var/run/jambu /opt/jambu",
+        "exec >> /var/log/jambu/onstart.log 2>&1",
+        "date -u +'[%Y-%m-%dT%H:%M:%SZ] jambu onstart begin'",
+    ]
+
+    for key, value in (runtime_env or {}).items():
+        lines.append(f"export {key}={_shell_quote(str(value))}")
+        lines.append(f"echo {_shell_quote(f'{key}={value}')} >> /etc/jambu/runtime.env")
+
+    if watchdog_enabled:
+        decode = (
+            "import base64,zlib;"
+            f"open({AGENT_REMOTE_PATH!r},'wb').write("
+            f"zlib.decompress(base64.b64decode(open('{AGENT_REMOTE_PATH}.b64','rb').read())))"
+        )
+        lines += [
+            "",
+            "# --- lifecycle watchdog (survives local CLI death) ---",
+            f"echo {_b64(json.dumps(agent_config))} | base64 -d > {CONFIG_REMOTE_PATH}",
+            f"chmod 600 {CONFIG_REMOTE_PATH}",
+            "PYBIN=$(command -v python3 || command -v python)",
+            'if [ -z "$PYBIN" ]; then',
+            '  echo "jambu: no python interpreter in this image; watchdog NOT installed"',
+            "else",
+            f"  cat > {AGENT_REMOTE_PATH}.b64 <<'JAMBU_AGENT_EOF'",
+            _b64_gz_block(agent_source),
+            "JAMBU_AGENT_EOF",
+            f'  "$PYBIN" -c {_shell_quote(decode)}',
+            f"  rm -f {AGENT_REMOTE_PATH}.b64",
+            f"  chmod 700 {AGENT_REMOTE_PATH}",
+            f'  nohup "$PYBIN" -u {AGENT_REMOTE_PATH} >> {WATCHDOG_LOG_PATH} 2>&1 &',
+            "  echo $! > /var/run/jambu/watchdog.pid",
+            '  echo "jambu: watchdog started pid $(cat /var/run/jambu/watchdog.pid)"',
+            "fi",
+        ]
+
+    lines += [
+        "",
+        "# --- model runtime ---",
+        runtime_start_command,
+        "date -u +'[%Y-%m-%dT%H:%M:%SZ] jambu onstart done'",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def _shell_quote(value: str) -> str:
+    return "'" + value.replace("'", "'\"'\"'") + "'"

jambu_gpu-0.1.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: jambu-gpu
+Version: 0.1.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.
+
+The API key is read from the environment, a project `.env`, or `~/.jambu/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
+
+- [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.1.0.dist-info/RECORD

@@ -0,0 +1,46 @@
+jambu_gpu/__init__.py,sha256=P6KIiXguhDm9CeGcw3foqcxAKa7aFoolINxlBiNEBlo,123
+jambu_gpu/__main__.py,sha256=dBCaXiNWd2Tv9A9tb_B9kJG2OOY-b5FpWYwRyV1yQso,66
+jambu_gpu/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jambu_gpu/cli/_common.py,sha256=GdE_B1PexSPA8ErlmtGbeih8BpSjnQKJ21OhUYfahLA,3308
+jambu_gpu/cli/inspect.py,sha256=wXYuIKO_j6Hgmp7GJ_gwUo5_lPmsyDtRS-oKUtrh7GQ,8085
+jambu_gpu/cli/lifecycle.py,sha256=zmgkUJNK9DSdzTumxDKW-gwyiIAjTaUOM00U8kpZy_M,3862
+jambu_gpu/cli/main.py,sha256=1gLANCnlxQVDPlUpHI5-8zLm-SWv1XTgbE6t6m37w8c,3083
+jambu_gpu/cli/providers.py,sha256=vDR5SgxsMVLWpZsdSLKuJy8qOUxv1M7-IHIJUCnAleI,3058
+jambu_gpu/cli/run.py,sha256=Pcgyt-w76y01S1h8EXtPsUQBX9pDJQdwaPd_daf-T2Y,1180
+jambu_gpu/cli/setup.py,sha256=a6uyzyNLWC8iLMifnJrbDqL9DTCveYKYR72ZNqBABj8,5473
+jambu_gpu/cli/status.py,sha256=Veq5xcupz4XhR8GDvkoXvwkiPKpPz-5eOh9N1ayLG1k,6931
+jambu_gpu/cli/validate.py,sha256=9DFh8TLIcvPIct5FQk78VPfW29PMqkOcij8N_F8yXHs,2081
+jambu_gpu/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jambu_gpu/core/beacon.py,sha256=9brx1I4vH-yIKHmKdNdB4qUSngSfW8mnKxrO7cbh0SY,4400
+jambu_gpu/core/config.py,sha256=rTSHJDIaoulGWOmxX6cJ0rKOhOdEAbfhHSUqaCq9R5Q,20463
+jambu_gpu/core/credentials.py,sha256=5sqo1rJoRS0Cu5ZijWuYYH8ZAJb6EVVBew4y0pMilcM,2532
+jambu_gpu/core/durations.py,sha256=4-Gq--HNOBGXLLWQHssC08gkQwQjT_3oBHD4ootHKxs,1645
+jambu_gpu/core/engine.py,sha256=EmLAVAIuHbETqOeF7ZvxB4yQfj52D2LeCYnbj2dsvhA,39545
+jambu_gpu/core/errors.py,sha256=4TjV6YuJh7ocMLjER5WG6X6NPIH01K8zGJfUoYMOLOc,1435
+jambu_gpu/core/events.py,sha256=vKO1GONEL6x-juaSlA717Z3n_vc_FkcXMabElBVGKV4,4013
+jambu_gpu/core/execution.py,sha256=6cXL-QbYg7rDeIpMwgTl9uAUh9LhEwtfyST1l_QfADk,5689
+jambu_gpu/core/health.py,sha256=nbd4JNvNF7-Lpd58Ce_48J7A5Sob3gek6ihv9Q36nkk,1909
+jambu_gpu/core/model_inspect.py,sha256=vb22jQ0NaSOsKrKWE4BlxXgbh26_qMhRMsAHYLVofCA,15615
+jambu_gpu/core/models.py,sha256=KkZMNduegE49Lcx9f4mo65Bj4o7KobrUH4zyrKawibk,7619
+jambu_gpu/core/policy.py,sha256=H1-NxNgndmLMVxCE6UdwHbsdcY3JxTILXYLV-Uw25Ko,8214
+jambu_gpu/core/state.py,sha256=DoLLc9giZW9qN20EYI-G9eOVi0Nlt3zRS6NHxdamJTY,13498
+jambu_gpu/core/tool_parsers.py,sha256=zqaVJ0-m0H3B9gEhhe3-gWm7nhpwp9OBMAAsBx-Odu8,2475
+jambu_gpu/providers/__init__.py,sha256=qM_BUMeabdamPdHTQHcSfp8okfjidkGhj2y_YUpBbMg,168
+jambu_gpu/providers/base.py,sha256=UpPdyCvdk-hTdtXtHzdeo-Ut-kZPpIm4WurAHGxV5kQ,4582
+jambu_gpu/providers/registry.py,sha256=tj63zPcEPmUxVLqHFiFIesS_rWes0B45mOwLmjilanE,2032
+jambu_gpu/providers/vast/__init__.py,sha256=LPaQrruQaRu59u7IMrOkx2eNb_176vcN9DGvevL8E4g,63
+jambu_gpu/providers/vast/client.py,sha256=MMRYcmoI8tZJ1DAQs2x9lgtPqjVxG7z2Wr469busm5I,9158
+jambu_gpu/providers/vast/config.py,sha256=_R6fWMa4lTFKbPAlpyHZhzfE96OWuVTH803tjNL9mQo,1749
+jambu_gpu/providers/vast/mapper.py,sha256=2Z0GW6MMAw8_rxKbwppPq7PLyvEZNvylYXzvUJCLalA,8284
+jambu_gpu/providers/vast/provider.py,sha256=z17MRLtrJRaTmEWl9kgHCPVLtSCYwor547hbAqS1ttA,16123
+jambu_gpu/runtime/__init__.py,sha256=ncpE8jTc_dX4cVlO3IBKg5vDv-n1TREKj4aksisqTDM,218
+jambu_gpu/runtime/base.py,sha256=p3s1hyq_iKu5XTT9gwMj27m9iTTbIPw613nMO_C_M3U,2878
+jambu_gpu/runtime/vllm.py,sha256=egfoGsRQiLQlr825wmZtIhsl0lLPGghWD-O85INaO-I,9117
+jambu_gpu/watchdog/__init__.py,sha256=79yCptDKSE8dA-PowfQzcxrNaK6eEqhe_WDTi9BR_Fk,154
+jambu_gpu/watchdog/agent_body.py,sha256=OET5tmEsG-cvb3T5af9XxP3GBlFAH-rvYQDakw0fp5E,18288
+jambu_gpu/watchdog/builder.py,sha256=FAW_173EQYKA0Ffp-wHfzI-Gsil4WfjCXExvLePvUCs,5995
+jambu_gpu-0.1.0.dist-info/METADATA,sha256=dJ68OrIKbvYgUxwflGI9fLAF9FD9gFB1KEA2R9J_YRY,2406
+jambu_gpu-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+jambu_gpu-0.1.0.dist-info/entry_points.txt,sha256=y8w6NcSvrjLN56L88UuDEUWbryOp9aMr52rm_dESU1g,48
+jambu_gpu-0.1.0.dist-info/licenses/LICENSE,sha256=7ofvt29ghOnzKapRr48K5JoCiQNnA5AcGFu6fSrtmSQ,1088
+jambu_gpu-0.1.0.dist-info/RECORD,,

jambu_gpu-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

jambu_gpu-0.1.0.dist-info/entry_points.txt

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

jambu_gpu-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jambu.ai and João Gabriel Lima
+
+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.