hypergen 0.1.0
Optimized inference and fine-tuning framework for diffusion (image & video) models.
License: MIT
Requires Python: >=3.10
Keywords: ai, deep-learning, diffusion, flux, image-generation, lora, sdxl, stable-diffusion

<div align="center">

![HyperGen](.assets/header.webp)

# HyperGen

**Train & run diffusion models 3x faster with 80% less VRAM**

Optimized inference and fine-tuning framework for image & video diffusion models.

![Status](https://img.shields.io/badge/status-pre--alpha-orange)
![Python](https://img.shields.io/badge/python-3.10+-blue)
![License](https://img.shields.io/badge/license-MIT-green)

</div>

---

## ✨ Simple as 5 Lines

```python
from hypergen import model, dataset

m = model.load("stabilityai/stable-diffusion-xl-base-1.0")
ds = dataset.load("./my_images")
lora = m.train_lora(ds, steps=1000)
```

That's it! HyperGen handles optimization, memory management, and acceleration automatically.

## 🚀 Features

- **Dead Simple API**: Train LoRAs in 5 lines of code
- **Universal**: Works with FLUX, SDXL, SD3, CogVideoX, and more
- **Optimized**: Built on top of diffusers, PEFT, and PyTorch
- **Flexible**: Simple for beginners, powerful for experts

## Installation

```bash
pip install hypergen
```

### From Source

```bash
git clone https://github.com/ntegrals/hypergen.git
cd hypergen
pip install -e .
```

## Quick Start

### Load a Dataset

```python
from hypergen import dataset

# Load images from a folder
ds = dataset.load("./my_training_images")
print(f"Loaded {len(ds)} images")

# Supports captions too!
# Just put a .txt file next to each image:
#   my_images/
#     photo1.jpg
#     photo1.txt  <- "A beautiful sunset"
#     photo2.jpg
#     photo2.txt  <- "A mountain landscape"
```

### Train a LoRA

```python
from hypergen import model, dataset

# Load model
m = model.load("stabilityai/stable-diffusion-xl-base-1.0")
m.to("cuda")

# Load dataset
ds = dataset.load("./my_images")

# Train LoRA
lora = m.train_lora(ds, steps=1000)
```

### Advanced Options

```python
# Customize everything
lora = m.train_lora(
    ds,
    steps=2000,
    learning_rate=5e-5,
    rank=32,                    # LoRA rank
    alpha=64,                   # LoRA alpha
    batch_size=2,               # Or "auto"
    save_steps=500,             # Save checkpoints
    output_dir="./checkpoints"
)
```

### Generate Images

```python
# Basic generation
image = m.generate("A cat holding a sign that says hello world")

# With options
images = m.generate(
    ["A sunset", "A mountain"],
    num_inference_steps=30,
    guidance_scale=7.5
)
```

## 🎯 Supported Models

HyperGen works with any diffusion model from HuggingFace:

- **FLUX.1**: `black-forest-labs/FLUX.1-dev`
- **SDXL**: `stabilityai/stable-diffusion-xl-base-1.0`
- **SD 3**: `stabilityai/stable-diffusion-3-medium-diffusers`
- **CogVideoX**: `THUDM/CogVideoX-5b` (video)
- Any other diffusers-compatible model

## 🌐 Serve Models (OpenAI-Compatible API)

HyperGen provides a production-ready API server with request queuing, similar to vLLM:

### Start Server

```bash
# Basic serving
hypergen serve stabilityai/stable-diffusion-xl-base-1.0

# With authentication
hypergen serve stabilityai/stable-diffusion-xl-base-1.0 \
  --api-key token-abc123

# With LoRA
hypergen serve stabilityai/stable-diffusion-xl-base-1.0 \
  --lora ./my_lora \
  --api-key token-abc123

# Custom settings
hypergen serve black-forest-labs/FLUX.1-dev \
  --port 8000 \
  --dtype bfloat16 \
  --max-queue-size 100 \
  --max-batch-size 4
```

### Use with OpenAI Client

```python
from openai import OpenAI

# Point to your HyperGen server
client = OpenAI(
    api_key="token-abc123",
    base_url="http://localhost:8000/v1"
)

# Generate images (OpenAI-compatible API)
response = client.images.generate(
    model="sdxl",
    prompt="A cat holding a sign that says hello world",
    n=2,
    size="1024x1024"
)
```

### Features

- **OpenAI-Compatible**: Drop-in replacement for OpenAI's image generation API
- **Request Queue**: Automatic request batching and queuing
- **LoRA Support**: Load and switch LoRAs dynamically
- **Authentication**: Optional API key authentication
- **Production-Ready**: Built on FastAPI + uvicorn

See [examples/serve_client.py](examples/serve_client.py) for complete examples.

## 📖 Examples

Check out the [examples/](examples/) directory:

- [quickstart.py](examples/quickstart.py) - Minimal 5-line example
- [complete_example.py](examples/complete_example.py) - All features demonstrated
- [serve_client.py](examples/serve_client.py) - API client examples

## 🏗️ Architecture

```
hypergen/
├── model/       # Model loading and management
├── dataset/     # Dataset handling
├── training/    # LoRA training pipelines
├── serve/       # API server and queue management
├── inference/   # Inference optimizations
└── optimization/ # Performance improvements
```

## 🛣️ Roadmap

**Phase 1**: ✅ Core Architecture
- [x] Model loading
- [x] Dataset handling
- [x] LoRA training scaffold
- [x] OpenAI-compatible API server
- [x] Request queue management
- [ ] Complete training loop implementation

**Phase 2**: ⚡ Optimizations
- [ ] Gradient checkpointing
- [ ] Mixed precision training
- [ ] Flash Attention support
- [ ] Auto-configuration
- [ ] Request batching for inference

**Phase 3**: 🚀 Advanced Features
- [ ] Multi-GPU training
- [ ] Multi-GPU serving
- [ ] Video model support
- [ ] Custom CUDA kernels
- [ ] LoRA hot-swapping

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 📄 License

MIT

---

## 📜 Project History

**Note on Aura Voice**: This repository previously hosted Aura Voice, an early tech demo showcasing AI voice capabilities. As the underlying technology evolved significantly beyond that initial demonstration, the demo is no longer representative of current capabilities and has been deprecated.

Thank you to everyone who supported and used Aura Voice! The original code remains accessible at commit [00c18d2](https://github.com/ntegrals/hypergen/tree/00c18d2) for reference.

HyperGen represents a new direction focused on optimized diffusion model training and serving.