Metadata-Version: 2.4
Name: cjm-substrate-torch-utils
Version: 0.0.13
Summary: PyTorch helpers for cjm-substrate capabilities: GPU memory release, typed CUDA-OOM handling, and device selection.
Author-email: "Christian J. Mills" <9126128+cj-mills@users.noreply.github.com>
License: Apache-2.0
Project-URL: Repository, https://github.com/cj-mills/cjm-substrate-torch-utils
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cjm-substrate>=0.0.51
Requires-Dist: numpy
Requires-Dist: torch
Dynamic: license-file

# cjm-substrate-torch-utils

<!-- generated from the context graph by `cjm-context-graph readme` — do not edit by hand; edit the graph (the urge to hand-edit = move it on-graph) -->

PyTorch helpers for cjm-substrate capabilities: GPU memory release, typed CUDA-OOM handling, and device selection.

## Modules

- **`cjm_substrate_torch_utils.device`** — Resolve a device spec (auto / cpu / cuda / cuda:N) to a concrete torch device string.
- **`cjm_substrate_torch_utils.memory`** — Robust move-to-CPU + drop-references + gc + CUDA-cache cleanup for releasing models, factored out of the per-capability reimplementations.
- **`cjm_substrate_torch_utils.oom`** — Convert torch CUDA out-of-memory exceptions into the substrate's typed CapabilityResourceError (SG-47 Track B) so CR-7 reactive retry can evict and reload.

## API

### `cjm_substrate_torch_utils.device`

- `resolve_torch_device` _function_ — Resolve a device spec to a concrete torch device string.

### `cjm_substrate_torch_utils.memory`

- `release_model` _function_ — Release one or more model objects: move to CPU, drop references, gc, free CUDA cache.

### `cjm_substrate_torch_utils.oom`

- `cuda_oom_to_capability_resource_error` _function_ — Convert a CUDA out-of-memory exception into a substrate-typed `CapabilityResourceError`.
