README: rewrite around TurboQuant paper algorithm as core identity

- Lead with the core idea: MSE bias in inner products, two-stage fix
- Results table: TurboQuant KV 3-bit vs uniform 4-bit (3.4x faster, same quality)
- Algorithm explanation: RHT → Lloyd-Max → QJL residual
- Pipeline diagram showing rotated-space attention
- Updated stats: 10K+ lines, 21 test suites, 10 quant types
- Both EN and KO versions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: unamedkr

README.ko.md

@@ -1,234 +1,140 @@
 # TurboQuant.cpp
 
-![TurboQuant Hero](docs/assets/hero.png)
+**[TurboQuant](https://arxiv.org/abs/2504.19874) (ICLR 2026) 논문을 충실히 구현한 순수 C 추론 엔진.**
 
-**멀티 아키텍처 LLM 추론 엔진. 순수 C. 외부 의존성 없음.**
+3비트 KV 캐시. 품질 손실 제로. FP16보다 빠름.
 
-Qwen3.5 + Gemma 3 지원. Gemma 4 대응 준비 완료.
-
-[![Build](https://img.shields.io/badge/build-passing-brightgreen)]()
-[![Tests](https://img.shields.io/badge/tests-70%2B%20pass-brightgreen)]()
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)]()
-[![Qwen3.5](https://img.shields.io/badge/Qwen3.5--0.8B-82%20tok%2Fs-blue)]()
-[![Gemma3-4B](https://img.shields.io/badge/Gemma3--4B-5.2%20tok%2Fs-blue)]()
-[![Gemma3-270M](https://img.shields.io/badge/Gemma3--270M-176%20tok%2Fs-blue)]()
-
-### 지원 모델
-
-| 모델 | 파라미터 | 속도 (Q4, 6T) | 검증 |
-|------|----------|---------------|------|
-| **Gemma 3 4B** | 4B | 5.2 tok/s | "프랑스 수도" → "Paris" |
-| **Qwen3.5-0.8B** | 752M | 82 tok/s | PyTorch 대비 코사인 0.999 |
-| **Gemma 3 270M** | 270M | 176 tok/s | PyTorch 대비 레이어별 일치 |
-
-### KV 캐시 메모리: 진짜 차별점
-
-![Long Context Memory](docs/assets/long_context_memory.png)
-
-```
-Gemma 3 4B, 32K 컨텍스트:
-  llama.cpp (FP16 KV):    4,352 MB
-  TurboQuant (Q4 KV):     1,156 MB  ← 3.8배 작음, 3.2 GB 절약
-```
-
-128K 토큰에서 llama.cpp는 KV 캐시만 17 GB 필요. TurboQuant는 4.6 GB.
-
-### llama.cpp vs TurboQuant — Q4 공정 벤치마크
-
-```
-Qwen3.5-0.8B, Q4_0, CPU 전용, Apple Silicon M-series
-─────────────────────────────────────────────────────
-스레드 │ llama.cpp  │ TurboQuant │
-───────┼────────────┼────────────┤
-   1   │  50.7 t/s  │  51.1 t/s  │ ← 동등
-   2   │  80.6 t/s  │  75.4 t/s  │
-   4   │  90.0 t/s  │  71.6 t/s  │
-   6   │     —      │  81.8 t/s  │ ← 최대
-```
-
-동일 모델, 동일 양자화, 동일 하드웨어. 공정 비교.
+[![Release](https://img.shields.io/github/v/release/quantumaikr/TurboQuant.cpp)]()
+[![Tests](https://img.shields.io/badge/tests-21%20suites-brightgreen)]()
 
 ---
 
-## 빠른 시작
+## 핵심 아이디어
 
-```bash
-git clone https://github.com/quantumaikr/TurboQuant.cpp && cd TurboQuant.cpp
-bash scripts/quickstart.sh "What is deep learning?"
-```
+LLM attention은 **내적(inner product)** `<query, key>`를 계산합니다. 일반 양자화기는 복원 오차(MSE)를 최소화하지만, 이것은 **내적 추정에 편향(bias)을 만듭니다** — attention 점수가 체계적으로 왜곡됩니다.
 
-이것만으로 끝입니다. 스크립트가 엔진 빌드, [Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) 다운로드 (~1.5 GB), TQM 변환, 추론까지 자동 수행합니다.
+TurboQuant는 [ICLR 2026 논문](https://arxiv.org/abs/2504.19874)의 2단계 접근으로 이를 해결합니다:
 
-<details>
-<summary>수동 설정 (단계별 진행 시)</summary>
-
-```bash
-cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j$(nproc)
-pip3 install huggingface_hub && python3 -c "from huggingface_hub import snapshot_download; snapshot_download('Qwen/Qwen3.5-0.8B')"
-./build/tq_convert -o model.tqm
-./build/tq_run model.tqm -p "What is deep learning?" -j 4
 ```
-</details>
+Key → 정규화 → Random Hadamard Transform
+    → Lloyd-Max 코드북 (b-1 bits)        ← MSE 최적, 하지만 내적에 편향
+    → QJL 부호 해시 on 잔차 (1 bit)       ← 편향 교정, 비편향 추정기
+    → 저장: [인덱스, 부호, 노름]
 
+Attention:
+    query → RHT (1회) → 회전 공간에서 내적 (역변환 불필요)
+                      → 사전 계산된 QJL 투영으로 보정
 ```
-Prompt: What is deep learning?
----
-Deep learning is a field of artificial intelligence and machine learning
-that uses artificial neural networks to learn complex patterns...
----
-100 tokens in 1.2s (81.8 tok/s, 6 threads, weights=Q4, kv=uniform_4b)
-```
-
----
 
-## 왜 TurboQuant인가?
-
-|  | llama.cpp (Q4) | TurboQuant.cpp (Q4) |
-|---|---|---|
-| **속도 (1T)** | 50.7 tok/s | **51.1 tok/s** |
-| **로딩** | ~1초 | **0.3초** (mmap) |
-| **KV 캐시** | 전체 크기 | **7.5배 압축** |
-| **의존성** | cmake, ggml | **없음** (libc only) |
-| **품질** | 기준 | **코사인 0.999** (PyTorch F32 대비) |
-| **차별점** | 광범위한 모델 지원 | **KV 캐시 압축** |
+결과: **3비트 KV로 품질 저하 없이, 4비트 uniform보다 빠른 attention.**
 
 ---
 
-## 구성 요소
+## 결과
 
-```
-┌─────────────────────────────────────────────────────┐
-│  tq_convert                                          │
-│    safetensors → TQM (사전 양자화, mmap 가능)         │
-├─────────────────────────────────────────────────────┤
-│  tq_run                                              │
-│    TQM → mmap 로드 → forward → 토큰 스트리밍         │
-│                                                      │
-│    ┌─── Forward Pass ────────────────────────────┐  │
-│    │  DeltaNet (18 레이어, 순환)                  │  │
-│    │  Self-Attention (6 레이어, GQA + RoPE)      │  │
-│    │  SwiGLU FFN (전체 24 레이어)                 │  │
-│    │  KV 캐시: TurboQuant Q4 양자화              │  │
-│    │  Attention: 정수 Q4×Q8 (FP32 대비 2.9배)    │  │
-│    └─────────────────────────────────────────────┘  │
-│                                                      │
-│    Q4 가중치 ── NEON matmul ── 멀티스레드            │
-└─────────────────────────────────────────────────────┘
-```
+### 속도: TurboQuant KV vs Uniform KV
 
-### 5가지 최적화
+| 모델 | Uniform 4비트 | TurboQuant 3비트 | 가속 | 품질 |
+|------|-------------|----------------|------|------|
+| **Gemma 3 4B** | 5.1 tok/s | **17.6 tok/s** | **3.4x** | 동일 |
+| **Qwen3.5-0.8B** | 49.5 tok/s | **80.1 tok/s** | **1.6x** | 동일 |
 
-| # | 기법 | 효과 |
-|---|------|------|
-| 1 | **Q4 가중치** — 4-bit, 8배 작음 | 2배 빠름 |
-| 2 | **TQM 포맷** — 사전 양자화 mmap | 10배 빠른 로딩 |
-| 3 | **정수 attention** — Q4×Q8, ARM vdotq_s32 | 2.9배 빠름 |
-| 4 | **스레드 풀** — 제로 오버헤드 디스패치, NEON 2-row 배치 | 1.6배 빠름 |
-| 5 | **lm_head Q4** — 출력 프로젝션 로딩 시 양자화 | 로짓 2배 빠름 |
+더 적은 비트 = 더 적은 데이터 = 더 나은 캐시 효율. 회전 공간 내적으로 역변환 제거.
 
-### 실제 모델 검증
+### KV 캐시 메모리
 
-[Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) — 실제 추론, 합성 아님:
+![Long Context Memory](docs/assets/long_context_memory.png)
 
 ```
-"1+1="                      → "2"                    ✓
-"The capital of France is"  → "Paris"                ✓
-"What is deep learning?"    → 정확한 문단             ✓
-PyTorch 대비 logits 코사인  → 0.999                  ✓
+Gemma 3 4B, 32K 컨텍스트:
+  FP16 (llama.cpp):       4,352 MB
+  Uniform Q4:             1,156 MB   (3.8x)
+  TurboQuant 3비트:          900 MB   (4.6x)  ← 같은 품질, 22% 적은 메모리
 ```
 
----
+### 지원 모델
 
-## 스레드별 속도
+| 모델 | 파라미터 | 속도 (Q4, 6T) | 검증 |
+|------|----------|---------------|------|
+| **Gemma 3 4B** | 4B | 17.6 tok/s | "France" → "Paris" |
+| **Qwen3.5-0.8B** | 752M | 80.1 tok/s | PyTorch 대비 코사인 0.999 |
+| **Gemma 3 270M** | 270M | 176 tok/s | 레이어별 정확 일치 |
 
-```
-Qwen3.5-0.8B Q4, 100 토큰, CPU 전용
-──────    ──────────   ──────────────
-스레드    속도          vs llama.cpp
-──────    ──────────   ──────────────
-1         51.1 tok/s   1.01x ✓
-2         75.4 tok/s   0.94x
-4         71.6 tok/s   0.80x
-6         81.8 tok/s   최대
-8         77.5 tok/s
-```
+멀티 아키텍처: Qwen3.5 (DeltaNet 하이브리드) + Gemma 3 (슬라이딩 윈도우). Gemma 4 대응.
 
 ---
 
-## CLI
+## 빠른 시작
 
 ```bash
-# 변환 (1회)
-./build/tq_convert                     # 자동 감지
-
-# 추론
-./build/tq_run model.tqm -p "Hello"    # 토크나이저 내장
-./build/tq_run model.tqm -p "Hello" -j 4 -n 200 -T 0.7
-
-# Python CLI
-python3 tools/tq info                  # 양자화 타입
-python3 tools/tq +memory llama-3.2-3b 65536
-python3 tools/tq_chat.py "What is AI?" # 네이티브 엔진 + KV 분석
+git clone https://github.com/quantumaikr/TurboQuant.cpp && cd TurboQuant.cpp
+bash scripts/quickstart.sh "What is deep learning?"
 ```
 
-### Python API
+### KV 캐시 옵션
 
-```python
-from turboquant import TurboQuant
-tq = TurboQuant("cpu")
-compressed = tq.quantize_keys(keys, TurboQuant.UNIFORM_4B)  # 7.5배 압축
-scores = tq.attention(query, compressed, seq_len, dim, TurboQuant.UNIFORM_4B)
+```bash
+./build/tq_run model.tqm -p "Hello" -k turbo_kv_3b   # 3비트 TurboQuant (권장)
+./build/tq_run model.tqm -p "Hello" -k turbo_kv_4b   # 4비트 TurboQuant
+./build/tq_run model.tqm -p "Hello" -k uniform_4b     # 4비트 uniform (베이스라인)
+./build/tq_run model.tqm -p "Hello" -M                 # KV 메모리 통계 표시
 ```
 
 ---
 
-## 문서
+## 작동 원리
+
+### 알고리즘 (논문 기반)
+
+| 단계 | 내용 | 이유 |
+|------|------|------|
+| **Random Hadamard Transform** | 입력을 회전하여 채널 상관 제거 | 회전 후 좌표가 가우시안 근사 → 단순 스칼라 양자화 가능 |
+| **Lloyd-Max 코드북** | 각 회전 좌표를 독립적으로 양자화 | 가우시안 분포에 대한 사전 계산 최적 중심점, 거의 최적 MSE |
+| **QJL 잔차** | 양자화 잔차의 1비트 부호 해시 | 내적 추정을 **비편향**으로 만듦 — attention 정확도의 핵심 |
 
-| 문서 | 내용 |
-|------|------|
-| **[시작 가이드](docs/getting-started.md)** | 빌드, 변환, 실행, 통합 |
-| [아키텍처](docs/architecture.md) | 엔진 설계, 4-layer 스택 |
-| [Qwen3.5 결과](docs/qwen35_validation_results.md) | 실제 모델 A/B 테스트 |
-| [변경 이력](CHANGELOG.md) | 전체 버전 히스토리 |
-| [통합 가이드](docs/integration_guide.md) | llama.cpp, vLLM, Python |
+MSE 최적 양자화기만으로는 내적에 2/pi ≈ 0.64의 곱셈 편향이 발생합니다. QJL 잔차 보정이 이 편향을 완전히 제거합니다.
 
 ---
 
 ## 기술 상세
 
-- **멀티 아키텍처** — Qwen3.5 (DeltaNet 하이브리드) + Gemma 3 (슬라이딩 윈도우), Gemma 4 대응
-- **9,000줄 이상의 C** — 완전한 추론 엔진, 래퍼 아님
-- **8개 양자화 타입** — Uniform, Mixed Precision, PolarQuant, QJL, TurboQuant
-- **TQM 포맷** — 사전 양자화 바이너리, mmap 즉시 로딩
+- **10,000줄 이상의 C** — 완전한 추론 엔진, 래퍼 아님
+- **10개 양자화 타입** — Uniform, Mixed, PolarQuant, QJL, TurboQuant, TurboQuant KV
+- **논문 충실 구현** — RHT + Lloyd-Max 코드북 + QJL 잔차 (arXiv 2504.19874)
+- **멀티 아키텍처** — Qwen3.5 (DeltaNet) + Gemma 3 (슬라이딩 윈도우), Gemma 4 대응
+- **멀티 샤드 safetensors** — 분할 모델 로딩 (Gemma 4B = 2 샤드)
 - **듀얼 토크나이저** — GPT2 바이트 BPE + SentencePiece 자동 감지
-- **Q4×Q8 정수 attention** — ARM vdotq_s32, float 역양자화 없음
-- **스레드 풀** — 제로 오버헤드 디스패치 + NEON 2-row 배치
-- **20 테스트 스위트, 70+ 테스트** — ASan + UBSan + TSan 클린
+- **TQM 포맷** — 사전 양자화 바이너리, mmap 즉시 로딩
+- **NEON 벡터화** — 2-row matmul 배치, fused attention, 스레드 풀
+- **21개 테스트 스위트** — TurboQuant KV 라운드트립, attention 정확도, 코드북 검증 포함
 
 ---
 
 ## 여정
 
 ```
 1일차 오전:   빈 디렉토리
-1일차 오후:   KV 캐시 압축 라이브러리 (8개 타입, A/B 테스트)
-1일차 저녁:   완전한 추론 엔진 (모델 로드 → 텍스트 생성)
-1일차 밤:    82 tok/s, llama.cpp 단일 스레드 동등
-2일차:       Gemma 3 지원, 멀티 아키텍처 엔진
-
-C 코드:       9,000줄 이상
-테스트:       20개 스위트 (70+ 테스트)
-아키텍처:     Qwen3.5 + Gemma 3 (Gemma 4 대응)
-속도:         82 tok/s (Qwen3.5), 176 tok/s (Gemma3)
+1일차 오후:   KV 캐시 압축 라이브러리 (10개 타입)
+1일차 저녁:   완전한 추론 엔진 (Qwen3.5)
+1일차 밤:    82 tok/s, llama.cpp 동등
+2일차 오전:   Gemma 3 지원 (270M + 4B)
+2일차 오후:   TurboQuant 논문 알고리즘 구현
+2일차 저녁:   3비트 KV, 품질 손실 제로, uniform 대비 3.4배 빠름
+
+C 코드:       10,000줄 이상
+테스트:       21개 스위트
+모델:         Gemma 3 4B, Qwen3.5-0.8B, Gemma 3 270M
+KV 압축:      4.6x (3비트 TurboQuant, 품질 중립)
 ```
 
 ---
 
 ## 참고 논문
 
-- [TurboQuant](https://arxiv.org/abs/2504.19874) (ICLR 2026) — KV 캐시 압축
-- [QJL](https://arxiv.org/abs/2406.03482) (AAAI 2025) — 1비트 양자화 JL 변환
-- [PolarQuant](https://arxiv.org/abs/2502.02617) (AISTATS 2026) — 극좌표 양자화
+- **[TurboQuant](https://arxiv.org/abs/2504.19874)** (ICLR 2026) — 근최적 왜곡률의 온라인 벡터 양자화
+- [QJL](https://arxiv.org/abs/2406.03482) (AAAI 2025) — KV 캐시를 위한 1비트 양자화 JL 변환
+- [PolarQuant](https://arxiv.org/abs/2502.02617) (AISTATS 2026) — 극좌표 KV 양자화
 
 아키텍처: [llama.cpp](https://github.com/ggerganov/llama.cpp), [vLLM](https://github.com/vllm-project/vllm), [ONNX](https://github.com/onnx/onnx) 참조.