How ContentRouter Decides Which Compressors to Use for Different Content Types

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

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

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])

## 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.

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