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

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.