Update README.md

README.md

@@ -1,29 +1,81 @@
 ---
-library_name: transformers
+license: apache-2.0
 tags:
-- lora
-- fine-tuning
-- peft
-- adaptive
-- research
+  - lora
+  - fine-tuning
+  - adaptive
+  - research
+  - nested-lora
+  - rank-adaptation
+library_name: transformers
 datasets:
-- glue
-metrics:
-- accuracy
-- f1
+  - nyu-mll/glue
+pipeline_tag: text-classification
 ---
 
 # Unified-LoRA
 
-## ⚠️ Important
+**Adaptive rank controller for LoRA fine-tuning via nested orbital slicing.**
+
+⚠️ **This is NOT a pretrained model.** Unified-LoRA is a training method/controller for LoRA.
+
+👉 **Code**: [github.com/Sva76/Unified-LoRa](https://github.com/Sva76/Unified-LoRa)
+👉 **Demo**: [unified_lora_demo.ipynb](https://github.com/Sva76/Unified-LoRa/blob/main/notebooks/unified_lora_demo.ipynb)
+
+## What It Does
+
+Instead of fixing `rank=8` and hoping it works, Unified-LoRA allocates a single LoRA matrix pair at max rank and controls active capacity via **matrix slicing** (r4 ⊂ r8 ⊂ r16). An OrbitalController monitors gradient stress per layer and promotes/demotes rank using adaptive thresholds (μ ± kσ).
+
+**Key properties:**
+- Zero cold-start on rank transitions (lower ranks are subsets of higher ranks)
+- Per-layer independence (each adapter finds its own optimal rank)
+- ~100 lines of code, no SVD, negligible overhead
+
+## Results
+
+**GLUE (DistilBERT, 67M):** Comparable or better on 3/4 tasks with 33–56% rank reduction.
+
+| Task | Baseline (r=16) | Adaptive | Rank Reduction |
+|------|-----------------|----------|----------------|
+| MRPC | 0.882 F1        | **0.886**| 42%            |
+| CoLA | 0.488 MCC       | **0.491**| 56%            |
+| RTE  | 0.556 Acc       | **0.592**| 33%            |
+
+**Noise resilience (validated use case):** +31 F1 points at 50% label noise, 9× lower variance vs fixed rank. No benefit on clean data. Pattern confirmed at 67M, 1.1B, and 3B scales.
+
+**NestedLoRA stress tests:** Performance parity with baseline, ~15% rank saving, zero cold-start degradation.
+
+## Quick Start
+
+```python
+from controller import setup_unified_lora
+
+adapters, ctrl = setup_unified_lora(
+    model,
+    target_modules=["q_proj", "v_proj"],
+    max_rank=16,
+    rank_levels=[4, 8, 16],
+)
 
-This is NOT a pretrained model.
+for batch in dataloader:
+    loss = model(**batch).loss
+    loss.backward()
+    ctrl.step()
+    optimizer.step()
+    optimizer.zero_grad()
+```
 
-Unified-LoRA is a training method / controller for LoRA.
+## Citation
 
-👉 Use the GitHub repo:
-https://github.com/Sva76/Unified-LoRa
+```bibtex
+@software{unified_lora_2025,
+  author = {Simona Vargiu},
+  title = {Unified-LoRA: Adaptive Rank Controller via Nested Orbital Slicing},
+  year = {2025},
+  url = {https://github.com/Sva76/Unified-LoRa}
+}
+```
 
-Adaptive LoRA fine-tuning with dynamic rank control.
+## Contact
 
-👉 Demo: https://github.com/Sva76/Unified-LoRa/blob/main/notebooks/unified_lora_demo.ipynb
+Simona Vargiu (Independent Researcher) — simona.vargiu.malta@gmail.com