alloc 0.0.1__py3-none-any.whl

alloc/upload.py

@@ -0,0 +1,138 @@
+"""Artifact upload — POST extracted fields to /runs/ingest as JSON."""
+
+from __future__ import annotations
+
+import gzip
+import json
+from typing import Optional
+
+
+class UploadLimitError(Exception):
+    """Raised when the server rejects an upload due to tier limits."""
+
+    def __init__(self, status_code: int, detail: dict):
+        self.status_code = status_code
+        self.detail = detail
+        msg = detail.get("message", f"Upload rejected (HTTP {status_code})")
+        super().__init__(msg)
+
+
+def _normalize_gpu_type(raw_name: object) -> Optional[str]:
+    """Best-effort normalization from NVML GPU names to catalog IDs."""
+    if raw_name is None:
+        return None
+
+    name = str(raw_name).strip()
+    if not name:
+        return None
+
+    upper = name.upper()
+    if "H100" in upper and "NVL" in upper:
+        return "H100-NVL"
+    if "H200" in upper:
+        return "H200"
+    if "H100" in upper:
+        return "H100-80GB"
+    if "A100" in upper and "40" in upper:
+        return "A100-40GB"
+    if "A100" in upper:
+        return "A100-80GB"
+    if "A10G" in upper:
+        return "A10G"
+    if "L40S" in upper:
+        return "L40S"
+    if "L4" in upper:
+        return "L4"
+    if "T4" in upper:
+        return "T4"
+    if "V100" in upper:
+        return "V100-32GB"
+    if "4090" in upper:
+        return "RTX-4090"
+    if "3090" in upper:
+        return "RTX-3090"
+    return None
+
+
+def _to_positive_int(value: object, default: int = 1) -> int:
+    """Parse a positive integer with a safe fallback."""
+    try:
+        parsed = int(value)  # type: ignore[arg-type]
+        return parsed if parsed > 0 else default
+    except Exception:
+        return default
+
+
+def upload_artifact(artifact_path: str, api_url: str, token: str) -> dict:
+    """Upload a .json.gz artifact to POST /runs/ingest.
+
+    Reads the artifact, extracts summary fields, and sends JSON.
+    Returns response dict with run_id and status.
+    Raises UploadLimitError on 402/403/429, other errors via raise_for_status.
+    """
+    import httpx
+
+    with gzip.open(artifact_path, "rt", encoding="utf-8") as f:
+        report = json.load(f)
+
+    probe = report.get("probe") or {}
+    ghost = report.get("ghost") or {}
+    hardware = report.get("hardware") or {}
+
+    gpu_type = (
+        probe.get("gpu_type")
+        or _normalize_gpu_type(probe.get("gpu_name"))
+        or _normalize_gpu_type(hardware.get("gpu_name"))
+    )
+    num_gpus = _to_positive_int(
+        probe.get("num_gpus") or hardware.get("num_gpus_detected"),
+        default=1,
+    )
+
+    payload = {
+        "model_name": probe.get("model_name"),
+        "gpu_type": gpu_type,
+        "num_gpus": num_gpus,
+        "strategy": probe.get("strategy"),
+        "tp_degree": probe.get("tp_degree"),
+        "pp_degree": probe.get("pp_degree"),
+        "dp_degree": probe.get("dp_degree"),
+        "num_nodes": probe.get("num_nodes"),
+        "gpus_per_node": probe.get("gpus_per_node"),
+        "interconnect_type": probe.get("interconnect_type"),
+        "objective": probe.get("objective"),
+        "max_budget_hourly": probe.get("max_budget_hourly"),
+        "peak_vram_mb": probe.get("peak_vram_mb"),
+        "avg_gpu_util": probe.get("avg_gpu_util"),
+        "avg_power_watts": probe.get("avg_power_watts"),
+        "duration_s": probe.get("duration_seconds"),
+        "exit_code": probe.get("exit_code"),
+        "probe_samples": probe.get("samples"),
+        "step_count": probe.get("step_count"),
+        "step_time_ms_p50": probe.get("step_time_ms_p50"),
+        "step_time_ms_p90": probe.get("step_time_ms_p90"),
+        "samples_per_sec": probe.get("samples_per_sec"),
+        "dataloader_wait_pct": probe.get("dataloader_wait_pct"),
+        "ghost_report": ghost if ghost else None,
+        "source": probe.get("source") or "cli",
+    }
+
+    with httpx.Client(timeout=30) as client:
+        resp = client.post(
+            f"{api_url}/runs/ingest",
+            json=payload,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {token}",
+            },
+        )
+
+        if resp.status_code in (402, 403, 429):
+            try:
+                detail = resp.json().get("detail", {})
+            except Exception:
+                detail = {"message": resp.text[:200]}
+            raise UploadLimitError(resp.status_code, detail)
+
+        resp.raise_for_status()
+        return resp.json()

alloc/yaml_config.py

@@ -0,0 +1,287 @@
+""".alloc.yaml config — GPU fleet, explore, budget, priority.
+
+Searches for .alloc.yaml in cwd, then parents, then ~/.alloc/preferences.yaml.
+Never crashes. Returns None or defaults on missing/invalid config.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+
+CONFIG_FILENAME = ".alloc.yaml"
+GLOBAL_PREFS_PATH = Path.home() / ".alloc" / "preferences.yaml"
+
+_ALLOWED_OBJECTIVES = {
+    "cheapest",
+    "fastest",
+    "fastest_within_budget",
+    "best_value",
+}
+
+_ALLOWED_INTERCONNECTS = {
+    "pcie",
+    "nvlink",
+    "infiniband",
+    "unknown",
+}
+
+
+@dataclass
+class FleetEntry:
+    """A GPU in the user's fleet or explore list."""
+
+    gpu: str                        # GPU ID or alias (e.g. "H100", "nvidia-h100-sxm-80gb")
+    cloud: Optional[str] = None     # "aws", "gcp", "azure", "lambda", etc.
+    count: Optional[int] = None     # Max GPUs available
+    rate: Optional[float] = None    # Custom $/hr override
+    explore: bool = False           # True = "I don't have this but want to evaluate"
+
+
+@dataclass
+class AllocConfig:
+    """Parsed .alloc.yaml content."""
+
+    fleet: List[FleetEntry] = field(default_factory=list)
+    explore: List[FleetEntry] = field(default_factory=list)
+    objective: Optional[str] = None  # cheapest | fastest | fastest_within_budget | best_value
+    priority_cost: int = 50         # 0-100, latency = 100 - cost
+    budget_monthly: Optional[float] = None  # Monthly budget in USD
+    budget_hourly: Optional[float] = None   # Hourly budget cap
+    org_budget_monthly: Optional[float] = None  # Org ceiling (from --from-org sync)
+    interconnect: Optional[str] = None  # pcie | nvlink | infiniband | unknown
+
+    @property
+    def priority_latency(self) -> int:
+        return 100 - self.priority_cost
+
+    @property
+    def fleet_gpu_ids(self) -> List[str]:
+        """GPU IDs from fleet entries."""
+        return [e.gpu for e in self.fleet]
+
+    @property
+    def explore_gpu_ids(self) -> List[str]:
+        """GPU IDs from explore entries."""
+        return [e.gpu for e in self.explore]
+
+    @property
+    def all_gpu_ids(self) -> List[str]:
+        """All GPU IDs (fleet + explore)."""
+        return self.fleet_gpu_ids + self.explore_gpu_ids
+
+    @property
+    def rate_overrides(self) -> Dict[str, float]:
+        """GPU ID → custom $/hr for entries with rate set."""
+        overrides = {}
+        for e in self.fleet + self.explore:
+            if e.rate is not None:
+                overrides[e.gpu] = e.rate
+        return overrides
+
+    def to_dict(self) -> dict:
+        """Serialize to dict suitable for YAML output."""
+        d = {}  # type: dict
+
+        if self.objective is not None:
+            d["objective"] = self.objective
+
+        if self.fleet:
+            d["fleet"] = [_entry_to_dict(e) for e in self.fleet]
+
+        if self.explore:
+            d["explore"] = [_entry_to_dict(e) for e in self.explore]
+
+        d["priority"] = {
+            "cost": self.priority_cost,
+            "latency": self.priority_latency,
+        }
+
+        if self.budget_monthly is not None:
+            d.setdefault("budget", {})["monthly_usd"] = self.budget_monthly
+        if self.budget_hourly is not None:
+            d.setdefault("budget", {})["hourly_usd"] = self.budget_hourly
+        if self.org_budget_monthly is not None:
+            d.setdefault("budget", {})["org_ceiling_usd"] = self.org_budget_monthly
+
+        if self.interconnect is not None:
+            d["interconnect"] = self.interconnect
+
+        return d
+
+
+def _entry_to_dict(e: FleetEntry) -> dict:
+    """Serialize a FleetEntry, omitting None/default fields."""
+    d = {"gpu": e.gpu}  # type: dict
+    if e.cloud is not None:
+        d["cloud"] = e.cloud
+    if e.count is not None:
+        d["count"] = e.count
+    if e.rate is not None:
+        d["rate"] = e.rate
+    return d
+
+
+def load_alloc_config(path: Optional[str] = None) -> Optional[AllocConfig]:
+    """Load and parse .alloc.yaml.
+
+    Search order:
+      1. Explicit path (if provided)
+      2. .alloc.yaml in cwd
+      3. .alloc.yaml in parent directories (up to filesystem root)
+      4. ~/.alloc/preferences.yaml
+
+    Returns None if no config file found or parse fails.
+    """
+    config_path = _find_config(path)
+    if config_path is None:
+        return None
+
+    try:
+        with open(config_path, "r") as f:
+            raw = yaml.safe_load(f)
+    except Exception:
+        return None
+
+    if not isinstance(raw, dict):
+        return None
+
+    return _parse_config(raw)
+
+
+def validate_config(config: AllocConfig) -> List[str]:
+    """Validate an AllocConfig. Returns list of error strings (empty = valid)."""
+    errors = []
+
+    if config.objective is not None and config.objective not in _ALLOWED_OBJECTIVES:
+        errors.append(
+            f"objective must be one of {sorted(_ALLOWED_OBJECTIVES)}, got {config.objective}"
+        )
+
+    if config.interconnect is not None and config.interconnect not in _ALLOWED_INTERCONNECTS:
+        errors.append(
+            f"interconnect must be one of {sorted(_ALLOWED_INTERCONNECTS)}, got {config.interconnect}"
+        )
+
+    if config.priority_cost < 0 or config.priority_cost > 100:
+        errors.append(f"priority.cost must be 0-100, got {config.priority_cost}")
+
+    if config.budget_monthly is not None and config.budget_monthly < 0:
+        errors.append(f"budget.monthly_usd must be >= 0, got {config.budget_monthly}")
+
+    if config.budget_hourly is not None and config.budget_hourly < 0:
+        errors.append(f"budget.hourly_usd must be >= 0, got {config.budget_hourly}")
+
+    for entry in config.fleet + config.explore:
+        if not entry.gpu:
+            errors.append("Fleet/explore entry missing 'gpu' field")
+        if entry.rate is not None and entry.rate < 0:
+            errors.append(f"Rate for {entry.gpu} must be >= 0, got {entry.rate}")
+        if entry.count is not None and entry.count < 1:
+            errors.append(f"Count for {entry.gpu} must be >= 1, got {entry.count}")
+
+    return errors
+
+
+def write_alloc_config(config: AllocConfig, path: Optional[str] = None) -> str:
+    """Write config to YAML file. Returns the path written to."""
+    out_path = path or os.path.join(os.getcwd(), CONFIG_FILENAME)
+
+    data = config.to_dict()
+
+    with open(out_path, "w") as f:
+        f.write("# Alloc GPU configuration\n")
+        f.write("# Docs: https://alloclabs.com/docs/right-sizing\n\n")
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+    return out_path
+
+
+def _find_config(explicit_path: Optional[str] = None) -> Optional[str]:
+    """Find .alloc.yaml by searching cwd → parents → global prefs."""
+    if explicit_path:
+        if os.path.isfile(explicit_path):
+            return explicit_path
+        return None
+
+    # Walk from cwd upward
+    current = Path.cwd()
+    for _ in range(50):  # Safety limit
+        candidate = current / CONFIG_FILENAME
+        if candidate.is_file():
+            return str(candidate)
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+
+    # Global preferences
+    if GLOBAL_PREFS_PATH.is_file():
+        return str(GLOBAL_PREFS_PATH)
+
+    return None
+
+
+def _parse_config(raw: dict) -> AllocConfig:
+    """Parse raw YAML dict into AllocConfig."""
+    objective = raw.get("objective")
+    if not isinstance(objective, str) or not objective.strip():
+        objective = None
+
+    fleet = []
+    for item in raw.get("fleet", []):
+        if isinstance(item, str):
+            fleet.append(FleetEntry(gpu=item))
+        elif isinstance(item, dict):
+            fleet.append(FleetEntry(
+                gpu=item.get("gpu", ""),
+                cloud=item.get("cloud"),
+                count=item.get("count"),
+                rate=item.get("rate"),
+                explore=False,
+            ))
+
+    explore = []
+    for item in raw.get("explore", []):
+        if isinstance(item, str):
+            explore.append(FleetEntry(gpu=item, explore=True))
+        elif isinstance(item, dict):
+            explore.append(FleetEntry(
+                gpu=item.get("gpu", ""),
+                cloud=item.get("cloud"),
+                count=item.get("count"),
+                rate=item.get("rate"),
+                explore=True,
+            ))
+
+    priority = raw.get("priority", {})
+    priority_cost = priority.get("cost", 50) if isinstance(priority, dict) else 50
+
+    budget = raw.get("budget", {})
+    budget_monthly = budget.get("monthly_usd") if isinstance(budget, dict) else None
+    budget_hourly = budget.get("hourly_usd") if isinstance(budget, dict) else None
+    org_budget_monthly = budget.get("org_ceiling_usd") if isinstance(budget, dict) else None
+
+    interconnect = raw.get("interconnect")
+    if isinstance(interconnect, str) and interconnect.strip():
+        interconnect = interconnect.strip().lower()
+        if interconnect not in _ALLOWED_INTERCONNECTS:
+            interconnect = None
+    else:
+        interconnect = None
+
+    return AllocConfig(
+        fleet=fleet,
+        explore=explore,
+        objective=objective,
+        priority_cost=priority_cost,
+        budget_monthly=budget_monthly,
+        budget_hourly=budget_hourly,
+        org_budget_monthly=org_budget_monthly,
+        interconnect=interconnect,
+    )

alloc-0.0.1.dist-info/METADATA

@@ -0,0 +1,256 @@
+Metadata-Version: 2.4
+Name: alloc
+Version: 0.0.1
+Summary: Engineer-first training calibration: estimate VRAM fit, profile short runs, and pick GPU configs under real budget constraints.
+Author-email: Alloc Labs <hello@alloclabs.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://alloclabs.com
+Project-URL: Repository, https://github.com/alloc-labs/alloc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: gpu
+Requires-Dist: pynvml>=11.5.0; extra == "gpu"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+
+# alloc (by [Alloc Labs](https://www.alloclabs.com))
+
+Engineer-first training calibration: estimate VRAM fit, profile short runs, and pick GPU configs under real budget constraints.
+
+[![Website](https://img.shields.io/badge/alloclabs.com-website-22c55e)](https://www.alloclabs.com)
+[![PyPI](https://img.shields.io/pypi/v/alloc)](https://pypi.org/project/alloc/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+> Built by [Alloc Labs](https://www.alloclabs.com): reduce ML training costs with better pre-flight decisions and faster feedback loops.
+
+## What Alloc Does
+
+Most ML teams waste spend because resource decisions are guesswork and feedback arrives too late. Alloc gives you a progressive workflow:
+
+- **Pre-flight**: estimate VRAM fit and rank feasible configs by objective (`alloc scan`, `alloc ghost`)
+- **Calibration run**: measure peak VRAM + utilization (and optionally step timing) from a short run (`alloc run`)
+- **Run history**: upload artifacts for team visibility and budget-aware proposals (`alloc upload`)
+
+Alloc is launcher-first. It works with `python`, `torchrun`, `accelerate`, and cluster entrypoints (Slurm, Ray, Kubernetes) because it does not require framework-specific wrappers for baseline value.
+
+## Who This Is For
+
+- **Solo engineers** who want a fast sanity check before burning GPU time
+- **ML teams** who need repeatable right-sizing and bottleneck visibility
+- **Platform/infra leads** who want budget-aware controls without rewriting training code
+
+## Why It Is Low Friction
+
+- **No code changes required** for baseline value (`alloc run`)
+- **Optional deeper integration** via callbacks when you want richer timing signals
+- **Local-first artifacts** so users still get value without cloud connectivity
+- **Progressive adoption** from local CLI to team workflows and governance
+
+## Install
+
+```bash
+pip install alloc
+
+# With GPU monitoring support (NVML via pynvml)
+pip install alloc[gpu]
+```
+
+Notes:
+- `alloc` does not depend on torch. If you want `alloc ghost train.py` to infer param counts from a script, torch must be installed in that environment, otherwise use `--param-count-b`.
+- `alloc run` will still execute your command without `alloc[gpu]`, but it cannot collect GPU metrics.
+
+## Commands
+
+### `alloc scan`: Remote Ghost Scan (no GPU needed)
+
+```bash
+alloc scan --model llama-3-70b --gpu A100-80GB
+alloc scan --model mistral-7b --gpu A10G --strategy fsdp --num-gpus 4
+alloc scan --param-count-b 13.0 --gpu H100-80GB --dtype bf16
+
+# Objective + budget constraints
+alloc scan --model llama-3-70b --gpu H100-80GB --objective fastest_within_budget --max-budget-hourly 12
+
+# Topology hints (optional, improves planner quality)
+alloc scan --param-count-b 70 --gpu H100-80GB --num-gpus 64 --num-nodes 8 --gpus-per-node 8 --interconnect infiniband
+```
+
+### `alloc ghost`: Local VRAM estimation
+
+```bash
+alloc ghost train.py --dtype bf16 --batch-size 32
+alloc ghost train.py --param-count-b 7.0   # manual override
+```
+
+Analyzes your training script to discover model parameters and computes a VRAM breakdown. Uses a three-method fallback: (1) `--param-count-b` manual override, (2) subprocess execution to find `nn.Module` classes and count parameters, (3) AST parsing for `from_pretrained()` calls.
+
+### `alloc run`: Training with GPU monitoring
+
+```bash
+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.
+
+**Default: calibrate-and-exit.** Auto-stops when GPU metrics stabilize, prints a verdict with bottleneck classification and a top recommendation, then exits. Use `--timeout N` to adjust max calibration time (default 120s). Use `--full` to monitor the entire run.
+
+**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
+
+```bash
+alloc login
+# Prompts for email + password, stores token + refresh_token in ~/.alloc/config.json
+
+alloc login --token <ACCESS_TOKEN>
+# Paste an access token from the dashboard (no password prompt)
+```
+
+### `alloc whoami`: Show current auth + org context
+
+```bash
+alloc whoami
+alloc whoami --json
+```
+
+Prints the current identity (when logged in), plus objective, effective budget cap, and fleet counts.
+
+### `alloc logout`: Clear local session
+
+```bash
+alloc logout
+```
+
+Clears saved `token`/`refresh_token` from `~/.alloc/config.json`.
+
+### `alloc upload`: Upload artifact to dashboard
+
+```bash
+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).
+
+If your session token has expired and a `refresh_token` is available (password login flow), `alloc upload` refreshes once and retries automatically.
+
+### `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 init`: Configure GPU fleet and budget
+
+```bash
+alloc init                     # interactive wizard
+alloc init --yes               # non-interactive defaults (full catalog, 50/50 priority)
+alloc init --from-org --yes    # pull fleet/budget/objective from your org (requires alloc login)
+```
+
+Creates a `.alloc.yaml` file in the current directory with your GPU fleet, explore list, budget, and priority weights. When present, `ghost`, `run`, and `scan` automatically use fleet context for recommendations. Use `--no-config` on any command to skip it.
+
+### `alloc version`
+
+```bash
+alloc version
+```
+
+## Python API
+
+```python
+import alloc
+
+# Static VRAM analysis (never crashes your training)
+report = alloc.ghost(model)
+print(report.total_gb)  # e.g., 115.42
+
+# Or from param count (no torch needed)
+report = alloc.ghost(param_count_b=7.0, dtype="bf16")
+```
+
+## Framework Callbacks
+
+Optional callbacks for deeper profiling. Captures step-level timing, throughput, and dataloader wait estimates.
+
+```python
+# HuggingFace Transformers
+from alloc import HuggingFaceCallback
+trainer = Trainer(..., callbacks=[HuggingFaceCallback()])
+
+# PyTorch Lightning
+from alloc import LightningCallback
+trainer = Trainer(..., callbacks=[LightningCallback()])
+```
+
+Callbacks write a `.alloc_callback.json` sidecar with step time (p50/p90), samples/sec, and estimated dataloader wait %. This unlocks higher confidence analysis and dataloader bottleneck detection.
+
+## Configuration
+
+Alloc works with zero config. You can optionally configure it with environment variables and/or a `.alloc.yaml` in your repo.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ALLOC_API_URL` | `https://alloc-production-ffc2.up.railway.app` | API endpoint for remote scans |
+| `ALLOC_TOKEN` | (empty) | Auth token for API calls |
+| `ALLOC_UPLOAD` | `false` | Upload results to dashboard (`alloc run --upload` also works) |
+| `ALLOC_OUT` | `alloc_artifact.json.gz` | Artifact output path |
+| `ALLOC_GPU_COUNT_CANDIDATES` | (empty) | Override GPU-count candidates for ranking (comma-separated ints) |
+
+## Architecture
+
+| Module | Purpose |
+|--------|---------|
+| `ghost.py` | VRAM estimation from parameter count. Computes weights + gradients + optimizer + activations + buffer breakdown. |
+| `model_extractor.py` | Three-method model discovery: subprocess execution (`nn.Module` finder), AST parsing (`from_pretrained`), manual override. |
+| `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` with probe, ghost, hardware, and context sections. |
+| `cli.py` | Typer CLI with `ghost`, `run`, `scan`, `login`, `upload`, `init`, `catalog`, `version` commands. |
+| `yaml_config.py` | `.alloc.yaml` parser: fleet, explore, priority, budget. Loaded automatically by `ghost`, `run`, `scan`. |
+| `callbacks.py` | Framework callbacks: HuggingFace `TrainerCallback` and Lightning `Callback` with step timing (p50/p90), throughput, and dataloader wait estimation. |
+| `upload.py` | Artifact uploader: POSTs `.json.gz` to `POST /runs/ingest`. |
+| `display.py` | Rich terminal formatting for reports. |
+| `config.py` | Env-var-only configuration (API URL, Supabase URL, token storage). |
+
+## Design Principles
+
+1. **Zero config**: `alloc run python train.py` works out of the box
+2. **No monkey-patching**: External monitoring only; deeper signals are opt-in
+3. **Never crash user's training**: All Alloc failures are caught and training continues
+4. **Progressive disclosure**: Individual use first, team governance later
+
+## Telemetry Levels
+
+Alloc intentionally starts non-invasive and adds richer signals only when you opt in.
+
+- **NVML (today)**: peak VRAM, GPU utilization, power draw, basic hardware context (driver/CUDA/SM), multi-GPU discovery from the process tree.
+- **Framework timing (today, opt-in)**: step time p50/p90, samples/sec, estimated dataloader wait percentage via HF/Lightning callbacks.
+- **Distributed timing (planned, opt-in)**: per-rank timing skew, communication overhead, stronger interconnect-aware recommendations.