README.md

---
title: GP-Tea Skin Analysis
emoji: 🔬
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
---

# GP-Tea Skin Analysis API

An AI-powered skin condition analysis service that provides medical insights from skin images using deep learning.

## Features

- **Image Classification**: Advanced skin condition detection using TensorFlow EfficientNetV2S
- **Medical Analysis**: Comprehensive skin health assessment with confidence scoring
- **Real-time Processing**: Fast inference with optimized model performance
- **REST API**: Easy integration with mobile and web applications

---

## Repository Structure

```
api_image/
├── app/
│   ├── main.py                # FastAPI application with JSON endpoints
│   ├── predict.py             # Image preprocessing and prediction logic
│   ├── model_loader.py        # Loads the trained EfficientNetV2S model
│   ├── model/                 # Local model storage (auto-downloaded if missing)
│   │   └── efficientnetv2s.h5 # Pretrained model file
│   └── uploads/               # Temporary upload directory (auto-created)
├── test_images/               # Sample images for testing the API
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker setup for deployment
└── README.md                  # Project documentation (this file)
```

---

## Features

- **JSON API Endpoints**: Clean REST API for Flutter integration
- **CORS Enabled**: Ready for mobile app cross-origin requests
- **Multi-class Classification**: Supports medical image classification
- **Confidence Scores**: Returns probability percentages for predictions
- **File Upload Support**: Handles image file uploads with validation
- **Error Handling**: Proper HTTP status codes and error messages
- **Health Check**: Monitoring endpoint for service status
- **Temperature Scaling**: Calibrated probabilities for reliable predictions
- **Automatic Cleanup**: Temporary files are automatically removed

---

## Model Details

- Base Model: EfficientNetV2S (20.5 million parameters)
- Dataset: [HAM10000](https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/DBW86T)
- Calibration: Temperature Scaling (optimal T=2.77)
- Performance:
  - Accuracy: 0.88
  - Macro F1-score: 0.80
  - Expected Calibration Error (ECE): 0.022 (after T-scaling)

For full technical details, see the Model Technical Information section in the app.

---

## Model Download from Hugging Face

The model file `efficientnetv2s.h5` is hosted on [Hugging Face Hub](https://huggingface.co/Miguel764/efficientnetv2s-skin-cancer-classifier) and is automatically downloaded the first time the app runs.

How it works:

- Expected local path: `app/model/efficientnetv2s.h5`
- On startup, `app/model_loader.py` checks for the file
- If missing, it is downloaded via `huggingface_hub` and saved to `app/model/`
- Subsequent runs load the local copy

Note for Docker users: When running inside a container, the downloaded model is stored inside the container’s filesystem. Mount a volume if you need to persist it on the host.

Manual download link (optional): https://huggingface.co/Miguel764/efficientnetv2s-skin-cancer-classifier

---

## Installation & Usage

### 1) Install dependencies

```sh
cd Image_classification/api_image
pip install -r requirements.txt
```

**Requirements**: Python 3.8 and TensorFlow 2.10.0 (GPU recommended). (very important!!!!! Must be Python 3.8)

### 2) Run the API server

```sh
  uvicorn app.main:app --host 0.0.0.0 --port 8003 --reload
```

The API will be available at http://localhost:8003

Access the API documentation at http://localhost:8003/docs

### 3) Test the API

Use the sample images in `test_images/` folder to test the endpoints.

---

## API Endpoints

### Health Check

- **GET** `/health` - Service health status

### Image Classification

- **POST** `/api/classify` - Upload and classify medical image

#### Example Request (cURL):

```sh
curl -X POST "http://localhost:8000/api/classify" \
     -H "accept: application/json" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@test_images/sample.jpg"
```

#### Example Response:

```json
{
  "success": true,
  "prediction": {
    "top_prediction": {
      "label": "Melanoma",
      "confidence": 0.95,
      "confidence_percent": "95.00%"
    },
    "all_predictions": [
      {
        "label": "Melanoma",
        "confidence": 0.95,
        "confidence_percent": "95.00%"
      },
      {
        "label": "Benign Nevus",
        "confidence": 0.03,
        "confidence_percent": "3.00%"
      }
    ]
  }
}
```

---

## Flutter Integration

### Base URL Configuration

```dart
class ApiConfig {
  static const String imageApiUrl = "http://localhost:8000";
}
```

---

## Docker Deployment

Build and run the API in a container:

```sh
docker build -t medical-image-api .
docker run -p 8000:8000 medical-image-api
```

---

## Error Handling

The API returns consistent error responses:

```json
{
  "detail": "File must be an image"
}
```

Common HTTP status codes:

- `200` - Success
- `400` - Bad Request (invalid file, missing data)
- `422` - Unprocessable Entity (validation error)
- `500` - Internal Server Error (classification failed)

---

## Technical Notes

- **Backend Only**: No web interface, pure JSON API
- **CORS Enabled**: Ready for mobile app integration
- **File Validation**: Checks file type and validity
- **Temporary Storage**: Uploaded files are automatically cleaned up
- **Model Auto-Download**: Model downloads from Hugging Face on first run
- **Python 3.8 Compatible**: Uses TensorFlow 2.10.0 for compatibility