Melanoma Skin Cancer Classification Model

Challenge participants: Build a model to classify skin lesion images as Benign or Malignant (Melanoma).

Table of Contents

• Quick Start
• Introduction
• Requirements
• Project Structure
• Detailed Tutorial
• Submission Guidelines
• License

Quick Start

Clone the repository:

git clone [email protected]:AIOZAI/Melanoma_Skin_Cancer_Model.git

Or download directly: Melanoma Skin Cancer Baseline

Then navigate into the project directory and follow the steps below:

# 1. Install dependencies (do not add any other libraries to requirements.txt)
pip install -r requirements.txt

# 2. Implement your solution by following the tutorial below

# 3. Run the demo to test your implementation
python demo.py

# 4. Verify your submission
python -m my_ai_lib.predict_submission

Note: You need to implement your Melanoma classification solution following the tutorial guide.

Introduction

The Melanoma Skin Cancer Classification Challenge is a medical AI competition in which participants predict whether a skin lesion image is Benign or Malignant. It is a binary classification problem on high-resolution dermatoscopic images.

Participants are provided with:

• Model access: Melanoma Skin Cancer Baseline

  • A code baseline to build your solution on.
  • Predefined libraries and tools in requirements.txt (do not add any other libraries).

• Dataset access: Melanoma Skin Cancer Dataset

  • A training set to train your model (includes ground_truth.csv).
  • A test set to predict labels for generating the submission file.

Goal: Classify each skin lesion image as Benign (0) or Malignant (1).

Requirements

System Requirements

• Python 3.10+

Dependencies

Install all required packages:

pip install -r requirements.txt

Project Structure

Your AI library should follow this structure:

repository/
├── my_ai_lib/                   # Your AI library
│   ├── __init__.py              # Required: library initialization
│   ├── run.py                   # Required: main workflow function
│   ├── predict_submission.py    # Required: submission function
│   └── [your_modules]/          # Your custom modules
├── models/                      # Model weights directory
├── demo.py                      # Demo script
├── requirements.txt             # Dependencies
└── README.md                    # Documentation

Description

• The input and output of the AI model are defined in my_ai_lib/run.py.
• The AI model is designed to process a single input item (an image file path).
• In my_ai_lib/predict_submission.py, you process all items in the test dataset and save the results to result.csv in the required submission format.
• See the instructions below for full details.

Key Components

Component	Description	Status
my_ai_lib/	Core AI library directory	Required
my_ai_lib/__init__.py	Library initialization	Required
my_ai_lib/run.py	Main AI workflow	Required
my_ai_lib/predict_submission.py	Generates predictions for challenge submission	Required
demo.py	Demo and testing script	Required

Detailed Tutorial

Step 1: Initialize Your AI Library

1.1 Define my_ai_lib/__init__.py

from .run import run

This exposes the run() function from run.py as an attribute of my_ai_lib, so it can be called as my_ai_lib.run().

1.2 Define Input/Output Objects in my_ai_lib/run.py

Create your custom input and output classes:

from pathlib import Path
from typing import Any, Union, Literal
from aioz_ainode_adapter.schemas import InputObject, OutputObject, FileObject

class MelanomaInput(InputObject):
    # Local path to the skin lesion image
    image_path: str

class MelanomaOutput(OutputObject):
    # Predicted class (0: Benign, 1: Melanoma)
    label: int

Step 2: Understanding AIOZ Schema Objects

The aioz_ainode_adapter library defines 3 core object types based on pydantic.BaseModel:

🔸 InputObject

Defines the input format that the AIOZ-AI-Node system sends to your AI library.

Default parameters:

Parameter	Type	Description
device	Choice	Device for your model: "cuda", "cpu", or "gpu"
model_storage_directory	String	Directory containing model weights

Important: Always use model_storage_directory for model weight paths, as AIOZ-AI-Node will specify this location.

🔸 OutputObject

Defines the output format that your AI library returns to the AIOZ-AI-Node system.

🔸 FileObject

Defines the format for a file output. It has two fields:

Field	Type	Description
data	Choice	File data: io.BufferedReader, Path, or URL
name	String	File name

Example:

output_file = FileObject(data=open("file/path.csv", "rb"), name="output.csv")

Note:

• Input files must be local file paths or URLs.
• Output files must be FileObject instances.

Step 3: Implement the Main Workflow

3.1 Define Your AI Task Function

def do_ai_task(
        image_path: str,
        model_storage_directory: Union[str, Path],
        device: Literal["cpu", "cuda", "gpu"] = "cpu",
        *args, **kwargs) -> int:
    """
    Predict whether a skin lesion is Malignant (Melanoma) based on the image.

    Args:
        image_path: Path to the image file.
        model_storage_directory: Directory containing trained model weights.
        device: Device to run inference on ("cpu", "cuda", or "gpu").

    Returns:
        Predicted class (0: Benign, 1: Melanoma).
    """
    # 1. Load and preprocess the image from image_path
    # Example using Pillow:
    # from PIL import Image
    # img = Image.open(image_path)

    # 2. Run prediction using your trained model
    # label = model.predict(img)
    label = 0
    return label

3.2 Implement the Required run() Function

def run(input_obj: InputObject) -> OutputObject:
    """
    Main entry point for the Melanoma Skin Cancer Classification library.

    Args:
        input_obj: Input object containing the image path and parameters.

    Returns:
        Output object containing the predicted label.
    """
    try:
        # Validate and parse input
        melanoma_input = MelanomaInput.model_validate(input_obj.model_dump())

        # Execute AI task
        label = do_ai_task(
            image_path=melanoma_input.image_path,
            model_storage_directory=melanoma_input.model_storage_directory,
            device=melanoma_input.device
        )

        # Create output object
        output_obj = MelanomaOutput(label=label)
    except Exception as e:
        raise Exception(e)

    return output_obj

Critical: The run() function name is mandatory and cannot be changed. do_ai_task() can be renamed and customized.

Step 4: Create a Demo Script

Create demo.py to test your implementation:

import my_ai_lib
from aioz_ainode_adapter.schemas import InputObject

def main():
    """Demo function to test the Melanoma Classification library."""
    # Path to a skin lesion image
    image_path = "path/to/skin_lesion_image.jpg"

    input_obj = InputObject(image_path=image_path)
    output_obj = my_ai_lib.run(input_obj)
    print(f"Output: {output_obj}")

    # Map label to class name
    class_names = {0: "Benign", 1: "Melanoma"}
    print(f"Predicted Class: {class_names.get(output_obj.label, 'Unknown')}")

if __name__ == '__main__':
    main()

The my_ai_lib.run() function receives an InputObject and returns an OutputObject.

Run this command to test your implementation:

python demo.py

Expected console output:

Input: device='cpu' model_storage_directory='models' image_path='path/to/skin_lesion_image.jpg'
Output: label=0
Predicted Class: Benign

Step 5: Add Model Weights

Place your trained model files in the models/ directory:

models/
├── model.pth          # Your trained model
├── config.json        # Model configuration
└── ...

Step 6: Create the Prediction Script (for Private Submission)

Implement the predict_submission() function in my_ai_lib/predict_submission.py.

Requirements

• Function accepts the test data folder path (string).
• Loads your trained model.
• Processes the test dataset (images in the test data folder).
• Generates predictions.
• Saves results to ./result.csv.

Implementation Template

import os
import csv
import my_ai_lib
from aioz_ainode_adapter.schemas import InputObject

def predict_submission(test_data_folder: str):
    """
    Generate predictions for challenge submission.

    Args:
        test_data_folder: Path to the test data directory.
    """
    # 1. Locate the test images folder
    test_folder = test_data_folder
    for root, dirs, files in os.walk(test_data_folder):
        if any(f.endswith(('.jpg', '.jpeg', '.png')) for f in files):
            test_folder = root
            break

    image_files = [f for f in os.listdir(test_folder) if f.endswith(('.jpg', '.jpeg', '.png'))]
    print(f"Found {len(image_files)} images in {test_folder}")

    # 2. Process each image
    results = []
    for filename in image_files:
        image_path = os.path.join(test_folder, filename)

        # Call run() with the image path
        output_obj = my_ai_lib.run(InputObject(image_path=image_path))

        # id is the filename, label is the prediction (0 or 1)
        results.append({"id": filename, "label": output_obj.label})

    # 3. Save to ./result.csv
    with open("./result.csv", "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=["id", "label"])
        writer.writeheader()
        writer.writerows(results)

    print(f"Saved {len(results)} predictions to ./result.csv")

def main():
    """Entry point for testing submission."""
    predict_submission("path/to/test/data")

if __name__ == '__main__':
    main()

Important: result.csv must match the challenge's sample submission format.

Verify Your Submission

python -m my_ai_lib.predict_submission

Submission Guidelines

Submission Format

The submission file has two fields:

• id: The image filename.
• label: The target class (0: Benign, 1: Melanoma).

Example:

id,label
9c9a204a57f34a71b9454fef633f7038.jpg,0
cec04296a9bf4b969a8770f3ee2b439f.jpg,1

License

This repository is licensed under the MIT License.