akadmin/headroom
1
0
Fork 0
mirror of https://github.com/headroomlabs-ai/headroom.git synced 2026-08-27 14:17:10 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
headroom/CHANGELOG.md
chopratejas 175746cc26 Prepare for OSS release v0.2.0 
This commit prepares Headroom for public open source release with
comprehensive documentation, licensing, and community infrastructure.

License & Legal:
- Add Apache 2.0 LICENSE file
- Add NOTICE file with third-party attributions
- Add SECURITY.md for vulnerability reporting

Community:
- Add CONTRIBUTING.md with contribution guidelines
- Add CODE_OF_CONDUCT.md (Contributor Covenant)
- Add GitHub issue templates (bug report, feature request)
- Add pull request template

Documentation:
- Update README.md with compelling value proposition
- Add docs/getting-started.md
- Add docs/proxy.md for proxy server documentation
- Add docs/transforms.md for transform reference
- Add docs/api.md for API reference
- Add examples/README.md

Package Infrastructure:
- Add headroom/py.typed for PEP 561 compliance
- Add headroom/cli.py for CLI entry point
- Add .github/workflows/ci.yml for CI pipeline
- Add .github/workflows/publish.yml for PyPI publishing
- Update pyproject.toml with proper metadata

New Features:
- Add multi-provider support (Google, Cohere, LiteLLM, OpenAI-compatible)
- Add universal tokenizer registry with multiple backends
- Add model registry with pricing and context limits
- Add production proxy server with caching and rate limiting

Code Quality:
- Fix 83 lint issues via ruff auto-fix
- Fix version consistency (benchmarks 0.1.0 → 0.2.0)
- Add skip decorators for optional dependency tests
2026-01-07 11:36:44 -08:00

3.6 KiB
Raw Blame History

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