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,
});

Constructor Parameters

Prop

Type

from headroom import HeadroomClient, OpenAIProvider, HeadroomConfig, SmartCrusherConfig, CacheAlignerConfig
from openai import OpenAI

client = HeadroomClient(
    original_client=OpenAI(),
    provider=OpenAIProvider(),
    default_mode="optimize",
    config=HeadroomConfig(
        smart_crusher=SmartCrusherConfig(min_tokens_to_crush=100),
        cache_aligner=CacheAlignerConfig(enabled=True),
    ),
)

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 client

Accepts all standard OpenAI/Anthropic parameters plus Headroom-specific overrides:

Prop

Type

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    headroom_mode="optimize",
    headroom_keep_turns=5,
)

headroom_tool_profiles has no effect in 0.37.0

headroom_tool_profiles is accepted but not currently wired through TransformPipeline.apply(), so passing it changes nothing. To keep specific tool outputs from being compressed as aggressively, use config.smart_crusher.max_items_after_crush or config.smart_crusher.enabled = False instead — see Compression Too Aggressive.

chat.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" keys

get_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_count

validate_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

Prop

Type

from headroom import SmartCrusherConfig

config = SmartCrusherConfig(
    min_tokens_to_crush=200,
    max_items_after_crush=15,
    variance_threshold=2.0,
    preserve_change_points=True,
)

CacheAlignerConfig

Prop

Type

Prop

Type

from headroom import CacheAlignerConfig

config = CacheAlignerConfig(
    enabled=True,
    use_dynamic_detector=True,
    normalize_whitespace=True,
    entropy_threshold=0.7,
)

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

The top-level config object that contains all sub-configurations:

from headroom import HeadroomConfig

config = HeadroomConfig()
config.smart_crusher.min_tokens_to_crush = 100
config.cache_aligner.enabled = True
# Note: rolling_window has been removed — use headroom_keep_turns per-request instead

RelevanceScorerConfig

Prop

Type

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 API

GoogleProvider

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.

Exception	Meaning
`HeadroomError`	Base class for all Headroom errors
`ConfigurationError`	Invalid config values
`ProviderError`	Provider issue (unknown model, etc.)
`StorageError`	Database issue
`CompressionError`	Compression failed (rare)
`ValidationError`	Setup validation failed

All exceptions include a details dict with additional context.

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.

On this page