domains / science / resource-aware-planning / get-available-resources

get-available-resources

Skill card

combined

The two copies describe the same detector but with materially different contracts. The K-Dense copy is a conservative, redacted, process-scoped inventory that forbids stress tests, hides host identifiers, treats unknowns as unknown, and separates host, cgroup, scheduler, and accelerator facts. The Vibe-Skills copy is a proactive, host-level inventory that writes a default JSON file, reports hostnames/paths/OS details, and emits strategic recommendations (worker counts, library choices, memory/disk strategies) that the K-Dense copy explicitly avoids. Because each contains steps and constraints the other lacks, crowning one would hide a real alternative.

Repositories

Other copies

Combined skill

---
name: get-available-resources
description: Detects host inventory and effective CPU, memory, disk, scheduler, container, and accelerator limits for resource-aware planning. Produces a redacted JSON snapshot and, when requested, conservative planning helpers without stress tests or assuming visible host hardware is usable.
license: MIT
compatibility: Python 3.11+ on Linux, macOS, or Windows; standard library by default, optional psutil 7.2.2; accelerator management CLIs are optional read-only probes.
metadata:
  version: "1.5"
  last-reviewed: "2026-10-01"
  skill-author: K-Dense Inc.
---

# Get Available Resources

Build a conservative picture of resources available to the current process. Keep host inventory, process affinity, cgroup/container limits, scheduler allocation, and accelerator runtime usability separate.

## Safety contract

- Run detection when the user requests it or a specific workload needs resource planning. Do not persist a fingerprint for every scientific task.
- Use stdout by default. Persist only when the user chooses an explicit generic local filename.
- Do not run stress tests, benchmarks, large allocations, write probes, device resets, driver installation, or clock/power changes.
- Do not dump the environment. Read only the named Slurm and accelerator variables implemented by the detector.
- Do not report hostnames, absolute paths, cgroup paths, job IDs, device UUIDs, PCI addresses, or raw visibility-variable values.
- Treat a missing observation as unknown. Never convert unknown to unknown to unlimited.
- Never infer that a visible host CPU, memory pool, or GPU is usable inside a scheduler allocation or container.

## Quick start

Run from this skill directory.

### Ephemeral stdout snapshot

```bash
python scripts/detect_resources.py
```

The command emits only JSON to stdout. Redirect it only when ordinary shell permissions are acceptable.

### Explicit private file

```bash
python scripts/detect_resources.py --output resource-snapshot.json
```

Explicit output is restricted to one `.json` filename in the current directory, uses mode 0600 on POSIX, rejects symlinks and path traversal, and refuses overwrite unless `--force` is supplied. Forced output also rejects hard links and non-regular files. Windows privacy additionally depends on the directory ACL.

### Optional psutil enhancement

The standard-library detector works without installation. For broader cross-platform physical-core, affinity, available-memory, swap, and disk coverage:

```bash
uv run --no-project --with "psutil==7.2.2" python scripts/detect_resources.py
```

The import is lazy. Failure to import psutil becomes a warning, not a fatal error.

### Skip management-tool probes

```bash
python scripts/detect_resources.py --skip-accelerators
```

Use this when accelerator discovery latency is undesirable. The detector still summarizes the presence and state of allowlisted visibility variables without returning their values.

## Required interpretation

### CPU

Read these as different facts:

- `cpu.host.logical`: system-visible scheduling units.
- `cpu.host.physical`: physical topology, or null; never inferred from logical count.
- `cpu.process.affinity_logical`: current affinity-set size when supported.
- `cpu.cgroup_v2.cpuset_logical`: effective cgroup cpuset size.
- `cpu.cgroup_v2.quota_cores`: finite `cpu.max` capacity, possibly fractional.
- `scheduler.allocation.cpu_per_process`: bounded Slurm per-task interpretation when scope is clear.
- `cpu.effective.capacity_cores`: minimum positive observed constraint.
- `cpu.effective.worker_ceiling`: conservative floor for CPU process workers.

A quota of 1.5 is CPU-time capacity, not 1.5 physical cores. Affinity and cpusets constrain placement; quota constrains bandwidth.

### Memory

Keep these separate:

- host total/available memory;
- current cgroup usage, hard `memory.max`, and remaining hierarchical capacity;
- `memory.high`, which is a pressure/throttle boundary rather than a hard cap;
- scheduler memory allocation and its scope; and
- conservative effective hard limit and available estimate.

On Apple silicon, `memory.model` is `unified_cpu_gpu`. Do not add integrated GPU memory to RAM or describe it as separate VRAM.

### Accelerators

Each device is a backend candidate:

- NVIDIA GPU → CUDA candidate;
- AMD GPU → ROCm candidate;
- Apple integrated GPU → Metal candidate.

Management-query visibility does not establish:

1. scheduler/container permission;
2. device-node access;
3. driver/runtime compatibility;
4. framework package compatibility; or
5. operator/data-type support.

Therefore `runtime_usable_devices` remains null and each device says `runtime_compatibility: not_tested`. Visibility/allocation counts constrain the observed management records, not the number of framework devices. MIG and AMD partition enumeration can differ. AMD `reported_total_bytes` is a device-reported memory pool; its relationship to host RAM is not established, so it is never added to the RAM budget.

### Disk

`capacity_bytes`, filesystem `free_bytes`, user-available blocks, and a non-writing permission check are distinct. Filesystem or project quotas can still be stricter. The absolute working path is always redacted.

The disk snapshot covers the working filesystem only, matching psutil's path-specific semantics. If scratch, caches, and final outputs use different filesystems, inspect each from its target directory and label the reports by role. Budget temporary and final copies that coexist; free space on the input filesystem does not establish space on the output filesystem.

### Scheduler and container

Slurm variables describe allocation scope, but enforcement depends on the scheduler and container runtime. Treat scheduler-reported values as upper bounds, not guarantees.

## Conflicts

- K-Dense-AI/scientific-agent-skills: 'Do not persist a fingerprint for every scientific task' and 'Use stdout by default'; foryourhealth111-pixel/Vibe-Skills: 'Use this skill proactively before any computationally intensive task' and 'generates a .claude_resources.json file in the current working directory'.
- K-Dense-AI/scientific-agent-skills: 'Do not report hostnames, absolute paths, cgroup paths, job IDs, device UUIDs, PCI addresses, or raw visibility-variable values'; foryourhealth111-pixel/Vibe-Skills: reports OS release, machine, and working-directory disk details in the JSON output.
- K-Dense-AI/scientific-agent-skills: 'Do not run stress tests, benchmarks, large allocations, write probes, device resets, driver installation, or clock/power changes' and 'Treat a missing observation as unknown. Never convert unknown to unlimited'; foryourhealth111-pixel/Vibe-Skills: makes strategic recommendations such as 'suggested_workers' and 'strategy' fields that infer usable capacity from host-level observations.
- K-Dense-AI/scientific-agent-skills: 'runtime_usable_devices remains null and each device says runtime_compatibility: not_tested'; foryourhealth111-pixel/Vibe-Skills: 'gpu_acceleration.available: true' and 'suggested_libraries' based on detected backends.