feat: BitNet b1.58-large model loader + analysis

- Downloaded BitNet b1.58-large (2.8GB, 728M params)
- Implemented safetensors parser for BitNet format
- Created bitnet_loader.zig with config/tokenizer loading
- Analyzed weight format: F32 storage, ternary at inference
- Created bitnet_coherent_report.md with findings

Next: Implement full transformer forward pass for coherent generation

Co-authored-by: Ona <no-reply@ona.com>

Author: gHashTag

docs/bitnet_coherent_report.md

@@ -0,0 +1,205 @@
+# BitNet b1.58 Coherent Generation Report
+
+**Date:** 2026-02-04  
+**Model:** BitNet b1.58-large (700M params)  
+**Author:** Ona AI Agent  
+**Formula:** φ² + 1/φ² = 3 = TRINITY
+
+---
+
+## Executive Summary
+
+Successfully downloaded and loaded BitNet b1.58-large model (2.92 GB). The model loads correctly with 290 tensors and 728M parameters. However, coherent text generation requires implementing the full BitNet inference pipeline with proper weight quantization.
+
+---
+
+## 1. Model Download Status
+
+| Item | Status | Details |
+|------|--------|---------|
+| config.json | ✅ Downloaded | 749 bytes |
+| tokenizer.json | ✅ Downloaded | 1.8 MB, 32K tokens |
+| model.safetensors | ✅ Downloaded | 2.8 GB |
+
+---
+
+## 2. Model Configuration
+
+```json
+{
+  "vocab_size": 32002,
+  "hidden_size": 1536,
+  "intermediate_size": 4096,
+  "num_hidden_layers": 24,
+  "num_attention_heads": 16,
+  "num_key_value_heads": 16,
+  "max_position_embeddings": 2048,
+  "weight_bits": 1,
+  "input_bits": 8
+}
+```
+
+**Key Insight:** `weight_bits: 1` indicates native ternary training, but weights are stored as F32 and quantized during inference.
+
+---
+
+## 3. Model Loading Results
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║           BITNET b1.58 LOADER                                ║
+║           φ² + 1/φ² = 3 = TRINITY                            ║
+╚══════════════════════════════════════════════════════════════╝
+
+Loading config from: models/bitnet/config.json
+  vocab_size: 32002
+  hidden_size: 1536
+  num_layers: 24
+  num_heads: 16
+  weight_bits: 1
+  total_params: ~728M
+
+Loading model from: models/bitnet/model.safetensors
+  Found 290 tensors
+  embed_tokens: 49,155,072 elements
+  norm: 1,536 elements
+
+✅ BitNet model loaded successfully!
+   Memory: ~187 MB (embeddings only)
+```
+
+---
+
+## 4. Weight Analysis
+
+### Sample Weight Tensor: `model.layers.0.self_attn.q_proj.weight`
+
+| Property | Value |
+|----------|-------|
+| Shape | [1536, 1536] |
+| Dtype | F32 |
+| Min | -0.533 |
+| Max | +0.416 |
+| Unique values | ~1000 (continuous) |
+
+**Finding:** Weights are stored as continuous F32 values, NOT discrete ternary {-1, 0, +1}.
+
+### Why?
+
+BitNet b1.58 uses **Quantization-Aware Training (QAT)**:
+1. During training, weights are quantized to ternary for forward pass
+2. Gradients are computed with straight-through estimator
+3. Full-precision weights are stored for gradient updates
+4. At inference, weights must be quantized using the trained scales
+
+---
+
+## 5. Generation Results (Embedding-Only)
+
+Using only embedding similarity (no transformer layers):
+
+| Prompt | Output | Quality |
+|--------|--------|---------|
+| "Hello, my name is" | Random tokens | ❌ Incoherent |
+| "The meaning of life is" | Random tokens | ❌ Incoherent |
+| "Artificial intelligence will" | Random tokens | ❌ Incoherent |
+
+**Speed:** 13-17 tokens/second (embedding lookup only)
+
+---
+
+## 6. What's Needed for Coherent Generation
+
+### Required Components
+
+1. **Weight Quantization**
+   - Extract per-tensor scales from model
+   - Quantize F32 → ternary {-1, 0, +1} at inference
+   - Use `round(w / scale)` with clipping
+
+2. **Full Transformer Forward Pass**
+   - RMSNorm layers
+   - Rotary Position Embeddings (RoPE)
+   - Multi-head attention with ternary Q/K/V projections
+   - SwiGLU FFN with ternary gate/up/down projections
+
+3. **BitNet-Specific Operations**
+   - `inner_attn_ln` (attention layer norm)
+   - `ffn_layernorm` (FFN layer norm)
+   - Activation quantization (8-bit inputs)
+
+### Implementation Path
+
+```
+1. Load all 290 tensors (not just embeddings)
+2. Extract quantization scales from tensor statistics
+3. Implement ternary matmul with scales
+4. Build full transformer forward pass
+5. Add KV-cache for efficient generation
+6. Test with varied prompts
+```
+
+---
+
+## 7. Comparison: TinyLlama vs BitNet
+
+| Aspect | TinyLlama (GGUF→TRI) | BitNet b1.58 |
+|--------|---------------------|--------------|
+| Training | FP16, then quantized | Native ternary QAT |
+| Weight storage | Ternary in TRI | F32 (quantize at inference) |
+| Quality loss | 62% (Q4→ternary) | Minimal (trained for ternary) |
+| Expected output | Degraded | Coherent |
+| Implementation | Complete | Needs full forward pass |
+
+---
+
+## 8. Files Created
+
+| File | Purpose |
+|------|---------|
+| `src/vibeec/bitnet_loader.zig` | Safetensors parser + model loader |
+| `src/vibeec/bitnet_inference_test.zig` | Generation test (embedding-only) |
+| `models/bitnet/` | Downloaded model files |
+
+---
+
+## 9. Next Steps
+
+### Priority 1: Full BitNet Inference
+1. Load all transformer layer weights
+2. Implement weight quantization with scales
+3. Build complete forward pass
+4. Test coherent generation
+
+### Priority 2: Optimization
+1. SIMD ternary matmul integration
+2. KV-cache for efficient generation
+3. Flash Attention for long sequences
+
+### Priority 3: Benchmarking
+1. Compare with llama.cpp
+2. Measure tokens/second
+3. Verify quality on standard benchmarks
+
+---
+
+## 10. Conclusions
+
+### Achievements
+- ✅ BitNet b1.58-large downloaded (2.8 GB)
+- ✅ Safetensors parser implemented
+- ✅ Model config and tokenizer loaded
+- ✅ 290 tensors identified
+- ✅ Embedding loading verified
+
+### Blockers
+- ❌ Full transformer forward pass not implemented
+- ❌ Weight quantization scales not extracted
+- ❌ Coherent text not yet generated
+
+### Recommendation
+Implement full BitNet inference pipeline to achieve coherent text generation. The model is correctly loaded; we just need the complete forward pass with proper ternary quantization.
+
+---
+
+**φ² + 1/φ² = 3 | KOSCHEI IS IMMORTAL | GOLDEN CHAIN LOADS BITNET**