API Reference
Complete API reference for the Headroom Python and TypeScript SDKs. Core client, configuration types, result types, errors, and utilities.
Complete API reference for the Headroom Python and TypeScript SDKs.
Core
HeadroomClient
The main entry point for the Headroom SDK.
Prop
Type
import { } from 'headroom-ai';
const = new ({
: 'http://localhost:8787',
: 'your-api-key',
: 30_000,
: true,
: 2,
});chat.completions.create()
Create a chat completion with optional optimization.
The TypeScript SDK uses compress() to optimize messages before sending them to your LLM client:
import { } from 'headroom-ai';
const = await (messages, {
: 'gpt-4o',
: 100_000,
});
// Then pass result.messages to your LLM clientchat.completions.simulate()
Preview optimization without making an API call.
plan = client.chat.completions.simulate(
model="gpt-4o",
messages=[...],
)
print(f"Tokens: {plan.tokens_before} -> {plan.tokens_after}")
print(f"Savings: {plan.tokens_saved/plan.tokens_before*100:.1f}%")
print(f"Transforms: {plan.transforms}")Returns: SimulationResult
compress() (TypeScript)
Top-level function to compress messages via the Headroom proxy.
Prop
Type
import { } from 'headroom-ai';
const = await (messages, {
: 'gpt-4o',
: 'http://localhost:8787',
: 15_000,
: true,
: 2,
: 100_000,
});get_stats()
Quick stats for the current session (no database query).
stats = client.get_stats()
# Returns dict with "session", "config", and "transforms" keysget_metrics()
Query stored metrics from the database.
from datetime import datetime, timedelta
metrics = client.get_metrics(
start_time=datetime.utcnow() - timedelta(hours=1),
limit=100,
)get_summary()
Aggregate statistics across all stored metrics.
summary = client.get_summary()
# Returns dict with total_requests, total_tokens_before, total_tokens_after,
# total_tokens_saved, avg_tokens_saved, avg_cache_alignment,
# audit_count, optimize_countvalidate_setup()
Validate that the client is configured correctly.
result = client.validate_setup()
# Returns {"valid": bool, "provider": {...}, "storage": {...},
# "config": {...}, "cache_optimizer": {...}}, each with "ok"/"error"
if not result["valid"]:
for key in ("provider", "storage", "config", "cache_optimizer"):
if not result[key]["ok"]:
print(f" - {key}: {result[key]['error']}")Configuration
SmartCrusherConfig
Prop
Type
CacheAlignerConfig
Prop
Type
Context management
Context management is now handled automatically inside the pipeline (live-zone-only compression). Headroom never drops messages from the conversation history; it compresses only the newest content blocks (latest user message, latest tool result) and keeps the cache hot zone — system prompt, tools, and older turns — untouched. Use the headroom_keep_turns / headroom_output_buffer_tokens per-request overrides to tune behavior. The RollingWindowConfig, IntelligentContextConfig, and ScoringWeights classes have been retired from the Python package (from headroom import RollingWindowConfig fails) and from the compression pipeline itself; the TypeScript SDK's HeadroomConfig type still exports the equivalent field names as unused legacy type surface, wired to nothing.
HeadroomConfig
Prop
Type
RelevanceScorerConfig
Prop
Type
Results
CompressResult (TypeScript)
Prop
Type
SimulationResult (Python)
Prop
Type
WasteSignals (Python)
plan.waste_signals is a plain dict[str, int], not a class instance:
Prop
Type
RequestMetrics (Python)
Prop
Type
Cost estimates are computed on demand inside HeadroomClient (estimate_cost() on the provider) rather than stored on RequestMetrics.
Providers
OpenAIProvider
from headroom import OpenAIProvider
provider = OpenAIProvider()
counter = provider.get_token_counter("gpt-4o")
tokens = counter.count_text("Hello, world!")
limit = provider.get_context_limit("gpt-4o") # 128000
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 APIGoogleProvider
from headroom.providers import GoogleProvider
provider = GoogleProvider()Relevance Scoring
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(tier="hybrid", alpha=0.7)BM25Scorer
Fast keyword-based scoring (zero dependencies):
from headroom import BM25Scorer
scorer = BM25Scorer()
scores = scorer.score_batch(["item 1", "item 2"], "search query")EmbeddingScorer
Semantic similarity scoring (requires headroom-ai[relevance]):
from headroom import EmbeddingScorer, embedding_available
if embedding_available():
scorer = EmbeddingScorer(model_name="BAAI/bge-small-en-v1.5")
scores = scorer.score_batch(items, query)HybridScorer
Combines BM25 and embeddings:
from headroom import HybridScorer
scorer = HybridScorer(alpha=0.5) # 50% BM25, 50% embedding
scores = scorer.score_batch(items, query)Transforms (Direct Use)
SmartCrusher
from headroom import SmartCrusher
import json
crusher = SmartCrusher()
result = crusher.crush(content=json.dumps({"results": [...]}), query="user query")CacheAligner
from headroom import CacheAligner, Tokenizer, OpenAIProvider
provider = OpenAIProvider()
tokenizer = Tokenizer(provider.get_token_counter("gpt-4o"), "gpt-4o")
aligner = CacheAligner()
result = aligner.apply(messages, tokenizer)TransformPipeline
from headroom import TransformPipeline, SmartCrusher, CacheAligner
pipeline = TransformPipeline(transforms=[
SmartCrusher(),
CacheAligner(),
])
# model_limit is required for direct pipeline use — HeadroomClient
# supplies it automatically from the provider's context limits
result = pipeline.apply(messages, "gpt-4o", model_limit=128_000)Errors
| Exception | Meaning |
|---|---|
HeadroomError | Base class for all errors |
HeadroomConnectionError | Cannot reach proxy |
HeadroomAuthError | 401 from proxy |
HeadroomCompressError | Compression failed (includes statusCode, errorType) |
ConfigurationError | Invalid configuration |
ProviderError | Provider issues |
StorageError | Storage failures |
TokenizationError | Token counting failed |
CacheError | Cache operations failed |
ValidationError | Validation failures |
TransformError | Transform execution failed |
Use mapProxyError(status, type, message) to convert proxy error responses to the correct class.
Utilities
Tokenizer
from headroom import Tokenizer, count_tokens_text, count_tokens_messages, OpenAIProvider
provider = OpenAIProvider()
token_counter = provider.get_token_counter("gpt-4o")
# Quick counting
tokens = count_tokens_text("Hello, world!", token_counter)
# With tokenizer instance
tokenizer = Tokenizer(token_counter, "gpt-4o")
tokens = tokenizer.count_text("Hello")
tokens = tokenizer.count_messages(messages)generate_report()
Generate HTML/Markdown reports from stored metrics:
from headroom import generate_report
report = generate_report(
store_url="sqlite:///headroom.db",
format="html",
period="day",
)TypeScript Message Types
Prop
Type
The TypeScript SDK uses the standard OpenAI message format with SystemMessage, UserMessage, AssistantMessage, and ToolMessage variants.