$ show antirez/iris.c
Iris is a high-performance C inference engine for diffusion image generation models, specifically designed for FLUX.2 Klein (4B/9B) and Z-Image-Turbo (6B) architectures. It provides a complete pipeline from text encoding (Qwen3-4B/8B) through transformer denoising to VAE decoding, outputting PNG or PPM images. The system operates as both a standalone CLI tool with an interactive REPL and a C library (libiris.a), featuring memory-mapped weight loading for efficiency (~4-5GB peak for 4B model) and optional Metal GPU acceleration on Apple Silicon for significant speedups. The architecture is modular: separate components handle safetensors weight loading, BPE tokenization, transformer blocks (double/single stream for Flux, main/refiner for Z-Image), VAE decoding, and image I/O (PNG/JPEG/PPM). The CLI supports text-to-image, image-to-image, multi-reference generation, and various scheduling strategies (shifted sigmoid, linear, power). Memory optimization techniques include releasing the text encoder after embedding extraction, embedding caching with 4-bit quantization, and dynamic attention memory budgeting for reference images. The codebase demonstrates deep systems engineering and ML inference expertise, with hand-optimized kernels, custom Metal shaders, and detailed performance instrumentation. It is self-contained with no external dependencies beyond standard C libraries and optional BLAS/Metal, making it portable across Linux and macOS. The project includes regression test vectors and a JPEG decoder fuzzer, indicating a focus on correctness and reliability.
The LLM identified 5 files worth highlighting for reuse:
Reads model weights from HuggingFace safetensors format using memory-mapped files. Parses JSON header to locate tensors, converts BF16/F16 to F32 on-the-fly. Can be extracted as a standalone tensor loader for any ML model using safetensors, with minimal adaptation for different tensor layouts.
Single-header JPEG decoder supporting baseline and progressive modes, chroma subsampling, and restart markers. Uses AAN integer IDCT for performance. Self-contained and easily embeddable in any C project requiring JPEG decoding without external libraries.
Vendored linenoise library providing UTF-8-aware line editing with history, completion, and mask mode. Used for interactive CLI but can be extracted as a standalone line editing library for any terminal-based C application.
4-bit quantized embedding cache for repeated prompts. Uses block-wise min/max scaling and stores quantized values to reduce memory and compute. Pattern is reusable for caching any high-dimensional vectors with minimal loss, applicable to retrieval or embedding-based systems.
BPE tokenizer that loads a HuggingFace tokenizer.json file and tokenizes text with special tokens and chat templates. Handles byte-level BPE with regex pre-tokenization. Can be reused for other models using the same tokenizer format, providing a lightweight C implementation of tokenization.