Files
headroom/wiki/api.md
6cc0801219 docs: fix generate_report example arguments (#4435)
## 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>
2026-11-03 22:51:09 -06:00

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 RollingWindow and score-based IntelligentContextManager / MessageScorer APIs 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.