mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
new docs UI + ts doc coverage
This commit is contained in:
Adib Mohsin
parent
ccc763a7b0
commit
911eb85a44
101 changed files with 14334 additions and 0 deletions
26
docs/.gitignore
vendored
Normal file
26
docs/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# deps
|
||||
/node_modules
|
||||
|
||||
# generated content
|
||||
.source
|
||||
|
||||
# test & build
|
||||
/coverage
|
||||
/.next/
|
||||
/out/
|
||||
/build
|
||||
*.tsbuildinfo
|
||||
|
||||
# misc
|
||||
.DS_Store
|
||||
*.pem
|
||||
/.pnp
|
||||
.pnp.js
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# others
|
||||
.env*.local
|
||||
.vercel
|
||||
next-env.d.ts
|
||||
45
docs/README.md
Normal file
45
docs/README.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
# docs
|
||||
|
||||
This is a Next.js application generated with
|
||||
[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
|
||||
|
||||
Run development server:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
# or
|
||||
pnpm dev
|
||||
# or
|
||||
yarn dev
|
||||
```
|
||||
|
||||
Open http://localhost:3000 with your browser to see the result.
|
||||
|
||||
## Explore
|
||||
|
||||
In the project, you can see:
|
||||
|
||||
- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
|
||||
- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep.
|
||||
|
||||
| Route | Description |
|
||||
| ------------------------- | ------------------------------------------------------ |
|
||||
| `app/(home)` | The route group for your landing page and other pages. |
|
||||
| `app/docs` | The documentation layout and pages. |
|
||||
| `app/api/search/route.ts` | The Route Handler for search. |
|
||||
|
||||
### Fumadocs MDX
|
||||
|
||||
A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
|
||||
|
||||
Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
|
||||
|
||||
## Learn More
|
||||
|
||||
To learn more about Next.js and Fumadocs, take a look at the following
|
||||
resources:
|
||||
|
||||
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
|
||||
features and API.
|
||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
||||
- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs
|
||||
6
docs/app/(home)/layout.tsx
Normal file
6
docs/app/(home)/layout.tsx
Normal file
|
|
@ -0,0 +1,6 @@
|
|||
import { HomeLayout } from 'fumadocs-ui/layouts/home';
|
||||
import { baseOptions } from '@/lib/layout.shared';
|
||||
|
||||
export default function Layout({ children }: LayoutProps<'/'>) {
|
||||
return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
|
||||
}
|
||||
5
docs/app/(home)/page.tsx
Normal file
5
docs/app/(home)/page.tsx
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
import { redirect } from 'next/navigation';
|
||||
|
||||
export default function HomePage() {
|
||||
redirect('/docs');
|
||||
}
|
||||
7
docs/app/api/search/route.ts
Normal file
7
docs/app/api/search/route.ts
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
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',
|
||||
});
|
||||
63
docs/app/docs/[[...slug]]/page.tsx
Normal file
63
docs/app/docs/[[...slug]]/page.tsx
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
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,
|
||||
},
|
||||
};
|
||||
}
|
||||
11
docs/app/docs/layout.tsx
Normal file
11
docs/app/docs/layout.tsx
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
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>
|
||||
);
|
||||
}
|
||||
53
docs/app/global.css
Normal file
53
docs/app/global.css
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
@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;
|
||||
}
|
||||
28
docs/app/layout.tsx
Normal file
28
docs/app/layout.tsx
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
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'],
|
||||
});
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: {
|
||||
default: 'Headroom',
|
||||
template: '%s | Headroom',
|
||||
},
|
||||
description:
|
||||
'Compress everything your AI agent reads. Same answers, fraction of the tokens.',
|
||||
metadataBase: new URL('https://chopratejas.github.io/headroom/'),
|
||||
};
|
||||
|
||||
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>
|
||||
);
|
||||
}
|
||||
10
docs/app/llms-full.txt/route.ts
Normal file
10
docs/app/llms-full.txt/route.ts
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
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'));
|
||||
}
|
||||
23
docs/app/llms.mdx/docs/[[...slug]]/route.ts
Normal file
23
docs/app/llms.mdx/docs/[[...slug]]/route.ts
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
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,
|
||||
}));
|
||||
}
|
||||
8
docs/app/llms.txt/route.ts
Normal file
8
docs/app/llms.txt/route.ts
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
import { source } from '@/lib/source';
|
||||
import { llms } from 'fumadocs-core/source';
|
||||
|
||||
export const revalidate = false;
|
||||
|
||||
export function GET() {
|
||||
return new Response(llms(source).index());
|
||||
}
|
||||
27
docs/app/og/docs/[...slug]/route.tsx
Normal file
27
docs/app/og/docs/[...slug]/route.tsx
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
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,
|
||||
}));
|
||||
}
|
||||
1176
docs/bun.lock
Normal file
1176
docs/bun.lock
Normal file
File diff suppressed because it is too large
Load diff
59
docs/components/button.tsx
Normal file
59
docs/components/button.tsx
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
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 };
|
||||
12
docs/components/code-block.tsx
Normal file
12
docs/components/code-block.tsx
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
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>
|
||||
);
|
||||
}
|
||||
346
docs/components/community-charts.tsx
Normal file
346
docs/components/community-charts.tsx
Normal file
|
|
@ -0,0 +1,346 @@
|
|||
'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>
|
||||
)
|
||||
}
|
||||
95
docs/components/map.tsx
Normal file
95
docs/components/map.tsx
Normal file
|
|
@ -0,0 +1,95 @@
|
|||
'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"
|
||||
/>
|
||||
)
|
||||
}
|
||||
224
docs/components/marketing.tsx
Normal file
224
docs/components/marketing.tsx
Normal file
|
|
@ -0,0 +1,224 @@
|
|||
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>
|
||||
);
|
||||
}
|
||||
41
docs/components/mdx.tsx
Normal file
41
docs/components/mdx.tsx
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
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 {
|
||||
LiveStats,
|
||||
KeyFeatures,
|
||||
FrameworkIntegrations,
|
||||
} from './marketing';
|
||||
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,
|
||||
LiveStats,
|
||||
KeyFeatures,
|
||||
FrameworkIntegrations,
|
||||
...components,
|
||||
} satisfies MDXComponents;
|
||||
}
|
||||
|
||||
export const useMDXComponents = getMDXComponents;
|
||||
|
||||
declare global {
|
||||
type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
|
||||
}
|
||||
71
docs/components/stats.tsx
Normal file
71
docs/components/stats.tsx
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
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>
|
||||
)
|
||||
}
|
||||
154
docs/content/docs/agno.mdx
Normal file
154
docs/content/docs/agno.mdx
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
---
|
||||
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 |
|
||||
127
docs/content/docs/anthropic-sdk.mdx
Normal file
127
docs/content/docs/anthropic-sdk.mdx
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
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: {} } }],
|
||||
});
|
||||
```
|
||||
785
docs/content/docs/api-reference.mdx
Normal file
785
docs/content/docs/api-reference.mdx
Normal file
|
|
@ -0,0 +1,785 @@
|
|||
---
|
||||
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.
|
||||
131
docs/content/docs/architecture.mdx
Normal file
131
docs/content/docs/architecture.mdx
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
---
|
||||
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)
|
||||
150
docs/content/docs/benchmarks.mdx
Normal file
150
docs/content/docs/benchmarks.mdx
Normal file
|
|
@ -0,0 +1,150 @@
|
|||
---
|
||||
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
|
||||
```
|
||||
163
docs/content/docs/cache-optimization.mdx
Normal file
163
docs/content/docs/cache-optimization.mdx
Normal file
|
|
@ -0,0 +1,163 @@
|
|||
---
|
||||
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
|
||||
205
docs/content/docs/ccr.mdx
Normal file
205
docs/content/docs/ccr.mdx
Normal file
|
|
@ -0,0 +1,205 @@
|
|||
---
|
||||
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. To disable:
|
||||
# headroom proxy --no-ccr-responses
|
||||
|
||||
# To disable proactive expansion:
|
||||
# headroom proxy --no-ccr-expansion
|
||||
```
|
||||
</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.
|
||||
173
docs/content/docs/code-compression.mdx
Normal file
173
docs/content/docs/code-compression.mdx
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
---
|
||||
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_llmlingua=True, # Use LLMLingua 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_llmlingua` | `True` | Use LLMLingua 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>
|
||||
22
docs/content/docs/community-savings.mdx
Normal file
22
docs/content/docs/community-savings.mdx
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
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
|
||||
|
||||
<CommunityCharts section="stats" />
|
||||
|
||||
## Savings Over Time
|
||||
|
||||
<CommunityCharts section="area" />
|
||||
|
||||
## Top Savings by Instance
|
||||
|
||||
<CommunityCharts section="bar" />
|
||||
|
||||
## Instance Details
|
||||
|
||||
<CommunityCharts section="table" />
|
||||
371
docs/content/docs/configuration.mdx
Normal file
371
docs/content/docs/configuration.mdx
Normal file
|
|
@ -0,0 +1,371 @@
|
|||
---
|
||||
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.
|
||||
|
||||
## 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
|
||||
--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
|
||||
|
||||
# Enable LLMLingua ML compression
|
||||
headroom proxy --llmlingua
|
||||
headroom proxy --llmlingua --llmlingua-device cuda --llmlingua-rate 0.4
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
|----------|-------------|---------|
|
||||
| `HEADROOM_LOG_LEVEL` | Logging level | `INFO` |
|
||||
| `HEADROOM_STORE_URL` | Database URL | temp directory |
|
||||
| `HEADROOM_DEFAULT_MODE` | Default mode | `optimize` |
|
||||
| `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_SAVINGS_PATH` | Override persistent savings file location | `~/.headroom/proxy_savings.json` |
|
||||
| `HEADROOM_TELEMETRY` | Set to `off` to disable anonymous telemetry | `on` |
|
||||
|
||||
## 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/models.json`, or set `HEADROOM_MODEL_LIMITS` to a JSON string or file path.
|
||||
|
||||
Settings are resolved in this order (later overrides earlier):
|
||||
|
||||
1. Built-in defaults
|
||||
2. `~/.headroom/models.json` config file
|
||||
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}")
|
||||
```
|
||||
188
docs/content/docs/context-management.mdx
Normal file
188
docs/content/docs/context-management.mdx
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
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.
|
||||
276
docs/content/docs/errors.mdx
Normal file
276
docs/content/docs/errors.mdx
Normal file
|
|
@ -0,0 +1,276 @@
|
|||
---
|
||||
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
|
||||
```
|
||||
138
docs/content/docs/failure-learning.mdx
Normal file
138
docs/content/docs/failure-learning.mdx
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
---
|
||||
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) |
|
||||
160
docs/content/docs/how-compression-works.mdx
Normal file
160
docs/content/docs/how-compression-works.mdx
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
---
|
||||
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>
|
||||
153
docs/content/docs/image-compression.mdx
Normal file
153
docs/content/docs/image-compression.mdx
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
---
|
||||
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
|
||||
# Enable image compression (default)
|
||||
headroom proxy --image-optimize
|
||||
|
||||
# Disable image compression
|
||||
headroom proxy --no-image-optimize
|
||||
```
|
||||
|
||||
## 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>
|
||||
109
docs/content/docs/index.mdx
Normal file
109
docs/content/docs/index.mdx
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
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>
|
||||
164
docs/content/docs/installation.mdx
Normal file
164
docs/content/docs/installation.mdx
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
---
|
||||
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.
|
||||
|
||||
### 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]"
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### 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` | `0.0.0.0` | Host the proxy binds to |
|
||||
| `HEADROOM_MODE` | `optimize` | Default mode: `optimize`, `audit`, or `passthrough` |
|
||||
| `HEADROOM_LOG_LEVEL` | `INFO` | Logging level |
|
||||
|
||||
### 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>
|
||||
188
docs/content/docs/langchain.mdx
Normal file
188
docs/content/docs/langchain.mdx
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
---
|
||||
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,
|
||||
)
|
||||
```
|
||||
143
docs/content/docs/limitations.mdx
Normal file
143
docs/content/docs/limitations.mdx
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
---
|
||||
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`)
|
||||
89
docs/content/docs/litellm.mdx
Normal file
89
docs/content/docs/litellm.mdx
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
---
|
||||
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`.
|
||||
149
docs/content/docs/mcp.mdx
Normal file
149
docs/content/docs/mcp.mdx
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
---
|
||||
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
|
||||
```
|
||||
|
||||
## 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.
|
||||
243
docs/content/docs/memory.mdx
Normal file
243
docs/content/docs/memory.mdx
Normal file
|
|
@ -0,0 +1,243 @@
|
|||
---
|
||||
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 |
|
||||
49
docs/content/docs/meta.json
Normal file
49
docs/content/docs/meta.json
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
{
|
||||
"pages": [
|
||||
"---Getting Started---",
|
||||
"index",
|
||||
"quickstart",
|
||||
"installation",
|
||||
"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",
|
||||
"---Observability---",
|
||||
"metrics",
|
||||
"simulation",
|
||||
"---API Reference---",
|
||||
"api-reference",
|
||||
"---Architecture---",
|
||||
"architecture",
|
||||
"benchmarks",
|
||||
"limitations",
|
||||
"---Help---",
|
||||
"errors",
|
||||
"troubleshooting"
|
||||
]
|
||||
}
|
||||
272
docs/content/docs/metrics.mdx
Normal file
272
docs/content/docs/metrics.mdx
Normal file
|
|
@ -0,0 +1,272 @@
|
|||
---
|
||||
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,
|
||||
"llmlingua_enabled": false
|
||||
}
|
||||
```
|
||||
|
||||
## 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)` |
|
||||
126
docs/content/docs/openai-sdk.mdx
Normal file
126
docs/content/docs/openai-sdk.mdx
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
---
|
||||
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: {} } }],
|
||||
});
|
||||
```
|
||||
246
docs/content/docs/proxy.mdx
Normal file
246
docs/content/docs/proxy.mdx
Normal file
|
|
@ -0,0 +1,246 @@
|
|||
---
|
||||
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 |
|
||||
| `--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 |
|
||||
| `--budget` | None | Daily budget limit in USD |
|
||||
| `--openai-api-url` | `https://api.openai.com` | Custom OpenAI API URL |
|
||||
|
||||
### Context management
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--no-intelligent-context` | `false` | Fall back to RollingWindow (oldest-first drops) |
|
||||
| `--no-intelligent-scoring` | `false` | Disable multi-factor importance scoring |
|
||||
| `--no-compress-first` | `false` | Disable trying deeper compression before dropping |
|
||||
|
||||
By default, the proxy uses **IntelligentContextManager** which scores messages by recency, semantic similarity, TOIN-learned patterns, error indicators, and forward references. Dropped messages are stored in CCR for retrieval.
|
||||
|
||||
```bash
|
||||
# Use legacy RollingWindow
|
||||
headroom proxy --no-intelligent-context
|
||||
|
||||
# Faster but less intelligent scoring
|
||||
headroom proxy --no-intelligent-scoring
|
||||
```
|
||||
|
||||
### LLMLingua (ML compression)
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--llmlingua` | `false` | Enable LLMLingua-2 ML-based compression |
|
||||
| `--llmlingua-device` | `auto` | Device: `auto`, `cuda`, `cpu`, `mps` |
|
||||
| `--llmlingua-rate` | `0.3` | Target compression rate (0.3 = keep 30%) |
|
||||
|
||||
```bash
|
||||
pip install "headroom-ai[llmlingua]"
|
||||
|
||||
headroom proxy --llmlingua --llmlingua-device cuda
|
||||
headroom proxy --llmlingua --llmlingua-rate 0.2
|
||||
```
|
||||
|
||||
<Callout type="info" title="LLMLingua resource cost">
|
||||
LLMLingua adds ~2 GB of dependencies (torch, transformers), 10-30s cold start, and ~1 GB RAM. Enable when maximum compression justifies the cost.
|
||||
</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/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>
|
||||
240
docs/content/docs/quickstart.mdx
Normal file
240
docs/content/docs/quickstart.mdx
Normal file
|
|
@ -0,0 +1,240 @@
|
|||
---
|
||||
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>
|
||||
227
docs/content/docs/shared-context.mdx
Normal file
227
docs/content/docs/shared-context.mdx
Normal file
|
|
@ -0,0 +1,227 @@
|
|||
---
|
||||
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
|
||||
149
docs/content/docs/simulation.mdx
Normal file
149
docs/content/docs/simulation.mdx
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
---
|
||||
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>
|
||||
143
docs/content/docs/smart-crusher.mdx
Normal file
143
docs/content/docs/smart-crusher.mdx
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
---
|
||||
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>
|
||||
137
docs/content/docs/strands.mdx
Normal file
137
docs/content/docs/strands.mdx
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
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 |
|
||||
213
docs/content/docs/text-and-logs.mdx
Normal file
213
docs/content/docs/text-and-logs.mdx
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
---
|
||||
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% |
|
||||
| `LLMLinguaCompressor` | Any text (max compression) | Semantic meaning via ML | 80-95% |
|
||||
|
||||
## 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
|
||||
|
||||
## LLMLingua (Optional, Maximum Compression)
|
||||
|
||||
For maximum compression on any text, Headroom integrates with Microsoft's LLMLingua-2, a BERT-based token classifier trained via GPT-4 distillation. It achieves up to 20x compression while preserving semantic meaning.
|
||||
|
||||
```python
|
||||
from headroom.transforms import LLMLinguaCompressor, LLMLinguaConfig
|
||||
|
||||
config = LLMLinguaConfig(
|
||||
device="auto", # auto, cuda, cpu, mps
|
||||
code_compression_rate=0.4, # Conservative for code
|
||||
json_compression_rate=0.35, # Moderate for JSON
|
||||
text_compression_rate=0.25, # Aggressive for text
|
||||
)
|
||||
|
||||
compressor = LLMLinguaCompressor(config)
|
||||
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 is opt-in">
|
||||
LLMLingua adds ~2GB of model weights and 50-200ms latency per request. Install it only when you need maximum compression: `pip install "headroom-ai[llmlingua]"`
|
||||
</Callout>
|
||||
|
||||
### Memory Management
|
||||
|
||||
```python
|
||||
from headroom.transforms import unload_llmlingua_model, is_llmlingua_model_loaded
|
||||
|
||||
# Check if model is loaded
|
||||
print(is_llmlingua_model_loaded()) # True
|
||||
|
||||
# Free ~1GB RAM when done
|
||||
unload_llmlingua_model()
|
||||
```
|
||||
|
||||
## 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 |
|
||||
| Any (max compression mode) | LLMLinguaCompressor | Explicitly enabled |
|
||||
|
||||
## 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 |
|
||||
| LLMLinguaCompressor | Any text | 5-20% of original | 50-200ms |
|
||||
352
docs/content/docs/troubleshooting.mdx
Normal file
352
docs/content/docs/troubleshooting.mdx
Normal file
|
|
@ -0,0 +1,352 @@
|
|||
---
|
||||
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
|
||||
|
||||
### 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
|
||||
139
docs/content/docs/vercel-ai-sdk.mdx
Normal file
139
docs/content/docs/vercel-ai-sdk.mdx
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
---
|
||||
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.
|
||||
11
docs/next.config.mjs
Normal file
11
docs/next.config.mjs
Normal file
|
|
@ -0,0 +1,11 @@
|
|||
import { createMDX } from 'fumadocs-mdx/next';
|
||||
|
||||
const withMDX = createMDX();
|
||||
|
||||
/** @type {import('next').NextConfig} */
|
||||
const config = {
|
||||
reactStrictMode: true,
|
||||
serverExternalPackages: ['typescript', 'twoslash'],
|
||||
};
|
||||
|
||||
export default withMDX(config);
|
||||
5257
docs/package-lock.json
generated
Normal file
5257
docs/package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load diff
41
docs/package.json
Normal file
41
docs/package.json
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
{
|
||||
"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.2",
|
||||
"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.8",
|
||||
"tailwindcss": "^4.2.2",
|
||||
"typescript": "^5.9.3"
|
||||
}
|
||||
}
|
||||
7
docs/postcss.config.mjs
Normal file
7
docs/postcss.config.mjs
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
const config = {
|
||||
plugins: {
|
||||
'@tailwindcss/postcss': {},
|
||||
},
|
||||
};
|
||||
|
||||
export default config;
|
||||
29
docs/proxy.ts
Normal file
29
docs/proxy.ts
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
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();
|
||||
}
|
||||
44
docs/source.config.ts
Normal file
44
docs/source.config.ts
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
|
||||
import { metaSchema, pageSchema } from 'fumadocs-core/source/schema';
|
||||
import { transformerTwoslash } from 'fumadocs-twoslash';
|
||||
import { rehypeCodeDefaultOptions } from 'fumadocs-core/mdx-plugins';
|
||||
|
||||
export const docs = defineDocs({
|
||||
dir: 'content/docs',
|
||||
docs: {
|
||||
schema: pageSchema,
|
||||
postprocess: {
|
||||
includeProcessedMarkdown: true,
|
||||
},
|
||||
},
|
||||
meta: {
|
||||
schema: metaSchema,
|
||||
},
|
||||
});
|
||||
|
||||
export default defineConfig({
|
||||
mdxOptions: {
|
||||
rehypeCodeOptions: {
|
||||
themes: {
|
||||
light: 'github-light',
|
||||
dark: 'github-dark',
|
||||
},
|
||||
transformers: [
|
||||
...(rehypeCodeDefaultOptions.transformers ?? []),
|
||||
transformerTwoslash({
|
||||
twoslashOptions: {
|
||||
compilerOptions: {
|
||||
target: 9, // ES2022
|
||||
lib: ['lib.es2022.d.ts', 'lib.dom.d.ts', 'lib.dom.iterable.d.ts'],
|
||||
},
|
||||
// Documentation code snippets are illustrative — don't require full type validity
|
||||
handbookOptions: {
|
||||
noErrors: true,
|
||||
},
|
||||
},
|
||||
}),
|
||||
],
|
||||
langs: ['js', 'jsx', 'ts', 'tsx', 'python', 'bash', 'json', 'yaml', 'toml', 'css'],
|
||||
},
|
||||
},
|
||||
});
|
||||
35
docs/tsconfig.json
Normal file
35
docs/tsconfig.json
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
{
|
||||
"compilerOptions": {
|
||||
"target": "ESNext",
|
||||
"lib": ["dom", "dom.iterable", "esnext"],
|
||||
"allowJs": true,
|
||||
"skipLibCheck": true,
|
||||
"strict": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"noEmit": true,
|
||||
"esModuleInterop": true,
|
||||
"module": "esnext",
|
||||
"moduleResolution": "bundler",
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"jsx": "react-jsx",
|
||||
"incremental": true,
|
||||
"paths": {
|
||||
"@/*": ["./*"],
|
||||
"collections/*": ["./.source/*"]
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "next"
|
||||
}
|
||||
]
|
||||
},
|
||||
"include": [
|
||||
"next-env.d.ts",
|
||||
"**/*.ts",
|
||||
"**/*.tsx",
|
||||
".next/types/**/*.ts",
|
||||
".next/dev/types/**/*.ts"
|
||||
],
|
||||
"exclude": ["node_modules"]
|
||||
}
|
||||
|
Before Width: | Height: | Size: 86 KiB After Width: | Height: | Size: 86 KiB |
|
Before Width: | Height: | Size: 142 KiB After Width: | Height: | Size: 142 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