# HIS.js Model Publishing Strategy

## 🚨 **Important: Built-in Models NOT Included in npm Package**

The built-in GGUF models (`src/model/his.gguf` - 397MB) are **NOT** included in the published npm package for these reasons:

1. **Package Size** - Would make npm package 400MB+ instead of 45KB
2. **Download Performance** - Poor user experience downloading large packages
3. **NPM Limits** - npm has size restrictions for packages
4. **Storage Costs** - Expensive to host large models on npm registry
5. **Version Control** - Models should be versioned separately from code

## 📦 **Current Package Structure**

```json
{
  "files": [
    "dist",           // 45KB - Core library code
    "README.md",      // Documentation
    "LICENSE",        // MIT License
    "docs"            // Additional docs
  ]
}
```

**Published Package Size: ~45KB** ✅

## 🎯 **Recommended Solutions**

### **Option 1: External Model Download (Recommended)**

Users download models on first use:

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

const his = new HisJS({
  projectRoot: process.cwd(),
  localAI: {
    autoDownload: true,  // Auto-download if missing
    modelUrl: 'https://github.com/yourusername/his-js-models/releases/download/v1.0.0/his.gguf',
    tokenizerUrl: 'https://github.com/yourusername/his-js-models/releases/download/v1.0.0/tokenizer.json',
    enableCache: true
  }
});

await his.initialize(); // Downloads models if needed
```

### **Option 2: User-Provided Models**

Users provide their own GGUF models:

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

### **Option 3: Separate Model Package**

Create a separate package for models:

```bash
# Main package
npm install @his-js/core

# Models (optional)
npm install @his-js/models
```

## 🔧 **Implementation Plan**

### **Phase 1: Update LocalAI Class**
Add auto-download capability:

```typescript
export interface LocalAIConfig {
  modelPath?: string;
  tokenizerPath?: string;
  autoDownload?: boolean;
  modelUrl?: string;
  tokenizerUrl?: string;
  // ... other config
}
```

### **Phase 2: Model Download Service**
```typescript
private async downloadModels(): Promise<void> {
  if (this.config.autoDownload && !await this.checkModelsExist()) {
    console.log('Downloading HIS.js models...');
    await this.downloadFile(this.config.modelUrl!, this.builtinModelPath);
    await this.downloadFile(this.config.tokenizerUrl!, this.builtinTokenizerPath);
  }
}
```

### **Phase 3: Create Model Repository**
- Separate GitHub repo: `his-js-models`
- Release models as GitHub releases
- Provide direct download URLs

## 📊 **Size Comparison**

| Approach | Package Size | Download Time | User Experience |
|----------|---------------|---------------|----------------|
| Built-in Models | 400MB+ | Very Slow | ❌ Poor |
| Auto-Download | 45KB + 400MB once | Fast first time | ✅ Good |
| User-Provided | 45KB | Fast | ✅ Flexible |
| Separate Package | 45KB + optional | Fast | ✅ Modular |

## 🎯 **Recommended User Experience**

### **For Quick Start:**
```javascript
// Zero config - auto-downloads models
const his = new HisJS({
  localAI: { autoDownload: true }
});
```

### **For Production:**
```javascript
// Use company's own models
const his = new HisJS({
  localAI: {
    modelPath: '/company/models/optimized-llm.gguf',
    tokenizerPath: '/company/models/tokenizer.json'
  }
});
```

### **For Offline:**
```javascript
// Models already downloaded locally
const his = new HisJS({
  localAI: {
    modelPath: './offline-models/his.gguf'
  }
});
```

## 🚀 **Benefits of This Approach**

1. **Fast Installation** - 45KB package installs instantly
2. **Flexible Models** - Users can choose any GGUF model
3. **Offline Support** - Models work without internet after download
4. **Version Control** - Models and code versioned separately
5. **Cost Effective** - No expensive npm storage for large files
6. **Better UX** - Progressive loading, not blocked by large downloads

## 📝 **Next Steps**

1. ✅ **Update package.json** - Exclude model files
2. 🔄 **Implement auto-download** - Add download capability
3. 📦 **Create model repository** - Host models separately  
4. 📚 **Update documentation** - Explain model setup
5. 🧪 **Test download flow** - Verify user experience

This approach keeps the main package lightweight while providing the convenience of built-in models through smart downloading.