Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
feat(sdk): support per-call config override in compress() (#3370)
Shubham Srivastavac3e8a1ee63f8
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.tsindex dbfa71fd6..79355eeba 100644--- a/sdk/typescript/src/client.ts+++ b/sdk/typescript/src/client.ts@@ -19,7 +19,7 @@ import type {import { mapProxyError, HeadroomConnectionError, HeadroomAuthError, HeadroomCompressError } from "./errors.js";import { deepCamelCase, deepSnakeCase } from "./utils/case.js";import { parseSSE } from "./utils/stream.js";-import type { HeadroomConfig, HeadroomMode } from "./types/config.js";+import type { CompressRequestConfig, HeadroomMode } from "./types/config.js";import type {SimulationResult,RequestMetrics,@@ -191,7 +191,7 @@ class Messages {export interface ExtendedClientOptions extends HeadroomClientOptions {providerApiKey?: string;defaultMode?: HeadroomMode;- config?: HeadroomConfig;+ config?: CompressRequestConfig;}export class HeadroomClient implements HeadroomClientInterface {@@ -200,7 +200,7 @@ export class HeadroomClient implements HeadroomClientInterface {private timeout: number;private fallback: boolean;private retries: number;- private config: HeadroomConfig | undefined;+ private config: CompressRequestConfig | undefined;private stack: string | undefined;/** @internal */ providerApiKey: string | undefined;@@ -234,7 +234,7 @@ export class HeadroomClient implements HeadroomClientInterface {async compress(messages: OpenAIMessage[],- options: { model?: string; tokenBudget?: number } = {},+ options: { model?: string; tokenBudget?: number; config?: CompressRequestConfig } = {},): Promise<CompressResult> {const model = options.model ?? "gpt-4o";@@ -243,7 +243,7 @@ export class HeadroomClient implements HeadroomClientInterface {for (let attempt = 0; attempt < maxAttempts; attempt++) {try {- return await this._doCompress(messages, model, options.tokenBudget);+ return await this._doCompress(messages, model, options.tokenBudget, options.config);} catch (error) {lastError = error;if (error instanceof HeadroomAuthError) throw error;@@ -569,13 +569,15 @@ export class HeadroomClient implements HeadroomClientInterface {messages: OpenAIMessage[],model: string,tokenBudget?: number,+ config?: CompressRequestConfig,): Promise<CompressResult> {const body: Record<string, unknown> = { messages, model };if (tokenBudget) {body.token_budget = tokenBudget;}- if (this.config) {- body.config = deepSnakeCase(this.config);+ const mergedConfig = { ...this.config, ...config };+ if (Object.keys(mergedConfig).length > 0) {+ body.config = deepSnakeCase(mergedConfig);}const response = await this._fetch("/v1/compress", {diff --git a/sdk/typescript/src/compress.ts b/sdk/typescript/src/compress.tsindex 935cb9e26..23bf50e05 100644--- a/sdk/typescript/src/compress.ts+++ b/sdk/typescript/src/compress.ts@@ -25,6 +25,7 @@ export async function compress(model,tokenBudget,hooks,+ config,...clientOptions} = options;@@ -57,7 +58,7 @@ export async function compress(// 5. Compress via proxyconst client = providedClient ?? new HeadroomClient(clientOptions);- const result = await client.compress(openaiMessages, { model, tokenBudget });+ const result = await client.compress(openaiMessages, { model, tokenBudget, config });// 6. Convert compressed messages back to original formatconst outputMessages = fromOpenAI(result.messages, inputFormat);diff --git a/sdk/typescript/src/index.ts b/sdk/typescript/src/index.tsindex 5b74b7437..a888e4cac 100644--- a/sdk/typescript/src/index.ts+++ b/sdk/typescript/src/index.ts@@ -51,6 +51,8 @@ export {// --- Config types ---export type {HeadroomMode,+ CompressMode,+ CompressRequestConfig,RelevanceTier,ContentType,BlockKind,diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.tsindex a0dc91883..aef505aad 100644--- a/sdk/typescript/src/types.ts+++ b/sdk/typescript/src/types.ts@@ -4,6 +4,7 @@*/import type { CompressionHooks } from "./hooks.js";+import type { CompressRequestConfig } from "./types/config.js";// --- Message types (OpenAI chat format) ---@@ -69,6 +70,9 @@ export interface CompressOptions {hooks?: CompressionHooks;/** Integration slug sent as X-Headroom-Stack (e.g. "adapter_ts_openai"). */stack?: string;+ /** Per-call /v1/compress config, merged over the client-level config+ * (per-call keys override at the top level). */+ config?: CompressRequestConfig;}export interface CompressResult {@@ -103,7 +107,7 @@ export interface HeadroomClientOptions {export interface HeadroomClientInterface {compress(messages: OpenAIMessage[],- options?: { model?: string; tokenBudget?: number },+ options?: { model?: string; tokenBudget?: number; config?: CompressRequestConfig },): Promise<CompressResult>;}diff --git a/sdk/typescript/src/types/config.ts b/sdk/typescript/src/types/config.tsindex bd596d419..adee140ea 100644--- a/sdk/typescript/src/types/config.ts+++ b/sdk/typescript/src/types/config.ts@@ -7,6 +7,30 @@export type HeadroomMode = "audit" | "optimize" | "simulate";+/** Pipeline mode accepted by POST /v1/compress. Unset = default marker-free+ * pipeline. Any other value is rejected (400) by the proxy. */+export type CompressMode = "ccr" | "lossy_inline" | "lossless_then_lossy";++/** Config accepted by the POST /v1/compress endpoint. camelCase keys are+ * snake_cased on the wire (e.g. targetRatio -> target_ratio). Every field is+ * optional; only these keys are honored by the endpoint. */+export interface CompressRequestConfig {+ /** Compression pipeline mode (unset = default marker-free pipeline). */+ mode?: CompressMode;+ /** Target keep-ratio (0–1) for lossy compression. -> target_ratio */+ targetRatio?: number;+ /** Also compress user-role messages (default false). -> compress_user_messages */+ compressUserMessages?: boolean;+ /** Number of most-recent messages to protect from compression. -> protect_recent */+ protectRecent?: number;+ /** Protect analysis/reasoning context from compression. -> protect_analysis_context */+ protectAnalysisContext?: boolean;+ /** Freeze the first N messages (prefix) from compression. -> frozen_message_count */+ frozenMessageCount?: number;+ /** Session id for session-aware compression. -> session_id */+ sessionId?: string;+}+export type RelevanceTier = "bm25" | "embedding" | "hybrid";export type ContentType =diff --git a/sdk/typescript/test/client.test.ts b/sdk/typescript/test/client.test.tsindex 0f5cc48cf..b5997ca8e 100644--- a/sdk/typescript/test/client.test.ts+++ b/sdk/typescript/test/client.test.ts@@ -263,4 +263,48 @@ describe("HeadroomClient", () => {const body = JSON.parse(mockFetch.mock.calls[0][1].body);expect(body.model).toBe("gpt-4o");});++ it("sends a per-call config (snake_cased) in the request body", async () => {+ mockFetch.mockResolvedValueOnce(okResponse(sampleProxyResponse));+ const client = new HeadroomClient({ baseUrl: "http://localhost:8787" });++ await client.compress(sampleMessages, {+ model: "gpt-4o",+ config: { mode: "ccr", targetRatio: 0.3, compressUserMessages: true },+ });++ const [, opts] = mockFetch.mock.calls[0];+ const body = JSON.parse(opts.body);+ expect(body.config.mode).toBe("ccr");+ expect(body.config.target_ratio).toBe(0.3);+ expect(body.config.compress_user_messages).toBe(true);+ });++ it("per-call config overrides client-level config", async () => {+ mockFetch.mockResolvedValueOnce(okResponse(sampleProxyResponse));+ const client = new HeadroomClient({+ baseUrl: "http://localhost:8787",+ config: { mode: "lossy_inline" },+ });++ await client.compress(sampleMessages, {+ model: "gpt-4o",+ config: { mode: "ccr" },+ });++ const [, opts] = mockFetch.mock.calls[0];+ const body = JSON.parse(opts.body);+ expect(body.config.mode).toBe("ccr");+ });++ it("omits the config key when neither client nor call sets config", async () => {+ mockFetch.mockResolvedValueOnce(okResponse(sampleProxyResponse));+ const client = new HeadroomClient({ baseUrl: "http://localhost:8787" });++ await client.compress(sampleMessages, { model: "gpt-4o" });++ const [, opts] = mockFetch.mock.calls[0];+ const body = JSON.parse(opts.body);+ expect(body.config).toBeUndefined();+ });});diff --git a/sdk/typescript/test/compress.test.ts b/sdk/typescript/test/compress.test.tsindex 69a741bd2..0bddcce16 100644--- a/sdk/typescript/test/compress.test.ts+++ b/sdk/typescript/test/compress.test.ts@@ -1,5 +1,6 @@import { describe, it, expect, vi, beforeEach } from "vitest";import { compress } from "../src/compress.js";+import { HeadroomClient } from "../src/client.js";import type { OpenAIMessage } from "../src/types.js";const mockFetch = vi.fn();@@ -115,4 +116,22 @@ describe("compress()", () => {const body = JSON.parse(mockFetch.mock.calls[0][1].body);expect(body.messages).toHaveLength(5);});++ it("forwards a per-call config, overriding a provided client's config", async () => {+ mockFetch.mockResolvedValueOnce(okResponse());+ const client = new HeadroomClient({+ baseUrl: "http://localhost:8787",+ config: { mode: "lossy_inline" },+ });++ await compress([{ role: "user", content: "hello" }], {+ client,+ config: { mode: "ccr", targetRatio: 0.25 },+ });++ const [, opts] = mockFetch.mock.calls[0];+ const body = JSON.parse(opts.body);+ expect(body.config.mode).toBe("ccr");+ expect(body.config.target_ratio).toBe(0.25);+ });});