## 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>
7.1 KiB
API Reference
HeadroomClient
The main entry point for Headroom SDK.
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.
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.
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
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
from headroom import CacheAlignerConfig
config = CacheAlignerConfig(
extract_dates=True,
normalize_whitespace=True,
stable_prefix_min_tokens=100,
)
RelevanceScorerConfig
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().
@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.
@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.
@dataclass
class WasteSignals:
json_bloat_tokens: int
html_noise_tokens: int
whitespace_tokens: int
dynamic_date_tokens: int
repetition_tokens: int
Providers
OpenAIProvider
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
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).
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).
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.
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.
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
from headroom import SmartCrusher
crusher = SmartCrusher()
result = crusher.crush(
data={"results": [...]},
query="user query",
)
CacheAligner
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
RollingWindowand score-basedIntelligentContextManager/MessageScorerAPIs have been removed and are no longer part of Headroom.
TransformPipeline
from headroom import TransformPipeline
pipeline = TransformPipeline(
[
SmartCrusher(),
CacheAligner(),
]
)
result = pipeline.transform(messages)
Utilities
Tokenizer
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.
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.
The TypeScript SDK provides compress(), HeadroomClient, and framework adapters for Vercel AI SDK, OpenAI, and Anthropic.