Upload README.md

README.md

@@ -0,0 +1,76 @@
+# LuminaRS — Lightweight Recursive Art Image Generator
+
+A novel ~90M parameter image generation model for art/illustration that runs on mobile devices (2-4GB VRAM).
+
+## Why LuminaRS?
+
+| Problem | Current Solutions | LuminaRS |
+|---------|------------------|----------|
+| Heavy models (6-12GB) | SDXL, Flux | ~90M params, <500MB |
+| Can't run mobile | Quantized SD (quality loss) | Designed small from scratch |
+| Poor prompt adherence | SD 1.5 | TRM-style recursive reasoning |
+| No art specialization | General photo models | Art-focused training stages |
+| Unstable training | Diffusion (score matching) | Flow matching (stable ODE) |
+
+## Architecture (Novel Contributions)
+
+### 1. Recursive Shared-Weight Refinement (from TRM)
+Inspired by [Tiny Recursive Models](https://arxiv.org/abs/2510.04871) — beat 200x larger LLMs with 7M params.
+```python
+for _ in range(T): z = z + unet(z, text, t)  # shared-weight refinement
+```
+Effective depth = T x L without Tx parameters.
+
+### 2. Flow Matching (instead of Diffusion)
+- v(x_t, t) = x_clean - x_noise (straight-line velocity)
+- 10-12 inference steps vs 50+ for diffusion
+- No score matching instability
+
+### 3. ConvNeXt + MQA Cross-Attention
+Depthwise 7x7 conv, Adaptive LayerNorm (time), MQA cross-attn (text), GELU MLP
+
+### 4. Staged Freeze/Thaw Training
+| Stage | What's Trained | LR |
+|-------|---------------|-----|
+| 1 | All denoiser params | 1e-4 |
+| 2 | Cross-attention only | 1e-5 |
+| 3 | All params, joint | 1e-6 |
+
+VAE and CLIP always frozen.
+
+## Parameter Budget
+| Component | Params |
+|-----------|--------|
+| Encoder | ~35M |
+| Bottleneck | ~15M |
+| Decoder | ~35M |
+| Embeds | ~5M |
+| **Total trainable** | **~90M** |
+| VAE (frozen) | ~83M |
+| CLIP (frozen) | ~303M |
+| **Inference VRAM (b=1)** | **~1.5-2GB** |
+
+## Quick Start
+```python
+from luminars.model import LuminaRS
+from luminars.config import LuminaRSConfig
+from luminars.sampler import sample_flow
+cfg = LuminaRSConfig()
+model = LuminaRS(cfg)
+latents = sample_flow(model, text_emb, (1,16,32,32), 12)
+```
+
+## Files
+- luminars/ -- model, config, loss, sampler, train helpers
+- train.py -- main training script
+- LuminaRS_Colab.ipynb -- Colab notebook
+
+## Research Foundations
+- TRM (Jolicoeur-Martineau 2025): Recursive reasoning
+- SnapGen (2024): Mobile UNet design
+- ZigMa (2024): Mamba diffusion
+- Flow Matching (Lipman 2023): Stable ODE generation
+- MQA (Shazeer 2019): Multi-query attention
+- ConvNeXt (Liu 2022): Modernized CNN
+
+MIT License