# Superezio Enterprise - Arquitetura de Monitoramento de GPU

Este documento detalha a arquitetura do sistema de gerenciamento e monitoramento de hardware, focado em GPUs NVIDIA, implementado no projeto `superezio_enterprise`.

## 1. Visão Geral

O objetivo deste sistema é mover de uma simulação para um gerenciamento de hardware real e em tempo real. O `HardwareManager` agora interage diretamente com os drivers da NVIDIA para descobrir, monitorar e alocar recursos de GPU de forma inteligente. Isso é essencial para aplicações de IA e Machine Learning que dependem de uso eficiente de VRAM e poder computacional.

## 2. Dependência Principal

- **Biblioteca**: `nvidia-ml-py`
- **Descrição**: Este pacote fornece os bindings Python para a **NVIDIA Management Library (NVML)**, que é uma API C para monitorar e gerenciar GPUs NVIDIA. É a mesma biblioteca que alimenta a ferramenta `nvidia-smi`.
- **Instalação**: A dependência foi adicionada ao `requirements.txt`.

## 3. Arquitetura do `HardwareManager`

O `HardwareManager` foi completamente redesenhado e opera como um singleton thread-safe com os seguintes componentes:

### 3.1. Inicialização e Descoberta Automática

- Na inicialização, o `HardwareManager` chama `nvmlInit()`.
- Ele detecta automaticamente o número de GPUs NVIDIA disponíveis no sistema (`nvmlDeviceGetCount()`).
- Se nenhuma GPU for encontrada, ele emite um aviso e opera em um modo degradado onde nenhuma alocação pode ser feita.
- Para cada GPU descoberta, ele obtém e armazena um *handle*, que é um ponteiro para a GPU usado em todas as operações subsequentes.

### 3.2. Monitoramento em Background

- Para evitar que chamadas de monitoramento bloqueiem o loop de eventos principal da aplicação, o `HardwareManager` inicia uma **thread de monitoramento dedicada** (`_monitor_loop`).
- Esta thread executa um loop contínuo que, a cada `gpu_monitoring_interval_seconds` (configurável em `config.py`), chama a função `update_all_gpu_states()`.
- A função `update_all_gpu_states()` coleta as seguintes métricas para cada GPU:
  - **Uso de Memória (VRAM)**: Total, livre e usada (em MB).
  - **Utilização do Núcleo da GPU**: Em porcentagem (%).
  - **Temperatura**: Em graus Celsius (°C).
  - **Consumo de Energia**: Em Watts (W).
- Os dados coletados são armazenados em um dicionário de `GpuState` (um dataclass), que fornece um snapshot consistente e thread-safe do estado das GPUs.

### 3.3. Lógica de Alocação Inteligente

A função `assign_model_to_gpu` foi aprimorada para tomar decisões baseadas em dados reais:

- **Input**: Recebe o nome de um modelo e, crucialmente, a **VRAM estimada que ele requer** (`required_vram_mb`).
- **Processo de Decisão**:
  1. Verifica se o modelo já está alocado.
  2. Itera sobre os estados mais recentes de todas as GPUs (obtidos pela thread de monitoramento).
  3. Filtra as GPUs que possuem **VRAM livre suficiente** para atender à requisição.
  4. Dentre as candidatas, seleciona aquela com a **menor utilização de núcleo (%)** como critério de desempate.
  5. Se nenhuma GPU puder atender à requisição, a alocação falha e um erro é logado.
- **Output**: Retorna o ID da GPU alocada ou `None` em caso de falha.

### 3.4. Liberação e Desligamento

- A função `release_model` remove um modelo das alocações, permitindo que outros modelos usem os recursos.
- A função `shutdown` é crucial: ela para a thread de monitoramento e chama `nvmlShutdown()` para liberar todos os recursos da NVML de forma limpa.

## 4. Integração com Outros Módulos

- **HealthManager**: Um novo health check (`gpu_status`) foi adicionado. Ele verifica se as GPUs estão acessíveis e se suas temperaturas estão dentro de limites seguros (atualmente < 90°C), marcando o sistema como `UNHEALTHY` em caso de superaquecimento.
- **main.py**: O fluxo de demonstração foi atualizado para refletir o novo sistema. Ele tenta alocar modelos com diferentes requisitos de VRAM e imprime um relatório ao vivo do estado das GPUs no console, mostrando a eficácia do monitoramento.

## 5. Como Usar

1.  **Instale as dependências**: `pip install -r requirements.txt`.
2.  **Execute a aplicação**: `python -m superezio_enterprise.main`.
3.  **Observe o Console**: O log mostrará a descoberta das GPUs, o processo de alocação de modelos e um relatório de status ao vivo impresso a cada 5 segundos durante a demonstração.