UPLOAD_INSTRUCTIONS.md

# Instructions to Upload to Hugging Face

This repository is ready to be pushed to Hugging Face Model Hub!

## Quick Setup (5 minutes)

### Step 1: Create Hugging Face Repository

1. Go to https://huggingface.co/new
2. Fill in:
   - **Model name**: `nfqa-multilingual-classifier`
   - **License**: Apache 2.0 (recommended) or your choice
   - **Visibility**: Public (or Private if you prefer)
3. Click **"Create model"**
4. **Important**: Copy your repository URL from the page

### Step 2: Get Your Access Token

1. Go to https://huggingface.co/settings/tokens
2. Click **"New token"**
3. Name: `model-upload`
4. Type: **Write** (important!)
5. Click **"Generate token"**
6. **Copy the token** (you won't see it again)

### Step 3: Connect This Repository

Replace `YOUR_USERNAME` with your actual Hugging Face username:

```bash
cd /Users/alisalman/thesis/nfqa-multilingual-classifier

# Add Hugging Face as remote
git remote add origin https://huggingface.co/YOUR_USERNAME/nfqa-multilingual-classifier

# Configure git to use your HF credentials
git config credential.helper store

# Push to Hugging Face (you'll be prompted for username and token)
git push -u origin master
```

When prompted:
- **Username**: Your Hugging Face username
- **Password**: Paste your access token (not your password!)

### Step 4: Verify Upload

1. Go to `https://huggingface.co/YOUR_USERNAME/nfqa-multilingual-classifier`
2. You should see:
   - ✅ All model files (11 files)
   - ✅ README with full documentation
   - ✅ Training visualizations (confusion matrix, training curves)
   - ✅ Model card with usage examples
3. Test the **Inference API** widget with a question

---

## Alternative: Use Hugging Face CLI

If you prefer using the CLI:

```bash
# Install if not already installed
pip install --upgrade huggingface_hub

# Login
huggingface-cli login
# Paste your token when prompted

# Create repository
huggingface-cli repo create nfqa-multilingual-classifier --type model

# Upload
cd /Users/alisalman/thesis/nfqa-multilingual-classifier
huggingface-cli upload nfqa-multilingual-classifier . --repo-type model
```

---

## What's Included

This repository contains:

✅ **Model Files** (1.1 GB total):
- `model.safetensors` - Model weights
- `config.json` - Model configuration
- `tokenizer.json` - Tokenizer
- `tokenizer_config.json` - Tokenizer settings
- `sentencepiece.bpe.model` - Vocabulary
- `special_tokens_map.json` - Special tokens

✅ **Documentation**:
- `README.md` - Comprehensive model card
- `classification_report.txt` - Per-category performance
- `test_results.json` - Detailed evaluation metrics

✅ **Visualizations**:
- `confusion_matrix.png` - Test set confusion matrix
- `training_curves.png` - Training/validation curves

✅ **Git Configuration**:
- `.gitattributes` - LFS tracking for large files
- `.gitignore` - Ignore patterns

---

## Before You Push

### Update README Placeholders

Edit [README.md](README.md) and replace:
- `[Your Name/Organization]` → Your actual name
- `[Specify your license]` → Your license choice
- `your-username/nfqa-multilingual-classifier` → Your actual repo URL
- `[Your email]` → Your contact email
- `[Your repository]` → Your GitHub repo (if any)

You can edit directly on Hugging Face after uploading, or do it now:

```bash
nano README.md
# or use your preferred editor
```

---

## Troubleshooting

### Error: "Repository not found"
- Make sure you created the repository on huggingface.co first
- Check that the username in the URL matches your HF username

### Error: "Authentication failed"
- Make sure you're using your **token** as password, not your account password
- Verify the token has **Write** permissions
- Try `git credential reject` to clear cached credentials

### Error: "Large file not properly tracked"
- LFS is already configured in this repo
- Just push normally, git-lfs will handle large files automatically

### Upload is very slow
- The model is ~1.1 GB, this is normal
- It may take 5-15 minutes depending on your internet speed
- Git LFS uploads large files efficiently

---

## After Upload

1. **Test the model**:
   ```python
   from transformers import pipeline

   classifier = pipeline("text-classification",
                        model="YOUR_USERNAME/nfqa-multilingual-classifier")
   result = classifier("What is the capital of France?")
   print(result)
   ```

2. **Add widget examples** in the README YAML front matter (optional)

3. **Share your model** on social media, papers, etc.

4. **Monitor usage** at `https://huggingface.co/YOUR_USERNAME/nfqa-multilingual-classifier/tree/main`

---

## Quick Reference

```bash
# View repository status
cd /Users/alisalman/thesis/nfqa-multilingual-classifier
git status

# View commit history
git log --oneline

# Check remote URL
git remote -v

# Push updates (after making changes)
git add .
git commit -m "Update model card"
git push
```

---

**Need help?**
- Hugging Face Docs: https://huggingface.co/docs/hub
- Git LFS Guide: https://git-lfs.github.com/

**Ready to push?** Follow Step 3 above!