alloc 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alloc
-Version: 0.2.0
+Version: 0.3.0
 Summary: GPU intelligence for ML training — right-size before you launch.
 Author-email: Alloc Labs <hello@alloclabs.com>
 License: Apache-2.0
@@ -61,14 +61,19 @@ Analyzes model parameters from the script filename and computes VRAM breakdown.
 ### `alloc run` — Training with GPU monitoring
 
 ```bash
-alloc run python train.py
+alloc run python train.py                # calibrate and exit (default)
+alloc run --full python train.py         # monitor full training run
 alloc run torchrun --nproc_per_node=4 train.py
 alloc run -- python train.py --epochs 10
 ```
 
 Wraps your command, monitors GPU memory/utilization/power via `pynvml`, and writes an artifact.
 
-**Short-run mode:** `--probe-steps N` profiles for N samples then auto-stops when metrics stabilize (variance threshold < 5.0% over 20 samples).
+**Default: calibrate-and-exit.** Auto-stops when GPU metrics stabilize (~30-60s), prints a verdict with bottleneck classification and recommendation, then exits. Use `--full` to monitor the entire run. Use `--timeout N` to adjust max calibration time (default 120s).
+
+**Multi-GPU:** Automatically discovers all GPUs used by the process tree (works with `torchrun`, `accelerate launch`, etc.).
+
+**Hardware context:** Captures driver version, CUDA version, and SM compute capability from NVML.
 
 ### `alloc login` — Authenticate with dashboard
 
@@ -85,6 +90,18 @@ alloc upload alloc_artifact.json.gz
 
 Uploads a previously saved `.json.gz` artifact to the dashboard via `POST /runs/ingest`. Requires authentication (`alloc login` first).
 
+### `alloc catalog` — Browse GPU hardware catalog
+
+```bash
+alloc catalog list                           # list all 13 GPUs (sorted by VRAM)
+alloc catalog list --sort cost               # sort by $/hr
+alloc catalog list --sort tflops             # sort by BF16 TFLOPS
+alloc catalog show H100                      # detailed specs for H100
+alloc catalog show nvidia-a100-sxm-80gb      # lookup by stable ID
+```
+
+Offline reference for GPU specs, interconnect details, and cloud pricing. Supports aliases (H100, A100, T4) and stable IDs.
+
 ### `alloc version`
 
 ```bash
@@ -119,8 +136,11 @@ All config via environment variables. Zero config files required.
 | Module | Purpose |
 |--------|---------|
 | `ghost.py` | Static VRAM analysis via parameter walking. With torch: `model.named_parameters()`. Without: pure math from param count. |
-| `probe.py` | External GPU monitoring via `pynvml`. Runs user script unmodified as subprocess. |
-| `artifact_writer.py` | Artifact Writer: writes `alloc_artifact.json.gz`, optional W&B upload. |
+| `probe.py` | External GPU monitoring via `pynvml`. Process-tree aware multi-GPU discovery. Captures hardware context (driver, CUDA, SM version). |
+| `stability.py` | Multi-signal stability detection for calibrate-and-exit (VRAM plateau + util std dev + power std dev). |
+| `catalog/` | Bundled GPU hardware catalog (13 GPUs) with specs and pricing. Powers `alloc catalog` commands. |
+| `context.py` | Context autodiscovery: git (SHA, branch, repo), container (Docker/Podman), Ray (job ID, cluster). |
+| `artifact_writer.py` | Artifact Writer: writes `alloc_artifact.json.gz` (v0.5.0) with probe, ghost, hardware, and context sections. |
 | `cli.py` | Typer CLI with `ghost`, `run`, `scan`, `login`, `upload`, `version` commands. |
 | `callbacks.py` | Framework callbacks: HuggingFace `TrainerCallback` (step count capture). |
 | `upload.py` | Artifact uploader: POSTs `.json.gz` to `POST /runs/ingest`. |

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

@@ -32,14 +32,19 @@ Analyzes model parameters from the script filename and computes VRAM breakdown.
 ### `alloc run` — Training with GPU monitoring
 
 ```bash
-alloc run python train.py
+alloc run python train.py                # calibrate and exit (default)
+alloc run --full python train.py         # monitor full training run
 alloc run torchrun --nproc_per_node=4 train.py
 alloc run -- python train.py --epochs 10
 ```
 
 Wraps your command, monitors GPU memory/utilization/power via `pynvml`, and writes an artifact.
 
-**Short-run mode:** `--probe-steps N` profiles for N samples then auto-stops when metrics stabilize (variance threshold < 5.0% over 20 samples).
+**Default: calibrate-and-exit.** Auto-stops when GPU metrics stabilize (~30-60s), prints a verdict with bottleneck classification and recommendation, then exits. Use `--full` to monitor the entire run. Use `--timeout N` to adjust max calibration time (default 120s).
+
+**Multi-GPU:** Automatically discovers all GPUs used by the process tree (works with `torchrun`, `accelerate launch`, etc.).
+
+**Hardware context:** Captures driver version, CUDA version, and SM compute capability from NVML.
 
 ### `alloc login` — Authenticate with dashboard
 
@@ -56,6 +61,18 @@ alloc upload alloc_artifact.json.gz
 
 Uploads a previously saved `.json.gz` artifact to the dashboard via `POST /runs/ingest`. Requires authentication (`alloc login` first).
 
+### `alloc catalog` — Browse GPU hardware catalog
+
+```bash
+alloc catalog list                           # list all 13 GPUs (sorted by VRAM)
+alloc catalog list --sort cost               # sort by $/hr
+alloc catalog list --sort tflops             # sort by BF16 TFLOPS
+alloc catalog show H100                      # detailed specs for H100
+alloc catalog show nvidia-a100-sxm-80gb      # lookup by stable ID
+```
+
+Offline reference for GPU specs, interconnect details, and cloud pricing. Supports aliases (H100, A100, T4) and stable IDs.
+
 ### `alloc version`
 
 ```bash
@@ -90,8 +107,11 @@ All config via environment variables. Zero config files required.
 | Module | Purpose |
 |--------|---------|
 | `ghost.py` | Static VRAM analysis via parameter walking. With torch: `model.named_parameters()`. Without: pure math from param count. |
-| `probe.py` | External GPU monitoring via `pynvml`. Runs user script unmodified as subprocess. |
-| `artifact_writer.py` | Artifact Writer: writes `alloc_artifact.json.gz`, optional W&B upload. |
+| `probe.py` | External GPU monitoring via `pynvml`. Process-tree aware multi-GPU discovery. Captures hardware context (driver, CUDA, SM version). |
+| `stability.py` | Multi-signal stability detection for calibrate-and-exit (VRAM plateau + util std dev + power std dev). |
+| `catalog/` | Bundled GPU hardware catalog (13 GPUs) with specs and pricing. Powers `alloc catalog` commands. |
+| `context.py` | Context autodiscovery: git (SHA, branch, repo), container (Docker/Podman), Ray (job ID, cluster). |
+| `artifact_writer.py` | Artifact Writer: writes `alloc_artifact.json.gz` (v0.5.0) with probe, ghost, hardware, and context sections. |
 | `cli.py` | Typer CLI with `ghost`, `run`, `scan`, `login`, `upload`, `version` commands. |
 | `callbacks.py` | Framework callbacks: HuggingFace `TrainerCallback` (step count capture). |
 | `upload.py` | Artifact uploader: POSTs `.json.gz` to `POST /runs/ingest`. |

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alloc"
-version = "0.2.0"
+version = "0.3.0"
 description = "GPU intelligence for ML training — right-size before you launch."
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -41,3 +41,6 @@ Repository = "https://github.com/alloc-labs/alloc"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.setuptools.package-data]
+"alloc.catalog" = ["*.json"]

alloc-0.3.0/src/alloc/__init__.py

@@ -0,0 +1,10 @@
+"""Alloc — GPU intelligence for ML training."""
+
+from __future__ import annotations
+
+__version__ = "0.3.0"
+
+from alloc.ghost import ghost, GhostReport
+from alloc.callbacks import AllocCallback as HuggingFaceCallback
+
+__all__ = ["ghost", "GhostReport", "HuggingFaceCallback", "__version__"]

{alloc-0.2.0 → alloc-0.3.0}/src/alloc/artifact_writer.py

@@ -16,6 +16,8 @@ def write_report(
     ghost_report: Optional[dict] = None,
     probe_result: Optional[dict] = None,
     output_path: Optional[str] = None,
+    hardware_context: Optional[dict] = None,
+    context: Optional[dict] = None,
 ) -> str:
     """Write an artifact to disk.
 
@@ -34,10 +36,12 @@ def write_report(
         )
 
         report = {
-            "version": "0.2.0",
+            "version": "0.5.0",
             "timestamp": datetime.now(timezone.utc).isoformat(),
             "ghost": ghost_report,
             "probe": probe_result,
+            "hardware": hardware_context,
+            "context": context if context else None,
         }
 
         with gzip.open(resolved_path, "wt", encoding="utf-8") as f:

{alloc-0.2.0 → alloc-0.3.0}/src/alloc/callbacks.py

@@ -45,9 +45,14 @@ try:
         def __init__(self):
             # type: () -> None
             self.step_count = 0  # type: int
+            self._last_write_step = 0  # type: int
+            self._write_every = 10  # type: int
 
         def on_step_end(self, args, state, control, **kwargs):
             self.step_count = state.global_step
+            if self.step_count - self._last_write_step >= self._write_every:
+                _write_step_count(self.step_count, framework="huggingface")
+                self._last_write_step = self.step_count
 
         def on_train_end(self, args, state, control, **kwargs):
             self.step_count = state.global_step

alloc-0.3.0/src/alloc/catalog/__init__.py

@@ -0,0 +1,109 @@
+"""GPU catalog — offline hardware specs and pricing for CLI.
+
+Source of truth: apps/api/src/engine/catalog/gpus.v1.json
+This is a bundled copy for offline CLI use. Update when the API catalog changes.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List, Optional
+
+_CATALOG_DIR = Path(__file__).parent
+
+# Aliases for common shorthand names
+_ALIASES = {
+    "H100": "nvidia-h100-sxm-80gb",
+    "H100-80GB": "nvidia-h100-sxm-80gb",
+    "A100": "nvidia-a100-sxm-80gb",
+    "A100-80GB": "nvidia-a100-sxm-80gb",
+    "A100-40GB": "nvidia-a100-40gb",
+    "A10G": "nvidia-a10g-24gb",
+    "L40S": "nvidia-l40s-48gb",
+    "L4": "nvidia-l4-24gb",
+    "T4": "nvidia-t4-16gb",
+    "V100": "nvidia-v100-32gb",
+    "V100-32GB": "nvidia-v100-32gb",
+    "V100-16GB": "nvidia-v100-16gb",
+    "RTX-4090": "nvidia-rtx4090-24gb",
+    "RTX-3090": "nvidia-rtx3090-24gb",
+    "H200": "nvidia-h200-141gb",
+    "H100-NVL": "nvidia-h100-nvl-94gb",
+}
+
+
+def _load_catalog() -> dict:
+    """Load GPU catalog from bundled JSON."""
+    with open(_CATALOG_DIR / "gpus.v1.json") as f:
+        return json.load(f)
+
+
+def _load_rate_card() -> dict:
+    """Load default rate card from bundled JSON."""
+    with open(_CATALOG_DIR / "default_rate_card.json") as f:
+        return json.load(f)
+
+
+def list_gpus() -> List[dict]:
+    """Return all GPUs sorted by VRAM descending.
+
+    Each entry has: id, display_name, vendor, vram_gb, architecture,
+    bandwidth_gbps, bf16_tflops, tdp_watts, pricing.
+    """
+    catalog = _load_catalog()
+    rate_card = _load_rate_card()
+
+    result = []
+    for gpu_id, spec in catalog.get("gpus", {}).items():
+        pricing = rate_card.get("rates", {}).get(spec["display_name"], {})
+        result.append({
+            "id": gpu_id,
+            "display_name": spec["display_name"],
+            "vendor": spec.get("vendor", "nvidia"),
+            "vram_gb": spec["vram_gb"],
+            "architecture": spec.get("architecture", ""),
+            "bandwidth_gbps": spec.get("bandwidth_gbps", 0),
+            "bf16_tflops": spec.get("bf16_tflops", 0),
+            "fp16_tflops": spec.get("fp16_tflops", 0),
+            "fp32_tflops": spec.get("fp32_tflops", 0),
+            "tf32_tflops": spec.get("tf32_tflops", 0),
+            "tdp_watts": spec.get("tdp_watts", 0),
+            "interconnect": spec.get("interconnect"),
+            "pricing": pricing,
+        })
+
+    return sorted(result, key=lambda x: x["vram_gb"], reverse=True)
+
+
+def get_gpu(gpu_id: str) -> Optional[dict]:
+    """Look up a GPU by stable ID or alias.
+
+    Returns full spec dict or None if not found.
+    """
+    # Resolve aliases
+    resolved = _ALIASES.get(gpu_id, gpu_id)
+
+    catalog = _load_catalog()
+    rate_card = _load_rate_card()
+
+    spec = catalog.get("gpus", {}).get(resolved)
+    if not spec:
+        return None
+
+    pricing = rate_card.get("rates", {}).get(spec["display_name"], {})
+    return {
+        "id": resolved,
+        "display_name": spec["display_name"],
+        "vendor": spec.get("vendor", "nvidia"),
+        "vram_gb": spec["vram_gb"],
+        "architecture": spec.get("architecture", ""),
+        "bandwidth_gbps": spec.get("bandwidth_gbps", 0),
+        "bf16_tflops": spec.get("bf16_tflops", 0),
+        "fp16_tflops": spec.get("fp16_tflops", 0),
+        "fp32_tflops": spec.get("fp32_tflops", 0),
+        "tf32_tflops": spec.get("tf32_tflops", 0),
+        "tdp_watts": spec.get("tdp_watts", 0),
+        "interconnect": spec.get("interconnect"),
+        "pricing": pricing,
+    }

alloc-0.3.0/src/alloc/catalog/default_rate_card.json

@@ -0,0 +1,18 @@
+{
+  "version": "1",
+  "rates": {
+    "H200": { "aws": 5.50, "gcp": 5.30, "azure": 5.40 },
+    "H100-80GB": { "aws": 4.00, "gcp": 3.90, "azure": 3.85 },
+    "H100-NVL": { "aws": 4.50, "gcp": 4.40, "azure": 4.30 },
+    "A100-80GB": { "aws": 2.50, "gcp": 2.48, "azure": 2.55 },
+    "A100-40GB": { "aws": 2.00, "gcp": 1.95, "azure": 2.10 },
+    "A10G": { "aws": 0.75, "gcp": 0.70, "azure": 0.80 },
+    "L40S": { "aws": 1.50, "gcp": 1.45, "azure": 1.55 },
+    "L4": { "aws": 0.50, "gcp": 0.45, "azure": 0.55 },
+    "T4": { "aws": 0.35, "gcp": 0.30, "azure": 0.40 },
+    "V100-32GB": { "aws": 1.20, "gcp": 1.15, "azure": 1.25 },
+    "V100-16GB": { "aws": 0.90, "gcp": 0.85, "azure": 0.95 },
+    "RTX-4090": { "lambda": 0.70, "coreweave": 0.74 },
+    "RTX-3090": { "lambda": 0.50, "coreweave": 0.54 }
+  }
+}

alloc-0.3.0/src/alloc/catalog/gpus.v1.json

@@ -0,0 +1,174 @@
+{
+  "version": "1",
+  "gpus": {
+    "nvidia-h200-141gb": {
+      "display_name": "H200",
+      "vendor": "nvidia",
+      "vram_gb": 141,
+      "bandwidth_gbps": 4800,
+      "fp16_tflops": 989,
+      "bf16_tflops": 989,
+      "fp32_tflops": 67,
+      "tf32_tflops": 495,
+      "architecture": "Hopper",
+      "tdp_watts": 700,
+      "interconnect": { "nvlink_gen": 4, "nvlink_bw_gbps": 900, "pcie_gen": 5 }
+    },
+    "nvidia-h100-sxm-80gb": {
+      "display_name": "H100-80GB",
+      "vendor": "nvidia",
+      "vram_gb": 80,
+      "bandwidth_gbps": 3350,
+      "fp16_tflops": 989,
+      "bf16_tflops": 989,
+      "fp32_tflops": 67,
+      "tf32_tflops": 495,
+      "architecture": "Hopper",
+      "tdp_watts": 700,
+      "interconnect": { "nvlink_gen": 4, "nvlink_bw_gbps": 900, "pcie_gen": 5 }
+    },
+    "nvidia-h100-nvl-94gb": {
+      "display_name": "H100-NVL",
+      "vendor": "nvidia",
+      "vram_gb": 94,
+      "bandwidth_gbps": 3350,
+      "fp16_tflops": 989,
+      "bf16_tflops": 989,
+      "fp32_tflops": 67,
+      "tf32_tflops": 495,
+      "architecture": "Hopper",
+      "tdp_watts": 400,
+      "interconnect": { "nvlink_gen": 4, "nvlink_bw_gbps": 900, "pcie_gen": 5 }
+    },
+    "nvidia-a100-sxm-80gb": {
+      "display_name": "A100-80GB",
+      "vendor": "nvidia",
+      "vram_gb": 80,
+      "bandwidth_gbps": 2039,
+      "fp16_tflops": 312,
+      "bf16_tflops": 312,
+      "fp32_tflops": 19.5,
+      "tf32_tflops": 156,
+      "architecture": "Ampere",
+      "tdp_watts": 400,
+      "interconnect": { "nvlink_gen": 3, "nvlink_bw_gbps": 600, "pcie_gen": 4 }
+    },
+    "nvidia-a100-40gb": {
+      "display_name": "A100-40GB",
+      "vendor": "nvidia",
+      "vram_gb": 40,
+      "bandwidth_gbps": 1555,
+      "fp16_tflops": 312,
+      "bf16_tflops": 312,
+      "fp32_tflops": 19.5,
+      "tf32_tflops": 156,
+      "architecture": "Ampere",
+      "tdp_watts": 400,
+      "interconnect": { "nvlink_gen": 3, "nvlink_bw_gbps": 600, "pcie_gen": 4 }
+    },
+    "nvidia-a10g-24gb": {
+      "display_name": "A10G",
+      "vendor": "nvidia",
+      "vram_gb": 24,
+      "bandwidth_gbps": 600,
+      "fp16_tflops": 125,
+      "bf16_tflops": 125,
+      "fp32_tflops": 31.2,
+      "tf32_tflops": 62.5,
+      "architecture": "Ampere",
+      "tdp_watts": 300,
+      "interconnect": { "pcie_gen": 4 }
+    },
+    "nvidia-l40s-48gb": {
+      "display_name": "L40S",
+      "vendor": "nvidia",
+      "vram_gb": 48,
+      "bandwidth_gbps": 864,
+      "fp16_tflops": 362,
+      "bf16_tflops": 362,
+      "fp32_tflops": 91.6,
+      "tf32_tflops": 183,
+      "architecture": "Ada Lovelace",
+      "tdp_watts": 350,
+      "interconnect": { "pcie_gen": 4 }
+    },
+    "nvidia-l4-24gb": {
+      "display_name": "L4",
+      "vendor": "nvidia",
+      "vram_gb": 24,
+      "bandwidth_gbps": 300,
+      "fp16_tflops": 121,
+      "bf16_tflops": 121,
+      "fp32_tflops": 30.3,
+      "tf32_tflops": 60,
+      "architecture": "Ada Lovelace",
+      "tdp_watts": 72,
+      "interconnect": { "pcie_gen": 4 }
+    },
+    "nvidia-t4-16gb": {
+      "display_name": "T4",
+      "vendor": "nvidia",
+      "vram_gb": 16,
+      "bandwidth_gbps": 320,
+      "fp16_tflops": 65,
+      "bf16_tflops": 0,
+      "fp32_tflops": 8.1,
+      "tf32_tflops": 0,
+      "architecture": "Turing",
+      "tdp_watts": 70,
+      "interconnect": { "pcie_gen": 3 }
+    },
+    "nvidia-v100-32gb": {
+      "display_name": "V100-32GB",
+      "vendor": "nvidia",
+      "vram_gb": 32,
+      "bandwidth_gbps": 900,
+      "fp16_tflops": 125,
+      "bf16_tflops": 0,
+      "fp32_tflops": 15.7,
+      "tf32_tflops": 0,
+      "architecture": "Volta",
+      "tdp_watts": 300,
+      "interconnect": { "nvlink_gen": 2, "nvlink_bw_gbps": 300, "pcie_gen": 3 }
+    },
+    "nvidia-v100-16gb": {
+      "display_name": "V100-16GB",
+      "vendor": "nvidia",
+      "vram_gb": 16,
+      "bandwidth_gbps": 900,
+      "fp16_tflops": 125,
+      "bf16_tflops": 0,
+      "fp32_tflops": 15.7,
+      "tf32_tflops": 0,
+      "architecture": "Volta",
+      "tdp_watts": 300,
+      "interconnect": { "nvlink_gen": 2, "nvlink_bw_gbps": 300, "pcie_gen": 3 }
+    },
+    "nvidia-rtx4090-24gb": {
+      "display_name": "RTX-4090",
+      "vendor": "nvidia",
+      "vram_gb": 24,
+      "bandwidth_gbps": 1008,
+      "fp16_tflops": 330,
+      "bf16_tflops": 330,
+      "fp32_tflops": 82.6,
+      "tf32_tflops": 165,
+      "architecture": "Ada Lovelace",
+      "tdp_watts": 450,
+      "interconnect": { "pcie_gen": 4 }
+    },
+    "nvidia-rtx3090-24gb": {
+      "display_name": "RTX-3090",
+      "vendor": "nvidia",
+      "vram_gb": 24,
+      "bandwidth_gbps": 936,
+      "fp16_tflops": 142,
+      "bf16_tflops": 142,
+      "fp32_tflops": 35.6,
+      "tf32_tflops": 71,
+      "architecture": "Ampere",
+      "tdp_watts": 350,
+      "interconnect": { "pcie_gen": 4 }
+    }
+  }
+}