# How to Enable Tolerance in Headroom.js: Configuring the Adaptive-Sizer Transform

> Learn how to enable tolerance in Headroom.js by configuring the adaptiveSizer transform. Control compression ratio variance for optimal header behavior.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-17

---

**You enable tolerance in Headroom.js by setting the `tolerance` property within the `transforms.adaptiveSizer` configuration object when instantiating the Headroom client, which controls the acceptable compression-ratio variance before the algorithm adjusts the number of retained items.**

The open-source Headroom library (`chopratejas/headroom`) provides an adaptive-sizer transform that relies on a tolerance threshold to determine when to expand the count of kept items based on compression-ratio differences. While the core algorithm is implemented in Python, the JavaScript SDK exposes this setting directly, allowing you to override the default 15% variance limit.

## What Is Tolerance in Headroom.js?

**Tolerance** is a floating-point ratio that defines how much the compression-ratio may differ before the adaptive-sizer algorithm expands the number of items it retains. In the underlying Python implementation located at [`headroom/transforms/adaptive_sizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/adaptive_sizer.py), the internal `_validate_with_zlib` helper accepts this parameter and applies a default value of `0.15` (15%) at lines 59–62. This value represents the maximum acceptable deviation before the system triggers an expansion of the kept item count to maintain data integrity.

## How to Configure Tolerance in the JavaScript SDK

When creating a Headroom instance, pass your custom tolerance value through the `transforms.adaptiveSizer` configuration object. If you omit this field, the client automatically falls back to the 15% default defined in the Python source.

### Basic Configuration Example

```javascript
// Import the Headroom client
import { Headroom } from '@headroom/sdk';

// Create instance with custom tolerance
const hr = new Headroom({
  // other Headroom options...
  transforms: {
    adaptiveSizer: {
      // Allow up to 30% compression-ratio variance before expanding K
      tolerance: 0.30,
      // Optional: bias factor (1.0 = neutral)
      bias: 1.0,
    },
  },
});

// Use the client normally
await hr.runPrompt(...);

```

### Parameter Reference

- **`tolerance`**: A floating-point number between `0.0` and `1.0` representing the percentage (as a decimal) of acceptable compression-ratio variance. Values closer to `0.0` enforce stricter retention policies, while higher values allow more aggressive compression.
- **`bias`**: An optional multiplier that influences the algorithm to keep more or fewer items; `1.0` maintains neutral behavior.

## How Tolerance Works in the Source Code

According to the `chopratejas/headroom` source code, the tolerance value flows from the JavaScript configuration into the Python backend. The public `compute_optimal_k` function in [`headroom/transforms/adaptive_sizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/adaptive_sizer.py) (lines 59–61) forwards the tolerance parameter to the internal validation logic. This ensures that the `_validate_with_zlib` helper respects your custom threshold when evaluating compression ratios against the zlib-validated baseline.

## Summary

- **Tolerance** controls the compression-ratio variance threshold (default: 15% or `0.15`) in Headroom’s adaptive-sizer transform.
- Configure it in the JavaScript SDK via the `transforms.adaptiveSizer.tolerance` field when instantiating the Headroom client.
- The default value is hardcoded in [`headroom/transforms/adaptive_sizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/adaptive_sizer.py) within the `_validate_with_zlib` function at lines 59–62.
- Valid values are floating-point decimals between `0.0` and `1.0`, where lower values enforce stricter retention.

## Frequently Asked Questions

### What is the default tolerance value in Headroom.js?

The default tolerance is **15% (0.15)**, defined in the Python backend at [`headroom/transforms/adaptive_sizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/adaptive_sizer.py) within the `_validate_with_zlib` helper (lines 59–62). This default applies automatically when you do not specify a custom tolerance in the JavaScript configuration.

### Can I disable tolerance by setting it to zero?

Yes. Setting `tolerance: 0.0` forces the adaptive-sizer to expand the number of kept items whenever any compression-ratio deviation is detected, effectively eliminating all tolerance for maximum data retention precision.

### Does the tolerance setting affect the `compute_optimal_k` function?

Yes. According to the source code in [`headroom/transforms/adaptive_sizer.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/adaptive_sizer.py) (lines 59–61), the public `compute_optimal_k` entry point forwards the tolerance value to the internal validator, ensuring the setting propagates through the entire compression pipeline.

### Is the tolerance configuration available when using the Python API directly?

Yes. While this guide focuses on the JavaScript SDK, the Python implementation accepts tolerance as a parameter in the `compute_optimal_k` function and `_validate_with_zlib` helper, allowing identical configuration when using the Python client natively.