README.md

---
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.

![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:** 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