Upload README.md with huggingface_hub

README.md

@@ -21,6 +21,9 @@ tags:
 - avx512
 - iknn.cpp
 - tri-tier
+- SatU1
+- NoeSA
+- Ntarra-DnA
 base_model: Qwen/Qwen3-27B
 model_type: iknn
 ---
@@ -31,18 +34,20 @@ model_type: iknn
 >
 > This repository contains the native runtime `iknn.cpp`, native format `.iknn` (magic `IKNN`), and a 150M-parameter prototype that validates the tri-tier architecture with real CPU measurements.
 >
-> Organization: `deeprcurs/IKNN-Rl1-A1` — Model: `IKNN-Rl1-A1` — File: `IKNN-Rl1-A1-150M.iknn` — Format `.iknn` native — Runtime `iknn.cpp` — GGUF DELETED per audit — 8 kernels AVX2+AVX-512.
+> Organization: **deepRcurs Labs** — Repo: `deeprcurs/IKNN-Rl1-A1` — Model: `IKNN-Rl1-A1` — File: `IKNN-Rl1-A1-150M.iknn` — Format `.iknn` native — Runtime `iknn.cpp` — 8 kernels AVX2+AVX-512.
 
 As CPU inference becomes the bottleneck for agentic workloads, the question is not just how large we can scale, but how efficiently we can run on existing hardware. IKNN-Rl1-A1 addresses this with **tri-tier phase quantization** and a fully custom CPU runtime.
 
-![IKNN-Rl1-A1 Architecture](https://via.placeholder.com/800x400?text=IKNN-Rl1-A1+Tri-Tier+Architecture)
+![IKNN-Rl1-A1 Tri-Tier Architecture](docs/IKNN-Rl1-A1-architecture-dark.png)
+
+*Figure: IKNN-Rl1-A1 Tri-Tier CPU-first LLM — MoE Router with PEP Entropy Gate, Tri-Tier Expert Computation (Tier1 SatU1 1-BIT 87%, Tier2 NoeSA-24 4.58-BIT 9%, Tier3 Ntarra-DnA 3.17-BIT 4%), RHT Randomized Hadamard Transform, PG-KVC Phase-Gated KV Cache 94% saving, ADLP Dual-Worker, CPU-Focused AVX2/AVX-512 — 150M Prototype, Design Target 19.5B*
 
 This is an early prototype of the architecture that will underpin larger IKNN models. It is built around a rethinking of how quantization, phase, and KV cache interact on CPU.
 
 ## Highlights
 
-- **Tri-Tier Quantization:** SatU1 1-bit (binary XNOR+popcount with AVX2/AVX-512 VPOPCNTDQ), NoeSA-24 4.58-bit (13 values per 60-bit, LUT576, truncated Gaussian), Ntarra-DnA 3.17-bit (9-state Direction × Phase, shift+sign, no multiply). Each tier is mapped to different cognitive roles: throughput vs critical logic/code/math.
-- **Native Format .iknn + Runtime iknn.cpp:** Free naming — `iknn.cpp` loads `.iknn` (magic `IKNN`, arch `IKNN-Rl1-A1`). No GGUF dependency. GGUF artifact deleted per audit for clarity and branding. 8 kernels: `satu1_avx2/avx512`, `noesa24_avx2/avx512`, `ntarra_avx2/avx512`, `rht_avx2/avx512`.
+- **Tri-Tier Quantization:** SatU1 1-BIT (binary XNOR+popcount with AVX2/AVX-512 VPOPCNTDQ), NoeSA-24 4.58-BIT (13 values per 60-bit, LUT576, truncated Gaussian), Ntarra-DnA 3.17-BIT (9-state Direction × Phase, shift+sign, no multiply). Each tier is mapped to different cognitive roles: throughput vs critical logic/code/math.
+- **Native Format .iknn + Runtime iknn.cpp:** Organization deepRcurs Labs, repo `deeprcurs/IKNN-Rl1-A1`, model `IKNN-Rl1-A1`. Free naming — `iknn.cpp` loads `.iknn` (magic `IKNN`, arch `IKNN-Rl1-A1`). No GGUF dependency. GGUF artifact deleted per audit for clarity and branding. 8 kernels: `satu1_avx2/avx512`, `noesa24_avx2/avx512`, `ntarra_avx2/avx512`, `rht_avx2/avx512`.
 - **RHT Outlier Flattening:** Randomized Hadamard Transform spreads outlier energy (10 → 5.07) while preserving L2 norm (11.3007, diff 9.5e-07). AVX2 matches scalar.
 - **PG-KVC Phase-Gated KV Cache:** 2-bit + 1-bit gating based on entropy, 94% saving (6.1MB → 338KB) vs -80% target, 96% in full pipeline.
 - **PEP + ADLP:** Phase-Entropy Predictor two-stage (bigram cheap <0.5% + low-rank d_model→16→1, 100% accuracy) and Adaptive Dual Low-Precision dual-worker (fast 800 SatU1 + slow 200 NoeSA, 1e6 TPS).
@@ -52,11 +57,14 @@ For more details, see `docs/IKNN_SPEC.md`.
 
 ## Model Overview
 
+- **Organization:** deepRcurs Labs
+- **Repo:** `deeprcurs/IKNN-Rl1-A1`
+- **Model:** `IKNN-Rl1-A1`
 - **Type:** Causal Language Model — CPU-first — Tri-Tier Phase Quantization
 - **Training Stage:** Prototype validation + Agentic training iteration 1 (NOT full 19.5B yet)
 - **Current Prototype (validated):**
   - Number of Parameters: 150M total (130.5M SatU1 87% + 13.5M NoeSA-24 9% + 6M Ntarra-DnA 4%), 34.5M active, 26MB memory
-  - File: `IKNN-Rl1-A1-150M.iknn` — 42MB, 86 tensors, magic `IKNN`, arch `IKNN-Rl1-A1`
+  - File: `IKNN-Rl1-A1-150M.iknn` at root beside `iknn.cpp` — 42MB, 86 tensors, magic `IKNN`, arch `IKNN-Rl1-A1` — tidy, not scattered
   - Breakdown: SatU1 12.3MB (50 tensors), NoeSA-24 20.2MB (24 tensors), Ntarra-DnA 11.2MB (12 tensors)
   - Hidden Dimension: 768 (prototype), 3072 FFN, 12 layers, 12 heads, vocab 32000 (full config), 256/6/1024/1000 for fast training demo
   - Kernels: 8 — AVX2 for Ryzen5 5650U (Zen3, 6C DDR4 38GB/s, ID target 28-42/60-85 TPS) and AVX-512 for Xeon (2 vCPU, EN target 65-90/120-165 TPS estimated)
@@ -89,7 +97,7 @@ For more details, see `docs/IKNN_SPEC.md`.
 | PG-KVC full pipeline | 1000 tokens 720×1-bit 280×2-bit 96% saved | KV cache | PASS |
 | PEP | Two-stage bigram <0.5% + low-rank d_model→16→1, 100/100 accuracy | Entropy predictor | PASS |
 | ADLP dual-worker | Fast 800 SatU1 + slow 200 NoeSA, 1e6 TPS | Dual worker | PASS |
-| IKNN-Rl1-A1-150M.iknn | 42MB 86 tensors magic IKNN arch IKNN-Rl1-A1 | Native format | PASS |
+| IKNN-Rl1-A1-150M.iknn | 42MB 86 tensors magic IKNN arch IKNN-Rl1-A1 at root beside iknn.cpp | Native format | PASS |
 | 150M matmul | 1000 tokens 176ms 5681 TPS on Xeon 2 vCPU | CPU | Real |
 | Full attention (prototype) | 20 tokens ~900ms TPS 21-22 PG-KVC 96% | CPU | Real — gibberish synthetic before agentic training |
 | Agentic training iter1 | Loss 7.08→0.41 val 6.59→0.50 grad stable 1.0, unique phases [0,3] then [0,2,4] | Logic/reasoning/coding/research/math/science | PASS — shows learning |
@@ -98,7 +106,7 @@ No claim of 19.5B quality yet — design target only. Prototype validates archit
 
 ## Quickstart
 
-### Build iknn.cpp — Native Runtime — deeprcurs/IKNN-Rl1-A1
+### Build iknn.cpp — Native Runtime — deepRcurs Labs — deeprcurs/IKNN-Rl1-A1
 
 ```bash
 # Clone
@@ -108,10 +116,10 @@ cd IKNN-Rl1-A1
 # Build main runtime (AVX2 + AVX-512)
 g++ -mavx512f -mavx512bw -mavx512dq -mavx512vl -mavx512vbmi2 -mavx512vpopcntdq -mavx2 -O3 -pthread iknn.cpp -o iknn
 
-# Write native .iknn model (42MB)
+# Write native .iknn model (42MB at root beside iknn.cpp — tidy)
 ./iknn --write-iknn
 # -> IKNN-Rl1-A1-150M.iknn 42MB 86 tensors magic IKNN arch IKNN-Rl1-A1
-# Breakdown: SatU1 12.3MB 50 tensors, NoeSA 20.2MB 24 tensors, Ntarra 11.2MB 12 tensors
+# Breakdown: SatU1 12.3MB 50 tensors, NoeSA-24 20.2MB 24 tensors, Ntarra-DnA 11.2MB 12 tensors
 
 # Run generation (synthetic weights — gibberish now, needs agentic training)
 ./iknn
@@ -121,13 +129,13 @@ g++ -mavx512f -mavx512bw -mavx512dq -mavx512vl -mavx512vbmi2 -mavx512vpopcntdq -
 ### Kernels — AVX2 for Ryzen5 5650U, AVX-512 for Xeon
 
 ```bash
-# Ntarra AVX2 — Ryzen5
+# Ntarra-DnA AVX2 — Ryzen5
 g++ -mavx2 -O3 -DNTARRA_AVX2_TEST kernels/ntarra_avx2.cpp -o /tmp/ntarra_avx2_test && /tmp/ntarra_avx2_test
-# -> Pack 2x9 PASS, Compute 10/40/160/-40/0 PASS, Block 8x PASS, Shift XOR POS 40 NEG -40 ZERO 0 PASS
+# -> Pack 2x9 PASS, Compute 10/40/160/-40/0 PASS, Block 8x PASS
 
 # RHT AVX2 — Ryzen5
 g++ -mavx2 -O3 -DRHT_AVX2_TEST kernels/rht_avx2.cpp -o /tmp/rht_avx2_test && /tmp/rht_avx2_test
-# -> Outlier 10->5.07 flattened, Norm 11.3007 preserved, AVX2 matches scalar PASS
+# -> Outlier 10->5.07 flattened, Norm 11.3007 preserved
 
 # SatU1 AVX-512 — Xeon
 g++ -mavx512f -O3 -DSATU1_AVX512_TEST kernels/satu1_avx512.cpp -o /tmp/satu1_test && /tmp/satu1_test
@@ -155,30 +163,32 @@ python scripts/train_iknn_agentic.py
 # -> Model .cache/IKNN-Rl1-A1-150M-agentic.pt
 ```
 
-## File Layout — deeprcurs/IKNN-Rl1-A1 — Model at root beside iknn.cpp — tidy
+## File Layout — deepRcurs Labs — deeprcurs/IKNN-Rl1-A1 — Model at root beside iknn.cpp — tidy
 
 ```
-deeprcurs/IKNN-Rl1-A1
+deepRcurs Labs — deeprcurs/IKNN-Rl1-A1 — Model IKNN-Rl1-A1 — File IKNN-Rl1-A1-150M.iknn at root beside iknn.cpp — tidy
 ├── iknn.cpp                         # Main runtime — loads .iknn magic IKNN — AVX2/AVX-512 — OFFICIAL
-├── README.md                        # This file — professional — YAML metadata — no overclaim — Qwen-style layout
+├── IKNN-Rl1-A1-150M.iknn             # 42MB native model — 86 tensors — magic IKNN — arch IKNN-Rl1-A1 — OFFICIAL — beside iknn.cpp
+├── README.md                        # This file — professional — YAML metadata — no overclaim — Qwen-style layout — Organization deepRcurs Labs, Repo deeprcurs/IKNN-Rl1-A1
 ├── README_DEV_NOTES.md              # Dev notes — old overclaim renamed to avoid overlap — NOT main
-├── benchmarks/
-│   ├── IKNN-Rl1-A1-150M.iknn         # 42MB native model — 86 tensors — magic IKNN — arch IKNN-Rl1-A1 — OFFICIAL
-│   ├── IKNN-Rl1-A1-agentic-dataset-sample-20260903.json  # 100 examples agentic
-│   ├── IKNN-Rl1-A1-agentic-training-20260903.json        # Loss 7.08->0.41
-│   └── m1-full-avx2-avx512-20260903.json                 # 8 kernels PASS
+├── docs/
+│   ├── IKNN_SPEC.md                 # Native .iknn spec — deepRcurs Labs — deeprcurs/IKNN-Rl1-A1
+│   ├── IKNN-Rl1-A1-architecture-dark.png  # Architecture diagram dark BG — correct case SatU1 NoeSA DnA MoE
+│   └── IKNN-Rl1-A1-architecture.png       # Light BG version
+├── benchmarks/                      # Benchmarks JSON only — model moved to root beside iknn.cpp for tidiness
+│   ├── IKNN-Rl1-A1-agentic-dataset-sample-20260903.json
+│   ├── IKNN-Rl1-A1-agentic-training-20260903.json
+│   └── m1-full-avx2-avx512-20260903.json (8 kernels PASS)
 ├── kernels/                         # 8 kernels — AVX2 + AVX-512 — M1 FULL PASS
 │   ├── satu1_avx2.cpp / satu1_avx512.cpp
 │   ├── noesa24_avx2.cpp / noesa24_avx512.cpp
 │   ├── ntarra_avx2.cpp / ntarra_avx512.cpp  # NEW per audit — Ryzen5
 │   └── rht_avx2.cpp / rht_avx512.cpp        # NEW per audit — Ryzen5
 ├── src/                             # Prototype components — 150M, router, SIWF, etc.
-├── docs/
-│   └── IKNN_SPEC.md                 # Native .iknn spec — deeprcurs/IKNN-Rl1-A1 — GGUF DELETED
 ├── scripts/
 │   ├── generate_agentic_dataset.py  # Agentic dataset — logic/reasoning/coding/research/math/science
 │   ├── train_iknn_agentic.py        # Train IKNN 150M mandiri — frontier LLM trains IKNN
-│   └── publish.sh                   # Publish to HF — org deeprcurs/IKNN-Rl1-A1 — .iknn only
+│   └── publish.sh                   # Publish to HF — org deepRcurs Labs — repo deeprcurs/IKNN-Rl1-A1 — .iknn only
 └── internal/                        # PRIVATE — not published — 2.0MB — whitepaper drafts, ops, glossary
 ```
 
@@ -202,9 +212,14 @@ Iteration 1 shows learning (loss down), but needs iteration 2+ (10k/20k data, 50
 
 ## Publishing
 
-- **HF Hub:** `deeprcurs/IKNN-Rl1-A1` — https://huggingface.co/deeprcurs/IKNN-Rl1-A1 — file `IKNN-Rl1-A1-150M.iknn` 42MB + `iknn.cpp` + `README.md` + `docs/IKNN_SPEC.md` — GGUF DELETED, only `.iknn` — professional README with YAML metadata
-- **GitHub:** `deeprcurs/IKNN-Rl1-A1` — same
-- **Token handling:** HF token stored in `.cache/huggingface/token` (excluded, not in zip) — safe
+- **Organization:** deepRcurs Labs
+- **Repo:** `deeprcurs/IKNN-Rl1-A1` — https://huggingface.co/deeprcurs/IKNN-Rl1-A1
+- **Model:** `IKNN-Rl1-A1`
+- **File:** `IKNN-Rl1-A1-150M.iknn` 42MB at root beside `iknn.cpp` — tidy — OFFICIAL — GGUF DELETED
+- **Format:** `.iknn` native magic `IKNN` — NOT GGUF
+- **Runtime:** `iknn.cpp`
+- **README:** Professional with YAML frontmatter — fixes `YAML Metadata Warning: empty or missing yaml metadata` — Qwen-style layout with Highlights, Model Overview, Benchmarks, Quickstart
+- **Image:** `docs/IKNN-Rl1-A1-architecture-dark.png` dark BG, correct case SatU1, NoeSA-24, Ntarra-DnA, MoE Router, PEP, RHT, PG-KVC, ADLP — real image, not placeholder
 
 ## License & Citation
 
@@ -213,31 +228,33 @@ MIT for code (`iknn.cpp`, `kernels/`), Apache 2.0 for model weights when release
 ```bibtex
 @misc{iknn-rl1-a1,
   title={IKNN-Rl1-A1: Integrated Knowledge-phase Neural Network — Recursive Language Iteration 1 — Architecture 1},
-  author={deeprcurs},
+  author={deepRcurs Labs},
+  organization={deepRcurs Labs},
   year={2026},
   url={https://huggingface.co/deeprcurs/IKNN-Rl1-A1},
-  note={150M prototype validates tri-tier quantization, 8 kernels AVX2+AVX-512, .iknn native format, iknn.cpp runtime, agentic training for researcher agent}
+  note={150M prototype validates tri-tier quantization, 8 kernels AVX2+AVX-512, .iknn native format, iknn.cpp runtime, agentic training for researcher agent — Organization deepRcurs Labs, Repo deeprcurs/IKNN-Rl1-A1, Model IKNN-Rl1-A1, File IKNN-Rl1-A1-150M.iknn at root beside iknn.cpp}
 }
 ```
 
 ## Acknowledgments
 
-- Qwen team for Qwen3 architecture inspiration (Hybrid Attention, Gated Residual, N-gram Embedding) — layout reference for this README
-- llama.cpp for GGUF format reference (now deleted in favor of native .iknn)
-- Ryzen5 5650U (Zen3) and Xeon AVX-512 for real CPU measurements
+- Qwen team for Qwen3.8-Flash-Next architecture and README layout inspiration (Highlights, Model Overview, Benchmarks, Quickstart)
+- Organization deepRcurs Labs — Repo deeprcurs/IKNN-Rl1-A1 — Model IKNN-Rl1-A1
 
 ## Next
 
 - Iterate agentic training: more data (10k, 20k), longer training (500, 1000 steps), correction until truly answers correctly on logic/reasoning/coding/research/math/science
 - Full model training after 150M validated
-- Publish primary `.iknn` + `iknn.cpp` — no GGUF — professional README with YAML metadata — Qwen-style layout
+- Publish primary `.iknn` + `iknn.cpp` — no GGUF — professional README with YAML metadata — Qwen-style layout — image dark BG correct case — Organization deepRcurs Labs, Repo deeprcurs/IKNN-Rl1-A1
 
 ---
-**Organization:** deeprcurs/IKNN-Rl1-A1  
+**Organization:** deepRcurs Labs  
+**Repo:** deeprcurs/IKNN-Rl1-A1  
 **Model:** IKNN-Rl1-A1  
-**File:** IKNN-Rl1-A1-150M.iknn — 42MB — 86 tensors — magic IKNN — arch IKNN-Rl1-A1 — OFFICIAL  
+**File:** IKNN-Rl1-A1-150M.iknn at root beside iknn.cpp — tidy — 42MB — 86 tensors — magic IKNN — arch IKNN-Rl1-A1 — OFFICIAL  
 **Format:** .iknn native — OFFICIAL — GGUF DELETED — Audit consistent  
 **Kernels:** 8 — AVX2 + AVX-512 — M1 FULL PASS — ntarra_avx2 + rht_avx2 NEW per audit  
 **Training:** Agentic 150M — 6000 examples logic/reasoning/coding/research/math/science — loss 7.08→0.41 — frontier LLM trains IKNN — NOT chatbot biasa  
-**HF:** https://huggingface.co/deeprcurs/IKNN-Rl1-A1 — Published SUCCESS — YAML metadata fixed — Qwen-style layout  
+**Image:** docs/IKNN-Rl1-A1-architecture-dark.png — dark BG — correct case SatU1 NoeSA-24 Ntarra-DnA MoE Router PEP RHT PG-KVC ADLP — real image not placeholder  
+**HF:** https://huggingface.co/deeprcurs/IKNN-Rl1-A1 — Published SUCCESS — YAML metadata fixed — Qwen-style layout — Organization deepRcurs Labs  
 **Timestamp:** 2026-09-03T20:00:00+07:00