{"id":"get-available-resources","name":"get-available-resources","summary":"ユーザーがリソース認識計画を求める場合や、明らかにリソースに敏感なローカルワークロードの前に、ホストインベントリや有効なCPU、メモリ、ディスク、スケジューラ、コンテナ、アクセラレータの制限を検出します。","body":"# Get Available Resources\n\nBuild a conservative picture of resources available to the **current process**.\nKeep host inventory, process affinity, cgroup/container limits, scheduler\nallocation, and accelerator runtime usability separate.\n\n## Safety contract\n\nFollow these rules:\n\n- Run detection when the user requests it or a specific workload needs resource\n  planning. Do not persist a fingerprint for every scientific task.\n- Use stdout by default. Persist only when the user chooses an explicit generic\n  local filename.\n- Do not run stress tests, benchmarks, large allocations, write probes, device\n  resets, driver installation, or clock/power changes.\n- Do not dump the environment. Read only the named Slurm and accelerator\n  variables implemented by the detector.\n- Do not report hostnames, absolute paths, cgroup paths, job IDs, device UUIDs,\n  PCI addresses, or raw visibility-variable values.\n- Treat a missing observation as unknown. Never convert unknown to unlimited.\n- Never infer that a visible host CPU, memory pool, or GPU is usable inside a\n  scheduler allocation or container.\n\nThe bundled detector uses only fixed executable/argument tuples, no shell,\nshort timeouts, bounded stdout/stderr, and partial-failure warnings.\n\n## Quick start\n\nRun from this skill directory.\n\n### Ephemeral stdout snapshot\n\n```bash\npython scripts/detect_resources.py\n```\n\nThe command emits only JSON to stdout. Redirect it only when ordinary shell\npermissions are acceptable.\n\n### Explicit private file\n\n```bash\npython scripts/detect_resources.py --output resource-snapshot.json\n```\n\nExplicit output is restricted to one `.json` filename in the current\ndirectory, uses private permissions, rejects symlinks and path traversal, and\nrefuses overwrite unless `--force` is supplied.\n\n### Optional psutil enhancement\n\nThe standard-library detector works without installation. For broader\ncross-platform physical-core, affinity, available-memory, swap, and disk\ncoverage:\n\n```bash\nuv pip install \"psutil==7.2.2\"\n```\n\nThe import is lazy. Failure to import psutil becomes a warning, not a fatal\nerror.\n\n### Skip management-tool probes\n\n```bash\npython scripts/detect_resources.py --skip-accelerators\n```\n\nUse this when accelerator discovery latency is undesirable. The detector still\nsummarizes the presence and state of allowlisted visibility variables without\nreturning their values.\n\n## Required interpretation\n\n### CPU\n\nRead these as different facts:\n\n- `cpu.host.logical`: system-visible scheduling units.\n- `cpu.host.physical`: physical topology, or null; never inferred from logical\n  count.\n- `cpu.process.affinity_logical`: current affinity-set size when supported.\n- `cpu.cgroup_v2.cpuset_logical`: effective cgroup cpuset size.\n- `cpu.cgroup_v2.quota_cores`: finite `cpu.max` capacity, possibly fractional.\n- `scheduler.allocation.cpu_per_process`: bounded Slurm per-task\n  interpretation when scope is clear.\n- `cpu.effective.capacity_cores`: minimum positive observed constraint.\n- `cpu.effective.worker_ceiling`: conservative floor for CPU process workers.\n\nA quota of 1.5 is CPU-time capacity, not 1.5 physical cores. Affinity and\ncpusets constrain placement; quota constrains bandwidth.\n\n### Memory\n\nKeep these separate:\n\n- host total/available memory;\n- current cgroup usage, hard `memory.max`, and remaining hierarchical capacity;\n- `memory.high`, which is a pressure/throttle boundary rather than a hard cap;\n- scheduler memory allocation and its scope; and\n- conservative effective hard limit and available estimate.\n\nOn Apple silicon, `memory.model` is `unified_cpu_gpu`. Do not add integrated GPU\nmemory to RAM or describe it as separate VRAM.\n\n### Accelerators\n\nEach device is a backend **candidate**:\n\n- NVIDIA GPU → CUDA candidate;\n- AMD GPU → ROCm candidate;\n- Apple integrated GPU → Metal candidate.\n\nManagement-query visibility does not establish:\n\n1. scheduler/container permission;\n2. device-node access;\n3. driver/runtime compatibility;\n4. framework package compatibility; or\n5. operator/data-type support.\n\nTherefore `runtime_usable_devices` remains null and each device says\n`runtime_compatibility: not_tested`. Visibility/allocation counts are upper\nbounds, not guarantees.\n\n### Disk\n\n`capacity_bytes`, filesystem `free_bytes`, user-available blocks, and a\nnon-writing permission check are distinct. Filesystem or project quotas can\nstill be stricter. The absolute working path is always redacted.\n\n### Scheduler and container\n\nSlurm variables describe allocation scope, but enforcement depends on site\nconfiguration such as task affinity or cgroups. Prefer affinity and cgroup\nobservations as enforcement evidence.\n\nContainer markers identify context; cgroup controls identify limits. A\ncontainer with no finite cgroup value can still see host inventory, and a\nnon-root cgroup is not automatically labeled a container.\n\nSee [`references/resource_semantics.md`](references/resource_semantics.md) for\nthe detailed platform rules.\n\n## Plan a workload\n\nThe planner consumes a validated snapshot and performs no work:\n\n```bash\npython scripts/plan_workload.py resource-snapshot.json \\\n  --workload cpu \\\n  --tasks 100 \\\n  --memory-per-worker-mib 2048\n```\n\nOptional controls:\n\n- `--workers N`: explicit upper bound.\n- `--reserve-memory-mib N`: memory kept outside the worker budget.\n- `--workload cpu|mixed|io`: selects a bounded worker heuristic.\n- `--accelerator none|any|cuda|rocm|metal`: requests a candidate backend\n  decision without claiming usability.\n- `--output plan.json`: explicit private local output; stdout is default.\n\nFor CPU or mixed work, use `suggested_workers` and\n`threads_per_worker` together. Process workers multiplied by BLAS/OpenMP native\nthreads can oversubscribe an allocation.\n\nThe I/O plan permits bounded oversubscription (maximum 32) but labels it a\nheuristic. Benchmark only the real representative workload and stay within\nscheduler/container limits.\n\n## Validate or diff snapshots\n\nValidate:\n\n```bash\npython scripts/snapshot_tools.py validate resource-snapshot.json\n```\n\nDiff resource state while ignoring `observed_at`:\n\n```bash\npython scripts/snapshot_tools.py diff before.json after.json\n```\n\nUse `--include-volatile` to include the timestamp. Inputs must be regular,\nnon-symlink JSON files no larger than 1 MiB. Diffs are bounded.\n\nThe schema and null/zero meanings are documented in\n[`references/snapshot_schema.md`](references/snapshot_schema.md).\n\n## Optional accelerator diagnostic plan\n\nGenerate a plan without executing any diagnostic:\n\n```bash\npython scripts/accelerator_diagnostics.py resource-snapshot.json \\\n  --backend auto\n```\n\nThe result contains fixed, read-only management query argument lists and\nseparate gates for visibility, permission, and runtime compatibility. Run a\nframework's official availability check only in the exact environment that\nwill execute the workload. Do not install or mutate drivers automatically.\n\n## Partial failures and provenance\n\nOne failed probe must not erase successful observations. Inspect:\n\n- `completeness`;\n- sorted `warnings` with stable codes;\n- sorted `provenance` source/status records; and\n- null fields.\n\nSubprocess stderr and raw exception text are not copied into the snapshot\nbecause they can contain identifiers or paths.\n\n## Platform notes\n\n- **Linux:** reads only bounded `/proc` and cgroup v2 files. Ancestor CPU and\n  memory limits are considered.\n- **macOS:** uses fixed `sysctl` keys and a bounded\n  `system_profiler SPDisplaysDataType -json` query. Apple silicon memory is\n  unified.\n- **Windows:** optional psutil improves physical-core, affinity, available\n  memory, and swap observations. Processor-group scope can make host and\n  process counts differ.\n- **Slurm:** reads an allowlist of allocation variables. It never emits job,\n  node, submit-host, GPU-ID, or path values.\n- **NVIDIA/AMD:** management CLIs are optional. Absence is normal; timeout,\n  truncation, parse failure, and runtime uncertainty remain explicit.\n\n## Bundled files\n\n- `scripts/detect_resources.py` — redacted snapshot collector.\n- `scripts/plan_workload.py` — deterministic worker/memory planner.\n- `scripts/snapshot_tools.py` — schema validator and bounded structural diff.\n- `scripts/accelerator_diagnostics.py` — non-executing read-only diagnostic\n  plan.\n- `tests/get-available-resources/` in the repository root — network-free\n  Linux, macOS, Windows, cgroup, Slurm, and accelerator cases.\n- `references/resource_semantics.md` — interpretation and platform details.\n- `references/snapshot_schema.md` — schema 1.1 contract.\n- `references/sources.md` — dated official-source ledger.\n\nOfficial documentation was refreshed on **2026-07-23**; consult\n[`references/sources.md`](references/sources.md) before changing semantics or\ndependency pins.","author":"@K-Dense-AI","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/get-available-resources","license":"MIT","category":"writing","lang":"en","tokens":1884,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/resource_semantics.md","size":9180,"sha256":"3b4085d73cb4697b7b5776b6f7d3d62ff9bf3a2e18e773ec5ad70a209325b2b9"},{"path":"references/snapshot_schema.md","size":5606,"sha256":"a5852a32fd56f503f4b4c7857090a039a7921e6ecae290b8b7796927358281ee"},{"path":"references/sources.md","size":7277,"sha256":"e570dd93116e337bb3203c463808194e236976e41df565e913e4549df631b346"},{"path":"scripts/accelerator_diagnostics.py","size":4623,"sha256":"1b39815180c32917a88574bbd1477f7e02e6861642e3926a60261274a06baaa8"},{"path":"scripts/_common.py","size":6068,"sha256":"cefeb42d44648b5636053cd3d3d4e08723b4e07df27daa8c8ca1e235d596ca42"},{"path":"scripts/detect_resources.py","size":59840,"sha256":"f6063f23acb9fb2f57263e015c0bfcd07dda2088f5317481e723e2c538174945"},{"path":"scripts/plan_workload.py","size":10799,"sha256":"eb378d23db082ed3e389fb016fd5031ce196806a2c60031a45293cab5d8bc000"},{"path":"scripts/snapshot_tools.py","size":16960,"sha256":"c636c2ae4993f5fcddd9520d85d80bcbad6cc3d4769fd85427cf8f2752dbc87d"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"developer.apple.com, docs.docker.com, docs.kernel.org, docs.nvidia.com, docs.python.org, learn.microsoft.com, psutil.readthedocs.io, rocm.docs.amd.com","message":"bundled scripts reach 11 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["developer.apple.com","docs.docker.com","docs.kernel.org","docs.nvidia.com","docs.python.org","learn.microsoft.com","psutil.readthedocs.io","rocm.docs.amd.com","slurm.schedmd.com","specs.opencontainers.org","www.kernel.org"]}}