mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
175746cc26
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
109 lines
2.1 KiB
Markdown
109 lines
2.1 KiB
Markdown
# Getting Started with Headroom
|
|
|
|
This guide will help you get up and running with Headroom in under 5 minutes.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# Core package (minimal dependencies)
|
|
pip install headroom
|
|
|
|
# With proxy server
|
|
pip install headroom[proxy]
|
|
|
|
# With semantic relevance (for smarter compression)
|
|
pip install headroom[relevance]
|
|
|
|
# Everything
|
|
pip install headroom[all]
|
|
```
|
|
|
|
## Quick Start: Proxy Mode (Recommended)
|
|
|
|
The easiest way to use Headroom is as a proxy server:
|
|
|
|
```bash
|
|
# Start the proxy
|
|
headroom proxy --port 8787
|
|
```
|
|
|
|
Then point your LLM client at it:
|
|
|
|
```bash
|
|
# Claude Code
|
|
ANTHROPIC_BASE_URL=http://localhost:8787 claude
|
|
|
|
# OpenAI-compatible clients
|
|
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
|
|
```
|
|
|
|
That's it! All your requests now go through Headroom and get optimized automatically.
|
|
|
|
## Quick Start: Python SDK
|
|
|
|
If you want programmatic control:
|
|
|
|
```python
|
|
from headroom import HeadroomClient
|
|
from openai import OpenAI
|
|
|
|
# Create a wrapped client
|
|
client = HeadroomClient(
|
|
original_client=OpenAI(),
|
|
default_mode="optimize",
|
|
)
|
|
|
|
# Use exactly like the original
|
|
response = client.chat.completions.create(
|
|
model="gpt-4o",
|
|
messages=[
|
|
{"role": "system", "content": "You are a helpful assistant."},
|
|
{"role": "user", "content": "Hello!"},
|
|
],
|
|
)
|
|
```
|
|
|
|
## Modes
|
|
|
|
### Audit Mode
|
|
|
|
Observe without modifying:
|
|
|
|
```python
|
|
client = HeadroomClient(
|
|
original_client=OpenAI(),
|
|
default_mode="audit",
|
|
)
|
|
# Logs metrics but doesn't change requests
|
|
```
|
|
|
|
### Optimize Mode
|
|
|
|
Apply transforms to reduce tokens:
|
|
|
|
```python
|
|
client = HeadroomClient(
|
|
original_client=OpenAI(),
|
|
default_mode="optimize",
|
|
)
|
|
# Compresses tool outputs, aligns cache prefixes, etc.
|
|
```
|
|
|
|
### Simulate Mode
|
|
|
|
Preview what optimizations would do:
|
|
|
|
```python
|
|
plan = client.chat.completions.simulate(
|
|
model="gpt-4o",
|
|
messages=[...],
|
|
)
|
|
print(f"Would save {plan.tokens_saved} tokens")
|
|
print(f"Transforms: {plan.transforms_applied}")
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- [Proxy Server Documentation](proxy.md) - Configure the proxy
|
|
- [Transforms Reference](transforms.md) - Understand each transform
|
|
- [API Reference](api.md) - Full API documentation
|