# HuggingFace Model Upload Instructions

## Setup

1. Install HuggingFace CLI:
```bash
pip install huggingface_hub
huggingface-cli login
# Enter token: hf_YOUR_TOKEN_HERE
```

2. Create model repository on HuggingFace (visit https://huggingface.co/new-model):
```
Model ID: quantflux-3-0-trial-244-xgb
Visibility: Public
Type: Model
```

## Upload Methods

### Method 1: Using huggingface_hub (Recommended)

```bash
from huggingface_hub import HfApi
api = HfApi()

# Create repo
api.create_repo(
    repo_id="quantflux-3-0-trial-244-xgb",
    repo_type="model",
    exist_ok=True
)

# Upload all files
api.upload_folder(
    folder_path="/home/ubuntu/QuantFlux-3.0/huggingface_package",
    repo_id="quantflux-3-0-trial-244-xgb",
    repo_type="model"
)
```

### Method 2: Using Git CLI

```bash
cd /home/ubuntu/QuantFlux-3.0/huggingface_package

# Initialize git
git init
git config user.email "quantflux@example.com"
git config user.name "QuantFlux Team"

# Add LFS support
git lfs install

# Add all files
git add .

# Commit
git commit -m "QuantFlux Alpha (Test Model for 3.0) Trial 244 Alpha Alpha XGBoost Model v1.0"

# Add HuggingFace remote
git remote add origin https://huggingface.co/quantflux-3-0-trial-244-xgb

# Push to HuggingFace
git push -u origin main
```

### Method 3: Python Script

```python
#!/usr/bin/env python3
import os
from huggingface_hub import HfApi, CommitOperationAdd
from pathlib import Path

api = HfApi()
token = "hf_YOUR_TOKEN_HERE"
repo_id = "quantflux-3-0-trial-244-xgb"

# Prepare files
package_dir = Path("/home/ubuntu/QuantFlux-3.0/huggingface_package")
operations = []

for file_path in package_dir.glob("*"):
    if file_path.is_file():
        operations.append(
            CommitOperationAdd(
                path_in_repo=file_path.name,
                path_or_fileobj=str(file_path)
            )
        )

# Upload
api.create_commit(
    repo_id=repo_id,
    operations=operations,
    commit_message="Initial upload: QuantFlux Alpha (Test Model for 3.0) Trial 244 Alpha Alpha XGBoost Model",
    repo_type="model",
    token=token
)

print(f"Model uploaded to: https://huggingface.co/{repo_id}")
```

## Post-Upload Steps

1. Verify all files on HuggingFace:
   - trial_244_xgb.pkl (79 MB)
   - scaler.pkl
   - MODEL_CARD.md
   - TECHNICAL_ARCHITECTURE.md
   - README.md
   - Other documentation files

2. Add model tags:
   - machine-learning
   - trading
   - cryptocurrency
   - bitcoin
   - xgboost
   - time-series
   - forecasting

3. Set model card information:
   - Model ID: quantflux-3-0-trial-244-xgb
   - Task: Binary Classification
   - Domain: Financial/Trading
   - Benchmark: 84.38% accuracy (forward test)

4. Share model link:
   - https://huggingface.co/quantflux-3-0-trial-244-xgb

## Verification

After upload, test loading from HuggingFace:

```python
from huggingface_hub import hf_hub_download
import pickle

# Download model
model_path = hf_hub_download(
    repo_id="quantflux-3-0-trial-244-xgb",
    filename="trial_244_xgb.pkl"
)
scaler_path = hf_hub_download(
    repo_id="quantflux-3-0-trial-244-xgb",
    filename="scaler.pkl"
)

# Load
with open(model_path, 'rb') as f:
    model = pickle.load(f)
with open(scaler_path, 'rb') as f:
    scaler = pickle.load(f)

print("Model loaded successfully!")
print(f"Model type: {type(model)}")
print(f"Scaler type: {type(scaler)}")
```

## Troubleshooting

### Large File Upload Issues
- Ensure git-lfs is installed: `git lfs install`
- Check .gitattributes includes *.pkl files
- Verify file size: 79 MB model should be handled by LFS

### Token Issues
- Verify token is valid: `huggingface-cli whoami`
- Check token has write permissions to org/user

### Network Issues
- Use `--resume-download` flag if upload interrupted
- Consider uploading in smaller batches

## File Manifest

Total files: 10
Total size: ~165 MB

Documentation:
- README.md (4.2 KB) - Quick start
- MODEL_CARD.md (19 KB) - Full specifications
- TECHNICAL_ARCHITECTURE.md (29 KB) - System design
- PACKAGE_CONTENTS.txt (13 KB) - File index

Models:
- trial_244_xgb.pkl (79 MB) - XGBoost model
- scaler.pkl (983 B) - Feature scaler

Metadata:
- model_metadata.json (6.6 KB) - Hyperparameters
- feature_names.json (2.7 KB) - Feature list
- FEATURE_FORMULAS.json (7.5 KB) - Feature specs

Configuration:
- .gitattributes (143 B) - Git LFS config
- UPLOAD_INSTRUCTIONS.md (this file)

## Next Steps

1. Upload package using one of the methods above
2. Verify all files are accessible
3. Test model loading from HuggingFace
4. Share model URL publicly
5. Monitor downloads and usage
6. Accept feedback and issues from community