README.md

---
title: Marine Guard API
emoji: 🌊
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# Marine Guard API 🌊

FastAPI backend for the Marine Pollution Detection and Incident Management System.

## 🚀 Features

- 🔐 **JWT Authentication** - Secure user registration and login
- 🤖 **ML-Powered Classification** - AI incident analysis with 87.8% threat accuracy, 81.0% severity accuracy
- 🗄️ **MongoDB Atlas Integration** - Cloud database with graceful fallback
- 🌐 **CORS-Enabled** - Ready for frontend integration
- 🏥 **Health Monitoring** - Built-in health checks and monitoring
- 📊 **Interactive API Docs** - Swagger UI available at `/docs`

## 🎯 API Endpoints

### Authentication
- `POST /api/auth/register` - User registration
- `POST /api/auth/login` - User login

### Incidents
- `GET /api/incidents` - Get user incidents (requires auth)
- `POST /api/incidents` - Create new incident (requires auth)
- `POST /api/incidents/classify` - Classify incident text using ML

### Monitoring
- `GET /health` - Health check endpoint
- `GET /` - API status

## 🔧 Environment Variables

Set these in your Hugging Face Spaces environment:

```
MONGODB_URI=your_mongodb_atlas_connection_string
JWT_SECRET_KEY=your_secure_secret_key
ALLOWED_ORIGINS=https://your-frontend-domain.com
```

## 🤖 ML Model Details

### Threat Classification Model
- **Accuracy**: 87.8%
- **Classes**: Oil, Chemical, Other
- **Algorithm**: TF-IDF + Random Forest

### Severity Classification Model  
- **Accuracy**: 81.0%
- **Classes**: high, medium, low
- **Algorithm**: TF-IDF + Random Forest

### Fallback System
- Automatic rule-based classification if ML models unavailable
- Confidence scores provided for all predictions

## 📱 Frontend Integration

This API is designed to work with the Marine Pollution Detection frontend. Set your frontend's API base URL to:

```
VITE_API_BASE_URL=https://your-space-name.hf.space/api
```

## 🛠️ Development

Built with:
- **FastAPI** 0.115.2 - Modern Python web framework
- **Motor** - Async MongoDB driver
- **scikit-learn** - Machine learning models
- **Pydantic** - Data validation
- **Passlib** - Password hashing
- **PyJWT** - JSON Web Token handling

## 📊 Health & Monitoring

The API includes comprehensive health checking:
- Database connectivity testing
- Model loading verification
- Graceful degradation for service issues

Visit `/health` for real-time status information.