What Types of Data Can CacheAligner Detect? A Deep Dive into Headroom's Volatile Content Patterns

CacheAligner detects four specific volatile data patterns—UUIDs, ISO-8601 timestamps, JWTs, and hex hashes (MD5, SHA-1, SHA-256)—using structural validation functions rather than regular expressions.

CacheAligner is a detector-only transform in the chopratejas/headroom repository designed to spot dynamic content within system prompts. By identifying these volatile patterns, developers can maintain stable cache prefixes and optimize LLM inference costs. The implementation relies on precise structural checks implemented in headroom/transforms/cache_aligner.py.

The Four Data Types CacheAligner Detects

According to the chopratejas/headroom source code, CacheAligner specifically looks for four concrete patterns that commonly introduce volatility into system prompts.

UUIDs (Canonical RFC 4122)

CacheAligner identifies standard UUIDs through the _is_uuid function (lines 76-93). The validation confirms the token contains exactly 36 characters including four hyphens, then attempts to parse it using Python's uuid.UUID constructor. This catches canonical forms like 123e4567-e89b-12d3-a456-426614174000 without relying on regex patterns.

ISO-8601 Timestamps

The _is_iso8601 function (lines 96-112) detects date-time strings by first checking length and delimiter structure, then normalizing any "Z" suffix to +00:00 before passing to datetime.fromisoformat. This recognizes formats such as 2024-03-01T12:34:56Z while rejecting invalid date strings through Python's standard library validation.

JSON Web Tokens (JWTs)

JWT detection occurs in _is_jwt_shape (lines 115-136), which splits the token on periods and verifies three distinct segments. Each segment must be base64-url decodable and contain at least 4 bytes. This structural approach identifies tokens like eyJhbGciOiJIUzI1NiIs... by validating the shape rather than decoding payload claims.

Hexadecimal Hash Digests

The _is_hex_hash function (lines 139-152) recognizes MD5, SHA-1, and SHA-256 hashes by checking if the token length exists in the set {32, 40, 64} and successfully parses as hexadecimal via int(token, 16). This distinguishes cryptographic fingerprints from random alphanumeric strings through length-specific validation.

How the Detection Pipeline Works

CacheAligner processes prompts through a four-stage pipeline that never mutates the input text.

Tokenization – The _split_tokens helper splits prompt text on whitespace and strips surrounding punctuation to isolate candidate strings.

Classification – Each token passes through _classify_token, which sequentially invokes the four detection helpers in order of specificity (UUID, ISO-8601, JWT, then hash).

Reporting – For every match, the system creates a VolatileFinding(label, sample) dataclass instance. A warning log aggregates counts per label, while a stable hash of the unchanged system prompt is stored in CachePrefixMetrics for observability.

Scoring – The CacheAligner.get_alignment_score method converts finding counts into a 0-100 alignment metric, subtracting 10 points per volatile detection and clamping the result.

Source Code Reference

The core detection logic resides in headroom/transforms/cache_aligner.py, which exports the CacheAligner class and the detect_volatile_content convenience function. Configuration options live in headroom/config.py via CacheAlignerConfig, while architecture documentation in wiki/ARCHITECTURE.md positions CacheAligner as the first stage in the compression pipeline.

Practical Usage Example

The following example demonstrates detecting a UUID, timestamp, and JWT within a system prompt:

from headroom.transforms.cache_aligner import detect_volatile_content, align_for_cache

system_prompt = """
You are a helpful assistant.
Today is 2024-03-01.
Your request id is 123e4567-e89b-12d3-a456-426614174000.
Auth token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTYifQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
"""

findings = detect_volatile_content(system_prompt)
for f in findings:
    print(f"⚠️  {f.label}: {f.sample}")

messages = [{"role": "system", "content": system_prompt}]
cleaned, prefix_hash = align_for_cache(messages)

print("\nStable prefix hash:", prefix_hash)
print("Messages unchanged:", cleaned == messages)  # True

This outputs detection warnings for each volatile pattern while returning the original messages unmodified and a stable hash for cache comparison.

Summary

• CacheAligner detects four specific patterns: UUIDs, ISO-8601 timestamps, JWTs, and hex hashes (MD5/SHA-1/SHA-256).
• Detection uses structural validation (uuid.UUID, datetime.fromisoformat, base64 decoding, and int(token, 16)) rather than regular expressions.
• The transform is read-only: it never modifies prompts, only reports findings via VolatileFinding objects and logs.
• Implementation resides in headroom/transforms/cache_aligner.py with specific helper functions at lines 76-152.
• An alignment score (0-100) quantifies cache stability based on the count of volatile content detected.

Frequently Asked Questions

Does CacheAligner modify the prompt content?

No. CacheAligner is a detector-only transform that identifies volatile patterns but never mutates the input messages. The align_for_cache function returns the original messages unchanged alongside a stable prefix hash and detection metrics.

How does CacheAligner detect UUIDs without using regular expressions?

The _is_uuid function validates UUIDs by checking the token length (36 characters), confirming four hyphens exist at specific positions, and attempting instantiation via Python's uuid.UUID parser. This structural approach avoids regex overhead while ensuring RFC 4122 compliance.

What is the alignment score and how is it calculated?

The alignment score is a 0-100 metric produced by CacheAligner.get_alignment_score. The calculation subtracts 10 points for each volatile finding detected in the prompt, then clamps the result to a minimum of 0. Higher scores indicate more cache-friendly content with fewer dynamic elements.

Can I disable specific detection patterns in CacheAligner?

Yes. Configuration is managed through CacheAlignerConfig in headroom/config.py, which allows toggling individual detectors or adjusting the sensitivity thresholds for the alignment scoring algorithm.

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