# How ContentRouter Decides Which Compressors to Use for Different Content Types

> Discover how ContentRouter's deterministic six-step pipeline selects the best compressors for diverse content, including CODE_AWARE for code and SMART_CRUSHER for JSON arrays.

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

---

**The ContentRouter employs a deterministic six-step pipeline that detects content type, handles mixed payloads specially, and maps specific content categories to dedicated compression strategies such as CODE_AWARE for source code and SMART_CRUSHER for JSON arrays.**

In the `chopratejas/headroom` repository, the `ContentRouter` serves as the central decision-making engine for intelligent text compression. Rather than applying a one-size-fits-all algorithm, the router analyzes incoming payloads to determine how ContentRouter decides which compressors to use based on structural characteristics and configuration settings.

## The Decision Pipeline

The routing logic in [`headroom/transforms/content_router.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/content_router.py) processes every input through a strict hierarchy. Understanding this flow is essential for predicting which compressor will handle your specific content.

### Early-Out for Empty Content

The router first checks for empty or whitespace-only input at lines 49-52. When detected, it immediately returns a **passthrough** result without invoking any compressor:

```python
if not content or not content.strip():
    result = RouterCompressionResult(... strategy_used=CompressionStrategy.PASSTHROUGH ...)

```

This optimization prevents wasted CPU cycles on null payloads.

### Mixed Content Detection

Next, the router examines whether the payload contains multiple content types using `is_mixed_content()` (lines 57-75). This function scans the text with regex patterns to identify code fences, JSON blocks, prose sections, and search results.

When two or more indicators are present, the router selects the **MIXED** strategy. At lines 163-176, the payload splits into individual sections, with each segment routed separately through the detection pipeline. This ensures that code blocks within documentation receive different treatment than surrounding explanatory text.

### Content Type Detection

For homogeneous content, the router delegates to `_detect_content()` (lines 124-142). This method selects between Rust and pure-Python detection backends based on the `HEADROOM_DETECT_BACKEND` environment variable or platform defaults.

The detection system returns a `ContentType` enum value, such as:
- `SOURCE_CODE`
- `JSON_ARRAY`
- `SEARCH_RESULTS`
- `BUILD_OUTPUT`
- `PLAIN_TEXT`

### Strategy Mapping

The `_strategy_from_detection()` method (lines 1890-1897) contains a static mapping that translates `ContentType` values into `CompressionStrategy` selections:

- `ContentType.SOURCE_CODE` → `CompressionStrategy.CODE_AWARE`
- `ContentType.JSON_ARRAY` → `CompressionStrategy.SMART_CRUSHER`
- `ContentType.SEARCH_RESULTS` → `CompressionStrategy.SEARCH`
- `ContentType.BUILD_OUTPUT` → `CompressionStrategy.LOG`
- `ContentType.PLAIN_TEXT` → `CompressionStrategy.TEXT`

### Configuration Overrides

After initial mapping, the router checks `ContentRouterConfig` settings at lines 2002-2006. If `prefer_code_aware_for_code` is disabled (the default), the router substitutes **KOMPRESS** as the fallback strategy. The `fallback_strategy` setting (defaulting to `KOMPRESS`) also activates when content type detection returns an unknown category.

### Final Compression Application

The router invokes the selected compressor via `_apply_strategy_to_content()`, delegating to specific implementations like `self._code_compressor`, `self._smart_crusher`, or `self._kompress_compressor`. The resulting `RouterCompressionResult` contains the compressed text, the primary strategy used, and a detailed routing log for debugging purposes.

## Configuration Options

The `ContentRouterConfig` class in [`headroom/transforms/compression_policy.py`](https://github.com/chopratejas/headroom/blob/main/headroom/transforms/compression_policy.py) controls routing behavior through two critical flags:

- **`prefer_code_aware_for_code`**: When set to `True`, preserves source code detection; when `False`, forces the `fallback_strategy` instead.
- **`fallback_strategy`**: Defines the compressor used for unknown content types or when code-aware preferences are disabled (defaults to `KOMPRESS`).

## Practical Examples

```python
from headroom.transforms import ContentRouter, CompressionStrategy

router = ContentRouter()

# Plain text → TEXT compressor (KOMPRESS by default)

plain = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
result = router.compress(plain)
print(result.strategy_used)          # → CompressionStrategy.TEXT (KOMPRESS)

print(result.compression_ratio)     # token savings %

# JSON array → SMART_CRUSHER

json_array = "[{\"id\": 1}, {\"id\": 2}, {\"id\": 3}]"
result = router.compress(json_array)
print(result.strategy_used)          # → CompressionStrategy.SMART_CRUSHER

# Mixed content (code block + prose) → MIXED strategy

mixed = """Here is some documentation.

```python
def hello():
    print("world")

```

The function above prints a greeting.
"""
result = router.compress(mixed)
print(result.strategy_used)          # → CompressionStrategy.MIXED

print([d.strategy for d in result.routing_log])

# → [CompressionStrategy.KOMPRESS, CompressionStrategy.CODE_AWARE]

```

## Summary

- **Empty inputs** bypass compression entirely via the PASSTHROUGH strategy.
- **Mixed content** triggers automatic segmentation, with each section routed to its optimal compressor.
- **Content type detection** relies on `HEADROOM_DETECT_BACKEND` to choose between Rust and Python implementations.
- **Static mappings** in `_strategy_from_detection()` assign source code to CODE_AWARE, JSON to SMART_CRUSHER, and search results to SEARCH.
- **Configuration overrides** allow forcing KOMPRESS or other fallback strategies when `prefer_code_aware_for_code` is disabled.
- **Debug logs** in `RouterCompressionResult` expose the exact routing decisions for each payload.

## Frequently Asked Questions

### How does ContentRouter handle documents containing both code and prose?

When `is_mixed_content()` detects multiple content indicators (lines 57-75), the router applies the MIXED strategy. It splits the payload into sections at lines 163-176, then routes each segment individually through the detection pipeline. This ensures code blocks receive CODE_AWARE compression while surrounding text uses TEXT or KOMPRESS strategies.

### Can I force the router to use a specific compressor regardless of content type?

Yes, through `ContentRouterConfig` settings. If you disable `prefer_code_aware_for_code` (which defaults to False), the router substitutes your configured `fallback_strategy` (defaulting to KOMPRESS) for all content, effectively bypassing the type-specific mapping in `_strategy_from_detection()`.

### What happens when ContentRouter cannot identify the content type?

When detection returns an unknown `ContentType`, the router consults `ContentRouterConfig.fallback_strategy` (lines 2002-2006). By default, this routes the content to the KOMPRESS compressor, ensuring every payload receives compression even when the detection backend fails to categorize the input.

### Which detection backends does ContentRouter support?

The `_detect_content()` method (lines 124-142) supports both Rust and pure-Python implementations. The router selects the backend based on the `HEADROOM_DETECT_BACKEND` environment variable, falling back to platform defaults when the variable is unset. Both backends return the same `ContentType` enum values used for strategy selection.