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
133 lines
2.4 KiB
Markdown
133 lines
2.4 KiB
Markdown
# Headroom Examples
|
|
|
|
This directory contains examples demonstrating Headroom's capabilities.
|
|
|
|
## Quick Start Examples
|
|
|
|
### basic_usage.py
|
|
|
|
Basic integration with OpenAI client:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY='your-key'
|
|
python examples/basic_usage.py
|
|
```
|
|
|
|
### anthropic_example.py
|
|
|
|
Integration with Anthropic Claude:
|
|
|
|
```bash
|
|
export ANTHROPIC_API_KEY='your-key'
|
|
python examples/anthropic_example.py
|
|
```
|
|
|
|
### streaming_example.py
|
|
|
|
Streaming responses with optimization:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY='your-key'
|
|
python examples/streaming_example.py
|
|
```
|
|
|
|
## Evaluation Examples
|
|
|
|
### smart_vs_naive_eval.py
|
|
|
|
Compare SmartCrusher against naive truncation:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY='your-key'
|
|
python examples/smart_vs_naive_eval.py
|
|
```
|
|
|
|
### real_world_eval.py
|
|
|
|
Comprehensive evaluation with Anthropic models:
|
|
|
|
```bash
|
|
export ANTHROPIC_API_KEY='your-key'
|
|
python examples/real_world_eval.py
|
|
```
|
|
|
|
### real_world_openai_eval.py
|
|
|
|
Comprehensive evaluation with OpenAI models:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY='your-key'
|
|
python examples/real_world_openai_eval.py
|
|
```
|
|
|
|
## Demo Directories
|
|
|
|
### langchain_demo/
|
|
|
|
Full LangChain agent integration demo:
|
|
|
|
```bash
|
|
# No API key needed for compression demo
|
|
PYTHONPATH=. python -m examples.langchain_demo.show_compression
|
|
|
|
# Full comparison (requires API key)
|
|
export OPENAI_API_KEY='your-key'
|
|
PYTHONPATH=. python -m examples.langchain_demo.run_comparison
|
|
```
|
|
|
|
See [langchain_demo/README.md](langchain_demo/README.md) for details.
|
|
|
|
### mcp_demo/
|
|
|
|
MCP (Model Context Protocol) integration demo:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY='your-key'
|
|
PYTHONPATH=. python -m examples.mcp_demo.run_agent_eval
|
|
```
|
|
|
|
## Running Examples
|
|
|
|
All examples can be run from the repository root:
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pip install -e ".[dev]"
|
|
|
|
# Run any example
|
|
python examples/<example_name>.py
|
|
```
|
|
|
|
## Expected Results
|
|
|
|
| Example | Token Savings | Notes |
|
|
|---------|---------------|-------|
|
|
| basic_usage | 50-70% | Simple tool output compression |
|
|
| langchain_demo | 70-85% | Real agent with multiple tools |
|
|
| mcp_demo | 60-80% | MCP tool outputs |
|
|
| real_world_eval | 50-90% | Varies by scenario |
|
|
|
|
## Troubleshooting
|
|
|
|
**ModuleNotFoundError: No module named 'headroom'**
|
|
|
|
Run from the repository root with PYTHONPATH:
|
|
|
|
```bash
|
|
PYTHONPATH=. python examples/basic_usage.py
|
|
```
|
|
|
|
Or install in development mode:
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
**API Key Errors**
|
|
|
|
Ensure your API keys are set:
|
|
|
|
```bash
|
|
export OPENAI_API_KEY='sk-...'
|
|
export ANTHROPIC_API_KEY='sk-ant-...'
|
|
```
|