mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
Deployed 55579445 with MkDocs version: 1.6.1
This commit is contained in:
parent
2889707c54
commit
54aaf78976
128 changed files with 81945 additions and 55076 deletions
78
404.html
78
404.html
|
|
@ -217,7 +217,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/index.md" class="md-tabs__link">
|
||||
<a href="/headroom/." class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -238,7 +238,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/quickstart.md" class="md-tabs__link">
|
||||
<a href="/headroom/quickstart/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -260,7 +260,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/proxy.md" class="md-tabs__link">
|
||||
<a href="/headroom/proxy/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -282,7 +282,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/integration-guide.md" class="md-tabs__link">
|
||||
<a href="/headroom/integration-guide/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -304,7 +304,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/ARCHITECTURE.md" class="md-tabs__link">
|
||||
<a href="/headroom/ARCHITECTURE/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -326,7 +326,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/benchmarks.md" class="md-tabs__link">
|
||||
<a href="/headroom/benchmarks/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -348,7 +348,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/cli.md" class="md-tabs__link">
|
||||
<a href="/headroom/cli/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -370,7 +370,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="/headroom/macos-deployment.md" class="md-tabs__link">
|
||||
<a href="/headroom/macos-deployment/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -442,7 +442,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/index.md" class="md-nav__link">
|
||||
<a href="/headroom/." class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -535,7 +535,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/quickstart.md" class="md-nav__link">
|
||||
<a href="/headroom/quickstart/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -563,7 +563,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/getting-started.md" class="md-nav__link">
|
||||
<a href="/headroom/getting-started/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -591,7 +591,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/docker-install.md" class="md-nav__link">
|
||||
<a href="/headroom/docker-install/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -619,7 +619,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/persistent-installs.md" class="md-nav__link">
|
||||
<a href="/headroom/persistent-installs/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -647,7 +647,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/configuration.md" class="md-nav__link">
|
||||
<a href="/headroom/configuration/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -752,7 +752,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/proxy.md" class="md-nav__link">
|
||||
<a href="/headroom/proxy/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -780,7 +780,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/compression.md" class="md-nav__link">
|
||||
<a href="/headroom/compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -808,7 +808,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/ccr.md" class="md-nav__link">
|
||||
<a href="/headroom/ccr/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -836,7 +836,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/image-compression.md" class="md-nav__link">
|
||||
<a href="/headroom/image-compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -864,7 +864,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/memory.md" class="md-nav__link">
|
||||
<a href="/headroom/memory/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -892,7 +892,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/shared-context.md" class="md-nav__link">
|
||||
<a href="/headroom/shared-context/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -920,7 +920,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/learn.md" class="md-nav__link">
|
||||
<a href="/headroom/learn/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1021,7 +1021,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/integration-guide.md" class="md-nav__link">
|
||||
<a href="/headroom/integration-guide/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1049,7 +1049,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/langchain.md" class="md-nav__link">
|
||||
<a href="/headroom/langchain/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1077,7 +1077,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/agno.md" class="md-nav__link">
|
||||
<a href="/headroom/agno/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1105,7 +1105,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/strands.md" class="md-nav__link">
|
||||
<a href="/headroom/strands/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1133,7 +1133,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/mcp.md" class="md-nav__link">
|
||||
<a href="/headroom/mcp/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1232,7 +1232,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/ARCHITECTURE.md" class="md-nav__link">
|
||||
<a href="/headroom/ARCHITECTURE/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1260,7 +1260,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/transforms.md" class="md-nav__link">
|
||||
<a href="/headroom/transforms/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1288,7 +1288,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/text-compression.md" class="md-nav__link">
|
||||
<a href="/headroom/text-compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1413,7 +1413,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/benchmarks.md" class="md-nav__link">
|
||||
<a href="/headroom/benchmarks/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1441,7 +1441,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/LATENCY_BENCHMARKS.md" class="md-nav__link">
|
||||
<a href="/headroom/LATENCY_BENCHMARKS/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1469,7 +1469,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/LIMITATIONS.md" class="md-nav__link">
|
||||
<a href="/headroom/LIMITATIONS/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1572,7 +1572,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/cli.md" class="md-nav__link">
|
||||
<a href="/headroom/cli/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1600,7 +1600,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/api.md" class="md-nav__link">
|
||||
<a href="/headroom/api/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1628,7 +1628,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/sdk.md" class="md-nav__link">
|
||||
<a href="/headroom/sdk/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1656,7 +1656,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/metrics.md" class="md-nav__link">
|
||||
<a href="/headroom/metrics/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1684,7 +1684,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/errors.md" class="md-nav__link">
|
||||
<a href="/headroom/errors/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1712,7 +1712,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/troubleshooting.md" class="md-nav__link">
|
||||
<a href="/headroom/troubleshooting/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1805,7 +1805,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="/headroom/macos-deployment.md" class="md-nav__link">
|
||||
<a href="/headroom/macos-deployment/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
4350
ARCHITECTURE/index.html
Normal file
4350
ARCHITECTURE/index.html
Normal file
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
3355
agno/index.html
Normal file
3355
agno/index.html
Normal file
File diff suppressed because it is too large
Load diff
3310
api/index.html
Normal file
3310
api/index.html
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -1,6 +0,0 @@
|
|||
import { HomeLayout } from 'fumadocs-ui/layouts/home';
|
||||
import { baseOptions } from '@/lib/layout.shared';
|
||||
|
||||
export default function Layout({ children }: LayoutProps<'/'>) {
|
||||
return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
|
||||
}
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
import { redirect } from 'next/navigation';
|
||||
|
||||
export default function HomePage() {
|
||||
redirect('/docs');
|
||||
}
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
import { source } from '@/lib/source';
|
||||
import { createFromSource } from 'fumadocs-core/search/server';
|
||||
|
||||
export const { GET } = createFromSource(source, {
|
||||
// https://docs.orama.com/docs/orama-js/supported-languages
|
||||
language: 'english',
|
||||
});
|
||||
|
|
@ -1,63 +0,0 @@
|
|||
import { getPageImage, getPageMarkdownUrl, source } from '@/lib/source';
|
||||
import {
|
||||
DocsBody,
|
||||
DocsDescription,
|
||||
DocsPage,
|
||||
DocsTitle,
|
||||
MarkdownCopyButton,
|
||||
ViewOptionsPopover,
|
||||
} from 'fumadocs-ui/layouts/docs/page';
|
||||
import { notFound } from 'next/navigation';
|
||||
import { getMDXComponents } from '@/components/mdx';
|
||||
import type { Metadata } from 'next';
|
||||
import { createRelativeLink } from 'fumadocs-ui/mdx';
|
||||
import { gitConfig } from '@/lib/shared';
|
||||
|
||||
export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
|
||||
const params = await props.params;
|
||||
const page = source.getPage(params.slug);
|
||||
if (!page) notFound();
|
||||
|
||||
const MDX = page.data.body;
|
||||
const markdownUrl = getPageMarkdownUrl(page).url;
|
||||
|
||||
return (
|
||||
<DocsPage toc={page.data.toc} full={page.data.full}>
|
||||
<DocsTitle>{page.data.title}</DocsTitle>
|
||||
<DocsDescription className="mb-0">{page.data.description}</DocsDescription>
|
||||
<div className="flex flex-row gap-2 items-center border-b pb-6">
|
||||
<MarkdownCopyButton markdownUrl={markdownUrl} />
|
||||
<ViewOptionsPopover
|
||||
markdownUrl={markdownUrl}
|
||||
githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/content/docs/${page.path}`}
|
||||
/>
|
||||
</div>
|
||||
<DocsBody>
|
||||
<MDX
|
||||
components={getMDXComponents({
|
||||
// this allows you to link to other pages with relative file paths
|
||||
a: createRelativeLink(source, page),
|
||||
})}
|
||||
/>
|
||||
</DocsBody>
|
||||
</DocsPage>
|
||||
);
|
||||
}
|
||||
|
||||
export async function generateStaticParams() {
|
||||
return source.generateParams();
|
||||
}
|
||||
|
||||
export async function generateMetadata(props: PageProps<'/docs/[[...slug]]'>): Promise<Metadata> {
|
||||
const params = await props.params;
|
||||
const page = source.getPage(params.slug);
|
||||
if (!page) notFound();
|
||||
|
||||
return {
|
||||
title: page.data.title,
|
||||
description: page.data.description,
|
||||
openGraph: {
|
||||
images: getPageImage(page).url,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
import { source } from '@/lib/source';
|
||||
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
|
||||
import { baseOptions } from '@/lib/layout.shared';
|
||||
|
||||
export default function Layout({ children }: LayoutProps<'/docs'>) {
|
||||
return (
|
||||
<DocsLayout tree={source.getPageTree()} {...baseOptions()}>
|
||||
{children}
|
||||
</DocsLayout>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
@import 'tailwindcss';
|
||||
@import 'fumadocs-ui/css/neutral.css';
|
||||
@import 'fumadocs-ui/css/preset.css';
|
||||
@import 'fumadocs-twoslash/twoslash.css';
|
||||
|
||||
@theme {
|
||||
--color-fd-background: hsl(0, 0%, 98%);
|
||||
--color-fd-foreground: hsl(0, 0%, 3.9%);
|
||||
--color-fd-muted: hsl(0, 0%, 96.1%);
|
||||
--color-fd-muted-foreground: hsl(0, 0%, 45.1%);
|
||||
--color-fd-popover: hsl(0, 0%, 100%);
|
||||
--color-fd-popover-foreground: hsl(0, 0%, 15.1%);
|
||||
--color-fd-card: hsl(0, 0%, 99.7%);
|
||||
--color-fd-card-foreground: hsl(0, 0%, 3.9%);
|
||||
--color-fd-border: hsla(0, 0%, 60%, 0.2);
|
||||
--color-fd-primary: hsl(0, 0%, 9%);
|
||||
--color-fd-primary-foreground: hsl(0, 0%, 98%);
|
||||
--color-fd-secondary: hsl(0, 0%, 96.1%);
|
||||
--color-fd-secondary-foreground: hsl(0, 0%, 9%);
|
||||
--color-fd-accent: hsl(0, 0%, 94.1%);
|
||||
--color-fd-accent-foreground: hsl(0, 0%, 9%);
|
||||
--color-fd-ring: hsl(0, 0%, 63.9%);
|
||||
--color-purple: hsl(262, 52%, 56%);
|
||||
}
|
||||
|
||||
.dark {
|
||||
--color-fd-background: hsl(0, 0%, 2%);
|
||||
--color-fd-foreground: hsl(0, 0%, 98%);
|
||||
--color-fd-muted: hsl(0, 0%, 8%);
|
||||
--color-fd-muted-foreground: hsl(0, 0%, 60%);
|
||||
--color-fd-popover: hsl(0, 0%, 4%);
|
||||
--color-fd-popover-foreground: hsl(0, 0%, 98%);
|
||||
--color-fd-card: hsl(0, 0%, 4%);
|
||||
--color-fd-card-foreground: hsl(0, 0%, 98%);
|
||||
--color-fd-border: hsl(0, 0%, 50%, 0.2);
|
||||
--color-fd-primary: hsl(0, 0%, 98%);
|
||||
--color-fd-primary-foreground: hsl(0, 0%, 9%);
|
||||
--color-fd-secondary: hsl(0, 0%, 12.9%);
|
||||
--color-fd-secondary-foreground: hsl(0, 0%, 98%);
|
||||
--color-fd-accent: hsl(0, 0%, 15%);
|
||||
--color-fd-accent-foreground: hsl(0, 0%, 100%);
|
||||
--color-fd-ring: hsl(0, 0%, 34.9%);
|
||||
--color-purple: hsl(262, 60%, 65%);
|
||||
}
|
||||
|
||||
html {
|
||||
scrollbar-gutter: stable;
|
||||
}
|
||||
|
||||
html > body[data-scroll-locked] {
|
||||
margin-right: 0px !important;
|
||||
--removed-body-scroll-bar-size: 0px !important;
|
||||
}
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
import { RootProvider } from 'fumadocs-ui/provider/next';
|
||||
import './global.css';
|
||||
import { Inter } from 'next/font/google';
|
||||
import type { Metadata } from 'next';
|
||||
|
||||
const inter = Inter({
|
||||
subsets: ['latin'],
|
||||
});
|
||||
|
||||
// Canonical URL for the live docs. ``metadataBase`` resolves the og:url
|
||||
// and twitter:url for every page; pointing it at the actual live site
|
||||
// is what lets crawlers (search + LLM) follow the right canonical and
|
||||
// pick up ``/llms.txt`` / ``/sitemap.xml`` / og images. Override at
|
||||
// build time via ``NEXT_PUBLIC_SITE_URL`` (e.g. when promoting to a
|
||||
// custom domain).
|
||||
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://headroom-docs.vercel.app';
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: {
|
||||
default: 'Headroom — Context Optimization Layer for AI Agents',
|
||||
template: '%s | Headroom',
|
||||
},
|
||||
description:
|
||||
'Compress everything your AI agent reads — tool outputs, logs, files, RAG chunks. Same answers, fraction of the tokens. Library, proxy, MCP server. Local-first. Apache 2.0.',
|
||||
metadataBase: new URL(SITE_URL),
|
||||
alternates: {
|
||||
canonical: '/',
|
||||
},
|
||||
openGraph: {
|
||||
type: 'website',
|
||||
siteName: 'Headroom',
|
||||
title: 'Headroom — Context Optimization Layer for AI Agents',
|
||||
description:
|
||||
'Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60–95% fewer tokens, same answers.',
|
||||
url: '/',
|
||||
},
|
||||
twitter: {
|
||||
card: 'summary_large_image',
|
||||
title: 'Headroom — Context Optimization Layer for AI Agents',
|
||||
description:
|
||||
'Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60–95% fewer tokens, same answers.',
|
||||
},
|
||||
};
|
||||
|
||||
export default function Layout({ children }: LayoutProps<'/'>) {
|
||||
return (
|
||||
<html lang="en" className={inter.className} suppressHydrationWarning>
|
||||
<body className="flex flex-col min-h-screen">
|
||||
<RootProvider>{children}</RootProvider>
|
||||
</body>
|
||||
</html>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
import { getLLMText, source } from '@/lib/source';
|
||||
|
||||
export const revalidate = false;
|
||||
|
||||
export async function GET() {
|
||||
const scan = source.getPages().map(getLLMText);
|
||||
const scanned = await Promise.all(scan);
|
||||
|
||||
return new Response(scanned.join('\n\n'));
|
||||
}
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
import { getLLMText, getPageMarkdownUrl, source } from '@/lib/source';
|
||||
import { notFound } from 'next/navigation';
|
||||
|
||||
export const revalidate = false;
|
||||
|
||||
export async function GET(_req: Request, { params }: RouteContext<'/llms.mdx/docs/[[...slug]]'>) {
|
||||
const { slug } = await params;
|
||||
const page = source.getPage(slug?.slice(0, -1));
|
||||
if (!page) notFound();
|
||||
|
||||
return new Response(await getLLMText(page), {
|
||||
headers: {
|
||||
'Content-Type': 'text/markdown',
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export function generateStaticParams() {
|
||||
return source.getPages().map((page) => ({
|
||||
lang: page.locale,
|
||||
slug: getPageMarkdownUrl(page).segments,
|
||||
}));
|
||||
}
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
import { source } from '@/lib/source';
|
||||
import { llms } from 'fumadocs-core/source';
|
||||
|
||||
export const revalidate = false;
|
||||
|
||||
export function GET() {
|
||||
return new Response(llms(source).index());
|
||||
}
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
import { getPageImage, source } from '@/lib/source';
|
||||
import { notFound } from 'next/navigation';
|
||||
import { ImageResponse } from 'next/og';
|
||||
import { generate as DefaultImage } from 'fumadocs-ui/og';
|
||||
|
||||
export const revalidate = false;
|
||||
|
||||
export async function GET(_req: Request, { params }: RouteContext<'/og/docs/[...slug]'>) {
|
||||
const { slug } = await params;
|
||||
const page = source.getPage(slug.slice(0, -1));
|
||||
if (!page) notFound();
|
||||
|
||||
return new ImageResponse(
|
||||
<DefaultImage title={page.data.title} description={page.data.description} site="My App" />,
|
||||
{
|
||||
width: 1200,
|
||||
height: 630,
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
export function generateStaticParams() {
|
||||
return source.getPages().map((page) => ({
|
||||
lang: page.locale,
|
||||
slug: getPageImage(page).segments,
|
||||
}));
|
||||
}
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
// Next.js App Router robots convention (Next 13+). The default Next
|
||||
// behaviour allows everything; this file makes the intent explicit so
|
||||
// AI-bot operators that read an opt-in list (GPTBot, ClaudeBot,
|
||||
// PerplexityBot, Google-Extended, etc.) see a clear green light, and
|
||||
// so the sitemap is discoverable.
|
||||
//
|
||||
// Headroom docs are open-source documentation we WANT indexed. If a
|
||||
// future page should be excluded, add it to the ``disallow`` list of
|
||||
// the relevant rule.
|
||||
|
||||
import type { MetadataRoute } from 'next';
|
||||
|
||||
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://headroom-docs.vercel.app';
|
||||
|
||||
export default function robots(): MetadataRoute.Robots {
|
||||
return {
|
||||
rules: [
|
||||
// Bot-specific allows. These names are the literal user-agent
|
||||
// strings each operator publishes. Listing them explicitly is
|
||||
// the documented way to opt INTO AI-training / AI-search
|
||||
// indexing — silence (no rule) is treated as opt-out by some
|
||||
// operators (notably Google-Extended).
|
||||
{ userAgent: 'GPTBot', allow: '/' },
|
||||
{ userAgent: 'OAI-SearchBot', allow: '/' },
|
||||
{ userAgent: 'ChatGPT-User', allow: '/' },
|
||||
{ userAgent: 'ClaudeBot', allow: '/' },
|
||||
{ userAgent: 'Claude-Web', allow: '/' },
|
||||
{ userAgent: 'anthropic-ai', allow: '/' },
|
||||
{ userAgent: 'PerplexityBot', allow: '/' },
|
||||
{ userAgent: 'Perplexity-User', allow: '/' },
|
||||
{ userAgent: 'Google-Extended', allow: '/' },
|
||||
{ userAgent: 'cohere-ai', allow: '/' },
|
||||
{ userAgent: 'CCBot', allow: '/' },
|
||||
{ userAgent: 'Applebot-Extended', allow: '/' },
|
||||
// Catch-all so traditional search crawlers also see an
|
||||
// explicit allow.
|
||||
{ userAgent: '*', allow: '/' },
|
||||
],
|
||||
sitemap: `${SITE_URL}/sitemap.xml`,
|
||||
host: SITE_URL,
|
||||
};
|
||||
}
|
||||
|
|
@ -1,39 +0,0 @@
|
|||
// Next.js App Router sitemap convention (Next 13+). Pulls every page
|
||||
// out of the Fumadocs ``source`` (same source that backs ``/llms.txt``,
|
||||
// search, and the OG image generator) and emits a valid sitemap.xml.
|
||||
//
|
||||
// Search engines and AI crawlers use this to enumerate every doc page
|
||||
// without scraping HTML. The ``robots.ts`` route advertises the
|
||||
// sitemap URL so well-behaved crawlers find it on the first GET.
|
||||
|
||||
import type { MetadataRoute } from 'next';
|
||||
import { source } from '@/lib/source';
|
||||
|
||||
const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? 'https://headroom-docs.vercel.app';
|
||||
|
||||
export default function sitemap(): MetadataRoute.Sitemap {
|
||||
const now = new Date();
|
||||
|
||||
// Static top-level routes (home page; docs index is covered by the
|
||||
// page enumeration below).
|
||||
const staticRoutes: MetadataRoute.Sitemap = [
|
||||
{
|
||||
url: `${SITE_URL}/`,
|
||||
lastModified: now,
|
||||
changeFrequency: 'weekly',
|
||||
priority: 1.0,
|
||||
},
|
||||
];
|
||||
|
||||
// Every Fumadocs page (introduction, quickstart, installation,
|
||||
// integrations, …). ``page.url`` is the relative URL like
|
||||
// ``/docs/quickstart``; ``page.data`` carries the front-matter.
|
||||
const docPages: MetadataRoute.Sitemap = source.getPages().map((page) => ({
|
||||
url: `${SITE_URL}${page.url}`,
|
||||
lastModified: now,
|
||||
changeFrequency: 'weekly' as const,
|
||||
priority: 0.8,
|
||||
}));
|
||||
|
||||
return [...staticRoutes, ...docPages];
|
||||
}
|
||||
3011
benchmarks/index.html
Normal file
3011
benchmarks/index.html
Normal file
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
4983
cli/index.html
Normal file
4983
cli/index.html
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -1,59 +0,0 @@
|
|||
import * as React from "react";
|
||||
import { Slot } from "@radix-ui/react-slot";
|
||||
import { cva, type VariantProps } from "class-variance-authority";
|
||||
import { cn } from "@/lib/cn";
|
||||
|
||||
const buttonVariants = cva(
|
||||
"cursor-pointer active:scale-99 duration-200 font-medium inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-full text-sm font-medium focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: "bg-foreground text-background hover:brightness-95",
|
||||
neutral: "bg-foreground text-background hover:brightness-95",
|
||||
destructive:
|
||||
"bg-destructive text-destructive-foreground shadow-md hover:bg-destructive/90",
|
||||
outline:
|
||||
"shadow-sm text-foreground shadow-black/6.5 border border-transparent bg-card ring-1 ring-foreground/15 duration-200 hover:bg-muted/50",
|
||||
secondary:
|
||||
"bg-secondary text-secondary-foreground hover:bg-secondary/80",
|
||||
ghost: "hover:bg-foreground/5 text-foreground/75 hover:text-foreground",
|
||||
link: "text-primary underline-offset-4 hover:underline",
|
||||
},
|
||||
size: {
|
||||
default: "h-8 px-3 py-2",
|
||||
sm: "h-7 px-2.5 text-sm",
|
||||
lg: "h-11 px-6 font-medium text-base",
|
||||
icon: "size-9",
|
||||
"icon-sm": "size-7",
|
||||
"icon-xs": "size-5",
|
||||
},
|
||||
},
|
||||
defaultVariants: {
|
||||
variant: "default",
|
||||
size: "default",
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
export interface ButtonProps
|
||||
extends
|
||||
React.ButtonHTMLAttributes<HTMLButtonElement>,
|
||||
VariantProps<typeof buttonVariants> {
|
||||
asChild?: boolean;
|
||||
}
|
||||
|
||||
const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
|
||||
({ className, variant, size, asChild = false, ...props }, ref) => {
|
||||
const Comp = asChild ? Slot : "button";
|
||||
return (
|
||||
<Comp
|
||||
className={cn(buttonVariants({ variant, size, className }))}
|
||||
ref={ref}
|
||||
{...props}
|
||||
/>
|
||||
);
|
||||
},
|
||||
);
|
||||
Button.displayName = "Button";
|
||||
|
||||
export { Button, buttonVariants };
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
interface CodeBlockProps {
|
||||
code: string;
|
||||
lang?: string;
|
||||
}
|
||||
|
||||
export function CodeBlock({ code }: CodeBlockProps) {
|
||||
return (
|
||||
<pre className="mt-3 p-3 text-xs rounded-lg bg-fd-muted text-fd-foreground overflow-x-auto font-mono whitespace-pre-wrap break-words">
|
||||
{code}
|
||||
</pre>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,346 +0,0 @@
|
|||
'use client'
|
||||
|
||||
import { useState } from 'react'
|
||||
import {
|
||||
AreaChart, Area, BarChart, Bar,
|
||||
XAxis, YAxis, Tooltip, ResponsiveContainer, CartesianGrid,
|
||||
} from 'recharts'
|
||||
|
||||
// --- Embedded telemetry data ---
|
||||
const DATA = {
|
||||
total_tokens_saved: 41750654085,
|
||||
total_cost_saved: 176635.62,
|
||||
total_requests: 1194154,
|
||||
unique_instances: 889,
|
||||
active_days: 14,
|
||||
daily_stats: [
|
||||
{ date: '2026-03-30', requests: 1050, instances: 17, cost_saved: 42.29, tokens_saved: 7560502 },
|
||||
{ date: '2026-03-31', requests: 26526, instances: 149, cost_saved: 1904.15, tokens_saved: 1004245860 },
|
||||
{ date: '2026-04-01', requests: 53480, instances: 117, cost_saved: 3353.50, tokens_saved: 860455498 },
|
||||
{ date: '2026-04-02', requests: 64906, instances: 123, cost_saved: 18007.10, tokens_saved: 3431477414 },
|
||||
{ date: '2026-04-03', requests: 99872, instances: 162, cost_saved: 29238.20, tokens_saved: 6159073542 },
|
||||
{ date: '2026-04-04', requests: 90992, instances: 147, cost_saved: 12863.30, tokens_saved: 1864667449 },
|
||||
{ date: '2026-04-05', requests: 162541, instances: 142, cost_saved: 49802.60, tokens_saved: 11990261722 },
|
||||
{ date: '2026-04-06', requests: 127494, instances: 174, cost_saved: 11533.70, tokens_saved: 3850552409 },
|
||||
{ date: '2026-04-07', requests: 158840, instances: 201, cost_saved: 14260.90, tokens_saved: 4113326538 },
|
||||
{ date: '2026-04-08', requests: 84459, instances: 186, cost_saved: 8383.12, tokens_saved: 2317153362 },
|
||||
{ date: '2026-04-09', requests: 137856, instances: 208, cost_saved: 10663.80, tokens_saved: 2058570508 },
|
||||
{ date: '2026-04-10', requests: 111043, instances: 192, cost_saved: 9893.92, tokens_saved: 1979992305 },
|
||||
{ date: '2026-04-11', requests: 65851, instances: 147, cost_saved: 5853.92, tokens_saved: 1521911387 },
|
||||
{ date: '2026-04-12', requests: 9244, instances: 27, cost_saved: 835.12, tokens_saved: 591405589 },
|
||||
],
|
||||
hourly_stats: [
|
||||
{ hour: '2026-04-10 06:00', requests: 8548, instances: 9, cost_saved: 577.12, tokens_saved: 198669219 },
|
||||
{ hour: '2026-04-10 07:00', requests: 8289, instances: 18, cost_saved: 456.34, tokens_saved: 172834374 },
|
||||
{ hour: '2026-04-10 08:00', requests: 8066, instances: 23, cost_saved: 559.56, tokens_saved: 196181344 },
|
||||
{ hour: '2026-04-10 09:00', requests: 4890, instances: 16, cost_saved: 206.95, tokens_saved: 124914685 },
|
||||
{ hour: '2026-04-10 10:00', requests: 9531, instances: 21, cost_saved: 421.51, tokens_saved: 236470420 },
|
||||
{ hour: '2026-04-10 11:00', requests: 5170, instances: 13, cost_saved: 174.45, tokens_saved: 114113494 },
|
||||
{ hour: '2026-04-10 12:00', requests: 10982, instances: 20, cost_saved: 388.05, tokens_saved: 166308102 },
|
||||
{ hour: '2026-04-10 13:00', requests: 8001, instances: 16, cost_saved: 228.53, tokens_saved: 134921875 },
|
||||
{ hour: '2026-04-10 14:00', requests: 4950, instances: 15, cost_saved: 208.56, tokens_saved: 119763470 },
|
||||
{ hour: '2026-04-10 15:00', requests: 9000, instances: 17, cost_saved: 1739.51, tokens_saved: 166911747 },
|
||||
{ hour: '2026-04-10 16:00', requests: 12569, instances: 17, cost_saved: 1130.82, tokens_saved: 312958735 },
|
||||
{ hour: '2026-04-10 17:00', requests: 12057, instances: 17, cost_saved: 443.07, tokens_saved: 203763560 },
|
||||
{ hour: '2026-04-10 18:00', requests: 14011, instances: 18, cost_saved: 1018.06, tokens_saved: 294928335 },
|
||||
{ hour: '2026-04-10 19:00', requests: 12599, instances: 17, cost_saved: 915.21, tokens_saved: 327535343 },
|
||||
{ hour: '2026-04-10 20:00', requests: 10522, instances: 16, cost_saved: 2484.87, tokens_saved: 206735552 },
|
||||
{ hour: '2026-04-10 21:00', requests: 7125, instances: 16, cost_saved: 928.27, tokens_saved: 289265979 },
|
||||
{ hour: '2026-04-10 22:00', requests: 4481, instances: 9, cost_saved: 190.60, tokens_saved: 137301814 },
|
||||
{ hour: '2026-04-10 23:00', requests: 4033, instances: 5, cost_saved: 154.82, tokens_saved: 126989500 },
|
||||
{ hour: '2026-04-11 00:00', requests: 8998, instances: 12, cost_saved: 770.90, tokens_saved: 254824094 },
|
||||
{ hour: '2026-04-11 01:00', requests: 13729, instances: 12, cost_saved: 668.12, tokens_saved: 330717273 },
|
||||
{ hour: '2026-04-11 02:00', requests: 3738, instances: 2, cost_saved: 152.18, tokens_saved: 126547280 },
|
||||
{ hour: '2026-04-11 03:00', requests: 4449, instances: 4, cost_saved: 185.03, tokens_saved: 134597314 },
|
||||
{ hour: '2026-04-11 04:00', requests: 5961, instances: 9, cost_saved: 303.65, tokens_saved: 157734893 },
|
||||
{ hour: '2026-04-11 05:00', requests: 6550, instances: 8, cost_saved: 248.84, tokens_saved: 158834743 },
|
||||
{ hour: '2026-04-11 06:00', requests: 5429, instances: 8, cost_saved: 268.11, tokens_saved: 155129772 },
|
||||
{ hour: '2026-04-11 07:00', requests: 5671, instances: 11, cost_saved: 225.25, tokens_saved: 143244185 },
|
||||
{ hour: '2026-04-11 08:00', requests: 7258, instances: 12, cost_saved: 264.80, tokens_saved: 158618368 },
|
||||
{ hour: '2026-04-11 09:00', requests: 8732, instances: 7, cost_saved: 301.46, tokens_saved: 157720064 },
|
||||
{ hour: '2026-04-11 10:00', requests: 6058, instances: 6, cost_saved: 230.22, tokens_saved: 155936384 },
|
||||
{ hour: '2026-04-11 11:00', requests: 7615, instances: 13, cost_saved: 444.21, tokens_saved: 288328690 },
|
||||
{ hour: '2026-04-11 12:00', requests: 6749, instances: 10, cost_saved: 716.35, tokens_saved: 542054609 },
|
||||
{ hour: '2026-04-11 13:00', requests: 6276, instances: 10, cost_saved: 2259.74, tokens_saved: 572384133 },
|
||||
{ hour: '2026-04-11 14:00', requests: 8858, instances: 16, cost_saved: 846.04, tokens_saved: 602153567 },
|
||||
{ hour: '2026-04-11 15:00', requests: 9284, instances: 12, cost_saved: 811.16, tokens_saved: 581585147 },
|
||||
{ hour: '2026-04-11 16:00', requests: 7390, instances: 16, cost_saved: 749.69, tokens_saved: 566925112 },
|
||||
{ hour: '2026-04-11 17:00', requests: 11558, instances: 13, cost_saved: 1023.99, tokens_saved: 623709492 },
|
||||
{ hour: '2026-04-11 18:00', requests: 6154, instances: 10, cost_saved: 709.22, tokens_saved: 546162461 },
|
||||
{ hour: '2026-04-11 19:00', requests: 5711, instances: 11, cost_saved: 660.33, tokens_saved: 548094492 },
|
||||
{ hour: '2026-04-11 20:00', requests: 9287, instances: 13, cost_saved: 800.20, tokens_saved: 575078608 },
|
||||
{ hour: '2026-04-11 21:00', requests: 5858, instances: 9, cost_saved: 675.77, tokens_saved: 547657183 },
|
||||
{ hour: '2026-04-11 22:00', requests: 5523, instances: 13, cost_saved: 1133.82, tokens_saved: 638333840 },
|
||||
{ hour: '2026-04-11 23:00', requests: 7668, instances: 8, cost_saved: 903.46, tokens_saved: 592286174 },
|
||||
{ hour: '2026-04-12 00:00', requests: 5723, instances: 9, cost_saved: 655.44, tokens_saved: 543699655 },
|
||||
{ hour: '2026-04-12 01:00', requests: 5291, instances: 8, cost_saved: 673.29, tokens_saved: 552129148 },
|
||||
{ hour: '2026-04-12 02:00', requests: 6689, instances: 9, cost_saved: 698.83, tokens_saved: 551696076 },
|
||||
{ hour: '2026-04-12 03:00', requests: 6532, instances: 8, cost_saved: 749.06, tokens_saved: 569436595 },
|
||||
{ hour: '2026-04-12 04:00', requests: 4805, instances: 3, cost_saved: 644.29, tokens_saved: 540846848 },
|
||||
{ hour: '2026-04-12 05:00', requests: 5181, instances: 6, cost_saved: 642.90, tokens_saved: 539173642 },
|
||||
{ hour: '2026-04-12 06:00', requests: 4739, instances: 1, cost_saved: 637.17, tokens_saved: 537999942 },
|
||||
],
|
||||
top_instances: [
|
||||
{ os: 'Windows', version: '0.5.18', cost_saved: 36325.40, instance_id: '1d5d8ed0', tokens_saved: 8852060567 },
|
||||
{ os: 'Linux', version: '0.5.19', cost_saved: 2188.80, instance_id: '96d9632f', tokens_saved: 2395311403 },
|
||||
{ os: 'Windows', version: '0.5.17', cost_saved: 11878.30, instance_id: '1e850cb3', tokens_saved: 2375786993 },
|
||||
{ os: 'Windows', version: '0.5.17', cost_saved: 9080.36, instance_id: '0cdfb8e9', tokens_saved: 1816351278 },
|
||||
{ os: 'Linux', version: '0.5.18', cost_saved: 7580.30, instance_id: '7456b0f9', tokens_saved: 1635744469 },
|
||||
{ os: 'Darwin', version: '0.5.16', cost_saved: 1772.99, instance_id: '1661b732', tokens_saved: 1488844495 },
|
||||
{ os: 'Darwin', version: '0.5.17', cost_saved: 4667.23, instance_id: '08bf5ae1', tokens_saved: 933450700 },
|
||||
{ os: 'Darwin', version: '0.5.18', cost_saved: 0, instance_id: 'e20f01b6', tokens_saved: 565038755 },
|
||||
{ os: 'Linux', version: '0.5.18', cost_saved: 538.37, instance_id: '5b0795b2', tokens_saved: 557489086 },
|
||||
{ os: 'Windows', version: '0.5.18', cost_saved: 1773.69, instance_id: 'eff9e644', tokens_saved: 503362483 },
|
||||
{ os: 'Windows', version: '0.5.18', cost_saved: 1812.66, instance_id: '388102c7', tokens_saved: 485305324 },
|
||||
{ os: 'Linux', version: '0.5.17', cost_saved: 2297.45, instance_id: '3ee70444', tokens_saved: 468622655 },
|
||||
{ os: 'Darwin', version: '0.5.16', cost_saved: 319.65, instance_id: '6e758d1e', tokens_saved: 437502391 },
|
||||
{ os: 'Linux', version: '0.5.18', cost_saved: 1461.02, instance_id: 'b2e71a28', tokens_saved: 415224504 },
|
||||
{ os: 'Darwin', version: '0.5.21', cost_saved: 509.44, instance_id: '8b3795aa', tokens_saved: 353583838 },
|
||||
{ os: 'Linux', version: '0.5.17', cost_saved: 1663.48, instance_id: 'b6a1a735', tokens_saved: 334438796 },
|
||||
{ os: 'Linux', version: '0.5.21', cost_saved: 1603.77, instance_id: 'd0c16fa0', tokens_saved: 322890921 },
|
||||
{ os: 'Linux', version: '0.5.18', cost_saved: 1580.12, instance_id: '4140eb00', tokens_saved: 316804284 },
|
||||
{ os: 'Darwin', version: '0.5.21', cost_saved: 1052.77, instance_id: '2b11b55c', tokens_saved: 308601543 },
|
||||
{ os: 'Darwin', version: '0.5.17', cost_saved: 1473.78, instance_id: '1ede777b', tokens_saved: 296950447 },
|
||||
],
|
||||
}
|
||||
|
||||
// --- Formatters ---
|
||||
|
||||
function fmt(n: number): string {
|
||||
if (n >= 1e9) return `${(n / 1e9).toFixed(1)}B`
|
||||
if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`
|
||||
if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`
|
||||
return n.toFixed(0)
|
||||
}
|
||||
|
||||
function fmtUsd(n: number): string {
|
||||
if (n >= 1e3) return `$${(n / 1e3).toFixed(1)}K`
|
||||
return `$${n.toFixed(0)}`
|
||||
}
|
||||
|
||||
const MONTHS = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
|
||||
|
||||
function fmtDateDaily(d: string): string {
|
||||
const [, m, day] = d.split('-')
|
||||
return `${MONTHS[parseInt(m, 10) - 1]} ${parseInt(day, 10)}`
|
||||
}
|
||||
|
||||
function fmtDateHourly(d: string): string {
|
||||
// "2026-04-10 06:00" → "Apr 10 6am"
|
||||
const [date, time] = d.split(' ')
|
||||
const [, m, day] = date.split('-')
|
||||
const hour = parseInt(time.split(':')[0], 10)
|
||||
const ampm = hour >= 12 ? 'pm' : 'am'
|
||||
const h12 = hour === 0 ? 12 : hour > 12 ? hour - 12 : hour
|
||||
return `${MONTHS[parseInt(m, 10) - 1]} ${parseInt(day, 10)} ${h12}${ampm}`
|
||||
}
|
||||
|
||||
// --- Components ---
|
||||
|
||||
const PURPLE = 'hsl(262, 52%, 56%)'
|
||||
const PURPLE_LIGHT = 'hsl(262, 60%, 65%)'
|
||||
|
||||
type Metric = 'cost_saved' | 'requests' | 'tokens_saved'
|
||||
type TimeRange = 'daily' | 'hourly'
|
||||
|
||||
function ToggleButton({ active, onClick, children }: { active: boolean; onClick: () => void; children: React.ReactNode }) {
|
||||
return (
|
||||
<button
|
||||
onClick={onClick}
|
||||
className={`px-3 py-1 text-xs font-medium rounded-md transition ${
|
||||
active
|
||||
? 'bg-fd-primary text-fd-primary-foreground'
|
||||
: 'bg-fd-muted text-fd-muted-foreground hover:text-fd-foreground'
|
||||
}`}
|
||||
>
|
||||
{children}
|
||||
</button>
|
||||
)
|
||||
}
|
||||
|
||||
function CustomTooltip({ active, payload, label }: any) {
|
||||
if (!active || !payload?.length) return null
|
||||
return (
|
||||
<div className="rounded-lg border border-fd-border bg-fd-card px-3 py-2 text-xs shadow-lg">
|
||||
<p className="font-medium text-fd-foreground mb-1">{label}</p>
|
||||
{payload.map((p: any) => (
|
||||
<p key={p.dataKey} className="text-fd-muted-foreground">
|
||||
{p.dataKey === 'cost_saved' ? fmtUsd(p.value) : fmt(p.value)}
|
||||
</p>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
function StatsCards() {
|
||||
return (
|
||||
<div className="grid grid-cols-2 md:grid-cols-4 gap-4 not-prose">
|
||||
{[
|
||||
{ label: 'Cost Saved', value: fmtUsd(DATA.total_cost_saved) },
|
||||
{ label: 'Requests Optimized', value: fmt(DATA.total_requests) },
|
||||
{ label: 'Active Instances', value: fmt(DATA.unique_instances) },
|
||||
{ label: 'Active Days', value: String(DATA.active_days) },
|
||||
].map(s => (
|
||||
<div key={s.label} className="flex flex-col items-center p-5 rounded-xl border border-fd-border bg-fd-card">
|
||||
<span className="text-2xl font-bold text-fd-foreground">{s.value}</span>
|
||||
<span className="mt-1 text-sm text-fd-muted-foreground">{s.label}</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
function AreaChartSection() {
|
||||
const [metric, setMetric] = useState<Metric>('tokens_saved')
|
||||
const [timeRange, setTimeRange] = useState<TimeRange>('hourly')
|
||||
|
||||
const isHourly = timeRange === 'hourly'
|
||||
const chartData: { label: string; requests: number; instances: number; cost_saved: number; tokens_saved: number }[] = !isHourly
|
||||
? DATA.daily_stats.map(d => ({ label: fmtDateDaily(d.date), requests: d.requests, instances: d.instances, cost_saved: d.cost_saved, tokens_saved: d.tokens_saved }))
|
||||
: DATA.hourly_stats.map(d => ({ label: fmtDateHourly(d.hour), requests: d.requests, instances: d.instances, cost_saved: d.cost_saved, tokens_saved: d.tokens_saved }))
|
||||
|
||||
const metricLabels: Record<Metric, string> = {
|
||||
cost_saved: 'Cost Saved',
|
||||
requests: 'Requests',
|
||||
tokens_saved: 'Tokens Saved',
|
||||
}
|
||||
|
||||
const tickFormatter = (v: number) =>
|
||||
metric === 'cost_saved' ? fmtUsd(v) : fmt(v)
|
||||
|
||||
return (
|
||||
<div className="rounded-xl border border-fd-border bg-fd-card p-5 not-prose">
|
||||
<div className="flex flex-wrap items-center justify-between gap-3 mb-5">
|
||||
<div className="flex gap-1">
|
||||
{(['cost_saved', 'requests', 'tokens_saved'] as Metric[]).map(m => (
|
||||
<ToggleButton key={m} active={metric === m} onClick={() => setMetric(m)}>
|
||||
{metricLabels[m]}
|
||||
</ToggleButton>
|
||||
))}
|
||||
</div>
|
||||
<div className="flex gap-1">
|
||||
{(['hourly', 'daily'] as TimeRange[]).map(t => (
|
||||
<ToggleButton key={t} active={timeRange === t} onClick={() => setTimeRange(t)}>
|
||||
{t === 'hourly' ? 'Last 48h' : 'Daily'}
|
||||
</ToggleButton>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
<div className="h-72">
|
||||
<ResponsiveContainer width="100%" height="100%" minWidth={0} minHeight={0}>
|
||||
<AreaChart data={chartData} margin={{ left: 0, right: 10, top: 5, bottom: isHourly ? 40 : 5 }}>
|
||||
<defs>
|
||||
<linearGradient id="purpleGrad" x1="0" y1="0" x2="0" y2="1">
|
||||
<stop offset="0%" stopColor={PURPLE} stopOpacity={0.3} />
|
||||
<stop offset="100%" stopColor={PURPLE} stopOpacity={0} />
|
||||
</linearGradient>
|
||||
</defs>
|
||||
<CartesianGrid strokeDasharray="3 3" stroke="var(--color-fd-border)" />
|
||||
<XAxis
|
||||
dataKey="label"
|
||||
tick={{ fontSize: 9, fill: 'var(--color-fd-muted-foreground)' }}
|
||||
interval={isHourly ? 3 : 0}
|
||||
angle={isHourly ? -45 : 0}
|
||||
textAnchor={isHourly ? 'end' : 'middle'}
|
||||
height={isHourly ? 60 : 30}
|
||||
/>
|
||||
<YAxis tickFormatter={tickFormatter} tick={{ fontSize: 10, fill: 'var(--color-fd-muted-foreground)' }} width={45} />
|
||||
<Tooltip content={<CustomTooltip />} />
|
||||
<Area
|
||||
type="monotone"
|
||||
dataKey={metric}
|
||||
stroke={PURPLE}
|
||||
strokeWidth={2}
|
||||
fill="url(#purpleGrad)"
|
||||
/>
|
||||
</AreaChart>
|
||||
</ResponsiveContainer>
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
function BarChartSection() {
|
||||
const barData = DATA.top_instances.slice(0, 10).map(i => ({
|
||||
name: `${i.instance_id} (${i.os})`,
|
||||
tokens_saved: i.tokens_saved,
|
||||
cost_saved: i.cost_saved,
|
||||
}))
|
||||
|
||||
return (
|
||||
<div className="rounded-xl border border-fd-border bg-fd-card p-5 not-prose">
|
||||
<div className="h-80">
|
||||
<ResponsiveContainer width="100%" height="100%" minWidth={0} minHeight={0}>
|
||||
<BarChart data={barData} layout="vertical" margin={{ left: 0, right: 10, top: 5, bottom: 5 }}>
|
||||
<CartesianGrid strokeDasharray="3 3" stroke="var(--color-fd-border)" horizontal={false} />
|
||||
<XAxis type="number" tickFormatter={fmt} tick={{ fontSize: 10, fill: 'var(--color-fd-muted-foreground)' }} />
|
||||
<YAxis type="category" dataKey="name" tick={{ fontSize: 9, fill: 'var(--color-fd-muted-foreground)' }} width={85} />
|
||||
<Tooltip content={({ active, payload }: any) => {
|
||||
if (!active || !payload?.length) return null
|
||||
const d = payload[0].payload
|
||||
return (
|
||||
<div className="rounded-lg border border-fd-border bg-fd-card px-3 py-2 text-xs shadow-lg">
|
||||
<p className="font-medium text-fd-foreground">{d.name}</p>
|
||||
<p className="text-fd-muted-foreground">{fmt(d.tokens_saved)} tokens</p>
|
||||
<p className="text-fd-muted-foreground">{fmtUsd(d.cost_saved)} saved</p>
|
||||
</div>
|
||||
)
|
||||
}} />
|
||||
<Bar dataKey="tokens_saved" fill={PURPLE} radius={[0, 4, 4, 0]} />
|
||||
</BarChart>
|
||||
</ResponsiveContainer>
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
function DataTable() {
|
||||
return (
|
||||
<div className="rounded-xl border border-fd-border bg-fd-card overflow-hidden not-prose">
|
||||
<div className="overflow-x-auto">
|
||||
<table className="w-full text-sm">
|
||||
<thead>
|
||||
<tr className="border-b border-fd-border text-left text-fd-muted-foreground">
|
||||
<th className="px-5 py-2 font-medium">Instance</th>
|
||||
<th className="px-5 py-2 font-medium">OS</th>
|
||||
<th className="px-5 py-2 font-medium">Version</th>
|
||||
<th className="px-5 py-2 font-medium text-right">Tokens Saved</th>
|
||||
<th className="px-5 py-2 font-medium text-right">Cost Saved</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{DATA.top_instances.map((inst, i) => (
|
||||
<tr
|
||||
key={inst.instance_id}
|
||||
className={`border-b border-fd-border last:border-0 ${i % 2 === 0 ? 'bg-fd-muted/30' : ''}`}
|
||||
>
|
||||
<td className="px-5 py-2.5 font-mono text-xs text-fd-foreground">{inst.instance_id}</td>
|
||||
<td className="px-5 py-2.5 text-fd-muted-foreground">{inst.os}</td>
|
||||
<td className="px-5 py-2.5 text-fd-muted-foreground">{inst.version}</td>
|
||||
<td className="px-5 py-2.5 text-right text-fd-foreground font-medium">{fmt(inst.tokens_saved)}</td>
|
||||
<td className="px-5 py-2.5 text-right text-fd-foreground font-medium">{fmtUsd(inst.cost_saved)}</td>
|
||||
</tr>
|
||||
))}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export function CommunityCharts({ section }: { section?: 'stats' | 'area' | 'bar' | 'table' }) {
|
||||
if (section === 'stats') return <StatsCards />
|
||||
if (section === 'area') return <AreaChartSection />
|
||||
if (section === 'bar') return <BarChartSection />
|
||||
if (section === 'table') return <DataTable />
|
||||
|
||||
// Render all if no section specified
|
||||
return (
|
||||
<div className="space-y-10">
|
||||
<StatsCards />
|
||||
<AreaChartSection />
|
||||
<BarChartSection />
|
||||
<DataTable />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
import { fetchCommunityStats, fmtNum, fmtUsd } from '@/lib/telemetry';
|
||||
|
||||
/**
|
||||
* Server component that renders the top-level stats for the community savings page.
|
||||
* Fetches live data from Supabase at render time.
|
||||
*/
|
||||
export async function CommunityStatsHeader() {
|
||||
const data = await fetchCommunityStats();
|
||||
|
||||
const stats = [
|
||||
{ value: fmtNum(data.total_tokens_saved), label: 'Tokens Saved' },
|
||||
{ value: fmtUsd(data.total_cost_saved), label: 'Cost Saved' },
|
||||
{ value: fmtNum(data.total_requests), label: 'Requests Optimized' },
|
||||
{ value: fmtNum(data.unique_instances), label: 'Active Instances' },
|
||||
];
|
||||
|
||||
return (
|
||||
<div className="grid grid-cols-2 md:grid-cols-4 gap-4 not-prose">
|
||||
{stats.map((s) => (
|
||||
<div
|
||||
key={s.label}
|
||||
className="flex flex-col items-center p-5 rounded-xl border border-fd-border bg-fd-card"
|
||||
>
|
||||
<span className="text-2xl font-bold text-fd-foreground">
|
||||
{s.value}
|
||||
</span>
|
||||
<span className="mt-1 text-sm text-fd-muted-foreground">
|
||||
{s.label}
|
||||
</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
import Link from 'next/link';
|
||||
import { fetchCommunityStats, fmtNum, fmtUsd } from '@/lib/telemetry';
|
||||
|
||||
/**
|
||||
* Server component that fetches live stats from Supabase at render time.
|
||||
* Falls back to hardcoded data if the API is unreachable.
|
||||
*/
|
||||
export async function LiveStats() {
|
||||
const data = await fetchCommunityStats();
|
||||
|
||||
const stats = [
|
||||
{ value: fmtNum(data.total_tokens_saved), label: 'Tokens Saved' },
|
||||
{ value: fmtUsd(data.total_cost_saved), label: 'Cost Saved' },
|
||||
{ value: fmtNum(data.total_requests), label: 'Requests Optimized' },
|
||||
{ value: fmtNum(data.unique_instances), label: 'Active Instances' },
|
||||
];
|
||||
|
||||
return (
|
||||
<div className="not-prose">
|
||||
<div className="grid grid-cols-2 md:grid-cols-4 gap-4 my-8">
|
||||
{stats.map((s) => (
|
||||
<div
|
||||
key={s.label}
|
||||
className="flex flex-col items-center p-5 rounded-xl border border-fd-border bg-fd-card"
|
||||
>
|
||||
<span className="text-2xl font-bold text-fd-foreground">
|
||||
{s.value}
|
||||
</span>
|
||||
<span className="mt-1 text-sm text-fd-muted-foreground">
|
||||
{s.label}
|
||||
</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
<Link
|
||||
href="/docs/community-savings"
|
||||
className="text-sm font-medium hover:underline"
|
||||
>
|
||||
View detailed charts and breakdowns →
|
||||
</Link>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
'use client'
|
||||
import DottedMap from 'dotted-map'
|
||||
import { useEffect, useState } from 'react'
|
||||
|
||||
const pins = [
|
||||
{ lat: 40.73061, lng: -73.935242 },
|
||||
{ lat: 48.8534, lng: 2.3488 },
|
||||
{ lat: 51.5074, lng: -0.1278 },
|
||||
{ lat: 35.6895, lng: 139.6917 },
|
||||
{ lat: 34.0522, lng: -118.2437 },
|
||||
{ lat: 55.7558, lng: 37.6173 },
|
||||
{ lat: 39.9042, lng: 116.4074 },
|
||||
{ lat: 19.4326, lng: -99.1332 },
|
||||
{ lat: 37.7749, lng: -122.4194 },
|
||||
{ lat: -33.8688, lng: 151.2093 },
|
||||
{ lat: 28.6139, lng: 77.209 },
|
||||
{ lat: 52.52, lng: 13.405 },
|
||||
{ lat: 41.9028, lng: 12.4964 },
|
||||
{ lat: 43.65107, lng: -79.347015 },
|
||||
{ lat: -23.55052, lng: -46.633308 },
|
||||
{ lat: 31.2304, lng: 121.4737 },
|
||||
{ lat: 55.9533, lng: -3.1883 },
|
||||
{ lat: 35.6762, lng: 139.6503 },
|
||||
{ lat: 1.3521, lng: 103.8198 },
|
||||
{ lat: 37.5665, lng: 126.978 },
|
||||
{ lat: 53.3498, lng: -6.2603 },
|
||||
{ lat: 30.0444, lng: 31.2357 },
|
||||
{ lat: 50.4501, lng: 30.5234 },
|
||||
{ lat: -34.6037, lng: -58.3816 },
|
||||
{ lat: 59.9343, lng: 30.3351 },
|
||||
{ lat: 25.276987, lng: 55.296249 },
|
||||
{ lat: 45.4642, lng: 9.19 },
|
||||
{ lat: -22.9068, lng: -43.1729 },
|
||||
{ lat: 40.4168, lng: -3.7038 },
|
||||
{ lat: 41.3851, lng: 2.1734 },
|
||||
{ lat: 13.7563, lng: 100.5018 },
|
||||
{ lat: 52.3676, lng: 4.9041 },
|
||||
{ lat: -37.8136, lng: 144.9631 },
|
||||
{ lat: 60.1695, lng: 24.9354 },
|
||||
{ lat: 47.4979, lng: 19.0402 },
|
||||
{ lat: 59.3293, lng: 18.0686 },
|
||||
{ lat: 35.9078, lng: 127.7669 },
|
||||
{ lat: 46.2044, lng: 6.1432 },
|
||||
{ lat: 29.7604, lng: -95.3698 },
|
||||
{ lat: 39.7392, lng: -104.9903 },
|
||||
{ lat: -11.6647, lng: 27.4794 },
|
||||
{ lat: -10.7026, lng: 25.5122 },
|
||||
{ lat: -4.4419, lng: 15.2663 },
|
||||
]
|
||||
|
||||
function buildSvg(isDark: boolean) {
|
||||
const map = new DottedMap({ height: 55, grid: 'diagonal' })
|
||||
|
||||
pins.forEach((pin) => {
|
||||
map.addPin({
|
||||
...pin,
|
||||
svgOptions: {
|
||||
color: isDark
|
||||
? '#a78bfa' // bright purple on #050505
|
||||
: '#7c3aed', // vivid purple on #FAFAFA
|
||||
radius: 0.4,
|
||||
},
|
||||
})
|
||||
})
|
||||
|
||||
return map.getSVG({
|
||||
radius: 0.22,
|
||||
color: isDark
|
||||
? '#555555' // medium gray on #050505
|
||||
: '#a0a0a0', // medium gray on #FAFAFA
|
||||
shape: 'circle',
|
||||
backgroundColor: 'transparent',
|
||||
})
|
||||
}
|
||||
|
||||
export const Map = () => {
|
||||
const [isDark, setIsDark] = useState(false)
|
||||
|
||||
useEffect(() => {
|
||||
const check = () => setIsDark(document.documentElement.classList.contains('dark'))
|
||||
check()
|
||||
const observer = new MutationObserver(check)
|
||||
observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] })
|
||||
return () => observer.disconnect()
|
||||
}, [])
|
||||
|
||||
const svgMap = buildSvg(isDark)
|
||||
|
||||
return (
|
||||
<img
|
||||
src={`data:image/svg+xml;utf8,${encodeURIComponent(svgMap)}`}
|
||||
alt="map illustration"
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
|
@ -1,224 +0,0 @@
|
|||
import Link from 'next/link';
|
||||
import { Button } from './button';
|
||||
import { CodeBlock } from './code-block';
|
||||
|
||||
// --- Live Stats Grid ---
|
||||
|
||||
const liveStats = [
|
||||
{ value: '$176.6K', label: 'Cost Saved' },
|
||||
{ value: '1.19M', label: 'Requests Optimized' },
|
||||
{ value: '889', label: 'Active Instances' },
|
||||
{ value: '14', label: 'Active Days' },
|
||||
];
|
||||
|
||||
export function LiveStats() {
|
||||
return (
|
||||
<div className="not-prose">
|
||||
<div className="grid grid-cols-2 md:grid-cols-4 gap-4 my-8">
|
||||
{liveStats.map((s) => (
|
||||
<div
|
||||
key={s.label}
|
||||
className="flex flex-col items-center p-5 rounded-xl border border-fd-border bg-fd-card"
|
||||
>
|
||||
<span className="text-2xl font-bold text-fd-foreground">
|
||||
{s.value}
|
||||
</span>
|
||||
<span className="mt-1 text-sm text-fd-muted-foreground">
|
||||
{s.label}
|
||||
</span>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
<Link
|
||||
href="/docs/community-savings"
|
||||
className="text-sm font-medium hover:underline"
|
||||
>
|
||||
View detailed charts and breakdowns →
|
||||
</Link>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// --- Key Features Grid ---
|
||||
|
||||
const features: {
|
||||
title: string;
|
||||
description: string;
|
||||
href: string;
|
||||
code?: string;
|
||||
lang?: string;
|
||||
}[] = [
|
||||
{
|
||||
title: 'Lossless Compression (CCR)',
|
||||
description:
|
||||
'Compresses aggressively, stores originals, gives the LLM a tool to retrieve full details. Nothing is thrown away.',
|
||||
href: '/docs/ccr',
|
||||
},
|
||||
{
|
||||
title: 'Smart Content Detection',
|
||||
description:
|
||||
'Auto-detects JSON, code, logs, text, diffs, HTML. Routes each to the best compressor. Zero configuration needed.',
|
||||
href: '/docs/how-compression-works',
|
||||
},
|
||||
{
|
||||
title: 'Cache Optimization',
|
||||
description:
|
||||
"Stabilizes prefixes so provider KV caches hit. Tracks frozen messages to preserve the 90% read discount.",
|
||||
href: '/docs/cache-optimization',
|
||||
},
|
||||
{
|
||||
title: 'Image Compression',
|
||||
description:
|
||||
'40-90% token reduction via trained ML router. Automatically selects resize/quality tradeoff per image.',
|
||||
href: '/docs/image-compression',
|
||||
},
|
||||
{
|
||||
title: 'Persistent Memory',
|
||||
description:
|
||||
'Hierarchical memory (user/session/agent/turn) with SQLite + HNSW backends. Survives across conversations.',
|
||||
href: '/docs/memory',
|
||||
},
|
||||
{
|
||||
title: 'Failure Learning',
|
||||
description:
|
||||
'Reads past sessions, finds failed tool calls, correlates with what succeeded, writes learnings to CLAUDE.md.',
|
||||
href: '/docs/failure-learning',
|
||||
},
|
||||
{
|
||||
title: 'Multi-Agent Context',
|
||||
description: 'Compress what moves between agents. Any framework.',
|
||||
href: '/docs/shared-context',
|
||||
code: 'ctx = SharedContext()\nctx.put("research", big_output)\nsummary = ctx.get("research")',
|
||||
lang: 'python',
|
||||
},
|
||||
{
|
||||
title: 'Metrics & Observability',
|
||||
description:
|
||||
'Prometheus endpoint, per-request logging, cost tracking, budget limits, pipeline timing breakdowns.',
|
||||
href: '/docs/metrics',
|
||||
},
|
||||
];
|
||||
|
||||
export async function KeyFeatures() {
|
||||
return (
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-4 my-8 not-prose">
|
||||
{await Promise.all(
|
||||
features.map(async (f) => (
|
||||
<div
|
||||
key={f.title}
|
||||
className="flex flex-col p-5 rounded-xl border border-fd-border bg-fd-card"
|
||||
>
|
||||
<h3 className="text-base font-semibold text-fd-foreground">
|
||||
{f.title}
|
||||
</h3>
|
||||
<p className="mt-2 text-sm text-fd-muted-foreground flex-1">
|
||||
{f.description}
|
||||
</p>
|
||||
{f.code && <CodeBlock code={f.code} lang={f.lang} />}
|
||||
<Link
|
||||
href={f.href}
|
||||
className="mt-3 text-sm font-medium hover:underline"
|
||||
>
|
||||
Learn more →
|
||||
</Link>
|
||||
</div>
|
||||
)),
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
// --- Framework Integrations Bento ---
|
||||
|
||||
const integrations: {
|
||||
title: string;
|
||||
description: string;
|
||||
code: string;
|
||||
lang: string;
|
||||
href: string;
|
||||
}[] = [
|
||||
{
|
||||
title: 'LangChain',
|
||||
description:
|
||||
'Wrap any chat model. Supports memory, retrievers, tools, streaming, async.',
|
||||
code: 'from headroom.integrations.langchain import HeadroomChatModel\nllm = HeadroomChatModel(ChatOpenAI())',
|
||||
lang: 'python',
|
||||
href: '/docs/langchain',
|
||||
},
|
||||
{
|
||||
title: 'Agno',
|
||||
description:
|
||||
'Full agent framework integration with observability hooks.',
|
||||
code: 'from headroom.integrations.agno import HeadroomAgnoModel\nmodel = HeadroomAgnoModel(Claude())\nagent = Agent(model=model)',
|
||||
lang: 'python',
|
||||
href: '/docs/agno',
|
||||
},
|
||||
{
|
||||
title: 'Strands',
|
||||
description:
|
||||
'Model wrapping + tool output hook provider for Strands Agents.',
|
||||
code: 'from headroom.integrations.strands import HeadroomStrandsModel\nmodel = HeadroomStrandsModel(...)\nagent = Agent(model=model)',
|
||||
lang: 'python',
|
||||
href: '/docs/strands',
|
||||
},
|
||||
{
|
||||
title: 'MCP Tools',
|
||||
description:
|
||||
'Three tools for Claude Code, Cursor, or any MCP client: headroom_compress, headroom_retrieve, headroom_stats.',
|
||||
code: 'headroom mcp install && claude',
|
||||
lang: 'bash',
|
||||
href: '/docs/mcp',
|
||||
},
|
||||
{
|
||||
title: 'TypeScript SDK',
|
||||
description:
|
||||
'compress(), Vercel AI SDK middleware, OpenAI and Anthropic client wrappers.',
|
||||
code: 'npm install headroom-ai',
|
||||
lang: 'bash',
|
||||
href: '/docs/vercel-ai-sdk',
|
||||
},
|
||||
{
|
||||
title: 'Vercel AI SDK',
|
||||
description:
|
||||
'One-liner withHeadroom() or headroomMiddleware() for any Vercel AI SDK model.',
|
||||
code: "import { withHeadroom } from 'headroom-ai/vercel-ai'\nconst model = withHeadroom(openai('gpt-4o'))",
|
||||
lang: 'typescript',
|
||||
href: '/docs/vercel-ai-sdk',
|
||||
},
|
||||
];
|
||||
|
||||
export async function FrameworkIntegrations() {
|
||||
return (
|
||||
<div className="not-prose">
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-4 my-8">
|
||||
{await Promise.all(
|
||||
integrations.map(async (i) => (
|
||||
<div
|
||||
key={i.title}
|
||||
className="flex flex-col p-5 rounded-xl border border-fd-border bg-fd-card"
|
||||
>
|
||||
<h3 className="text-base font-semibold text-fd-foreground">
|
||||
{i.title}
|
||||
</h3>
|
||||
<p className="mt-2 text-sm text-fd-muted-foreground flex-1">
|
||||
{i.description}
|
||||
</p>
|
||||
<CodeBlock code={i.code} lang={i.lang} />
|
||||
<Link
|
||||
href={i.href}
|
||||
className="mt-3 text-sm font-medium hover:underline"
|
||||
>
|
||||
{i.title} Guide →
|
||||
</Link>
|
||||
</div>
|
||||
)),
|
||||
)}
|
||||
</div>
|
||||
<Button variant="link" size="sm" asChild>
|
||||
<Link href="/docs/quickstart">
|
||||
All integration patterns →
|
||||
</Link>
|
||||
</Button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
import defaultMdxComponents from 'fumadocs-ui/mdx';
|
||||
import type { MDXComponents } from 'mdx/types';
|
||||
import * as Twoslash from 'fumadocs-twoslash/ui';
|
||||
import { AutoTypeTable, type AutoTypeTableProps } from 'fumadocs-typescript/ui';
|
||||
import { createGenerator } from 'fumadocs-typescript';
|
||||
import { TypeTable } from 'fumadocs-ui/components/type-table';
|
||||
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
|
||||
import {
|
||||
KeyFeatures,
|
||||
FrameworkIntegrations,
|
||||
} from './marketing';
|
||||
import { LiveStats } from './live-stats';
|
||||
import { CommunityStatsHeader } from './community-stats-header';
|
||||
import { StatsSection } from './stats';
|
||||
import { CommunityCharts } from './community-charts';
|
||||
|
||||
const generator = createGenerator();
|
||||
|
||||
export function getMDXComponents(components?: MDXComponents) {
|
||||
return {
|
||||
...defaultMdxComponents,
|
||||
...Twoslash,
|
||||
AutoTypeTable: (props: Partial<AutoTypeTableProps>) => (
|
||||
<AutoTypeTable {...props} generator={generator} />
|
||||
),
|
||||
TypeTable,
|
||||
Tab,
|
||||
Tabs,
|
||||
StatsSection,
|
||||
CommunityCharts,
|
||||
CommunityStatsHeader,
|
||||
LiveStats,
|
||||
KeyFeatures,
|
||||
FrameworkIntegrations,
|
||||
...components,
|
||||
} satisfies MDXComponents;
|
||||
}
|
||||
|
||||
export const useMDXComponents = getMDXComponents;
|
||||
|
||||
declare global {
|
||||
type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
|
||||
}
|
||||
|
|
@ -1,71 +0,0 @@
|
|||
import { Map } from '@/components/map'
|
||||
|
||||
export function StatsSection() {
|
||||
return (
|
||||
<section className="@container relative py-12 md:py-20 not-prose overflow-hidden">
|
||||
<div className="mask-radial-to-75% absolute inset-0 max-md:hidden flex items-center justify-center">
|
||||
<div className="w-[140%] min-w-[900px]">
|
||||
<Map />
|
||||
</div>
|
||||
</div>
|
||||
<div className="mx-auto max-w-5xl px-6">
|
||||
<div className="md:max-w-3/5 lg:max-w-1/2 bg-fd-card ring-fd-border shadow-black/6.5 relative rounded-xl p-6 shadow-xl ring-1 sm:p-10">
|
||||
<div className="mb-8 space-y-4">
|
||||
<h2 className="text-fd-muted-foreground text-balance text-3xl font-semibold">
|
||||
The Context Optimization Layer for{' '}
|
||||
<strong className="text-fd-foreground font-semibold">
|
||||
LLM Applications
|
||||
</strong>
|
||||
</h2>
|
||||
<p className="text-fd-muted-foreground">
|
||||
Compress everything your AI agent reads.{' '}
|
||||
<strong className="text-fd-foreground font-semibold">
|
||||
Same answers, fraction of the tokens.
|
||||
</strong>
|
||||
</p>
|
||||
</div>
|
||||
<div className="**:text-center *:bg-fd-muted/50 grid grid-cols-2 gap-1 *:rounded-md *:p-4">
|
||||
<div className="space-y-2 *:block">
|
||||
<span className="text-3xl font-semibold">
|
||||
87 <span className="text-fd-muted-foreground text-lg">%</span>
|
||||
</span>
|
||||
<p className="text-fd-muted-foreground text-xs">
|
||||
<strong className="text-fd-foreground font-medium">
|
||||
Token Reduction
|
||||
</strong>
|
||||
</p>
|
||||
</div>
|
||||
<div className="space-y-2 *:block">
|
||||
<span className="text-3xl font-semibold">
|
||||
100 <span className="text-fd-muted-foreground text-lg">%</span>
|
||||
</span>
|
||||
<p className="text-fd-muted-foreground text-xs">
|
||||
<strong className="text-fd-foreground font-medium">
|
||||
Accuracy
|
||||
</strong>
|
||||
</p>
|
||||
</div>
|
||||
<div className="space-y-2 *:block">
|
||||
<span className="text-3xl font-semibold">6</span>
|
||||
<p className="text-fd-muted-foreground text-xs">
|
||||
<strong className="text-fd-foreground font-medium">
|
||||
Algorithms
|
||||
</strong>
|
||||
</p>
|
||||
</div>
|
||||
<div className="space-y-2 *:block">
|
||||
<span className="text-3xl font-semibold">
|
||||
100 <span className="text-fd-muted-foreground text-lg">+</span>
|
||||
</span>
|
||||
<p className="text-fd-muted-foreground text-xs">
|
||||
<strong className="text-fd-foreground font-medium">
|
||||
Providers
|
||||
</strong>
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
)
|
||||
}
|
||||
3035
compression/index.html
Normal file
3035
compression/index.html
Normal file
File diff suppressed because it is too large
Load diff
3296
configuration/index.html
Normal file
3296
configuration/index.html
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -1,154 +0,0 @@
|
|||
---
|
||||
title: Agno
|
||||
description: Automatic context compression for Agno AI agents with model wrapping and observability hooks.
|
||||
---
|
||||
|
||||
Headroom integrates with [Agno](https://github.com/agno-agi/agno) (formerly Phidata) to compress context for AI agents. Wrap any Agno model for automatic optimization, and use hooks for observability.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[agno]" agno
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```python
|
||||
from agno.agent import Agent
|
||||
from agno.models.openai import OpenAIChat
|
||||
from headroom.integrations.agno import HeadroomAgnoModel
|
||||
|
||||
model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
|
||||
agent = Agent(model=model)
|
||||
|
||||
response = agent.run("What's the capital of France?")
|
||||
|
||||
print(f"Tokens saved: {model.total_tokens_saved}")
|
||||
print(model.get_savings_summary())
|
||||
# {'total_requests': 1, 'total_tokens_saved': 245, 'average_savings_percent': 12.3}
|
||||
```
|
||||
|
||||
Works with any Agno provider:
|
||||
|
||||
```python
|
||||
from agno.models.anthropic import Claude
|
||||
from agno.models.google import Gemini
|
||||
|
||||
claude_model = HeadroomAgnoModel(Claude(id="claude-sonnet-4-20250514"))
|
||||
gemini_model = HeadroomAgnoModel(Gemini(id="gemini-2.0-flash"))
|
||||
```
|
||||
|
||||
## Observability hooks
|
||||
|
||||
Use hooks for detailed tracking without modifying your model:
|
||||
|
||||
```python
|
||||
from headroom.integrations.agno import (
|
||||
HeadroomAgnoModel,
|
||||
HeadroomPreHook,
|
||||
HeadroomPostHook,
|
||||
)
|
||||
|
||||
model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
|
||||
|
||||
pre_hook = HeadroomPreHook()
|
||||
post_hook = HeadroomPostHook(token_alert_threshold=10000)
|
||||
|
||||
agent = Agent(
|
||||
model=model,
|
||||
pre_hooks=[pre_hook],
|
||||
post_hooks=[post_hook],
|
||||
)
|
||||
|
||||
response = agent.run("Analyze this large dataset...")
|
||||
|
||||
# Check for alerts
|
||||
if post_hook.alerts:
|
||||
print(f"{len(post_hook.alerts)} requests exceeded threshold")
|
||||
```
|
||||
|
||||
Or use the convenience factory:
|
||||
|
||||
```python
|
||||
from headroom.integrations.agno import create_headroom_hooks
|
||||
|
||||
pre_hook, post_hook = create_headroom_hooks(
|
||||
token_alert_threshold=5000,
|
||||
log_level="DEBUG",
|
||||
)
|
||||
```
|
||||
|
||||
## Tool-heavy agents
|
||||
|
||||
Tool outputs (JSON, logs, search results) see the biggest compression gains at 70-90% reduction:
|
||||
|
||||
```python
|
||||
from agno.tools.duckduckgo import DuckDuckGoTools
|
||||
|
||||
model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
|
||||
|
||||
agent = Agent(
|
||||
model=model,
|
||||
tools=[DuckDuckGoTools()],
|
||||
show_tool_calls=True,
|
||||
)
|
||||
|
||||
response = agent.run("Research the latest AI developments")
|
||||
print(f"Tokens saved: {model.total_tokens_saved}")
|
||||
```
|
||||
|
||||
## Async support
|
||||
|
||||
```python
|
||||
import asyncio
|
||||
|
||||
async def process():
|
||||
model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
|
||||
|
||||
response = await model.aresponse(messages)
|
||||
|
||||
async for chunk in model.aresponse_stream(messages):
|
||||
print(chunk, end="", flush=True)
|
||||
|
||||
asyncio.run(process())
|
||||
```
|
||||
|
||||
## Standalone message optimization
|
||||
|
||||
Optimize messages without wrapping a model:
|
||||
|
||||
```python
|
||||
from headroom.integrations.agno import optimize_messages
|
||||
|
||||
optimized, metrics = optimize_messages(messages, model="gpt-4o")
|
||||
print(f"Tokens saved: {metrics['tokens_saved']}")
|
||||
```
|
||||
|
||||
## Session management
|
||||
|
||||
Reset metrics between sessions:
|
||||
|
||||
```python
|
||||
model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
|
||||
|
||||
# Session 1
|
||||
agent.run("First conversation...")
|
||||
print(model.get_savings_summary())
|
||||
|
||||
# Reset for new session
|
||||
model.reset()
|
||||
|
||||
# Session 2 starts fresh
|
||||
agent.run("Second conversation...")
|
||||
```
|
||||
|
||||
## Supported providers
|
||||
|
||||
| Provider | Agno Model | Auto-Detected |
|
||||
|----------|-----------|---------------|
|
||||
| OpenAI | `OpenAIChat`, `OpenAILike` | Yes |
|
||||
| Anthropic | `Claude`, `AwsBedrock` | Yes |
|
||||
| Google | `Gemini`, `VertexAI` | Yes |
|
||||
| Groq | `Groq` | Yes |
|
||||
| Mistral | `Mistral` | Yes |
|
||||
| Ollama | `Ollama` | Yes |
|
||||
|
|
@ -1,127 +0,0 @@
|
|||
---
|
||||
title: Anthropic SDK
|
||||
description: Auto-compress messages in the Anthropic TypeScript SDK with a single withHeadroom() wrapper.
|
||||
---
|
||||
|
||||
Headroom wraps the Anthropic TypeScript SDK to automatically compress messages before every `messages.create()` call. All other methods pass through unchanged.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install headroom-ai @anthropic-ai/sdk
|
||||
```
|
||||
|
||||
<Callout type="info" title="Proxy required">
|
||||
The TypeScript SDK sends messages to a local Headroom proxy for compression. Start the proxy before using the SDK:
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[proxy]"
|
||||
headroom proxy
|
||||
```
|
||||
</Callout>
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/anthropic';
|
||||
import Anthropic from '@anthropic-ai/sdk';
|
||||
|
||||
const client = withHeadroom(new Anthropic());
|
||||
|
||||
const response = await client.messages.create({
|
||||
model: 'claude-sonnet-4-5-20250929',
|
||||
messages: longConversation,
|
||||
max_tokens: 1024,
|
||||
});
|
||||
```
|
||||
|
||||
Every call to `client.messages.create()` compresses messages first. The response format is identical to the unwrapped client.
|
||||
|
||||
## How it works
|
||||
|
||||
`withHeadroom()` returns a proxy around your Anthropic client that intercepts `messages.create()`:
|
||||
|
||||
1. Converts Anthropic-format messages to OpenAI format (the compression engine's native format)
|
||||
2. Sends them to the Headroom proxy's `/v1/compress` endpoint
|
||||
3. Converts the compressed messages back to Anthropic format
|
||||
4. Forwards the request to Anthropic as normal
|
||||
|
||||
### Message format conversion
|
||||
|
||||
The adapter handles the full Anthropic message format including content blocks:
|
||||
|
||||
| Anthropic format | OpenAI format |
|
||||
|-----------------|---------------|
|
||||
| `{ type: "text", text: "..." }` | `{ role: "user", content: "..." }` |
|
||||
| `{ type: "tool_use", id, name, input }` | `{ tool_calls: [{ id, function: { name, arguments } }] }` |
|
||||
| `{ type: "tool_result", tool_use_id, content }` | `{ role: "tool", tool_call_id, content }` |
|
||||
|
||||
This conversion is lossless. Your request and response behave identically to an unwrapped client.
|
||||
|
||||
## Options
|
||||
|
||||
Pass compression options as the second argument:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/anthropic';
|
||||
import Anthropic from '@anthropic-ai/sdk';
|
||||
|
||||
const client = withHeadroom(new Anthropic(), {
|
||||
model: 'claude-sonnet-4-5-20250929',
|
||||
baseUrl: 'http://localhost:8787',
|
||||
});
|
||||
```
|
||||
|
||||
## Streaming
|
||||
|
||||
Streaming works normally. Compression happens before the request:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/anthropic';
|
||||
import Anthropic from '@anthropic-ai/sdk';
|
||||
|
||||
const client = withHeadroom(new Anthropic());
|
||||
|
||||
const stream = await client.messages.create({
|
||||
model: 'claude-sonnet-4-5-20250929',
|
||||
messages: longConversation,
|
||||
max_tokens: 1024,
|
||||
stream: true,
|
||||
});
|
||||
```
|
||||
|
||||
## Tool use
|
||||
|
||||
Tool results are where compression has the biggest impact. Large JSON payloads from tool calls are compressed automatically:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/anthropic';
|
||||
import Anthropic from '@anthropic-ai/sdk';
|
||||
|
||||
const client = withHeadroom(new Anthropic());
|
||||
|
||||
const response = await client.messages.create({
|
||||
model: 'claude-sonnet-4-5-20250929',
|
||||
max_tokens: 1024,
|
||||
messages: [
|
||||
{ role: 'user', content: 'What went wrong?' },
|
||||
{
|
||||
role: 'assistant',
|
||||
content: [
|
||||
{ type: 'tool_use', id: 'toolu_1', name: 'get_logs', input: { service: 'api' } },
|
||||
],
|
||||
},
|
||||
{
|
||||
role: 'user',
|
||||
content: [
|
||||
{
|
||||
type: 'tool_result',
|
||||
tool_use_id: 'toolu_1',
|
||||
content: hugeLogOutput, // Compressed automatically
|
||||
},
|
||||
],
|
||||
},
|
||||
],
|
||||
tools: [{ name: 'get_logs', description: 'Get logs', input_schema: { type: 'object', properties: {} } }],
|
||||
});
|
||||
```
|
||||
|
|
@ -1,785 +0,0 @@
|
|||
---
|
||||
title: API Reference
|
||||
description: 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.
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
baseUrl: { type: 'string', description: 'Base URL for the Headroom proxy' },
|
||||
apiKey: { type: 'string', description: 'API key for authentication' },
|
||||
timeout: { type: 'number', description: 'Request timeout in milliseconds' },
|
||||
fallback: { type: 'boolean', description: 'Return original messages on failure instead of throwing' },
|
||||
retries: { type: 'number', description: 'Number of retry attempts on failure' },
|
||||
}} />
|
||||
|
||||
```ts twoslash
|
||||
import { HeadroomClient } from 'headroom-ai';
|
||||
|
||||
const client = new HeadroomClient({
|
||||
baseUrl: 'http://localhost:8787',
|
||||
apiKey: 'your-api-key',
|
||||
timeout: 30_000,
|
||||
fallback: true,
|
||||
retries: 2,
|
||||
});
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
**Constructor Parameters**
|
||||
|
||||
<TypeTable type={{
|
||||
original_client: { type: 'OpenAI | Anthropic', description: 'The underlying LLM client', default: 'Required' },
|
||||
provider: { type: 'Provider', description: 'Token counting provider', default: 'Auto-detected' },
|
||||
default_mode: { type: '"audit" | "optimize"', description: 'Default compression mode', default: '"audit"' },
|
||||
store_url: { type: 'str | None', description: 'Storage URL for metrics database', default: 'None' },
|
||||
smart_crusher_config: { type: 'SmartCrusherConfig', description: 'Compression settings', default: 'Default config' },
|
||||
cache_aligner_config: { type: 'CacheAlignerConfig', description: 'Cache alignment settings', default: 'Default config' },
|
||||
rolling_window_config: { type: 'RollingWindowConfig', description: 'Context window settings', default: 'Default config' },
|
||||
enable_cache_optimizer: { type: 'bool', description: 'Enable provider-specific cache optimization', default: 'True' },
|
||||
enable_semantic_cache: { type: 'bool', description: 'Enable query-level semantic caching', default: 'False' },
|
||||
model_context_limits: { type: 'dict[str, int]', description: 'Override context limits per model', default: '{}' },
|
||||
}} />
|
||||
|
||||
```python
|
||||
from headroom import HeadroomClient, OpenAIProvider
|
||||
from openai import OpenAI
|
||||
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
default_mode="optimize",
|
||||
)
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### chat.completions.create()
|
||||
|
||||
Create a chat completion with optional optimization.
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
The TypeScript SDK uses `compress()` to optimize messages before sending them to your LLM client:
|
||||
|
||||
```ts twoslash
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
const result = await compress(messages, {
|
||||
model: 'gpt-4o',
|
||||
tokenBudget: 100_000,
|
||||
});
|
||||
|
||||
// Then pass result.messages to your LLM client
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
Accepts all standard OpenAI/Anthropic parameters plus Headroom-specific overrides:
|
||||
|
||||
<TypeTable type={{
|
||||
headroom_mode: { type: '"audit" | "optimize" | "simulate"', description: 'Override mode for this request', default: 'Client default' },
|
||||
headroom_query: { type: 'str', description: 'Query for relevance scoring', default: 'None' },
|
||||
headroom_output_buffer_tokens: { type: 'int', description: 'Reserve tokens for output', default: '4000' },
|
||||
headroom_keep_turns: { type: 'int', description: 'Keep last N turns uncompressed', default: '2' },
|
||||
headroom_tool_profiles: { type: 'dict', description: 'Per-tool compression overrides', default: '{}' },
|
||||
}} />
|
||||
|
||||
```python
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[...],
|
||||
headroom_mode="optimize",
|
||||
headroom_keep_turns=5,
|
||||
headroom_tool_profiles={
|
||||
"important_tool": {"skip_compression": True},
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### chat.completions.simulate()
|
||||
|
||||
Preview optimization without making an API call.
|
||||
|
||||
```python
|
||||
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.
|
||||
|
||||
<TypeTable type={{
|
||||
model: { type: 'string', description: 'Model name for token counting and context limits' },
|
||||
baseUrl: { type: 'string', description: 'Base URL for the Headroom proxy' },
|
||||
apiKey: { type: 'string', description: 'API key for authentication' },
|
||||
timeout: { type: 'number', description: 'Request timeout in milliseconds' },
|
||||
fallback: { type: 'boolean', description: 'Return original messages on failure instead of throwing' },
|
||||
retries: { type: 'number', description: 'Number of retry attempts on failure' },
|
||||
client: { type: 'HeadroomClientInterface', description: 'Pre-configured client instance to use' },
|
||||
tokenBudget: { type: 'number', description: 'Token budget — compress to fit within this limit' },
|
||||
hooks: { type: 'CompressionHooks', description: 'Compression hooks for pre/post processing' },
|
||||
}} />
|
||||
|
||||
```ts twoslash
|
||||
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).
|
||||
|
||||
```python
|
||||
stats = client.get_stats()
|
||||
# Returns dict with "session", "config", and "transforms" keys
|
||||
```
|
||||
|
||||
### get_metrics()
|
||||
|
||||
Query stored metrics from the database.
|
||||
|
||||
```python
|
||||
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.
|
||||
|
||||
```python
|
||||
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.
|
||||
|
||||
```python
|
||||
result = client.validate_setup()
|
||||
if not result["valid"]:
|
||||
for issue in result["issues"]:
|
||||
print(f" - {issue}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### SmartCrusherConfig
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
enabled: { type: 'boolean', description: 'Enable/disable the smart crusher' },
|
||||
minItemsToAnalyze: { type: 'number', description: 'Minimum items before analyzing for compression' },
|
||||
minTokensToCrush: { type: 'number', description: 'Minimum tokens before applying compression' },
|
||||
varianceThreshold: { type: 'number', description: 'Variance threshold for analysis' },
|
||||
uniquenessThreshold: { type: 'number', description: 'Uniqueness threshold for deduplication' },
|
||||
similarityThreshold: { type: 'number', description: 'Similarity threshold for grouping' },
|
||||
maxItemsAfterCrush: { type: 'number', description: 'Maximum items to keep after compression' },
|
||||
preserveChangePoints: { type: 'boolean', description: 'Preserve change points in data' },
|
||||
useFeedbackHints: { type: 'boolean', description: 'Use feedback hints for scoring' },
|
||||
toinConfidenceThreshold: { type: 'number', description: 'TOIN confidence threshold' },
|
||||
relevance: { type: 'RelevanceScorerConfig', description: 'Relevance scoring configuration' },
|
||||
anchor: { type: 'AnchorConfig', description: 'Anchor selection configuration' },
|
||||
dedupIdenticalItems: { type: 'boolean', description: 'Deduplicate identical items' },
|
||||
firstFraction: { type: 'number', description: 'Fraction of items to keep from the start' },
|
||||
lastFraction: { type: 'number', description: 'Fraction of items to keep from the end' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
<TypeTable type={{
|
||||
min_tokens_to_crush: { type: 'int', description: 'Minimum tokens before applying compression', default: '200' },
|
||||
max_items_after_crush: { type: 'int', description: 'Maximum items to keep after compression', default: '50' },
|
||||
keep_first: { type: 'int', description: 'Always keep first N items', default: '3' },
|
||||
keep_last: { type: 'int', description: 'Always keep last N items', default: '2' },
|
||||
relevance_threshold: { type: 'float', description: 'Minimum relevance score to keep', default: '0.3' },
|
||||
anomaly_std_threshold: { type: 'float', description: 'Std devs for anomaly detection', default: '2.0' },
|
||||
preserve_errors: { type: 'bool', description: 'Always keep error items', default: 'True' },
|
||||
relevance_tier: { type: '"bm25" | "embedding" | "hybrid"', description: 'Relevance scoring method', default: '"bm25"' },
|
||||
}} />
|
||||
|
||||
```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,
|
||||
)
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### CacheAlignerConfig
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
enabled: { type: 'boolean', description: 'Enable/disable cache alignment' },
|
||||
useDynamicDetector: { type: 'boolean', description: 'Use dynamic content detector' },
|
||||
detectionTiers: { type: '("regex" | "ner" | "semantic")[]', description: 'Detection tiers to apply' },
|
||||
extraDynamicLabels: { type: 'string[]', description: 'Additional labels for dynamic content detection' },
|
||||
entropyThreshold: { type: 'number', description: 'Entropy threshold for dynamic detection' },
|
||||
datePatterns: { type: 'string[]', description: 'Regex patterns for date extraction' },
|
||||
normalizeWhitespace: { type: 'boolean', description: 'Normalize whitespace for stable prefix' },
|
||||
collapseBlankLines: { type: 'boolean', description: 'Collapse consecutive blank lines' },
|
||||
dynamicTailSeparator: { type: 'string', description: 'Separator between static and dynamic content' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
<TypeTable type={{
|
||||
enabled: { type: 'bool', description: 'Enable/disable cache alignment', default: 'True' },
|
||||
extract_dates: { type: 'bool', description: 'Extract date patterns from system prompt', default: 'True' },
|
||||
normalize_whitespace: { type: 'bool', description: 'Normalize whitespace for stable prefix', default: 'True' },
|
||||
stable_prefix_min_tokens: { type: 'int', description: 'Minimum prefix tokens for caching', default: '100' },
|
||||
dynamic_patterns: { type: 'list[str]', description: 'Regex patterns to extract as dynamic content', default: '[]' },
|
||||
}} />
|
||||
|
||||
```python
|
||||
from headroom import CacheAlignerConfig
|
||||
|
||||
config = CacheAlignerConfig(
|
||||
enabled=True,
|
||||
extract_dates=True,
|
||||
normalize_whitespace=True,
|
||||
stable_prefix_min_tokens=100,
|
||||
)
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### RollingWindowConfig
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
enabled: { type: 'boolean', description: 'Enable/disable rolling window' },
|
||||
keepSystem: { type: 'boolean', description: 'Never drop system messages' },
|
||||
keepLastTurns: { type: 'number', description: 'Always keep last N turns' },
|
||||
outputBufferTokens: { type: 'number', description: 'Reserve tokens for model output' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
<TypeTable type={{
|
||||
enabled: { type: 'bool', description: 'Enable/disable rolling window', default: 'True' },
|
||||
max_tokens: { type: 'int', description: 'Maximum token budget', default: '100000' },
|
||||
preserve_system: { type: 'bool', description: 'Never drop system messages', default: 'True' },
|
||||
preserve_recent_turns: { type: 'int', description: 'Always keep last N turns', default: '5' },
|
||||
drop_oldest_first: { type: 'bool', description: 'Drop oldest messages first', default: 'True' },
|
||||
}} />
|
||||
|
||||
```python
|
||||
from headroom import RollingWindowConfig
|
||||
|
||||
config = RollingWindowConfig(
|
||||
max_tokens=100000,
|
||||
preserve_system=True,
|
||||
preserve_recent_turns=5,
|
||||
drop_oldest_first=True,
|
||||
)
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### IntelligentContextConfig
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
enabled: { type: 'boolean', description: 'Enable intelligent context management' },
|
||||
keepSystem: { type: 'boolean', description: 'Never drop system messages' },
|
||||
keepLastTurns: { type: 'number', description: 'Protect last N user turns' },
|
||||
outputBufferTokens: { type: 'number', description: 'Reserve tokens for model output' },
|
||||
useImportanceScoring: { type: 'boolean', description: 'Use semantic scoring vs position-only' },
|
||||
scoringWeights: { type: 'ScoringWeights', description: 'Custom importance weights' },
|
||||
recencyDecayRate: { type: 'number', description: 'Exponential decay lambda' },
|
||||
toinIntegration: { type: 'boolean', description: 'Use TOIN patterns if available' },
|
||||
toinConfidenceThreshold: { type: 'number', description: 'TOIN confidence threshold' },
|
||||
compressThreshold: { type: 'number', description: 'Try compression first if less than this fraction over budget' },
|
||||
summarizationEnabled: { type: 'boolean', description: 'Enable summarization of dropped messages' },
|
||||
summarizationModel: { type: 'string | null', description: 'Model to use for summarization' },
|
||||
summaryMaxTokens: { type: 'number', description: 'Maximum tokens for summary' },
|
||||
summarizeThreshold: { type: 'number', description: 'Threshold for triggering summarization' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
<TypeTable type={{
|
||||
enabled: { type: 'bool', description: 'Enable intelligent context management', default: 'False' },
|
||||
keep_system: { type: 'bool', description: 'Never drop system messages', default: 'True' },
|
||||
keep_last_turns: { type: 'int', description: 'Protect last N user turns', default: '2' },
|
||||
output_buffer_tokens: { type: 'int', description: 'Reserve tokens for model output', default: '4000' },
|
||||
use_importance_scoring: { type: 'bool', description: 'Use semantic scoring vs position-only', default: 'True' },
|
||||
scoring_weights: { type: 'ScoringWeights', description: 'Custom importance weights', default: 'Default weights' },
|
||||
toin_integration: { type: 'bool', description: 'Use TOIN patterns if available', default: 'True' },
|
||||
recency_decay_rate: { type: 'float', description: 'Exponential decay lambda', default: '0.1' },
|
||||
compress_threshold: { type: 'float', description: 'Try compression first if less than this fraction over budget', default: '0.1' },
|
||||
}} />
|
||||
|
||||
```python
|
||||
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,
|
||||
)
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### ScoringWeights
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
recency: { type: 'number', description: 'Exponential decay from conversation end' },
|
||||
semanticSimilarity: { type: 'number', description: 'Embedding cosine similarity to recent context' },
|
||||
toinImportance: { type: 'number', description: 'TOIN retrieval rate' },
|
||||
errorIndicator: { type: 'number', description: 'TOIN field semantics error detection' },
|
||||
forwardReference: { type: 'number', description: 'Messages referenced by later messages' },
|
||||
tokenDensity: { type: 'number', description: 'Unique tokens / total tokens' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
<TypeTable type={{
|
||||
recency: { type: 'float', description: 'Exponential decay from conversation end', default: '0.20' },
|
||||
semantic_similarity: { type: 'float', description: 'Embedding cosine similarity to recent context', default: '0.20' },
|
||||
toin_importance: { type: 'float', description: 'TOIN retrieval rate', default: '0.25' },
|
||||
error_indicator: { type: 'float', description: 'TOIN field semantics error detection', default: '0.15' },
|
||||
forward_reference: { type: 'float', description: 'Messages referenced by later messages', default: '0.15' },
|
||||
token_density: { type: 'float', description: 'Unique tokens / total tokens', default: '0.05' },
|
||||
}} />
|
||||
|
||||
Weights are automatically normalized to sum to 1.0.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### HeadroomConfig
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
storeUrl: { type: 'string', description: 'Storage URL for metrics database' },
|
||||
defaultMode: { type: 'HeadroomMode', description: 'Default compression mode' },
|
||||
modelContextLimits: { type: 'Record<string, number>', description: 'Override context limits per model' },
|
||||
toolCrusher: { type: 'ToolCrusherConfig', description: 'Tool crusher configuration' },
|
||||
smartCrusher: { type: 'SmartCrusherConfig', description: 'Smart crusher configuration' },
|
||||
cacheAligner: { type: 'CacheAlignerConfig', description: 'Cache aligner configuration' },
|
||||
rollingWindow: { type: 'RollingWindowConfig', description: 'Rolling window configuration' },
|
||||
cacheOptimizer: { type: 'CacheOptimizerConfig', description: 'Cache optimizer configuration' },
|
||||
ccr: { type: 'CCRConfig', description: 'CCR (Cross-Conversation Retrieval) configuration' },
|
||||
prefixFreeze: { type: 'PrefixFreezeConfig', description: 'Prefix freeze configuration' },
|
||||
contentRouterEnabled: { type: 'boolean', description: 'Enable content-type routing' },
|
||||
intelligentContext: { type: 'IntelligentContextConfig', description: 'Intelligent context management configuration' },
|
||||
generateDiffArtifact: { type: 'boolean', description: 'Generate diff artifacts for debugging' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
The top-level config object that contains all sub-configurations:
|
||||
|
||||
```python
|
||||
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
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### RelevanceScorerConfig
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
<TypeTable type={{
|
||||
tier: { type: 'RelevanceTier', description: 'Scoring method: "bm25" | "embedding" | "hybrid"' },
|
||||
bm25K1: { type: 'number', description: 'BM25 k1 parameter' },
|
||||
bm25B: { type: 'number', description: 'BM25 b parameter' },
|
||||
embeddingModel: { type: 'string', description: 'Model name for embedding scorer' },
|
||||
hybridAlpha: { type: 'number', description: 'Weight for hybrid scoring (0=embedding, 1=bm25)' },
|
||||
adaptiveAlpha: { type: 'boolean', description: 'Automatically adapt alpha based on query' },
|
||||
relevanceThreshold: { type: 'number', description: 'Minimum relevance score to keep' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
<TypeTable type={{
|
||||
scorer_type: { type: '"bm25" | "embedding" | "hybrid"', description: 'Scoring method', default: '"bm25"' },
|
||||
embedding_model: { type: 'str | None', description: 'Model name for embedding scorer', default: 'None' },
|
||||
hybrid_alpha: { type: 'float', description: 'Weight for hybrid scoring (0=embedding, 1=bm25)', default: '0.5' },
|
||||
}} />
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Results
|
||||
|
||||
### CompressResult (TypeScript)
|
||||
|
||||
<TypeTable type={{
|
||||
messages: { type: 'any[]', description: 'Compressed messages in the same format as input' },
|
||||
tokensBefore: { type: 'number', description: 'Token count before compression' },
|
||||
tokensAfter: { type: 'number', description: 'Token count after compression' },
|
||||
tokensSaved: { type: 'number', description: 'Tokens removed by compression' },
|
||||
compressionRatio: { type: 'number', description: 'Ratio of tokens after to tokens before' },
|
||||
transformsApplied: { type: 'string[]', description: 'Names of transforms that were applied' },
|
||||
ccrHashes: { type: 'string[]', description: 'CCR hashes for cross-conversation retrieval' },
|
||||
compressed: { type: 'boolean', description: 'Whether compression was actually applied' },
|
||||
}} />
|
||||
|
||||
### SimulationResult (Python)
|
||||
|
||||
<TypeTable type={{
|
||||
tokens_before: { type: 'int', description: 'Token count before compression' },
|
||||
tokens_after: { type: 'int', description: 'Token count after compression' },
|
||||
tokens_saved: { type: 'int', description: 'Tokens removed by compression' },
|
||||
savings_percent: { type: 'float', description: 'Percentage of tokens saved' },
|
||||
transforms_applied: { type: 'list[str]', description: 'Names of transforms that were applied' },
|
||||
waste_signals: { type: 'WasteSignals', description: 'Detected waste in the request' },
|
||||
}} />
|
||||
|
||||
### WasteSignals (Python)
|
||||
|
||||
<TypeTable type={{
|
||||
json_bloat_tokens: { type: 'int', description: 'Tokens from JSON formatting waste' },
|
||||
html_noise_tokens: { type: 'int', description: 'Tokens from HTML tags and noise' },
|
||||
whitespace_tokens: { type: 'int', description: 'Tokens from excessive whitespace' },
|
||||
dynamic_date_tokens: { type: 'int', description: 'Tokens from dynamic date strings' },
|
||||
repetition_tokens: { type: 'int', description: 'Tokens from repeated content' },
|
||||
}} />
|
||||
|
||||
### RequestMetrics (Python)
|
||||
|
||||
<TypeTable type={{
|
||||
request_id: { type: 'str', description: 'Unique request identifier' },
|
||||
timestamp: { type: 'datetime', description: 'When the request was processed' },
|
||||
model: { type: 'str', description: 'Model name used' },
|
||||
tokens_input_before: { type: 'int', description: 'Input tokens before compression' },
|
||||
tokens_input_after: { type: 'int', description: 'Input tokens after compression' },
|
||||
tokens_output: { type: 'int', description: 'Output tokens from the model' },
|
||||
cost_before: { type: 'float', description: 'Cost before compression (USD)' },
|
||||
cost_after: { type: 'float', description: 'Cost after compression (USD)' },
|
||||
transforms_applied: { type: 'list[str]', description: 'Transforms that were applied' },
|
||||
}} />
|
||||
|
||||
---
|
||||
|
||||
## Providers
|
||||
|
||||
### OpenAIProvider
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
from headroom import GoogleProvider
|
||||
|
||||
provider = GoogleProvider(
|
||||
enable_context_caching=True,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Relevance Scoring
|
||||
|
||||
### 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)
|
||||
```
|
||||
|
||||
### 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 `headroom-ai[relevance]`):
|
||||
|
||||
```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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
### RollingWindow
|
||||
|
||||
```python
|
||||
from headroom import RollingWindow
|
||||
|
||||
window = RollingWindow(config)
|
||||
result = window.apply(messages, max_tokens=100000)
|
||||
```
|
||||
|
||||
### IntelligentContextManager
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
from headroom import TransformPipeline
|
||||
|
||||
pipeline = TransformPipeline([
|
||||
SmartCrusher(),
|
||||
CacheAligner(),
|
||||
RollingWindow(),
|
||||
])
|
||||
|
||||
result = pipeline.transform(messages)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Errors
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
| 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.
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
| 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.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## 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 HTML/Markdown reports from stored metrics:
|
||||
|
||||
```python
|
||||
from headroom import generate_report
|
||||
|
||||
report = generate_report(
|
||||
store_url="sqlite:///headroom.db",
|
||||
format="html",
|
||||
period="day",
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TypeScript Message Types
|
||||
|
||||
<TypeTable type={{
|
||||
role: { type: '"system" | "user" | "assistant" | "tool"', description: 'The role of the message sender' },
|
||||
content: { type: 'string | ContentPart[] | null', description: 'Message content (string, content parts array, or null for tool-calling assistant messages)' },
|
||||
tool_calls: { type: 'ToolCall[]', description: 'Tool calls made by the assistant (assistant messages only)' },
|
||||
tool_call_id: { type: 'string', description: 'ID of the tool call this message responds to (tool messages only)' },
|
||||
}} />
|
||||
|
||||
The TypeScript SDK uses the standard OpenAI message format with `SystemMessage`, `UserMessage`, `AssistantMessage`, and `ToolMessage` variants.
|
||||
|
|
@ -1,131 +0,0 @@
|
|||
---
|
||||
title: Architecture
|
||||
description: How Headroom's three-stage compression pipeline works, from message parsing through transform execution to provider cache optimization.
|
||||
---
|
||||
|
||||
Headroom sits between your application and the LLM provider. It intercepts messages, compresses them intelligently, and forwards the optimized request. The response comes back unchanged.
|
||||
|
||||
## High-Level Flow
|
||||
|
||||
```
|
||||
+---------------------------------------------------------------+
|
||||
| YOUR APPLICATION |
|
||||
+---------------------------------------------------------------+
|
||||
|
|
||||
v
|
||||
+---------------------------------------------------------------+
|
||||
| HEADROOM CLIENT |
|
||||
| +-----------+ +------------+ +---------+ |
|
||||
| | ANALYZE | > | TRANSFORM | > | CALL | |
|
||||
| | (Parser) | | (Pipeline)| | (API) | |
|
||||
| +-----------+ +------------+ +---------+ |
|
||||
| | | | |
|
||||
| v v v |
|
||||
| Count tokens Apply compressions Send to LLM provider |
|
||||
| Detect waste Preserve meaning Log metrics |
|
||||
+---------------------------------------------------------------+
|
||||
|
|
||||
v
|
||||
+---------------------------------------------------------------+
|
||||
| OPENAI / ANTHROPIC / GOOGLE |
|
||||
+---------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Entry Points
|
||||
|
||||
Headroom can be used in three ways, all feeding into the same pipeline:
|
||||
|
||||
| Entry Point | How It Works | Code Changes |
|
||||
|-------------|-------------|--------------|
|
||||
| **SDK Mode** | Wrap your LLM client with `HeadroomClient` | Minimal -- swap client constructor |
|
||||
| **Proxy Mode** | Run `headroom proxy` and point your client at it | Zero -- just change the base URL |
|
||||
| **Integrations** | LangChain, Vercel AI SDK, Agno adapters | Framework-specific setup |
|
||||
|
||||
## The Transform Pipeline
|
||||
|
||||
Messages flow through a sequence of transforms. Each transform is independent, safe to skip, and fails gracefully (returns original content unchanged).
|
||||
|
||||
### Stage 1: Cache Aligner
|
||||
|
||||
Extracts dynamic content (dates, UUIDs, session tokens) from your system prompt and moves it to the end. This stabilizes the prefix so provider caches (Anthropic `cache_control`, OpenAI prefix caching) can hit on repeated calls.
|
||||
|
||||
```
|
||||
Before: "You are helpful. Current Date: 2024-12-15"
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Changes daily = cache miss every day
|
||||
|
||||
After: "You are helpful." [stable prefix]
|
||||
"[Context: Current Date: 2024-12-15]" [dynamic tail]
|
||||
```
|
||||
|
||||
Overhead: sub-millisecond.
|
||||
|
||||
### Stage 2: Smart Crusher
|
||||
|
||||
Analyzes tool output content and compresses it using statistical methods. This is where the bulk of token savings come from.
|
||||
|
||||
**What it does:**
|
||||
|
||||
1. Parses JSON arrays in tool outputs
|
||||
2. Runs field-level statistical analysis (variance, uniqueness, change points)
|
||||
3. Selects a representative subset using the Kneedle algorithm on bigram coverage
|
||||
4. Preserves errors, anomalies, and distribution boundaries unconditionally
|
||||
5. Factors out constant fields shared by all items
|
||||
|
||||
**Strategies by content type:**
|
||||
|
||||
| Content | Strategy | Typical Savings |
|
||||
|---------|----------|-----------------|
|
||||
| JSON arrays of dicts | Statistical sampling + anomaly preservation | 83--95% |
|
||||
| JSON arrays of strings | Dedup + adaptive sampling | 60--90% |
|
||||
| JSON arrays of numbers | Statistical summary + outlier preservation | 70--85% |
|
||||
| Build/test logs | Pattern clustering | 85--94% |
|
||||
| HTML | Article extraction (trafilatura-based) | ~95% |
|
||||
|
||||
**Item retention split:** 30% from array start (schema), 15% from end (recency), 55% by importance score. Error items are always kept regardless of budget.
|
||||
|
||||
Overhead: 1--50ms for typical payloads. Scales linearly with input size.
|
||||
|
||||
### Stage 3: Context Manager
|
||||
|
||||
Ensures the final message array fits within the model's context window.
|
||||
|
||||
**Rolling Window** (default): Drops oldest messages first, preserving system prompt and recent turns. Tool calls and their responses are dropped as atomic units.
|
||||
|
||||
**Intelligent Context** (advanced): Scores every message on six dimensions (recency, semantic similarity, TOIN importance, error indicators, forward references, token density) and drops the lowest-scored messages first. Dropped messages are stored in CCR for potential retrieval.
|
||||
|
||||
Overhead: sub-millisecond for Rolling Window; depends on scoring config for Intelligent Context.
|
||||
|
||||
## Provider Cache Optimization
|
||||
|
||||
After the pipeline, Headroom applies provider-specific cache hints:
|
||||
|
||||
| Provider | Mechanism | Savings |
|
||||
|----------|-----------|---------|
|
||||
| Anthropic | `cache_control` blocks on stable prefix | Up to 90% on cached tokens |
|
||||
| OpenAI | Prefix alignment for automatic caching | Up to 50% on cached tokens |
|
||||
| Google | `CachedContent` API | Up to 75% on cached tokens |
|
||||
|
||||
## CCR: Compress-Cache-Retrieve
|
||||
|
||||
When SmartCrusher compresses a tool output or Intelligent Context drops messages, the original content is stored in a local compression cache. If the LLM needs the full data, it can request retrieval via a `ccr_retrieve` tool call. This makes compression reversible.
|
||||
|
||||
```
|
||||
Compress: 1000 items -> 15 items (stored original in CCR)
|
||||
Cache: Hash-indexed local store (SQLite)
|
||||
Retrieve: LLM calls ccr_retrieve("abc123") -> original 1000 items
|
||||
```
|
||||
|
||||
## TOIN: Tool Output Intelligence Network
|
||||
|
||||
TOIN learns compression patterns across sessions and users. When a tool is used repeatedly, TOIN builds up statistics about which fields matter, which items get retrieved, and what compression strategies work best. These learned patterns feed back into SmartCrusher and Intelligent Context scoring.
|
||||
|
||||
Cold start: For new tool types, TOIN falls back to statistical heuristics. Patterns build up over time as tools are used.
|
||||
|
||||
## What Headroom Does NOT Touch
|
||||
|
||||
- **User messages**: Never compressed (the user's intent must be preserved exactly)
|
||||
- **System prompts**: Content preserved; only dynamic parts are relocated for caching
|
||||
- **Code**: Passes through unchanged unless tree-sitter AST compression is explicitly enabled
|
||||
- **Model responses**: Returned unchanged from the provider
|
||||
- **Short content**: Tool outputs under 200 tokens pass through (overhead exceeds savings)
|
||||
|
|
@ -1,150 +0,0 @@
|
|||
---
|
||||
title: Benchmarks
|
||||
description: Compression performance, accuracy preservation, latency overhead, and real-world production telemetry from 250+ Headroom proxy instances.
|
||||
---
|
||||
|
||||
Headroom's core promise: compress context without losing accuracy. This page covers compression benchmarks, accuracy evaluations, latency overhead, and production telemetry.
|
||||
|
||||
## Compression Performance
|
||||
|
||||
Tested on Apple M-series (CPU), Headroom v0.5.18. Each test runs `compress()` on realistic tool outputs.
|
||||
|
||||
| Content Type | Original | Compressed | Saved | Ratio | Latency |
|
||||
|---|---|---|---|---|---|
|
||||
| JSON array (100 items) | 3,163 | 297 | 2,866 | **90.6%** | 1ms |
|
||||
| JSON array (500 items) | 9,526 | 1,614 | 7,912 | **83.1%** | 2ms |
|
||||
| Shell output (200 lines) | 3,238 | 469 | 2,769 | **85.5%** | 1ms |
|
||||
| Build log (200 lines) | 2,412 | 148 | 2,264 | **93.9%** | 1ms |
|
||||
| grep results (150 hits) | 2,624 | 2,624 | 0 | 0.0% | <1ms |
|
||||
| Python source (~480 lines) | 2,958 | 2,958 | 0 | 0.0% | <1ms |
|
||||
| **Total** | **23,921** | **8,110** | **15,811** | **66.1%** | **5ms** |
|
||||
|
||||
<Callout type="info" title="Zero compression is intentional">
|
||||
grep results and Python source show 0% compression. These are already compact structured formats. SmartCrusher only compresses JSON arrays; code passes through to preserve correctness.
|
||||
</Callout>
|
||||
|
||||
## Accuracy Benchmarks
|
||||
|
||||
### HTML Extraction
|
||||
|
||||
**Dataset**: Scrapinghub Article Extraction Benchmark (181 HTML pages with ground truth)
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| **F1 Score** | 0.919 |
|
||||
| **Precision** | 0.879 |
|
||||
| **Recall** | 0.982 |
|
||||
| **Compression** | 94.9% |
|
||||
|
||||
For LLM applications, recall is critical -- 98.2% means nearly all article content is preserved. The slight precision drop (some extra content) does not hurt LLM accuracy.
|
||||
|
||||
### JSON Compression (SmartCrusher)
|
||||
|
||||
**Test**: 100 production log entries with critical error at position 67. Task: find the error, error code, resolution, and affected count.
|
||||
|
||||
| Metric | Baseline | Headroom |
|
||||
|---|---|---|
|
||||
| Input tokens | 10,144 | 1,260 |
|
||||
| Correct answers | 4/4 | **4/4** |
|
||||
| Compression | -- | **87.6%** |
|
||||
|
||||
SmartCrusher preserves first N items (schema), last N items (recency), all anomalies (errors, warnings), and statistical distribution.
|
||||
|
||||
### QA Accuracy Preservation
|
||||
|
||||
| Metric | Original HTML | Extracted | Delta |
|
||||
|---|---|---|---|
|
||||
| F1 Score | 0.85 | 0.87 | +0.02 |
|
||||
| Exact Match | 60% | 62% | +2% |
|
||||
|
||||
<Callout type="info" title="Extraction can improve accuracy">
|
||||
Removing HTML noise sometimes helps LLMs focus on relevant content, leading to slightly higher scores on extraction benchmarks.
|
||||
</Callout>
|
||||
|
||||
## Latency Overhead
|
||||
|
||||
### SDK Compression Latency
|
||||
|
||||
Measured per-scenario on Apple M-series (CPU):
|
||||
|
||||
| Scenario | Tokens In | Tokens Out | Saved | p50 (ms) | p95 (ms) |
|
||||
|----------|-----------|------------|-------|----------|----------|
|
||||
| JSON: Search Results (100 items) | 10.2K | 1.5K | 8.7K | 189 | 231 |
|
||||
| JSON: Search Results (500 items) | 50.2K | 1.5K | 48.7K | 943 | 955 |
|
||||
| JSON: Search Results (1K items) | 100.5K | 1.5K | 99.0K | 2,012 | 2,198 |
|
||||
| JSON: API Responses (500 items) | 38.9K | 1.1K | 37.8K | 743 | 776 |
|
||||
| JSON: Database Rows (1K rows) | 43.7K | 605 | 43.1K | 961 | 1,104 |
|
||||
| JSON: String Array (100 strings) | 1.1K | 231 | 820 | 15 | 15 |
|
||||
| JSON: String Array (500 strings) | 4.9K | 233 | 4.6K | 72 | 80 |
|
||||
| JSON: Number Array (200 numbers) | 1.2K | 192 | 1.1K | 31 | 62 |
|
||||
| JSON: Mixed Array (250 items) | 2.3K | 368 | 1.9K | 38 | 40 |
|
||||
|
||||
### Cost-Benefit Analysis
|
||||
|
||||
Net latency benefit = LLM time saved from fewer tokens minus compression overhead (at Claude Sonnet pricing, $3.0/MTok):
|
||||
|
||||
| Scenario | Compress (ms) | LLM Saved (ms) | Net Benefit | Savings per 1K Requests |
|
||||
|----------|---------------|-----------------|-------------|------------------------|
|
||||
| JSON: Search Results (100 items) | 189 | 261 | **+72ms** | $26 |
|
||||
| JSON: Search Results (500 items) | 943 | 1,461 | **+518ms** | $146 |
|
||||
| JSON: Search Results (1K items) | 2,012 | 2,969 | **+957ms** | $297 |
|
||||
| JSON: API Responses (500 items) | 743 | 1,134 | **+391ms** | $113 |
|
||||
| JSON: Database Rows (1K rows) | 961 | 1,292 | **+331ms** | $129 |
|
||||
|
||||
Compression pays for itself in latency for 11 of 12 tested scenarios against Claude Sonnet. Slower and more expensive models (Opus) benefit even more.
|
||||
|
||||
### Pipeline Step Timing
|
||||
|
||||
| Step | Median | P90 | Description |
|
||||
|------|--------|-----|-------------|
|
||||
| `pipeline_total` | 16.9ms | 289ms | Full compression pipeline |
|
||||
| `content_router` | 11.7ms | 259ms | Content detection + routing |
|
||||
| `smart_crusher` | 50.1ms | 50ms | JSON array compression |
|
||||
| `text_compressor` | 32.0ms | 576ms | Text compression (Kompress ONNX) |
|
||||
| `initial_token_count` | 2.9ms | 16ms | Token counting (tiktoken) |
|
||||
|
||||
ContentRouter accounts for 91--98% of pipeline cost on average. CacheAligner and RollingWindow are sub-millisecond.
|
||||
|
||||
## Production Telemetry
|
||||
|
||||
Real-world data from **50,000+ proxy sessions** across 250+ unique instances (March--April 2026). Collected via anonymous telemetry (opt-out: `HEADROOM_TELEMETRY=off`).
|
||||
|
||||
### Proxy Overhead
|
||||
|
||||
| Percentile | Latency |
|
||||
|---|---|
|
||||
| **Median (P50)** | **52ms** |
|
||||
| P90 | 309ms |
|
||||
| P99 | 4,172ms |
|
||||
| Mean | 161ms |
|
||||
|
||||
The median 52ms overhead is negligible compared to LLM inference time (typically 2--10 seconds).
|
||||
|
||||
### Compression Rate
|
||||
|
||||
| Percentile | Compression |
|
||||
|---|---|
|
||||
| P25 | 4.8% |
|
||||
| **Median** | **4.8%** |
|
||||
| P75 | 6.9% |
|
||||
| Mean | 11.3% |
|
||||
|
||||
Median compression is modest because many requests are short conversational turns. Heavy tool-use sessions (file reads, shell output) see 40--80% compression.
|
||||
|
||||
### Fleet Summary
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| Clean instances | 249 |
|
||||
| Total tokens saved | 1.4 billion |
|
||||
| Total savings | ~$4,000 |
|
||||
| OS distribution | Linux 57%, macOS 38%, Windows 5% |
|
||||
|
||||
## Reproducing Results
|
||||
|
||||
```bash
|
||||
git clone https://github.com/chopratejas/headroom.git
|
||||
cd headroom
|
||||
pip install -e ".[evals,html]"
|
||||
pytest tests/test_evals/ -v -s
|
||||
```
|
||||
|
|
@ -1,163 +0,0 @@
|
|||
---
|
||||
title: Cache Optimization
|
||||
description: Stabilize message prefixes for provider KV cache hits and configure provider-specific caching strategies.
|
||||
---
|
||||
|
||||
LLM providers cache prompt prefixes to avoid reprocessing identical input on repeated calls. Headroom's **CacheAligner** stabilizes your message prefixes so these caches actually hit, and then applies provider-specific strategies to maximize savings.
|
||||
|
||||
## How CacheAligner works
|
||||
|
||||
System prompts often contain dynamic content -- today's date, session IDs, timestamps -- that changes between requests. Even a single character difference at the start of a prompt invalidates the entire provider cache.
|
||||
|
||||
CacheAligner solves this by extracting dynamic content and moving it to the end of the message, keeping the prefix stable:
|
||||
|
||||
```
|
||||
Before:
|
||||
"You are helpful. Current Date: 2025-04-06" <- changes daily, no cache hit
|
||||
|
||||
After:
|
||||
"You are helpful." <- stable prefix, cache hit
|
||||
"[Context: Current Date: 2025-04-06]" <- dynamic part moved to tail
|
||||
```
|
||||
|
||||
The prefix stays byte-identical across requests, so the provider's KV cache can reuse previously computed attention states.
|
||||
|
||||
## Provider-specific strategies
|
||||
|
||||
Each LLM provider implements caching differently. Headroom applies the optimal strategy for each.
|
||||
|
||||
### Anthropic
|
||||
|
||||
Anthropic supports explicit `cache_control` blocks that mark content as cacheable. Cached input tokens cost **90% less** than regular input tokens.
|
||||
|
||||
Headroom automatically inserts `cache_control` breakpoints at the right positions in your messages so that stable prefixes (system prompts, early conversation turns) are cached across requests.
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| Cache read discount | 90% off input price |
|
||||
| Cache write cost | 25% premium on first write |
|
||||
| Cache TTL | 5 minutes (extended on hit) |
|
||||
|
||||
### OpenAI
|
||||
|
||||
OpenAI uses automatic **prefix caching** -- if consecutive requests share the same message prefix, the provider reuses cached KV states. No explicit API markers are needed, but the prefix must be byte-identical.
|
||||
|
||||
CacheAligner ensures your prefixes remain stable by extracting dynamic content, which is the key requirement for OpenAI prefix caching to work.
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| Cache read discount | 50% off input price |
|
||||
| Activation | Automatic (prefix match) |
|
||||
| Min prefix length | 1024 tokens |
|
||||
|
||||
### Google
|
||||
|
||||
Google provides the **CachedContent API**, which lets you explicitly cache large context (system instructions, documents, tools) and reference it across requests. Cached tokens cost **75% less**.
|
||||
|
||||
Headroom can manage CachedContent lifecycle automatically, creating and refreshing cached content objects as needed.
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| Cache read discount | 75% off input price |
|
||||
| Mechanism | Explicit CachedContent API objects |
|
||||
| Min cache size | 32,768 tokens |
|
||||
|
||||
## Configuration
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from "headroom-ai";
|
||||
import type {
|
||||
CacheAlignerConfig,
|
||||
CacheOptimizerConfig,
|
||||
HeadroomConfig,
|
||||
} from "headroom-ai";
|
||||
|
||||
// CacheAligner: stabilize prefixes for cache hits
|
||||
const cacheAligner: CacheAlignerConfig = {
|
||||
enabled: true,
|
||||
datePatterns: [
|
||||
"Today is \\w+ \\d+, \\d{4}",
|
||||
"Current time: .*",
|
||||
],
|
||||
normalizeWhitespace: true,
|
||||
collapseBlankLines: true,
|
||||
};
|
||||
|
||||
// CacheOptimizer: provider-level caching
|
||||
const cacheOptimizer: CacheOptimizerConfig = {
|
||||
enabled: true,
|
||||
autoDetectProvider: true, // Detect Anthropic/OpenAI/Google automatically
|
||||
minCacheableTokens: 1024,
|
||||
};
|
||||
|
||||
// Full configuration
|
||||
const config: HeadroomConfig = {
|
||||
cacheAligner,
|
||||
cacheOptimizer,
|
||||
};
|
||||
|
||||
// Compress with cache optimization
|
||||
const result = await compress(messages, {
|
||||
model: "claude-sonnet-4-20250514",
|
||||
config,
|
||||
});
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import HeadroomClient, OpenAIProvider, AnthropicProvider, GoogleProvider
|
||||
from headroom.transforms import CacheAlignerConfig
|
||||
from openai import OpenAI
|
||||
|
||||
# CacheAligner configuration
|
||||
aligner_config = CacheAlignerConfig(
|
||||
enabled=True,
|
||||
dynamic_patterns=[
|
||||
r"Today is \w+ \d+, \d{4}",
|
||||
r"Current time: .*",
|
||||
r"Session ID: [a-f0-9-]+",
|
||||
],
|
||||
)
|
||||
|
||||
# Provider-specific cache settings
|
||||
# OpenAI: prefix caching (automatic, just keep prefixes stable)
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(enable_prefix_caching=True),
|
||||
enable_cache_optimizer=True,
|
||||
)
|
||||
|
||||
# Anthropic: cache_control blocks (90% read discount)
|
||||
from anthropic import Anthropic
|
||||
|
||||
client = HeadroomClient(
|
||||
original_client=Anthropic(),
|
||||
provider=AnthropicProvider(enable_cache_control=True),
|
||||
enable_cache_optimizer=True,
|
||||
)
|
||||
|
||||
# Google: CachedContent API (75% read discount)
|
||||
client = HeadroomClient(
|
||||
original_client=google_client,
|
||||
provider=GoogleProvider(enable_context_caching=True),
|
||||
enable_cache_optimizer=True,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## How savings compound
|
||||
|
||||
CacheAligner and provider caching work together with Headroom's compression transforms:
|
||||
|
||||
1. **SmartCrusher** reduces token count by 70-90%
|
||||
2. **CacheAligner** stabilizes prefixes so provider caches hit
|
||||
3. **Provider caching** discounts the remaining input tokens by 50-90%
|
||||
|
||||
For example, with Anthropic:
|
||||
- 100K input tokens compressed to 20K (80% savings from SmartCrusher)
|
||||
- 18K of those 20K hit the cache (90% cache read discount)
|
||||
- Effective cost: 2K full-price tokens + 18K at 10% = 3.8K equivalent tokens
|
||||
- **Total savings: 96.2%** compared to the original 100K tokens
|
||||
|
|
@ -1,202 +0,0 @@
|
|||
---
|
||||
title: Reversible Compression (CCR)
|
||||
description: Compress-Cache-Retrieve architecture that makes compression lossless — the LLM can always get the original data back.
|
||||
---
|
||||
|
||||
Headroom's CCR (Compress-Cache-Retrieve) architecture makes compression **reversible**. When content is compressed, the original data is cached locally. If the LLM needs the full data, it retrieves it instantly.
|
||||
|
||||
<Callout type="info" title="Nothing is ever thrown away">
|
||||
Unlike traditional lossy compression, CCR guarantees that every piece of original data remains accessible. You get 70-90% token savings with zero risk of permanent data loss.
|
||||
</Callout>
|
||||
|
||||
## The problem with traditional compression
|
||||
|
||||
Traditional compression forces a difficult tradeoff:
|
||||
|
||||
- **Aggressive compression** risks losing data the LLM needs
|
||||
- **Conservative compression** misses out on token savings
|
||||
|
||||
CCR eliminates this tradeoff entirely. Compress aggressively, retrieve on demand.
|
||||
|
||||
## Architecture
|
||||
|
||||
CCR flows through four phases:
|
||||
|
||||
```
|
||||
TOOL OUTPUT (1000 items)
|
||||
-> SmartCrusher compresses to 20 items
|
||||
-> Original cached with hash=abc123
|
||||
-> Retrieval tool injected into context
|
||||
|
||||
LLM PROCESSING
|
||||
Option A: LLM solves task with 20 items -> Done (90% savings)
|
||||
Option B: LLM calls headroom_retrieve(hash=abc123)
|
||||
-> Response Handler returns full data automatically
|
||||
```
|
||||
|
||||
## Phase 1: Compression Store
|
||||
|
||||
When SmartCrusher compresses tool output:
|
||||
|
||||
1. The original content is stored in an LRU cache
|
||||
2. A hash key is generated for retrieval
|
||||
3. A marker is added to the compressed output:
|
||||
|
||||
```
|
||||
[1000 items compressed to 20. Retrieve more: hash=abc123]
|
||||
```
|
||||
|
||||
## Phase 2: Tool Injection
|
||||
|
||||
Headroom injects a `headroom_retrieve` tool into the LLM's available tools:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "headroom_retrieve",
|
||||
"description": "Retrieve original uncompressed data from Headroom cache",
|
||||
"parameters": {
|
||||
"hash": "The hash key from the compression marker",
|
||||
"query": "Optional: search within the cached data"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The LLM sees this tool alongside your application's tools and can call it whenever the compressed data is insufficient.
|
||||
|
||||
## Phase 3: Response Handler
|
||||
|
||||
When the LLM calls `headroom_retrieve`:
|
||||
|
||||
1. The Response Handler intercepts the tool call
|
||||
2. Data is retrieved from the local cache (around 1ms)
|
||||
3. The result is added to the conversation
|
||||
4. The API call continues automatically
|
||||
|
||||
The client never sees CCR tool calls -- they are handled transparently by Headroom.
|
||||
|
||||
## Phase 4: Context Tracker
|
||||
|
||||
Across multiple turns, the Context Tracker maintains awareness of all compressed content:
|
||||
|
||||
1. Remembers what was compressed in earlier turns
|
||||
2. Analyzes new queries for relevance to compressed content
|
||||
3. Proactively expands relevant data before the LLM asks
|
||||
|
||||
```
|
||||
Turn 1: User searches for files
|
||||
-> 500 files compressed to 15, cached (hash=abc123)
|
||||
-> LLM answers with 15 files
|
||||
|
||||
Turn 5: User asks "What about the auth middleware?"
|
||||
-> Context Tracker detects "auth" may match cached content
|
||||
-> Proactively expands compressed data
|
||||
-> LLM finds auth_middleware.py in the full list
|
||||
```
|
||||
|
||||
## BM25 search within compressed data
|
||||
|
||||
The LLM does not have to retrieve everything. It can search within compressed data using the optional `query` parameter:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "headroom_retrieve",
|
||||
"parameters": {
|
||||
"hash": "abc123",
|
||||
"query": "authentication errors"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This runs a BM25 search over the cached items, returning only the relevant subset instead of the full original payload.
|
||||
|
||||
## Retrieving originals
|
||||
|
||||
CCR works automatically through the proxy, but you can also retrieve cached data programmatically:
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from "headroom-ai";
|
||||
import type { CCRConfig } from "headroom-ai";
|
||||
|
||||
// CCR is enabled by default when compressing through the proxy.
|
||||
const result = await compress(messages, {
|
||||
model: "gpt-4o",
|
||||
});
|
||||
|
||||
// Access compressed messages — CCR markers are embedded automatically
|
||||
console.log(result.messages);
|
||||
|
||||
// CCR configuration options
|
||||
const ccrConfig: CCRConfig = {
|
||||
enabled: true,
|
||||
injectTool: true, // Inject headroom_retrieve tool
|
||||
injectRetrievalMarker: true, // Add retrieval markers to compressed output
|
||||
feedbackEnabled: true, // Learn from retrieval patterns
|
||||
storeMaxEntries: 1000, // Max cached items
|
||||
storeTtlSeconds: 3600, // Cache TTL
|
||||
};
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import HeadroomClient, OpenAIProvider
|
||||
from openai import OpenAI
|
||||
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
default_mode="optimize",
|
||||
)
|
||||
|
||||
# CCR happens automatically during chat completions.
|
||||
# The LLM calls headroom_retrieve when it needs more data.
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
)
|
||||
|
||||
# CCR is enabled by default in the current proxy path. Use --no-optimize for
|
||||
# full passthrough behavior.
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Message-level CCR
|
||||
|
||||
CCR is not limited to tool outputs. When IntelligentContext drops low-importance messages to fit the context budget, those messages are also stored in CCR:
|
||||
|
||||
```
|
||||
100-message conversation (50K tokens)
|
||||
-> IntelligentContext scores messages by importance
|
||||
-> Drops 60 low-scoring messages
|
||||
-> Dropped messages cached with hash=def456
|
||||
-> Marker inserted: "60 messages dropped, retrieve: def456"
|
||||
```
|
||||
|
||||
The marker includes the CCR reference so the LLM can recover earlier context:
|
||||
|
||||
```
|
||||
[Earlier context compressed: 60 message(s) dropped by importance scoring.
|
||||
Full content available via ccr_retrieve tool with reference 'def456'.]
|
||||
```
|
||||
|
||||
When users retrieve dropped messages via CCR, TOIN learns those message patterns are important and scores them higher in future sessions -- improving drop decisions across all users.
|
||||
|
||||
## CCR-enabled components
|
||||
|
||||
| Component | What it compresses | CCR integration |
|
||||
|---|---|---|
|
||||
| **SmartCrusher** | JSON arrays (tool outputs) | Stores original array, marker includes hash |
|
||||
| **ContentRouter** | Code, logs, search results, text | Stores original content by strategy |
|
||||
| **IntelligentContext** | Messages (conversation turns) | Stores dropped messages, marker includes hash |
|
||||
|
||||
## Why CCR matters
|
||||
|
||||
| Approach | Risk | Savings |
|
||||
|---|---|---|
|
||||
| No compression | None | 0% |
|
||||
| Traditional compression | Data loss | 70-90% |
|
||||
| CCR compression | None (reversible) | 70-90% |
|
||||
|
||||
CCR gives you the savings of aggressive compression with zero risk. The LLM can always retrieve the original data if needed.
|
||||
|
|
@ -1,173 +0,0 @@
|
|||
---
|
||||
title: Code Compression
|
||||
description: AST-aware compression that preserves imports, signatures, and types while compressing function bodies. Powered by tree-sitter.
|
||||
---
|
||||
|
||||
Headroom's CodeAwareCompressor uses tree-sitter to parse source code into an AST, then selectively compresses function bodies while preserving the structural elements that LLMs need -- imports, signatures, type annotations, and error handlers.
|
||||
|
||||
## Why AST-Aware Compression?
|
||||
|
||||
Naive truncation breaks code. Cutting a function in half leaves invalid syntax that confuses the LLM. CodeAwareCompressor guarantees:
|
||||
|
||||
- **Syntax validity** -- output always parses correctly
|
||||
- **Structural preservation** -- imports, signatures, types, decorators are kept intact
|
||||
- **Lightweight** -- ~50MB (tree-sitter) vs ~1GB for LLMLingua
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Tier | Languages | Support Level |
|
||||
|---|---|---|
|
||||
| Tier 1 | Python, JavaScript, TypeScript | Full AST analysis |
|
||||
| Tier 2 | Go, Rust, Java, C, C++ | Function body compression |
|
||||
|
||||
## What Gets Preserved vs Compressed
|
||||
|
||||
**Always preserved:**
|
||||
- Import statements
|
||||
- Function and method signatures
|
||||
- Class definitions
|
||||
- Type annotations
|
||||
- Decorators
|
||||
- Error handlers (`try`/`except`, `try`/`catch`)
|
||||
|
||||
**Compressed:**
|
||||
- Function bodies (implementations)
|
||||
- Comments (unless configured to preserve)
|
||||
- Verbose docstrings (configurable: full, first line, or removed)
|
||||
|
||||
## Example
|
||||
|
||||
```python
|
||||
from headroom.transforms import CodeAwareCompressor
|
||||
|
||||
compressor = CodeAwareCompressor()
|
||||
|
||||
code = '''
|
||||
import os
|
||||
from typing import List
|
||||
|
||||
def process_items(items: List[str]) -> List[str]:
|
||||
"""Process a list of items."""
|
||||
results = []
|
||||
for item in items:
|
||||
if not item:
|
||||
continue
|
||||
processed = item.strip().lower()
|
||||
results.append(processed)
|
||||
return results
|
||||
'''
|
||||
|
||||
result = compressor.compress(code, language="python")
|
||||
print(result.compressed)
|
||||
# import os
|
||||
# from typing import List
|
||||
#
|
||||
# def process_items(items: List[str]) -> List[str]:
|
||||
# """Process a list of items."""
|
||||
# results = []
|
||||
# for item in items:
|
||||
# # ... (5 lines compressed)
|
||||
# pass
|
||||
|
||||
print(f"Compression: {result.compression_ratio:.0%}") # ~55%
|
||||
print(f"Syntax valid: {result.syntax_valid}") # True
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
```python
|
||||
from headroom.transforms import CodeAwareCompressor, CodeCompressorConfig, DocstringMode
|
||||
|
||||
config = CodeCompressorConfig(
|
||||
preserve_imports=True, # Always keep imports
|
||||
preserve_signatures=True, # Always keep function signatures
|
||||
preserve_type_annotations=True, # Keep type hints
|
||||
preserve_error_handlers=True, # Keep try/except blocks
|
||||
preserve_decorators=True, # Keep decorators
|
||||
docstring_mode=DocstringMode.FIRST_LINE, # FULL, FIRST_LINE, REMOVE
|
||||
target_compression_rate=0.2, # Keep 20% of tokens
|
||||
max_body_lines=5, # Lines to keep per function body
|
||||
min_tokens_for_compression=100, # Skip small content
|
||||
language_hint=None, # Auto-detect if None
|
||||
fallback_to_kompress=True, # Use Kompress for unknown langs
|
||||
)
|
||||
|
||||
compressor = CodeAwareCompressor(config)
|
||||
result = compressor.compress(code)
|
||||
```
|
||||
|
||||
### Configuration Options
|
||||
|
||||
| Option | Default | Description |
|
||||
|---|---|---|
|
||||
| `preserve_imports` | `True` | Keep all import statements |
|
||||
| `preserve_signatures` | `True` | Keep function/method signatures |
|
||||
| `preserve_type_annotations` | `True` | Keep type hints |
|
||||
| `preserve_error_handlers` | `True` | Keep try/except blocks |
|
||||
| `preserve_decorators` | `True` | Keep decorators |
|
||||
| `docstring_mode` | `FIRST_LINE` | How to handle docstrings: `FULL`, `FIRST_LINE`, `REMOVE` |
|
||||
| `target_compression_rate` | `0.2` | Fraction of tokens to keep (0.2 = keep 20%) |
|
||||
| `max_body_lines` | `5` | Max lines to keep per function body |
|
||||
| `min_tokens_for_compression` | `100` | Skip files smaller than this |
|
||||
| `language_hint` | `None` | Override language detection |
|
||||
| `fallback_to_kompress` | `True` | Use Kompress for unsupported languages |
|
||||
|
||||
## Before and After
|
||||
|
||||
```python
|
||||
# Before (full source file)
|
||||
def process_data(items: List[str]) -> Dict[str, int]:
|
||||
"""Process items and count occurrences."""
|
||||
result = {}
|
||||
for item in items:
|
||||
item = item.strip().lower()
|
||||
if item in result:
|
||||
result[item] += 1
|
||||
else:
|
||||
result[item] = 1
|
||||
return result
|
||||
|
||||
# After (signature preserved, body compressed)
|
||||
def process_data(items: List[str]) -> Dict[str, int]:
|
||||
"""Process items and count occurrences."""
|
||||
result = {}
|
||||
for item in items:
|
||||
# ... (5 lines compressed)
|
||||
pass
|
||||
```
|
||||
|
||||
The LLM sees the function's purpose, its input/output types, and the general approach -- enough to reason about the code without needing every implementation line.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Install tree-sitter language pack
|
||||
pip install "headroom-ai[code]"
|
||||
```
|
||||
|
||||
## Memory Management
|
||||
|
||||
Tree-sitter parsers are lazy-loaded and cached. You can free memory when done:
|
||||
|
||||
```python
|
||||
from headroom.transforms import is_tree_sitter_available, unload_tree_sitter
|
||||
|
||||
# Check if tree-sitter is installed
|
||||
print(is_tree_sitter_available()) # True
|
||||
|
||||
# Free memory when done
|
||||
unload_tree_sitter()
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| Compression | 40-70% token reduction |
|
||||
| Speed | ~10-50ms per file |
|
||||
| Memory | ~50MB (tree-sitter parsers) |
|
||||
| Syntax validity | Guaranteed |
|
||||
|
||||
<Callout type="info" title="Automatic routing">
|
||||
When you use the Headroom proxy or call `compress()`, source code is automatically detected and routed to CodeAwareCompressor. Direct usage gives you control over compression settings per language.
|
||||
</Callout>
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
---
|
||||
title: Community Savings
|
||||
description: Aggregate savings from Headroom instances across the community. Anonymous telemetry data — no prompts, no content, no PII.
|
||||
---
|
||||
|
||||
Real-time aggregate metrics from Headroom proxy instances worldwide. All data is anonymous — only token counts, compression ratios, and cost estimates are collected. [Opt out anytime](https://github.com/chopratejas/headroom/blob/main/headroom/telemetry/beacon.py) with `HEADROOM_TELEMETRY=off`.
|
||||
|
||||
## Overview
|
||||
|
||||
<CommunityStatsHeader />
|
||||
|
||||
## Savings Over Time
|
||||
|
||||
<CommunityCharts section="area" />
|
||||
|
||||
## Top Savings by Instance
|
||||
|
||||
<CommunityCharts section="bar" />
|
||||
|
||||
## Instance Details
|
||||
|
||||
<CommunityCharts section="table" />
|
||||
|
|
@ -1,422 +0,0 @@
|
|||
---
|
||||
title: Configuration
|
||||
description: All configuration options for the Headroom Python and TypeScript SDKs, proxy server, and per-request overrides.
|
||||
---
|
||||
|
||||
Headroom can be configured via the SDK constructor, proxy command line, environment variables, or per-request overrides.
|
||||
|
||||
## CLI Context Tool
|
||||
|
||||
`headroom wrap ...` uses RTK for local shell-output filtering by default.
|
||||
Set `HEADROOM_CONTEXT_TOOL=lean-ctx` to have wrap commands install or reuse
|
||||
`lean-ctx` and run `lean-ctx init --agent <tool>` instead of RTK setup.
|
||||
|
||||
```bash
|
||||
export HEADROOM_CONTEXT_TOOL=lean-ctx
|
||||
headroom wrap claude
|
||||
headroom wrap codex --prepare-only
|
||||
```
|
||||
|
||||
Supported values are `rtk` and `lean-ctx`; unset defaults to `rtk`.
|
||||
|
||||
## Modes
|
||||
|
||||
| Mode | Behavior | Use Case |
|
||||
|------|----------|----------|
|
||||
| `audit` | Observes and logs, no modifications | Production monitoring, baseline measurement |
|
||||
| `optimize` | Applies safe, deterministic transforms | Production optimization |
|
||||
| `simulate` | Returns plan without API call | Testing, cost estimation |
|
||||
|
||||
## SDK Configuration
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { HeadroomClient } from 'headroom-ai';
|
||||
|
||||
// Reads from HEADROOM_BASE_URL and HEADROOM_API_KEY automatically
|
||||
const client = new HeadroomClient();
|
||||
|
||||
// Or configure explicitly
|
||||
const explicit = new HeadroomClient({
|
||||
baseUrl: 'http://localhost:8787',
|
||||
apiKey: 'your-api-key',
|
||||
timeout: 30_000,
|
||||
fallback: true,
|
||||
retries: 2,
|
||||
});
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import HeadroomClient, OpenAIProvider
|
||||
from openai import OpenAI
|
||||
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
|
||||
# Mode: "audit" (observe only) or "optimize" (apply transforms)
|
||||
default_mode="optimize",
|
||||
|
||||
# Enable provider-specific cache optimization
|
||||
enable_cache_optimizer=True,
|
||||
|
||||
# Enable query-level semantic caching
|
||||
enable_semantic_cache=False,
|
||||
|
||||
# Override default context limits per model
|
||||
model_context_limits={
|
||||
"gpt-4o": 128000,
|
||||
"gpt-4o-mini": 128000,
|
||||
},
|
||||
|
||||
# Database location (defaults to temp directory)
|
||||
# store_url="sqlite:////absolute/path/to/headroom.db",
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Per-Request Overrides
|
||||
|
||||
Override configuration for individual requests:
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
const result = await compress(messages, {
|
||||
model: 'gpt-4o',
|
||||
tokenBudget: 100_000,
|
||||
timeout: 15_000,
|
||||
});
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[...],
|
||||
|
||||
# Override mode for this request
|
||||
headroom_mode="audit",
|
||||
|
||||
# Reserve more tokens for output
|
||||
headroom_output_buffer_tokens=8000,
|
||||
|
||||
# Keep last N turns (don't compress)
|
||||
headroom_keep_turns=5,
|
||||
|
||||
# Skip compression for specific tools
|
||||
headroom_tool_profiles={
|
||||
"important_tool": {"skip_compression": True}
|
||||
},
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## SmartCrusher Configuration
|
||||
|
||||
Fine-tune JSON compression behavior:
|
||||
|
||||
```python
|
||||
from headroom.transforms import SmartCrusherConfig
|
||||
|
||||
config = SmartCrusherConfig(
|
||||
# Maximum items to keep after compression
|
||||
max_items_after_crush=15,
|
||||
|
||||
# Minimum tokens before applying compression
|
||||
min_tokens_to_crush=200,
|
||||
|
||||
# Relevance scoring tier: "bm25" (fast) or "embedding" (accurate)
|
||||
relevance_tier="bm25",
|
||||
|
||||
# Always keep items with these field values
|
||||
preserve_fields=["error", "warning", "failure"],
|
||||
)
|
||||
```
|
||||
|
||||
## CacheAligner Configuration
|
||||
|
||||
Control prefix stabilization for provider cache hit rates:
|
||||
|
||||
```python
|
||||
from headroom.transforms import CacheAlignerConfig
|
||||
|
||||
config = CacheAlignerConfig(
|
||||
# Enable/disable cache alignment
|
||||
enabled=True,
|
||||
|
||||
# Patterns to extract from system prompt
|
||||
dynamic_patterns=[
|
||||
r"Today is \w+ \d+, \d{4}",
|
||||
r"Current time: .*",
|
||||
],
|
||||
)
|
||||
```
|
||||
|
||||
## RollingWindow Configuration
|
||||
|
||||
Control context window management when messages exceed model limits:
|
||||
|
||||
```python
|
||||
from headroom.transforms import RollingWindowConfig
|
||||
|
||||
config = RollingWindowConfig(
|
||||
# Minimum turns to always keep
|
||||
min_keep_turns=3,
|
||||
|
||||
# Reserve tokens for output
|
||||
output_buffer_tokens=4000,
|
||||
|
||||
# Drop oldest tool outputs first
|
||||
prefer_drop_tool_outputs=True,
|
||||
)
|
||||
```
|
||||
|
||||
## IntelligentContext Configuration
|
||||
|
||||
Semantic-aware context management with importance scoring:
|
||||
|
||||
```python
|
||||
from headroom.config import IntelligentContextConfig, ScoringWeights
|
||||
|
||||
# Customize scoring weights (must sum to 1.0, or will be normalized)
|
||||
weights = ScoringWeights(
|
||||
recency=0.20, # Newer messages score higher
|
||||
semantic_similarity=0.20, # Similarity to recent context
|
||||
toin_importance=0.25, # TOIN-learned retrieval patterns
|
||||
error_indicator=0.15, # TOIN-learned error field types
|
||||
forward_reference=0.15, # Messages referenced by later messages
|
||||
token_density=0.05, # Information density
|
||||
)
|
||||
|
||||
config = IntelligentContextConfig(
|
||||
enabled=True,
|
||||
keep_system=True, # Never drop system messages
|
||||
keep_last_turns=2, # Protect last N user turns
|
||||
output_buffer_tokens=4000, # Reserve for model output
|
||||
use_importance_scoring=True,
|
||||
scoring_weights=weights,
|
||||
toin_integration=True, # Use TOIN patterns if available
|
||||
recency_decay_rate=0.1, # Exponential decay lambda
|
||||
compress_threshold=0.1, # Try compression first if <10% over budget
|
||||
)
|
||||
```
|
||||
|
||||
### Scoring Weights
|
||||
|
||||
<TypeTable type={{
|
||||
recency: { type: 'float', description: 'Exponential decay from conversation end', default: '0.20' },
|
||||
semantic_similarity: { type: 'float', description: 'Embedding cosine similarity to recent context', default: '0.20' },
|
||||
toin_importance: { type: 'float', description: 'TOIN retrieval_rate (high retrieval = important)', default: '0.25' },
|
||||
error_indicator: { type: 'float', description: 'TOIN field_semantics error detection', default: '0.15' },
|
||||
forward_reference: { type: 'float', description: 'Count of later messages referencing this one', default: '0.15' },
|
||||
token_density: { type: 'float', description: 'Unique tokens / total tokens', default: '0.05' },
|
||||
}} />
|
||||
|
||||
Weights are automatically normalized to sum to 1.0:
|
||||
|
||||
```python
|
||||
weights = ScoringWeights(recency=1.0, toin_importance=1.0)
|
||||
normalized = weights.normalized()
|
||||
# recency=0.5, toin_importance=0.5, others=0.0
|
||||
```
|
||||
|
||||
## Proxy Configuration
|
||||
|
||||
### Command Line Options
|
||||
|
||||
```bash
|
||||
headroom proxy \
|
||||
--port 8787 \ # Port to listen on
|
||||
--host 0.0.0.0 \ # Host to bind to
|
||||
--mode token \ # token compression mode; use cache for prefix-cache stability
|
||||
--budget 10.00 \ # Daily budget limit in USD
|
||||
--log-file headroom.jsonl # Log file path
|
||||
```
|
||||
|
||||
### Feature Flags
|
||||
|
||||
```bash
|
||||
# Disable optimization (passthrough mode)
|
||||
headroom proxy --no-optimize
|
||||
|
||||
# Disable semantic caching
|
||||
headroom proxy --no-cache
|
||||
|
||||
# Preserve provider prefix-cache stability instead of maximizing token removal
|
||||
headroom proxy --mode cache
|
||||
|
||||
# Enable memory and live learning
|
||||
headroom proxy --memory
|
||||
headroom proxy --learn --min-evidence 3
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `HEADROOM_HOST` | Proxy bind host | `127.0.0.1` |
|
||||
| `HEADROOM_PORT` | Proxy bind port | `8787` |
|
||||
| `HEADROOM_MODE` | Proxy optimization mode: `token` or `cache` | `token` |
|
||||
| `HEADROOM_WORKERS` | Uvicorn worker count | `1` |
|
||||
| `HEADROOM_LIMIT_CONCURRENCY` | Maximum concurrent connections before 503 | `1000` |
|
||||
| `HEADROOM_MAX_CONNECTIONS` | Maximum upstream HTTP connections | `500` |
|
||||
| `HEADROOM_MAX_KEEPALIVE` | Maximum upstream keep-alive connections | `100` |
|
||||
| `HEADROOM_BUDGET` | Daily budget limit in USD | -- |
|
||||
| `HEADROOM_TELEMETRY` | Set to `off` to disable anonymous telemetry | enabled |
|
||||
| `HEADROOM_STATELESS` | Set to `true` to disable filesystem writes | `false` |
|
||||
| `HEADROOM_MODEL_LIMITS` | Custom model config (JSON string or file path) | -- |
|
||||
| `HEADROOM_BASE_URL` | Base URL of the Headroom proxy (TypeScript SDK) | `http://localhost:8787` |
|
||||
| `HEADROOM_API_KEY` | API key for Headroom Cloud authentication | -- |
|
||||
| `HEADROOM_CONFIG_DIR` | Canonical config (read-mostly) root. Derives `models.json` and per-plugin config paths when set. | `~/.headroom/config` |
|
||||
| `HEADROOM_WORKSPACE_DIR` | Canonical workspace (read-write state) root. Derives savings, memory DB, logs, TOIN, subscription state, and more when set. | `~/.headroom` |
|
||||
| `HEADROOM_SAVINGS_PATH` | Override persistent savings file location. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |
|
||||
| `HEADROOM_TOIN_PATH` | Override TOIN telemetry file location. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |
|
||||
| `HEADROOM_SUBSCRIPTION_STATE_PATH` | Override subscription tracker state file. Always wins when set. | derived from `${HEADROOM_WORKSPACE_DIR}` |
|
||||
| `HEADROOM_TELEMETRY` | Set to `off` to disable anonymous telemetry | `on` |
|
||||
| `HEADROOM_MEMORY_INJECTION_MODE` | Memory-context routing mode: `live_zone_tail` (default) or `disabled`. The legacy `system_prompt` mode was retired by PR-A2; supplying it raises. | `live_zone_tail` |
|
||||
| `HEADROOM_PROXY_PYTHON_FORWARDER_MODE` | Python forwarder serialization mode. `byte_faithful` (default) forwards original request bytes verbatim when no transform mutated the body and re-serializes canonically only when needed — keeps Anthropic prompt-cache hit-rate intact. `legacy_json_kwarg` is an explicit operator opt-in for emergency rollback to the historical `httpx ... json=body` behavior. NOT a fallback — only flip on explicit operator decision. | `byte_faithful` |
|
||||
| `HEADROOM_STRIP_INTERNAL_HEADERS` | Python proxy: whether to strip internal `x-headroom-*` request headers (e.g. `x-headroom-bypass`, `x-headroom-mode`, `x-headroom-user-id`, `x-headroom-stack`, `x-headroom-base-url`) before every upstream forwarder call (PR-A5, fixes P5-49). `enabled` (default) stops fingerprinting / leakage. `disabled` is an explicit operator opt-in for diagnostic shadow tracing — NOT a fallback. Inbound reads of these headers (bypass gating, memory user-id resolution) are unaffected because they read `request.headers` directly. | `enabled` |
|
||||
| `HEADROOM_PROXY_STRIP_INTERNAL_HEADERS` | Rust proxy: same policy as `HEADROOM_STRIP_INTERNAL_HEADERS` but for the Rust transparent proxy. Stripping happens inside `build_forward_request_headers` so both HTTP and WebSocket upstream calls are gated by one flag. `enabled` default; `disabled` operator opt-in for diagnostic shadow tracing. Response-side `X-Headroom-*` injection (e.g. `x-headroom-tokens-saved`) is unrelated and stays. | `enabled` |
|
||||
|
||||
### Filesystem Contract
|
||||
|
||||
Headroom resolves every on-disk resource through a two-root model
|
||||
(`HEADROOM_CONFIG_DIR` + `HEADROOM_WORKSPACE_DIR`) with additive
|
||||
precedence rules: explicit argument > per-resource env var > derived
|
||||
from canonical root > default. Every legacy env var continues to work
|
||||
unchanged.
|
||||
|
||||
See the **[Filesystem Contract](https://github.com/chopratejas/headroom/blob/main/wiki/filesystem-contract.md)**
|
||||
page for the full bucket table, plugin-author guidance, and the Docker
|
||||
naming overlap note (`HEADROOM_WORKSPACE` is *not* the same as
|
||||
`HEADROOM_WORKSPACE_DIR`).
|
||||
|
||||
## Custom Model Configuration
|
||||
|
||||
Configure context limits and pricing for new or custom models:
|
||||
|
||||
```json
|
||||
{
|
||||
"anthropic": {
|
||||
"context_limits": {
|
||||
"claude-4-opus-20250301": 200000,
|
||||
"claude-custom-finetune": 128000
|
||||
},
|
||||
"pricing": {
|
||||
"claude-4-opus-20250301": {
|
||||
"input": 15.00,
|
||||
"output": 75.00,
|
||||
"cached_input": 1.50
|
||||
}
|
||||
}
|
||||
},
|
||||
"openai": {
|
||||
"context_limits": {
|
||||
"gpt-5": 256000,
|
||||
"ft:gpt-4o:my-org": 128000
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Save as `${HEADROOM_CONFIG_DIR}/models.json` (defaults to
|
||||
`~/.headroom/config/models.json`), or set `HEADROOM_MODEL_LIMITS` to a
|
||||
JSON string or file path. Installs that still have
|
||||
`~/.headroom/models.json` (the legacy location) continue to work.
|
||||
|
||||
Settings are resolved in this order (later overrides earlier):
|
||||
|
||||
1. Built-in defaults
|
||||
2. `${HEADROOM_CONFIG_DIR}/models.json` (new canonical location); falls
|
||||
back to `~/.headroom/models.json` (legacy) when the canonical file
|
||||
is absent
|
||||
3. `HEADROOM_MODEL_LIMITS` environment variable
|
||||
4. SDK constructor arguments
|
||||
|
||||
### Pattern-Based Inference
|
||||
|
||||
Unknown models are automatically inferred from naming patterns:
|
||||
|
||||
| Pattern | Inferred Settings |
|
||||
|---------|-------------------|
|
||||
| `*opus*` | 200K context, Opus-tier pricing |
|
||||
| `*sonnet*` | 200K context, Sonnet-tier pricing |
|
||||
| `*haiku*` | 200K context, Haiku-tier pricing |
|
||||
| `gpt-4o*` | 128K context, GPT-4o pricing |
|
||||
| `o1*`, `o3*` | 200K context, reasoning model pricing |
|
||||
|
||||
## Provider-Specific Settings
|
||||
|
||||
<Tabs groupId="lang" items={['OpenAI', 'Anthropic', 'Google']}>
|
||||
<Tab value="OpenAI">
|
||||
```python
|
||||
from headroom import OpenAIProvider
|
||||
|
||||
provider = OpenAIProvider(
|
||||
enable_prefix_caching=True,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Anthropic">
|
||||
```python
|
||||
from headroom import AnthropicProvider
|
||||
|
||||
provider = AnthropicProvider(
|
||||
enable_cache_control=True,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Google">
|
||||
```python
|
||||
from headroom import GoogleProvider
|
||||
|
||||
provider = GoogleProvider(
|
||||
enable_context_caching=True,
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Tool Profiles
|
||||
|
||||
Skip or customize compression for specific tools:
|
||||
|
||||
```python
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
headroom_tool_profiles={
|
||||
"important_tool": {"skip_compression": True},
|
||||
"search_tool": {"max_items_after_crush": 25},
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
## Configuration Precedence
|
||||
|
||||
Settings are applied in this order (later overrides earlier):
|
||||
|
||||
1. Default values
|
||||
2. Environment variables
|
||||
3. SDK constructor arguments
|
||||
4. Per-request overrides
|
||||
|
||||
## Validation
|
||||
|
||||
Validate your configuration at startup:
|
||||
|
||||
```python
|
||||
result = client.validate_setup()
|
||||
|
||||
if not result["valid"]:
|
||||
print("Configuration issues:")
|
||||
for issue in result["issues"]:
|
||||
print(f" - {issue}")
|
||||
```
|
||||
|
|
@ -1,188 +0,0 @@
|
|||
---
|
||||
title: Context Management
|
||||
description: Intelligent importance-based context management that scores messages by learned patterns, with rolling window fallback and output buffer reservation.
|
||||
---
|
||||
|
||||
When conversations grow beyond a model's context window, Headroom decides which messages to keep and which to drop. Instead of naively removing the oldest messages, **IntelligentContext** scores every message by learned importance and drops the least valuable ones first.
|
||||
|
||||
## IntelligentContext
|
||||
|
||||
IntelligentContext is a message-level compressor. It analyzes your conversation, assigns an importance score to each message, and removes low-scoring messages until the conversation fits within the token budget.
|
||||
|
||||
Dropped messages are not lost -- they are stored in [CCR](/docs/ccr) for on-demand retrieval by the LLM.
|
||||
|
||||
```
|
||||
100-message conversation (50K tokens) with a 32K budget
|
||||
-> Score each message by importance
|
||||
-> Drop 60 lowest-scoring messages
|
||||
-> Cache dropped messages in CCR (hash=def456)
|
||||
-> Insert marker: "60 messages dropped, retrieve: def456"
|
||||
-> Final context: 40 messages within budget
|
||||
```
|
||||
|
||||
## Scoring weights
|
||||
|
||||
Each message receives a weighted score from six factors:
|
||||
|
||||
| Weight | Default | Description |
|
||||
|---|---|---|
|
||||
| `recency` | 0.20 | Exponential decay from the end of the conversation. Recent messages score higher. |
|
||||
| `semantic_similarity` | 0.20 | Embedding cosine similarity to recent context. Messages related to the current topic score higher. |
|
||||
| `toin_importance` | 0.25 | TOIN retrieval rate -- messages matching patterns that users frequently retrieve via CCR are scored higher. Learned across all users. |
|
||||
| `error_indicator` | 0.15 | TOIN field semantics error detection. Messages containing error patterns (learned, not hardcoded) are preserved. |
|
||||
| `forward_reference` | 0.15 | Count of later messages that reference this one. Messages that other messages depend on are kept. |
|
||||
| `token_density` | 0.05 | Unique tokens divided by total tokens. Dense, information-rich messages score higher than repetitive ones. |
|
||||
|
||||
<Callout type="info" title="No hardcoded patterns">
|
||||
Error detection does not rely on keyword matching like "error" or "fail". Instead, it uses TOIN's learned `field_semantics.inferred_type` to identify error-bearing messages -- this adapts to your specific data patterns across sessions and users.
|
||||
</Callout>
|
||||
|
||||
Weights are automatically normalized to sum to 1.0, so you can set relative values without worrying about exact proportions.
|
||||
|
||||
## Rolling window fallback
|
||||
|
||||
If IntelligentContext is disabled or scoring data is unavailable, Headroom falls back to a **rolling window** strategy:
|
||||
|
||||
- Drop the oldest messages first
|
||||
- Always keep the system prompt
|
||||
- Always keep the last N user/assistant turns
|
||||
- Drop tool calls and their responses as atomic pairs (no orphaned tool data)
|
||||
|
||||
This provides a safe baseline that works without any learned data.
|
||||
|
||||
## Protection rules
|
||||
|
||||
Headroom enforces several protections to ensure model output quality:
|
||||
|
||||
### Output buffer reservation
|
||||
|
||||
A configurable number of tokens is reserved for the model's response. The context budget is calculated as:
|
||||
|
||||
```
|
||||
context_budget = model_context_limit - output_buffer_tokens
|
||||
```
|
||||
|
||||
This prevents the input from consuming the entire context window and leaving no room for the model to respond.
|
||||
|
||||
### System message protection
|
||||
|
||||
System messages are never dropped. They contain critical instructions, persona definitions, and tool descriptions that the model needs throughout the conversation.
|
||||
|
||||
### Turn protection
|
||||
|
||||
The last N user/assistant turns are always preserved, ensuring the model has immediate conversational context. By default, the last 2 turns are protected.
|
||||
|
||||
## Configuration
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from "headroom-ai";
|
||||
import type {
|
||||
IntelligentContextConfig,
|
||||
ScoringWeights,
|
||||
RollingWindowConfig,
|
||||
HeadroomConfig,
|
||||
} from "headroom-ai";
|
||||
|
||||
// Scoring weights (normalized automatically)
|
||||
const scoringWeights: ScoringWeights = {
|
||||
recency: 0.20,
|
||||
semanticSimilarity: 0.20,
|
||||
toinImportance: 0.25,
|
||||
errorIndicator: 0.15,
|
||||
forwardReference: 0.15,
|
||||
tokenDensity: 0.05,
|
||||
};
|
||||
|
||||
// IntelligentContext configuration
|
||||
const intelligentContext: IntelligentContextConfig = {
|
||||
enabled: true,
|
||||
keepSystem: true,
|
||||
keepLastTurns: 2,
|
||||
outputBufferTokens: 4000,
|
||||
useImportanceScoring: true,
|
||||
scoringWeights,
|
||||
toinIntegration: true,
|
||||
recencyDecayRate: 0.1,
|
||||
compressThreshold: 0.1,
|
||||
};
|
||||
|
||||
// Rolling window fallback
|
||||
const rollingWindow: RollingWindowConfig = {
|
||||
enabled: true,
|
||||
keepSystem: true,
|
||||
keepLastTurns: 3,
|
||||
outputBufferTokens: 4000,
|
||||
};
|
||||
|
||||
// Full configuration
|
||||
const config: HeadroomConfig = {
|
||||
intelligentContext,
|
||||
rollingWindow,
|
||||
};
|
||||
|
||||
const result = await compress(messages, {
|
||||
model: "gpt-4o",
|
||||
config,
|
||||
});
|
||||
|
||||
console.log(`Compressed: ${result.tokensBefore} -> ${result.tokensAfter}`);
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import HeadroomClient, OpenAIProvider
|
||||
from headroom.config import IntelligentContextConfig, ScoringWeights
|
||||
from openai import OpenAI
|
||||
|
||||
# Customize scoring weights
|
||||
weights = ScoringWeights(
|
||||
recency=0.20,
|
||||
semantic_similarity=0.20,
|
||||
toin_importance=0.25,
|
||||
error_indicator=0.15,
|
||||
forward_reference=0.15,
|
||||
token_density=0.05,
|
||||
)
|
||||
|
||||
context_config = IntelligentContextConfig(
|
||||
enabled=True,
|
||||
keep_system=True, # Never drop system messages
|
||||
keep_last_turns=2, # Protect last 2 user turns
|
||||
output_buffer_tokens=4000, # Reserve for model output
|
||||
use_importance_scoring=True,
|
||||
scoring_weights=weights,
|
||||
toin_integration=True, # Use TOIN patterns
|
||||
recency_decay_rate=0.1, # Exponential decay lambda
|
||||
compress_threshold=0.1, # Try compression first if <10% over budget
|
||||
)
|
||||
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
default_mode="optimize",
|
||||
)
|
||||
|
||||
# Per-request overrides
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
headroom_output_buffer_tokens=8000, # More room for long responses
|
||||
headroom_keep_turns=5, # Protect last 5 turns
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## How scoring improves over time
|
||||
|
||||
IntelligentContext integrates with TOIN (Tool-Output Intelligence Network) to learn from real usage:
|
||||
|
||||
1. Messages are dropped based on current scores
|
||||
2. Dropped messages are stored in CCR
|
||||
3. If the LLM retrieves a dropped message, TOIN records that pattern
|
||||
4. Future conversations score similar message patterns higher
|
||||
5. Drop accuracy improves across all users, not just within one session
|
||||
|
||||
This feedback loop means the system gets smarter the more it is used. Error messages that users frequently need are automatically preserved, while verbose success messages that nobody retrieves are dropped more aggressively.
|
||||
|
|
@ -1,201 +0,0 @@
|
|||
---
|
||||
title: Docker-Native Install
|
||||
description: Run Headroom without installing Python or Node.js on the host. A native `headroom` wrapper keeps the proxy and CLI in Docker while your other tools run on the host OS.
|
||||
---
|
||||
|
||||
Run Headroom without installing Python or Node.js on the host. The install scripts add a native `headroom` wrapper that keeps **Headroom itself** in Docker while orchestrating the rest of your workflow on the host OS.
|
||||
|
||||
## One-line install
|
||||
|
||||
### Linux
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### macOS (bash 4.3+)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.sh | "$(brew --prefix bash)/bin/bash"
|
||||
```
|
||||
|
||||
Stock `/bin/bash` on macOS is 3.2, so install a newer bash first (for example via Homebrew) and run the installer with that shell. The installed wrapper pins that same bash interpreter so later invocations stay on the supported runtime.
|
||||
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
irm https://raw.githubusercontent.com/chopratejas/headroom/main/scripts/install.ps1 | iex
|
||||
```
|
||||
|
||||
## What the installer does
|
||||
|
||||
1. Verifies Docker is installed and available.
|
||||
2. Pulls `ghcr.io/chopratejas/headroom:latest` by default, or reuses / pulls `HEADROOM_DOCKER_IMAGE` when you set a custom image override.
|
||||
3. Installs a `headroom` wrapper into `~/.local/bin` or `~/bin`.
|
||||
4. Updates shell startup files so the wrapper directory is on `PATH`.
|
||||
|
||||
The wrapper keeps Headroom inside Docker and mounts host state back into the container so native behavior stays consistent:
|
||||
|
||||
- project workspace → `/workspace`
|
||||
- `~/.headroom`
|
||||
- `~/.claude`
|
||||
- `~/.codex`
|
||||
- `~/.gemini`
|
||||
|
||||
Port `8787` stays the default, so `http://localhost:8787` works the same way as a native install.
|
||||
|
||||
Published releases also push versioned GHCR tags such as `ghcr.io/chopratejas/headroom:0.5.26`, and those images are built with the same synced package version used for the matching PyPI and npm release.
|
||||
|
||||
## How the wrapper behaves
|
||||
|
||||
### Native Headroom commands
|
||||
|
||||
These run directly inside the container:
|
||||
|
||||
```bash
|
||||
headroom proxy
|
||||
headroom learn
|
||||
headroom mcp install
|
||||
headroom memory list
|
||||
```
|
||||
|
||||
For `proxy`, the wrapper publishes the selected port back to the host:
|
||||
|
||||
```bash
|
||||
docker run --rm -it \
|
||||
-p 8787:8787 \
|
||||
-v "$PWD:/workspace" \
|
||||
-w /workspace \
|
||||
ghcr.io/chopratejas/headroom:latest \
|
||||
headroom proxy --host 0.0.0.0 --port 8787
|
||||
```
|
||||
|
||||
### `wrap` commands
|
||||
|
||||
`wrap` is host-oriented in Docker-native mode:
|
||||
|
||||
- the wrapper starts the Headroom proxy in Docker
|
||||
- container-side prep writes Headroom config, memory, and selected CLI context-tool setup into mounted host files
|
||||
- the target CLI itself is launched on the host by the wrapper
|
||||
|
||||
Supported host wrap flows:
|
||||
|
||||
- `headroom wrap claude`
|
||||
- `headroom wrap codex`
|
||||
- `headroom wrap aider`
|
||||
- `headroom wrap cursor`
|
||||
- `headroom wrap openclaw`
|
||||
- `headroom unwrap openclaw`
|
||||
|
||||
OpenClaw remains host-native in Docker-native mode:
|
||||
|
||||
- the host must already have the `openclaw` CLI installed
|
||||
- `headroom wrap openclaw` installs/configures the Headroom plugin through the host `openclaw` CLI
|
||||
- plugin auto-start still launches the installed host `headroom` wrapper from `PATH`, which then runs Headroom in Docker
|
||||
- local plugin source mode (`--plugin-path`) is also supported, but it may require host `npm` when build steps are needed
|
||||
|
||||
## Persistent Docker lifecycle from the native wrapper
|
||||
|
||||
The Docker-native `headroom` wrapper exposes the persistent Docker lifecycle directly:
|
||||
|
||||
```bash
|
||||
headroom install apply --profile default --preset persistent-docker
|
||||
headroom install status
|
||||
headroom install restart
|
||||
headroom install remove
|
||||
```
|
||||
|
||||
In Docker-native mode this surface is intentionally scoped to **persistent-docker**:
|
||||
|
||||
- supported: `apply`, `status`, `start`, `stop`, `restart`, `remove`
|
||||
- supported flags: `--profile`, `--port`, `--backend`, `--anyllm-provider`, `--region`, `--mode`, `--memory`, `--no-telemetry`, `--image`
|
||||
- not supported: `persistent-service`, `persistent-task`, or provider/user/system mutation flags such as `--scope`, `--providers`, and `--target`
|
||||
|
||||
Those broader lifecycle and config-mutation flows still belong to the Python-native `headroom install ...` command.
|
||||
|
||||
Persistent Docker deployments launched by the wrapper also tag the proxy process with deployment metadata, so `/health` reports the active `profile`, `preset`, `runtime`, `supervisor`, and `scope` the same way the Python install subsystem does.
|
||||
|
||||
## Docker Compose support
|
||||
|
||||
Use `docker/docker-compose.native.yml` when you want an explicit compose-managed proxy or CLI shell, or when you prefer compose over the native wrapper's `headroom install ...` surface.
|
||||
|
||||
### Persistent Docker runtime
|
||||
|
||||
The `proxy` service uses `restart: unless-stopped`, so compose can act as the always-on Docker runtime for Headroom:
|
||||
|
||||
```bash
|
||||
export HEADROOM_HOST_HOME="$HOME"
|
||||
export HEADROOM_WORKSPACE="$PWD"
|
||||
docker compose -f docker/docker-compose.native.yml up -d proxy
|
||||
```
|
||||
|
||||
```powershell
|
||||
$env:HEADROOM_HOST_HOME = $HOME
|
||||
$env:HEADROOM_WORKSPACE = (Get-Location).Path
|
||||
docker compose -f docker/docker-compose.native.yml up -d proxy
|
||||
```
|
||||
|
||||
This is a supported persistent-Docker path when you want the proxy managed explicitly through Compose instead of the installed wrapper.
|
||||
|
||||
<Callout type="info" title="HEADROOM_WORKSPACE vs HEADROOM_WORKSPACE_DIR">
|
||||
These are two different variables — both are set by the compose file, and both are retained for backward compatibility:
|
||||
|
||||
- **`HEADROOM_WORKSPACE`** (host-side) is the directory the compose file bind-mounts into the container as `/workspace`. It behaves like CWD in a native (non-Docker) run.
|
||||
- **`HEADROOM_WORKSPACE_DIR`** (inside the container) is the canonical Headroom state root from the [filesystem contract](/docs/filesystem-contract). The compose file sets it to `/tmp/headroom-home/.headroom` so the proxy resolves savings, logs, TOIN, and memory under the bind-mounted `${HOME}/.headroom`.
|
||||
|
||||
You do not need to set `HEADROOM_WORKSPACE_DIR` manually when using the shipped compose file — it is already in the `environment:` block.
|
||||
</Callout>
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
```bash
|
||||
export HEADROOM_HOST_HOME="$HOME"
|
||||
export HEADROOM_WORKSPACE="$PWD"
|
||||
docker compose -f docker/docker-compose.native.yml up proxy
|
||||
```
|
||||
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
$env:HEADROOM_HOST_HOME = $HOME
|
||||
$env:HEADROOM_WORKSPACE = (Get-Location).Path
|
||||
docker compose -f docker/docker-compose.native.yml up proxy
|
||||
```
|
||||
|
||||
You can also run one-off CLI commands through compose:
|
||||
|
||||
```bash
|
||||
docker compose -f docker/docker-compose.native.yml run --rm cli learn
|
||||
docker compose -f docker/docker-compose.native.yml run --rm cli mcp install
|
||||
```
|
||||
|
||||
## Environment passthrough
|
||||
|
||||
The wrapper forwards Headroom and provider environment variables into the container, including common prefixes such as:
|
||||
|
||||
- `HEADROOM_`
|
||||
- `ANTHROPIC_`
|
||||
- `OPENAI_`
|
||||
- `GEMINI_`
|
||||
- `AWS_`
|
||||
- `GOOGLE_` / `GOOGLE_CLOUD_`
|
||||
- `AZURE_`
|
||||
- `OTEL_`
|
||||
|
||||
That keeps provider auth and runtime config working without maintaining a separate env file for the container.
|
||||
|
||||
## Notes
|
||||
|
||||
- Docker is the only required Headroom runtime dependency on the host.
|
||||
- Wrapped tools like Claude Code, Codex CLI, Aider, and Cursor still run on the host when you use `headroom wrap ...`.
|
||||
- The install scripts are idempotent: rerunning them refreshes the wrapper and image without duplicating shell profile blocks.
|
||||
- For persistent service and task installs, use the Python-native `headroom install ...` workflow — see [Persistent Installs](/docs/persistent-installs).
|
||||
- For Docker-native `headroom install ...`, the wrapper persists its profile manifest under `~/.headroom/deploy/<profile>/`.
|
||||
|
||||
## Next steps
|
||||
|
||||
<Cards>
|
||||
<Card title="Quickstart" href="/docs/quickstart" />
|
||||
<Card title="Proxy Server" href="/docs/proxy" />
|
||||
<Card title="Installation (pip / npm / plain Docker)" href="/docs/installation" />
|
||||
</Cards>
|
||||
|
|
@ -1,276 +0,0 @@
|
|||
---
|
||||
title: Error Handling
|
||||
description: How to catch and handle Headroom errors in Python and TypeScript. Error hierarchy, proxy error mapping, and safety guarantees.
|
||||
---
|
||||
|
||||
Headroom provides explicit exceptions for debugging, with a core safety guarantee: **compression failures never break your LLM calls**. If compression fails, the original content passes through unchanged.
|
||||
|
||||
## Error Hierarchy
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
```
|
||||
HeadroomError (base class)
|
||||
+-- HeadroomConnectionError # Cannot reach proxy
|
||||
+-- HeadroomAuthError # 401 from proxy
|
||||
+-- HeadroomCompressError # Compression failed (with statusCode)
|
||||
+-- ConfigurationError # Invalid configuration
|
||||
+-- ProviderError # Provider issues
|
||||
+-- StorageError # Storage failures
|
||||
+-- TokenizationError # Token counting failed
|
||||
+-- CacheError # Cache operations failed
|
||||
+-- ValidationError # Validation failures
|
||||
+-- TransformError # Transform execution failed
|
||||
```
|
||||
|
||||
```ts twoslash
|
||||
import {
|
||||
HeadroomError,
|
||||
HeadroomConnectionError,
|
||||
HeadroomAuthError,
|
||||
HeadroomCompressError,
|
||||
ConfigurationError,
|
||||
ProviderError,
|
||||
mapProxyError,
|
||||
} from 'headroom-ai';
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
```
|
||||
HeadroomError (base class)
|
||||
+-- ConfigurationError # Invalid configuration
|
||||
+-- ProviderError # Provider issues (unknown model, etc.)
|
||||
+-- StorageError # Database/storage failures
|
||||
+-- CompressionError # Compression failures (rare)
|
||||
+-- ValidationError # Setup validation failures
|
||||
```
|
||||
|
||||
```python
|
||||
from headroom import (
|
||||
HeadroomError,
|
||||
ConfigurationError,
|
||||
ProviderError,
|
||||
StorageError,
|
||||
CompressionError,
|
||||
ValidationError,
|
||||
)
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Catching Errors
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
```ts twoslash
|
||||
import { compress, HeadroomConnectionError, HeadroomAuthError, HeadroomCompressError, HeadroomError } from 'headroom-ai';
|
||||
|
||||
try {
|
||||
const result = await compress(messages, { model: 'gpt-4o' });
|
||||
} catch (e) {
|
||||
if (e instanceof HeadroomConnectionError) {
|
||||
console.error('Cannot reach proxy:', e.message);
|
||||
} else if (e instanceof HeadroomAuthError) {
|
||||
console.error('Auth failed:', e.message);
|
||||
} else if (e instanceof HeadroomCompressError) {
|
||||
console.error(`Compress failed (${e.statusCode}):`, e.message);
|
||||
} else if (e instanceof HeadroomError) {
|
||||
console.error('Headroom error:', e.message, e.details);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
```python
|
||||
from headroom import (
|
||||
HeadroomClient,
|
||||
HeadroomError,
|
||||
ConfigurationError,
|
||||
StorageError,
|
||||
)
|
||||
|
||||
try:
|
||||
client = HeadroomClient(...)
|
||||
response = client.chat.completions.create(...)
|
||||
|
||||
except ConfigurationError as e:
|
||||
print(f"Config issue: {e}")
|
||||
print(f"Details: {e.details}")
|
||||
|
||||
except StorageError as e:
|
||||
print(f"Storage issue: {e}")
|
||||
# Headroom continues to work, just without metrics persistence
|
||||
|
||||
except HeadroomError as e:
|
||||
print(f"Headroom error: {e}")
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Error Types in Detail
|
||||
|
||||
### ConfigurationError
|
||||
|
||||
Raised when configuration is invalid.
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { ConfigurationError } from 'headroom-ai';
|
||||
|
||||
// ConfigurationError is thrown when the proxy returns
|
||||
// a configuration_error type in its error response
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
try:
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
default_mode="invalid_mode", # Will raise ConfigurationError
|
||||
)
|
||||
except ConfigurationError as e:
|
||||
print(f"Config error: {e}")
|
||||
print(f"Field: {e.details.get('field')}")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### ProviderError
|
||||
|
||||
Raised for provider-specific issues (unknown model, API error, token counting failure).
|
||||
|
||||
```python
|
||||
try:
|
||||
response = client.chat.completions.create(
|
||||
model="unknown-model-xyz",
|
||||
messages=[...],
|
||||
)
|
||||
except ProviderError as e:
|
||||
print(f"Provider error: {e}")
|
||||
print(f"Provider: {e.details.get('provider')}")
|
||||
```
|
||||
|
||||
### StorageError
|
||||
|
||||
Raised when database operations fail. Storage errors do not affect core functionality -- the application can continue without historical metrics.
|
||||
|
||||
```python
|
||||
try:
|
||||
metrics = client.get_metrics()
|
||||
except StorageError as e:
|
||||
metrics = [] # Continue without historical metrics
|
||||
```
|
||||
|
||||
### CompressionError
|
||||
|
||||
Raised when compression fails (rare). In practice, compression errors are caught internally and the original content passes through unchanged. This exception is only raised in strict mode.
|
||||
|
||||
### HeadroomConnectionError (TypeScript)
|
||||
|
||||
Raised when the TypeScript SDK cannot connect to the Headroom proxy.
|
||||
|
||||
```ts twoslash
|
||||
import { compress, HeadroomConnectionError } from 'headroom-ai';
|
||||
|
||||
try {
|
||||
await compress(messages, { model: 'gpt-4o' });
|
||||
} catch (e) {
|
||||
if (e instanceof HeadroomConnectionError) {
|
||||
console.error('Is the proxy running? Start with: headroom proxy');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Proxy Error Mapping
|
||||
|
||||
The TypeScript SDK automatically maps proxy error responses to the correct error class:
|
||||
|
||||
| HTTP Status | Proxy Error Type | TypeScript Class |
|
||||
|-------------|-----------------|-----------------|
|
||||
| 401 | -- | `HeadroomAuthError` |
|
||||
| 4xx/5xx | `configuration_error` | `ConfigurationError` |
|
||||
| 4xx/5xx | `provider_error` | `ProviderError` |
|
||||
| 4xx/5xx | `storage_error` | `StorageError` |
|
||||
| 4xx/5xx | `tokenization_error` | `TokenizationError` |
|
||||
| 4xx/5xx | `validation_error` | `ValidationError` |
|
||||
| 4xx/5xx | `transform_error` | `TransformError` |
|
||||
| 4xx/5xx | (other) | `HeadroomCompressError` |
|
||||
|
||||
The `mapProxyError()` function handles this mapping:
|
||||
|
||||
```ts twoslash
|
||||
import { mapProxyError } from 'headroom-ai';
|
||||
|
||||
const error = mapProxyError(400, 'configuration_error', 'Invalid mode');
|
||||
// Returns a ConfigurationError instance
|
||||
```
|
||||
|
||||
## Error Details
|
||||
|
||||
All Headroom exceptions include a `details` dict/object with additional context:
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { HeadroomError } from 'headroom-ai';
|
||||
|
||||
// HeadroomError.details is Record<string, any> | undefined
|
||||
// HeadroomCompressError also has .statusCode and .errorType
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
try:
|
||||
client = HeadroomClient(...)
|
||||
except HeadroomError as e:
|
||||
print(f"Error: {e}")
|
||||
print(f"Type: {type(e).__name__}")
|
||||
print(f"Details: {e.details}")
|
||||
# Details might include:
|
||||
# - field: which config field caused the error
|
||||
# - provider: which provider was involved
|
||||
# - model: which model was requested
|
||||
# - original_error: underlying exception
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Safety Guarantee
|
||||
|
||||
If compression fails, the original content passes through unchanged. Your LLM calls never fail due to Headroom:
|
||||
|
||||
```python
|
||||
messages = [
|
||||
{"role": "tool", "content": "malformed json {{{"}
|
||||
]
|
||||
|
||||
# This will NOT raise an exception
|
||||
# The malformed content passes through unchanged
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
)
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Catch specific exceptions** rather than broad `Exception` to avoid hiding real bugs
|
||||
2. **Let StorageError pass** -- storage errors do not affect core compression functionality
|
||||
3. **Validate on startup** with `client.validate_setup()` to catch configuration issues early
|
||||
4. **Enable logging** at WARNING level to see when compression is skipped
|
||||
|
||||
```python
|
||||
import logging
|
||||
logging.basicConfig(level=logging.WARNING)
|
||||
# WARNING:headroom.transforms.smart_crusher:Skipping compression: invalid JSON
|
||||
```
|
||||
|
|
@ -1,138 +0,0 @@
|
|||
---
|
||||
title: Failure Learning
|
||||
description: Offline failure analysis for coding agents. Analyzes past sessions, finds what went wrong, correlates with what fixed it, and writes project-level learnings.
|
||||
---
|
||||
|
||||
`headroom learn` analyzes past coding agent sessions, finds what went wrong, correlates each failure with what eventually worked, and writes specific project-level learnings that prevent the same mistakes next session.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# See recommendations for current project (dry-run, no changes)
|
||||
headroom learn
|
||||
|
||||
# Write recommendations to CLAUDE.md and MEMORY.md
|
||||
headroom learn --apply
|
||||
|
||||
# Analyze a specific project
|
||||
headroom learn --project ~/my-project --apply
|
||||
|
||||
# Analyze all projects
|
||||
headroom learn --all --apply
|
||||
```
|
||||
|
||||
## Success Correlation
|
||||
|
||||
The core innovation. Instead of cataloging failures ("Read failed 5 times"), Headroom finds what the model did to **fix** each failure:
|
||||
|
||||
- **Failed**: `Read axion-formats/src/main/java/.../FirstClassEntity.java`
|
||||
- **Then succeeded**: `Read axion-scala-common/src/main/scala/.../FirstClassEntity.scala`
|
||||
- **Learning**: "`FirstClassEntity` is at `axion-scala-common/`, not `axion-formats/`"
|
||||
|
||||
This produces specific, actionable corrections -- not generic advice.
|
||||
|
||||
## What It Learns
|
||||
|
||||
### Environment Facts
|
||||
|
||||
Which runtime commands work vs fail.
|
||||
|
||||
```markdown
|
||||
### Environment
|
||||
- **Python**: use `uv run python` (not `python3` -- modules not available outside venv)
|
||||
```
|
||||
|
||||
### File Path Corrections
|
||||
|
||||
Wrong paths the model keeps guessing, with the correct locations.
|
||||
|
||||
```markdown
|
||||
### File Path Corrections
|
||||
- `axion-common/src/.../AxionSparkConstants.scala`
|
||||
-> actually at `axion-spark-common/src/.../AxionSparkConstants.scala`
|
||||
```
|
||||
|
||||
### Search Scope
|
||||
|
||||
Which directories to search in (narrow paths fail, broader ones work).
|
||||
|
||||
```markdown
|
||||
### Search Scope
|
||||
- Don't search `axion-model/` -> use `axion/` (the repo root)
|
||||
```
|
||||
|
||||
### Command Patterns
|
||||
|
||||
How commands should (and should not) be run.
|
||||
|
||||
```markdown
|
||||
### Command Patterns
|
||||
- **user_prefers_manual**: User rejected gradle 18 times -- show the command, don't execute
|
||||
- **python_runtime**: Use `uv run python` not `python3` (ModuleNotFoundError)
|
||||
```
|
||||
|
||||
### Known Large Files
|
||||
|
||||
Files that need `offset`/`limit` with Read.
|
||||
|
||||
```markdown
|
||||
### Known Large Files
|
||||
- `proxy/server.py` (~8000 lines) -- always use offset/limit
|
||||
```
|
||||
|
||||
## Where Learnings Go
|
||||
|
||||
| Pattern | Destination | Why |
|
||||
|---------|-------------|-----|
|
||||
| Environment, paths, search scope, commands, large files | **CLAUDE.md** | Stable project facts, version-controllable |
|
||||
| Missing paths, retry patterns, permissions | **MEMORY.md** | May change, agent-specific |
|
||||
|
||||
CLAUDE.md lives in your project directory. MEMORY.md lives in `~/.claude/projects/*/memory/`.
|
||||
|
||||
## Marker-Based Updates
|
||||
|
||||
Headroom manages a clearly-delimited section in each file:
|
||||
|
||||
```markdown
|
||||
<!-- headroom:learn:start -->
|
||||
## Headroom Learned Patterns
|
||||
*Auto-generated by `headroom learn` -- do not edit manually*
|
||||
...
|
||||
<!-- headroom:learn:end -->
|
||||
```
|
||||
|
||||
On re-run, only the content between markers is replaced. Your existing file content is preserved.
|
||||
|
||||
## Architecture
|
||||
|
||||
The system is built with an adapter pattern so it can support multiple agent systems:
|
||||
|
||||
- **Scanners** read tool-specific log formats (e.g., `~/.claude/projects/*.jsonl`) and produce normalized `ToolCall` sequences
|
||||
- **Analyzers** work on `ToolCall` data -- same analysis logic for any agent system
|
||||
- **Writers** output to tool-specific context injection mechanisms (e.g., CLAUDE.md)
|
||||
|
||||
To add support for a new agent (e.g., Cursor), you write a Scanner that reads its log format and a Writer that outputs to `.cursorrules`. The analyzers stay the same.
|
||||
|
||||
## CLI Reference
|
||||
|
||||
```bash
|
||||
headroom learn [OPTIONS]
|
||||
|
||||
Options:
|
||||
--project PATH Project directory to analyze (default: current directory)
|
||||
--all Analyze all discovered projects
|
||||
--apply Write recommendations (default: dry-run)
|
||||
--claude-dir PATH Path to .claude directory (default: ~/.claude)
|
||||
```
|
||||
|
||||
## Real-World Results
|
||||
|
||||
Tested on 67,583 tool calls across 23 projects:
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Failure rate | 7.5% (5,066 failures) |
|
||||
| Corrections extracted | 164 per project (avg) |
|
||||
| Path corrections | 22 (axion project) |
|
||||
| Search scope corrections | 24 (axion project) |
|
||||
| Command patterns learned | 5 (axion project) |
|
||||
|
|
@ -1,147 +0,0 @@
|
|||
---
|
||||
title: Filesystem Contract
|
||||
description: Where Headroom writes config, runtime state, logs, and caches — the canonical two-root model, precedence rules, and Docker behavior.
|
||||
---
|
||||
|
||||
Headroom writes configuration, runtime state, logs, and caches to a small set of well-known paths under the user's home directory. This page is the source of truth for where those paths live, how to override them, and how they behave inside Docker containers.
|
||||
|
||||
## Two-root model
|
||||
|
||||
| Variable | Default | Purpose | Typical access |
|
||||
|---|---|---|---|
|
||||
| `HEADROOM_CONFIG_DIR` | `~/.headroom/config` | User/admin-authored configuration (model catalogs, plugin settings, etc.) | Read-mostly |
|
||||
| `HEADROOM_WORKSPACE_DIR` | `~/.headroom` | Runtime state written by the proxy and CLI (savings, logs, memory DB, telemetry, caches) | Read-write |
|
||||
|
||||
Both variables are recognized by the Python proxy / CLI and the npm SDK. They are **additive** — every pre-existing per-resource env var (`HEADROOM_SAVINGS_PATH`, `HEADROOM_TOIN_PATH`, `HEADROOM_SUBSCRIPTION_STATE_PATH`, `HEADROOM_MODEL_LIMITS`, ...) continues to work with identical semantics.
|
||||
|
||||
## Precedence
|
||||
|
||||
For every per-resource helper, resolution follows this order:
|
||||
|
||||
```
|
||||
explicit argument
|
||||
│ falls through when None/""
|
||||
▼
|
||||
per-resource env var (e.g. HEADROOM_SAVINGS_PATH)
|
||||
│ falls through when unset/blank
|
||||
▼
|
||||
derived from canonical root
|
||||
│ e.g. ${HEADROOM_WORKSPACE_DIR}/proxy_savings.json
|
||||
▼
|
||||
default (e.g. ~/.headroom/proxy_savings.json)
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
- `HEADROOM_WORKSPACE_DIR=/mnt/state` → savings land at `/mnt/state/proxy_savings.json` unless `HEADROOM_SAVINGS_PATH` overrides.
|
||||
- `HEADROOM_SAVINGS_PATH=/custom/savings.json` always wins, even when `HEADROOM_WORKSPACE_DIR` is set.
|
||||
- Unset both and the default is `~/.headroom/proxy_savings.json`.
|
||||
|
||||
## Bucket assignments
|
||||
|
||||
### Workspace bucket (`HEADROOM_WORKSPACE_DIR`)
|
||||
|
||||
| Resource | Default path | Legacy env var |
|
||||
|---|---|---|
|
||||
| Proxy savings ledger | `${WORKSPACE_DIR}/proxy_savings.json` | `HEADROOM_SAVINGS_PATH` |
|
||||
| TOIN telemetry JSON | `${WORKSPACE_DIR}/toin.json` | `HEADROOM_TOIN_PATH` |
|
||||
| Subscription tracker state | `${WORKSPACE_DIR}/subscription_state.json` | `HEADROOM_SUBSCRIPTION_STATE_PATH` |
|
||||
| Memory SQLite | `${WORKSPACE_DIR}/memory.db` | CLI `--memory-db-path` |
|
||||
| Native memory directory | `${WORKSPACE_DIR}/memories/` | `MemoryConfig.native_memory_dir` |
|
||||
| License cache | `${WORKSPACE_DIR}/license_cache.json` | — |
|
||||
| Session stats JSONL | `${WORKSPACE_DIR}/session_stats.jsonl` | — |
|
||||
| Memory sync state | `${WORKSPACE_DIR}/sync_state.json` | — |
|
||||
| Memory bridge state | `${WORKSPACE_DIR}/bridge_state.json` | — |
|
||||
| Proxy log directory | `${WORKSPACE_DIR}/logs/` | — |
|
||||
| HTTP 400 debug dumps | `${WORKSPACE_DIR}/logs/debug_400/` | — |
|
||||
| Vendored `rtk` binary | `${WORKSPACE_DIR}/bin/rtk[.exe]` | — |
|
||||
| Vendored `lean-ctx` binary | `${WORKSPACE_DIR}/bin/lean-ctx[.exe]` | — |
|
||||
| Deployment profiles | `${WORKSPACE_DIR}/deploy/` | — |
|
||||
| Beacon lock file | `${WORKSPACE_DIR}/.beacon_lock_<port>` | — |
|
||||
|
||||
### Config bucket (`HEADROOM_CONFIG_DIR`)
|
||||
|
||||
| Resource | Default path | Legacy env var |
|
||||
|---|---|---|
|
||||
| Models catalog | `${CONFIG_DIR}/models.json` | `HEADROOM_MODEL_LIMITS` (content override) |
|
||||
| Plugin settings | `${CONFIG_DIR}/plugins/<name>/...` | — |
|
||||
|
||||
### Backward compatibility — models.json
|
||||
|
||||
`models.json` historically lived at `~/.headroom/models.json` (i.e. in the workspace root, not in `config/`). For a seamless migration the Python providers check **both** locations in this order:
|
||||
|
||||
1. `${HEADROOM_CONFIG_DIR}/models.json` (new canonical location)
|
||||
2. `${HEADROOM_WORKSPACE_DIR}/models.json` (legacy fallback)
|
||||
|
||||
Existing installs continue to work unchanged. New installs are encouraged to put `models.json` in the config bucket.
|
||||
|
||||
## Plugin authors
|
||||
|
||||
Two helpers give plugins isolated, per-plugin directories under both roots:
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
from headroom import paths
|
||||
|
||||
cfg_dir = paths.plugin_config_dir("my-plugin")
|
||||
# → ~/.headroom/config/plugins/my-plugin
|
||||
|
||||
state_dir = paths.plugin_workspace_dir("my-plugin")
|
||||
# → ~/.headroom/plugins/my-plugin
|
||||
|
||||
cfg_dir.mkdir(parents=True, exist_ok=True)
|
||||
(cfg_dir / "settings.json").write_text("{}")
|
||||
```
|
||||
|
||||
### npm SDK
|
||||
|
||||
```typescript
|
||||
import { pluginConfigDir, pluginWorkspaceDir } from "@headroom/sdk";
|
||||
|
||||
const cfgDir = pluginConfigDir("my-plugin");
|
||||
const stateDir = pluginWorkspaceDir("my-plugin");
|
||||
```
|
||||
|
||||
Plugin-author helpers reject names containing `/` or `\` to keep the namespace flat.
|
||||
|
||||
## Docker naming overlap: `HEADROOM_WORKSPACE` vs `HEADROOM_WORKSPACE_DIR`
|
||||
|
||||
These are **two different variables** with different semantics, both retained for backward compatibility:
|
||||
|
||||
| Variable | Scope | Meaning |
|
||||
|---|---|---|
|
||||
| `HEADROOM_WORKSPACE` | Host-side (Docker) | Directory to bind-mount into the container as `/workspace` (equivalent to CWD in native runs). Used by `docker-compose.native.yml`. |
|
||||
| `HEADROOM_WORKSPACE_DIR` | Inside the container | Canonical Headroom state root. Resolves to `/tmp/headroom-home/.headroom` inside the official container image, which in turn bind-mounts to `${HOME}/.headroom` on the host. |
|
||||
|
||||
The official Docker bootstrap (compose file, `scripts/install.sh`, and the Python `install` command) sets `HEADROOM_WORKSPACE_DIR` and `HEADROOM_CONFIG_DIR` inside the container so the proxy resolves state to the bind-mounted path without any user action.
|
||||
|
||||
## Project-scoped `.headroom/` directories
|
||||
|
||||
A few code paths deliberately use **project-local** `.headroom/` paths resolved relative to the current working directory rather than the canonical workspace root:
|
||||
|
||||
- `headroom/proxy/server.py` — project-scoped memory DB default
|
||||
- `headroom/memory/mcp_server.py` — project-scoped memory DB default
|
||||
- `headroom/cli/wrap.py` — project-scoped memory and hook artifacts
|
||||
|
||||
These **do not obey** `HEADROOM_WORKSPACE_DIR`. This is intentional: it preserves the "project memory lives in the project directory" invariant. Users who want a single centrally located memory store can pass `--memory-db-path <path>` explicitly or set the path via the plugin API.
|
||||
|
||||
## Legacy per-resource env vars
|
||||
|
||||
Every legacy env var continues to work with its original semantics (raw string in, raw string out — no tilde expansion, no path-separator normalization), ensuring byte-for-byte backward compatibility.
|
||||
|
||||
Full list:
|
||||
|
||||
- `HEADROOM_SAVINGS_PATH`
|
||||
- `HEADROOM_TOIN_PATH`
|
||||
- `HEADROOM_SUBSCRIPTION_STATE_PATH`
|
||||
- `HEADROOM_MODEL_LIMITS` (content override — JSON string or file path)
|
||||
|
||||
## See also
|
||||
|
||||
<Cards>
|
||||
<Card title="Configuration" href="/docs/configuration" />
|
||||
<Card title="Docker-Native Install" href="/docs/docker-install" />
|
||||
<Card title="Persistent Installs" href="/docs/persistent-installs" />
|
||||
<Card title="Memory" href="/docs/memory" />
|
||||
</Cards>
|
||||
|
|
@ -1,160 +0,0 @@
|
|||
---
|
||||
title: How Compression Works
|
||||
description: Understand Headroom's three-stage compression pipeline, automatic content routing, and how different content types are compressed.
|
||||
---
|
||||
|
||||
Headroom automatically detects what kind of content you're sending and routes it to the right compressor. You don't need to configure anything -- just call `compress()` and the pipeline handles the rest.
|
||||
|
||||
## The Three-Stage Pipeline
|
||||
|
||||
Every request flows through three stages:
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌────────────────┐ ┌─────────────────────┐
|
||||
│ CacheAligner │────>│ ContentRouter │────>│ IntelligentContext │
|
||||
│ │ │ │ │ │
|
||||
│ Stabilize │ │ Detect type & │ │ Score messages & │
|
||||
│ prefix for │ │ route to best │ │ fit within token │
|
||||
│ cache hits │ │ compressor │ │ budget │
|
||||
└──────────────┘ └────────────────┘ └─────────────────────┘
|
||||
```
|
||||
|
||||
1. **CacheAligner** extracts dynamic content (dates, user context) from your system prompt so the static prefix stays cacheable across requests.
|
||||
2. **ContentRouter** inspects each tool output and routes it to the optimal compressor -- SmartCrusher for JSON arrays, CodeAwareCompressor for source code, LogCompressor for build output, and so on.
|
||||
3. **IntelligentContext** scores every message by importance (recency, semantic relevance, error indicators) and drops the lowest-value messages to fit within the model's context window.
|
||||
|
||||
## Content Type Detection
|
||||
|
||||
The router auto-detects content type by analyzing structure and patterns. No manual hints required.
|
||||
|
||||
| Content Type | Detection Signal | Compressor | Typical Savings |
|
||||
|---|---|---|---|
|
||||
| JSON arrays | Valid JSON with array elements | SmartCrusher | 70-90% |
|
||||
| Source code | Syntax patterns, indentation, keywords | CodeAwareCompressor | 40-70% |
|
||||
| Search results | `file:line:content` format | SearchCompressor | 80-95% |
|
||||
| Build/test logs | Timestamps, log levels, pytest/npm markers | LogCompressor | 85-95% |
|
||||
| Diffs | Unified diff format | DiffCompressor | 60-80% |
|
||||
| HTML | Tag structure | HTMLCompressor | 50-70% |
|
||||
| Plain text | Fallback | TextCompressor | 60-80% |
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from "headroom-ai";
|
||||
|
||||
const messages = [
|
||||
{ role: "system" as const, content: "You are a helpful assistant." },
|
||||
{ role: "user" as const, content: "Summarize this data" },
|
||||
{ role: "tool" as const, content: '{"results": [...]}', tool_call_id: "call_1" },
|
||||
];
|
||||
|
||||
const result = await compress(messages);
|
||||
console.log(`Tokens saved: ${result.tokensSaved}`);
|
||||
console.log(`Compression ratio: ${result.compressionRatio}`);
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom.compression import compress
|
||||
|
||||
result = compress(content)
|
||||
print(result.compressed)
|
||||
print(f"Saved {result.savings_percentage:.0f}% tokens")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Configuring the Compressor
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from "headroom-ai";
|
||||
|
||||
const result = await compress(messages, {
|
||||
model: "gpt-4o",
|
||||
tokenBudget: 50000,
|
||||
});
|
||||
|
||||
console.log(`Before: ${result.tokensBefore} tokens`);
|
||||
console.log(`After: ${result.tokensAfter} tokens`);
|
||||
console.log(`Transforms: ${result.transformsApplied.join(", ")}`);
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom.compression import UniversalCompressor, UniversalCompressorConfig
|
||||
|
||||
config = UniversalCompressorConfig(
|
||||
compression_ratio_target=0.5, # Keep 50% of content
|
||||
use_entropy_preservation=True, # Preserve UUIDs, hashes
|
||||
use_magika=True, # ML-based content detection
|
||||
ccr_enabled=True, # Store originals for retrieval
|
||||
)
|
||||
|
||||
compressor = UniversalCompressor(config=config)
|
||||
result = compressor.compress(content)
|
||||
|
||||
print(f"Type: {result.content_type}")
|
||||
print(f"Handler: {result.handler_used}")
|
||||
print(f"Saved: {result.savings_percentage:.0f}%")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Structure Preservation
|
||||
|
||||
Headroom doesn't blindly truncate. It identifies what matters in each content type and preserves it:
|
||||
|
||||
| Content Type | What's Preserved | What's Compressed |
|
||||
|---|---|---|
|
||||
| **JSON** | Keys, brackets, booleans, nulls, short values, UUIDs | Long string values, whitespace |
|
||||
| **Code** | Imports, function signatures, class definitions, types | Function bodies, comments |
|
||||
| **Logs** | Timestamps, log levels, error messages, stack traces | Repeated patterns, verbose details |
|
||||
| **Text** | High-entropy tokens (IDs, hashes), headers | Low-information content |
|
||||
|
||||
## Real Compression Ratios
|
||||
|
||||
| Content Type | Compression | Speed | What's Preserved |
|
||||
|---|---|---|---|
|
||||
| JSON (large arrays) | 70-90% | ~1ms | All keys, structure |
|
||||
| Source code (Python) | 50-70% | ~10ms | Signatures, imports |
|
||||
| Search results | 80-95% | ~2ms | Relevant matches |
|
||||
| Build logs | 85-95% | ~3ms | Errors, stack traces |
|
||||
| Plain text | 60-80% | ~5ms | High-entropy tokens |
|
||||
|
||||
## Batch Compression
|
||||
|
||||
For multiple contents, batch compression is more efficient:
|
||||
|
||||
```python
|
||||
from headroom.compression import UniversalCompressor
|
||||
|
||||
compressor = UniversalCompressor()
|
||||
|
||||
contents = [
|
||||
'{"users": [...]}',
|
||||
'def hello(): pass',
|
||||
'Plain text content',
|
||||
]
|
||||
|
||||
results = compressor.compress_batch(contents)
|
||||
|
||||
for result in results:
|
||||
print(f"{result.content_type}: {result.savings_percentage:.0f}% saved")
|
||||
```
|
||||
|
||||
## What Happens Under the Hood
|
||||
|
||||
When you call `compress()`, here is the full sequence:
|
||||
|
||||
1. **Content detection** -- Magika (ML-based) or pattern matching identifies the content type
|
||||
2. **Structure extraction** -- A handler extracts a structure mask marking what to preserve
|
||||
3. **Compression** -- Non-structural content is compressed (SmartCrusher, LLMLingua, or text utilities)
|
||||
4. **CCR storage** -- If enabled, the original is stored for retrieval when the LLM needs full context
|
||||
|
||||
<Callout type="info" title="Zero-config by default">
|
||||
The pipeline works out of the box with no configuration. All detection, routing, and compression happens automatically. Configuration is available when you need fine-grained control.
|
||||
</Callout>
|
||||
|
|
@ -1,152 +0,0 @@
|
|||
---
|
||||
title: Image Compression
|
||||
description: ML-powered image compression that reduces vision model token usage by 40-90% while maintaining answer accuracy.
|
||||
---
|
||||
|
||||
Vision models charge by the token, and images are expensive. A single 1024x1024 image costs ~765 tokens on OpenAI. Headroom's image compression uses a trained ML router to analyze your query and automatically select the optimal compression technique, saving 40-90% of image tokens.
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
User uploads image + asks question
|
||||
|
|
||||
[Query Analysis]
|
||||
TrainedRouter (MiniLM from HuggingFace)
|
||||
Classifies: "What animal is this?" -> full_low
|
||||
|
|
||||
[Image Analysis]
|
||||
SigLIP analyzes image properties
|
||||
(has text? complex? fine details?)
|
||||
|
|
||||
[Apply Compression]
|
||||
OpenAI: detail="low"
|
||||
Anthropic: Resize to 512px
|
||||
Google: Resize to 768px
|
||||
|
|
||||
Compressed request to LLM
|
||||
```
|
||||
|
||||
The router is a fine-tuned MiniLM classifier (`chopratejas/technique-router` on HuggingFace) with 93.7% accuracy across 1,157 training examples.
|
||||
|
||||
## Compression Techniques
|
||||
|
||||
| Technique | Savings | When Used | Example Query |
|
||||
|---|---|---|---|
|
||||
| `full_low` | ~87% | General understanding | "What is this?", "Describe the scene" |
|
||||
| `preserve` | 0% | Fine details needed | "Count the whiskers", "Read the serial number" |
|
||||
| `crop` | 50-90% | Region-specific queries | "What's in the corner?", "Focus on the background" |
|
||||
| `transcode` | ~99% | Text extraction | "Read the sign", "Transcribe the document" |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### With Headroom Proxy (Zero Code Changes)
|
||||
|
||||
```bash
|
||||
# Start the proxy
|
||||
headroom proxy --port 8787
|
||||
|
||||
# Connect your client -- images are compressed automatically
|
||||
ANTHROPIC_BASE_URL=http://localhost:8787 claude
|
||||
```
|
||||
|
||||
### With HeadroomClient
|
||||
|
||||
```python
|
||||
from headroom import HeadroomClient
|
||||
|
||||
client = HeadroomClient(provider="openai")
|
||||
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "What animal is this?"},
|
||||
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
|
||||
]
|
||||
}]
|
||||
)
|
||||
# Image automatically compressed with detail="low" (87% savings)
|
||||
```
|
||||
|
||||
### Direct API
|
||||
|
||||
```python
|
||||
from headroom.image import ImageCompressor
|
||||
|
||||
compressor = ImageCompressor()
|
||||
|
||||
# Compress images in messages
|
||||
compressed_messages = compressor.compress(messages, provider="openai")
|
||||
|
||||
# Check savings
|
||||
print(f"Saved {compressor.last_savings:.0f}% tokens")
|
||||
print(f"Technique: {compressor.last_result.technique.value}")
|
||||
```
|
||||
|
||||
## Provider Support
|
||||
|
||||
The compressor adapts its strategy per provider:
|
||||
|
||||
| Provider | Compression Method | Details |
|
||||
|---|---|---|
|
||||
| **OpenAI** | Sets `detail="low"` | Native detail parameter |
|
||||
| **Anthropic** | Resizes to 512px | PIL-based resize |
|
||||
| **Google Gemini** | Resizes to 768px | Optimized for Gemini's 768x768 tile system |
|
||||
|
||||
### Token Savings by Provider
|
||||
|
||||
**OpenAI** (1024x1024 image):
|
||||
|
||||
| Technique | Before | After | Savings |
|
||||
|---|---|---|---|
|
||||
| `full_low` | 765 tokens | 85 tokens | 89% |
|
||||
| `preserve` | 765 tokens | 765 tokens | 0% |
|
||||
|
||||
**Anthropic** (1024x1024 image):
|
||||
|
||||
| Before | After | Savings |
|
||||
|---|---|---|
|
||||
| ~1,398 tokens | ~349 tokens | 75% |
|
||||
|
||||
**Google Gemini** (1536x1536 image):
|
||||
|
||||
| Before | After | Savings |
|
||||
|---|---|---|
|
||||
| 1,032 tokens (4 tiles) | 258 tokens (1 tile) | 75% |
|
||||
|
||||
## Configuration
|
||||
|
||||
```python
|
||||
from headroom.image import ImageCompressor
|
||||
|
||||
compressor = ImageCompressor(
|
||||
model_id="chopratejas/technique-router", # HuggingFace model
|
||||
use_siglip=True, # Enable image analysis
|
||||
device="cuda", # Use GPU if available (auto, cuda, cpu, mps)
|
||||
)
|
||||
```
|
||||
|
||||
### Proxy Configuration
|
||||
|
||||
```bash
|
||||
# Image optimization is part of the ContentRouter path when the optional image
|
||||
# dependencies are installed. There are no public proxy CLI image toggles in
|
||||
# the current release.
|
||||
headroom proxy
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
| Metric | Value |
|
||||
|---|---|
|
||||
| Router inference | ~10ms (CPU), ~2ms (GPU) |
|
||||
| Image resize | ~5-20ms |
|
||||
| First request | +2-3s (model download, cached after) |
|
||||
| Router accuracy | 93.7% |
|
||||
| Model size | ~128MB |
|
||||
| GPU memory (SigLIP) | ~400MB |
|
||||
|
||||
<Callout type="info" title="Automatic with the proxy">
|
||||
When using the Headroom proxy, image compression happens automatically on every request that contains images. No code changes needed.
|
||||
</Callout>
|
||||
|
|
@ -1,109 +0,0 @@
|
|||
---
|
||||
title: Introduction
|
||||
description: Headroom is the context optimization layer for LLM applications. Compress tool outputs, DB results, file reads, and RAG results before they reach the model. Same answers, fraction of the tokens.
|
||||
---
|
||||
|
||||
<StatsSection />
|
||||
|
||||
Headroom compresses everything your AI agent reads -- tool outputs, database results, file reads, RAG retrievals, API responses -- before it reaches the LLM. The model sees less noise, responds faster, and costs less.
|
||||
|
||||
## Quick preview
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
const messages = [
|
||||
{ role: 'user' as const, content: 'Analyze these results' },
|
||||
];
|
||||
|
||||
const result = await compress(messages, { model: 'gpt-4o' });
|
||||
console.log(`Saved ${result.tokensSaved} tokens (${(result.compressionRatio * 100).toFixed(0)}%)`);
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import compress
|
||||
|
||||
result = compress(messages, model="gpt-4o")
|
||||
response = client.messages.create(
|
||||
model="gpt-4o",
|
||||
messages=result.messages,
|
||||
)
|
||||
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Community stats
|
||||
|
||||
<LiveStats />
|
||||
|
||||
## What gets compressed
|
||||
|
||||
| Content type | What happens | Typical savings |
|
||||
|---|---|---|
|
||||
| JSON arrays (tool outputs) | Statistical analysis keeps errors, anomalies, boundaries | 70--90% |
|
||||
| Source code | AST-aware compression preserves signatures, collapses bodies | 40--70% |
|
||||
| Build/test logs | Keeps failures and errors, drops passing noise | 80--95% |
|
||||
| Search results | Ranks by relevance, keeps top matches | 60--80% |
|
||||
| Plain text | ModernBERT token classification removes redundancy | 30--50% |
|
||||
| Git diffs | Preserves change hunks, drops unchanged context | 40--60% |
|
||||
| Images | ML router selects optimal resize/quality tradeoff | 40--90% |
|
||||
|
||||
## Where Headroom fits
|
||||
|
||||
```
|
||||
Your Agent / App
|
||||
|
|
||||
| tool outputs, logs, DB reads, RAG results, file reads, API responses
|
||||
v
|
||||
Headroom <-- proxy, Python library, TS SDK, or framework integration
|
||||
|
|
||||
v
|
||||
LLM Provider (OpenAI, Anthropic, Google, Bedrock, 100+ via LiteLLM)
|
||||
```
|
||||
|
||||
Headroom works as a **transparent proxy** (zero code changes), a **Python function** (`compress()`), a **TypeScript function** (`compress()`), or a **framework integration** (LangChain, Agno, Strands, LiteLLM, Vercel AI SDK, MCP).
|
||||
|
||||
## Real-world results
|
||||
|
||||
**100 production log entries. One critical error buried at position 67.**
|
||||
|
||||
| Metric | Baseline | Headroom |
|
||||
|---|---|---|
|
||||
| Input tokens | 10,144 | 1,260 |
|
||||
| Correct answers | **4/4** | **4/4** |
|
||||
|
||||
87.6% fewer tokens. Same answer. The FATAL error was automatically preserved -- not by keyword matching, but by statistical analysis of field variance.
|
||||
|
||||
| Scenario | Before | After | Savings |
|
||||
|---|---|---|---|
|
||||
| Code search (100 results) | 17,765 | 1,408 | **92%** |
|
||||
| SRE incident debugging | 65,694 | 5,118 | **92%** |
|
||||
| Codebase exploration | 78,502 | 41,254 | **47%** |
|
||||
| GitHub issue triage | 54,174 | 14,761 | **73%** |
|
||||
|
||||
## Key Features
|
||||
|
||||
<KeyFeatures />
|
||||
|
||||
## Framework Integrations
|
||||
|
||||
<FrameworkIntegrations />
|
||||
|
||||
## Nothing is lost
|
||||
|
||||
Compressed content goes into the CCR store (Compress-Cache-Retrieve). The LLM gets a `headroom_retrieve` tool and can fetch full originals when it needs more detail. Compression is aggressive but reversible.
|
||||
|
||||
## Next steps
|
||||
|
||||
<Cards>
|
||||
<Card title="Quickstart" href="/docs/quickstart" />
|
||||
<Card title="Installation" href="/docs/installation" />
|
||||
<Card title="Proxy Server" href="/docs/proxy" />
|
||||
<Card title="Vercel AI SDK" href="/docs/vercel-ai-sdk" />
|
||||
<Card title="LangChain" href="/docs/langchain" />
|
||||
<Card title="How Compression Works" href="/docs/how-compression-works" />
|
||||
</Cards>
|
||||
|
|
@ -1,194 +0,0 @@
|
|||
---
|
||||
title: Installation
|
||||
description: Install Headroom via pip, npm, or Docker. Includes all Python extras, TypeScript setup, Docker image tags, and environment variables.
|
||||
---
|
||||
|
||||
## Python
|
||||
|
||||
Headroom requires **Python 3.10+** and is published as `headroom-ai` on PyPI.
|
||||
Current release wheels are built for Python **3.10 through 3.13**. If your
|
||||
installer is using a newer Python, force a supported interpreter.
|
||||
|
||||
### Core package
|
||||
|
||||
```bash
|
||||
pip install headroom-ai
|
||||
```
|
||||
|
||||
The core package includes the `compress()` function, SmartCrusher, CacheAligner, and IntelligentContext. No heavy dependencies.
|
||||
|
||||
### Extras
|
||||
|
||||
Install only what you need, or grab everything with `[all]`:
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[all]"
|
||||
```
|
||||
|
||||
| Extra | What it adds | Install command |
|
||||
|---|---|---|
|
||||
| `proxy` | Proxy server, MCP tools, HTTP API | `pip install "headroom-ai[proxy]"` |
|
||||
| `ml` | Kompress (ModernBERT text compression, requires PyTorch) | `pip install "headroom-ai[ml]"` |
|
||||
| `code` | CodeCompressor (tree-sitter AST parsing) | `pip install "headroom-ai[code]"` |
|
||||
| `mcp` | MCP server tools (`headroom_compress`, `headroom_retrieve`, `headroom_stats`) | `pip install "headroom-ai[mcp]"` |
|
||||
| `langchain` | LangChain `HeadroomChatModel` wrapper | `pip install "headroom-ai[langchain]"` |
|
||||
| `agno` | Agno `HeadroomAgnoModel` wrapper | `pip install "headroom-ai[agno]"` |
|
||||
| `evals` | Evaluation framework (GSM8K, SQuAD, BFCL benchmarks) | `pip install "headroom-ai[evals]"` |
|
||||
| `all` | Everything above | `pip install "headroom-ai[all]"` |
|
||||
|
||||
You can combine extras:
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[proxy,langchain,ml]"
|
||||
```
|
||||
|
||||
### pipx
|
||||
|
||||
`pipx` creates one virtual environment per app. If that environment uses an
|
||||
unsupported Python version, `pipx` may resolve an older compatible Headroom
|
||||
release instead of the newest one.
|
||||
|
||||
Use Python 3.13 explicitly:
|
||||
|
||||
```bash
|
||||
pipx install --python python3.13 "headroom-ai[all]"
|
||||
```
|
||||
|
||||
For a pinned release:
|
||||
|
||||
```bash
|
||||
pipx install --python python3.13 "headroom-ai[all]==0.21.4"
|
||||
```
|
||||
|
||||
Check which Python an existing `pipx` environment uses:
|
||||
|
||||
```bash
|
||||
pipx list
|
||||
```
|
||||
|
||||
### Verify the install
|
||||
|
||||
```bash
|
||||
python -c "import headroom; print(headroom.__version__)"
|
||||
```
|
||||
|
||||
## TypeScript / Node.js
|
||||
|
||||
The TypeScript SDK is published as `headroom-ai` on npm. It requires **Node.js 18+**.
|
||||
|
||||
```bash
|
||||
npm install headroom-ai
|
||||
```
|
||||
|
||||
Or with other package managers:
|
||||
|
||||
```bash
|
||||
pnpm add headroom-ai
|
||||
yarn add headroom-ai
|
||||
```
|
||||
|
||||
<Callout type="info" title="The TS SDK needs a running proxy">
|
||||
The TypeScript SDK sends messages to the Headroom proxy over HTTP for compression. The proxy runs the full compression pipeline (Python). Start it before using the SDK:
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[proxy]"
|
||||
headroom proxy --port 8787
|
||||
```
|
||||
|
||||
Then point the SDK at it:
|
||||
|
||||
```ts
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
const result = await compress(messages, {
|
||||
baseUrl: 'http://localhost:8787',
|
||||
});
|
||||
```
|
||||
</Callout>
|
||||
|
||||
### Verify the install
|
||||
|
||||
```bash
|
||||
node -e "const h = require('headroom-ai'); console.log('headroom-ai loaded')"
|
||||
```
|
||||
|
||||
## Docker
|
||||
|
||||
Pre-built images are published to GitHub Container Registry on every release.
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/chopratejas/headroom:latest
|
||||
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest
|
||||
```
|
||||
|
||||
<Callout type="info" title="Running Headroom without installing Python or Node?">
|
||||
If you want a host `headroom` CLI that keeps Headroom itself inside a container — with mounted state, a one-line installer, and a persistent Docker lifecycle — see [Docker-Native Install](/docs/docker-install).
|
||||
</Callout>
|
||||
|
||||
### Image tags
|
||||
|
||||
| Tag | Extras | Base image | Description |
|
||||
|---|---|---|---|
|
||||
| `latest` | `proxy` | Debian slim | Default image, runs the proxy |
|
||||
| `<version>` | `proxy` | Debian slim | Pinned version |
|
||||
| `nonroot` | `proxy` | Debian slim | Runs as non-root user |
|
||||
| `code` | `proxy,code` | Debian slim | Includes tree-sitter for code compression |
|
||||
| `code-nonroot` | `proxy,code` | Debian slim | Code compression, non-root |
|
||||
| `slim` | `proxy` | Distroless | Minimal image, no shell |
|
||||
| `slim-nonroot` | `proxy` | Distroless | Minimal, non-root |
|
||||
| `code-slim` | `proxy,code` | Distroless | Code compression, minimal |
|
||||
| `code-slim-nonroot` | `proxy,code` | Distroless | Code compression, minimal, non-root |
|
||||
|
||||
### Build from source
|
||||
|
||||
Use Docker Bake for multi-variant builds:
|
||||
|
||||
```bash
|
||||
# List all targets
|
||||
docker buildx bake --list targets
|
||||
|
||||
# Build the default runtime image
|
||||
docker buildx bake runtime-default
|
||||
|
||||
# Build a specific variant with custom registry
|
||||
docker buildx bake runtime-code-slim-nonroot \
|
||||
--set '*.tags=my-registry/headroom:code-slim-nonroot'
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
|
||||
These variables configure Headroom at runtime. Set them in your shell, `.env` file, or container environment.
|
||||
|
||||
### LLM provider keys
|
||||
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `OPENAI_API_KEY` | OpenAI API key (used when proxying to OpenAI) |
|
||||
| `ANTHROPIC_API_KEY` | Anthropic API key (used when proxying to Anthropic) |
|
||||
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS credentials for Bedrock backend |
|
||||
| `GOOGLE_APPLICATION_CREDENTIALS` | Google Cloud credentials for Vertex AI backend |
|
||||
|
||||
### Proxy configuration
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `HEADROOM_PORT` | `8787` | Port the proxy listens on |
|
||||
| `HEADROOM_HOST` | `127.0.0.1` | Host the proxy binds to |
|
||||
| `HEADROOM_MODE` | `token` | Default optimization mode: `token` or `cache` |
|
||||
| `HEADROOM_TELEMETRY` | enabled | Set to `off` to disable anonymous telemetry |
|
||||
|
||||
### TypeScript SDK
|
||||
|
||||
| Variable | Default | Description |
|
||||
|---|---|---|
|
||||
| `HEADROOM_BASE_URL` | `http://localhost:8787` | Proxy URL for the TypeScript SDK |
|
||||
| `HEADROOM_API_KEY` | _(none)_ | API key if the proxy requires auth |
|
||||
|
||||
## Next steps
|
||||
|
||||
<Cards>
|
||||
<Card title="Quickstart" href="/docs/quickstart" />
|
||||
<Card title="Proxy Server" href="/docs/proxy" />
|
||||
<Card title="Configuration" href="/docs/configuration" />
|
||||
<Card title="Vercel AI SDK" href="/docs/vercel-ai-sdk" />
|
||||
</Cards>
|
||||
|
|
@ -1,188 +0,0 @@
|
|||
---
|
||||
title: LangChain
|
||||
description: Automatic context compression for LangChain chat models, memory, retrievers, and agents.
|
||||
---
|
||||
|
||||
Headroom integrates with LangChain to compress context across all LangChain patterns: chat models, memory, retrievers, agents, and streaming.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[langchain]"
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
Wrap any chat model in one line:
|
||||
|
||||
```python
|
||||
from langchain_openai import ChatOpenAI
|
||||
from headroom.integrations import HeadroomChatModel
|
||||
|
||||
llm = HeadroomChatModel(ChatOpenAI(model="gpt-4o"))
|
||||
|
||||
# Use exactly like before
|
||||
response = llm.invoke("Hello!")
|
||||
|
||||
# Check savings
|
||||
print(llm.get_metrics())
|
||||
# {'tokens_saved': 12500, 'savings_percent': 45.2, 'requests': 50}
|
||||
```
|
||||
|
||||
Works with any provider:
|
||||
|
||||
```python
|
||||
from langchain_anthropic import ChatAnthropic
|
||||
|
||||
llm = HeadroomChatModel(ChatAnthropic(model="claude-sonnet-4-20250514"))
|
||||
```
|
||||
|
||||
## Memory integration
|
||||
|
||||
`HeadroomChatMessageHistory` wraps any chat history with automatic compression. Long conversations stay under your token budget:
|
||||
|
||||
```python
|
||||
from langchain.memory import ConversationBufferMemory
|
||||
from langchain_community.chat_message_histories import ChatMessageHistory
|
||||
from headroom.integrations import HeadroomChatMessageHistory
|
||||
|
||||
base_history = ChatMessageHistory()
|
||||
compressed_history = HeadroomChatMessageHistory(
|
||||
base_history,
|
||||
compress_threshold_tokens=4000, # Compress when over 4K tokens
|
||||
keep_recent_turns=5, # Always keep last 5 turns
|
||||
)
|
||||
|
||||
memory = ConversationBufferMemory(chat_memory=compressed_history)
|
||||
```
|
||||
|
||||
After usage:
|
||||
|
||||
```python
|
||||
print(compressed_history.get_compression_stats())
|
||||
# {'compression_count': 12, 'total_tokens_saved': 28000}
|
||||
```
|
||||
|
||||
## Retriever integration
|
||||
|
||||
`HeadroomDocumentCompressor` filters retrieved documents by relevance. Retrieve many for recall, keep the best for precision:
|
||||
|
||||
```python
|
||||
from langchain.retrievers import ContextualCompressionRetriever
|
||||
from langchain_community.vectorstores import FAISS
|
||||
from headroom.integrations import HeadroomDocumentCompressor
|
||||
|
||||
base_retriever = vectorstore.as_retriever(search_kwargs={"k": 50})
|
||||
|
||||
compressor = HeadroomDocumentCompressor(
|
||||
max_documents=10,
|
||||
min_relevance=0.3,
|
||||
prefer_diverse=True, # MMR-style diversity
|
||||
)
|
||||
|
||||
retriever = ContextualCompressionRetriever(
|
||||
base_compressor=compressor,
|
||||
base_retriever=base_retriever,
|
||||
)
|
||||
|
||||
# Retrieves 50 docs, returns best 10
|
||||
docs = retriever.invoke("What is Python?")
|
||||
```
|
||||
|
||||
## Agent tool wrapping
|
||||
|
||||
`wrap_tools_with_headroom` compresses tool outputs before they re-enter the agent's context:
|
||||
|
||||
```python
|
||||
from langchain_core.tools import tool
|
||||
from headroom.integrations import wrap_tools_with_headroom
|
||||
|
||||
@tool
|
||||
def search_database(query: str) -> str:
|
||||
"""Search the database."""
|
||||
return json.dumps({"results": [...], "total": 1000})
|
||||
|
||||
wrapped_tools = wrap_tools_with_headroom(
|
||||
[search_database],
|
||||
min_chars_to_compress=1000,
|
||||
)
|
||||
|
||||
agent = create_openai_tools_agent(llm, wrapped_tools, prompt)
|
||||
executor = AgentExecutor(agent=agent, tools=wrapped_tools)
|
||||
```
|
||||
|
||||
Per-tool metrics:
|
||||
|
||||
```python
|
||||
from headroom.integrations import get_tool_metrics
|
||||
|
||||
metrics = get_tool_metrics()
|
||||
print(metrics.get_summary())
|
||||
# {'total_invocations': 25, 'total_compressions': 18, 'total_chars_saved': 450000}
|
||||
```
|
||||
|
||||
## LangGraph ReAct agent
|
||||
|
||||
```python
|
||||
from langchain_openai import ChatOpenAI
|
||||
from langgraph.prebuilt import create_react_agent
|
||||
from headroom.integrations import HeadroomChatModel, wrap_tools_with_headroom
|
||||
|
||||
llm = HeadroomChatModel(ChatOpenAI(model="gpt-4o"))
|
||||
tools = wrap_tools_with_headroom([search_web, query_database])
|
||||
|
||||
agent = create_react_agent(llm, tools)
|
||||
result = agent.invoke({
|
||||
"messages": [("user", "Find users who signed up last week")]
|
||||
})
|
||||
```
|
||||
|
||||
## LangGraph custom graph
|
||||
|
||||
Insert a compression node between tools and the agent in a custom `StateGraph`:
|
||||
|
||||
```python
|
||||
from langgraph.graph import StateGraph, MessagesState, START, END
|
||||
from headroom.integrations.langchain import create_compress_tool_messages_node
|
||||
|
||||
graph = StateGraph(MessagesState)
|
||||
graph.add_node("agent", agent_node)
|
||||
graph.add_node("tools", tools_node)
|
||||
graph.add_node("compress", create_compress_tool_messages_node(
|
||||
min_tokens_to_compress=100,
|
||||
))
|
||||
|
||||
# Wire: tools -> compress -> agent
|
||||
graph.add_edge(START, "agent")
|
||||
graph.add_edge("tools", "compress")
|
||||
graph.add_edge("compress", "agent")
|
||||
```
|
||||
|
||||
## Streaming
|
||||
|
||||
Full async support:
|
||||
|
||||
```python
|
||||
# Async invoke
|
||||
response = await llm.ainvoke("Hello!")
|
||||
|
||||
# Async streaming
|
||||
async for chunk in llm.astream("Tell me a story"):
|
||||
print(chunk.content, end="", flush=True)
|
||||
```
|
||||
|
||||
## Custom configuration
|
||||
|
||||
```python
|
||||
from headroom import HeadroomConfig, HeadroomMode
|
||||
|
||||
config = HeadroomConfig(
|
||||
default_mode=HeadroomMode.OPTIMIZE,
|
||||
smart_crusher_target_ratio=0.3,
|
||||
)
|
||||
|
||||
llm = HeadroomChatModel(
|
||||
ChatOpenAI(model="gpt-4o"),
|
||||
headroom_config=config,
|
||||
)
|
||||
```
|
||||
|
|
@ -1,143 +0,0 @@
|
|||
---
|
||||
title: Limitations
|
||||
description: When Headroom helps, when it does not, and what to watch out for. Honest documentation of compression constraints and safety gates.
|
||||
---
|
||||
|
||||
Headroom is designed to compress LLM context without losing accuracy. This page documents when it helps, when it does not, and the safety gates that prevent harmful compression.
|
||||
|
||||
## When Headroom Helps vs. Does Not
|
||||
|
||||
| Content Type | Compression | Latency Impact | Best For |
|
||||
|---|---|---|---|
|
||||
| **JSON: Arrays of dicts** (search results, API responses, DB rows) | 86--100% | Net latency win on Sonnet/Opus | Primary use case |
|
||||
| **JSON: Arrays of strings** (file paths, log lines, tags) | 60--90% | Net latency win | String dedup + sampling |
|
||||
| **JSON: Arrays of numbers** (metrics, time series) | 70--85% | Net latency win | Statistical summary |
|
||||
| **JSON: Mixed-type arrays** | 50--70% | Net latency win | Group-by-type compression |
|
||||
| **Structured logs** (as JSON) | 82--95% | Net latency win | Log entries in tool outputs |
|
||||
| **Agentic conversations** (25--50 turns) | 56--81% | Break-even to net win | Multi-tool agent sessions |
|
||||
| **Plain text** (documentation, articles) | 43--46% | Adds latency (cost savings only) | Cost optimization |
|
||||
| **Code** | Passthrough | Minimal overhead | See below |
|
||||
| **RAG document contexts** | Passthrough | Minimal overhead | Not compressed |
|
||||
|
||||
### Where Headroom Adds the Most Value
|
||||
|
||||
- Long agent sessions with accumulated tool outputs (40--80% compression)
|
||||
- JSON-heavy workflows -- API responses, database queries (83--94% compression)
|
||||
- Build and test output (85--94% compression)
|
||||
- Multi-tool agents (60--76% compression across tool results)
|
||||
|
||||
### Where Headroom Adds Little Value
|
||||
|
||||
- Short conversational exchanges (median 4.8% compression)
|
||||
- Code-only sessions (reading/writing files) -- code passes through
|
||||
- Single-turn requests with no accumulated context
|
||||
|
||||
## What Headroom Does NOT Compress
|
||||
|
||||
- **Short messages** (< 300 tokens) -- overhead exceeds savings
|
||||
- **Source code** -- passes through unchanged to preserve correctness
|
||||
- **grep/search results** -- compact structured format, already minimal
|
||||
- **Images** -- counted at fixed token cost (~1,600 tokens), not compressed
|
||||
- **System prompts** -- preserved for prefix cache compatibility
|
||||
|
||||
## Code Compression
|
||||
|
||||
Headroom includes an AST-aware CodeCompressor (tree-sitter, 8 languages) but it is gated behind safety protections that prevent it from firing in most real-world scenarios. This is intentional.
|
||||
|
||||
**Why code mostly passes through:**
|
||||
|
||||
1. **Word count gate**: Content under 50 words is silently skipped
|
||||
2. **Recent code protection** (`protect_recent_code=4`): Code in the last 4 messages is never compressed
|
||||
3. **Analysis intent protection** (`protect_analysis_context=True`): If the most recent user message contains keywords like "analyze", "review", "explain", "fix", "debug" -- ALL code in the conversation is protected
|
||||
|
||||
**Why this is the right default**: Code is almost always fetched because the user wants to work with it. Compressing function bodies would remove exactly what they need.
|
||||
|
||||
**Where code savings come from**: The IntelligentContextManager drops old code messages that are no longer relevant (scoring-based), which is a better strategy than stripping function bodies.
|
||||
|
||||
**Override**: Set `protect_analysis_context=False` in `ContentRouterConfig` for aggressive code compression. Requires `headroom-ai[code]` for tree-sitter.
|
||||
|
||||
## JSON Compression Constraints
|
||||
|
||||
### What Gets Compressed
|
||||
|
||||
- Arrays of **dicts**: Full statistical analysis with adaptive K (Kneedle algorithm)
|
||||
- Arrays of **strings**: Dedup + adaptive sampling + error preservation
|
||||
- Arrays of **numbers**: Statistical summary + outlier/change-point preservation
|
||||
- **Mixed-type** arrays: Grouped by type, each group compressed independently
|
||||
- **Nested** objects: Recursed into, arrays within are compressed (up to depth 5)
|
||||
|
||||
### What Passes Through
|
||||
|
||||
- Arrays below 5 items (`min_items_to_analyze`)
|
||||
- Content below 200 tokens (`min_tokens_to_crush`)
|
||||
- Bool-only arrays
|
||||
- JSON objects without array values
|
||||
- Malformed JSON (silently passes through, no error)
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- **NaN/Infinity** in numeric fields: Filtered out before statistics are computed
|
||||
- **Nesting depth > 5**: Inner arrays not examined for compression
|
||||
- **Mixed-type arrays with small groups**: Groups below `min_items_to_analyze` are kept as-is
|
||||
|
||||
## Safety Gates
|
||||
|
||||
All compressors follow the same principle: **fail gracefully, return original content unchanged**.
|
||||
|
||||
- Invalid JSON passes through (no error raised)
|
||||
- AST parse failure falls back to original or LLMLingua
|
||||
- Compression that makes output larger returns the original
|
||||
- Missing optional dependencies (tree-sitter, LLMLingua) cause a passthrough with warning log
|
||||
- Errors are logged at WARNING level and never propagated to callers
|
||||
|
||||
<Callout type="info" title="One exception">
|
||||
LLMLingua out-of-memory during model loading raises a `RuntimeError`. All other failures are silently handled.
|
||||
</Callout>
|
||||
|
||||
## Adaptive K: How Item Retention Works
|
||||
|
||||
SmartCrusher does not use fixed K values. It uses information-theoretic sizing:
|
||||
|
||||
1. **Kneedle algorithm** on bigram coverage curves finds the point where adding more items stops providing new information
|
||||
2. **SimHash** fingerprinting detects near-duplicate items
|
||||
3. **zlib validation** ensures the subset captures the full set's diversity
|
||||
|
||||
The resulting K is split: 30% from array start, 15% from end, 55% for importance-scored items.
|
||||
|
||||
**Safety guarantees (additive, never dropped):**
|
||||
|
||||
- Error items (containing "error", "exception", "failed", "critical") -- across ALL array types
|
||||
- Numeric anomalies (> 2 standard deviations from mean)
|
||||
- String length anomalies (> 2 standard deviations from mean length)
|
||||
- Change points (sudden shifts in running values)
|
||||
|
||||
These are kept even if they exceed the K budget.
|
||||
|
||||
## Configuration Tuning
|
||||
|
||||
| Parameter | Default | Effect |
|
||||
|---|---|---|
|
||||
| `min_items_to_analyze` | 5 | Arrays below this pass through |
|
||||
| `min_tokens_to_crush` | 200 | Content below this passes through |
|
||||
| `max_items_after_crush` | 15 | Upper bound on retained items |
|
||||
| `variance_threshold` | 2.0 | Std devs for anomaly detection (lower = more preserved) |
|
||||
| `protect_analysis_context` | True | Protect code when user asks about it |
|
||||
| `protect_recent_code` | 4 | Messages from end to protect code in |
|
||||
| `skip_user_messages` | True | Never compress user messages |
|
||||
| `toin_confidence_threshold` | 0.3 | Minimum TOIN confidence to apply hints |
|
||||
|
||||
## Provider Interactions
|
||||
|
||||
- CacheAligner maximizes Anthropic/OpenAI prefix cache hit rates
|
||||
- Token counting uses model-specific tokenizers (tiktoken for OpenAI, calibrated estimation for Anthropic)
|
||||
- Compression works with all providers -- no provider-specific limitations
|
||||
- Compressed content is valid JSON -- downstream tools and parsers work unchanged
|
||||
|
||||
## TOIN Cold Start
|
||||
|
||||
The Tool Output Intelligence Network (TOIN) learns compression patterns from usage. For new tool types:
|
||||
|
||||
- No learned patterns exist -- falls back to statistical heuristics
|
||||
- Confidence below `toin_confidence_threshold` (default 0.3) -- TOIN hints ignored
|
||||
- Patterns build up over time as tools are used repeatedly
|
||||
- Cross-session learning requires persistence (`TelemetryConfig.storage_path`)
|
||||
|
|
@ -1,89 +0,0 @@
|
|||
---
|
||||
title: LiteLLM
|
||||
description: Add Headroom compression to LiteLLM with a single callback. Works with all 100+ supported providers.
|
||||
---
|
||||
|
||||
Headroom integrates with [LiteLLM](https://github.com/BerriAI/litellm) as a callback that compresses messages before they reach any provider. One line to enable, works with all 100+ LiteLLM-supported providers.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install headroom-ai litellm
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```python
|
||||
import litellm
|
||||
from headroom.integrations.litellm_callback import HeadroomCallback
|
||||
|
||||
litellm.callbacks = [HeadroomCallback()]
|
||||
|
||||
# All calls now compressed automatically
|
||||
response = litellm.completion(model="gpt-4o", messages=[...])
|
||||
response = litellm.completion(model="bedrock/claude-sonnet", messages=[...])
|
||||
response = litellm.completion(model="azure/gpt-4o", messages=[...])
|
||||
```
|
||||
|
||||
The callback compresses messages in LiteLLM's `pre_call_hook` before they reach the provider.
|
||||
|
||||
## How it works
|
||||
|
||||
1. You call `litellm.completion()` with your messages
|
||||
2. `HeadroomCallback.pre_call_hook` compresses the messages
|
||||
3. LiteLLM sends the compressed messages to the provider
|
||||
4. The response comes back unchanged
|
||||
|
||||
This works with every provider LiteLLM supports: OpenAI, Anthropic, Bedrock, Azure, Vertex AI, Cohere, Groq, Mistral, Together, Ollama, and more.
|
||||
|
||||
## With LiteLLM Proxy
|
||||
|
||||
If you run LiteLLM as a proxy server, use the ASGI middleware:
|
||||
|
||||
```python
|
||||
from litellm.proxy.proxy_server import app
|
||||
from headroom.integrations.asgi import CompressionMiddleware
|
||||
|
||||
app.add_middleware(CompressionMiddleware)
|
||||
```
|
||||
|
||||
Or configure via YAML:
|
||||
|
||||
```yaml
|
||||
# litellm_config.yaml
|
||||
litellm_settings:
|
||||
callbacks: ["headroom.integrations.litellm_callback.HeadroomCallback"]
|
||||
```
|
||||
|
||||
## Direct compress() with LiteLLM
|
||||
|
||||
You can also use `compress()` directly instead of the callback:
|
||||
|
||||
```python
|
||||
import litellm
|
||||
from headroom import compress
|
||||
|
||||
messages = [{"role": "user", "content": large_content}]
|
||||
compressed = compress(messages, model="bedrock/claude-sonnet")
|
||||
|
||||
response = litellm.completion(
|
||||
model="bedrock/claude-sonnet",
|
||||
messages=compressed.messages,
|
||||
)
|
||||
|
||||
print(f"Saved {compressed.tokens_saved} tokens")
|
||||
```
|
||||
|
||||
## ASGI middleware
|
||||
|
||||
Drop-in middleware for any ASGI application. Intercepts `/v1/messages`, `/v1/chat/completions`, `/v1/responses`, and `/chat/completions`:
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
from headroom.integrations.asgi import CompressionMiddleware
|
||||
|
||||
app = FastAPI()
|
||||
app.add_middleware(CompressionMiddleware)
|
||||
```
|
||||
|
||||
Response headers include `x-headroom-compressed: true` and `x-headroom-tokens-saved: 1234`.
|
||||
|
|
@ -1,186 +0,0 @@
|
|||
---
|
||||
title: MCP Tools
|
||||
description: Compression, retrieval, and stats as MCP tools for Claude Code, Cursor, and any MCP-compatible host.
|
||||
---
|
||||
|
||||
Headroom's MCP server exposes compression, retrieval, and observability as tools that any MCP-compatible AI coding tool can call -- Claude Code, Cursor, Codex, and more. No proxy required.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# MCP tools only (lightweight)
|
||||
pip install "headroom-ai[mcp]"
|
||||
|
||||
# Or with the proxy
|
||||
pip install "headroom-ai[proxy]"
|
||||
```
|
||||
|
||||
## Setup for Claude Code
|
||||
|
||||
```bash
|
||||
# Register with Claude Code (one-time)
|
||||
headroom mcp install
|
||||
|
||||
# Start Claude Code — it now has headroom tools
|
||||
claude
|
||||
```
|
||||
|
||||
Claude Code can now compress content on demand, retrieve originals, and check session stats.
|
||||
|
||||
For automatic compression of **all** traffic, also run the proxy:
|
||||
|
||||
```bash
|
||||
# Terminal 1
|
||||
headroom proxy
|
||||
|
||||
# Terminal 2
|
||||
ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
### headroom_compress
|
||||
|
||||
Compress content on demand. The LLM calls this when it wants to shrink large content before reasoning over it.
|
||||
|
||||
**Parameters:**
|
||||
- `content` (required) -- text to compress (files, JSON, logs, search results)
|
||||
|
||||
**Returns:**
|
||||
- `compressed` -- compressed text
|
||||
- `hash` -- key for retrieving the original later
|
||||
- `original_tokens` / `compressed_tokens` / `savings_percent`
|
||||
- `transforms` -- which compression algorithms were applied
|
||||
|
||||
Example flow:
|
||||
|
||||
```
|
||||
Claude: Let me compress this large output to save context space.
|
||||
|
||||
-> headroom_compress(content="[5000 lines of grep results...]")
|
||||
|
||||
<- {
|
||||
"compressed": "[key matches with context...]",
|
||||
"hash": "a1b2c3d4e5f6...",
|
||||
"original_tokens": 12000,
|
||||
"compressed_tokens": 3200,
|
||||
"savings_percent": 73.3,
|
||||
"transforms": ["router:search:0.27"]
|
||||
}
|
||||
```
|
||||
|
||||
The original is stored locally for 1 hour. If the LLM needs the full content later, it calls `headroom_retrieve`.
|
||||
|
||||
### headroom_retrieve
|
||||
|
||||
Retrieve original uncompressed content by hash.
|
||||
|
||||
**Parameters:**
|
||||
- `hash` (required) -- hash key from a previous compression
|
||||
- `query` (optional) -- search within the original to return only matching items
|
||||
|
||||
**Returns:**
|
||||
- `original_content` (full retrieval) or `results` (filtered search)
|
||||
- `source` -- `"local"` or `"proxy"`
|
||||
|
||||
Retrieval checks the local store first, then falls back to the proxy's store. Hashes from either source work transparently.
|
||||
|
||||
### headroom_stats
|
||||
|
||||
Session compression statistics.
|
||||
|
||||
**Returns:**
|
||||
- `compressions`, `retrievals`, `tokens_saved`, `savings_percent`
|
||||
- `estimated_cost_saved_usd`
|
||||
- `recent_events` -- last 10 compression/retrieval events
|
||||
- `sub_agents` -- stats from sub-agent MCP instances
|
||||
- `combined` -- main + sub-agent totals
|
||||
- `proxy` -- request count, cache hits, cost saved (if proxy is running)
|
||||
|
||||
Sub-agent stats are aggregated via a shared stats file at `~/.headroom/session_stats.jsonl`.
|
||||
|
||||
## CLI commands
|
||||
|
||||
```bash
|
||||
# Install (registers with Claude Code)
|
||||
headroom mcp install
|
||||
headroom mcp install --proxy-url http://host:9000 # Custom proxy URL
|
||||
headroom mcp install --force # Overwrite existing
|
||||
|
||||
# Check status
|
||||
headroom mcp status
|
||||
|
||||
# Uninstall
|
||||
headroom mcp uninstall
|
||||
|
||||
# Debug mode
|
||||
headroom mcp serve --debug
|
||||
```
|
||||
|
||||
## MCP host configuration
|
||||
|
||||
For MCP hosts that let you configure a local stdio server, point them at `headroom mcp serve`. If you also run the proxy, pass the proxy URL explicitly so retrieval and stats come from the intended proxy instance.
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"headroom": {
|
||||
"type": "stdio",
|
||||
"command": "headroom",
|
||||
"args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:8787"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For multiple proxy instances, register one stdio MCP server per proxy URL:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"headroom": {
|
||||
"type": "stdio",
|
||||
"command": "headroom",
|
||||
"args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:8787"]
|
||||
},
|
||||
"headroom-azure": {
|
||||
"type": "stdio",
|
||||
"command": "headroom",
|
||||
"args": ["mcp", "serve", "--proxy-url", "http://127.0.0.1:8788"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not assume that a running proxy exposes an HTTP MCP endpoint at `/mcp`. If `http://127.0.0.1:<port>/mcp` returns `404`, use the stdio configuration above.
|
||||
|
||||
## Cross-tool compatibility
|
||||
|
||||
| Tool | MCP Support | Setup |
|
||||
|------|-------------|-------|
|
||||
| Claude Code | Native | `headroom mcp install` |
|
||||
| Cursor | Supported | Add to Cursor MCP settings |
|
||||
| Codex | If supported | Configure MCP server |
|
||||
| Any MCP host | Yes | Point to `headroom mcp serve` |
|
||||
|
||||
## Architecture
|
||||
|
||||
### MCP only (no proxy)
|
||||
|
||||
The LLM calls `headroom_compress` on demand. Compression happens locally in the MCP process. Originals are stored in a local `CompressionStore` with 1-hour TTL.
|
||||
|
||||
### MCP + Proxy (full setup)
|
||||
|
||||
The proxy compresses all traffic at the HTTP level (before the LLM sees content). MCP tools operate after the LLM receives content. They handle different data and do not double-compress.
|
||||
|
||||
`headroom_retrieve` checks the local store first, then falls back to the proxy's store.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"MCP SDK not installed"** -- Run `pip install "headroom-ai[mcp]"`.
|
||||
|
||||
**"Proxy not running"** -- Start the proxy with `headroom proxy` in another terminal. Only needed for proxy-backed retrieval.
|
||||
|
||||
**"Entry not found or expired"** -- Local content expires after 1 hour, proxy content after 5 minutes.
|
||||
|
||||
**Claude doesn't see headroom tools** -- Run `headroom mcp status`, restart Claude Code, and verify with `/mcp` inside Claude Code.
|
||||
|
|
@ -1,243 +0,0 @@
|
|||
---
|
||||
title: Persistent Memory
|
||||
description: Hierarchical, temporal memory for LLM applications. Enable your AI to remember across conversations with intelligent scoping and versioning.
|
||||
---
|
||||
|
||||
LLMs have two fundamental limitations: context windows overflow with too much history, and every conversation starts from zero. Persistent Memory solves both by extracting key facts, persisting them, and injecting them when relevant.
|
||||
|
||||
This is **temporal compression** -- instead of carrying 10,000 tokens of conversation history, carry 100 tokens of extracted memories.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
from headroom import with_memory
|
||||
|
||||
# One line -- that's it
|
||||
client = with_memory(OpenAI(), user_id="alice")
|
||||
|
||||
# Use exactly like normal
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "I prefer Python for backend work"}]
|
||||
)
|
||||
# Memory extracted INLINE -- zero extra latency
|
||||
|
||||
# Later, in a new conversation...
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "What language should I use?"}]
|
||||
)
|
||||
# Response uses the Python preference from memory
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
The `with_memory()` wrapper intercepts every chat completion call:
|
||||
|
||||
1. **Inject** -- Semantic search finds relevant memories and prepends them to the user message
|
||||
2. **Instruct** -- Adds a memory extraction instruction to the system prompt
|
||||
3. **Call** -- Forwards the request to the LLM
|
||||
4. **Parse** -- Extracts the `<memory>` block from the response
|
||||
5. **Store** -- Saves with embeddings, vector index, and full-text search index
|
||||
6. **Return** -- Cleans the response (strips the memory block before returning)
|
||||
|
||||
Memory extraction happens **inline** as part of the LLM response. No extra API calls, no extra latency.
|
||||
|
||||
## Hierarchical Scoping
|
||||
|
||||
Memories exist at four scope levels, from broadest to narrowest:
|
||||
|
||||
| Scope | Persists Across | Use Case |
|
||||
|-------|-----------------|----------|
|
||||
| **User** | All sessions, all time | Long-term preferences, identity |
|
||||
| **Session** | Current session only | Current task context |
|
||||
| **Agent** | Current agent in session | Agent-specific context |
|
||||
| **Turn** | Single turn only | Ephemeral working memory |
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
from headroom import with_memory
|
||||
|
||||
# Session 1: Morning
|
||||
client1 = with_memory(
|
||||
OpenAI(),
|
||||
user_id="bob",
|
||||
session_id="morning-session",
|
||||
)
|
||||
response = client1.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "I prefer Go for performance-critical code"}]
|
||||
)
|
||||
# Memory stored at USER level (persists across sessions)
|
||||
|
||||
# Session 2: Afternoon (different session, same user)
|
||||
client2 = with_memory(
|
||||
OpenAI(),
|
||||
user_id="bob",
|
||||
session_id="afternoon-session",
|
||||
)
|
||||
response = client2.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=[{"role": "user", "content": "What language for my new microservice?"}]
|
||||
)
|
||||
# Recalls Go preference from morning session
|
||||
```
|
||||
|
||||
## Memory Categories
|
||||
|
||||
Memories are categorized for better organization and retrieval:
|
||||
|
||||
| Category | Description | Examples |
|
||||
|----------|-------------|----------|
|
||||
| `PREFERENCE` | Likes, dislikes, preferred approaches | "Prefers Python", "Likes dark mode" |
|
||||
| `FACT` | Identity, role, constraints | "Works at fintech startup", "Senior engineer" |
|
||||
| `CONTEXT` | Current goals, ongoing tasks | "Migrating to microservices", "Working on auth" |
|
||||
| `ENTITY` | Information about entities | "Project Apollo uses React", "Team lead is Sarah" |
|
||||
| `DECISION` | Decisions made | "Chose PostgreSQL over MySQL" |
|
||||
| `INSIGHT` | Derived insights | "User tends to prefer typed languages" |
|
||||
|
||||
## Memory API
|
||||
|
||||
The `with_memory()` wrapper exposes a `.memory` attribute for direct access:
|
||||
|
||||
```python
|
||||
client = with_memory(OpenAI(), user_id="alice")
|
||||
|
||||
# Search memories (semantic)
|
||||
results = client.memory.search("python preferences", top_k=5)
|
||||
for memory in results:
|
||||
print(f"{memory.content}")
|
||||
|
||||
# Add a memory manually
|
||||
client.memory.add(
|
||||
"User is a senior engineer",
|
||||
category="fact",
|
||||
importance=0.9,
|
||||
)
|
||||
|
||||
# Get all memories for this user
|
||||
all_memories = client.memory.get_all()
|
||||
|
||||
# Clear all memories
|
||||
client.memory.clear()
|
||||
|
||||
# Get stats
|
||||
stats = client.memory.stats()
|
||||
print(f"Total memories: {stats['total']}")
|
||||
print(f"By category: {stats['categories']}")
|
||||
```
|
||||
|
||||
## Temporal Versioning
|
||||
|
||||
When facts change, Headroom creates a **supersession chain** that preserves history:
|
||||
|
||||
```python
|
||||
from headroom.memory import HierarchicalMemory, MemoryCategory
|
||||
|
||||
memory = await HierarchicalMemory.create()
|
||||
|
||||
# Original fact
|
||||
orig = await memory.add(
|
||||
content="User works at Google",
|
||||
user_id="alice",
|
||||
category=MemoryCategory.FACT,
|
||||
)
|
||||
|
||||
# User changes jobs -- supersede the old memory
|
||||
new = await memory.supersede(
|
||||
old_memory_id=orig.id,
|
||||
new_content="User now works at Anthropic",
|
||||
)
|
||||
|
||||
# Query current state (excludes superseded by default)
|
||||
current = await memory.query(MemoryFilter(
|
||||
user_id="alice",
|
||||
include_superseded=False,
|
||||
))
|
||||
# Returns only "User now works at Anthropic"
|
||||
|
||||
# Get the full chain
|
||||
chain = await memory.get_history(new.id)
|
||||
# [
|
||||
# Memory(content="User works at Google", is_current=False),
|
||||
# Memory(content="User now works at Anthropic", is_current=True),
|
||||
# ]
|
||||
```
|
||||
|
||||
This gives you an audit trail, the ability to debug why the LLM made certain decisions, and rollback if needed.
|
||||
|
||||
## Backends
|
||||
|
||||
### Embedder Backends
|
||||
|
||||
```python
|
||||
from headroom.memory import MemoryConfig, EmbedderBackend
|
||||
|
||||
# Local embeddings (recommended -- fast, free, private)
|
||||
config = MemoryConfig(
|
||||
embedder_backend=EmbedderBackend.LOCAL,
|
||||
embedder_model="all-MiniLM-L6-v2",
|
||||
)
|
||||
|
||||
# OpenAI embeddings (higher quality, costs money)
|
||||
config = MemoryConfig(
|
||||
embedder_backend=EmbedderBackend.OPENAI,
|
||||
openai_api_key="sk-...",
|
||||
embedder_model="text-embedding-3-small",
|
||||
)
|
||||
|
||||
# Ollama embeddings (local server, many models)
|
||||
config = MemoryConfig(
|
||||
embedder_backend=EmbedderBackend.OLLAMA,
|
||||
ollama_base_url="http://localhost:11434",
|
||||
embedder_model="nomic-embed-text",
|
||||
)
|
||||
```
|
||||
|
||||
### Storage
|
||||
|
||||
Storage uses **SQLite** for CRUD and filtering, **HNSW** for vector similarity search, and **FTS5** for full-text keyword search. All embedded -- no external services required.
|
||||
|
||||
```python
|
||||
config = MemoryConfig(
|
||||
db_path="memory.db",
|
||||
vector_dimension=384,
|
||||
hnsw_ef_construction=200,
|
||||
hnsw_m=16,
|
||||
hnsw_ef_search=50,
|
||||
cache_enabled=True,
|
||||
cache_max_size=1000,
|
||||
)
|
||||
```
|
||||
|
||||
## Provider Compatibility
|
||||
|
||||
Memory works with any OpenAI-compatible client:
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
from headroom import with_memory
|
||||
|
||||
# OpenAI
|
||||
client = with_memory(OpenAI(), user_id="alice")
|
||||
|
||||
# Azure OpenAI
|
||||
client = with_memory(
|
||||
OpenAI(base_url="https://your-resource.openai.azure.com/..."),
|
||||
user_id="alice",
|
||||
)
|
||||
|
||||
# Groq
|
||||
from groq import Groq
|
||||
client = with_memory(Groq(), user_id="alice")
|
||||
```
|
||||
|
||||
## Performance
|
||||
|
||||
| Operation | Latency | Notes |
|
||||
|-----------|---------|-------|
|
||||
| Memory injection | <50ms | Local embeddings + HNSW search |
|
||||
| Memory extraction | +50-100 tokens | Part of LLM response (inline) |
|
||||
| Memory storage | <10ms | SQLite + HNSW + FTS5 indexing |
|
||||
| Cache hit | <1ms | LRU cache lookup |
|
||||
|
|
@ -1,52 +0,0 @@
|
|||
{
|
||||
"pages": [
|
||||
"---Getting Started---",
|
||||
"index",
|
||||
"quickstart",
|
||||
"installation",
|
||||
"docker-install",
|
||||
"persistent-installs",
|
||||
"community-savings",
|
||||
"---Compression---",
|
||||
"how-compression-works",
|
||||
"smart-crusher",
|
||||
"code-compression",
|
||||
"image-compression",
|
||||
"text-and-logs",
|
||||
"---Reversible Compression---",
|
||||
"ccr",
|
||||
"---Cache & Context---",
|
||||
"cache-optimization",
|
||||
"context-management",
|
||||
"---Memory---",
|
||||
"memory",
|
||||
"shared-context",
|
||||
"failure-learning",
|
||||
"---Proxy Server---",
|
||||
"proxy",
|
||||
"---Integrations---",
|
||||
"vercel-ai-sdk",
|
||||
"openai-sdk",
|
||||
"anthropic-sdk",
|
||||
"langchain",
|
||||
"agno",
|
||||
"strands",
|
||||
"litellm",
|
||||
"mcp",
|
||||
"---Configuration---",
|
||||
"configuration",
|
||||
"filesystem-contract",
|
||||
"---Observability---",
|
||||
"metrics",
|
||||
"simulation",
|
||||
"---API Reference---",
|
||||
"api-reference",
|
||||
"---Architecture---",
|
||||
"architecture",
|
||||
"benchmarks",
|
||||
"limitations",
|
||||
"---Help---",
|
||||
"errors",
|
||||
"troubleshooting"
|
||||
]
|
||||
}
|
||||
|
|
@ -1,271 +0,0 @@
|
|||
---
|
||||
title: Metrics & Monitoring
|
||||
description: Monitor compression performance, cost savings, and system health with Headroom's built-in metrics, Prometheus endpoint, and SDK APIs.
|
||||
---
|
||||
|
||||
Headroom provides comprehensive metrics for monitoring compression performance, cost savings, and system health through both the proxy server and the SDK.
|
||||
|
||||
## Proxy Endpoints
|
||||
|
||||
### Stats Endpoint
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/stats
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"persistent_savings": {
|
||||
"lifetime": {
|
||||
"tokens_saved": 12500,
|
||||
"compression_savings_usd": 0.04
|
||||
}
|
||||
},
|
||||
"requests": {
|
||||
"total": 42,
|
||||
"cached": 5,
|
||||
"rate_limited": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"tokens": {
|
||||
"input": 50000,
|
||||
"output": 8000,
|
||||
"saved": 12500,
|
||||
"savings_percent": 25.0
|
||||
},
|
||||
"cost": {
|
||||
"total_cost_usd": 0.15,
|
||||
"total_savings_usd": 0.04
|
||||
},
|
||||
"cache": {
|
||||
"entries": 10,
|
||||
"total_hits": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Persistent savings are stored at `~/.headroom/proxy_savings.json` and survive proxy restarts. Override the path with `HEADROOM_SAVINGS_PATH`.
|
||||
|
||||
### Historical Savings
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/stats-history
|
||||
```
|
||||
|
||||
Returns durable compression history with hourly, daily, weekly, and monthly rollups. Supports CSV export:
|
||||
|
||||
```bash
|
||||
curl "http://localhost:8787/stats-history?format=csv&series=daily"
|
||||
curl "http://localhost:8787/stats-history?format=csv&series=monthly"
|
||||
```
|
||||
|
||||
### Prometheus Metrics
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/metrics
|
||||
```
|
||||
|
||||
```
|
||||
# HELP headroom_requests_total Total requests processed
|
||||
headroom_requests_total{mode="optimize"} 1234
|
||||
|
||||
# HELP headroom_tokens_saved_total Total tokens saved
|
||||
headroom_tokens_saved_total 5678900
|
||||
|
||||
# HELP headroom_compression_ratio Compression ratio histogram
|
||||
headroom_compression_ratio_bucket{le="0.5"} 890
|
||||
headroom_compression_ratio_bucket{le="0.7"} 1100
|
||||
headroom_compression_ratio_bucket{le="0.9"} 1200
|
||||
|
||||
# HELP headroom_latency_seconds Request latency histogram
|
||||
headroom_latency_seconds_bucket{le="0.01"} 800
|
||||
headroom_latency_seconds_bucket{le="0.1"} 1150
|
||||
|
||||
# HELP headroom_cache_hits_total Cache hit counter
|
||||
headroom_cache_hits_total 456
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/health
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"version": "0.1.0",
|
||||
"uptime_seconds": 3600
|
||||
}
|
||||
```
|
||||
|
||||
## SDK Metrics
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
|
||||
### Proxy Stats
|
||||
|
||||
The TypeScript SDK queries the proxy for stats:
|
||||
|
||||
```ts twoslash
|
||||
import { HeadroomClient } from 'headroom-ai';
|
||||
|
||||
const client = new HeadroomClient();
|
||||
|
||||
// Get proxy stats
|
||||
const stats = await client.proxyStats();
|
||||
console.log(`Tokens saved: ${stats.tokens.saved}`);
|
||||
console.log(`Savings: ${stats.tokens.savings_percent}%`);
|
||||
```
|
||||
|
||||
### Compression Result Metrics
|
||||
|
||||
Every `compress()` call returns metrics:
|
||||
|
||||
```ts twoslash
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
const result = await compress(messages, { model: 'gpt-4o' });
|
||||
console.log(`Tokens: ${result.tokensBefore} -> ${result.tokensAfter}`);
|
||||
console.log(`Saved: ${result.tokensSaved} (${(result.compressionRatio * 100).toFixed(1)}%)`);
|
||||
console.log(`Transforms: ${result.transformsApplied.join(', ')}`);
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
|
||||
### Session Stats
|
||||
|
||||
Quick stats for the current session (no database query):
|
||||
|
||||
```python
|
||||
stats = client.get_stats()
|
||||
print(f"Mode: {stats['config']['mode']}")
|
||||
print(f"Tokens saved: {stats['session']['tokens_saved_total']}")
|
||||
print(f"Avg compression: {stats['session']['compression_ratio_avg']:.1%}")
|
||||
```
|
||||
|
||||
Returns:
|
||||
|
||||
```python
|
||||
{
|
||||
"session": {
|
||||
"requests_total": 10,
|
||||
"tokens_input_before": 50000,
|
||||
"tokens_input_after": 35000,
|
||||
"tokens_saved_total": 15000,
|
||||
"tokens_output_total": 8000,
|
||||
"cache_hits": 3,
|
||||
"compression_ratio_avg": 0.70,
|
||||
},
|
||||
"config": {
|
||||
"mode": "optimize",
|
||||
"provider": "openai",
|
||||
"cache_optimizer_enabled": True,
|
||||
"semantic_cache_enabled": False,
|
||||
},
|
||||
"transforms": {
|
||||
"smart_crusher_enabled": True,
|
||||
"cache_aligner_enabled": True,
|
||||
"rolling_window_enabled": True,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Historical Metrics
|
||||
|
||||
Query stored metrics from the database:
|
||||
|
||||
```python
|
||||
from datetime import datetime, timedelta
|
||||
|
||||
metrics = client.get_metrics(
|
||||
start_time=datetime.utcnow() - timedelta(hours=1),
|
||||
limit=100,
|
||||
)
|
||||
|
||||
for m in metrics:
|
||||
print(f"{m.timestamp}: {m.tokens_input_before} -> {m.tokens_input_after}")
|
||||
```
|
||||
|
||||
### Summary Statistics
|
||||
|
||||
Aggregate statistics across all stored metrics:
|
||||
|
||||
```python
|
||||
summary = client.get_summary()
|
||||
print(f"Total requests: {summary['total_requests']}")
|
||||
print(f"Total tokens saved: {summary['total_tokens_saved']}")
|
||||
print(f"Average compression: {summary['avg_compression_ratio']:.1%}")
|
||||
print(f"Total cost savings: ${summary['total_cost_saved_usd']:.2f}")
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Logging
|
||||
|
||||
<Tabs groupId="lang" items={['Python', 'Proxy']}>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
import logging
|
||||
|
||||
# INFO level shows compression summaries
|
||||
logging.basicConfig(level=logging.INFO)
|
||||
|
||||
# DEBUG level shows detailed transform decisions
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
INFO:headroom.transforms.pipeline:Pipeline complete: 45000 -> 4500 tokens (saved 40500, 90.0% reduction)
|
||||
INFO:headroom.transforms.smart_crusher:SmartCrusher applied top_n strategy: kept 15 of 1000 items
|
||||
DEBUG:headroom.transforms.smart_crusher:Kept items: [0,1,2,42,77,97,98,99] (errors at 42, warnings at 77)
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Proxy">
|
||||
```bash
|
||||
# Log to file
|
||||
headroom proxy --log-file headroom.jsonl
|
||||
|
||||
# Increase verbosity
|
||||
headroom proxy --log-level debug
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Cost Tracking
|
||||
|
||||
### Budget Alerts
|
||||
|
||||
Set a budget limit in the proxy:
|
||||
|
||||
```bash
|
||||
headroom proxy --budget 10.00
|
||||
```
|
||||
|
||||
When the budget is exceeded, requests return a budget exceeded error, the `/stats` endpoint shows budget status, and logs indicate the budget state.
|
||||
|
||||
## Key Metrics to Monitor
|
||||
|
||||
| Metric | What It Tells You | Target |
|
||||
|--------|-------------------|--------|
|
||||
| `tokens_saved_total` | Total cost savings | Higher is better |
|
||||
| `compression_ratio_avg` | Efficiency | 0.7--0.9 typical |
|
||||
| `cache_hit_rate` | Cache effectiveness | >20% is good |
|
||||
| `latency_p99` | Performance impact | <10ms |
|
||||
| `failed_requests` | Reliability | 0 |
|
||||
|
||||
## Grafana Dashboard
|
||||
|
||||
Example Prometheus queries for a Grafana dashboard:
|
||||
|
||||
| Panel | PromQL |
|
||||
|-------|--------|
|
||||
| Tokens Saved | `headroom_tokens_saved_total` |
|
||||
| Compression Ratio (median) | `histogram_quantile(0.5, headroom_compression_ratio_bucket)` |
|
||||
| Request Latency (p99) | `histogram_quantile(0.99, headroom_latency_seconds_bucket)` |
|
||||
| Cache Hit Rate | `headroom_cache_hits_total / (headroom_cache_hits_total + headroom_cache_misses_total)` |
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
---
|
||||
title: OpenAI SDK
|
||||
description: Auto-compress messages in the OpenAI Node.js SDK with a single withHeadroom() wrapper.
|
||||
---
|
||||
|
||||
Headroom wraps the OpenAI Node.js SDK to automatically compress messages before every `chat.completions.create()` call. All other methods (embeddings, images, audio) pass through unchanged.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install headroom-ai openai
|
||||
```
|
||||
|
||||
<Callout type="info" title="Proxy required">
|
||||
The TypeScript SDK sends messages to a local Headroom proxy for compression. Start the proxy before using the SDK:
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[proxy]"
|
||||
headroom proxy
|
||||
```
|
||||
</Callout>
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/openai';
|
||||
import OpenAI from 'openai';
|
||||
|
||||
const client = withHeadroom(new OpenAI());
|
||||
|
||||
// Messages are compressed automatically before sending
|
||||
const response = await client.chat.completions.create({
|
||||
model: 'gpt-4o',
|
||||
messages: longConversation,
|
||||
});
|
||||
```
|
||||
|
||||
That's it. Every call to `client.chat.completions.create()` compresses the messages first. The response format is identical to the unwrapped client.
|
||||
|
||||
## How it works
|
||||
|
||||
`withHeadroom()` returns a proxy around your OpenAI client that intercepts `chat.completions.create()`:
|
||||
|
||||
1. Extracts `messages` from the request params
|
||||
2. Sends them to the Headroom proxy's `/v1/compress` endpoint
|
||||
3. Replaces the original messages with the compressed result
|
||||
4. Forwards the request to OpenAI as normal
|
||||
|
||||
All other client methods are untouched:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/openai';
|
||||
import OpenAI from 'openai';
|
||||
|
||||
const client = withHeadroom(new OpenAI());
|
||||
|
||||
// These pass through unchanged
|
||||
const embedding = await client.embeddings.create({
|
||||
model: 'text-embedding-3-small',
|
||||
input: 'Hello world',
|
||||
});
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
Pass compression options as the second argument:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/openai';
|
||||
import OpenAI from 'openai';
|
||||
|
||||
const client = withHeadroom(new OpenAI(), {
|
||||
model: 'gpt-4o',
|
||||
baseUrl: 'http://localhost:8787',
|
||||
});
|
||||
```
|
||||
|
||||
## Streaming
|
||||
|
||||
Streaming works normally. Compression happens before the request is sent:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/openai';
|
||||
import OpenAI from 'openai';
|
||||
|
||||
const client = withHeadroom(new OpenAI());
|
||||
|
||||
const stream = await client.chat.completions.create({
|
||||
model: 'gpt-4o',
|
||||
messages: longConversation,
|
||||
stream: true,
|
||||
});
|
||||
|
||||
for await (const chunk of stream) {
|
||||
process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
|
||||
}
|
||||
```
|
||||
|
||||
## Tool calling
|
||||
|
||||
Tool call messages and tool results are compressed like any other message content. Large tool outputs (JSON arrays, logs) see the biggest savings:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/openai';
|
||||
import OpenAI from 'openai';
|
||||
|
||||
const client = withHeadroom(new OpenAI());
|
||||
|
||||
const response = await client.chat.completions.create({
|
||||
model: 'gpt-4o',
|
||||
messages: [
|
||||
{ role: 'user', content: 'Search for recent errors' },
|
||||
{
|
||||
role: 'assistant',
|
||||
content: null,
|
||||
tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'search', arguments: '{"q":"errors"}' } }],
|
||||
},
|
||||
{
|
||||
role: 'tool',
|
||||
tool_call_id: 'call_1',
|
||||
content: hugeJsonResult, // Compressed automatically
|
||||
},
|
||||
],
|
||||
tools: [{ type: 'function', function: { name: 'search', parameters: {} } }],
|
||||
});
|
||||
```
|
||||
|
|
@ -1,163 +0,0 @@
|
|||
---
|
||||
title: Persistent Installs
|
||||
description: Install Headroom as a durable local runtime — background service, scheduled watchdog, or restartable Docker container — instead of starting it ad hoc.
|
||||
---
|
||||
|
||||
Headroom can be installed as a durable local runtime instead of only being started ad hoc with `headroom proxy` or `headroom wrap ...`.
|
||||
|
||||
Use the Python-native `headroom install` CLI when you want supported tools to keep talking to an always-on proxy at `http://127.0.0.1:8787` and have `wrap` reuse or recover that deployment instead of starting a second ephemeral proxy.
|
||||
|
||||
## Runtime matrix
|
||||
|
||||
| Mode | What stays running | Primary entrypoint |
|
||||
|---|---|---|
|
||||
| Persistent Service | Native background service | `headroom install apply --preset persistent-service` |
|
||||
| Persistent Task | Scheduled watchdog + on-demand runner | `headroom install apply --preset persistent-task` |
|
||||
| Persistent Docker | Restartable Docker container | `headroom install apply --preset persistent-docker` |
|
||||
| On-Demand CLI (Python) | Nothing after command exits | `headroom proxy` |
|
||||
| On-Demand CLI (Docker) | Nothing after container exits | Docker-native wrapper / compose CLI |
|
||||
| Wrapped (Python) | Proxy lasts for wrapped session | `headroom wrap ...` |
|
||||
| Wrapped (Docker) | Containerized proxy + host tool session | Docker-native wrapper |
|
||||
|
||||
## Quick examples
|
||||
|
||||
### Persistent service on the local machine
|
||||
|
||||
```bash
|
||||
headroom install apply --preset persistent-service --providers auto
|
||||
headroom install status
|
||||
```
|
||||
|
||||
This installs a background service on the current machine, applies persistent tool wiring, and keeps the proxy healthy on port `8787`.
|
||||
|
||||
### Persistent watchdog task
|
||||
|
||||
```bash
|
||||
headroom install apply --preset persistent-task --providers manual --target claude --target codex
|
||||
```
|
||||
|
||||
This installs a scheduled recovery path instead of a traditional always-running service.
|
||||
|
||||
### Persistent Docker
|
||||
|
||||
```bash
|
||||
headroom install apply --preset persistent-docker --scope user --providers auto
|
||||
```
|
||||
|
||||
This uses Docker's restart policy instead of an OS supervisor.
|
||||
|
||||
If you are using the Docker-native host wrapper instead of a Python install, you can use `headroom install apply|status|start|stop|restart|remove` for the `persistent-docker` preset directly from the installed wrapper. Service/task installs and provider/user/system mutation flows still belong to the Python-native CLI.
|
||||
|
||||
## Command surface
|
||||
|
||||
```text
|
||||
headroom install apply
|
||||
headroom install status
|
||||
headroom install start
|
||||
headroom install stop
|
||||
headroom install restart
|
||||
headroom install remove
|
||||
```
|
||||
|
||||
`apply` creates or updates a named deployment profile, stores its manifest under `~/.headroom/deploy/<profile>/manifest.json`, applies reversible configuration changes, and starts the selected runtime.
|
||||
|
||||
## Presets and runtime kinds
|
||||
|
||||
### Presets
|
||||
|
||||
- `persistent-service` → native service supervisor
|
||||
- `persistent-task` → scheduled watchdog / recovery supervisor
|
||||
- `persistent-docker` → Docker restart policy with no extra OS supervisor
|
||||
|
||||
### Runtime kinds
|
||||
|
||||
- `--runtime python` runs `headroom proxy` directly
|
||||
- `--runtime docker` runs Headroom inside Docker while keeping the deployment managed locally
|
||||
|
||||
For `persistent-docker`, the runtime is always Docker.
|
||||
|
||||
## Configuration scopes
|
||||
|
||||
| Scope | What changes |
|
||||
|---|---|
|
||||
| `provider` | Tool-specific config surfaces where Headroom can make a precise reversible edit |
|
||||
| `user` | User-level shell or environment surfaces |
|
||||
| `system` | Machine-wide shell or environment surfaces |
|
||||
|
||||
### Provider scope today
|
||||
|
||||
Provider scope is intentionally conservative. The current direct adapters are:
|
||||
|
||||
- Claude Code → `~/.claude/settings.json` `env`
|
||||
- Codex → managed block in `~/.codex/config.toml`
|
||||
- OpenClaw → existing `wrap openclaw` / `unwrap openclaw` flow
|
||||
|
||||
For Copilot, Aider, Cursor, and broader env-driven setups, prefer `--scope user` or `--scope system`.
|
||||
|
||||
## Provider selection
|
||||
|
||||
| Option | Meaning |
|
||||
|---|---|
|
||||
| `--providers auto` | Detect supported tools on the host and configure the best available defaults |
|
||||
| `--providers all` | Configure all known targets |
|
||||
| `--providers manual --target ...` | Configure only the named tools |
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
headroom install apply --providers auto
|
||||
headroom install apply --providers all --scope user
|
||||
headroom install apply --providers manual --target claude --target copilot
|
||||
```
|
||||
|
||||
## Health and wrap behavior
|
||||
|
||||
Persistent deployments publish the same `readyz` and `health` endpoints as ad hoc proxy runs.
|
||||
|
||||
`/health` also exposes deployment metadata when the proxy was launched through the install subsystem:
|
||||
|
||||
```json
|
||||
{
|
||||
"deployment": {
|
||||
"profile": "default",
|
||||
"preset": "persistent-service",
|
||||
"runtime": "python",
|
||||
"supervisor": "service",
|
||||
"scope": "user"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The Python-native `headroom wrap ...` flow checks for a matching persistent deployment on the requested port before it starts a new ephemeral proxy. If an installed deployment exists but is stopped or unhealthy, it attempts to recover it first.
|
||||
|
||||
The Docker-native host wrapper does **not** yet reuse or recover persistent profiles automatically; it still starts a fresh proxy container unless you opt into `--no-proxy`.
|
||||
|
||||
## Docker-native relationship
|
||||
|
||||
The Docker-native host wrapper and the Python install CLI solve different layers of the runtime story:
|
||||
|
||||
- [Docker-Native Install](/docs/docker-install) → containerized on-demand CLI, wrapped host-tool flows, and Docker-native `persistent-docker` lifecycle commands
|
||||
- `headroom install ...` → full persistent service, task, and Docker lifecycle management, including provider/user/system mutation
|
||||
|
||||
For a no-Python persistent Docker workflow, use the compose-managed proxy path from `docker/docker-compose.native.yml`:
|
||||
|
||||
```bash
|
||||
export HEADROOM_HOST_HOME="$HOME"
|
||||
export HEADROOM_WORKSPACE="$PWD"
|
||||
docker compose -f docker/docker-compose.native.yml up -d proxy
|
||||
```
|
||||
|
||||
That keeps `localhost:8787` stable and restarts the proxy automatically.
|
||||
|
||||
<Callout type="info" title="HEADROOM_WORKSPACE vs HEADROOM_WORKSPACE_DIR">
|
||||
`HEADROOM_WORKSPACE` (the host-side bind-mount source used by the compose file) is **not** the same variable as `HEADROOM_WORKSPACE_DIR` (the canonical Headroom state root inside the container). Both are retained; the compose file sets the latter automatically. See [Filesystem Contract](/docs/filesystem-contract) for the full bucket model.
|
||||
</Callout>
|
||||
|
||||
## Related guides
|
||||
|
||||
<Cards>
|
||||
<Card title="Docker-Native Install" href="/docs/docker-install" />
|
||||
<Card title="Proxy Server" href="/docs/proxy" />
|
||||
<Card title="Filesystem Contract" href="/docs/filesystem-contract" />
|
||||
<Card title="Configuration" href="/docs/configuration" />
|
||||
</Cards>
|
||||
|
|
@ -1,283 +0,0 @@
|
|||
---
|
||||
title: Proxy Server
|
||||
description: Run the Headroom proxy to compress LLM traffic for any client — Claude Code, Cursor, OpenAI SDK, or custom apps.
|
||||
---
|
||||
|
||||
The Headroom proxy is a standalone HTTP server that compresses all LLM traffic passing through it. Point any client at the proxy and get automatic context optimization.
|
||||
|
||||
## Starting the proxy
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
headroom proxy
|
||||
|
||||
# Custom host and port
|
||||
headroom proxy --host 0.0.0.0 --port 8080
|
||||
|
||||
# With logging and budget
|
||||
headroom proxy \
|
||||
--log-file /var/log/headroom.jsonl \
|
||||
--budget 100.0
|
||||
```
|
||||
|
||||
Telemetry is enabled by default. Opt out with `HEADROOM_TELEMETRY=off` or `--no-telemetry`.
|
||||
|
||||
## CLI options
|
||||
|
||||
### Core
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--host` | `127.0.0.1` | Host to bind to |
|
||||
| `--port` | `8787` | Port to bind to |
|
||||
| `--workers` | `1` | Number of Uvicorn worker processes |
|
||||
| `--limit-concurrency` | `1000` | Maximum concurrent connections before Uvicorn returns 503 |
|
||||
| `--max-connections` | `500` | Maximum upstream HTTP connections |
|
||||
| `--max-keepalive` | `100` | Maximum upstream keep-alive connections |
|
||||
| `--mode` | `token` | Optimization mode: `token` prioritizes compression, `cache` preserves provider prefix-cache stability |
|
||||
| `--no-optimize` | `false` | Disable optimization (passthrough mode) |
|
||||
| `--no-cache` | `false` | Disable semantic caching |
|
||||
| `--no-rate-limit` | `false` | Disable rate limiting |
|
||||
| `--log-file` | None | Path to JSONL log file |
|
||||
| `--log-messages` | `false` | Store full request/response content for the live feed |
|
||||
| `--budget` | None | Daily budget limit in USD |
|
||||
| `--openai-api-url` | `https://api.openai.com` | Custom OpenAI API URL |
|
||||
| `--anthropic-api-url` | Anthropic default | Custom Anthropic API URL |
|
||||
| `--gemini-api-url` | Gemini default | Custom Gemini API URL |
|
||||
| `--backend` | `anthropic` | Backend: `anthropic`, `bedrock`, `openrouter`, `anyllm`, or `litellm-<provider>` |
|
||||
| `--no-telemetry` | `false` | Disable anonymous telemetry |
|
||||
| `--stateless` | `false` | Disable filesystem writes and keep runtime state in memory |
|
||||
|
||||
### Context management
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--mode token` | `token` | Prioritize token compression. This is the default. |
|
||||
| `--mode cache` | `token` | Preserve prior turns to maximize provider prefix-cache hit rate. |
|
||||
| `--intercept-tool-results` | `false` | Opt into tool-result interceptors such as ast-grep Read outlining. |
|
||||
| `--no-read-lifecycle` | `false` | Disable stale/superseded Read-output compression. |
|
||||
| `--code-aware` / `--no-code-aware` | disabled | Enable or disable AST-based code compression. Requires `headroom-ai[code]`. |
|
||||
| `--code-graph` | `false` | Index the current project and watch files via codebase-memory-mcp. |
|
||||
|
||||
By default, the proxy uses the shared **ContentRouter** pipeline. It routes text, logs, JSON, code, images, and tool outputs through the currently enabled compressors and preserves reversible CCR markers where applicable.
|
||||
|
||||
```bash
|
||||
# Maximize compression
|
||||
headroom proxy --mode token
|
||||
|
||||
# Preserve provider prefix cache stability
|
||||
headroom proxy --mode cache
|
||||
```
|
||||
|
||||
### Optional features
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--memory` | `false` | Enable persistent user memory and provider-appropriate memory tools |
|
||||
| `--memory-db-path` | `{cwd}/.headroom/memory.db` | Override the memory SQLite path |
|
||||
| `--no-memory-tools` | `false` | Disable automatic memory tool injection |
|
||||
| `--no-memory-context` | `false` | Disable automatic memory context injection |
|
||||
| `--memory-top-k` | `10` | Number of memories to inject as context |
|
||||
| `--learn` | `false` | Enable live traffic learning; implies `--memory` |
|
||||
| `--no-learn` | `false` | Explicitly disable traffic learning |
|
||||
| `--min-evidence` | `5` | Minimum observations before a learned pattern is persisted |
|
||||
| `--codex-wire-debug` | `false` | Write local Codex wire snapshots and matching proxy log traces |
|
||||
|
||||
```bash
|
||||
headroom proxy --memory
|
||||
headroom proxy --learn --min-evidence 3
|
||||
headroom proxy --codex-wire-debug
|
||||
```
|
||||
|
||||
<Callout type="info" title="LLMLingua removed from the proxy CLI">
|
||||
The old LLMLingua proxy toggles are no longer part of the CLI. Headroom's proxy compression path uses ContentRouter plus the current built-in compressors, including Kompress where applicable.
|
||||
</Callout>
|
||||
|
||||
## API endpoints
|
||||
|
||||
### `GET /health`
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/health
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"optimize": true,
|
||||
"stats": {
|
||||
"total_requests": 42,
|
||||
"tokens_saved": 15000,
|
||||
"savings_percent": 45.2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `GET /stats`
|
||||
|
||||
Live session statistics plus durable `persistent_savings` totals. Stored at `~/.headroom/proxy_savings.json` (override with `HEADROOM_SAVINGS_PATH`).
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/stats
|
||||
```
|
||||
|
||||
### `GET /stats-history`
|
||||
|
||||
Durable history with hourly, daily, weekly, and monthly rollups. Powers the `/dashboard` view.
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/stats-history
|
||||
curl "http://localhost:8787/stats-history?format=csv&series=weekly"
|
||||
```
|
||||
|
||||
### `GET /metrics`
|
||||
|
||||
Prometheus-format metrics for monitoring.
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/metrics
|
||||
```
|
||||
|
||||
```
|
||||
headroom_requests_total{mode="optimize"} 1234
|
||||
headroom_tokens_saved_total 5678900
|
||||
headroom_compression_ratio_bucket{le="0.5"} 890
|
||||
headroom_latency_seconds_bucket{le="0.01"} 800
|
||||
headroom_cache_hits_total 456
|
||||
```
|
||||
|
||||
### `POST /v1/messages`
|
||||
|
||||
Anthropic API format. The proxy compresses messages, forwards to Anthropic, and returns the response.
|
||||
|
||||
### `POST /v1/chat/completions`
|
||||
|
||||
OpenAI API format. The proxy compresses messages, forwards to OpenAI, and returns the response.
|
||||
|
||||
### `POST /v1/responses`
|
||||
|
||||
OpenAI Responses API format. The proxy compresses `input` payloads where applicable, forwards the request, and returns the response.
|
||||
|
||||
For Codex-compatible clients, the proxy also accepts these alias paths and routes them through the same handler:
|
||||
- `POST /v1/codex/responses`
|
||||
- `POST /backend-api/responses`
|
||||
- `POST /backend-api/codex/responses`
|
||||
|
||||
Matching WebSocket and subpath aliases are also supported for Codex flows.
|
||||
|
||||
### `POST /v1internal:streamGenerateContent`
|
||||
|
||||
Google Cloud Code Assist / Antigravity compatibility endpoint used by Pi-style `google-gemini-cli` and `google-antigravity` providers.
|
||||
|
||||
The proxy also accepts:
|
||||
- `POST /v1/v1internal:streamGenerateContent`
|
||||
|
||||
### `POST /v1/compress`
|
||||
|
||||
Compression-only endpoint. Compresses messages without calling any LLM. Used by the TypeScript SDK.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"messages": [{ "role": "user", "content": "..." }],
|
||||
"model": "gpt-4o"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"messages": [{ "role": "user", "content": "..." }],
|
||||
"tokens_before": 15000,
|
||||
"tokens_after": 3500,
|
||||
"tokens_saved": 11500,
|
||||
"compression_ratio": 0.23,
|
||||
"transforms_applied": ["router:smart_crusher:0.35"],
|
||||
"ccr_hashes": ["a1b2c3"]
|
||||
}
|
||||
```
|
||||
|
||||
Set `x-headroom-bypass: true` to skip compression.
|
||||
|
||||
## Agent wrapping
|
||||
|
||||
Use `headroom wrap` to transparently proxy any CLI tool:
|
||||
|
||||
```bash
|
||||
# Claude Code
|
||||
headroom wrap claude
|
||||
|
||||
# OpenAI Codex
|
||||
headroom wrap codex
|
||||
|
||||
# Aider
|
||||
headroom wrap aider
|
||||
|
||||
# Cursor
|
||||
headroom wrap cursor
|
||||
```
|
||||
|
||||
Or set the base URL manually:
|
||||
|
||||
```bash
|
||||
# Claude Code
|
||||
ANTHROPIC_BASE_URL=http://localhost:8787 claude
|
||||
|
||||
# Cursor / any OpenAI-compatible client
|
||||
OPENAI_BASE_URL=http://localhost:8787/v1 cursor
|
||||
```
|
||||
|
||||
## Cloud providers
|
||||
|
||||
```bash
|
||||
# AWS Bedrock
|
||||
headroom proxy --backend bedrock --region us-east-1
|
||||
|
||||
# Google Vertex AI
|
||||
headroom proxy --backend vertex_ai --region us-central1
|
||||
|
||||
# Azure OpenAI
|
||||
headroom proxy --backend azure
|
||||
|
||||
# OpenRouter (400+ models)
|
||||
OPENROUTER_API_KEY=sk-or-... headroom proxy --backend openrouter
|
||||
```
|
||||
|
||||
## Environment variables
|
||||
|
||||
```bash
|
||||
export HEADROOM_HOST=0.0.0.0
|
||||
export HEADROOM_PORT=8787
|
||||
export HEADROOM_BUDGET=100.0
|
||||
export OPENAI_TARGET_API_URL=https://custom.openai.endpoint.com
|
||||
headroom proxy
|
||||
```
|
||||
|
||||
## Production deployment
|
||||
|
||||
### gunicorn
|
||||
|
||||
```bash
|
||||
pip install gunicorn
|
||||
|
||||
gunicorn headroom.proxy.server:app \
|
||||
--workers 4 \
|
||||
--bind 0.0.0.0:8787 \
|
||||
--worker-class uvicorn.workers.UvicornWorker
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.11-slim
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
|
||||
&& pip install "headroom-ai[proxy]" \
|
||||
&& apt-get purge -y build-essential && apt-get autoremove -y \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
EXPOSE 8787
|
||||
CMD ["headroom", "proxy", "--host", "0.0.0.0"]
|
||||
```
|
||||
|
||||
<Callout type="info" title="Build dependencies">
|
||||
`build-essential` is required at install time because `headroom-ai` includes `hnswlib`, a C++ extension compiled from source. It is removed after installation to keep the image slim.
|
||||
</Callout>
|
||||
|
|
@ -1,240 +0,0 @@
|
|||
---
|
||||
title: Quickstart
|
||||
description: Get Headroom running in 5 minutes. Install, compress, and send to your LLM with fewer tokens.
|
||||
---
|
||||
|
||||
This guide gets you from zero to compressed LLM calls in under 5 minutes.
|
||||
|
||||
## 1. Install
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```bash
|
||||
npm install headroom-ai
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```bash
|
||||
pip install "headroom-ai[all]"
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Callout type="info" title="TypeScript SDK requires the proxy">
|
||||
The TypeScript SDK sends messages to a local Headroom proxy for compression. Start the proxy before using the TS SDK:
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[proxy]"
|
||||
headroom proxy --port 8787
|
||||
```
|
||||
|
||||
The proxy runs the compression pipeline (Python) and exposes an HTTP API that the TS SDK calls.
|
||||
</Callout>
|
||||
|
||||
## 2. Compress messages
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
const messages = [
|
||||
{ role: 'system' as const, content: 'You analyze search results.' },
|
||||
{ role: 'user' as const, content: 'Search for Python tutorials.' },
|
||||
{
|
||||
role: 'assistant' as const,
|
||||
content: null,
|
||||
tool_calls: [{
|
||||
id: 'call_1',
|
||||
type: 'function' as const,
|
||||
function: { name: 'search', arguments: '{"q": "python"}' },
|
||||
}],
|
||||
},
|
||||
{
|
||||
role: 'tool' as const,
|
||||
tool_call_id: 'call_1',
|
||||
content: JSON.stringify({
|
||||
results: Array.from({ length: 500 }, (_, i) => ({
|
||||
title: `Result ${i}`,
|
||||
snippet: `Description ${i}`,
|
||||
score: 100 - i,
|
||||
})),
|
||||
}),
|
||||
},
|
||||
{ role: 'user' as const, content: 'What are the top 3 results?' },
|
||||
];
|
||||
|
||||
const result = await compress(messages, {
|
||||
model: 'gpt-4o',
|
||||
baseUrl: 'http://localhost:8787',
|
||||
});
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import compress
|
||||
import json
|
||||
|
||||
messages = [
|
||||
{"role": "system", "content": "You analyze search results."},
|
||||
{"role": "user", "content": "Search for Python tutorials."},
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": None,
|
||||
"tool_calls": [{
|
||||
"id": "call_1",
|
||||
"type": "function",
|
||||
"function": {"name": "search", "arguments": '{"q": "python"}'},
|
||||
}],
|
||||
},
|
||||
{
|
||||
"role": "tool",
|
||||
"tool_call_id": "call_1",
|
||||
"content": json.dumps({
|
||||
"results": [
|
||||
{"title": f"Result {i}", "snippet": f"Description {i}", "score": 100 - i}
|
||||
for i in range(500)
|
||||
]
|
||||
}),
|
||||
},
|
||||
{"role": "user", "content": "What are the top 3 results?"},
|
||||
]
|
||||
|
||||
result = compress(messages, model="gpt-4o")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 3. Send to your LLM
|
||||
|
||||
Use the compressed messages exactly like the originals:
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import OpenAI from 'openai';
|
||||
|
||||
const client = new OpenAI();
|
||||
|
||||
// result.messages from the previous step
|
||||
const messages: any[] = [];
|
||||
|
||||
const response = await client.chat.completions.create({
|
||||
model: 'gpt-4o',
|
||||
messages,
|
||||
});
|
||||
|
||||
console.log(response.choices[0].message.content);
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI()
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=result.messages,
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 4. Check your savings
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
const result = {
|
||||
tokensBefore: 45000,
|
||||
tokensAfter: 4500,
|
||||
tokensSaved: 40500,
|
||||
compressionRatio: 0.9,
|
||||
transformsApplied: ['smart_crusher', 'cache_aligner'],
|
||||
messages: [],
|
||||
ccrHashes: [],
|
||||
compressed: true,
|
||||
};
|
||||
// ---cut---
|
||||
console.log(`Tokens before: ${result.tokensBefore}`);
|
||||
console.log(`Tokens after: ${result.tokensAfter}`);
|
||||
console.log(`Tokens saved: ${result.tokensSaved}`);
|
||||
console.log(`Compression: ${(result.compressionRatio * 100).toFixed(0)}%`);
|
||||
console.log(`Transforms: ${result.transformsApplied.join(', ')}`);
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
Tokens before: 45000
|
||||
Tokens after: 4500
|
||||
Tokens saved: 40500
|
||||
Compression: 90%
|
||||
Transforms: smart_crusher, cache_aligner
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
print(f"Tokens before: {result.tokens_before}")
|
||||
print(f"Tokens after: {result.tokens_after}")
|
||||
print(f"Tokens saved: {result.tokens_saved}")
|
||||
print(f"Compression: {result.compression_ratio:.0%}")
|
||||
print(f"Transforms: {result.transforms_applied}")
|
||||
```
|
||||
|
||||
Example output:
|
||||
|
||||
```
|
||||
Tokens before: 45000
|
||||
Tokens after: 4500
|
||||
Tokens saved: 40500
|
||||
Compression: 90%
|
||||
Transforms: ['smart_crusher', 'cache_aligner']
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Alternative: proxy mode (zero code changes)
|
||||
|
||||
If you do not want to change any code, run Headroom as a proxy and point your existing client at it:
|
||||
|
||||
```bash
|
||||
# Start the proxy
|
||||
headroom proxy --port 8787
|
||||
|
||||
# Point Claude Code at it
|
||||
ANTHROPIC_BASE_URL=http://localhost:8787 claude
|
||||
|
||||
# Or any OpenAI-compatible client
|
||||
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
|
||||
```
|
||||
|
||||
All requests flow through Headroom automatically. Check savings at any time:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8787/stats
|
||||
# {"requests_total": 42, "tokens_saved_total": 125000, ...}
|
||||
```
|
||||
|
||||
## What gets compressed
|
||||
|
||||
The biggest savings come from tool outputs -- search results, database rows, log files, API responses. Headroom auto-detects the content type and routes it to the best compressor. No configuration needed.
|
||||
|
||||
| Content type | Compressor | Typical savings |
|
||||
|---|---|---|
|
||||
| JSON arrays | SmartCrusher | 70--90% |
|
||||
| Source code | CodeCompressor | 40--70% |
|
||||
| Build/test logs | LogCompressor | 80--95% |
|
||||
| Search results | SearchCompressor | 60--80% |
|
||||
| Plain text | Kompress | 30--50% |
|
||||
|
||||
## Next steps
|
||||
|
||||
<Cards>
|
||||
<Card title="Installation" href="/docs/installation" />
|
||||
<Card title="Proxy Server" href="/docs/proxy" />
|
||||
<Card title="How Compression Works" href="/docs/how-compression-works" />
|
||||
<Card title="Configuration" href="/docs/configuration" />
|
||||
</Cards>
|
||||
|
|
@ -1,277 +0,0 @@
|
|||
---
|
||||
title: Releases & CI/CD
|
||||
description: Automated release pipeline with semantic versioning, multi-package publishing, and changelog generation.
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Headroom uses a unified GitHub Actions workflow (`.github/workflows/release.yml`) that automatically publishes all three packages, builds version-matched Docker images, generates changelogs from conventional commits, and creates GitHub Releases with package assets attached.
|
||||
|
||||
The release workflow also calls `.github/workflows/docker.yml` as a reusable workflow so GHCR images are published in the same release run with the exact same synced version as PyPI, npm, and GitHub release assets.
|
||||
|
||||
## Packages & Registries
|
||||
|
||||
| Package | Type | Registry | Environment Variable |
|
||||
|---------|------|----------|----------------------|
|
||||
| `headroom-ai` | Python | PyPI | `PYPI_PACKAGE` |
|
||||
| `headroom-ai` | TypeScript SDK | npmjs.org | `NPM_SDK_PACKAGE` |
|
||||
| `headroom-openclaw` | TypeScript plugin | npmjs.org | `NPM_OPENCLAW_PACKAGE` |
|
||||
| `@{owner}/headroom-ai` | TypeScript SDK | GitHub Package Registry | — |
|
||||
| `@{owner}/headroom-openclaw` | TypeScript plugin | GitHub Package Registry | — |
|
||||
| `headroom-ai-{version}.tar.gz` / `headroom_ai-{version}-py3-none-any.whl` | Python package distributions | GitHub Release (`{owner}/headroom`) | — |
|
||||
| `headroom-ai-{version}.tgz` / `headroom-openclaw-{version}.tgz` | Node release assets | GitHub Release (`{owner}/headroom`) | — |
|
||||
| `ghcr.io/{owner}/headroom` | Docker image | GitHub Container Registry | — |
|
||||
|
||||
## Version Strategy
|
||||
|
||||
The workflow uses a **canonical + commit-height** algorithm that eliminates infinite loops:
|
||||
|
||||
1. `pyproject.toml` holds the **canonical version** (e.g., `0.5.25`). This is the single source of truth — set manually before merging.
|
||||
2. On every push to `main`, the workflow counts commits since the last tagged release at the same canonical level.
|
||||
3. The **git tag** uses `v{canonical}.{height}` format (e.g., `v0.5.25.3` = 3 commits since canonical `0.5.25`).
|
||||
4. The **npm version** uses 3-part semver — bumped from canonical based on commit type (e.g., `feat:` + canonical `0.5.25` → `0.6.0`).
|
||||
|
||||
### Version Files
|
||||
|
||||
- `pyproject.toml` — `[project].version` — **canonical** (set manually before merge)
|
||||
- `headroom/_version.py` — `__version__` — synced at build time
|
||||
- `plugins/openclaw/package.json` — `version` — synced at build time
|
||||
- `sdk/typescript/package.json` — `version` — synced at build time
|
||||
|
||||
**The workflow NEVER commits back to the repo** — this breaks the infinite loop.
|
||||
|
||||
## Conventional Commits & Semantic Bumping
|
||||
|
||||
The workflow analyzes the **unreleased commits since the previous release tag** and applies the highest required bump level:
|
||||
|
||||
| Commit | Bump | Git Tag Example | npm Version |
|
||||
|--------|------|-----------------|-------------|
|
||||
| `fix:`, `ci:`, `chore:`, `perf:`, `refactor:` | patch | `v0.5.25.3` | `0.5.26` |
|
||||
| `feat:` | minor | `v0.6.0.0` | `0.6.0` |
|
||||
| Any conventional commit with `!` or any commit with `BREAKING CHANGE` in the body | major | `v1.0.0.0` | `1.0.0` |
|
||||
|
||||
Commits are linted in CI via `commitlint` using `@commitlint/config-conventional`.
|
||||
|
||||
### How the Canonical + Height Algorithm Works
|
||||
|
||||
```
|
||||
Canonical in pyproject.toml: 0.5.25
|
||||
Last tag at this canonical: v0.5.25.2 (2 commits ago)
|
||||
|
||||
HEAD commit: fix: resolve bug
|
||||
→ bump = patch
|
||||
→ height = 3 (2 prior + 1 new)
|
||||
→ git tag: v0.5.25.3
|
||||
→ npm version: 0.5.26 (canonical 0.5.25 + 1 patch bump)
|
||||
```
|
||||
|
||||
After npm publishes `0.5.26`, update `pyproject.toml` to `0.5.26` (manually, before next release).
|
||||
|
||||
## Release Workflow
|
||||
|
||||
The `release.yml` workflow runs on every push to `main` and consists of five jobs:
|
||||
|
||||
```
|
||||
detect-version → build → publish-pypi
|
||||
→ publish-npm
|
||||
→ publish-github-packages → create-release
|
||||
```
|
||||
|
||||
**Note:** The workflow never commits back to the repo. `pyproject.toml` is updated manually before merging.
|
||||
|
||||
### detect-version
|
||||
Reads canonical version from `pyproject.toml`, counts commits since the previous release tag, chooses the highest bump level across that unreleased commit range, and computes both the git tag version (`v{canonical}.{height}`) and npm version (3-part semver).
|
||||
|
||||
### build
|
||||
1. Syncs version across TypeScript package files via `scripts/version-sync.py --version {npm_version}`
|
||||
2. Generates changelog via `scripts/changelog-gen.py`
|
||||
3. Builds the Python package (`python -m build`)
|
||||
4. Uploads artifacts (dist + changelog)
|
||||
|
||||
### publish-pypi
|
||||
Downloads the Python dist artifact and publishes to PyPI via `pypa/gh-action-pypi-publish@release/v1` (trusted publisher).
|
||||
|
||||
### publish-npm
|
||||
Publishes both TypeScript packages to npmjs.org:
|
||||
- `sdk/typescript/` as `headroom-ai`
|
||||
- `plugins/openclaw/` as `headroom-openclaw`
|
||||
|
||||
### publish-github-packages
|
||||
Publishes both Node packages to GitHub Package Registry (`npm.pkg.github.com`) using the current repository owner as the npm scope:
|
||||
- `sdk/typescript/` as `@{owner}/headroom-ai`
|
||||
- `plugins/openclaw/` as `@{owner}/headroom-openclaw`
|
||||
|
||||
### GitHub release assets
|
||||
Uploads the built Python distributions and both npm tarballs to the GitHub Release created in the current repository. GitHub Packages does not provide a PyPI-compatible package registry, so the workflow publishes Python wheels and sdists to GitHub as release assets while npm packages go to GitHub Package Registry and Docker images go to GHCR.
|
||||
|
||||
### publish-docker
|
||||
Calls the reusable Docker workflow to publish GHCR images with the same semantic version and synced package metadata as the rest of the release.
|
||||
|
||||
### create-release
|
||||
Creates or updates the GitHub Release in the current repo, uploads the built Python distributions and npm tarballs as release assets, and publishes the generated changelog as release notes. The job still runs after the build succeeds even if one of the external registry publishes fails, so GitHub-hosted artifacts remain available on `main`.
|
||||
|
||||
## Configuration
|
||||
|
||||
All package names, registry URLs, and environment names are defined as top-level `env` constants:
|
||||
|
||||
```yaml
|
||||
env:
|
||||
PYPI_PACKAGE: headroom-ai
|
||||
PYPI_ENVIRONMENT: pypi
|
||||
NPM_REGISTRY_URL: https://registry.npmjs.org
|
||||
NPM_SDK_PACKAGE: headroom-ai
|
||||
NPM_OPENCLAW_PACKAGE: headroom-openclaw
|
||||
GITHUB_PACKAGES_REGISTRY_URL: https://npm.pkg.github.com
|
||||
```
|
||||
|
||||
To rename a package, update the corresponding constant — all references throughout the workflow update automatically.
|
||||
|
||||
## Safety Gates
|
||||
|
||||
Each publish job requires **both** of the following to be false:
|
||||
|
||||
```yaml
|
||||
if: github.event.inputs.dry_run != 'true' && vars.PYPI_SKIP != 'true'
|
||||
```
|
||||
|
||||
To skip a publish target, set the corresponding GitHub Actions variable:
|
||||
|
||||
| Variable | Effect |
|
||||
|----------|--------|
|
||||
| `PYPI_SKIP=true` | Skip PyPI publish |
|
||||
| `NPM_SKIP=true` | Skip both npm publishes |
|
||||
| `GH_PACKAGES_SKIP=true` | Skip GitHub Package Registry publish |
|
||||
|
||||
Set these in: **GitHub repo → Settings → Variables → Actions Variables → New repository variable**.
|
||||
|
||||
PyPI publishing is a hard gate for GitHub Releases unless `PYPI_SKIP=true`.
|
||||
If the PyPI upload fails, the workflow stops before creating or updating the
|
||||
GitHub Release, so release notes cannot advertise a version that was not
|
||||
published to PyPI.
|
||||
|
||||
Before release artifacts are built, the workflow runs:
|
||||
|
||||
```bash
|
||||
python scripts/verify-versions.py
|
||||
```
|
||||
|
||||
That gate fails on cross-package version drift. The sdist build is also checked
|
||||
for a top-level `LICENSE` file before any publish job can consume it.
|
||||
|
||||
## Workflow Triggers
|
||||
|
||||
The workflow runs on push to `main`, but ignores pushes that only touch docs, CI config, or scripts:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths-ignore:
|
||||
- "docs/**"
|
||||
- ".github/workflows/ci.yml"
|
||||
- ".github/workflows/publish.yml"
|
||||
- "scripts/**"
|
||||
- ...
|
||||
```
|
||||
|
||||
For manual control, use `workflow_dispatch`:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "Manual version override (e.g. 0.6.0)"
|
||||
required: false
|
||||
dry_run:
|
||||
description: "Skip publish"
|
||||
type: boolean
|
||||
default: false
|
||||
```
|
||||
|
||||
- **No version input:** auto-detected from commits (normal flow)
|
||||
- **`dry_run: true`:** runs all jobs except publish steps — useful for testing
|
||||
|
||||
## Local Testing with `act`
|
||||
|
||||
### Prerequisites
|
||||
|
||||
```bash
|
||||
# Install act
|
||||
winget install act
|
||||
|
||||
# Optional: install actionlint for schema validation
|
||||
winget install actionlint
|
||||
```
|
||||
|
||||
### Dry-run Test
|
||||
|
||||
```bash
|
||||
act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.json
|
||||
```
|
||||
|
||||
This runs the full workflow end-to-end with `dry_run=true`, skipping all publish steps.
|
||||
|
||||
### Test a Specific Commit Type
|
||||
|
||||
```bash
|
||||
act push -W .github/workflows/release.yml -e .github/act/push-feat.json
|
||||
```
|
||||
|
||||
The `push-feat.json` event file simulates a `feat:` commit on `main`.
|
||||
|
||||
### Validate the Release and Docker Workflows
|
||||
|
||||
```bash
|
||||
bash scripts/validate-workflows.sh
|
||||
```
|
||||
|
||||
This runs `actionlint` plus `act -n` against the release and Docker workflows using the checked-in `.github/act/*.json` event fixtures. CI runs the same script in the `workflow-validation` job so branch changes to release automation are validated before merge.
|
||||
|
||||
### Local Secrets
|
||||
|
||||
```bash
|
||||
cp .env.act.example .env.act
|
||||
# Edit .env.act and add your test tokens
|
||||
```
|
||||
|
||||
`act` automatically reads `.env` and passes values as workflow secrets.
|
||||
|
||||
## Workflow Files Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `.github/workflows/release.yml` | Main release pipeline |
|
||||
| `.github/workflows/ci.yml` | CI — lint, test, commitlint |
|
||||
| `.github/workflows/publish.yml` | Manual-only PyPI fallback (superseded by `release.yml`) |
|
||||
| `.commitlintrc.json` | Conventional commit rules |
|
||||
| `scripts/version-sync.py` | Sync version across all packages |
|
||||
| `scripts/changelog-gen.py` | Generate changelog from git log |
|
||||
| `scripts/verify-versions.py` | Pre-release version alignment check |
|
||||
| `.github/act/dry-run.json` | `act` event file for dry-run testing |
|
||||
| `.github/act/push-feat.json` | `act` event file for feat commit testing |
|
||||
| `.github/act/docker-version.json` | `act` event file for Docker workflow validation |
|
||||
| `scripts/validate-workflows.sh` | Shared `actionlint` + `act -n` workflow validation script |
|
||||
| `.actrc` | Default `act` flags (Ubuntu runner, reuse, quiet) |
|
||||
| `.actrc.local.example` | Local `act` override template |
|
||||
|
||||
## Required GitHub Secrets
|
||||
|
||||
| Secret | Purpose | Where to Get |
|
||||
|--------|---------|--------------|
|
||||
| `NPM_TOKEN` | Publishing to npmjs.org | npmjs.com → Account → Access Tokens |
|
||||
| `GITHUB_TOKEN` | GitHub Package Registry (auto-provided) | Automatically available in GitHub Actions |
|
||||
|
||||
The PyPI publish uses trusted publisher OIDC — no secret required, only the `pypi` GitHub Environment must be configured with your PyPI project.
|
||||
|
||||
## First Release Note
|
||||
|
||||
TypeScript packages (`headroom-ai` SDK and `headroom-openclaw`) start at version `0.1.0`, while Python `headroom-ai` is at `0.5.25`. Before the first automated release:
|
||||
|
||||
1. Update `pyproject.toml` to set the desired canonical version (e.g., `0.6.0`)
|
||||
2. Use `workflow_dispatch` with a manual `version` input to set the target version explicitly
|
||||
3. The workflow will align all three packages to the same version on first release
|
||||
|
||||
### Release Cadence with Canonical + Height
|
||||
|
||||
After each release, update `pyproject.toml` to match the published version before merging the next feature branch. This keeps the canonical current and ensures each release gets a unique git tag.
|
||||
|
|
@ -1,227 +0,0 @@
|
|||
---
|
||||
title: SharedContext
|
||||
description: Compressed inter-agent context sharing. Reduce token usage by ~80% when agents hand off to each other.
|
||||
---
|
||||
|
||||
When agents hand off to each other, context gets replayed in full. SharedContext compresses what moves between agents using Headroom's compression pipeline, typically saving **~80% of tokens** on agent handoffs.
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { SharedContext } from "headroom";
|
||||
|
||||
const ctx = new SharedContext();
|
||||
|
||||
// Agent A stores large output
|
||||
const entry = await ctx.put("research", bigResearchOutput, {
|
||||
agent: "researcher",
|
||||
});
|
||||
|
||||
// Agent B gets compressed version (~80% smaller)
|
||||
const summary = ctx.get("research");
|
||||
|
||||
// Agent B needs full details on demand
|
||||
const full = ctx.get("research", { full: true });
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import SharedContext
|
||||
|
||||
ctx = SharedContext()
|
||||
|
||||
# Agent A stores large output
|
||||
ctx.put("research", big_research_output, agent="researcher")
|
||||
|
||||
# Agent B gets compressed version (~80% smaller)
|
||||
summary = ctx.get("research")
|
||||
|
||||
# Agent B needs full details on demand
|
||||
full = ctx.get("research", full=True)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## API
|
||||
|
||||
### `put(key, content, agent?)`
|
||||
|
||||
Store content under a key. Compresses automatically using Headroom's full pipeline (SmartCrusher for JSON, CodeCompressor for code, Kompress for text).
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { SharedContext } from "headroom";
|
||||
const ctx = new SharedContext();
|
||||
// ---cut---
|
||||
const entry = await ctx.put("findings", bigJsonOutput, {
|
||||
agent: "researcher",
|
||||
});
|
||||
|
||||
entry.originalTokens; // 20000
|
||||
entry.compressedTokens; // 4000
|
||||
entry.savingsPercent; // 80.0
|
||||
entry.transforms; // ["router:json:0.20"]
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
entry = ctx.put("findings", big_json_output, agent="researcher")
|
||||
|
||||
entry.original_tokens # 20,000
|
||||
entry.compressed_tokens # 4,000
|
||||
entry.savings_percent # 80.0
|
||||
entry.transforms # ["router:json:0.20"]
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### `get(key, full?)`
|
||||
|
||||
Retrieve content. Returns the compressed version by default, or the original with `full=True`.
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { SharedContext } from "headroom";
|
||||
const ctx = new SharedContext();
|
||||
// ---cut---
|
||||
const compressed = ctx.get("findings"); // 4K tokens
|
||||
const original = ctx.get("findings", { full: true }); // 20K tokens
|
||||
const missing = ctx.get("nonexistent"); // null
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
compressed = ctx.get("findings") # 4K tokens
|
||||
original = ctx.get("findings", full=True) # 20K tokens
|
||||
missing = ctx.get("nonexistent") # None
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### `stats()`
|
||||
|
||||
Aggregated statistics across all entries.
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { SharedContext } from "headroom";
|
||||
const ctx = new SharedContext();
|
||||
// ---cut---
|
||||
const stats = ctx.stats();
|
||||
stats.entries; // 3
|
||||
stats.totalOriginalTokens; // 60000
|
||||
stats.totalCompressedTokens; // 12000
|
||||
stats.totalTokensSaved; // 48000
|
||||
stats.savingsPercent; // 80.0
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
stats = ctx.stats()
|
||||
stats.entries # 3
|
||||
stats.total_original_tokens # 60000
|
||||
stats.total_compressed_tokens # 12000
|
||||
stats.total_tokens_saved # 48000
|
||||
stats.savings_percent # 80.0
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### `keys()` and `clear()`
|
||||
|
||||
`keys()` lists all non-expired keys. `clear()` removes all entries.
|
||||
|
||||
## Configuration
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { SharedContext } from "headroom";
|
||||
// ---cut---
|
||||
const ctx = new SharedContext({
|
||||
model: "claude-sonnet-4-5-20250929", // For token counting
|
||||
ttl: 3600, // 1 hour (default)
|
||||
maxEntries: 100, // Evicts oldest when full
|
||||
});
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
ctx = SharedContext(
|
||||
model="claude-sonnet-4-5-20250929", # For token counting
|
||||
ttl=3600, # 1 hour (default)
|
||||
max_entries=100, # Evicts oldest when full
|
||||
)
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Entries expire after `ttl` seconds. When `maxEntries` is reached, the oldest entry is evicted.
|
||||
|
||||
## Framework Examples
|
||||
|
||||
SharedContext is framework-agnostic. It works anywhere context moves between agents.
|
||||
|
||||
### CrewAI
|
||||
|
||||
```python
|
||||
from headroom import SharedContext
|
||||
|
||||
ctx = SharedContext()
|
||||
|
||||
# After researcher task completes
|
||||
ctx.put("findings", researcher_task.output.raw)
|
||||
|
||||
# Coder task gets compressed context
|
||||
coder_context = ctx.get("findings")
|
||||
```
|
||||
|
||||
### LangGraph
|
||||
|
||||
```python
|
||||
from headroom import SharedContext
|
||||
|
||||
ctx = SharedContext()
|
||||
|
||||
def researcher_node(state):
|
||||
result = do_research()
|
||||
ctx.put("research", result)
|
||||
return {"research_summary": ctx.get("research")}
|
||||
|
||||
def coder_node(state):
|
||||
# Compressed summary in state, full details on demand
|
||||
full = ctx.get("research", full=True)
|
||||
return {"code": write_code(full)}
|
||||
```
|
||||
|
||||
### OpenAI Agents SDK
|
||||
|
||||
```python
|
||||
from headroom import SharedContext
|
||||
|
||||
ctx = SharedContext()
|
||||
|
||||
def compress_handoff(messages):
|
||||
for msg in messages:
|
||||
if len(msg.content) > 1000:
|
||||
ctx.put(msg.id, msg.content)
|
||||
msg.content = ctx.get(msg.id)
|
||||
return messages
|
||||
|
||||
handoff(agent=coder, input_filter=compress_handoff)
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
Under the hood, `put()` calls `headroom.compress()` -- the same pipeline used by the Headroom proxy -- and stores the original in memory. `get()` returns the compressed version. `get(full=True)` returns the original.
|
||||
|
||||
The compression pipeline routes content to the best compressor:
|
||||
|
||||
- **JSON arrays** -- SmartCrusher (70-95% compression)
|
||||
- **Code** -- CodeCompressor (AST-aware)
|
||||
- **Text** -- Kompress (ModernBERT-based) or passthrough
|
||||
|
|
@ -1,149 +0,0 @@
|
|||
---
|
||||
title: Simulation
|
||||
description: Preview compression results without making an LLM call. Use simulation for cost estimation, debugging, and understanding waste signals.
|
||||
---
|
||||
|
||||
Simulation mode lets you preview what Headroom would do to your messages without sending them to an LLM. This is useful for cost estimation, debugging compression behavior, and understanding where token waste comes from.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
// compress() returns the same result structure —
|
||||
// use it without sending to your LLM to simulate
|
||||
const result = await compress(messages, { model: 'gpt-4o' });
|
||||
console.log(`Would save: ${result.tokensSaved} tokens`);
|
||||
console.log(`Compression ratio: ${(result.compressionRatio * 100).toFixed(1)}%`);
|
||||
console.log(`Transforms: ${result.transformsApplied.join(', ')}`);
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
plan = client.chat.completions.simulate(
|
||||
model="gpt-4o",
|
||||
messages=large_conversation,
|
||||
)
|
||||
|
||||
print(f"Tokens before: {plan.tokens_before}")
|
||||
print(f"Tokens after: {plan.tokens_after}")
|
||||
print(f"Would save: {plan.tokens_saved} tokens ({plan.savings_percent:.1f}%)")
|
||||
print(f"Transforms: {plan.transforms_applied}")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Waste Signals
|
||||
|
||||
Simulation reports where token waste comes from in your messages:
|
||||
|
||||
```python
|
||||
plan = client.chat.completions.simulate(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
)
|
||||
|
||||
waste = plan.waste_signals
|
||||
print(f"JSON bloat: {waste.json_bloat_tokens} tokens")
|
||||
print(f"HTML noise: {waste.html_noise_tokens} tokens")
|
||||
print(f"Whitespace: {waste.whitespace_tokens} tokens")
|
||||
print(f"Dynamic dates: {waste.dynamic_date_tokens} tokens")
|
||||
print(f"Repetition: {waste.repetition_tokens} tokens")
|
||||
```
|
||||
|
||||
Waste signals help you understand which parts of your input are contributing the most unnecessary tokens.
|
||||
|
||||
## Block Breakdown
|
||||
|
||||
The parser breaks your conversation into blocks so you can see where tokens are concentrated:
|
||||
|
||||
```python
|
||||
# Block types: system, user, assistant, tool_call, tool_result, rag
|
||||
# The breakdown shows token counts per block type
|
||||
```
|
||||
|
||||
| Block Kind | Description |
|
||||
|-----------|-------------|
|
||||
| `system` | System prompt instructions |
|
||||
| `user` | User messages |
|
||||
| `assistant` | Model responses |
|
||||
| `tool_call` | Function call requests |
|
||||
| `tool_result` | Tool output (largest source of waste) |
|
||||
| `rag` | Retrieved document context |
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Cost Estimation
|
||||
|
||||
Run simulation on a representative sample of your workload to estimate savings before enabling `optimize` mode:
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
total_before = 0
|
||||
total_after = 0
|
||||
|
||||
for messages in sample_conversations:
|
||||
plan = client.chat.completions.simulate(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
)
|
||||
total_before += plan.tokens_before
|
||||
total_after += plan.tokens_after
|
||||
|
||||
savings_pct = (1 - total_after / total_before) * 100
|
||||
print(f"Estimated savings: {savings_pct:.1f}%")
|
||||
print(f"Tokens saved: {total_before - total_after:,}")
|
||||
```
|
||||
|
||||
### Debugging Compression
|
||||
|
||||
Use simulation to understand why a particular conversation is or is not being compressed:
|
||||
|
||||
```python
|
||||
plan = client.chat.completions.simulate(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
)
|
||||
|
||||
if plan.tokens_saved == 0:
|
||||
print("No compression applied. Possible reasons:")
|
||||
print("- Messages are too short (< 200 tokens per tool output)")
|
||||
print("- No tool outputs with compressible JSON arrays")
|
||||
print("- Content is already compact (code, grep results)")
|
||||
else:
|
||||
print(f"Transforms applied: {plan.transforms_applied}")
|
||||
# See the optimized messages
|
||||
print(json.dumps(plan.messages_optimized, indent=2))
|
||||
```
|
||||
|
||||
### Comparing Configurations
|
||||
|
||||
Test different configurations to find the best settings for your workload:
|
||||
|
||||
```python
|
||||
from headroom import HeadroomClient, OpenAIProvider
|
||||
from headroom.transforms import SmartCrusherConfig
|
||||
|
||||
configs = [
|
||||
SmartCrusherConfig(max_items_after_crush=10),
|
||||
SmartCrusherConfig(max_items_after_crush=25),
|
||||
SmartCrusherConfig(max_items_after_crush=50),
|
||||
]
|
||||
|
||||
for config in configs:
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
smart_crusher_config=config,
|
||||
)
|
||||
plan = client.chat.completions.simulate(model="gpt-4o", messages=messages)
|
||||
print(f"max_items={config.max_items_after_crush}: "
|
||||
f"{plan.tokens_saved} tokens saved ({plan.savings_percent:.1f}%)")
|
||||
```
|
||||
|
||||
<Callout type="info" title="No API call">
|
||||
Simulation never calls the LLM API. It runs the full transform pipeline locally and returns the results, so there is no cost and no latency from the provider.
|
||||
</Callout>
|
||||
|
|
@ -1,143 +0,0 @@
|
|||
---
|
||||
title: SmartCrusher
|
||||
description: Statistical JSON and array compression that keeps important items and drops the rest, achieving 70-90% token reduction.
|
||||
---
|
||||
|
||||
SmartCrusher is Headroom's compressor for JSON tool outputs. It analyzes arrays statistically, keeps the important items (errors, anomalies, relevant matches), and drops the rest. This is the compressor that fires automatically when ContentRouter detects JSON arrays.
|
||||
|
||||
## How It Works
|
||||
|
||||
SmartCrusher doesn't blindly truncate arrays. It scores each item across five dimensions:
|
||||
|
||||
1. **First/Last items** -- Context for pagination and recency
|
||||
2. **Error items** -- 100% preservation of error states (never dropped)
|
||||
3. **Anomalies** -- Statistical outliers (> 2 standard deviations from the mean)
|
||||
4. **Relevant items** -- Matches to the user's query via BM25/embeddings
|
||||
5. **Change points** -- Significant transitions in data
|
||||
|
||||
The result: a 1,000-item array becomes ~50 items with all the information the LLM actually needs.
|
||||
|
||||
## What Gets Preserved
|
||||
|
||||
| Category | Preserved | Why |
|
||||
|---|---|---|
|
||||
| Errors | 100% | Critical for debugging |
|
||||
| First N | 100% | Context and pagination |
|
||||
| Last N | 100% | Recency |
|
||||
| Anomalies | All | Unusual values matter |
|
||||
| Relevant | Top K | Match user's query |
|
||||
| Others | Sampled | Statistical representation |
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from "headroom-ai";
|
||||
|
||||
// SmartCrusher fires automatically for JSON tool outputs
|
||||
const messages = [
|
||||
{ role: "system" as const, content: "You are a helpful assistant." },
|
||||
{ role: "user" as const, content: "Find errors in the last 24 hours" },
|
||||
{
|
||||
role: "tool" as const,
|
||||
content: JSON.stringify({ results: new Array(1000).fill({ status: "ok" }) }),
|
||||
tool_call_id: "call_1",
|
||||
},
|
||||
];
|
||||
|
||||
const result = await compress(messages);
|
||||
console.log(`Tokens saved: ${result.tokensSaved}`);
|
||||
// SmartCrusher keeps errors, anomalies, and relevant items
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import SmartCrusher
|
||||
|
||||
crusher = SmartCrusher()
|
||||
|
||||
# Before: 1000 search results (45,000 tokens)
|
||||
tool_output = {"results": ["...1000 items..."]}
|
||||
|
||||
# After: ~50 important items (4,500 tokens) -- 90% reduction
|
||||
compressed = crusher.crush(tool_output, query="user's question")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Configuration
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from "headroom-ai";
|
||||
|
||||
// Configure via the Headroom proxy or HeadroomClient
|
||||
const result = await compress(messages, {
|
||||
model: "gpt-4o",
|
||||
tokenBudget: 10000, // SmartCrusher will reduce JSON to fit
|
||||
});
|
||||
|
||||
console.log(`Transforms: ${result.transformsApplied}`);
|
||||
// ["smart_crusher", "cache_aligner"]
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
from headroom import SmartCrusher, SmartCrusherConfig
|
||||
|
||||
config = SmartCrusherConfig(
|
||||
min_tokens_to_crush=200, # Only compress if > 200 tokens
|
||||
max_items_after_crush=50, # Keep at most 50 items
|
||||
keep_first=3, # Always keep first 3 items
|
||||
keep_last=2, # Always keep last 2 items
|
||||
relevance_threshold=0.3, # Keep items with relevance > 0.3
|
||||
anomaly_std_threshold=2.0, # Keep items > 2 std dev from mean
|
||||
preserve_errors=True, # Always keep error items
|
||||
)
|
||||
|
||||
crusher = SmartCrusher(config)
|
||||
compressed = crusher.crush(tool_output, query="find payment failures")
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Option | Default | Description |
|
||||
|---|---|---|
|
||||
| `min_tokens_to_crush` | `200` | Only compress arrays with more than this many tokens |
|
||||
| `max_items_after_crush` | `50` | Maximum items to keep after compression |
|
||||
| `keep_first` | `3` | Always keep the first N items |
|
||||
| `keep_last` | `2` | Always keep the last N items |
|
||||
| `relevance_threshold` | `0.3` | Minimum relevance score to keep an item |
|
||||
| `anomaly_std_threshold` | `2.0` | Standard deviation threshold for anomaly detection |
|
||||
| `preserve_errors` | `True` | Always keep items containing error states |
|
||||
|
||||
## Example: Before and After
|
||||
|
||||
Consider a tool that returns 1,000 search results:
|
||||
|
||||
```python
|
||||
# Before compression: 45,000 tokens
|
||||
{
|
||||
"results": [
|
||||
{"id": 1, "status": "ok", "message": "Success", "timestamp": "..."},
|
||||
{"id": 2, "status": "ok", "message": "Success", "timestamp": "..."},
|
||||
# ... 995 more "ok" results ...
|
||||
{"id": 998, "status": "error", "message": "Connection timeout", "timestamp": "..."},
|
||||
{"id": 999, "status": "ok", "message": "Success", "timestamp": "..."},
|
||||
{"id": 1000, "status": "ok", "message": "Success", "timestamp": "..."},
|
||||
]
|
||||
}
|
||||
|
||||
# After SmartCrusher: 4,500 tokens (90% reduction)
|
||||
# Kept: first 3, last 2, the error at id=998, statistical sample
|
||||
```
|
||||
|
||||
The LLM sees the structure, the error, and a representative sample -- everything it needs to answer "find errors in the last 24 hours" without wading through 1,000 identical success responses.
|
||||
|
||||
<Callout type="info" title="Automatic routing">
|
||||
You don't need to call SmartCrusher directly. The ContentRouter detects JSON arrays and routes them to SmartCrusher automatically. Direct usage is available when you want fine-grained control over the configuration.
|
||||
</Callout>
|
||||
|
|
@ -1,137 +0,0 @@
|
|||
---
|
||||
title: Strands
|
||||
description: Context compression for Strands Agents via model wrapping and hook-based tool output compression.
|
||||
---
|
||||
|
||||
Headroom integrates with [Strands Agents](https://github.com/strands-agents/sdk-python) through two patterns: wrap the model for full conversation compression, or hook into tool calls for targeted tool output compression.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
pip install headroom-ai strands-agents
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```python
|
||||
from strands import Agent
|
||||
from strands.models.bedrock import BedrockModel
|
||||
from headroom.integrations.strands import HeadroomStrandsModel
|
||||
|
||||
model = BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
|
||||
optimized = HeadroomStrandsModel(wrapped_model=model)
|
||||
|
||||
agent = Agent(model=optimized)
|
||||
response = agent("Investigate the production incident")
|
||||
|
||||
print(f"Tokens saved: {optimized.total_tokens_saved}")
|
||||
```
|
||||
|
||||
## Model wrapping
|
||||
|
||||
Wraps the Strands `Model` interface. Every call to `stream()` compresses messages before they reach the provider:
|
||||
|
||||
```python
|
||||
from headroom import HeadroomConfig
|
||||
from headroom.integrations.strands import HeadroomStrandsModel
|
||||
|
||||
optimized = HeadroomStrandsModel(
|
||||
wrapped_model=model,
|
||||
config=HeadroomConfig(),
|
||||
)
|
||||
|
||||
agent = Agent(model=optimized)
|
||||
response = agent("Analyze these logs")
|
||||
```
|
||||
|
||||
## Hook provider (tool output compression)
|
||||
|
||||
Compresses tool call results via Strands' hook system. Uses SmartCrusher on JSON arrays returned by tools:
|
||||
|
||||
```python
|
||||
from strands import Agent
|
||||
from strands.models.bedrock import BedrockModel
|
||||
from headroom.integrations.strands import HeadroomHookProvider
|
||||
|
||||
model = BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514-v1:0")
|
||||
hooks = HeadroomHookProvider(
|
||||
compress_tool_outputs=True,
|
||||
min_tokens_to_compress=200,
|
||||
preserve_errors=True,
|
||||
)
|
||||
|
||||
agent = Agent(model=model, hooks=[hooks])
|
||||
response = agent("Search the database for recent failures")
|
||||
|
||||
print(f"Tokens saved by hooks: {hooks.total_tokens_saved}")
|
||||
```
|
||||
|
||||
The hook preserves error items, anomalous values (statistical outliers), items matching the query context, and boundary items (first/last).
|
||||
|
||||
## Both together
|
||||
|
||||
Model wrapping compresses conversation history. Hooks compress individual tool results. Use both for maximum savings:
|
||||
|
||||
```python
|
||||
from headroom.integrations.strands import HeadroomStrandsModel, HeadroomHookProvider
|
||||
|
||||
optimized = HeadroomStrandsModel(wrapped_model=model)
|
||||
hooks = HeadroomHookProvider(compress_tool_outputs=True)
|
||||
|
||||
agent = Agent(model=optimized, hooks=[hooks])
|
||||
```
|
||||
|
||||
## How it works
|
||||
|
||||
```
|
||||
Agent decides to call tool
|
||||
|
|
||||
v
|
||||
Tool executes, returns result
|
||||
|
|
||||
v
|
||||
HeadroomHookProvider (optional)
|
||||
compresses tool result JSON
|
||||
|
|
||||
v
|
||||
Agent builds next API request
|
||||
|
|
||||
v
|
||||
HeadroomStrandsModel.stream()
|
||||
compresses full message list
|
||||
|
|
||||
v
|
||||
Provider API (Bedrock, etc.)
|
||||
```
|
||||
|
||||
The model wrapper uses the full Headroom pipeline (CacheAligner, ContentRouter, IntelligentContext). The hook provider uses SmartCrusher directly for fast JSON compression.
|
||||
|
||||
## Structured output
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
|
||||
class Analysis(BaseModel):
|
||||
severity: str
|
||||
root_cause: str
|
||||
recommendation: str
|
||||
|
||||
result = optimized.structured_output(Analysis, messages)
|
||||
```
|
||||
|
||||
## Metrics
|
||||
|
||||
```python
|
||||
for m in optimized.metrics_history:
|
||||
print(f" {m.tokens_before} -> {m.tokens_after} ({m.tokens_saved} saved)")
|
||||
|
||||
print(f"Total saved: {optimized.total_tokens_saved}")
|
||||
```
|
||||
|
||||
## Supported providers
|
||||
|
||||
| Strands Model | Provider Detected |
|
||||
|--------------|-------------------|
|
||||
| `BedrockModel` | Anthropic (via Bedrock) |
|
||||
| `OllamaModel` | OpenAI-compatible |
|
||||
| Custom `Model` | Falls back to estimation |
|
||||
|
|
@ -1,192 +0,0 @@
|
|||
---
|
||||
title: Text & Log Compression
|
||||
description: Specialized compressors for search results, build logs, diffs, and general text. Each preserves what matters for its content type.
|
||||
---
|
||||
|
||||
Headroom provides specialized compressors for text-based content that isn't JSON or source code. Each one understands the structure of its content type and preserves what the LLM needs while dropping the noise.
|
||||
|
||||
| Compressor | Input Type | What It Preserves | Typical Savings |
|
||||
|---|---|---|---|
|
||||
| `SearchCompressor` | grep/ripgrep output | Relevant matches, file diversity | 80-95% |
|
||||
| `LogCompressor` | Build/test logs | Errors, stack traces, summaries | 85-95% |
|
||||
| `DiffCompressor` | Unified diffs | Changed lines, context | 60-80% |
|
||||
| `TextCompressor` | General text | Relevant paragraphs, anchors | 60-80% |
|
||||
| `KompressCompressor` | General text fallback | Learned token scoring via ONNX | 30-50% |
|
||||
|
||||
## SearchCompressor
|
||||
|
||||
Compresses search results (grep, ripgrep, ag) while keeping the matches that matter.
|
||||
|
||||
```python
|
||||
from headroom.transforms import SearchCompressor
|
||||
|
||||
search_results = """
|
||||
src/utils.py:42:def process_data(items):
|
||||
src/utils.py:43: \"\"\"Process items.\"\"\"
|
||||
src/models.py:15:class DataProcessor:
|
||||
src/models.py:89: def process(self, items):
|
||||
... hundreds more matches ...
|
||||
"""
|
||||
|
||||
compressor = SearchCompressor()
|
||||
result = compressor.compress(search_results, context="find process")
|
||||
|
||||
print(f"Compressed {result.original_match_count} matches to {result.compressed_match_count}")
|
||||
print(result.compressed)
|
||||
```
|
||||
|
||||
**What gets preserved:**
|
||||
- Exact query matches (lines containing the search term)
|
||||
- High-relevance matches (scored by BM25 similarity)
|
||||
- File diversity (results from different files are kept)
|
||||
- First/last matches (context from start and end)
|
||||
|
||||
### Configuration
|
||||
|
||||
```python
|
||||
from headroom.transforms import SearchCompressor, SearchCompressorConfig
|
||||
|
||||
config = SearchCompressorConfig(
|
||||
max_results=50, # Keep up to 50 matches
|
||||
preserve_file_diversity=True, # Ensure different files represented
|
||||
relevance_threshold=0.3, # Minimum relevance score to keep
|
||||
)
|
||||
|
||||
compressor = SearchCompressor(config)
|
||||
```
|
||||
|
||||
## LogCompressor
|
||||
|
||||
Compresses build and test output while preserving errors, warnings, and summaries.
|
||||
|
||||
```python
|
||||
from headroom.transforms import LogCompressor
|
||||
|
||||
build_output = """
|
||||
===== test session starts =====
|
||||
collected 500 items
|
||||
tests/test_foo.py::test_1 PASSED
|
||||
... hundreds of passed tests ...
|
||||
tests/test_bar.py::test_fail FAILED
|
||||
AssertionError: expected 5, got 3
|
||||
===== 1 failed, 499 passed =====
|
||||
"""
|
||||
|
||||
compressor = LogCompressor()
|
||||
result = compressor.compress(build_output)
|
||||
|
||||
print(result.compressed)
|
||||
print(f"Compression ratio: {result.compression_ratio:.1%}")
|
||||
```
|
||||
|
||||
**What gets preserved:**
|
||||
- Errors and failures (any line with ERROR, FAILED, Exception)
|
||||
- Warnings
|
||||
- Full stack traces for debugging
|
||||
- Test/build summary lines
|
||||
- Section headers (structural markers like `=====`)
|
||||
|
||||
**What gets dropped:**
|
||||
- Hundreds of `PASSED` lines
|
||||
- Verbose success output
|
||||
- Repeated patterns
|
||||
|
||||
## DiffCompressor
|
||||
|
||||
Compresses unified diffs while keeping the actual changes and enough context to understand them.
|
||||
|
||||
```python
|
||||
from headroom.transforms import DiffCompressor
|
||||
|
||||
diff_output = """
|
||||
diff --git a/src/main.py b/src/main.py
|
||||
--- a/src/main.py
|
||||
+++ b/src/main.py
|
||||
@@ -42,7 +42,7 @@
|
||||
def process(items):
|
||||
- return [x for x in items]
|
||||
+ return [x.strip() for x in items if x]
|
||||
"""
|
||||
|
||||
compressor = DiffCompressor()
|
||||
result = compressor.compress(diff_output)
|
||||
```
|
||||
|
||||
## TextCompressor
|
||||
|
||||
General-purpose text compression with anchor preservation. Best for documentation, README files, and prose content.
|
||||
|
||||
```python
|
||||
from headroom.transforms import TextCompressor
|
||||
|
||||
long_text = """
|
||||
... thousands of lines of documentation ...
|
||||
"""
|
||||
|
||||
compressor = TextCompressor()
|
||||
result = compressor.compress(long_text, context="authentication")
|
||||
|
||||
print(result.compressed)
|
||||
```
|
||||
|
||||
**What gets preserved:**
|
||||
- Paragraphs relevant to the context query
|
||||
- Headers and section markers
|
||||
- Document structure and organization
|
||||
|
||||
## Kompress
|
||||
|
||||
```python
|
||||
from headroom.transforms.kompress_compressor import KompressCompressor
|
||||
|
||||
compressor = KompressCompressor()
|
||||
result = compressor.compress(long_output)
|
||||
|
||||
print(f"Before: {result.original_tokens} tokens")
|
||||
print(f"After: {result.compressed_tokens} tokens")
|
||||
print(f"Saved: {result.savings_percentage:.1f}%")
|
||||
```
|
||||
|
||||
<Callout type="info" title="LLMLingua was removed">
|
||||
The old LLMLingua transform and helper functions are no longer exported. Use Kompress and ContentRouter for text compression.
|
||||
</Callout>
|
||||
|
||||
## Content Type Detection
|
||||
|
||||
If you're building your own routing logic, you can use the content type detector directly:
|
||||
|
||||
```python
|
||||
from headroom.transforms import detect_content_type, ContentType
|
||||
|
||||
content = "src/main.py:42:def process():"
|
||||
|
||||
detection = detect_content_type(content)
|
||||
if detection.content_type == ContentType.SEARCH_RESULTS:
|
||||
result = SearchCompressor().compress(content, context="process")
|
||||
elif detection.content_type == ContentType.BUILD_OUTPUT:
|
||||
result = LogCompressor().compress(content)
|
||||
elif detection.content_type == ContentType.PLAIN_TEXT:
|
||||
result = TextCompressor().compress(content, context="process")
|
||||
```
|
||||
|
||||
## When Each Compressor Is Used
|
||||
|
||||
The ContentRouter selects the right compressor automatically. Here's when each fires:
|
||||
|
||||
| Content Pattern | Compressor | Detection Signal |
|
||||
|---|---|---|
|
||||
| `file:line:content` lines | SearchCompressor | grep/ripgrep output format |
|
||||
| pytest, npm, cargo markers | LogCompressor | Build tool output patterns |
|
||||
| `---/+++` and `@@` markers | DiffCompressor | Unified diff format |
|
||||
| Prose, documentation | TextCompressor | Fallback for non-structured text |
|
||||
| Long plain text | KompressCompressor | ContentRouter fallback |
|
||||
|
||||
## Performance
|
||||
|
||||
| Compressor | Typical Input | Output | Speed |
|
||||
|---|---|---|---|
|
||||
| SearchCompressor | 1,000 matches | 30-50 matches | ~2ms |
|
||||
| LogCompressor | 5,000 lines | 100-200 lines | ~3ms |
|
||||
| DiffCompressor | Large diff | Changed hunks only | ~2ms |
|
||||
| TextCompressor | 10,000 chars | 2,000 chars | ~2ms |
|
||||
| KompressCompressor | Plain text | 50-70% of original | model-dependent |
|
||||
|
|
@ -1,383 +0,0 @@
|
|||
---
|
||||
title: Troubleshooting
|
||||
description: Solutions for common Headroom issues including proxy startup, connection errors, no token savings, high latency, and installation problems.
|
||||
---
|
||||
|
||||
Solutions for common Headroom issues.
|
||||
|
||||
## Proxy Server Issues
|
||||
|
||||
### Proxy will not start
|
||||
|
||||
**Symptom**: `headroom proxy` fails or hangs.
|
||||
|
||||
```bash
|
||||
# Check if port is already in use
|
||||
lsof -i :8787
|
||||
|
||||
# Try a different port
|
||||
headroom proxy --port 8788
|
||||
|
||||
# Check for missing dependencies
|
||||
pip install "headroom-ai[proxy]"
|
||||
|
||||
# Run with debug logging
|
||||
headroom proxy --log-level debug
|
||||
```
|
||||
|
||||
### Connection refused when calling proxy
|
||||
|
||||
**Symptom**: `curl: (7) Failed to connect to localhost port 8787`
|
||||
|
||||
```bash
|
||||
# Verify proxy is running
|
||||
curl http://localhost:8787/health
|
||||
|
||||
# Check if proxy started on a different port
|
||||
ps aux | grep headroom
|
||||
```
|
||||
|
||||
### Proxy returns errors for some requests
|
||||
|
||||
**Symptom**: Some requests work, others fail with 502/503.
|
||||
|
||||
```bash
|
||||
# Check proxy logs for the actual error
|
||||
headroom proxy --log-level debug
|
||||
|
||||
# Verify API key is set
|
||||
echo $OPENAI_API_KEY # or ANTHROPIC_API_KEY
|
||||
|
||||
# Test the underlying API directly
|
||||
curl https://api.openai.com/v1/models \
|
||||
-H "Authorization: Bearer $OPENAI_API_KEY"
|
||||
```
|
||||
|
||||
## No Token Savings
|
||||
|
||||
**Symptom**: `stats['session']['tokens_saved_total']` is 0.
|
||||
|
||||
**Diagnosis**:
|
||||
|
||||
```python
|
||||
stats = client.get_stats()
|
||||
print(f"Mode: {stats['config']['mode']}") # Should be "optimize"
|
||||
print(f"SmartCrusher: {stats['transforms']['smart_crusher_enabled']}")
|
||||
```
|
||||
|
||||
**Common causes**:
|
||||
|
||||
- Mode is `audit` (observation only, no modifications)
|
||||
- Messages do not contain tool outputs
|
||||
- Tool outputs are below the 200-token threshold
|
||||
- Data is not compressible (high uniqueness, code, grep results)
|
||||
|
||||
**Solutions**:
|
||||
|
||||
<Tabs groupId="lang" items={['TypeScript', 'Python']}>
|
||||
<Tab value="TypeScript">
|
||||
```ts twoslash
|
||||
import { compress } from 'headroom-ai';
|
||||
|
||||
// Ensure the proxy is running in optimize mode
|
||||
// (default, unless --no-optimize was passed)
|
||||
const result = await compress(messages, { model: 'gpt-4o' });
|
||||
console.log(`Saved: ${result.tokensSaved} tokens`);
|
||||
console.log(`Compressed: ${result.compressed}`);
|
||||
```
|
||||
</Tab>
|
||||
<Tab value="Python">
|
||||
```python
|
||||
# 1. Ensure mode is "optimize"
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
default_mode="optimize", # NOT "audit"
|
||||
)
|
||||
|
||||
# 2. Or override per-request
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
headroom_mode="optimize",
|
||||
)
|
||||
|
||||
# 3. Lower the compression threshold
|
||||
config = HeadroomConfig()
|
||||
config.smart_crusher.min_tokens_to_crush = 100 # Default is 200
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Compression Too Aggressive
|
||||
|
||||
**Symptom**: LLM responses are missing information that was in tool outputs.
|
||||
|
||||
```python
|
||||
# 1. Keep more items
|
||||
config = HeadroomConfig()
|
||||
config.smart_crusher.max_items_after_crush = 50 # Default: 15
|
||||
|
||||
# 2. Skip compression for specific tools
|
||||
response = client.chat.completions.create(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
headroom_tool_profiles={
|
||||
"important_tool": {"skip_compression": True},
|
||||
},
|
||||
)
|
||||
|
||||
# 3. Disable SmartCrusher entirely
|
||||
config.smart_crusher.enabled = False
|
||||
```
|
||||
|
||||
## High Latency
|
||||
|
||||
**Symptom**: Requests take longer than expected.
|
||||
|
||||
**Diagnosis**:
|
||||
|
||||
```python
|
||||
import time
|
||||
import logging
|
||||
|
||||
logging.basicConfig(level=logging.DEBUG)
|
||||
|
||||
start = time.time()
|
||||
response = client.chat.completions.create(...)
|
||||
print(f"Total time: {time.time() - start:.2f}s")
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
|
||||
```python
|
||||
# 1. Use BM25 instead of embeddings (faster)
|
||||
config = HeadroomConfig()
|
||||
config.smart_crusher.relevance.tier = "bm25"
|
||||
|
||||
# 2. Increase threshold to skip small payloads
|
||||
config.smart_crusher.min_tokens_to_crush = 500
|
||||
|
||||
# 3. Disable transforms you don't need
|
||||
config.cache_aligner.enabled = False
|
||||
config.rolling_window.enabled = False
|
||||
```
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### pipx installs an older Headroom version
|
||||
|
||||
**Symptom**: PyPI shows a newer `headroom-ai` release, but `pipx install` or
|
||||
`pipx upgrade` keeps an older version. A pinned install can also fail with
|
||||
`No matching distribution found`.
|
||||
|
||||
**Cause**: `pipx` resolves packages inside its app virtual environment. If that
|
||||
environment uses a Python version that Headroom does not publish wheels for yet,
|
||||
pip may skip newer releases and choose the newest compatible build it can use.
|
||||
|
||||
Check the interpreter:
|
||||
|
||||
```bash
|
||||
pipx list
|
||||
```
|
||||
|
||||
Install with a supported Python explicitly:
|
||||
|
||||
```bash
|
||||
pipx install --python python3.13 "headroom-ai[all]"
|
||||
```
|
||||
|
||||
For a pinned release:
|
||||
|
||||
```bash
|
||||
pipx install --python python3.13 "headroom-ai[all]==0.21.4"
|
||||
```
|
||||
|
||||
If you already have Headroom installed under `pipx`, uninstall it first or
|
||||
reinstall it with the supported interpreter.
|
||||
|
||||
### pip install fails with C++ compilation error
|
||||
|
||||
**Symptom**: `RuntimeError: Unsupported compiler -- at least C++11 support is needed!`
|
||||
|
||||
```bash
|
||||
# Linux / Debian-based (including Docker)
|
||||
apt-get install -y build-essential && pip install headroom-ai
|
||||
|
||||
# macOS (Xcode command line tools)
|
||||
xcode-select --install && pip install headroom-ai
|
||||
```
|
||||
|
||||
For Docker, install and remove build tools in one layer:
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.11-slim
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends build-essential \
|
||||
&& pip install "headroom-ai[proxy]" \
|
||||
&& apt-get purge -y build-essential && apt-get autoremove -y \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
### ModuleNotFoundError: No module named 'headroom'
|
||||
|
||||
```bash
|
||||
# Check it is installed in the right environment
|
||||
pip show headroom-ai
|
||||
|
||||
# If using virtual environment, ensure it is activated
|
||||
source venv/bin/activate
|
||||
|
||||
# Reinstall
|
||||
pip install --upgrade headroom-ai
|
||||
```
|
||||
|
||||
### Missing optional dependency
|
||||
|
||||
```bash
|
||||
# For proxy server
|
||||
pip install "headroom-ai[proxy]"
|
||||
|
||||
# For embedding-based relevance scoring
|
||||
pip install "headroom-ai[relevance]"
|
||||
|
||||
# For code compression (tree-sitter)
|
||||
pip install "headroom-ai[code]"
|
||||
|
||||
# For everything
|
||||
pip install "headroom-ai[all]"
|
||||
```
|
||||
|
||||
## Provider-Specific Issues
|
||||
|
||||
### OpenAI: Invalid API key
|
||||
|
||||
```python
|
||||
import os
|
||||
from openai import OpenAI
|
||||
|
||||
api_key = os.environ.get("OPENAI_API_KEY")
|
||||
if not api_key:
|
||||
raise ValueError("OPENAI_API_KEY not set")
|
||||
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(api_key=api_key),
|
||||
provider=OpenAIProvider(),
|
||||
)
|
||||
```
|
||||
|
||||
### Anthropic: Authentication error
|
||||
|
||||
```python
|
||||
import os
|
||||
from anthropic import Anthropic
|
||||
|
||||
api_key = os.environ.get("ANTHROPIC_API_KEY")
|
||||
client = HeadroomClient(
|
||||
original_client=Anthropic(api_key=api_key),
|
||||
provider=AnthropicProvider(),
|
||||
)
|
||||
```
|
||||
|
||||
### Unknown model warnings
|
||||
|
||||
```python
|
||||
# For custom/fine-tuned models, specify context limit
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
model_context_limits={
|
||||
"ft:gpt-4o-2024-08-06:my-org::abc123": 128000,
|
||||
"my-custom-model": 32000,
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
## ValidationError on Setup
|
||||
|
||||
```python
|
||||
result = client.validate_setup()
|
||||
print(result)
|
||||
|
||||
# Common issues:
|
||||
# {"provider": {"ok": False, "error": "No API key"}}
|
||||
# -> Set OPENAI_API_KEY or pass api_key to OpenAI()
|
||||
#
|
||||
# {"storage": {"ok": False, "error": "unable to open database"}}
|
||||
# -> Check path permissions, use :memory: for testing
|
||||
#
|
||||
# {"config": {"ok": False, "error": "Invalid mode"}}
|
||||
# -> Use "audit" or "optimize" only
|
||||
```
|
||||
|
||||
For testing, use in-memory storage:
|
||||
|
||||
```python
|
||||
client = HeadroomClient(
|
||||
original_client=OpenAI(),
|
||||
provider=OpenAIProvider(),
|
||||
store_url="sqlite:///:memory:",
|
||||
)
|
||||
```
|
||||
|
||||
## Debugging Techniques
|
||||
|
||||
### Enable Full Logging
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
# See everything
|
||||
logging.basicConfig(
|
||||
level=logging.DEBUG,
|
||||
format="%(asctime)s %(name)s %(levelname)s %(message)s",
|
||||
)
|
||||
|
||||
# Or just Headroom logs
|
||||
logging.getLogger("headroom").setLevel(logging.DEBUG)
|
||||
```
|
||||
|
||||
### Use Simulation to Inspect Transforms
|
||||
|
||||
```python
|
||||
plan = client.chat.completions.simulate(
|
||||
model="gpt-4o",
|
||||
messages=messages,
|
||||
)
|
||||
|
||||
print(f"Tokens: {plan.tokens_before} -> {plan.tokens_after}")
|
||||
print(f"Transforms: {plan.transforms_applied}")
|
||||
print(f"Waste signals: {plan.waste_signals}")
|
||||
|
||||
import json
|
||||
print(json.dumps(plan.messages_optimized, indent=2))
|
||||
```
|
||||
|
||||
### Test Transforms Directly
|
||||
|
||||
```python
|
||||
from headroom import SmartCrusher, Tokenizer
|
||||
from headroom.config import SmartCrusherConfig
|
||||
import json
|
||||
|
||||
config = SmartCrusherConfig()
|
||||
crusher = SmartCrusher(config)
|
||||
tokenizer = Tokenizer()
|
||||
|
||||
messages = [
|
||||
{
|
||||
"role": "tool",
|
||||
"content": json.dumps({"items": list(range(100))}),
|
||||
"tool_call_id": "1",
|
||||
}
|
||||
]
|
||||
|
||||
result = crusher.apply(messages, tokenizer)
|
||||
print(f"Tokens: {result.tokens_before} -> {result.tokens_after}")
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. Enable debug logging and check the output
|
||||
2. Use `simulate()` to see what transforms would apply
|
||||
3. Run `validate_setup()` for configuration issues
|
||||
4. File an issue at [github.com/headroom-sdk/headroom](https://github.com/headroom-sdk/headroom/issues) with your Headroom version, Python version, provider, debug log output, and minimal reproduction code
|
||||
|
|
@ -1,139 +0,0 @@
|
|||
---
|
||||
title: Vercel AI SDK
|
||||
description: Compress LLM context with the Vercel AI SDK using middleware, withHeadroom(), or standalone compression.
|
||||
---
|
||||
|
||||
Headroom integrates with the [Vercel AI SDK](https://sdk.vercel.ai) through three patterns: a one-liner wrapper, composable middleware, and standalone message compression.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install headroom-ai ai @ai-sdk/openai
|
||||
```
|
||||
|
||||
<Callout type="info" title="Proxy required">
|
||||
The TypeScript SDK sends messages to a local Headroom proxy for compression. Start the proxy before using the SDK:
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[proxy]"
|
||||
headroom proxy
|
||||
```
|
||||
</Callout>
|
||||
|
||||
## withHeadroom() one-liner
|
||||
|
||||
The simplest integration. Wraps any Vercel AI SDK language model with automatic compression:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/vercel-ai';
|
||||
import { openai } from '@ai-sdk/openai';
|
||||
import { generateText } from 'ai';
|
||||
|
||||
const model = withHeadroom(openai('gpt-4o'));
|
||||
|
||||
const { text } = await generateText({
|
||||
model,
|
||||
messages: [
|
||||
{ role: 'user', content: 'Summarize these results...' },
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
`withHeadroom()` calls `wrapLanguageModel` + `headroomMiddleware()` under the hood. It works with any provider (`@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`, etc.).
|
||||
|
||||
## headroomMiddleware() for composition
|
||||
|
||||
Use the middleware directly when you need to compose it with other middleware:
|
||||
|
||||
```ts twoslash
|
||||
// @noErrors
|
||||
import { headroomMiddleware } from 'headroom-ai/vercel-ai';
|
||||
import { wrapLanguageModel } from 'ai';
|
||||
import { openai } from '@ai-sdk/openai';
|
||||
|
||||
const model = wrapLanguageModel({
|
||||
model: openai('gpt-4o'),
|
||||
middleware: headroomMiddleware(),
|
||||
});
|
||||
```
|
||||
|
||||
Pass options to control compression behavior:
|
||||
|
||||
```ts twoslash
|
||||
import { headroomMiddleware } from 'headroom-ai/vercel-ai';
|
||||
|
||||
const middleware = headroomMiddleware({
|
||||
model: 'gpt-4o',
|
||||
baseUrl: 'http://localhost:8787',
|
||||
});
|
||||
```
|
||||
|
||||
## compressVercelMessages() standalone
|
||||
|
||||
Compress Vercel-format messages directly without wrapping a model. Useful for custom pipelines:
|
||||
|
||||
```ts twoslash
|
||||
import { compressVercelMessages } from 'headroom-ai/vercel-ai';
|
||||
|
||||
const result = await compressVercelMessages(messages, {
|
||||
model: 'gpt-4o',
|
||||
});
|
||||
|
||||
console.log(`Saved ${result.tokensSaved} tokens`);
|
||||
// result.messages is in Vercel format, ready for the AI SDK
|
||||
```
|
||||
|
||||
## Streaming with streamText
|
||||
|
||||
Compression happens before the request. Streaming responses are unaffected:
|
||||
|
||||
```ts twoslash
|
||||
import { withHeadroom } from 'headroom-ai/vercel-ai';
|
||||
import { openai } from '@ai-sdk/openai';
|
||||
import { streamText } from 'ai';
|
||||
|
||||
const model = withHeadroom(openai('gpt-4o'));
|
||||
|
||||
const result = streamText({
|
||||
model,
|
||||
messages: longConversation,
|
||||
});
|
||||
|
||||
for await (const chunk of result.textStream) {
|
||||
process.stdout.write(chunk);
|
||||
}
|
||||
```
|
||||
|
||||
## generateObject with compressed context
|
||||
|
||||
Works with structured output:
|
||||
|
||||
```ts twoslash
|
||||
// @noErrors
|
||||
import { withHeadroom } from 'headroom-ai/vercel-ai';
|
||||
import { openai } from '@ai-sdk/openai';
|
||||
import { generateText, Output } from 'ai';
|
||||
import { z } from 'zod';
|
||||
|
||||
const model = withHeadroom(openai('gpt-4o'));
|
||||
|
||||
const { output } = await generateText({
|
||||
model,
|
||||
output: Output.object({
|
||||
schema: z.object({
|
||||
summary: z.string(),
|
||||
severity: z.enum(['low', 'medium', 'high']),
|
||||
}),
|
||||
}),
|
||||
messages: largeConversationHistory,
|
||||
});
|
||||
```
|
||||
|
||||
## How it works
|
||||
|
||||
1. Messages are converted from Vercel format to OpenAI format
|
||||
2. Headroom compresses them via the proxy's `/v1/compress` endpoint
|
||||
3. Compressed messages are converted back to Vercel format
|
||||
4. The original model receives the smaller prompt
|
||||
|
||||
All other model behavior (tool calling, structured output, streaming) is unchanged.
|
||||
2591
docker-install/index.html
Normal file
2591
docker-install/index.html
Normal file
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
|
||||
|
||||
<link rel="canonical" href="https://chopratejas.github.io/headroom/rtk-architecture/">
|
||||
<link rel="canonical" href="https://chopratejas.github.io/headroom/filesystem-contract/">
|
||||
|
||||
|
||||
|
||||
|
|
@ -23,7 +23,7 @@
|
|||
|
||||
|
||||
|
||||
<title>RTK architecture — why wrap-CLI only - Headroom</title>
|
||||
<title>Filesystem Contract - Headroom</title>
|
||||
|
||||
|
||||
|
||||
|
|
@ -76,7 +76,7 @@
|
|||
<div data-md-component="skip">
|
||||
|
||||
|
||||
<a href="#rtk-architecture-why-wrap-cli-only" class="md-skip">
|
||||
<a href="#filesystem-contract" class="md-skip">
|
||||
Skip to content
|
||||
</a>
|
||||
|
||||
|
|
@ -112,7 +112,7 @@
|
|||
<div class="md-header__topic" data-md-component="header-topic">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
RTK architecture — why wrap-CLI only
|
||||
Filesystem Contract
|
||||
|
||||
</span>
|
||||
</div>
|
||||
|
|
@ -224,7 +224,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../index.md" class="md-tabs__link">
|
||||
<a href=".." class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -245,7 +245,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../quickstart.md" class="md-tabs__link">
|
||||
<a href="../quickstart/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -267,7 +267,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../proxy.md" class="md-tabs__link">
|
||||
<a href="../proxy/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -289,7 +289,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../integration-guide.md" class="md-tabs__link">
|
||||
<a href="../integration-guide/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -311,7 +311,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../ARCHITECTURE.md" class="md-tabs__link">
|
||||
<a href="../ARCHITECTURE/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -333,7 +333,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../benchmarks.md" class="md-tabs__link">
|
||||
<a href="../benchmarks/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -355,7 +355,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../cli.md" class="md-tabs__link">
|
||||
<a href="../cli/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -377,7 +377,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../macos-deployment.md" class="md-tabs__link">
|
||||
<a href="../macos-deployment/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -449,7 +449,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../index.md" class="md-nav__link">
|
||||
<a href=".." class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -542,7 +542,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../quickstart.md" class="md-nav__link">
|
||||
<a href="../quickstart/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -570,7 +570,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../getting-started.md" class="md-nav__link">
|
||||
<a href="../getting-started/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -598,7 +598,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../docker-install.md" class="md-nav__link">
|
||||
<a href="../docker-install/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -626,7 +626,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../persistent-installs.md" class="md-nav__link">
|
||||
<a href="../persistent-installs/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -654,7 +654,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../configuration.md" class="md-nav__link">
|
||||
<a href="../configuration/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -759,7 +759,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../proxy.md" class="md-nav__link">
|
||||
<a href="../proxy/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -787,7 +787,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../compression.md" class="md-nav__link">
|
||||
<a href="../compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -815,7 +815,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../ccr.md" class="md-nav__link">
|
||||
<a href="../ccr/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -843,7 +843,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../image-compression.md" class="md-nav__link">
|
||||
<a href="../image-compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -871,7 +871,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../memory.md" class="md-nav__link">
|
||||
<a href="../memory/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -899,7 +899,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../shared-context.md" class="md-nav__link">
|
||||
<a href="../shared-context/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -927,7 +927,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../learn.md" class="md-nav__link">
|
||||
<a href="../learn/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1028,7 +1028,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../integration-guide.md" class="md-nav__link">
|
||||
<a href="../integration-guide/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1056,7 +1056,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../langchain.md" class="md-nav__link">
|
||||
<a href="../langchain/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1084,7 +1084,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../agno.md" class="md-nav__link">
|
||||
<a href="../agno/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1112,7 +1112,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../strands.md" class="md-nav__link">
|
||||
<a href="../strands/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1140,7 +1140,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../mcp.md" class="md-nav__link">
|
||||
<a href="../mcp/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1239,7 +1239,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../ARCHITECTURE.md" class="md-nav__link">
|
||||
<a href="../ARCHITECTURE/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1267,7 +1267,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../transforms.md" class="md-nav__link">
|
||||
<a href="../transforms/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1295,7 +1295,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../text-compression.md" class="md-nav__link">
|
||||
<a href="../text-compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1420,7 +1420,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../benchmarks.md" class="md-nav__link">
|
||||
<a href="../benchmarks/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1448,7 +1448,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../LATENCY_BENCHMARKS.md" class="md-nav__link">
|
||||
<a href="../LATENCY_BENCHMARKS/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1476,7 +1476,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../LIMITATIONS.md" class="md-nav__link">
|
||||
<a href="../LIMITATIONS/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1579,7 +1579,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../cli.md" class="md-nav__link">
|
||||
<a href="../cli/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1607,7 +1607,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../api.md" class="md-nav__link">
|
||||
<a href="../api/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1635,7 +1635,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../sdk.md" class="md-nav__link">
|
||||
<a href="../sdk/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1663,7 +1663,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../metrics.md" class="md-nav__link">
|
||||
<a href="../metrics/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1691,7 +1691,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../errors.md" class="md-nav__link">
|
||||
<a href="../errors/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1719,7 +1719,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../troubleshooting.md" class="md-nav__link">
|
||||
<a href="../troubleshooting/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1812,7 +1812,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../macos-deployment.md" class="md-nav__link">
|
||||
<a href="../macos-deployment/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1867,10 +1867,10 @@
|
|||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#tldr" class="md-nav__link">
|
||||
<a href="#two-root-model" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
TL;DR
|
||||
Two-root model
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1878,10 +1878,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#background" class="md-nav__link">
|
||||
<a href="#precedence" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Background
|
||||
Precedence
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1889,22 +1889,22 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#proxy-side-rtk-was-considered-and-rejected" class="md-nav__link">
|
||||
<a href="#bucket-assignments" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Proxy-side RTK was considered and rejected
|
||||
Bucket assignments
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Proxy-side RTK was considered and rejected">
|
||||
<nav class="md-nav" aria-label="Bucket assignments">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#1-cache-hot-zone-risk" class="md-nav__link">
|
||||
<a href="#workspace-bucket-headroom_workspace_dir" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
1. Cache hot zone risk
|
||||
Workspace bucket (HEADROOM_WORKSPACE_DIR)
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1912,10 +1912,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#2-parallel-implementation-with-log_compressorrs" class="md-nav__link">
|
||||
<a href="#config-bucket-headroom_config_dir" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
2. Parallel implementation with log_compressor.rs
|
||||
Config bucket (HEADROOM_CONFIG_DIR)
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1923,10 +1923,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#3-command-rewrite-vs-output-rewrite-different-value-propositions" class="md-nav__link">
|
||||
<a href="#backward-compatibility-modelsjson" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
3. Command-rewrite vs output-rewrite — different value propositions
|
||||
Backward compatibility — models.json
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1939,10 +1939,49 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#what-the-proxy-does-provide" class="md-nav__link">
|
||||
<a href="#plugin-authors" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
What the proxy does provide
|
||||
Plugin authors
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Plugin authors">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#python" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Python
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#npm-sdk" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
npm SDK
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#docker-naming-overlap-headroom_workspace-vs-headroom_workspace_dir" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Docker naming overlap: HEADROOM_WORKSPACE vs HEADROOM_WORKSPACE_DIR
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1950,10 +1989,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#what-the-wrap-cli-does" class="md-nav__link">
|
||||
<a href="#project-scoped-headroom-directories" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
What the wrap CLI does
|
||||
Project-scoped .headroom/ directories
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1961,10 +2000,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#re-litigation-policy" class="md-nav__link">
|
||||
<a href="#legacy-per-resource-env-vars" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Re-litigation policy
|
||||
Legacy per-resource env vars
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1972,10 +2011,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#references" class="md-nav__link">
|
||||
<a href="#see-also" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
References
|
||||
See also
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -2002,105 +2041,260 @@
|
|||
|
||||
|
||||
|
||||
<h1 id="rtk-architecture-why-wrap-cli-only">RTK architecture — why wrap-CLI only<a class="headerlink" href="#rtk-architecture-why-wrap-cli-only" title="Permanent link">¶</a></h1>
|
||||
<p><strong>Status:</strong> decided. Locked at Phase G PR-G3 (2026-05).
|
||||
<strong>Owner:</strong> Headroom realignment.</p>
|
||||
<h2 id="tldr">TL;DR<a class="headerlink" href="#tldr" title="Permanent link">¶</a></h2>
|
||||
<p><strong>RTK is a wrap-CLI hook, not a proxy-side compressor.</strong> The Headroom
|
||||
proxy does NOT invoke RTK on tool-result content. Future contributors
|
||||
who consider moving RTK into the proxy hot path: read this doc first.</p>
|
||||
<h2 id="background">Background<a class="headerlink" href="#background" title="Permanent link">¶</a></h2>
|
||||
<p>RTK (Realtime Token Kompress) rewrites shell <strong>commands</strong> at exec
|
||||
time so that a <code>git diff</code> or <code>grep</code> invocation emits a more
|
||||
compressed output before the agent ever ingests it. RTK runs in the
|
||||
wrap-CLI tail — <code>headroom wrap claude</code>, <code>headroom wrap codex</code>, etc.
|
||||
— where it installs a <code>~/.rtk/bin/rtk</code> shim ahead of the agent CLI
|
||||
and intercepts shelled-out subprocesses.</p>
|
||||
<p>It surfaces value in two places:
|
||||
1. <strong>Tokens saved per invocation</strong> — measured by <code>rtk gain --format json</code>.
|
||||
2. <strong>Tokens saved per session</strong> — aggregated at wrap-session end.</p>
|
||||
<p>Both signals feed <code>wrap_rtk_invocations_total</code> and
|
||||
<code>wrap_rtk_tokens_saved_per_session</code> (registered by the Rust proxy's
|
||||
observability surface so a single <code>/metrics</code> scrape exposes the full
|
||||
picture).</p>
|
||||
<h2 id="proxy-side-rtk-was-considered-and-rejected">Proxy-side RTK was considered and rejected<a class="headerlink" href="#proxy-side-rtk-was-considered-and-rejected" title="Permanent link">¶</a></h2>
|
||||
<p>At Phase G scoping, three reviewers floated the idea of invoking
|
||||
RTK on the <strong>proxy</strong> side: when a <code>tool_result</code> block flows
|
||||
upstream, dispatch it through RTK to shrink the content before it
|
||||
hits the model.</p>
|
||||
<p><strong>Decision: rejected.</strong> Three load-bearing reasons.</p>
|
||||
<h3 id="1-cache-hot-zone-risk">1. Cache hot zone risk<a class="headerlink" href="#1-cache-hot-zone-risk" title="Permanent link">¶</a></h3>
|
||||
<p>The proxy's Phase B cache-safety contract pins <code>tool_result</code>
|
||||
content as part of the cache hot zone. Compression there bursts
|
||||
the prompt cache because the rewritten bytes diverge from the
|
||||
canonical wire bytes the upstream cached. Phase B PR-B2 → PR-B7
|
||||
spent ~3000 LOC carving the live-zone-only surface specifically
|
||||
to prevent this class of cache-invalidation. Inserting RTK
|
||||
proxy-side would re-introduce it.</p>
|
||||
<h3 id="2-parallel-implementation-with-log_compressorrs">2. Parallel implementation with <code>log_compressor.rs</code><a class="headerlink" href="#2-parallel-implementation-with-log_compressorrs" title="Permanent link">¶</a></h3>
|
||||
<p>The Rust proxy already has a <code>crates/headroom-core/src/transforms/log_compressor.rs</code>
|
||||
that compresses <strong>tool output text</strong> in the live zone. It uses the
|
||||
same heuristics RTK uses (whitespace de-dup, line de-dup,
|
||||
file-listing collapse) but invoked at the proxy's per-block
|
||||
dispatcher rather than at the shell exec boundary. Adding RTK
|
||||
proxy-side would mean two implementations of the same compression
|
||||
in the same hot path; "no silent fallbacks, no parallel impls" is
|
||||
explicit project policy.</p>
|
||||
<h3 id="3-command-rewrite-vs-output-rewrite-different-value-propositions">3. Command-rewrite vs output-rewrite — different value propositions<a class="headerlink" href="#3-command-rewrite-vs-output-rewrite-different-value-propositions" title="Permanent link">¶</a></h3>
|
||||
<p>RTK rewrites <strong>commands</strong> before they execute. The
|
||||
<code>git log --oneline</code> you typed becomes <code>git log --oneline -n 50</code>
|
||||
because RTK has learned that the first 50 commits are usually
|
||||
enough context. That's a fundamentally different mechanism from
|
||||
compressing the <strong>output</strong> of an unmodified command. A proxy-side
|
||||
invocation would skip the command-rewrite half — the half that
|
||||
generates the largest savings on heavy shell workloads — and only
|
||||
catch the output side, which is already covered by
|
||||
<code>log_compressor</code> and <code>code_compressor</code>.</p>
|
||||
<h2 id="what-the-proxy-does-provide">What the proxy does provide<a class="headerlink" href="#what-the-proxy-does-provide" title="Permanent link">¶</a></h2>
|
||||
<p>Per Phase G PR-G3, the proxy exposes RTK-derived metrics via its
|
||||
registry:</p>
|
||||
<h1 id="filesystem-contract">Filesystem Contract<a class="headerlink" href="#filesystem-contract" title="Permanent link">¶</a></h1>
|
||||
<p>Headroom writes configuration, runtime state, logs, and caches to a small
|
||||
set of well-known paths under the user's home directory. This page is the
|
||||
source of truth for where those paths live, how to override them, and how
|
||||
they behave inside Docker containers.</p>
|
||||
<h2 id="two-root-model">Two-root model<a class="headerlink" href="#two-root-model" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Variable</th>
|
||||
<th>Default</th>
|
||||
<th>Purpose</th>
|
||||
<th>Typical access</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>HEADROOM_CONFIG_DIR</code></td>
|
||||
<td><code>~/.headroom/config</code></td>
|
||||
<td>User/admin-authored configuration (model catalogs, plugin settings, etc.)</td>
|
||||
<td>Read-mostly</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>HEADROOM_WORKSPACE_DIR</code></td>
|
||||
<td><code>~/.headroom</code></td>
|
||||
<td>Runtime state written by the proxy and CLI (savings, logs, memory DB, telemetry, caches)</td>
|
||||
<td>Read-write</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>Both variables are recognized by the Python proxy / CLI and the npm SDK.
|
||||
They are <strong>additive</strong> — every pre-existing per-resource env var
|
||||
(<code>HEADROOM_SAVINGS_PATH</code>, <code>HEADROOM_TOIN_PATH</code>,
|
||||
<code>HEADROOM_SUBSCRIPTION_STATE_PATH</code>, <code>HEADROOM_MODEL_LIMITS</code>, ...)
|
||||
continues to work with identical semantics.</p>
|
||||
<h2 id="precedence">Precedence<a class="headerlink" href="#precedence" title="Permanent link">¶</a></h2>
|
||||
<p>For every per-resource helper, resolution follows this order:</p>
|
||||
<div class="language-text highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>explicit argument
|
||||
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> │ falls through when None/""
|
||||
</span><span id="__span-0-3"><a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> ▼
|
||||
</span><span id="__span-0-4"><a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>per-resource env var (e.g. HEADROOM_SAVINGS_PATH)
|
||||
</span><span id="__span-0-5"><a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> │ falls through when unset/blank
|
||||
</span><span id="__span-0-6"><a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> ▼
|
||||
</span><span id="__span-0-7"><a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>derived from canonical root
|
||||
</span><span id="__span-0-8"><a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a> │ e.g. ${HEADROOM_WORKSPACE_DIR}/proxy_savings.json
|
||||
</span><span id="__span-0-9"><a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a> ▼
|
||||
</span><span id="__span-0-10"><a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>default (e.g. ~/.headroom/proxy_savings.json)
|
||||
</span></code></pre></div>
|
||||
<p>Examples:</p>
|
||||
<ul>
|
||||
<li><code>wrap_rtk_invocations_total{tool}</code> — driven by the wrap-CLI
|
||||
polling <code>rtk gain --format json</code> and incrementing the registered
|
||||
counter by the delta since last poll.</li>
|
||||
<li><code>wrap_rtk_tokens_saved_per_session</code> — emitted at wrap-session
|
||||
close.</li>
|
||||
<li><code>HEADROOM_WORKSPACE_DIR=/mnt/state</code> → savings land at
|
||||
<code>/mnt/state/proxy_savings.json</code> unless <code>HEADROOM_SAVINGS_PATH</code> overrides.</li>
|
||||
<li><code>HEADROOM_SAVINGS_PATH=/custom/savings.json</code> always wins, even when
|
||||
<code>HEADROOM_WORKSPACE_DIR</code> is set.</li>
|
||||
<li>Unset both and the default is <code>~/.headroom/proxy_savings.json</code>.</li>
|
||||
</ul>
|
||||
<p>This keeps the operator dashboard single-pane-of-glass without
|
||||
re-implementing RTK inside the proxy.</p>
|
||||
<h2 id="what-the-wrap-cli-does">What the wrap CLI does<a class="headerlink" href="#what-the-wrap-cli-does" title="Permanent link">¶</a></h2>
|
||||
<p>Every <code>headroom wrap <agent></code> subcommand:</p>
|
||||
<h2 id="bucket-assignments">Bucket assignments<a class="headerlink" href="#bucket-assignments" title="Permanent link">¶</a></h2>
|
||||
<h3 id="workspace-bucket-headroom_workspace_dir">Workspace bucket (<code>HEADROOM_WORKSPACE_DIR</code>)<a class="headerlink" href="#workspace-bucket-headroom_workspace_dir" title="Permanent link">¶</a></h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Resource</th>
|
||||
<th>Default path</th>
|
||||
<th>Legacy env var</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Proxy savings ledger</td>
|
||||
<td><code>${WORKSPACE_DIR}/proxy_savings.json</code></td>
|
||||
<td><code>HEADROOM_SAVINGS_PATH</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>TOIN telemetry JSON</td>
|
||||
<td><code>${WORKSPACE_DIR}/toin.json</code></td>
|
||||
<td><code>HEADROOM_TOIN_PATH</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Subscription tracker state</td>
|
||||
<td><code>${WORKSPACE_DIR}/subscription_state.json</code></td>
|
||||
<td><code>HEADROOM_SUBSCRIPTION_STATE_PATH</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Memory SQLite</td>
|
||||
<td><code>${WORKSPACE_DIR}/memory.db</code></td>
|
||||
<td>CLI <code>--memory-db-path</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Native memory directory</td>
|
||||
<td><code>${WORKSPACE_DIR}/memories/</code></td>
|
||||
<td><code>MemoryConfig.native_memory_dir</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>License cache</td>
|
||||
<td><code>${WORKSPACE_DIR}/license_cache.json</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Session stats JSONL</td>
|
||||
<td><code>${WORKSPACE_DIR}/session_stats.jsonl</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Memory sync state</td>
|
||||
<td><code>${WORKSPACE_DIR}/sync_state.json</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Memory bridge state</td>
|
||||
<td><code>${WORKSPACE_DIR}/bridge_state.json</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Proxy log directory</td>
|
||||
<td><code>${WORKSPACE_DIR}/logs/</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>HTTP 400 debug dumps</td>
|
||||
<td><code>${WORKSPACE_DIR}/logs/debug_400/</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Vendored <code>rtk</code> binary</td>
|
||||
<td><code>${WORKSPACE_DIR}/bin/rtk[.exe]</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Deployment profiles</td>
|
||||
<td><code>${WORKSPACE_DIR}/deploy/</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Beacon lock file</td>
|
||||
<td><code>${WORKSPACE_DIR}/.beacon_lock_<port></code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3 id="config-bucket-headroom_config_dir">Config bucket (<code>HEADROOM_CONFIG_DIR</code>)<a class="headerlink" href="#config-bucket-headroom_config_dir" title="Permanent link">¶</a></h3>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Resource</th>
|
||||
<th>Default path</th>
|
||||
<th>Legacy env var</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Models catalog</td>
|
||||
<td><code>${CONFIG_DIR}/models.json</code></td>
|
||||
<td><code>HEADROOM_MODEL_LIMITS</code> (content override)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Plugin settings</td>
|
||||
<td><code>${CONFIG_DIR}/plugins/<name>/...</code></td>
|
||||
<td>—</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<h3 id="backward-compatibility-modelsjson">Backward compatibility — models.json<a class="headerlink" href="#backward-compatibility-modelsjson" title="Permanent link">¶</a></h3>
|
||||
<p><code>models.json</code> historically lived at <code>~/.headroom/models.json</code> (i.e. in the
|
||||
workspace root, not in <code>config/</code>). For a seamless migration the Python
|
||||
providers check <strong>both</strong> locations in this order:</p>
|
||||
<ol>
|
||||
<li>Ensures the RTK binary is installed via <code>_ensure_rtk_binary()</code>.</li>
|
||||
<li>Injects the <code><!-- headroom:rtk-instructions --></code> block into the
|
||||
agent's instruction file (e.g. <code>AGENTS.md</code>, <code>.cursorrules</code>).</li>
|
||||
<li>Spawns the proxy and the agent CLI side-by-side.</li>
|
||||
<li>Polls <code>rtk gain --format json</code> on a 5-second memoization window
|
||||
and feeds the delta into the proxy's metric registry.</li>
|
||||
<li><code>${HEADROOM_CONFIG_DIR}/models.json</code> (new canonical location)</li>
|
||||
<li><code>${HEADROOM_WORKSPACE_DIR}/models.json</code> (legacy fallback)</li>
|
||||
</ol>
|
||||
<p>See <code>headroom/cli/wrap/</code> for the per-agent shims.</p>
|
||||
<h2 id="re-litigation-policy">Re-litigation policy<a class="headerlink" href="#re-litigation-policy" title="Permanent link">¶</a></h2>
|
||||
<p>A change to this architecture should:</p>
|
||||
<ol>
|
||||
<li>Quote the live-zone-only contract from
|
||||
<code>REALIGNMENT/04-phase-B-live-zone.md</code> and explain why the
|
||||
cache-burst risk is acceptable.</li>
|
||||
<li>Show measurements (not estimates) that proxy-side RTK adds value
|
||||
beyond <code>log_compressor.rs</code> on real production traffic.</li>
|
||||
<li>Have an exit ramp: a CLI flag to disable proxy-side RTK without
|
||||
reverting the wrap-CLI integration.</li>
|
||||
</ol>
|
||||
<p>Without all three, treat the proposal as a regression and link this
|
||||
doc.</p>
|
||||
<h2 id="references">References<a class="headerlink" href="#references" title="Permanent link">¶</a></h2>
|
||||
<p>Existing installs continue to work unchanged. New installs are encouraged
|
||||
to put <code>models.json</code> in the config bucket.</p>
|
||||
<h2 id="plugin-authors">Plugin authors<a class="headerlink" href="#plugin-authors" title="Permanent link">¶</a></h2>
|
||||
<p>Two helpers give plugins isolated, per-plugin directories under both
|
||||
roots:</p>
|
||||
<h3 id="python">Python<a class="headerlink" href="#python" title="Permanent link">¶</a></h3>
|
||||
<div class="language-python highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">headroom</span><span class="w"> </span><span class="kn">import</span> <span class="n">paths</span>
|
||||
</span><span id="__span-1-2"><a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>
|
||||
</span><span id="__span-1-3"><a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="n">cfg_dir</span> <span class="o">=</span> <span class="n">paths</span><span class="o">.</span><span class="n">plugin_config_dir</span><span class="p">(</span><span class="s2">"my-plugin"</span><span class="p">)</span>
|
||||
</span><span id="__span-1-4"><a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="c1"># → ~/.headroom/config/plugins/my-plugin</span>
|
||||
</span><span id="__span-1-5"><a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>
|
||||
</span><span id="__span-1-6"><a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="n">state_dir</span> <span class="o">=</span> <span class="n">paths</span><span class="o">.</span><span class="n">plugin_workspace_dir</span><span class="p">(</span><span class="s2">"my-plugin"</span><span class="p">)</span>
|
||||
</span><span id="__span-1-7"><a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="c1"># → ~/.headroom/plugins/my-plugin</span>
|
||||
</span><span id="__span-1-8"><a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>
|
||||
</span><span id="__span-1-9"><a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="n">cfg_dir</span><span class="o">.</span><span class="n">mkdir</span><span class="p">(</span><span class="n">parents</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">exist_ok</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||||
</span><span id="__span-1-10"><a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="p">(</span><span class="n">cfg_dir</span> <span class="o">/</span> <span class="s2">"settings.json"</span><span class="p">)</span><span class="o">.</span><span class="n">write_text</span><span class="p">(</span><span class="s2">"</span><span class="si">{}</span><span class="s2">"</span><span class="p">)</span>
|
||||
</span></code></pre></div>
|
||||
<h3 id="npm-sdk">npm SDK<a class="headerlink" href="#npm-sdk" title="Permanent link">¶</a></h3>
|
||||
<div class="language-typescript highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">pluginConfigDir</span><span class="p">,</span><span class="w"> </span><span class="nx">pluginWorkspaceDir</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s2">"@headroom/sdk"</span><span class="p">;</span>
|
||||
</span><span id="__span-2-2"><a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>
|
||||
</span><span id="__span-2-3"><a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="kd">const</span><span class="w"> </span><span class="nx">cfgDir</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">pluginConfigDir</span><span class="p">(</span><span class="s2">"my-plugin"</span><span class="p">);</span>
|
||||
</span><span id="__span-2-4"><a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="kd">const</span><span class="w"> </span><span class="nx">stateDir</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">pluginWorkspaceDir</span><span class="p">(</span><span class="s2">"my-plugin"</span><span class="p">);</span>
|
||||
</span></code></pre></div>
|
||||
<p>Plugin-author helpers reject names containing <code>/</code> or <code>\</code> to keep the
|
||||
namespace flat.</p>
|
||||
<h2 id="docker-naming-overlap-headroom_workspace-vs-headroom_workspace_dir">Docker naming overlap: <code>HEADROOM_WORKSPACE</code> vs <code>HEADROOM_WORKSPACE_DIR</code><a class="headerlink" href="#docker-naming-overlap-headroom_workspace-vs-headroom_workspace_dir" title="Permanent link">¶</a></h2>
|
||||
<p>These are <strong>two different variables</strong> with different semantics, both
|
||||
retained for backward compatibility:</p>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Variable</th>
|
||||
<th>Scope</th>
|
||||
<th>Meaning</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>HEADROOM_WORKSPACE</code></td>
|
||||
<td>Host-side (Docker)</td>
|
||||
<td>Directory to bind-mount into the container as <code>/workspace</code> (equivalent to CWD in native runs). Used by <code>docker-compose.native.yml</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>HEADROOM_WORKSPACE_DIR</code></td>
|
||||
<td>Inside-the-container</td>
|
||||
<td>Canonical Headroom state root. Resolves to <code>/tmp/headroom-home/.headroom</code> inside the official container image, which in turn bind-mounts to <code>${HOME}/.headroom</code> on the host.</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<p>The official Docker bootstrap (compose file, <code>scripts/install.sh</code>, and the
|
||||
Python <code>install</code> command) sets <code>HEADROOM_WORKSPACE_DIR</code> and
|
||||
<code>HEADROOM_CONFIG_DIR</code> inside the container so the proxy resolves state to
|
||||
the bind-mounted path without any user action.</p>
|
||||
<h2 id="project-scoped-headroom-directories">Project-scoped <code>.headroom/</code> directories<a class="headerlink" href="#project-scoped-headroom-directories" title="Permanent link">¶</a></h2>
|
||||
<p>A few code paths deliberately use <strong>project-local</strong> <code>.headroom/</code> paths
|
||||
resolved relative to the current working directory rather than the
|
||||
canonical workspace root:</p>
|
||||
<ul>
|
||||
<li><code>REALIGNMENT/09-phase-G-rtk-observability.md</code> — Phase G plan.</li>
|
||||
<li><code>REALIGNMENT/04-phase-B-live-zone.md</code> — cache hot-zone contract.</li>
|
||||
<li><code>headroom/cli/wrap/</code> — wrap-CLI implementation.</li>
|
||||
<li><code>crates/headroom-core/src/transforms/log_compressor.rs</code> — the
|
||||
proxy-side log compressor RTK would parallel.</li>
|
||||
<li>2026-05-01 user direction message archived in
|
||||
<code>project_compression_realignment_2026_05</code> memory note.</li>
|
||||
<li><code>headroom/proxy/server.py</code> — project-scoped memory DB default</li>
|
||||
<li><code>headroom/memory/mcp_server.py</code> — project-scoped memory DB default</li>
|
||||
<li><code>headroom/cli/wrap.py</code> — project-scoped memory and hook artifacts</li>
|
||||
</ul>
|
||||
<p>These <strong>do not obey</strong> <code>HEADROOM_WORKSPACE_DIR</code>. This is intentional: it
|
||||
preserves the "project memory lives in the project directory" invariant
|
||||
documented in <a href="../memory/">memory.md</a>. Users who want a single centrally
|
||||
located memory store can pass <code>--memory-db-path <path></code> explicitly or set
|
||||
the path via the plugin API.</p>
|
||||
<h2 id="legacy-per-resource-env-vars">Legacy per-resource env vars<a class="headerlink" href="#legacy-per-resource-env-vars" title="Permanent link">¶</a></h2>
|
||||
<p>Every legacy env var continues to work with its original semantics (raw
|
||||
string in, raw string out — no tilde expansion, no path-separator
|
||||
normalization), ensuring byte-for-byte backward compatibility.</p>
|
||||
<p>Full list:</p>
|
||||
<ul>
|
||||
<li><code>HEADROOM_SAVINGS_PATH</code></li>
|
||||
<li><code>HEADROOM_TOIN_PATH</code></li>
|
||||
<li><code>HEADROOM_SUBSCRIPTION_STATE_PATH</code></li>
|
||||
<li><code>HEADROOM_MODEL_LIMITS</code> (content override — JSON string or file path)</li>
|
||||
</ul>
|
||||
<h2 id="see-also">See also<a class="headerlink" href="#see-also" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li><a href="../configuration/">configuration.md</a> — general configuration reference</li>
|
||||
<li><a href="../docker-install/">docker-install.md</a> — Docker install details</li>
|
||||
<li><a href="../persistent-installs/">persistent-installs.md</a> — persistent
|
||||
deployment profiles</li>
|
||||
<li><a href="../memory/">memory.md</a> — memory-system paths and project scoping</li>
|
||||
</ul>
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load diff
3180
image-compression/index.html
Normal file
3180
image-compression/index.html
Normal file
File diff suppressed because it is too large
Load diff
1132
index.html
1132
index.html
File diff suppressed because it is too large
Load diff
2774
integration-guide/index.html
Normal file
2774
integration-guide/index.html
Normal file
File diff suppressed because it is too large
Load diff
3329
langchain/index.html
Normal file
3329
langchain/index.html
Normal file
File diff suppressed because it is too large
Load diff
File diff suppressed because it is too large
Load diff
3850
macos-deployment/index.html
Normal file
3850
macos-deployment/index.html
Normal file
File diff suppressed because it is too large
Load diff
2724
mcp/index.html
Normal file
2724
mcp/index.html
Normal file
File diff suppressed because it is too large
Load diff
3970
memory/index.html
Normal file
3970
memory/index.html
Normal file
File diff suppressed because it is too large
Load diff
3086
metrics/index.html
Normal file
3086
metrics/index.html
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -1,11 +0,0 @@
|
|||
import { createMDX } from 'fumadocs-mdx/next';
|
||||
|
||||
const withMDX = createMDX();
|
||||
|
||||
/** @type {import('next').NextConfig} */
|
||||
const config = {
|
||||
reactStrictMode: true,
|
||||
serverExternalPackages: ['typescript', 'twoslash'],
|
||||
};
|
||||
|
||||
export default withMDX(config);
|
||||
5167
package-lock.json
generated
5167
package-lock.json
generated
File diff suppressed because it is too large
Load diff
41
package.json
41
package.json
|
|
@ -1,41 +0,0 @@
|
|||
{
|
||||
"name": "headroom-docs",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"build": "next build",
|
||||
"dev": "next dev",
|
||||
"start": "next start",
|
||||
"types:check": "fumadocs-mdx && next typegen && tsc --noEmit",
|
||||
"postinstall": "fumadocs-mdx"
|
||||
},
|
||||
"dependencies": {
|
||||
"dotted-map": "^3.1.0",
|
||||
"fumadocs-core": "16.7.10",
|
||||
"fumadocs-mdx": "14.2.11",
|
||||
"fumadocs-twoslash": "^3.1.3",
|
||||
"fumadocs-typescript": "^4.0.3",
|
||||
"fumadocs-ui": "16.7.10",
|
||||
"headroom-ai": "file:../sdk/typescript",
|
||||
"lucide-react": "^1.7.0",
|
||||
"next": "16.2.6",
|
||||
"react": "^19.2.4",
|
||||
"react-dom": "^19.2.4",
|
||||
"recharts": "^3.8.1",
|
||||
"tailwind-merge": "^3.5.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@ai-sdk/openai": "^3.0.51",
|
||||
"@anthropic-ai/sdk": "^0.82.0",
|
||||
"@tailwindcss/postcss": "^4.2.2",
|
||||
"@types/mdx": "^2.0.13",
|
||||
"@types/node": "^25.5.0",
|
||||
"@types/react": "^19.2.14",
|
||||
"@types/react-dom": "^19.2.3",
|
||||
"ai": "^6.0.149",
|
||||
"openai": "^6.33.0",
|
||||
"postcss": "^8.5.10",
|
||||
"tailwindcss": "^4.2.2",
|
||||
"typescript": "^5.9.3"
|
||||
}
|
||||
}
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
|
||||
|
||||
<link rel="canonical" href="https://chopratejas.github.io/headroom/spec/001-vision/">
|
||||
<link rel="canonical" href="https://chopratejas.github.io/headroom/plans/2026-04-11-persistent-installs-design/">
|
||||
|
||||
|
||||
|
||||
|
|
@ -23,7 +23,7 @@
|
|||
|
||||
|
||||
|
||||
<title>001. Vision - Headroom</title>
|
||||
<title>Persistent Deployments / Installs Design - Headroom</title>
|
||||
|
||||
|
||||
|
||||
|
|
@ -76,7 +76,7 @@
|
|||
<div data-md-component="skip">
|
||||
|
||||
|
||||
<a href="#001-vision" class="md-skip">
|
||||
<a href="#persistent-deployments-installs-design" class="md-skip">
|
||||
Skip to content
|
||||
</a>
|
||||
|
||||
|
|
@ -112,7 +112,7 @@
|
|||
<div class="md-header__topic" data-md-component="header-topic">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
001. Vision
|
||||
Persistent Deployments / Installs Design
|
||||
|
||||
</span>
|
||||
</div>
|
||||
|
|
@ -224,7 +224,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../index.md" class="md-tabs__link">
|
||||
<a href="../.." class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -245,7 +245,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../quickstart.md" class="md-tabs__link">
|
||||
<a href="../../quickstart/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -267,7 +267,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../proxy.md" class="md-tabs__link">
|
||||
<a href="../../proxy/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -289,7 +289,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../integration-guide.md" class="md-tabs__link">
|
||||
<a href="../../integration-guide/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -311,7 +311,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../ARCHITECTURE.md" class="md-tabs__link">
|
||||
<a href="../../ARCHITECTURE/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -333,7 +333,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../benchmarks.md" class="md-tabs__link">
|
||||
<a href="../../benchmarks/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -355,7 +355,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../cli.md" class="md-tabs__link">
|
||||
<a href="../../cli/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -377,7 +377,7 @@
|
|||
|
||||
|
||||
<li class="md-tabs__item">
|
||||
<a href="../../macos-deployment.md" class="md-tabs__link">
|
||||
<a href="../../macos-deployment/" class="md-tabs__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -449,7 +449,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../index.md" class="md-nav__link">
|
||||
<a href="../.." class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -542,7 +542,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../quickstart.md" class="md-nav__link">
|
||||
<a href="../../quickstart/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -570,7 +570,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../getting-started.md" class="md-nav__link">
|
||||
<a href="../../getting-started/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -598,7 +598,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../docker-install.md" class="md-nav__link">
|
||||
<a href="../../docker-install/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -626,7 +626,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../persistent-installs.md" class="md-nav__link">
|
||||
<a href="../../persistent-installs/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -654,7 +654,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../configuration.md" class="md-nav__link">
|
||||
<a href="../../configuration/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -759,7 +759,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../proxy.md" class="md-nav__link">
|
||||
<a href="../../proxy/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -787,7 +787,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../compression.md" class="md-nav__link">
|
||||
<a href="../../compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -815,7 +815,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../ccr.md" class="md-nav__link">
|
||||
<a href="../../ccr/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -843,7 +843,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../image-compression.md" class="md-nav__link">
|
||||
<a href="../../image-compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -871,7 +871,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../memory.md" class="md-nav__link">
|
||||
<a href="../../memory/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -899,7 +899,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../shared-context.md" class="md-nav__link">
|
||||
<a href="../../shared-context/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -927,7 +927,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../learn.md" class="md-nav__link">
|
||||
<a href="../../learn/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1028,7 +1028,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../integration-guide.md" class="md-nav__link">
|
||||
<a href="../../integration-guide/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1056,7 +1056,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../langchain.md" class="md-nav__link">
|
||||
<a href="../../langchain/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1084,7 +1084,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../agno.md" class="md-nav__link">
|
||||
<a href="../../agno/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1112,7 +1112,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../strands.md" class="md-nav__link">
|
||||
<a href="../../strands/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1140,7 +1140,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../mcp.md" class="md-nav__link">
|
||||
<a href="../../mcp/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1239,7 +1239,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../ARCHITECTURE.md" class="md-nav__link">
|
||||
<a href="../../ARCHITECTURE/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1267,7 +1267,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../transforms.md" class="md-nav__link">
|
||||
<a href="../../transforms/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1295,7 +1295,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../text-compression.md" class="md-nav__link">
|
||||
<a href="../../text-compression/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1420,7 +1420,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../benchmarks.md" class="md-nav__link">
|
||||
<a href="../../benchmarks/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1448,7 +1448,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../LATENCY_BENCHMARKS.md" class="md-nav__link">
|
||||
<a href="../../LATENCY_BENCHMARKS/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1476,7 +1476,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../LIMITATIONS.md" class="md-nav__link">
|
||||
<a href="../../LIMITATIONS/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1579,7 +1579,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../cli.md" class="md-nav__link">
|
||||
<a href="../../cli/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1607,7 +1607,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../api.md" class="md-nav__link">
|
||||
<a href="../../api/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1635,7 +1635,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../sdk.md" class="md-nav__link">
|
||||
<a href="../../sdk/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1663,7 +1663,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../metrics.md" class="md-nav__link">
|
||||
<a href="../../metrics/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1691,7 +1691,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../errors.md" class="md-nav__link">
|
||||
<a href="../../errors/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1719,7 +1719,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../troubleshooting.md" class="md-nav__link">
|
||||
<a href="../../troubleshooting/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1812,7 +1812,7 @@
|
|||
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="../../macos-deployment.md" class="md-nav__link">
|
||||
<a href="../../macos-deployment/" class="md-nav__link">
|
||||
|
||||
|
||||
|
||||
|
|
@ -1867,110 +1867,10 @@
|
|||
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#what-headroom-is" class="md-nav__link">
|
||||
<a href="#problem" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
What Headroom Is
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="What Headroom Is">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#core-value-proposition" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Core Value Proposition
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#what-headroom-is-not" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
What Headroom Is Not
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#design-principles" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Design Principles
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
<nav class="md-nav" aria-label="Design Principles">
|
||||
<ul class="md-nav__list">
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#1-local-first-privacy" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
1. Local-First Privacy
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#2-transparent-compression" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
2. Transparent Compression
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#3-composable-integration" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
3. Composable Integration
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#4-production-ready-defaults" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
4. Production-Ready Defaults
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
</ul>
|
||||
</nav>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#core-guarantees" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Core Guarantees
|
||||
Problem
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1978,10 +1878,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#target-users" class="md-nav__link">
|
||||
<a href="#goals" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Target Users
|
||||
Goals
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -1989,10 +1889,10 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#success-metrics" class="md-nav__link">
|
||||
<a href="#architecture" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Success Metrics
|
||||
Architecture
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -2000,10 +1900,76 @@
|
|||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#version-history" class="md-nav__link">
|
||||
<a href="#command-model" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Version History
|
||||
Command model
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#runtime-adapters" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Runtime adapters
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#supervisor-adapters" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Supervisor adapters
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#tool-target-configuration" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Tool target configuration
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#wrap-behavior" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Wrap behavior
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#docs-strategy" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Docs strategy
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
||||
</li>
|
||||
|
||||
<li class="md-nav__item">
|
||||
<a href="#risks" class="md-nav__link">
|
||||
<span class="md-ellipsis">
|
||||
|
||||
Risks
|
||||
|
||||
</span>
|
||||
</a>
|
||||
|
|
@ -2030,170 +1996,118 @@
|
|||
|
||||
|
||||
|
||||
<h1 id="001-vision">001. Vision<a class="headerlink" href="#001-vision" title="Permanent link">¶</a></h1>
|
||||
<p><strong>Status:</strong> done</p>
|
||||
<h2 id="what-headroom-is">What Headroom Is<a class="headerlink" href="#what-headroom-is" title="Permanent link">¶</a></h2>
|
||||
<p>Headroom is a <strong>context compression proxy</strong> for AI provider APIs. It sits between AI coding tools (Claude Code, Copilot, Codex, etc.) and provider APIs (OpenAI, Anthropic, Google, Cohere), compressing context before it reaches the provider to reduce token usage and costs.</p>
|
||||
<h3 id="core-value-proposition">Core Value Proposition<a class="headerlink" href="#core-value-proposition" title="Permanent link">¶</a></h3>
|
||||
<ol>
|
||||
<li><strong>Token Savings</strong> — 30-90% reduction in tokens sent to providers through semantic compression</li>
|
||||
<li><strong>Cost Reduction</strong> — Lower API costs via compression before provider transmission</li>
|
||||
<li><strong>Context Window Extension</strong> — Effective 2-10x larger context windows via compression</li>
|
||||
<li><strong>Privacy</strong> — Prompts never logged by default; all processing stays local</li>
|
||||
<li><strong>Compatibility</strong> — Works with existing AI coding tools via proxy or SDK</li>
|
||||
</ol>
|
||||
<h3 id="what-headroom-is-not">What Headroom Is Not<a class="headerlink" href="#what-headroom-is-not" title="Permanent link">¶</a></h3>
|
||||
<h1 id="persistent-deployments-installs-design">Persistent Deployments / Installs Design<a class="headerlink" href="#persistent-deployments-installs-design" title="Permanent link">¶</a></h1>
|
||||
<h2 id="problem">Problem<a class="headerlink" href="#problem" title="Permanent link">¶</a></h2>
|
||||
<p>Headroom already supports session-oriented usage through <code>headroom proxy</code>, <code>headroom wrap ...</code>, and the Docker-native wrapper scripts, but there is no first-class way to install Headroom as a durable background runtime. That leaves users to hand-roll launch agents, services, scheduled tasks, or Docker restart policies, and it keeps direct tool usage (<code>claude</code>, <code>codex</code>, <code>copilot</code>, <code>openclaw</code>, etc.) tied to explicit <code>wrap</code> commands.</p>
|
||||
<p>The new feature should make Headroom deployable as a persistent local runtime while keeping the existing on-demand and wrapped flows intact.</p>
|
||||
<h2 id="goals">Goals<a class="headerlink" href="#goals" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li>A model provider — Headroom does not host or run AI models</li>
|
||||
<li>A data store — No prompt storage by default (local SQLite is optional)</li>
|
||||
<li>A logging service — No prompt logging by default</li>
|
||||
<li>A billing service — Usage tracking is internal only</li>
|
||||
<li>Support these runtime/install modes as one coherent system:</li>
|
||||
<li>Persistent Service</li>
|
||||
<li>Persistent Task</li>
|
||||
<li>Persistent Docker</li>
|
||||
<li>On-Demand CLI (Python)</li>
|
||||
<li>On-Demand CLI (Docker)</li>
|
||||
<li>Wrapped (Python)</li>
|
||||
<li>Wrapped (Docker)</li>
|
||||
<li>Support install target selection modes:</li>
|
||||
<li>Auto-Detect</li>
|
||||
<li>All</li>
|
||||
<li>Manual Select</li>
|
||||
<li>Support configuration scopes:</li>
|
||||
<li>Provider</li>
|
||||
<li>User</li>
|
||||
<li>System</li>
|
||||
<li>Keep <code>wrap</code> idempotent and persistent-aware.</li>
|
||||
<li>Preserve local defaults such as <code>localhost:8787</code>.</li>
|
||||
</ul>
|
||||
<h2 id="architecture">Architecture<a class="headerlink" href="#architecture" title="Permanent link">¶</a></h2>
|
||||
<p>Introduce a new shared deployment subsystem under <code>headroom.install</code>.</p>
|
||||
<p>Core model:</p>
|
||||
<ul>
|
||||
<li><code>execution_mode</code>: <code>persistent | on_demand | wrapped</code></li>
|
||||
<li><code>runtime_kind</code>: <code>python | docker</code></li>
|
||||
<li><code>supervisor_kind</code>: <code>service | task | none</code></li>
|
||||
</ul>
|
||||
<p>These three axes normalize all seven user-facing runtime modes without duplicating logic across CLI commands, install scripts, and platform-specific deployment adapters.</p>
|
||||
<p>The subsystem centers on a persisted deployment manifest in <code>~/.headroom/deploy/</code> that records:</p>
|
||||
<ul>
|
||||
<li>resolved proxy configuration</li>
|
||||
<li>runtime type</li>
|
||||
<li>supervisor type</li>
|
||||
<li>configured tool targets</li>
|
||||
<li>applied config mutations</li>
|
||||
<li>generated artifact paths</li>
|
||||
<li>health URL and port</li>
|
||||
</ul>
|
||||
<h2 id="command-model">Command model<a class="headerlink" href="#command-model" title="Permanent link">¶</a></h2>
|
||||
<p>Add a new public <code>headroom install</code> group:</p>
|
||||
<ul>
|
||||
<li><code>headroom install apply</code></li>
|
||||
<li><code>headroom install status</code></li>
|
||||
<li><code>headroom install start</code></li>
|
||||
<li><code>headroom install stop</code></li>
|
||||
<li><code>headroom install restart</code></li>
|
||||
<li><code>headroom install remove</code></li>
|
||||
</ul>
|
||||
<p>Add hidden helper commands for artifact runners and health recovery:</p>
|
||||
<ul>
|
||||
<li><code>headroom install agent run --profile <name></code></li>
|
||||
<li><code>headroom install agent ensure --profile <name></code></li>
|
||||
</ul>
|
||||
<p>Platform supervisors should register the hidden agent entrypoint rather than raw <code>headroom proxy ...</code> so restart, health polling, and manifest handling live in one place.</p>
|
||||
<h2 id="runtime-adapters">Runtime adapters<a class="headerlink" href="#runtime-adapters" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li><code>PythonRuntimeAdapter</code>: launches <code>headroom proxy</code> directly.</li>
|
||||
<li><code>DockerRuntimeAdapter</code>: launches a detached or foreground Docker container with the existing host mounts and loopback-only port publishing.</li>
|
||||
</ul>
|
||||
<p>Persistent Docker uses the same deployment manifest and status semantics as service/task installs, but the child runtime is Docker-managed rather than OS-supervised.</p>
|
||||
<h2 id="supervisor-adapters">Supervisor adapters<a class="headerlink" href="#supervisor-adapters" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li>Linux</li>
|
||||
<li>Service: systemd unit</li>
|
||||
<li>Task: cron watchdog + reboot/start entry</li>
|
||||
<li>macOS</li>
|
||||
<li>Service: LaunchDaemon / LaunchAgent variant</li>
|
||||
<li>Task: launchd user agent or cron-style watchdog where appropriate</li>
|
||||
<li>Windows</li>
|
||||
<li>Service: Windows Service wrapper</li>
|
||||
<li>Task: Scheduled Task startup + periodic health-check task</li>
|
||||
</ul>
|
||||
<p>Each adapter renders artifacts into <code>~/.headroom/deploy/</code> and stores enough metadata for clean removal.</p>
|
||||
<h2 id="tool-target-configuration">Tool target configuration<a class="headerlink" href="#tool-target-configuration" title="Permanent link">¶</a></h2>
|
||||
<p>Provider-level configuration should be target-specific and reversible.</p>
|
||||
<p>Initial target adapters:</p>
|
||||
<ul>
|
||||
<li>Claude Code</li>
|
||||
<li>write <code>env</code> keys into Claude settings JSON where appropriate</li>
|
||||
<li>Codex</li>
|
||||
<li>manage a marked block or targeted settings in <code>~/.codex/config.toml</code></li>
|
||||
<li>Copilot CLI</li>
|
||||
<li>configure BYOK environment surfaces using persistent env strategy</li>
|
||||
<li>OpenClaw</li>
|
||||
<li>reuse existing OpenClaw config/plugin merge logic where possible</li>
|
||||
<li>Aider / Cursor</li>
|
||||
<li>use env-based integration first, with tool-specific config only where a stable supported surface exists</li>
|
||||
</ul>
|
||||
<p>All non-marker edits must store previous values in the deployment manifest so uninstall removes only Headroom-managed changes.</p>
|
||||
<h2 id="wrap-behavior">Wrap behavior<a class="headerlink" href="#wrap-behavior" title="Permanent link">¶</a></h2>
|
||||
<p><code>headroom wrap ...</code> should consult the active deployment manifest before starting a new proxy. If a compatible persistent deployment is present and healthy, <code>wrap</code> should reuse it and only perform any remaining tool-specific preparation. If the deployment exists but is unhealthy, <code>wrap</code> should attempt to recover it through the install subsystem before falling back to an ephemeral proxy.</p>
|
||||
<h2 id="docs-strategy">Docs strategy<a class="headerlink" href="#docs-strategy" title="Permanent link">¶</a></h2>
|
||||
<p>The public docs should be reframed around:</p>
|
||||
<ul>
|
||||
<li>runtime mode</li>
|
||||
<li>lifecycle mode</li>
|
||||
<li>configuration scope</li>
|
||||
<li>direct-use vs <code>wrap</code></li>
|
||||
</ul>
|
||||
<p>Create a new top-level guide at <code>docs/persistent-installs.md</code> and update the existing Docker install, proxy, CLI, getting-started, quickstart, configuration, troubleshooting, and integration docs to reflect the broader runtime story.</p>
|
||||
<h2 id="risks">Risks<a class="headerlink" href="#risks" title="Permanent link">¶</a></h2>
|
||||
<ul>
|
||||
<li>Windows service installation is the highest-risk platform path and needs strong test isolation.</li>
|
||||
<li>Provider-specific config mutation must remain conservative and reversible.</li>
|
||||
<li><code>/health</code> should gain deployment metadata without breaking the existing <code>config</code> payload shape expected by current tests and docs.</li>
|
||||
</ul>
|
||||
<hr />
|
||||
<h2 id="design-principles">Design Principles<a class="headerlink" href="#design-principles" title="Permanent link">¶</a></h2>
|
||||
<h3 id="1-local-first-privacy">1. Local-First Privacy<a class="headerlink" href="#1-local-first-privacy" title="Permanent link">¶</a></h3>
|
||||
<p><strong>Principle:</strong> Prompt data never leaves the proxy unless explicitly exported.</p>
|
||||
<p><strong>Implications:</strong>
|
||||
- All compression happens locally or through the proxy
|
||||
- No third-party data sharing
|
||||
- Optional SQLite storage with user control
|
||||
- Export must be explicitly configured</p>
|
||||
<h3 id="2-transparent-compression">2. Transparent Compression<a class="headerlink" href="#2-transparent-compression" title="Permanent link">¶</a></h3>
|
||||
<p><strong>Principle:</strong> Users see exactly what is being compressed and why.</p>
|
||||
<p><strong>Implications:</strong>
|
||||
- Full observability into compression decisions
|
||||
- Metrics and logs show savings
|
||||
- Transform audit trail available
|
||||
- Dashboard visualizes all compression activity</p>
|
||||
<h3 id="3-composable-integration">3. Composable Integration<a class="headerlink" href="#3-composable-integration" title="Permanent link">¶</a></h3>
|
||||
<p><strong>Principle:</strong> Headroom works alongside existing tools without requiring workflow changes.</p>
|
||||
<p><strong>Implications:</strong>
|
||||
- Proxy mode: route traffic through Headroom
|
||||
- SDK mode: integrate into custom applications
|
||||
- CLI mode: wrap existing AI commands
|
||||
- Agent mode: MCP/LiteLLM/ASGI integrations</p>
|
||||
<h3 id="4-production-ready-defaults">4. Production-Ready Defaults<a class="headerlink" href="#4-production-ready-defaults" title="Permanent link">¶</a></h3>
|
||||
<p><strong>Principle:</strong> Safe defaults that work out of the box.</p>
|
||||
<p><strong>Implications:</strong>
|
||||
- Compression enabled by default
|
||||
- No logging by default
|
||||
- Cache enabled by default
|
||||
- Learning disabled by default</p>
|
||||
<hr />
|
||||
<h2 id="core-guarantees">Core Guarantees<a class="headerlink" href="#core-guarantees" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Guarantee</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Never logs prompts</strong></td>
|
||||
<td>No prompt data in logs unless exporter configured</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Never leaves proxy</strong></td>
|
||||
<td>All data stays local unless explicitly exported</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Composable</strong></td>
|
||||
<td>Works alongside Claude Code, Copilot, Codex, etc.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Transparent</strong></td>
|
||||
<td>Full observability into compression decisions</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Type-safe</strong></td>
|
||||
<td>Full type annotations, mypy compliance</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Test-covered</strong></td>
|
||||
<td>Unit, integration, and E2E test coverage</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h2 id="target-users">Target Users<a class="headerlink" href="#target-users" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>User</th>
|
||||
<th>Use Case</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><strong>Individual Developers</strong></td>
|
||||
<td>Reduce API costs for personal AI coding</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Development Teams</strong></td>
|
||||
<td>Shared compression with learn plugins</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Enterprises</strong></td>
|
||||
<td>Self-hosted deployment with security guarantees</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Plugin Authors</strong></td>
|
||||
<td>Extend Headroom via plugin ABI</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h2 id="success-metrics">Success Metrics<a class="headerlink" href="#success-metrics" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Metric</th>
|
||||
<th>Target</th>
|
||||
<th>Measurement</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Token savings</td>
|
||||
<td>>30%</td>
|
||||
<td>(tokens_before - tokens_after) / tokens_before</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Compression latency</td>
|
||||
<td><50ms</td>
|
||||
<td>Per-request proxy overhead</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Cache hit rate</td>
|
||||
<td>>60%</td>
|
||||
<td>cache_hits / total_requests</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Zero data exfiltration</td>
|
||||
<td>100%</td>
|
||||
<td>No prompts in logs by default</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<hr />
|
||||
<h2 id="version-history">Version History<a class="headerlink" href="#version-history" title="Permanent link">¶</a></h2>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Version</th>
|
||||
<th>Date</th>
|
||||
<th>Changes</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>1.0.0-draft</td>
|
||||
<td>2026-04-16</td>
|
||||
<td>Initial vision document</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
2710
plans/2026-04-17-fix-codex-proxy-resilience-plan/index.html
Normal file
2710
plans/2026-04-17-fix-codex-proxy-resilience-plan/index.html
Normal file
File diff suppressed because it is too large
Load diff
3018
plans/dynamic-smart-crusher/index.html
Normal file
3018
plans/dynamic-smart-crusher/index.html
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -1,7 +0,0 @@
|
|||
const config = {
|
||||
plugins: {
|
||||
'@tailwindcss/postcss': {},
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
29
proxy.ts
29
proxy.ts
|
|
@ -1,29 +0,0 @@
|
|||
import { NextRequest, NextResponse } from 'next/server';
|
||||
import { isMarkdownPreferred, rewritePath } from 'fumadocs-core/negotiation';
|
||||
import { docsContentRoute, docsRoute } from '@/lib/shared';
|
||||
|
||||
const { rewrite: rewriteDocs } = rewritePath(
|
||||
`${docsRoute}{/*path}`,
|
||||
`${docsContentRoute}{/*path}/content.md`,
|
||||
);
|
||||
const { rewrite: rewriteSuffix } = rewritePath(
|
||||
`${docsRoute}{/*path}.mdx`,
|
||||
`${docsContentRoute}{/*path}/content.md`,
|
||||
);
|
||||
|
||||
export default function proxy(request: NextRequest) {
|
||||
const result = rewriteSuffix(request.nextUrl.pathname);
|
||||
if (result) {
|
||||
return NextResponse.rewrite(new URL(result, request.nextUrl));
|
||||
}
|
||||
|
||||
if (isMarkdownPreferred(request)) {
|
||||
const result = rewriteDocs(request.nextUrl.pathname);
|
||||
|
||||
if (result) {
|
||||
return NextResponse.rewrite(new URL(result, request.nextUrl));
|
||||
}
|
||||
}
|
||||
|
||||
return NextResponse.next();
|
||||
}
|
||||
3073
proxy/index.html
Normal file
3073
proxy/index.html
Normal file
File diff suppressed because it is too large
Load diff
2949
quickstart/index.html
Normal file
2949
quickstart/index.html
Normal file
File diff suppressed because it is too large
Load diff
BIN
screenshots/cache-ttl-dashboard-history.png
Normal file
BIN
screenshots/cache-ttl-dashboard-history.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
BIN
screenshots/cache-ttl-dashboard-live.png
Normal file
BIN
screenshots/cache-ttl-dashboard-live.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 142 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 100 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 38 KiB |
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue