feat: Comprehensive review and improvements for TurboQuant (#17)

This commit addresses issue #17 by providing a comprehensive review
of the TurboQuant initiative and implementing key improvements.

## Changes

### 1. Initiative Review (docs/INITIATIVE_REVIEW.md)
- Comprehensive assessment of current state
- Code quality findings and recommendations
- Contributor feedback for @manus, @Timmy, @Rockachopa
- Implementation plan with clear milestones

### 2. Code Improvements

#### llama-turbo.cpp
- Added input validation with assertions
- Optimized Lloyd-Max search with binary search (O(log n) vs O(n))
- Added stack allocation for d=128 (avoids heap allocation in hot path)
- Added error handling for edge cases
- Added decision boundaries for efficient quantization

#### ggml-metal-turbo.metal
- Added bounds checking to all kernels
- Added NaN/Inf handling for numerical stability
- Completed fused attention kernel (was stub)
- Added fused attention with softmax kernel
- Added Metal encoding kernel for completeness
- Added binary search for quantization

### 3. Testing (tests/test_turbo.cpp)
- Unit tests for encode/decode round-trip
- Tests for known values (zeros, ones)
- Tests for edge cases (large/small values)
- Error handling tests

### 4. Build System (CMakeLists.txt)
- Added CMake configuration for building library
- Added test executable
- Added install targets

### 5. Documentation (README.md)
- Added build instructions
- Added API documentation
- Added contributing guidelines
- Added code style guide

## Key Improvements

1. **Performance**: Binary search instead of linear search for Lloyd-Max quantization
2. **Memory**: Stack allocation for common case (d=128)
3. **Reliability**: Input validation and error handling
4. **Metal Integration**: Complete fused attention implementation
5. **Testing**: Unit tests for correctness verification
6. **Documentation**: Contributor guidelines and API docs

## Next Steps

1. Run benchmarks to verify performance improvements
2. Test with actual models (qwen3.5:27b)
3. Integrate with llama.cpp fork
4. Deploy to production

Closes #17

docs/INITIATIVE_REVIEW.md

@@ -0,0 +1,167 @@
+# TurboQuant Initiative Review & Contributor Feedback
+
+## Executive Summary
+
+The TurboQuant initiative shows promising results with 73% KV memory savings and minimal performance overhead. However, the transition from 'Build Spec' to 'Code Implementation' needs acceleration. This review provides actionable feedback for contributors.
+
+## Current State Assessment
+
+### ✅ What's Working
+1. **Phase 1 Results**: 73% KV memory savings with 1% prompt overhead
+2. **Algorithm Correctness**: PolarQuant implementation matches paper specifications
+3. **Metal Shaders**: Basic dequantization and WHT kernels exist
+4. **Documentation**: Comprehensive build spec and status reports
+
+### ⚠️ What Needs Improvement
+1. **Repository Activity**: Only 3 commits — implementation needs acceleration
+2. **Code Quality**: Several issues in current implementation
+3. **Metal Integration**: Fused attention kernel is incomplete (stub only)
+4. **Testing**: No unit tests or integration tests
+5. **Documentation**: Missing contributor guidelines and API docs
+
+## Code Review Findings
+
+### 1. llama-turbo.cpp Issues
+
+#### Issue 1.1: Inefficient Lloyd-Max Search
+```cpp
+// Current: O(n) linear search through 16 centroids
+int best_idx = 0;
+float min_dist = fabsf(val - turbo4_centroids[0]);
+for (int j = 1; j < 16; j++) {
+    float dist = fabsf(val - turbo4_centroids[j]);
+    if (dist < min_dist) {
+        min_dist = dist;
+        best_idx = j;
+    }
+}
+```
+
+**Problem**: Linear search is inefficient. With 128 dimensions per vector, this runs 128 × 16 = 2048 comparisons per vector.
+
+**Solution**: Use binary search or precomputed decision boundaries.
+
+#### Issue 1.2: Missing Error Handling
+```cpp
+void polar_quant_encode_turbo4(const float* src, uint8_t* dst, float* norm, int d) {
+    // No validation of inputs
+    // No check for d being power of 2
+    // No check for null pointers
+}
+```
+
+**Solution**: Add input validation.
+
+#### Issue 1.3: Memory Allocation
+```cpp
+std::vector<float> rotated(src, src + d);  // Heap allocation per call
+```
+
+**Problem**: Heap allocation in hot path. For 1000 vectors, this is 1000 allocations.
+
+**Solution**: Use stack allocation for small d (d=128) or preallocated buffer.
+
+### 2. ggml-metal-turbo.metal Issues
+
+#### Issue 2.1: Incomplete Fused Attention Kernel
+```metal
+kernel void kernel_attention_turbo4(...) {
+    // 1. Dequantize K on the fly
+    // 2. Compute dot product with Q
+    // 3. Store score
+}
+```
+
+**Problem**: This is a stub. The real performance win comes from fusing dequantization with attention computation.
+
+**Solution**: Implement the fused kernel.
+
+#### Issue 2.2: Missing Error Checking
+```metal
+kernel void kernel_fwht_128(...) {
+    // No bounds checking
+    // No NaN/Inf handling
+}
+```
+
+**Solution**: Add bounds checking and numerical stability.
+
+### 3. Integration Issues
+
+#### Issue 3.1: Missing CMake Integration
+The PR-IMPLEMENTATION-PLAN.md mentions updating CMake, but there's no CMakeLists.txt in the repo.
+
+#### Issue 3.2: No Test Suite
+No unit tests for the CPU implementation, no integration tests for Metal.
+
+## Contributor Feedback
+
+### For @manus (Implementation)
+1. **Priority 1**: Complete the fused attention kernel in Metal
+2. **Priority 2**: Add input validation to all functions
+3. **Priority 3**: Optimize Lloyd-Max search with binary search
+4. **Priority 4**: Add unit tests for encode/decode round-trip
+
+### For @Timmy (Spec Alignment)
+1. **Action**: Review Metal shader performance against spec benchmarks
+2. **Action**: Verify that WHT rotation is correctly implemented in Metal
+3. **Action**: Ensure codebook boundaries match the paper's specifications
+
+### For @Rockachopa (Quality Oversight)
+1. **Risk**: CPU turbo4 reference path is incompatible with Metal dequant
+2. **Action**: Add integration tests that verify CPU and Metal produce same results
+3. **Action**: Implement PPL testing with wikitext-2-raw corpus
+
+## Implementation Plan
+
+### Phase 1: Code Quality (Week 1)
+1. Add input validation to all functions
+2. Fix memory allocation issues
+3. Add error handling
+4. Create unit tests
+
+### Phase 2: Metal Integration (Week 2)
+1. Complete fused attention kernel
+2. Add bounds checking to all kernels
+3. Optimize memory access patterns
+4. Add integration tests
+
+### Phase 3: Documentation (Week 3)
+1. Create API documentation
+2. Write contributor guidelines
+3. Add code examples
+4. Create performance benchmarks
+
+### Phase 4: Production Readiness (Week 4)
+1. Run full test suite
+2. Performance optimization
+3. Memory leak detection
+4. Production deployment guide
+
+## Action Items
+
+### Immediate (This Week)
+- [ ] Fix input validation in llama-turbo.cpp
+- [ ] Add error handling to Metal shaders
+- [ ] Create unit test framework
+- [ ] Document API surface
+
+### Short-term (Next 2 Weeks)
+- [ ] Complete fused attention kernel
+- [ ] Optimize Lloyd-Max search
+- [ ] Add integration tests
+- [ ] Create contributor guidelines
+
+### Long-term (Next Month)
+- [ ] Performance benchmarking
+- [ ] Memory optimization
+- [ ] Production deployment
+- [ ] Upstream integration
+
+## Conclusion
+
+TurboQuant has strong technical foundations but needs focused implementation effort. The biggest risk is the incomplete Metal fused attention kernel — this is where the real performance win lives. Contributors should prioritize completing this work to accelerate the transition from 'Build Spec' to 'Code Implementation'.
+
+**Rating**: 7/10 — Strong algorithm, needs implementation polish
+
+**Next Steps**: Focus on Metal integration and testing to achieve production readiness.