Pneumonia Chest X-Ray Classification Challenge Model

Challenge participants: Build robust chest x-ray model solutions.

Table of Contents

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

Quick Start

Download code baseline

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

# 2. Start developing your solution. Follow the tutorial below to implement your AI model

# 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 pneumonia chest X-ray model following the tutorial guide.

Introduction

The Chest X-ray Classification Challenge is a medical AI project where you classify chest X-ray images to detect pneumonia based on radiological patterns. Perfect for mastering computer vision and medical image analysis techniques!

AIOZ Pneumonia Chest X-Ray Classification Challenge

In this challenge, participants will be provided with:

• Model Access: Pneumonia Chest X-Ray Model

  • Code baseline to develop solutions.
  • Predefined libraries and tools in requirements.txt (Do not add any other libraries to requirments.txt file).

• Dataset Access:Pneumonia Chest X-Ray Data

  • Training dataset to train your AI models.
  • Testing dataset to predict labels for generating the submission file.

Goal: Build and improve solutions based on provided resources while fostering creativity in model design and training strategies.

Requirements

System Requirements

• Python 3.10+
• CUDA-compatible GPU (recommended)

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.
• In my_ai_lib/predict_submission.py, we process all items in the test dataset and save the results to result.csv in the required submission format.
• Please refer to the instructions below for more 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	Submission function	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 file exposes the run() function from run.py as an attribute of the my_ai_lib, allowing it to be called via 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 MyInput(InputObject):
    input_image: str
    example_param: Any

class MyOutput(OutputObject):
    text: str
    output_image: FileObject

Step 2: Understanding AIOZ Schema Objects

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

🔸 InputObject

Define the format for input when the AIOZ-AI-Node system sends it to your AI library.

Default Parameters:

Parameter	Type	Description
device	Choice	Device for your model: ["cuda", "cpu", "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

Define the format for output when your AI library sends to the AIOZ-AI-Node system.

🔸 FileObject

Define the format for the file, if your output has a file. This object has two fields:

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

Example FileObject creation:

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

Note:

• If your input param have a file, it must be a local file path or URL.
• If your output has a file, it must be a FileObject.

Step 3: Implement the Main Workflow

3.1 Define Your AI Task Function

def do_ai_task(
        input_image: Union[str, Path],
        example_param: Any,
        model_storage_directory: Union[str, Path],
        device: Literal["cpu", "cuda", "gpu"] = "cpu",
        *args, **kwargs) -> Any:
    """
    Define AI task: load model, pre-process, post-process, etc.
    
    Args:
        input_image: Path to input image
        example_param: Example parameter
        model_storage_directory: Directory containing model weights
        device: Computing device
        
    Returns:
        Result
    """
    # Define your AI task workflow. Below is an example
    text = "This is the AI task result"
    output_image = open("wiki/aioz.png", "rb")  # io.BufferedReader
    return text, output_image

3.2 Implement the Required run() Function

def run(input_obj: InputObject) -> OutputObject:
    """
    Main entry point for your AI library.
    
    Args:
        input_obj: Input object containing all parameters
        
    Returns:
        OutputObject: Results of AI processing
    """
    # Validate and parse input
    my_input = MyInput.model_validate(input_obj.model_dump())
    print(f"Input: {my_input}")

    # Execute AI task
    text, output_image = do_ai_task(
        input_image=my_input.input_image,
        example_param=my_input.example_param,
        model_storage_directory=my_input.model_storage_directory,
        device=my_input.device
    )

    # Create output object
    output_file = FileObject(data=output_image, name="output_image.png")
    output_obj = MyOutput(text=text, output_image=output_file)
    return output_obj

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

Step 4: Create 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 your AI library."""
    input_obj = InputObject(
        input_image="wiki/aioz.png", 
        example_param="example"
    )
    output_obj = my_ai_lib.run(input_obj)
    print(f"Output: {output_obj}")

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: type='InputObj' device='cuda' model_storage_directory='models' input_image='wiki/aioz.png' example_param='example'
Output: type='OutputObj' text='This is the AI task result' output_image=FileObject(type='FileObj', data=<_io.BufferedReader name='wiki/aioz.png'>, name='output_image.png')

Step 5: Add Model Weights

Place your trained model files in the models/ directory:

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

Step 6: Create Prediction Script (For Private Submission)

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

Requirements:

• Function accepting test data folder path (string).
• Load your trained model.
• Process test dataset.
• Generate predictions.
• Save results as ./result.csv

Implementation Template:

from aioz_ainode_adapter.schemas import InputObject
import my_ai_lib

def predict_submission(test_data_folder: str):
    """
    Generate predictions for challenge submission.
    
    Args:
        test_data_folder: Path to test data directory
    """
    # Load your model
    # Process test data
    # Generate predictions
    # Save to ./result.csv

    # Example:
    # Find test data folder (contains X-ray images - can use os.walk() to find all image files)
    # Loop with each image:
    # - You define InputObject
    #     input_obj = InputObject(
    #     input_image=str(img_path),
    #     example_param=str(example),
    # )
    # - Output (label is predicted from your model): output = my_ai_lib.run(input_obj)
    # - Write the predicted label (output.text) to result.csv (format: id, label)
    pass

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

if __name__ == '__main__':
    main()

Important: The 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 field:

• id: The unique name corresponding to each image.
• label: The predicted label for the corresponding image.

Example:

id,label
ce6e440e-2cfc-4684-97d7-fa3a7db7d799.jpeg,0
dec0a17f-9981-423e-8e0e-ebee7cb51b23.jpeg,1

License

This repository is licensed under the MIT License.