CHANGELOG.md

Changelog

All notable changes to Headroom will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

• Production-ready proxy server with caching, rate limiting, and metrics
• CLI command headroom proxy to start the proxy server

0.2.0 - 2025-01-07

Added

• SmartCrusher: Statistical compression for tool outputs
  • Keeps first/last K items, errors, anomalies, and relevance matches
  • Variance-based change point detection
  • Pattern detection (time series, logs, search results)
• Relevance Scoring Engine: ML-powered item relevance
  • BM25Scorer: Fast keyword matching (zero dependencies)
  • EmbeddingScorer: Semantic similarity with sentence-transformers
  • HybridScorer: Adaptive combination of both methods
• CacheAligner: Prefix stabilization for better cache hits
  • Dynamic date extraction
  • Whitespace normalization
  • Stable prefix hashing
• RollingWindow: Context management within token limits
  • Drops oldest tool units first
  • Never orphans tool results
  • Preserves recent turns
• Multi-Provider Support:
  • Anthropic with official count_tokens API
  • Google with official countTokens API
  • Cohere with official tokenize API
  • Mistral with official tokenizer
  • LiteLLM for unified interface
• Integrations:
  • LangChain callback handler (HeadroomOptimizer)
  • MCP (Model Context Protocol) utilities
• Proxy Server (headroom.proxy):
  • Semantic caching with LRU eviction
  • Token bucket rate limiting
  • Retry with exponential backoff
  • Cost tracking with budget enforcement
  • Prometheus metrics endpoint
  • Request logging (JSONL)
• Pricing Registry: Centralized model pricing with staleness tracking
• Benchmarks: Performance benchmarks for transforms and relevance scoring

Changed

• Improved token counting accuracy across all providers
• Enhanced tool output compression with relevance-aware selection

Fixed

• Mistral tokenizer API compatibility
• Google token counting for multi-turn conversations

0.1.0 - 2025-01-05

Added

• Initial release
• HeadroomClient: OpenAI-compatible client wrapper
• ToolCrusher: Basic tool output compression
• Audit mode for observation without modification
• Optimize mode for applying transforms
• Simulate mode for previewing changes
• SQLite and JSONL storage backends
• HTML report generation
• Streaming support

Safety Guarantees

• Never removes human content
• Never breaks tool ordering
• Parse failures are no-ops
• Preserves recency (last N turns)

---

Migration Guide

From 0.1.x to 0.2.x

The 0.2.0 release is backward compatible. New features are opt-in:

# Old code still works
from headroom import HeadroomClient, OpenAIProvider

# New SmartCrusher (replaces ToolCrusher for better compression)
from headroom import SmartCrusher, SmartCrusherConfig

config = SmartCrusherConfig(
    min_tokens_to_crush=200,
    max_items_after_crush=50,
)
crusher = SmartCrusher(config)

# New relevance scoring
from headroom import create_scorer

scorer = create_scorer("hybrid")  # or "bm25" for zero deps

Using the Proxy

New in 0.2.0 - run Headroom as a proxy server:

# Start the proxy
python -m headroom.proxy.server --port 8787

# Use with Claude Code
ANTHROPIC_BASE_URL=http://localhost:8787 claude