Metadata-Version: 2.4
Name: fastpluggy-ia-tools
Version: 0.1.10
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: FastPluggy>=0.4.17
Requires-Dist: nvidia-ml-py
Requires-Dist: psutil
Requires-Dist: Pillow
Requires-Dist: diffusers>=0.28.0
Requires-Dist: transformers
Requires-Dist: accelerate
Requires-Dist: safetensors
Requires-Dist: gguf>=0.10.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Provides-Extra: tests
Requires-Dist: pytest>=7.0; extra == "tests"
Requires-Dist: pytest-cov>=4.0; extra == "tests"
Provides-Extra: e2e
Requires-Dist: fastpluggy-cli; extra == "e2e"

# IA Tools Plugin

![IA Tools](https://img.shields.io/badge/FastPluggy-IA%20Tools-purple)
[![Release](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/ia_tools/-/badges/release.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/ia_tools/-/releases)
[![Pipeline Status](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/ia_tools/badges/main/pipeline.svg?key_text=CI)](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/ia_tools/-/pipelines?ignore_skipped=true)
[![Coverage](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/ia_tools/badges/main/coverage.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/ia_tools/-/pipelines)

A comprehensive FastPluggy plugin for AI/ML infrastructure monitoring and management.
This plugin provides essential tools for monitoring GPU resources, CUDA environments, and Hugging Face model caches.

## Overview

The IA Tools plugin is designed to help developers and system administrators monitor and manage AI/ML infrastructure components. It provides web-based interfaces for checking GPU status, CUDA availability, and managing Hugging Face model caches.

## Features

### 🖥️ GPU Information & Monitoring
- **Real-time GPU metrics**: Memory usage, utilization, temperature, power consumption, and fan speed
- **GPU process monitoring**: Track processes running on GPUs with detailed system information
- **Multi-GPU support**: Monitor multiple NVIDIA GPUs simultaneously
- **Process details**: View PID, memory usage, username, process name, and command line for GPU processes

### 🔧 CUDA Status & Environment Checking
- **CUDA availability detection**: Check if CUDA toolkit is installed and accessible
- **CUDA version reporting**: Display installed CUDA version information
- **PyTorch GPU support**: Verify PyTorch installation and GPU compatibility
- **Environment validation**: Comprehensive status dashboard for AI/ML development environment

### 🤗 Hugging Face Cache Management
- **Cache directory detection**: Automatically locate Hugging Face model cache
- **Model inventory**: List all cached models with detailed information
- **Storage analysis**: Display cache size, file counts, and storage usage
- **Model type detection**: Identify PyTorch, TensorFlow, ONNX, and Transformers models
- **Environment variable support**: Supports `HF_HOME` and `HUGGINGFACE_HUB_CACHE` configuration

### 🎨 Image Generation (Stable Diffusion)
- **Text-to-image**: Generate images from text prompts using HuggingFace Diffusers
- **Model auto-discovery**: Automatically detects cached Stable Diffusion models
- **Async generation**: Runs on a dedicated `image_gen` worker topic via tasks_worker
- **Gallery**: Browse, search, and filter generated images with pagination
- **Storage options**: Local disk or MinIO (auto-detected via minio_tools plugin)
- **Model hot-swap**: Switch between diffusion models without restarting
- **Thumbnails**: 256px JPEG thumbnails for fast gallery loading

See [docs/image-generation.md](docs/image-generation.md) for the full user guide and [docs/architecture.md](docs/architecture.md) for technical details.

## Installation

### Prerequisites
- Python >= 3.10
- FastPluggy framework
- NVIDIA GPU (optional, for GPU monitoring features)
- CUDA toolkit (optional, for CUDA status features)

### Dependencies
The plugin automatically installs the following dependencies:
- `nvidia-ml-py`: NVIDIA GPU monitoring library (provides the `pynvml` module)
- `psutil`: System and process monitoring

For image generation, install the optional dependencies:
```bash
pip install fastpluggy-ia-tools[image_gen]
```
This adds: `diffusers`, `transformers`, `accelerate`, `safetensors`, `Pillow`.

### Install from Source
```bash
pip install -e .           # core features only
pip install -e ".[image_gen]"  # with image generation
```

## Configuration

### Environment Variables

#### Hugging Face Cache Configuration
- `HUGGINGFACE_HUB_CACHE`: Custom cache directory path (highest priority)
- `HF_HOME`: Hugging Face home directory (cache will be `$HF_HOME/hub`)
- Default: `~/.cache/huggingface/hub`

#### System Configuration
- `PROCFS_PATH`: Custom /proc filesystem path for containerized environments

### Plugin Configuration
The plugin is automatically registered with FastPluggy and appears in the "IA" menu section.

#### Image Generation Settings
| Setting | Default | Description |
|---------|---------|-------------|
| `image_gen_enabled` | `true` | Enable/disable image generation |
| `image_gen_model` | `stabilityai/stable-diffusion-xl-base-1.0` | Default diffusion model |
| `image_gen_output_dir` | `/tmp/image-gen` | Local image storage directory |
| `image_gen_max_steps` | `50` | Maximum inference steps |
| `image_gen_default_width` | `1024` | Default image width |
| `image_gen_default_height` | `1024` | Default image height |
| `image_gen_device` | `auto` | Device: `auto`, `cuda`, or `cpu` |
| `image_gen_storage` | `auto` | Storage backend: `auto`, `local`, or `minio` |
| `image_gen_minio_bucket` | `image-gen` | MinIO bucket name |
| `huggingface_cache_dir` | _(empty)_ | Custom HuggingFace cache path |

## Usage

### Web Interface
Once installed, the plugin provides three main pages accessible through the FastPluggy web interface:

#### 1. GPU Info (`/gpu_info`)
- View detailed information about all available NVIDIA GPUs
- Monitor real-time GPU metrics and utilization
- Track GPU processes and their resource usage

#### 2. CUDA Status (`/cuda_status`)
- Check CUDA toolkit availability and version
- Verify PyTorch GPU support and configuration
- View comprehensive environment status dashboard

#### 3. Hugging Face Cache (`/huggingface_cache`)
- Browse cached Hugging Face models
- View cache summary and storage statistics
- Analyze model types and sizes

### Programmatic Access

#### GPU Monitoring
```python
from fastpluggy_plugin.ia_tools.tools.nvidia_gpu_tool import get_gpu_info, get_gpu_processes

# Get GPU information
gpu_info = get_gpu_info()
for gpu in gpu_info:
    print(f"GPU {gpu['gpu_index']}: {gpu['name']}")
    print(f"Memory: {gpu['used_memory']}/{gpu['total_memory']} MiB")
    print(f"Utilization: {gpu['utilization']}%")

# Get GPU processes
processes = get_gpu_processes()
for proc in processes:
    print(f"PID {proc['pid']}: {proc['process_name']} using {proc['memory_usage']} MiB")
```

#### Environment Checking
```python
from fastpluggy_plugin.ia_tools.widgets import check_nvidia_gpu, check_cuda_version, check_python_gpu_support

# Check NVIDIA GPU availability
has_gpu, gpus = check_nvidia_gpu()
if has_gpu:
    print(f"Found {len(gpus)} GPU(s)")

# Check CUDA version
has_cuda, version = check_cuda_version()
if has_cuda:
    print(f"CUDA version: {version}")

# Check PyTorch GPU support
has_torch, info = check_python_gpu_support()
if has_torch and info['cuda_available']:
    print(f"PyTorch {info['version']} with {info['gpu_count']} GPU(s)")
```

#### Hugging Face Cache Management
```python
from fastpluggy_plugin.ia_tools.tools.huggingface_cache_tool import get_cached_models, get_cache_summary

# Get cache summary
summary = get_cache_summary()
print(f"Cache directory: {summary['cache_directory']}")
print(f"Total models: {summary['total_models']}")
print(f"Total size: {summary['total_size_human']}")

# List cached models
models = get_cached_models()
for model in models:
    print(f"{model['full_name']}: {model['size_human']} ({model['model_type']})")
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/gpu_info` | GET | Display GPU information and processes |
| `/cuda_status` | GET | Show CUDA and PyTorch status dashboard |
| `/huggingface_cache` | GET | List Hugging Face cached models |
| `/image_gen` | GET | Image generation prompt form |
| `/image_gen/gallery` | GET | Generated images gallery |
| `/image_gen/gallery/{id}` | GET | Single image detail page |
| `/api/image_gen/generate` | POST | Submit a generation request |
| `/api/image_gen/status/{id}` | GET | Poll generation status |
| `/api/image_gen/models` | GET | List available diffusion models |
| `/api/image_gen/images/{file}` | GET | Serve generated image |
| `/api/image_gen/thumbnails/{file}` | GET | Serve thumbnail |
| `/api/image_gen/images/{id}` | DELETE | Delete a generated image |

All endpoints require authentication. Image generation endpoints return 503 if `image_gen_enabled=False` or diffusers is not installed.

## Error Handling

The plugin includes comprehensive error handling:
- Graceful degradation when NVIDIA drivers are not available
- Safe handling of missing CUDA installations
- Robust cache directory detection with fallbacks
- Process monitoring with permission handling

## Troubleshooting

### GPU Monitoring Issues
- Ensure NVIDIA drivers are installed and up-to-date
- Verify `nvidia-smi` command is available in PATH
- Check that the user has permissions to access GPU information

### CUDA Detection Problems
- Install CUDA toolkit if not present
- Ensure `nvcc` is available in PATH
- Verify CUDA installation with `nvcc --version`

### Hugging Face Cache Issues
- Check cache directory permissions
- Verify environment variables are set correctly
- Ensure sufficient disk space for cache operations

## Development

### Project Structure
```
src/fastpluggy_plugin/ia_tools/
├── src/
│   ├── plugin.py              # Main plugin class
│   ├── router.py              # FastAPI routes and endpoints
│   ├── widgets.py             # Environment checking utilities
│   └── tools/
│       ├── nvidia_gpu_tool.py # GPU monitoring functions
│       └── huggingface_cache_tool.py # HF cache management
├── pyproject.toml             # Package configuration
├── requirements.txt           # Additional dependencies
└── README.md                  # This file
```

### Contributing
1. Follow the existing code style and patterns
2. Add appropriate error handling and logging
3. Update documentation for new features
4. Test with various GPU configurations and environments

## License

This plugin is part of the FastPluggy ecosystem. Please refer to the main FastPluggy project for license information.

## Version History

- **0.0.12**: Image generation via HuggingFace Diffusers, storage abstraction (local/MinIO), async tasks_worker integration
- **0.0.7**: Full GPU monitoring, CUDA status, and Hugging Face cache management
- **0.0.5**: Added Hugging Face cache functionality
- Earlier versions: Basic GPU monitoring capabilities

## Support

For issues, feature requests, or contributions, please refer to the main FastPluggy project repository.
