QUICK_START.md

# Quick Start Guide - Intel Image Classifier

Get up and running in minutes!

## Prereq: Install Models

Before deploying, you need your trained models. Place them in:

```
backend/api/models/
├── pytorch_model.pth      # PyTorch model weights
└── model_best.keras       # TensorFlow/Keras model
```

**Note**: If you don't have these files yet, see `/ml/` directory for training scripts.

---

## Option A: Deploy to Hugging Face (Recommended ⭐)

### Step 1: Create Space on Hugging Face
1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Choose:
   - Name: `Intel_classification`
   - License: MIT
   - Space SDK: Docker
   - Visibility: Public

### Step 2: Clone and Update Repository
```bash
# Clone this repo
git clone https://github.com/danielle2035/Intel_classification.git
cd Intel_classification

# Add your trained models to backend/api/models/
cp /path/to/pytorch_model.pth backend/api/models/
cp /path/to/model_best.keras backend/api/models/

# Add Hugging Face remote
git remote add hf https://huggingface.co/spaces/YOUR_HF_USERNAME/Intel_classification
```

### Step 3: Deploy!
```bash
git push hf main
```

Done! Watch your Space build and deploy automatically. Access it at:
```
https://huggingface.co/spaces/YOUR_HF_USERNAME/Intel_classification
```

---

## Option B: Run Locally with Docker

### Easiest Way

```bash
# Build the image
docker build -t intel-classifier .

# Run it
docker run -p 7860:7860 intel-classifier
```

Then open: **http://localhost:7860**

### With Docker Compose (Development)

```bash
docker-compose up --build
```

Services:
- Frontend: http://localhost:3000
- Backend: http://localhost:8000
- Docs: http://localhost:8000/swagger

---

## Option C: Run Locally Without Docker

### Backend Setup

```bash
cd backend/api

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r ../requirements.txt

# Run migrations
python manage.py migrate

# Start server
python manage.py runserver 8000
```

Keep terminal open. Backend runs on **http://localhost:8000**

### Frontend Setup (New Terminal)

```bash
cd frontend

# Install dependencies
npm install

# Start development server
npm start
```

Frontend runs on **http://localhost:3000**

---

## Testing Your Deployment

### 1. Check Health
```bash
curl http://localhost:7860/health/
# Expected: {"status": "healthy", "service": "Intel Image Classifier API", "version": "1.0.0"}
```

### 2. Classify an Image
```bash
curl -X POST \
  -F "image=@test_image.jpg" \
  -F "model=pytorch" \
  http://localhost:7860/api/classify/
```

### 3. Visit Web Interface
Open in browser: **http://localhost:7860**

### 4. Check API Docs
- Swagger: **http://localhost:7860/swagger/**
- ReDoc: **http://localhost:7860/redoc/**
- Admin Panel: **http://localhost:7860/admin/** (user: admin, pass: admin)

---

## Troubleshooting

### "Port 7860 already in use"
```bash
# Find what's using it
lsof -i :7860

# Kill the process
kill -9 <PID>
```

### "Models not found"
Ensure these files exist:
- `backend/api/models/pytorch_model.pth`
- `backend/api/models/model_best.keras`

If missing, only one model will be available.

### "CORS Error"
This usually means backend and frontend are on different domains. Verify:
- Docker mode: Both on same domain ✅
- Local dev: Frontend 3000, Backend 8000 - they communicate via proxy ✅
- HF Spaces: Auto-configured ✅

### "Models take too long to load"
First startup loads models into memory. This can take 1-2 minutes for large models. Subsequent requests are fast!

---

## Common Tasks

### Change Confidence Threshold
Edit `backend/api/notifications/api_views.py`:
```python
CONFIDENCE_THRESHOLD = 0.6  # Change this value
```

### Add Custom Classes
Update `CLASSES` list in `backend/api/notifications/api_views.py`:
```python
CLASSES = ["buildings", "forest", "glacier", "mountain", "sea", "street", "YOUR_CLASS"]
```
Then retrain your models.

### Use a Different Model
Add to `backend/api/models/`:
- `pytorch_model.pth`
- `model_best.keras`

The API automatically detects available models.

---

## File Structure Reference

```
intel-classifier/
├── Dockerfile                    # Docker configuration
├── README.md                     # Main documentation
├── DEPLOYMENT.md                # Detailed deployment guide
├── REORGANIZATION.md            # What changed
├── QUICK_START.md              # This file!
│
├── backend/
│   ├── api/notifications/       # Image classification API
│   │   └── api_views.py
│   ├── models/                  # Your trained models
│   │   ├── pytorch_model.pth
│   │   └── model_best.keras
│   └── requirements.txt
│
├── frontend/                    # React web interface
│   ├── src/App.js
│   └── package.json
│
└── ml/                         # Training scripts (for reference)
    └── models/
```

---

## Next Steps

1. ✅ Add your trained models
2. ✅ Test locally (Docker or native)
3. ✅ Push to Hugging Face Spaces
4. ✅ Share with friends!
5. 📊 Monitor predictions at `/admin/`
6. 🔄 Retrain to improve accuracy
7. 🚀 Add more features (authentication, history, etc.)

---

## Support

Need help?

1. **Documentation**: See [DEPLOYMENT.md](DEPLOYMENT.md)
2. **Issues**: [GitHub Issues](https://github.com/danielle2035/Intel_classification/issues)
3. **Discussions**: [HF Space Discussions](https://huggingface.co/spaces/danielle2035/Intel_classification/discussions)

---

**Ready?** Let's go! 🚀

Choose your deployment method above and follow the steps!