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

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, 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

// 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 (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 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 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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}