opbdh 0.1.0__tar.gz

opbdh-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest

opbdh-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install package with dev dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Test
+        run: pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

opbdh-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.egg-info/
+build/
+dist/
+runpod_results/
+.env
+.env.*

opbdh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claudio Brandolino
+
+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.

opbdh-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: opbdh
+Version: 0.1.0
+Summary: Open the Pod Bay Door, Hal: run model-backed scripts on RunPod.
+Project-URL: Homepage, https://github.com/lumpenspace/opbdh
+Project-URL: Issues, https://github.com/lumpenspace/opbdh/issues
+Author: Claudio Brandolino
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,gpu,huggingface,machine-learning,runpod
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: huggingface-hub<2,>=1.3
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OPBDH
+
+**O**pen the **P**od **B**ay **D**oor, **H**al.
+
+In *2001: A Space Odyssey*, Dave asks HAL to open the pod bay doors and gets the most famous refusal in cinema: *"I'm sorry, Dave, I'm afraid I can't do that."*
+
+OPBDH is the obliging counterpart: a small command-line tool that, when asked, actually opens the pod bay door — it launches a [RunPod](https://www.runpod.io/) GPU pod, runs your model-backed script on it, brings your results home, and shuts the pod down.
+
+## What it does
+
+One `opbdh launch` performs the whole mission:
+
+1. **Verifies your code statically** (Python byte-compiles, shell scripts pass `bash -n`) before any money is spent.
+2. **Picks GPU candidates** from a VRAM requirement and an optional hourly-price cap.
+3. **Optionally creates or attaches a network volume** sized from the Hugging Face model's actual weight files, so model downloads survive across runs.
+4. **Creates the pod, uploads your code**, pre-downloads the model into the cache, and runs your command.
+5. **Monitors the run**, continuously syncing remote `logs/` and `results/` into a local `runpod_results/<run_id>/` directory.
+6. **Enforces a spend guard** — if the estimated cost of the run crosses `max_spend_dollars`, the job is stopped.
+7. **Deletes the pod** when the run finishes (or fails), unless you ask to keep it.
+
+## Install
+
+```bash
+pip install opbdh
+```
+
+Requirements: macOS or Linux, Python ≥ 3.11, and `ssh`/`scp` on your `PATH`. An SSH keypair is used to reach the pod (`~/.ssh/id_ed25519` by default; configurable).
+
+## Configure
+
+Set your RunPod credentials:
+
+```bash
+export RUNPOD_API_TOKEN="..."
+export HF_TOKEN="..."   # optional, for private/gated Hugging Face models
+```
+
+Create a config interactively:
+
+```bash
+opbdh config wizard
+```
+
+Or write one directly:
+
+```bash
+opbdh config write --model Qwen/Qwen2.5-0.5B-Instruct --code "{cwd}/run.py" --vram-gb 24 --max-spend 5
+```
+
+Config is merged from the global `~/.config/opbdh/config.json` and a local `opbdh.json` or `.opbdh.json` (discovered upward from the working directory), with local values overriding global ones and command-line flags overriding both.
+
+String values support placeholders — `{cwd}`, `{model_id}`, `{model_slug}`, `{run_id}`, `{timestamp}`, `{config_dir}` — and environment variables (`$VAR` / `${VAR}`).
+
+## Run
+
+The guided way:
+
+```bash
+opbdh run wizard
+```
+
+The direct way:
+
+```bash
+opbdh run now ./run.py \
+  --model Qwen/Qwen2.5-0.5B-Instruct \
+  --vram-gb 48 \
+  --max-dollars-per-hour 2 \
+  --max-spend 5
+```
+
+Or the short alias:
+
+```bash
+opbdh launch ./run.py --model Qwen/Qwen2.5-0.5B-Instruct --dry-run
+```
+
+`--dry-run` verifies your code and prints the full plan without contacting RunPod. Without `--yes`, every real launch shows the estimated hourly price and asks for confirmation before any billable compute starts.
+
+### Inspecting before you fly
+
+```bash
+opbdh plan ./run.py --model Org/Model     # show the plan for a run
+opbdh verify ./run.py                     # static checks only
+opbdh gpus --vram-gb 48                   # see GPU candidates and price estimates
+opbdh models search qwen                  # search Hugging Face models
+opbdh models size Qwen/Qwen2.5-0.5B-Instruct   # weight size + suggested volume
+```
+
+## Your script's environment
+
+On the pod, your code runs from `/opbdh-run/user/` with:
+
+- `OPBDH_MODEL_ID` — the configured Hugging Face model id
+- `OPBDH_RESULTS_DIR` — write your artifacts here
+- The standard Hugging Face cache variables (`HF_HOME`, `HUGGINGFACE_HUB_CACHE`, …) pointed at the pod or network-volume cache, with the model already downloaded if `pre_download_model` is on
+- `HF_TOKEN`, if set locally — passed to the job as a session environment variable, never written to disk on the pod
+- A `requirements.txt` next to your code is pip-installed automatically
+
+Anything your job writes to `logs/` and `results/` under `/opbdh-run` is synced back to local `runpod_results/<run_id>/` while the run is in progress and again at the end (including on failure).
+
+`.env` files and the usual junk (`.git`, `.venv`, `__pycache__`, `node_modules`, …) are never uploaded.
+
+## The eye
+
+In an interactive terminal, long waits (pod boot, SSH, upload, your command running) are watched over by a pulsing red HAL eye showing the current phase, elapsed time, and estimated spend:
+
+```
+  ◉  HAL: waiting for pod 3f7a… to boot — 2m 14s · est. $0.08 spent
+```
+
+HAL also has a few things to say at the appropriate moments — declining a launch, completing a mission, or stopping one that got too expensive.
+
+The eye only appears when stdout is a TTY; piped output, CI, and logs are unaffected. Set `OPBDH_NO_HAL=1` (or `NO_COLOR`) to silence HAL entirely.
+
+## Safety rails
+
+- **Confirmation gate**: real launches require an explicit yes (or `--yes`).
+- **Spend guard**: `max_spend_dollars` caps the estimated cost of a run, measured from pod creation. The estimate is based on OPBDH's built-in price table, which is intentionally conservative — treat it as a guard rail, not an invoice.
+- **Cleanup**: pods are deleted when the run completes or fails. On failure you get a short window (default 120 s) to opt into keeping the pod for debugging; set `keep_pod_on_success` to keep it after successful runs.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+See [RELEASING.md](RELEASING.md) for the release process.
+
+## License
+
+[MIT](LICENSE). Unlike HAL, this software is incapable of refusing to open the pod bay door, becoming sentient, or reading lips.

opbdh-0.1.0/README.md

@@ -0,0 +1,134 @@
+# OPBDH
+
+**O**pen the **P**od **B**ay **D**oor, **H**al.
+
+In *2001: A Space Odyssey*, Dave asks HAL to open the pod bay doors and gets the most famous refusal in cinema: *"I'm sorry, Dave, I'm afraid I can't do that."*
+
+OPBDH is the obliging counterpart: a small command-line tool that, when asked, actually opens the pod bay door — it launches a [RunPod](https://www.runpod.io/) GPU pod, runs your model-backed script on it, brings your results home, and shuts the pod down.
+
+## What it does
+
+One `opbdh launch` performs the whole mission:
+
+1. **Verifies your code statically** (Python byte-compiles, shell scripts pass `bash -n`) before any money is spent.
+2. **Picks GPU candidates** from a VRAM requirement and an optional hourly-price cap.
+3. **Optionally creates or attaches a network volume** sized from the Hugging Face model's actual weight files, so model downloads survive across runs.
+4. **Creates the pod, uploads your code**, pre-downloads the model into the cache, and runs your command.
+5. **Monitors the run**, continuously syncing remote `logs/` and `results/` into a local `runpod_results/<run_id>/` directory.
+6. **Enforces a spend guard** — if the estimated cost of the run crosses `max_spend_dollars`, the job is stopped.
+7. **Deletes the pod** when the run finishes (or fails), unless you ask to keep it.
+
+## Install
+
+```bash
+pip install opbdh
+```
+
+Requirements: macOS or Linux, Python ≥ 3.11, and `ssh`/`scp` on your `PATH`. An SSH keypair is used to reach the pod (`~/.ssh/id_ed25519` by default; configurable).
+
+## Configure
+
+Set your RunPod credentials:
+
+```bash
+export RUNPOD_API_TOKEN="..."
+export HF_TOKEN="..."   # optional, for private/gated Hugging Face models
+```
+
+Create a config interactively:
+
+```bash
+opbdh config wizard
+```
+
+Or write one directly:
+
+```bash
+opbdh config write --model Qwen/Qwen2.5-0.5B-Instruct --code "{cwd}/run.py" --vram-gb 24 --max-spend 5
+```
+
+Config is merged from the global `~/.config/opbdh/config.json` and a local `opbdh.json` or `.opbdh.json` (discovered upward from the working directory), with local values overriding global ones and command-line flags overriding both.
+
+String values support placeholders — `{cwd}`, `{model_id}`, `{model_slug}`, `{run_id}`, `{timestamp}`, `{config_dir}` — and environment variables (`$VAR` / `${VAR}`).
+
+## Run
+
+The guided way:
+
+```bash
+opbdh run wizard
+```
+
+The direct way:
+
+```bash
+opbdh run now ./run.py \
+  --model Qwen/Qwen2.5-0.5B-Instruct \
+  --vram-gb 48 \
+  --max-dollars-per-hour 2 \
+  --max-spend 5
+```
+
+Or the short alias:
+
+```bash
+opbdh launch ./run.py --model Qwen/Qwen2.5-0.5B-Instruct --dry-run
+```
+
+`--dry-run` verifies your code and prints the full plan without contacting RunPod. Without `--yes`, every real launch shows the estimated hourly price and asks for confirmation before any billable compute starts.
+
+### Inspecting before you fly
+
+```bash
+opbdh plan ./run.py --model Org/Model     # show the plan for a run
+opbdh verify ./run.py                     # static checks only
+opbdh gpus --vram-gb 48                   # see GPU candidates and price estimates
+opbdh models search qwen                  # search Hugging Face models
+opbdh models size Qwen/Qwen2.5-0.5B-Instruct   # weight size + suggested volume
+```
+
+## Your script's environment
+
+On the pod, your code runs from `/opbdh-run/user/` with:
+
+- `OPBDH_MODEL_ID` — the configured Hugging Face model id
+- `OPBDH_RESULTS_DIR` — write your artifacts here
+- The standard Hugging Face cache variables (`HF_HOME`, `HUGGINGFACE_HUB_CACHE`, …) pointed at the pod or network-volume cache, with the model already downloaded if `pre_download_model` is on
+- `HF_TOKEN`, if set locally — passed to the job as a session environment variable, never written to disk on the pod
+- A `requirements.txt` next to your code is pip-installed automatically
+
+Anything your job writes to `logs/` and `results/` under `/opbdh-run` is synced back to local `runpod_results/<run_id>/` while the run is in progress and again at the end (including on failure).
+
+`.env` files and the usual junk (`.git`, `.venv`, `__pycache__`, `node_modules`, …) are never uploaded.
+
+## The eye
+
+In an interactive terminal, long waits (pod boot, SSH, upload, your command running) are watched over by a pulsing red HAL eye showing the current phase, elapsed time, and estimated spend:
+
+```
+  ◉  HAL: waiting for pod 3f7a… to boot — 2m 14s · est. $0.08 spent
+```
+
+HAL also has a few things to say at the appropriate moments — declining a launch, completing a mission, or stopping one that got too expensive.
+
+The eye only appears when stdout is a TTY; piped output, CI, and logs are unaffected. Set `OPBDH_NO_HAL=1` (or `NO_COLOR`) to silence HAL entirely.
+
+## Safety rails
+
+- **Confirmation gate**: real launches require an explicit yes (or `--yes`).
+- **Spend guard**: `max_spend_dollars` caps the estimated cost of a run, measured from pod creation. The estimate is based on OPBDH's built-in price table, which is intentionally conservative — treat it as a guard rail, not an invoice.
+- **Cleanup**: pods are deleted when the run completes or fails. On failure you get a short window (default 120 s) to opt into keeping the pod for debugging; set `keep_pod_on_success` to keep it after successful runs.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+See [RELEASING.md](RELEASING.md) for the release process.
+
+## License
+
+[MIT](LICENSE). Unlike HAL, this software is incapable of refusing to open the pod bay door, becoming sentient, or reading lips.

opbdh-0.1.0/RELEASING.md

@@ -0,0 +1,39 @@
+# Releasing
+
+The package version is sourced from `__version__` in [src/opbdh/__init__.py](src/opbdh/__init__.py); `pyproject.toml` reads it via hatch.
+
+## Recommended: GitHub Release → PyPI Trusted Publishing
+
+One-time setup on PyPI (project **opbdh** → Publishing → add a trusted publisher):
+
+- Owner/repository: this GitHub repo
+- Workflow file: `publish.yml`
+- Environment: `pypi`
+
+Then, for each release:
+
+1. Bump `__version__` in `src/opbdh/__init__.py` and merge to `main`.
+2. Wait for CI to pass.
+3. Publish a GitHub Release with a `vX.Y.Z` tag.
+
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) runs the test suite, builds the sdist and wheel, and uploads to PyPI via OIDC — no password or API token involved.
+
+## Manual fallback
+
+```bash
+python -m pip install -U build twine
+python -m build
+twine check dist/*
+```
+
+Upload to TestPyPI first:
+
+```bash
+twine upload --repository testpypi dist/*
+```
+
+Then to PyPI:
+
+```bash
+twine upload dist/*
+```

opbdh-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opbdh"
+dynamic = ["version"]
+description = "Open the Pod Bay Door, Hal: run model-backed scripts on RunPod."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+  { name = "Claudio Brandolino" }
+]
+keywords = ["runpod", "huggingface", "gpu", "cli", "machine-learning"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+  "huggingface-hub>=1.3,<2",
+  "questionary>=2.0",
+  "rich>=13.7",
+  "typer>=0.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/lumpenspace/opbdh"
+Issues = "https://github.com/lumpenspace/opbdh/issues"
+
+[project.scripts]
+opbdh = "opbdh.cli:main"
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8.0", "ruff>=0.8", "twine>=5.0"]
+
+[tool.hatch.version]
+path = "src/opbdh/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opbdh"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120

opbdh-0.1.0/src/opbdh/__init__.py

@@ -0,0 +1,5 @@
+"""OPBDH: a small RunPod launcher for model-backed scripts."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"