| --- |
| license: mit |
| language: |
| - en |
| library_name: custom |
| pipeline_tag: text-generation |
| tags: |
| - cpu |
| - cpu-first |
| - iknn |
| - 1-bit |
| - quantization |
| - agentic |
| - researcher-agent |
| - logic |
| - reasoning |
| - coding |
| - math |
| - science |
| - avx2 |
| - avx512 |
| - iknn.cpp |
| - tri-tier |
| - SatU1 |
| - NoeSA |
| - Ntarra-DnA |
| model_type: iknn |
| --- |
| |
| # IKNN-Rl1-A1 |
|
|
| > **CPU-first language model for agentic and researcher workflows — logic, reasoning, coding, research, mathematics, and science.** |
| > |
| > 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 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. |
|
|
|  |
|
|
| *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:** 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). |
| - **Agentic Researcher Focus:** Dataset V1 6000 examples + V2 10k hard — 2000 each logic, reasoning, coding, research, 1000 math, 1000 science — generated via **Clean Mining** — anonymous frontier synthesis — pointer: CM-V2-20260903-##51pct — see internal/protocol/CLEAN_MINING_PROTOCOL.md for mapping. Training V1 loss 7.08→0.41 val 6.59→0.50, V2 loss 7.01→0.20 val 6.44→0.20 improvement 51% — grad stable 1.0, no explosion. Designed for agentic tasks and researcher agents. Checkpoint `.pt` 21MB saved in `checkpoints/` on HF without affecting workspace snapshot (`.cache/` excluded — no interference). Datasets published to separate repos `deeprcurs/IKNN-Rl1-Dataset-*` variant — IKNN-Rl1-Dataset — no snapshot interference. |
| |
| 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` 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) |
| - Runtime: `iknn.cpp` — AVX2 fallback, AVX-512 fast path, PG-KVC 94% saving |
| - **Design Target (not yet proven, for transparency):** |
| - 19.5B parametric (17B SatU1 + 1.7B NoeSA-24 + 0.8B Ntarra-DnA) + 8B N-Gram non-parametric, ~4.12GB RAM, avg 1.6 bits/param |
| - This target is architectural design from whitepaper v1.0, not yet trained to quality — prototype 150M validates kernels, packing, and runtime only |
| - **Context Length:** 2048 (prototype), extensible |
|
|
| ## Benchmark Results — Real Measurement (150M prototype, 10× smaller) |
|
|
| ### Kernels — M1 FULL PASS — 8 kernels — AVX2 + AVX-512 |
|
|
| | Kernel | Throughput / Result | Target | Status | |
| |---|---|---|---| |
| | SatU1 AVX2 | 16 Giga/s 12c | CPU AVX2 AVX2 | PASS | |
| | SatU1 AVX-512 | 32 Giga/s 4c | Xeon AVX-512 | PASS | |
| | NoeSA-24 AVX2 | Pack 13×24 60-bit | CPU AVX2 | PASS | |
| | NoeSA-24 AVX-512 | Pack 13×24 LUT576 | Xeon AVX-512 | PASS | |
| | Ntarra-DnA AVX2 | Pack 2×9 77, Compute 10/40/160/-40/0, Block 8× 40, Shift XOR POS 40 NEG -40 ZERO 0, Entropy gate | Ryzen5 — NEW per audit | PASS | |
| | Ntarra-DnA AVX-512 | Pack 2×9 77, Compute 10/40/160/-40/0 | Xeon | PASS | |
| | RHT AVX2 | Outlier 10→5.07 flattened, Norm 11.3007 preserved diff 9.5e-07, AVX2 matches scalar diff 0 | Ryzen5 — NEW per audit | PASS | |
| | RHT AVX-512 | Outlier 10→5.07, Norm 11.3007 preserved | Xeon | PASS | |
|
|
| ### Runtime |
|
|
| | Component | Result | Target | Status | |
| |---|---|---|---| |
| | PG-KVC | 1000 tokens 6.1MB → 338KB 94% saved, target -80% | KV cache | PASS | |
| | 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 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 | |
| | Agentic training iter2 V2 10k hard 500 steps | Loss 7.01→0.20 val 6.44→0.20 improvement 51% from V1 0.41, grad 0.40-1.0 stable, phi mean 2.049→2.032 | Logic/reasoning/coding/research/math/science hard — checkpoint 21MB in checkpoints/ | PASS — no problem, training SUCCESS | |
| |
| No claim of 19.5B quality yet — design target only. Prototype validates architecture. |
| |
| ### Checkpoints & Datasets — No Snapshot Interference |
| |
| Checkpoint `.pt` 21MB is stored in `.cache/` which is excluded from workspace snapshot (per PUBLISH_RULE), uploaded directly via HF API to `deeprcurs/IKNN-Rl1-A1` `checkpoints/` folder — snapshot stays 1.8M tidy. |
|
|
| Datasets are stored in `.cache/datasets/` excluded from snapshot, published to separate dataset repos: |
|
|
| - Master V2: `deeprcurs/IKNN-Rl1-Dataset-Agentic-V2` — 8000 train 2000 val 7.6MB+1.9MB hard |
| - Master All: `deeprcurs/IKNN-Rl1-Dataset` |
| - Dataset variant: |
| - `deeprcurs/IKNN-Rl1-Dataset-Logic` — 1589 train + 411 val |
| - `deeprcurs/IKNN-Rl1-Dataset-Reasoning` — 1604 train + 396 val |
| - `deeprcurs/IKNN-Rl1-Dataset-Coding` — 1601 train + 399 val |
| - `deeprcurs/IKNN-Rl1-Dataset-Research` — 1600 train + 400 val |
| - `deeprcurs/IKNN-Rl1-Dataset-Math` — 791 train + 209 val |
| - `deeprcurs/IKNN-Rl1-Dataset-Science` — 815 train + 185 val |
|
|
| . |
|
|
| ## Quickstart |
|
|
| ### Build iknn.cpp — Native Runtime — deepRcurs Labs — deeprcurs/IKNN-Rl1-A1 |
|
|
| ```bash |
| # Clone |
| git clone https://huggingface.co/deeprcurs/IKNN-Rl1-A1 |
| 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 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-24 20.2MB 24 tensors, Ntarra-DnA 11.2MB 12 tensors |
| |
| # Run generation (synthetic weights — gibberish now, needs agentic training) |
| ./iknn |
| # -> [Q] hello world [A] hello world w29234... 20 tokens ~900ms TPS 21-22 PG-KVC 96% saved |
| ``` |
|
|
| ### Kernels — AVX2 for Ryzen5 5650U, AVX-512 for Xeon |
|
|
| ```bash |
| # 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 |
| |
| # 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 |
| |
| # SatU1 AVX-512 — Xeon |
| g++ -mavx512f -O3 -DSATU1_AVX512_TEST kernels/satu1_avx512.cpp -o /tmp/satu1_test && /tmp/satu1_test |
| # -> 32 Giga/s PASS |
| ``` |
|
|
| ### Agentic Dataset + Training — Logic/Reasoning/Coding/Research/Math/Science |
|
|
| ```bash |
| # Setup venv (excluded from snapshot) |
| python3 -m venv .venv && source .venv/bin/activate |
| pip install torch --index-url https://download.pytorch.org/whl/cpu |
| pip install huggingface_hub |
| |
| # Generate agentic dataset V1 — 6000 examples — 1000 each logic/reasoning/coding/research/math/science |
| python scripts/generate_agentic_dataset.py |
| # -> Train 5000 -> .cache/datasets/iknn-agentic-train-5000.json 2.3MB (excluded from snapshot) |
| # -> Val 1000 -> .cache/datasets/iknn-agentic-val-1000.json (excluded) |
| # -> Sample 100 -> benchmarks/IKNN-Rl1-A1-agentic-dataset-sample-20260903.json |
| |
| # Generate V2 — 10k harder — 2000 each logic/reasoning/coding/research + 1000 math/science |
| python scripts/generate_agentic_dataset_v2.py |
| # -> Train 8000 -> .cache/datasets/iknn-agentic-train-8000-v2.json 7.6MB (excluded) |
| # -> Val 2000 -> .cache/datasets/iknn-agentic-val-2000-v2.json 1.9MB (excluded) |
| # -> Sample 100 -> benchmarks/IKNN-Rl1-A1-agentic-dataset-v2-sample-20260903.json |
| |
| # Train IKNN 150M V1 |
| python scripts/train_iknn_agentic.py |
| # -> Steps 100 batch 4 temp 1.0->0.01 2-state {0,3} then 3-state {0,2,4} |
| # -> Loss 7.08->0.41 val 6.59->0.50 grad stable 1.0 PASS |
| # -> Model .cache/IKNN-Rl1-A1-150M-agentic.pt 21MB (excluded) |
| |
| # Train V2 — 500 steps — loss 7.01->0.20 improvement 51% |
| python scripts/train_iknn_agentic_v2.py |
| # -> Steps 500 batch 8 temp 1.0->0.01 |
| # -> Loss 7.01->0.20 val 6.44->0.20 PASS — no problem |
| # -> Model .cache/IKNN-Rl1-A1-150M-agentic-v2.pt 21MB (excluded, uploaded to HF checkpoints/ without snapshot interference) |
| |
| # Publish — checkpoint .pt + datasets to HF — .cache excluded, upload via API |
| # checkpoint to deeprcurs/IKNN-Rl1-A1 checkpoints/ — no snapshot interference |
| # datasets to deeprcurs/IKNN-Rl1-Dataset-* per jenis — IKNN-Rl1-Dataset-(jenis) |
| ``` |
|
|
| ## File Layout — deepRcurs Labs — deeprcurs/IKNN-Rl1-A1 — Model at root beside iknn.cpp — tidy |
|
|
| ``` |
| deepRcurs Labs — deeprcurs/IKNN-Rl1-A1 — Model IKNN-Rl1-A1 — OFFICIAL |
| ├── iknn.cpp # Main runtime — loads .iknn magic IKNN — AVX2/AVX-512 — OFFICIAL |
| ├── IKNN-Rl1-A1-150M.iknn # 42MB native model — 86 tensors — magic IKNN — arch IKNN-Rl1-A1 — OFFICIAL |
| ├── README.md # YAML metadata — no overclaim — Organization deepRcurs Labs, Repo deeprcurs/IKNN-Rl1-A1 |
| ├── README_DEV_NOTES.md # Dev notes — old overclaim renamed to avoid overlap — NOT main |
| ├── docs/ |
| │ ├── IKNN_SPEC.md # Native .iknn spec — deepRcurs Labs — deeprcurs/IKNN-Rl1-A1 |
| │ ├── IKNN-Rl1-A1-architecture-dark.png # Architecture diagram dark BG — |
| │ └── IKNN-Rl1-A1-architecture.png # Light BG version |
| ├── benchmarks/ # Benchmarks JSON only — |
| │ ├── 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. |
| ├── scripts/ |
| │ ├── generate_agentic_dataset.py # Agentic dataset — logic/reasoning/coding/research/math/science |
| │ ├── generate_agentic_dataset_v2.py # Agentic dataset V2 10k hard — Clean Mining — pointer: CM-V2-20260903-##51pct |
| │ ├── train_iknn_agentic.py # Train IKNN 150M — Clean Mining — anonymous — pointer: CM-V2-20260903-##51pct |
| │ ├── train_iknn_agentic_v2.py # Train V2 500 steps — loss 0.20 — Clean Mining |
| │ ├── publish_all_v2.py # One-click publish — checkpoint .pt + dataset per jenis + (check)-## marker — no snapshot interference |
| │ └── publish.sh # Publish to HF — org deepRcurs Labs — repo deeprcurs/IKNN-Rl1-A1 — .iknn only |
| └── internal/ # PRIVATE — not published — 2.0MB — protocols: CLEAN_MINING, COMMENT_SANITIZATION, CHECKPOINT_DATASET_PUBLISH — hard rules |
| ``` |
|
|
| - `internal/` 2.0MB private — NOT published — per publish rule |
| - |
|
|
| ## Agentic Training — Researcher Agent — NOT Ordinary Chatbot |
|
|
| IKNN-Rl1-A1 is for **agentic task and researcher agent** — : |
|
|
| - **Logic:** Syllogism, Boolean, transitivity A⊆B∧B⊆C⇒A⊆C |
| - **Reasoning:** Decompose question, search papers, extract methods, compare, synthesize with citations, validate via experiments — chain-of-thought |
| - **Coding:** Hadamard transform for RHT, SatU1 XNOR+popcount AVX2, NoeSA-24 pack 13×24 60-bit, Ntarra phase rotator, PG-KVC compression — repo deeprcurs/IKNN-Rl1-A1 |
| - **Research:** Summarize SatU1, NoeSA-24, Ntarra-DnA, RHT, PG-KVC — key insights, citations [QuaRot][BitNet], next steps for CPU AVX2 |
| - **Math:** Compute a*b + a<<2 for Ntarra phase, shift 2 = *4 PHI1, steps |
| - **Science:** Why Hadamard preserves L2 norm H^T H = I, ||H x||_2 = ||x||_2, randomized D H, outlier 10→5.07 flattened, norm diff 9.5e-07 PASS |
|
|
| Iteration 1 shows learning (loss down), V2 shows improvement 51% loss 0.20 — needs iteration 3+ (20k data, 1000 steps) until truly answers correctly — **Clean Mining** methodology: anonymous frontier synthesis generates high-quality agentic dataset logic/reasoning/coding/research/math/science for CPU-first validation — pointer: CM-V2-20260903-##51pct — see internal/protocol/CLEAN_MINING_PROTOCOL.md for mapping — public term Clean Mining only per hard rule COMMENT_SANITIZATION_PROTOCOL.md — pointer: CM-V2-20260903-##51pct. |
|
|
| ## Publishing |
|
|
| - **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 — not GGUF |
| - **Format:** `.iknn` native magic `IKNN` |
| - **Runtime:** `iknn.cpp` |
| - **README:** Professional with YAML frontmatter — |
| - **Image:** `docs/IKNN-Rl1-A1-architecture-dark.png` |
|
|
| ## License & Citation |
|
|
| MIT for code (`iknn.cpp`, `kernels/`), Apache 2.0 for model weights when released. |
|
|
| ```bibtex |
| @misc{iknn-rl1-a1, |
| title={IKNN-Rl1-A1: Integrated Knowledge-phase Neural Network — Recursive Language Iteration 1 — Architecture 1}, |
| author={Mzed Imamkh}, |
| 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 — Organization deepRcurs Labs, Repo deeprcurs/IKNN-Rl1-A1, Model IKNN-Rl1-A1, File IKNN-Rl1-A1-150M.iknn at root beside iknn.cpp} |
| } |
| ``` |
|
|
| ## Acknowledgments |
|
|
| - 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`. |
|
|
| --- |
| **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 |
| **Format:** .iknn native — OFFICIAL |
| **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 — LLM trains IKNN |
| **Image:** docs/IKNN-Rl1-A1-architecture-dark.png — dark BG |
| **HF:** https://huggingface.co/deeprcurs/IKNN-Rl1-A1 |
| **Timestamp:** 2026-09-03T20:00:00+07:00 |
|
|
