> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bioptimus.runtime.pt2

Utilities for inspecting AOT-compiled .pt2 model packages.

Extracts target architecture information from the embedded ELF binaries (.cubin for CUDA, .so for CPU) without unpacking the full archive. Also reads model metadata (input/output shapes, dtypes) from the `model_metadata.json` embedded in the package.

## PackageArchInfo

```python theme={null}
@dataclass
class PackageArchInfo()
```

Architecture information extracted from a .pt2 package.

***

#### cuda\_compute\_capability

```python theme={null}
@property
def cuda_compute_capability() -> str | None
```

Returns the CUDA compute capability as 'X.Y' string.

***

#### cuda\_gpu\_description

```python theme={null}
@property
def cuda_gpu_description() -> str
```

Returns a human-readable description of the target GPU.

***

#### cpu\_description

```python theme={null}
@property
def cpu_description() -> str
```

Returns a human-readable description of the target CPU.

***

#### get\_package\_arch\_info

```python theme={null}
def get_package_arch_info(pt2_path: str | Path) -> PackageArchInfo
```

Extracts architecture info from a .pt2 package.

Reads only the ELF headers of the first .cubin and .so found in the archive. Does not unpack the full files.

<ParamField body="pt2_path">
  Path to the .pt2 model package.
</ParamField>

**Returns**:

Architecture information for the package.

**Raises**:

* `BioptimusRuntimeError` - If the package archive cannot be read.

***

#### check\_device\_compatibility

```python theme={null}
def check_device_compatibility(
        pt2_path: str | Path,
        device: torch.device | int | None = None) -> str | None
```

Checks if a .pt2 package is compatible with the target device.

<ParamField body="pt2_path">
  Path to the .pt2 model package.
</ParamField>

<ParamField body="device">
  The CUDA device to validate against. Accepts a `torch.device`, an integer device index, or `None`. When `None` (or a bare `"cuda"` device with no index), the current CUDA device is used. This ensures the check inspects the GPU the worker was actually assigned rather than always device 0.
</ParamField>

**Returns**:

None if compatible, or a descriptive error message if not.

## TensorSpec

```python theme={null}
@dataclass
class TensorSpec()
```

Specification for a single model input or output tensor.

**Attributes**:

* `name` - Name of the tensor (e.g. `"x"`, `"histology_tiles"`).
* `shape` - List of dimension sizes. Dynamic dimensions are represented as the string `_DYNAMIC`; fixed dimensions are integers.
* `dtype` - Expected dtype as a string (e.g. `"float32"`, `"int64"`).
* `description` - Human-readable description from the model metadata.

***

#### fixed\_shape

```python theme={null}
@property
def fixed_shape() -> dict[int, int]
```

Returns a mapping of axis index to fixed size for non-dynamic dims.

***

#### ndim

```python theme={null}
@property
def ndim() -> int
```

Returns the expected number of dimensions.

***

#### shape\_description

```python theme={null}
def shape_description() -> str
```

Returns a human-readable shape string like '(B, 3, 512, 512)'.

**Returns**:

Parenthesised comma-separated dimension description.

## PackageMetadata

```python theme={null}
@dataclass
class PackageMetadata()
```

Model metadata extracted from a .pt2 package.

**Attributes**:

* `model` - Model class name (e.g. `"EfficientUnet"`).
* `inputs` - Ordered list of input tensor specifications.
* `outputs` - Ordered list of output tensor specifications.
* `raw` - The full raw metadata dictionary.

***

#### load\_package\_metadata

```python theme={null}
def load_package_metadata(pt2_path: str | Path) -> PackageMetadata
```

Loads model metadata from a .pt2 package.

Reads the `model_metadata.json` file from the archive without extracting the full package.

<ParamField body="pt2_path">
  Path to the .pt2 model package.
</ParamField>

**Returns**:

Parsed metadata with input/output tensor specifications.

**Raises**:

* `BioptimusRuntimeError` - If the package archive or metadata JSON cannot be read.

***

#### validate\_input\_shapes

```python theme={null}
def validate_input_shapes(metadata: PackageMetadata,
                          tensors: dict[str, torch.Tensor]) -> str | None
```

Validates tensor shapes against the package metadata.

Checks that:

* All expected inputs are present.
* Each tensor has the correct number of dimensions.
* Fixed dimensions match exactly.
* Dynamic dimensions are consistent across inputs (same batch size).

<ParamField body="metadata">
  The package metadata with input specifications.
</ParamField>

<ParamField body="tensors">
  Mapping of input name to tensor.
</ParamField>

**Returns**:

None if all shapes are valid, or a descriptive error message.