eizen-nsga 1.0.4
Production-ready inference library for NSGA-Net neural architecture search models with support for computer vision, tabular data, and transformer models
License: MIT
Requires Python: >=3.8

# eizen-nsga

A production-ready inference package for NSGA-Net trained models with a YOLO-like API for seamless deployment.

## Features

- **Standalone Package**: Fully independent with no external dependencies on the NSGA-Net training codebase
- **Simple API**: Load models from ZIP files or URLs and run inference with minimal code
- **Remote Model Loading**: Supports HTTP, HTTPS, S3, GCS, and other remote storage backends
- **YOLO-Style Interface**: Familiar API design with class name mapping for easy integration
- **Multi-Task Support**: Handles classification and object detection tasks
- **Flexible Deployment**: Use locally, in containers, or cloud environments

## Installation

```bash
# For SOTA (computer vision) models
pip install eizen-nsga[sota]

# For NN (tabular) models
pip install eizen-nsga[nn]

# For Transformer (LLM) models
pip install eizen-nsga[transformer]

# Install all dependencies
pip install eizen-nsga[all]
```

## Quick Start

```python
from eizen_nsga import NASModel

# Load model from local ZIP file
model = NASModel("trained_model.zip")

# Or load from URL (HTTP, HTTPS, S3, GCS, etc.)
model = NASModel("https://example.com/models/model.zip")
model = NASModel("s3://mybucket/models/model.zip")

# Run inference (accepts file path, PIL Image, or numpy array)
result = model.predict("image.jpg")

# Classification results
print(f"Top class: {result['class']}")
print(f"Confidence: {result['confidence']:.2%}")
print(f"Top 5 predictions: {result['predictions']}")

# Or call directly like YOLO
result = model("image.jpg")
```

## Detection Models

```python
from nsga_inference import NASModel

# Load detection model
model = NASModel("detector.zip")

# Run detection
result = model.predict("image.jpg", conf_threshold=0.3, iou_threshold=0.45)

# Detection results
print(f"Found {result['count']} objects")
for det in result['detections']:
    print(f"  Box: {det['box']}, Class: {det['class']}, Conf: {det['confidence']}")
```

## Model Info

```python
# Get model information
info = model.info()
print(f"Category: {info['category']}")
print(f"Task: {info['task']}")
print(f"Backbone: {info['backbone']}")
print(f"Classes: {info['num_classes']}")
```

## Device Selection

```python
# Auto-detect device (default)
model = NASModel("model.zip")

# Specify device
model = NASModel("model.zip", device="cuda")
model = NASModel("model.zip", device="cpu")

# Move to different device
model.to("cuda")
```

## How It Works

1. **Extract**: Automatically extracts model ZIP file
2. **Parse**: Reads `log.txt` to get model configuration (genome, backbone, etc.)
3. **Build**: Constructs model architecture from genome encoding
4. **Load**: Loads trained weights from `weights.pt`
5. **Predict**: Runs inference on your images

## Supported Model Categories

- **SOTA**: Computer vision models with YOLOv8, ResNet, and EfficientNet backbones (fully supported)
- **NN**: Tabular data models (planned)
- **Transformer**: Large language models (planned)

## Model ZIP Structure

Your trained model ZIP should contain:
```
model.zip
├── weights.pt       # Trained model weights
└── log.txt          # Model configuration (genome, backbone, etc.)
```

## Package is Fully Standalone

This package includes all necessary SOTA modules internally:
- Model builders (micro/macro architectures)
- Genome encoders/decoders
- Neural operations
- Backbone registry
- Detection heads

No need to have the NSGA-Net training codebase installed!

## Requirements

**Core dependencies:**
- torch >= 1.9.0
- torchvision >= 0.10.0
- numpy >= 1.19.0
- pillow >= 8.0.0

**Optional (for SOTA models):**
- ultralytics >= 8.0.0

## License

MIT License - Copyright (c) 2024 Eizen.ai Team

## Links

- Homepage: https://eizen.ai
- GitHub: https://github.com/eizen-ai/nsga-net
- Issues: https://github.com/eizen-ai/nsga-net/issues