Metadata-Version: 2.4
Name: lilith-gpu-devices
Version: 0.1.0
Summary: GPU device selection, VRAM tracking, and multi-GPU management
Author-email: Lilith <lilith@nasty.sh>
License-Expression: MIT
Keywords: cuda,device-management,gpu,ml,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == 'torch'
Description-Content-Type: text/markdown

# GPU Tools

GPU utilities for ML services: device selection, VRAM tracking, and process monitoring.

## Packages

| Package | Description | Install |
|---------|-------------|---------|
| `lilith-gpu-devices` | Device selection, VRAM tracking, multi-GPU | `pip install -e ./devices` |
| `lilith-gpu-status` | GPU process monitoring CLI | `pip install -e ./status` |

## Installation

```bash
# Device utilities
pip install -e ./devices
pip install -e ./devices[torch]  # with PyTorch integration

# Status CLI
pip install -e ./status
```

## Usage

### gpu-status CLI

```bash
# Show GPU status and running services
gpu-status

# Live monitoring (updates every 2s)
gpu-status -w
gpu-status --watch
```

Output shows GPU info, memory usage, and running processes with service names:

```
╭─────────────────────────────────────────────────────────────────╮
│ GPU 0: NVIDIA GeForce RTX 3090  │  42°C  │  5.2 / 24.0 GB (22%) │
│ GPU 1: NVIDIA GeForce RTX 3090  │  38°C  │  1.1 / 24.0 GB  (5%) │
╰─────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────╮
│ Service               │ GPU │ VRAM    │ PID   │ Command                   │
├───────────────────────┼─────┼─────────┼───────┼───────────────────────────┤
│ conversation-ml       │ 0   │ 4.8 GB  │ 12345 │ python -m conv_ml         │
│ image-pipeline        │ 0,1 │ 6.2 GB  │ 12346 │ python -m image_pipeline  │
╰───────────────────────────────────────────────────────────────────────────╯
```

### GPU_SERVICE_NAME

Services should set `GPU_SERVICE_NAME` for monitoring visibility:

```bash
GPU_SERVICE_NAME=my-ml-service python -m my_service
```

Without it, services appear as "python" or the command name.

### Device Selection (lilith-gpu-devices)

```python
from gpu_devices import get_best_device, is_cuda_available

# Check CUDA availability
if is_cuda_available():
    device = get_best_device()  # Returns device with most free VRAM
```

## Integration

The `lilith-ml-service-base` package automatically warns if `GPU_SERVICE_NAME` is not set when creating ML services.

```python
# In your service - set GPU_SERVICE_NAME before importing
import os
os.environ["GPU_SERVICE_NAME"] = "my-service"

from lilith_ml_service_base import create_ml_service
app = create_ml_service(...)
```

## Workflow Integration

The lilith-platform includes a workflow wrapper:

```bash
./workflow/gpu          # runs gpu-status
./workflow/gpu -w       # live monitoring
```
