# Hugging Face Integration Guide

## 🚀 Clone Models from Hugging Face

HIS.js supports cloning AI models directly from Hugging Face repositories, making it easy to access pre-trained models without manual downloads.

## 📦 Setup

### **Option 1: Clone from Hugging Face (Recommended)**

```javascript
import HisJS from '@his-js/core';

const his = new HisJS({
  projectRoot: process.cwd(),
  localAI: {
    autoDownload: true,
    repoUrl: 'https://huggingface.co/tarun922/his-js',  // Your Hugging Face repo
    enableCache: true
  }
});

await his.initialize(); // Automatically clones if models missing
```

### **Option 2: Clone from Any Git Repository**

```javascript
const his = new HisJS({
  projectRoot: process.cwd(),
  localAI: {
    autoDownload: true,
    repoUrl: 'https://github.com/yourusername/ai-models',  // Any git repo
    enableCache: true
  }
});
```

### **Option 3: Use Local Models**

```javascript
const his = new HisJS({
  projectRoot: process.cwd(),
  localAI: {
    modelPath: './models/my-model.gguf',
    tokenizerPath: './models/tokenizer.json',
    enableCache: true
  }
});
```

## 🔧 Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `autoDownload` | boolean | Enable automatic model download/clone |
| `repoUrl` | string | Git repository URL to clone from |
| `modelUrl` | string | Individual model file download URL |
| `tokenizerUrl` | string | Individual tokenizer file download URL |
| `modelPath` | string | Local path to GGUF model file |
| `tokenizerPath` | string | Local path to tokenizer file |
| `enableCache` | boolean | Enable response caching |

## 📁 Repository Structure

When cloning, HIS.js expects this structure in your repository:

```
your-repo/
├── his.gguf           # Main GGUF model file
├── tokenizer.json     # Tokenizer configuration
└── README.md          # Optional documentation
```

## 🎯 Hugging Face Repository Setup

### **Step 1: Create Hugging Face Repository**

1. Go to [Hugging Face](https://huggingface.co/new)
2. Create a new repository (e.g., `tarun922/his-js`)
3. Upload your GGUF model and tokenizer files

### **Step 2: Upload Model Files**

```bash
# Install huggingface-cli
pip install huggingface_hub

# Upload your model
huggingface-cli upload his.gguf --repo-id tarun922/his-js
huggingface-cli upload tokenizer.json --repo-id tarun922/his-js
```

### **Step 3: Use in HIS.js**

```javascript
const his = new HisJS({
  localAI: {
    autoDownload: true,
    repoUrl: 'https://huggingface.co/tarun922/his-js'
  }
});
```

## 🔄 How It Works

### **Repository Cloning Process**

1. **Check Local Models** - Looks for existing models first
2. **Clone Repository** - `git clone` if models missing
3. **Update Paths** - Points to cloned model files
4. **Load Models** - Initializes AI with cloned models
5. **Fallback Gracefully** - Uses rule-based responses if cloning fails

### **Directory Structure After Cloning**

```
.his/
├── models/
│   └── his-js/           # Cloned repository
│       ├── .git/
│       ├── his.gguf       # Model file
│       ├── tokenizer.json  # Tokenizer
│       └── README.md
├── sessions/
├── events/
└── ...
```

## 🚀 Advanced Usage

### **Multiple Model Support**

```javascript
// Clone different models for different tasks
const hisForCode = new HisJS({
  localAI: {
    repoUrl: 'https://huggingface.co/tarun922/his-js-code'
  }
});

const hisForChat = new HisJS({
  localAI: {
    repoUrl: 'https://huggingface.co/tarun922/his-js-chat'
  }
});
```

### **Custom Clone Directory**

```javascript
const his = new HisJS({
  projectRoot: process.cwd(),
  localAI: {
    autoDownload: true,
    repoUrl: 'https://huggingface.co/tarun922/his-js',
    modelPath: './custom-models/his.gguf',  // Override cloned location
    tokenizerPath: './custom-models/tokenizer.json'
  }
});
```

### **Update Existing Models**

```javascript
// HIS.js automatically pulls latest changes on re-initialization
await his.initialize(); // Git pull if repo exists
```

## 🛠️ Troubleshooting

### **Git Not Available**

If `git` is not available on the system, HIS.js will:
- ⚠️ Show warning about git not being available
- 🔄 Fall back to rule-based responses
- 📝 Continue working without AI models

### **Repository Not Found**

```
Error: Failed to clone repository: Repository not found
```

**Solution:** Check the repository URL and ensure it's accessible.

### **Model Files Missing**

```
Models cloned but files not found at expected paths
```

**Solution:** Ensure your repository contains `his.gguf` and `tokenizer.json` files.

### **Permission Issues**

```
Error: Failed to clone repository: Permission denied
```

**Solution:** Check git permissions and repository access rights.

## 📊 Performance

### **Clone Time**
- **Small models (<100MB):** 10-30 seconds
- **Medium models (100-500MB):** 30-60 seconds  
- **Large models (>500MB):** 1-3 minutes

### **Storage Requirements**
- **Models:** Varies by model size
- **Repository:** Full git history
- **Cache:** Response cache (few MB)

### **Network Usage**
- **Initial clone:** Full repository size
- **Updates:** Git diff size only
- **After clone:** Zero network usage

## 🎯 Best Practices

### **1. Use Specific Models**
```javascript
// Good: Specific model for task
const his = new HisJS({
  localAI: {
    repoUrl: 'https://huggingface.co/tarun922/his-js-code'  // Code-specific
  }
});
```

### **2. Handle Network Issues**
```javascript
try {
  await his.initialize();
} catch (error) {
  console.log('Using fallback responses due to network issues');
}
```

### **3. Monitor Clone Status**
```javascript
const status = his.getLocalAIStatus();
if (!status.isReady) {
  console.log('Models not ready, using fallbacks');
}
```

### **4. Update Models Regularly**
```javascript
// Re-initialize to pull latest changes
await his.initialize();
```

## 🔒 Security Considerations

- **Repository Access:** Ensure repository is public or accessible
- **Model Verification:** Only clone from trusted sources
- **Network Security:** Cloning uses standard git protocol
- **Local Storage:** Models stored locally after cloning

## 🎉 Benefits

### **For Users**
- 🚀 **Easy Setup** - One-line configuration
- 🔄 **Auto Updates** - Git pull latest changes automatically
- 📁 **Organized** - Models kept in dedicated directories
- 🛡️ **Fallback Safe** - Works even if cloning fails

### **For Developers**
- 📦 **Version Control** - Models versioned with git
- 🔄 **Easy Updates** - Push model updates to repository
- 🌐 **Universal Access** - Clone from any git repository
- 📊 **Analytics** - Track model usage and performance

### **For Teams**
- 👥 **Shared Models** - Team uses same model repository
- 🔄 **Consistent Models** - Everyone has same model version
- 📈 **Scalable** - Easy to add new models
- 🔧 **Flexible** - Different repos for different use cases

This approach combines the convenience of automatic model management with the power and flexibility of git version control!