# Makarna Test Suite

This directory contains comprehensive tests for the Makarna inference engine.

## Test Structure

- **quant_test.go**: Quantization/dequantization correctness tests for all K-quant types
  - Q2_K (2-bit, 4 levels)
  - Q3_K (3-bit, 8 levels)
  - Q4_K (4-bit, 16 levels)
  - Q6_K (6-bit, 64 levels)
  - Q8_K (8-bit, 256 levels)

- **unit_quant_test.go**: Unit tests for low-level quantization utilities
  - FP16 ↔ FP32 conversion
  - Individual dequantization functions

- **backend_test.go**: Backend operation tests
  - Linear (matrix multiplication)
  - Embedding lookup
  - RMSNorm
  - Softmax

- **data/**: Golden test data (binary files)
  - Contains quantized blocks + original float32 data for validation

## Running Tests

### All Tests
```bash
cd tests
go test -v
```

### Specific Test
```bash
cd tests
go test -v -run TestQ3K_GoldenIter
```

## Test Patterns

Each quantization type is tested against 4 different data patterns:

1. **Gradient**: Linear range [-0.5, 0.5] - tests uniform distribution
2. **Random Normal**: Gaussian N(0, 0.05²) - typical weight distribution
3. **Random Large**: Gaussian N(0, 50²) - stress test for extreme values
4. **Sparse**: Mostly zeros with scattered values - tests sparsity handling

## Expected Precision

| Type  | Bits | Levels | Typical MSE (Normal) | Use Case |
|-------|------|--------|---------------------|----------|
| Q8_K  | 8    | 256    | < 0.001             | High precision |
| Q6_K  | 6    | 64     | < 0.002             | Embeddings |
| Q4_K  | 4    | 16     | < 0.05              | General weights |
| Q3_K  | 3    | 8      | < 0.15              | Medium quality mix |
| Q2_K  | 2    | 4      | < 0.5               | Aggressive compression |

**Note**: Large-range patterns (±50+) will have proportionally higher MSE due to quantization binning.

## Adding New Tests

1. Add test function to appropriate `*_test.go` file
2. Follow existing test naming: `Test<Feature>_<Variant>`
3. Use descriptive logging: `t.Logf()` for metrics, `t.Errorf()` for failures

## CI Integration

These tests run automatically on:
- Code changes to `pkg/tensor/`, `pkg/backend/`
- Test updates

All tests must pass before merge.