mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 13:29:19 +08:00
## Description
The `generate_report()` example in `docs/content/docs/api-reference.mdx`
and `wiki/api.md` passes `format="html"` and `period="day"`, and says it
produces "HTML/Markdown" reports. Neither keyword exists. Running the
documented snippet verbatim on 0.41.x:
```
TypeError: generate_report() got an unexpected keyword argument 'format'
```
Actual signature (`headroom/reporting/generator.py`):
`generate_report(store_url, output_path="report.html", start_time=None,
end_time=None) -> str`. It writes HTML only and returns the output file
path.
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- Replace the example with the real arguments (`output_path`,
`start_time`), say it returns the path, drop "Markdown" from the
description. Both files, docs only.
- `store_url` uses the `sqlite:////absolute/path/...` form that
`configuration.mdx` already documents: `sqlite:///headroom.db` resolves
to `/headroom.db` at the filesystem root, so the old example also fails
with `OperationalError: unable to open database file` on a normal
machine.
- `start_time` is timezone-aware (`datetime.now(timezone.utc)`), since
`format_timestamp` treats a naive datetime as already UTC (fixed in
0338644 after review).
## Testing
- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed
No regression test: the change is documentation text only, no code under
`headroom/` is modified, and there is no docs-snippet test harness in
the repo to extend.
### Test Output
```text
naive (old doc) cutoff: 2026-10-22T10:00:00Z
aware (new doc) cutoff: 2026-10-22T15:00:00Z
```
(`format_timestamp` from this branch, simulating a UTC-5 host at
2026-10-23 10:00 local = 15:00Z.)
## Real Behavior Proof
- Environment: headroom 0.41.x, macOS, Python 3.12.
- Exact command / steps: run the old snippet;
`inspect.signature(headroom.generate_report)`; run the new snippet with
an absolute `sqlite:////...` path.
- Observed result: old snippet raises `TypeError`; signature matches the
one above; new snippet writes `report.html` and returns its path.
- Not tested: Windows; the date filter was checked through
`format_timestamp` only, not an end-to-end report against a seeded
store.
## Runtime Rollout Safety
- Rollout-managed feature(s): none
- Minimum rollout channel: n/a (docs only)
- Stable/default behavior changed: no
- Kill switch / disable path: n/a
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this commit
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
---------
Signed-off-by: Anton Dziatkovskii <dzyatkovskiy.a@gmail.com>
Co-authored-by: Anton Dziatkovskii <dzyatkovskiy.a@gmail.com>
Co-authored-by: tonydzi <194927794+tonydzi@users.noreply.github.com>
Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
342 lines
7.1 KiB
Markdown
342 lines
7.1 KiB
Markdown
# API Reference
|
|
|
|
## HeadroomClient
|
|
|
|
The main entry point for Headroom SDK.
|
|
|
|
```python
|
|
from headroom import HeadroomClient
|
|
from openai import OpenAI
|
|
|
|
client = HeadroomClient(
|
|
original_client=OpenAI(),
|
|
default_mode="optimize",
|
|
)
|
|
```
|
|
|
|
### Constructor Parameters
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|-----------|------|---------|-------------|
|
|
| `original_client` | `OpenAI \| Anthropic` | Required | The underlying LLM client |
|
|
| `provider` | `Provider` | Required (no default) | Token counting provider — e.g. `OpenAIProvider()`, `AnthropicProvider()` |
|
|
| `default_mode` | `str` | `"audit"` | Default mode: "audit", "optimize", "off" |
|
|
| `store_url` | `str` | `None` | Storage URL for metrics |
|
|
| `model_context_limits` | `dict[str, int]` | `None` | Override context limits for models |
|
|
| `cache_optimizer` | `BaseCacheOptimizer` | `None` (auto-detect) | Custom cache optimizer |
|
|
| `enable_cache_optimizer` | `bool` | `True` | Enable provider-specific cache optimization |
|
|
| `enable_semantic_cache` | `bool` | `False` | Enable query-level semantic caching |
|
|
| `config` | `HeadroomConfig` | `None` | Full config object; set `config.smart_crusher` / `config.cache_aligner` here to override compression/cache-alignment settings — there is no separate `smart_crusher_config`/`cache_aligner_config` constructor kwarg |
|
|
|
|
### Methods
|
|
|
|
#### `chat.completions.create(**kwargs)`
|
|
|
|
Create a chat completion with optional optimization.
|
|
|
|
```python
|
|
response = client.chat.completions.create(
|
|
model="gpt-4o",
|
|
messages=[...],
|
|
headroom_mode="optimize", # Override default mode
|
|
)
|
|
```
|
|
|
|
**Additional Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `headroom_mode` | `str` | Override mode for this request |
|
|
| `headroom_query` | `str` | Query for relevance scoring |
|
|
|
|
#### `chat.completions.simulate(**kwargs)`
|
|
|
|
Preview optimization without making an API call.
|
|
|
|
```python
|
|
plan = client.chat.completions.simulate(
|
|
model="gpt-4o",
|
|
messages=[...],
|
|
)
|
|
|
|
print(f"Tokens before: {plan.tokens_before}")
|
|
print(f"Tokens after: {plan.tokens_after}")
|
|
print(f"Savings: {plan.savings_percent:.1f}%")
|
|
```
|
|
|
|
**Returns:** `SimulationResult`
|
|
|
|
---
|
|
|
|
## Configuration Classes
|
|
|
|
### SmartCrusherConfig
|
|
|
|
```python
|
|
from headroom import SmartCrusherConfig
|
|
|
|
config = SmartCrusherConfig(
|
|
min_tokens_to_crush=200,
|
|
max_items_after_crush=50,
|
|
keep_first=3,
|
|
keep_last=2,
|
|
relevance_threshold=0.3,
|
|
anomaly_std_threshold=2.0,
|
|
preserve_errors=True,
|
|
)
|
|
```
|
|
|
|
### CacheAlignerConfig
|
|
|
|
```python
|
|
from headroom import CacheAlignerConfig
|
|
|
|
config = CacheAlignerConfig(
|
|
extract_dates=True,
|
|
normalize_whitespace=True,
|
|
stable_prefix_min_tokens=100,
|
|
)
|
|
```
|
|
|
|
### RelevanceScorerConfig
|
|
|
|
```python
|
|
from headroom import RelevanceScorerConfig
|
|
|
|
config = RelevanceScorerConfig(
|
|
scorer_type="bm25", # "bm25", "embedding", or "hybrid"
|
|
embedding_model=None, # Model name for embedding scorer
|
|
hybrid_alpha=0.5, # Weight for hybrid scoring
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Data Models
|
|
|
|
### SimulationResult
|
|
|
|
Returned by `simulate()`.
|
|
|
|
```python
|
|
@dataclass
|
|
class SimulationResult:
|
|
tokens_before: int
|
|
tokens_after: int
|
|
tokens_saved: int
|
|
savings_percent: float
|
|
transforms_applied: list[str]
|
|
waste_signals: WasteSignals
|
|
```
|
|
|
|
### RequestMetrics
|
|
|
|
Metrics for a single request.
|
|
|
|
```python
|
|
@dataclass
|
|
class RequestMetrics:
|
|
request_id: str
|
|
timestamp: datetime
|
|
model: str
|
|
tokens_input_before: int
|
|
tokens_input_after: int
|
|
tokens_output: int
|
|
cost_before: float
|
|
cost_after: float
|
|
transforms_applied: list[str]
|
|
```
|
|
|
|
### WasteSignals
|
|
|
|
Detected waste in the request.
|
|
|
|
```python
|
|
@dataclass
|
|
class WasteSignals:
|
|
json_bloat_tokens: int
|
|
html_noise_tokens: int
|
|
whitespace_tokens: int
|
|
dynamic_date_tokens: int
|
|
repetition_tokens: int
|
|
```
|
|
|
|
---
|
|
|
|
## Providers
|
|
|
|
### OpenAIProvider
|
|
|
|
```python
|
|
from headroom import OpenAIProvider
|
|
|
|
provider = OpenAIProvider()
|
|
|
|
# Get token counter
|
|
counter = provider.get_token_counter("gpt-4o")
|
|
tokens = counter.count_text("Hello, world!")
|
|
|
|
# Get context limit
|
|
limit = provider.get_context_limit("gpt-4o") # 128000
|
|
|
|
# Estimate cost
|
|
cost = provider.estimate_cost(
|
|
input_tokens=1000,
|
|
output_tokens=500,
|
|
model="gpt-4o",
|
|
)
|
|
```
|
|
|
|
### AnthropicProvider
|
|
|
|
```python
|
|
from headroom import AnthropicProvider
|
|
from anthropic import Anthropic
|
|
|
|
provider = AnthropicProvider(client=Anthropic())
|
|
|
|
counter = provider.get_token_counter("claude-3-5-sonnet-latest")
|
|
tokens = counter.count_messages(messages) # Accurate count via API
|
|
```
|
|
|
|
---
|
|
|
|
## Relevance Scoring
|
|
|
|
### BM25Scorer
|
|
|
|
Fast keyword-based scoring (zero dependencies).
|
|
|
|
```python
|
|
from headroom import BM25Scorer
|
|
|
|
scorer = BM25Scorer()
|
|
scores = scorer.score_items(
|
|
items=["item 1", "item 2", ...],
|
|
query="search query",
|
|
)
|
|
```
|
|
|
|
### EmbeddingScorer
|
|
|
|
Semantic similarity scoring (requires `sentence-transformers`).
|
|
|
|
```python
|
|
from headroom import EmbeddingScorer, embedding_available
|
|
|
|
if embedding_available():
|
|
scorer = EmbeddingScorer(model="all-MiniLM-L6-v2")
|
|
scores = scorer.score_items(items, query)
|
|
```
|
|
|
|
### HybridScorer
|
|
|
|
Combines BM25 and embeddings.
|
|
|
|
```python
|
|
from headroom import HybridScorer
|
|
|
|
scorer = HybridScorer(alpha=0.5) # 50% BM25, 50% embedding
|
|
scores = scorer.score_items(items, query)
|
|
```
|
|
|
|
### create_scorer()
|
|
|
|
Factory function to create scorers.
|
|
|
|
```python
|
|
from headroom import create_scorer
|
|
|
|
# Auto-select best available scorer
|
|
scorer = create_scorer()
|
|
|
|
# Explicitly choose type
|
|
scorer = create_scorer(scorer_type="hybrid", alpha=0.7)
|
|
```
|
|
|
|
---
|
|
|
|
## Transforms (Direct Use)
|
|
|
|
### SmartCrusher
|
|
|
|
```python
|
|
from headroom import SmartCrusher
|
|
|
|
crusher = SmartCrusher()
|
|
result = crusher.crush(
|
|
data={"results": [...]},
|
|
query="user query",
|
|
)
|
|
```
|
|
|
|
### CacheAligner
|
|
|
|
```python
|
|
from headroom import CacheAligner
|
|
|
|
aligner = CacheAligner()
|
|
result = aligner.align(messages)
|
|
```
|
|
|
|
> **Context management** is handled automatically inside the pipeline
|
|
> (live-zone-only compression). The position-based `RollingWindow` and
|
|
> score-based `IntelligentContextManager` / `MessageScorer` APIs have been
|
|
> removed and are no longer part of Headroom.
|
|
|
|
### TransformPipeline
|
|
|
|
```python
|
|
from headroom import TransformPipeline
|
|
|
|
pipeline = TransformPipeline(
|
|
[
|
|
SmartCrusher(),
|
|
CacheAligner(),
|
|
]
|
|
)
|
|
|
|
result = pipeline.transform(messages)
|
|
```
|
|
|
|
---
|
|
|
|
## Utilities
|
|
|
|
### Tokenizer
|
|
|
|
```python
|
|
from headroom import Tokenizer, count_tokens_text, count_tokens_messages
|
|
|
|
# Quick counting
|
|
tokens = count_tokens_text("Hello, world!", model="gpt-4o")
|
|
|
|
# With tokenizer instance
|
|
tokenizer = Tokenizer(model="gpt-4o")
|
|
tokens = tokenizer.count_text("Hello")
|
|
tokens = tokenizer.count_messages(messages)
|
|
```
|
|
|
|
### generate_report()
|
|
|
|
Generate an HTML report from stored metrics.
|
|
|
|
```python
|
|
from datetime import datetime, timedelta, timezone
|
|
from headroom import generate_report
|
|
|
|
path = generate_report(
|
|
store_url="sqlite:////absolute/path/to/headroom.db",
|
|
output_path="report.html",
|
|
start_time=datetime.now(timezone.utc) - timedelta(days=1),
|
|
) # returns the path to the generated HTML file
|
|
```
|
|
|
|
---
|
|
|
|
## TypeScript SDK
|
|
|
|
For the TypeScript SDK API reference, see [TypeScript SDK](typescript-sdk.md).
|
|
|
|
The TypeScript SDK provides `compress()`, `HeadroomClient`, and framework adapters for Vercel AI SDK, OpenAI, and Anthropic.
|