Update README.md

README.md

@@ -1,33 +1,163 @@
 ---
 license: apache-2.0
-pipeline_tag: text-to-image
+language:
+- en
 library_name: diffusers
+pipeline_tag: text-to-image
+tags:
+- moe
+- sparse-moe
+- diffusion
+- text-to-image
+- image-generation
 ---
 
-![NucleusMoE-Image](demo.png)
+<p align="center">
+    <img src="assets/logo/OpsAI_Logo.png" width="200"/>
+</p>
+<p align="center">
+    <a href="https://github.com/WithNucleusAI/Nucleus-Image"><b>GitHub</b></a>&nbsp;&nbsp; | &nbsp;&nbsp;<a href="https://huggingface.co/NucleusAI/NucleusMoE-Image">Hugging Face</a>&nbsp;&nbsp; | &nbsp;&nbsp;<a href="">Tech Report</a>
+</p>
+
+<p align="center">
+    <img src="assets/collage/Collage-1-Top.jpeg" width="1600"/>
+    <img src="assets/collage/Collage-1-Bottom.jpeg" width="1600"/>
+</p>
+
+## Introduction
+
+**Nucleus-Image** is a text-to-image generation model built on a sparse mixture-of-experts (MoE) diffusion transformer architecture. It scales to **17B total parameters** across 64 routed experts per layer while activating only **~2B parameters** per forward pass, establishing a new Pareto frontier in quality-versus-efficiency. Nucleus-Image matches or exceeds leading models — including Qwen-Image, GPT Image 1, Seedream 3.0, and Imagen4 — on GenEval, DPG-Bench, and OneIG-Bench. This is a **base model** released without any post-training optimization (no DPO, no reinforcement learning, no human preference tuning) — all reported results reflect pre-training performance only. We release the full model weights, training code, and dataset, making Nucleus-Image the first fully open-source MoE diffusion model at this quality tier.
+
+## Key Features
+
+- **Sparse MoE efficiency**: 17B total capacity with only ~2B active parameters per forward pass, enabling high-quality generation at a fraction of the inference cost of dense models
+- **Expert-Choice Routing**: Guarantees balanced expert utilization without auxiliary load-balancing losses, with a decoupled routing design that separates timestep-aware assignment from timestep-conditioned computation
+- **Base model, no post-training**: This is a base model — all benchmark results are from pre-training alone, without DPO, reinforcement learning, or human preference tuning
+- **Multi-aspect-ratio support**: Trained with aspect-ratio bucketing from the outset at every resolution stage, supporting a range of output dimensions
+- **Text KV caching via diffusers**: Text tokens are excluded from the transformer backbone entirely and their KV projections are cached across all denoising steps. This caching is natively integrated into the `diffusers` pipeline — simply enable it with `TextKVCacheConfig` for automatic speedup with no code changes to the inference loop
+- **Progressive resolution training**: Three-stage curriculum (256 → 512 → 1024) with progressive sparsification of expert capacity
+
+## Model Specifications
+
+| Specification | Value |
+|---|---|
+| Total parameters | 17B |
+| Active parameters | ~2B |
+| Architecture | Sparse MoE Diffusion Transformer |
+| Layers | 32 |
+| Hidden dimension | 2048 |
+| Attention heads (Q / KV) | 16 / 4 (GQA) |
+| Experts per MoE layer | 64 routed + 1 shared |
+| Expert hidden dimension | 1344 |
+| Text encoder | Qwen3-VL-8B-Instruct |
+| Image tokenizer | Qwen-Image VAE (16ch) |
+| Training data | 700M images, 1.5B caption pairs |
+| Training curriculum | Progressive resolution (256 → 512 → 1024) |
+| Total training steps | 1.7M |
 
-NucleusMoE-Image is a 17B flow-based text-to-image generation MoE model with only 2B active parameters. Technical report coming soon...
+## Benchmark Results
 
-## Usage
+![Overall Performance](assets/Overall-Performance.png)
+
+Nucleus-Image achieves state-of-the-art or near state-of-the-art results on all three benchmarks despite activating only ~2B of its 17B parameters per forward pass. All results are from the base model at 1024x1024, 50 inference steps, CFG scale 8.0.
+
+| Benchmark | Score | Highlights |
+|---|---|---|
+| **GenEval** | **0.87** | Matches Qwen-Image; leads all models on spatial position (0.85) |
+| **DPG-Bench** | **88.79** | #1 overall; leads in entity (93.08), attribute (92.20), and other (93.62) |
+| **OneIG-Bench** | **0.522** | Surpasses Imagen4 (0.515) and Recraft V3 (0.502); strong style (0.430) |
+
+## Quick Start
+
+Install the latest version of diffusers:
+```
+pip install git+https://github.com/huggingface/diffusers
+```
+
+Generate images with Nucleus-Image:
 
 ```python
 import torch
 from diffusers import DiffusionPipeline
+from diffusers import TextKVCacheConfig
+
+model_name = "NucleusAI/NucleusMoE-Image"
 
-pipe = DiffusionPipeline.from_pretrained("NucleusAI/NucleusMoE-Image", torch_dtype=torch.bfloat16)
+pipe = DiffusionPipeline.from_pretrained(model_name, torch_dtype=torch.bfloat16)
 pipe.to("cuda")
 
+# Enable Text KV caching across denoising steps (integrated into diffusers)
 config = TextKVCacheConfig()
 pipe.transformer.enable_cache(config)
 
-prompt = "Vintage-style poster for Artificial Analysis depicting a retro-futuristic cityscape dominated by AI. Towering structures shaped like neural networks loom over sleek flying cars. In the foreground, a stylized robot extends a hand towards the viewer. Bold, sans-serif typography at the top reads 'Welcome to the AI Revolution' with 'Artificial Analysis' prominently displayed at the bottom in a retro chrome effect. The color palette consists of deep blues, vibrant oranges, and metallic silvers, reminiscent of 1950s sci-fi illustrations."
+# Supported aspect ratios
+aspect_ratios = {
+    "1:1": (1024, 1024),
+    "16:9": (1344, 768),
+    "9:16": (768, 1344),
+    "4:3": (1184, 896),
+    "3:4": (896, 1184),
+    "3:2": (1248, 832),
+    "2:3": (832, 1248),
+}
+
+prompt = "A weathered lighthouse on a rocky coastline at golden hour, waves crashing against the rocks below, seagulls circling overhead, dramatic clouds painted in shades of amber and violet"
+width, height = aspect_ratios["16:9"]
+
 image = pipe(
-    prompt,
-    height=1024,
-    width=1024,
-    guidance_scale=4.0,
+    prompt=prompt,
+    width=width,
+    height=height,
     num_inference_steps=50,
+    guidance_scale=8.0,
+    generator=torch.Generator(device="cuda").manual_seed(42),
 ).images[0]
-image.save("nucleus_image_demo.png")
+
+image.save("nucleus_output.png")
 ```
 
+## Show Cases
+
+### Portraits & People
+
+Nucleus-Image generations of human subjects and portraits, spanning diverse cultures, ages, and artistic styles — from expressive character studies to fine-grained close-ups with intricate skin texture and detail.
+
+<p align="center">
+    <img src="assets/collage/Collage-1-Top.jpeg" width="1600"/>
+    <img src="assets/collage/Collage-1-Bottom.jpeg" width="1600"/>
+</p>
+
+### Fantasy, Surrealism & Nature
+
+Nucleus-Image generations spanning fantasy, surrealism, animation, and the natural world.
+
+<p align="center">
+    <img src="assets/collage/Collage-2-Top.jpeg" width="1600"/>
+    <img src="assets/collage/Collage-2-Bottom.jpeg" width="1600"/>
+</p>
+
+### Commercial & Everyday Imagery
+
+Nucleus-Image generations across product photography, architecture, typography, food, and world culture — demonstrating versatility in commercial, conceptual, and everyday imagery.
+
+<p align="center">
+    <img src="assets/collage/Collage-3-Top.jpeg" width="1600"/>
+    <img src="assets/collage/Collage-3-Bottom.jpeg" width="1600"/>
+</p>
+
+## License
+
+Nucleus-Image is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+## Citation
+
+```bibtex
+@misc{nucleusimage2026,
+      title={Nucleus-Image: Sparse MoE for Image Generation},
+      author={Nucleus AI Team},
+      year={2026},
+      eprint={XXXX.XXXXX},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+}
+```