# HuggingFace Plugin

Automatic model management and download from HuggingFace repositories.

## Overview

**Enabled by Default**: Manages HuggingFace model downloads with automatic caching. Supports multiple repositories and models with configurable paths for weights and config files.

## Configuration

Configure models in `huggingface.yaml`:

```yaml
plugin.huggingface:
  enabled: true

huggingface:
  auto_download: true  # Automatically download models on startup
  repositories:
    reflectorch:
      repo_id: "valentinsingularity/reflectivity"
      models:
        - name: "model_name"
          config: "configs/model_config.yaml"
          weights: "saved_models/model_weights.safetensors"
    
    my_custom_repo:
      repo_id: "organization/repository-name"
      models:
        - name: "my_model"
          config: "path/to/config.yaml"
          weights: "path/to/weights.pt"
```

### Configuration Fields

| Field | Type | Description |
|-------|------|-------------|
| `auto_download` | `bool` | Enable automatic model download on startup |
| `repositories` | `dict` | Collection of HuggingFace repositories |
| `repo_id` | `str` | HuggingFace repository identifier (org/repo) |
| `models` | `list` | List of models to download from repository |
| `name` | `str` | Model identifier for your application |
| `config` | `str` | Path to config file in repository |
| `weights` | `str` | Path to model weights in repository |

## Model Storage

### Environment Variables

Two environment variables control where models are stored:

**`HF_HOME`** - General HuggingFace cache directory (default: `~/.cache/huggingface`):
```bash
export HF_HOME=${PWD}/storage/huggingface_cache
```

**`REFLECTORCH_ROOT_DIR`** - Reflectorch-specific storage directory (required for reflectorch models):
```bash
export REFLECTORCH_ROOT_DIR=${PWD}/storage/reflectorch
```

### Directory Structure

With `REFLECTORCH_ROOT_DIR` set, reflectorch models are organized as:
```
storage/reflectorch/
├── saved_models/     # Model weights (.safetensors, .pt)
└── configs/          # Model configuration files (.yaml)
```

Other models use the standard HuggingFace cache structure in `HF_HOME`.

## CLI Commands

### Download Models

Manually trigger model downloads:

```bash
vipr --config huggingface.yaml huggingface download
```

This downloads all configured models from HuggingFace repositories to the local cache.

**Use Cases:**
- Pre-deployment: Download models before production
- Offline scenarios: Cache models for air-gapped environments
- CI/CD: Prepare models during build process

## Adding Custom Models

### Step 1: Identify Repository

Find your model on HuggingFace: `https://huggingface.co/organization/repository-name`

### Step 2: Add to Configuration

```yaml
huggingface:
  repositories:
    my_project:  # Unique identifier for your use
      repo_id: "organization/repository-name"  # HuggingFace repo
      models:
        - name: "my_model_identifier"  # Name used in your code
          config: "path/in/repo/config.yaml"
          weights: "path/in/repo/model.safetensors"
```

### Step 3: Download

```bash
vipr --config huggingface.yaml huggingface download
```

## Supported Weight Formats

- `.safetensors` - Recommended format (faster, safer, no pickle)
- `.pt` - Standard PyTorch format
- `.bin` - Older PyTorch format (pickle-based)

## Example: Multiple Models

```yaml
huggingface:
  auto_download: true
  repositories:
    xray_models:
      repo_id: "valentinsingularity/reflectivity"
      models:
        - name: "xray_standard"
          config: "configs/xray_config.yaml"
          weights: "saved_models/xray_model.safetensors"
        - name: "xray_advanced"
          config: "configs/xray_advanced_config.yaml"
          weights: "saved_models/xray_advanced_model.safetensors"
    
    neutron_models:
      repo_id: "organization/neutron-analysis"
      models:
        - name: "neutron_standard"
          config: "configs/neutron.yaml"
          weights: "models/neutron.pt"
```

## Disabling Auto-Download

For manual control over downloads:

```yaml
huggingface:
  auto_download: false  # Disable automatic downloads
```

Then manually download when needed:
```bash
vipr --config huggingface.yaml huggingface download
```

## See Also

- [Inference Plugin](inference.md) - Model loading and inference
- [HuggingFace Hub Documentation](https://huggingface.co/docs/hub) - Repository structure