Meta tags:
description=Complete API reference for the Headroom Python and TypeScript SDKs. Core client, configuration types, result types, errors, and utilities.;

Headings (most frequently used words):

typescript, python, chat, completions, api, reference, core, configuration, results, providers, relevance, scoring, transforms, direct, use, errors, utilities, message, types, headroomclient, create, simulate, compress, get_stats, get_metrics, get_summary, validate_setup, smartcrusherconfig, cachealignerconfig, rollingwindowconfig, intelligentcontextconfig, scoringweights, headroomconfig, relevancescorerconfig, compressresult, simulationresult, wastesignals, requestmetrics, openaiprovider, anthropicprovider, googleprovider, create_scorer, bm25scorer, embeddingscorer, hybridscorer, smartcrusher, cachealigner, rollingwindow, intelligentcontextmanager, transformpipeline, tokenizer, generate_report, on, this, page,

Text of the page (most frequently used words):
number (39), headroom (36), from (31), import (27), type (24), int (23), prop (22), boolean (21), #typescript (20), true (19), python (18), string (16), config (16), messages (14), client (14), float (14), provider (13), the (13), bool (13), result (12), compression (11), model (11), api (10), enabled (10), tokenizer (9), gpt (9), scorer (9), str (9), compress (8), for (8), query (8), smartcrusher (7), scoringweights (7), intelligentcontextconfig (7), chat (7), and (7), openai (7), all (7), reference (7), rollingwindow (6), cachealigner (6), openaiprovider (6), rollingwindowconfig (6), cachealignerconfig (6), smartcrusherconfig (6), configuration (6), completions (6), headroomclient (6), sdk (6), with (6), tokens (6), failed (6), proxy (6), anthropic (6), message (5), errors (5), transforms (5), create_scorer (5), create (5), metrics (5), dict (5), plan (5), optimize (5), types (4), generate_report (4), transformpipeline (4), intelligentcontextmanager (4), use (4), hybridscorer (4), embeddingscorer (4), bm25scorer (4), relevance (4), scoring (4), googleprovider (4), anthropicprovider (4), results (4), headroomconfig (4), simulate (4), cache (4), optimization (4), issue (4), bm25 (4), counter (4), datetime (4), print (4), retries (4), fallback (4), timeout (4), baseurl (4), utilities (3), wastesignals (3), simulationresult (3), relevancescorerconfig (3), validate_setup (3), get_summary (3), get_metrics (3), get_stats (3), core (3), pipeline (3), transform (3), architecture (3), llm (3), simulation (3), stored (3), hello (3), context (3), database (3), class (3), use_importance_scoring (3), keep_last_turns (3), keep_system (3), max_tokens (3), score_items (3), items (3), scores (3), embedding (3), hybrid (3), list (3), transforms_applied (3), preserve_recent_turns (3), 100 (3), min_tokens_to_crush (3), returns (3), tokenbudget (3), const (3), apikey (3), your (3), direct (2), providers (2), requestmetrics (2), compressresult (2), how (2), works (2), execution (2), preview (2), without (2), making (2), call (2), cost (2), uses (2), standard (2), format (2), null (2), user (2), html (2), store_url (2), markdown (2), count_messages (2), count_text (2), world (2), count_tokens_text (2), quick (2), counting (2), validation (2), validationerror (2), storageerror (2), providererror (2), invalid (2), configurationerror (2), base (2), headroomerror (2), meaning (2), exception (2), error (2), failures (2), issues (2), 128000 (2), manager (2), apply (2), toin (2), 100000 (2), window (2), aligner (2), crusher (2), alpha (2), embedding_available (2), semantic (2), search (2), item (2), scorer_type (2), function (2), via (2), get_token_counter (2), limit (2), savings_percent (2), tokens_after (2), tokens_before (2), none (2), top (2), level (2), that (2), ccr (2), recency (2), toin_integration (2), scoring_weights (2), output_buffer_tokens (2), toinconfidencethreshold (2), outputbuffertokens (2), keeplastturns (2), keepsystem (2), drop_oldest_first (2), preserve_system (2), stable_prefix_min_tokens (2), normalize_whitespace (2), extract_dates (2), preserve_errors (2), anomaly_std_threshold (2), relevance_threshold (2), keep_last (2), keep_first (2), max_items_after_crush (2), timedelta (2), session (2), stats (2), 100_000 (2), http (2), localhost (2), 8787 (2), await (2), savings (2), headroom_tool_profiles (2), headroom_keep_turns (2), headroom_mode (2), audit (2), parameters (2), default_mode (2), original_client (2), complete (2), sdks (2), server (2), memory (2), reversible (2), this, page, three, stage, parsing, through, estimation, debugging, understanding, waste, signals, variants, toolmessage, assistantmessage, usermessage, systemmessage, tool_call_id, toolcall, tool_calls, contentpart, content, system, assistant, tool, role, day, period, sqlite, report, generate, reports, instance, count_tokens_messages, exceptions, include, additional, details, setup, rare, compressionerror, unknown, etc, values, convert, responses, correct, mapproxyerror, status, transformerror, operations, cacheerror, token, tokenizationerror, storage, includes, errortype, statuscode, headroomcompresserror, 401, headroomautherror, cannot, reach, headroomconnectionerror, model_limit, align, data, crush, combines, embeddings, minilm, similarity, requires, fast, keyword, based, zero, dependencies, explicitly, choose, auto, select, best, available, factory, scorers, enable_context_caching, accurate, count, claude, sonnet, latest, enable_cache_control, 500, output_tokens, 1000, input_tokens, estimate_cost, get_context_limit, enable_prefix_caching, cost_after, cost_before, tokens_output, tokens_input_after, tokens_input_before, timestamp, request_id, repetition_tokens, dynamic_date_tokens, whitespace_tokens, html_noise_tokens, json_bloat_tokens, waste_signals, tokens_saved, compressed, ccrhashes, transformsapplied, compressionratio, tokenssaved, tokensafter, tokensbefore, any, hybrid_alpha, embedding_model, relevancethreshold, adaptivealpha, hybridalpha, embeddingmodel, bm25b, bm25k1, relevancetier, tier, rolling_window, cache_aligner, smart_crusher, object, contains, sub, configurations, generatediffartifact, intelligentcontext, contentrouterenabled, prefixfreezeconfig, prefixfreeze, ccrconfig, cacheoptimizerconfig, cacheoptimizer, toolcrusherconfig, toolcrusher, record, modelcontextlimits, headroommode, defaultmode, storeurl, weights, are, automatically, normalized, sum, token_density, forward_reference, error_indicator, toin_importance, semantic_similarity, tokendensity, forwardreference, errorindicator, toinimportance, semanticsimilarity, 4000, compress_threshold, recency_decay_rate, summarizethreshold, summarymaxtokens, summarizationmodel, summarizationenabled, compressthreshold, toinintegration, recencydecayrate, useimportancescoring, dynamic_patterns, dynamictailseparator, collapseblanklines, normalizewhitespace, datepatterns, entropythreshold, extradynamiclabels, regex, ner, detectiontiers, usedynamicdetector, 200, relevance_tier, lastfraction, firstfraction, dedupidenticalitems, anchorconfig, anchor, usefeedbackhints, preservechangepoints, maxitemsaftercrush, similaritythreshold, uniquenessthreshold, variancethreshold, mintokenstocrush, minitemstoanalyze, valid, not, validate, configured, correctly, avg_compression_ratio, total_cost_saved_usd, total_requests, total_tokens_saved, summary, aggregate, statistics, across, hours, utcnow, start_time, keys, current, 15_000, compressionhooks, hooks, headroomclientinterface, skip_compression, important_tool, response, headroom_output_buffer_tokens, headroom_query, accepts, plus, specific, overrides, then, pass, before, sending, them, completion, optional, model_context_limits, enable_semantic_cache, enable_cache_optimizer, rolling_window_config, cache_aligner_config, smart_crusher_config, constructor, 30_000, key, new, main, entry, point, open, copy, troubleshooting, handling, help, limitations, benchmarks, monitoring, observability, mcp, tools, litellm, strands, agno, langchain, vercel, integrations, failure, learning, sharedcontext, persistent, management, text, log, image, code, community, installation, quickstart, introduction, getting, started,

Text of the page (random words):
api reference headroom headroom headroom search k getting started introduction quickstart installation community savings compression how compression works smartcrusher code compression image compression text log compression reversible compression reversible compression ccr cache context cache optimization context management memory persistent memory sharedcontext failure learning proxy server proxy server integrations vercel ai sdk openai sdk anthropic sdk langchain agno strands litellm mcp tools configuration configuration observability metrics monitoring simulation api reference api reference architecture architecture benchmarks limitations help error handling troubleshooting api reference api reference complete api reference for the headroom python and typescript sdks core client configuration types result types errors and utilities copy markdown open complete api reference for the headroom python and typescript sdks core headroomclient the main entry point for the headroom sdk typescript python prop type baseurl string apikey string timeout number fallback boolean retries number import headroomclient from headroom ai const client new headroomclient baseurl http localhost 8787 apikey your api key timeout 30_000 fallback true retries 2 constructor parameters prop type original_client openai anthropic provider provider default_mode audit optimize store_url str none smart_crusher_config smartcrusherconfig cache_aligner_config cachealignerconfig rolling_window_config rollingwindowconfig enable_cache_optimizer bool enable_semantic_cache bool model_context_limits dict str int from headroom import headroomclient openaiprovider from openai import openai client headroomclient original_client openai provider openaiprovider default_mode optimize chat completions create create a chat completion with optional optimization typescript python the typescript sdk uses compress to optimize messages before sending them to your llm client import compress from headroom ai const result await compress messages model gpt 4o tokenbudget 100_000 then pass result messages to your llm client accepts all standard openai anthropic parameters plus headroom specific overrides prop type headroom_mode audit optimize simulate headroom_query str headroom_output_buffer_tokens int headroom_keep_turns int headroom_tool_profiles dict response client chat completions create model gpt 4o messages headroom_mode optimize headroom_keep_turns 5 headroom_tool_profiles important_tool skip_compression true 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 savings_percent 1f print f transforms plan transforms_applied returns simulationresult compress typescript top level function to compress messages via the headroom proxy prop type model string baseurl string apikey string timeout number fallback boolean retries number client headroomclientinterface tokenbudget number hooks compressionhooks import compress from headroom ai const result await compress messages model gpt 4o baseurl http localhost 8787 timeout 15_000 fallback true retries 2 tokenbudget 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_saved avg_compression_ratio total_cost_saved_usd validate_setup validate that the client is configured correctly result client validate_setup if not result valid for issue in result issues print f issue configuration smartcrusherconfig typescript python prop type enabled boolean minitemstoanalyze number mintokenstocrush number variancethreshold number uniquenessthreshold number similaritythreshold number maxitemsaftercrush number preservechangepoints boolean usefeedbackhints boolean toinconfidencethreshold number relevance relevancescorerconfig anchor anchorconfig dedupidenticalitems boolean firstfraction number lastfraction number prop type min_tokens_to_crush int max_items_after_crush int keep_first int keep_last int relevance_threshold float anomaly_std_threshold float preserve_errors bool relevance_tier bm25 embedding hybrid 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 typescript python prop type enabled boolean usedynamicdetector boolean detectiontiers regex ner semantic extradynamiclabels string entropythreshold number datepatterns string normalizewhitespace boolean collapseblanklines boolean dynamictailseparator string prop type enabled bool extract_dates bool normalize_whitespace bool stable_prefix_min_tokens int dynamic_patterns list str from headroom import cachealignerconfig config cachealignerconfig enabled true extract_dates true normalize_whitespace true stable_prefix_min_tokens 100 rollingwindowconfig typescript python prop type enabled boolean keepsystem boolean keeplastturns number outputbuffertokens number prop type enabled bool max_tokens int preserve_system bool preserve_recent_turns int drop_oldest_first bool from headroom import rollingwindowconfig config rollingwindowconfig max_tokens 100000 preserve_system true preserve_recent_turns 5 drop_oldest_first true intelligentcontextconfig typescript python prop type enabled boolean keepsystem boolean keeplastturns number outputbuffertokens number useimportancescoring boolean scoringweights scoringweights recencydecayrate number toinintegration boolean toinconfidencethreshold number compressthreshold number summarizationenabled boolean summarizationmodel string null summarymaxtokens number summarizethreshold number prop type enabled bool keep_system bool keep_last_turns int output_buffer_tokens int use_importance_scoring bool scoring_weights scoringweights toin_integration bool recency_decay_rate float compress_threshold float from headroom config import intelligentcontextconfig scoringweights config intelligentcontextconfig enabled true keep_system true keep_last_turns 2 output_buffer_tokens 4000 use_importance_scoring true scoring_weights scoringweights toin_integration true scoringweights typescript python prop type recency number semanticsimilarity number toinimportance number errorindicator number forwardreference number tokendensity number prop type recency float semantic_similarity float toin_importance float error_indicator float forward_reference float token_density float weights are automatically normalized to sum to 1 0 headroomconfig typescript python prop type storeurl string defaultmode headroommode modelcontextlimits record string number toolcrusher toolcrusherconfig smartcrusher smartcrusherconfig cachealigner cachealignerconfig rollingwindow rollingwindowconfig cacheoptimizer cacheoptimizerconfig ccr ccrconfig prefixfreeze prefixfreezeconfig contentrouterenabled boolean intelligentcontext intelligentcontextconfig generatediffartifact boolean 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 config rolling_window preserve_recent_turns 3 relevancescorerconfig typescript python prop type tier relevancetier bm25k1 number bm25b number embeddingmodel string hybridalpha number adaptivealpha boolean relevancethreshold number prop type scorer_type bm25 embedding hybrid embedding_model str none hybrid_alpha float results compressresult typescript prop type messages any tokensbefore number tokensafter number tokenssaved number compressionratio number transformsapplied string ccrhashes string compressed boolean simulationresult python prop type tokens_before int tokens_after int tokens_saved int savings_percent float transforms_applied list str waste_signals wastesignals wastesignals python prop type json_bloat_tokens int html_noise_tokens int whitespace_tokens int dynamic_date_tokens int repetition_tokens int requestmetrics python prop type 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 providers openaiprovider from headroom import openaiprovider provider openaiprovider enable_prefix_caching true 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 enable_cache_control true counter provider get_token_counter claude 3 5 sonnet latest tokens counter count_messages messages accurate count via api googleprovider from headroom import googleprovider provider googleprovider enable_context_caching true 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 scorer_type hybrid alpha 0 7 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 headroom ai relevance 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 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 rollingwindow from headroom import rollingwindow window rollingwindow config result window apply messages max_tokens 100000 intelligentcontextmanager from headroom transforms import intelligentcontextmanager from headroom config import intelligentcontextconfig config intelligentcontextconfig keep_system true keep_last_turns 2 use_importance_scoring true manager intelligentcontextmanager config toin toin result manager apply messages tokenizer model_limit 128000 transformpipeline from headroom import transformpipeline pipeline transformpipeline smartcrusher cachealigner rollingwindow result pipeline transform messages errors typescript python 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 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 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 role system user assistant tool content string contentpart null tool_calls toolcall tool_call_id string the typescript sdk uses the standard openai message format with systemmessage usermessage assistantmessage and toolmessage variants simulation preview compression results without making an llm call use simulation for cost estimation debugging and understanding waste signals architecture how headroom s three stage compression pipeline works from message parsing through transform execution to provider cache optimization on this page core headroomclient chat completions create chat completions simulate compress typescript get_stats get_metrics get_summary validate_setup configuration smartcrusherconfig cachealignerconfig rollingwindowconfig intelligentcontextconfig scoringweights headroomconfig relevancescorerconfig results compressresult typescript simulationresult python wastesignals python requestmetrics python providers openaiprovider anthropicprovider googleprovider relevance scoring create_scorer bm25scorer embeddingscorer hybridscorer transforms direct use smartcrusher cachealigner rollingwindow intelligentcontextmanager transformpipeline errors utilities tokenizer generate_report typescript message types