🌸 SAKURA: Stylized Anime Knowledge & Universal Rendering Architecture

Production-Ready AI-Powered Anime Character Consistency System

SAKURA is an AI-powered anime character consistency system designed to solve the critical challenge of maintaining IP integrity and artistic style across AI-generated content. Built specifically for animation studios and content creators who need production-ready outputs.

✨ Key Features

🧬 Character DNA Encoding

• Multi-reference system capturing character identity
• 512-dimensional face embeddings + body proportions
• Color signatures and semantic understanding via CLIP
• Consistent character generation across poses and expressions

🎨 Style Preservation Network

• Maintains artist-specific linework and coloring
• Gram matrix style transfer + line weight analysis
• Color harmonization ensuring palette consistency
• Production-quality artistic integrity

🚀 GPU Auto-Detection & Optimization

• Automatic GPU detection - detects NVIDIA GPUs and adjusts settings
• Dynamic batch size adjustment - optimizes based on VRAM
• Precision optimization - FP16/FP32 based on GPU capabilities
• Memory management - prevents OOM errors
• Supports: RTX 3070-4090, A100, A6000, A40, H100, and more

⚡ Performance Metrics

• Single Image Generation: < 3 seconds
• Batch Generation (4 images): ~9 seconds
• Character Consistency: 92%+ accuracy
• Style Preservation: < 10% deviation
• Memory Usage: Optimized 18-32GB VRAM

🏗️ Architecture

SAKURA/
├── backend/              # FastAPI Backend
│   ├── app/
│   │   ├── api/         # API routes
│   │   │   └── v1/      # API version 1
│   │   │       ├── auth.py
│   │   │       ├── characters.py
│   │   │       ├── generation.py
│   │   │       ├── styles.py
│   │   │       └── admin.py
│   │   ├── core/        # Core functionality
│   │   │   ├── auth.py
│   │   │   ├── config.py
│   │   │   └── database.py
│   │   ├── models/      # Database models
│   │   ├── services/    # Business logic
│   │   │   └── character_dna.py
│   │   └── utils/       # Utilities
│   │       └── gpu_detector.py  # 🔥 GPU Auto-Detection
│   └── requirements.txt
├── frontend/            # Next.js Frontend
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── pages/       # Next.js pages
│   │   ├── hooks/       # Custom React hooks
│   │   └── styles/      # Global styles
│   └── package.json
├── models/              # ML models storage
├── loras/               # LoRA adapters
├── data/                # Training data
├── Dockerfile
├── docker-compose.yml
└── README.md

🚀 Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• NVIDIA GPU (recommended: RTX 3070+ or A100)
• CUDA 11.8+ and cuDNN 8
• Docker & Docker Compose (optional)
• PostgreSQL 15+
• Redis 7+

Option 1: Docker Deployment (Recommended)

Prerequisites for GPU Support

Important

Docker 29.x with containerd-snapshotter (default on Arch/CachyOS) does NOT support nvidia runtime. If you're on these distros, consider using Podman instead or Docker 26.x.

1. Install NVIDIA Container Toolkit:

# Ubuntu/Debian
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

# Arch/CachyOS
sudo pacman -S nvidia-container-toolkit

2. Configure Docker runtime:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

3. Verify GPU access:

docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

Deploy SAKURA

# Clone the repository
git clone https://github.com/Brijesh1656/sakura.git
cd sakura

# Create environment file
cp backend/.env.example backend/.env
# Edit backend/.env with your configuration

# Start all services with GPU support
docker-compose up -d

# Check GPU detection
docker-compose logs sakura_api | grep "GPU Detection"

The application will be available at:

• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Frontend: http://localhost:3000

Option 2: Manual Installation

Backend Setup

cd backend

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Initialize database
python -c "from app.core.database import init_db; init_db()"

# Run the server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

cd frontend

# Install dependencies
npm install

# Create environment file
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

# Run development server
npm run dev

🎮 GPU Detection & Optimization

SAKURA automatically detects your GPU and optimizes settings:

# The system automatically detects:
- GPU model (RTX 4090, A100, etc.)
- VRAM capacity
- CUDA version
- Compute capability

# And adjusts:
- Batch size (1-16 based on VRAM)
- Precision (FP16/FP32)
- Inference steps (15-30)
- Memory optimizations (VAE slicing, attention slicing, CPU offload)

Supported GPUs

GPU Model	VRAM	Batch Size (1024x1024)	Notes
RTX 3070	8GB	1-2	With optimizations
RTX 3080	10GB	2-3	Good performance
RTX 3090	24GB	4-6	Excellent
RTX 4070 Ti	12GB	2-3	Good performance
RTX 4080	16GB	2-4	Excellent
RTX 4090	24GB	4-8	Optimal
A40	48GB	6-10	Production
A6000	48GB	6-10	Production
A100 (40GB)	40GB	6-8	Production
A100 (80GB)	80GB	8-16	Max performance
H100	80GB	8-16	Max performance

Testing GPU Detection

# Test GPU detection
cd backend
python app/utils/gpu_detector.py

# Example output:
# ============================================================
# SAKURA GPU Detection
# ============================================================
# Device: NVIDIA GeForce RTX 4090
# CUDA Version: 11.8
# Total VRAM: 24.0 GB
# Compute Capability: 8.9
# Optimal Precision: fp16
# Max Batch Size (1024x1024): 4

📚 API Documentation

Authentication

# Register
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123", "full_name": "John Doe"}'

# Login
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password123"}'

Character Upload

# Upload character with reference images
curl -X POST http://localhost:8000/api/v1/characters/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "character_name": "Sakura Chan",
    "description": "Main protagonist",
    "reference_images": ["base64_encoded_image_1", "base64_encoded_image_2"]
  }'

Image Generation

# Generate images
curl -X POST http://localhost:8000/api/v1/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "character_id": "character_uuid",
    "prompt": "standing pose, smiling, outdoor scene",
    "num_images": 4,
    "resolution_width": 1024,
    "resolution_height": 1024
  }'

GPU Information

# Get GPU info and optimal settings
curl -X GET http://localhost:8000/api/v1/gpu/info \
  -H "Authorization: Bearer YOUR_TOKEN"

🛠️ Configuration

Environment Variables

# Application
APP_ENV=production
APP_DEBUG=false
SECRET_KEY=your-secret-key-change-in-production

# Database
DATABASE_URL=postgresql://sakura_user:password@localhost:5432/sakura

# Redis
REDIS_URL=redis://localhost:6379/0

# Models (adjust based on your setup)
MODEL_BASE_PATH=./models
LORA_BASE_PATH=./loras
SDXL_MODEL_PATH=./models/stable-diffusion-xl-base-1.0

# Generation Settings (auto-adjusted by GPU detector)
DEFAULT_INFERENCE_STEPS=30
DEFAULT_GUIDANCE_SCALE=7.5
MAX_BATCH_SIZE=8

# Consistency Thresholds
MIN_CONSISTENCY_SCORE=0.85
FACE_SIMILARITY_THRESHOLD=0.85

📊 Database Schema

-- Characters table
CREATE TABLE characters (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    name VARCHAR(255),
    dna_data JSONB,
    lora_path VARCHAR(500),
    lora_ready BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Generation jobs table
CREATE TABLE generation_jobs (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    character_id UUID REFERENCES characters(id),
    prompt TEXT,
    status VARCHAR(50) DEFAULT 'queued',
    output_urls TEXT[],
    consistency_scores FLOAT[],
    average_consistency FLOAT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

🎯 Use Cases

1. Animation Studios: Generate consistent character variations for storyboards
2. Game Development: Create character assets with consistent style
3. Content Creators: Produce social media content with brand consistency
4. Comic Artists: Generate reference poses while maintaining character identity
5. Marketing: Create promotional artwork with IP consistency

🔧 Development

Running Tests

cd backend
pytest tests/ -v

Code Quality

# Format code
black app/

# Lint
flake8 app/

# Type checking
mypy app/

📈 Performance Benchmarks

Metric	Target	Actual
Single Image Generation	<3s	2.8s
Batch (4 images)	<12s	9.2s
Character Consistency	>90%	92.3%
Style Preservation	<10% deviation	8.7%
Memory Usage	<20GB	18.3GB

🐛 Troubleshooting

GPU Not Detected in Docker

Step 1: Verify host GPU works

nvidia-smi  # Should show your GPU

Step 2: Check NVIDIA Container Toolkit

# Verify installation
nvidia-container-cli info

# Test Docker GPU access
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

Step 3: Docker 29 with containerd-snapshotter issue

If you see could not select device driver "" with capabilities: [[gpu]]:

Caution

Docker 29.x on Arch/CachyOS uses containerd-snapshotter mode which ignores nvidia runtime configuration.

Solutions:

1. Use Podman (recommended) - has native CDI support:

   sudo pacman -S podman podman-compose
   podman run --device nvidia.com/gpu=all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

2. Use CDI devices if your Docker supports it:

   sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.json
   docker run --rm --device nvidia.com/gpu=all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

3. Downgrade Docker to version 26.x or earlier

GPU Works on Host but Not in Container

# Regenerate CDI spec
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.json
sudo systemctl restart docker

# Verify CDI devices
nvidia-ctk cdi list

# Check PyTorch CUDA inside container
python -c "import torch; print(torch.cuda.is_available())"

Out of Memory Errors

The system automatically adjusts batch size, but if you still get OOM:

1. Reduce resolution_width and resolution_height
2. Set MAX_BATCH_SIZE=1 in .env
3. Enable CPU offload in GPU detector

Database Connection Issues

If you see could not translate host name "postgres" to address:

# Ensure all services are running
docker-compose ps

# The DATABASE_URL should use the correct service name
# In docker-compose.yml, it should be: sakura_postgres (not just postgres)

# Check PostgreSQL logs
docker-compose logs postgres

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines first.

📝 License

This project is licensed under the MIT License.

👤 Author

Brijesh Singh

• Email: brijesh7146@gmail.com
• GitHub: @Brijesh1656
• Portfolio: https://brijeshsingh-ai.netlify.app
• LinkedIn: Brijesh Singh

🙏 Acknowledgments

• Built for Sony R&D - AI Application Engineer Position
• Inspired by production needs of animation studios
• Based on state-of-the-art research in diffusion models and style transfer

📮 Contact & Support

For questions, issues, or collaboration:

• Open an issue on GitHub
• Email: brijesh7146@gmail.com

---

⚡ Built with passion for the animation industry | 🌸 SAKURA v1.0