mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
## Description Bring the published docs (headroom-docs.vercel.app) back in line with the current codebase. The docs described an older architecture, advertised user/community statistics the code no longer supports (the telemetry beacon was removed), shipped code samples that raise on import, and lacked an in-depth treatment of proxy-mode configuration. Docs-only change — no `headroom/` source touched. ## Type of Change - [x] Documentation update ## Changes Made - **Remove user/community stats.** The anonymous telemetry beacon was removed from the code and `HEADROOM_TELEMETRY` is now local-only, but the docs still advertised aggregate "instances worldwide" figures — which were hardcoded/fabricated. Deleted `community-savings.mdx` (+ nav entry), the community/live stat widgets and their components (`community-charts`, `community-stats-header`, `live-stats`, `stats`, `lib/telemetry`, and a second fabricated `LiveStats` in `marketing.tsx`), and the `## Production Telemetry` section in `benchmarks.mdx`. Reframed all telemetry wording as local-only. - **Correct the architecture docs.** Rewrote `architecture.mdx` to the real pipeline (interceptor → CacheAligner *off-by-default* → ContentRouter; Rust `_core`; CCR on by default). Dropped the removed 3-stage / Context Manager / RollingWindow model. Fixed `how-compression-works.mdx` (3-stage framing, dead LLMLingua reference, wrong compressor class names) and added an off-by-default note to `cache-optimization.mdx`. - **Fix broken code samples** (verified against source): `TextCompressor`→`TextCrusher` + real `SearchCompressorConfig` fields (`text-and-logs`), `MemoryCategory`→plain string (`memory`), `unload_tree_sitter` import path (`code-compression`). - **In-depth proxy configuration.** Added a "Configuration in depth" section to `proxy.mdx` (Kompress, CCR/lossless, file-read handling, reliability, tool-search/MCP, cost-aware routing, observability, security/networking, performance). Fixed the `HEADROOM_MODE` default (`token`→`cache`) in three pages and removed a duplicate `HEADROOM_TELEMETRY` row. - **Nav + links.** Un-orphaned `crewai`/`autogen` in the sidebar; normalized `chopratejas`→`headroomlabs-ai` repo/GHCR links (kept the real HF model id `chopratejas/technique-router`); `litellm-vertex`→`vertex_ai`. ## Testing - [ ] Unit tests pass (`pytest`) — N/A, no `headroom/` code changed - [ ] Linting passes (`ruff check .`) — N/A, no Python changed - [ ] Type checking passes (`mypy headroom`) — N/A, no Python changed - [x] Manual testing performed (static docs validation; output below) ### Test Output ```text -- dangling refs to deleted components/pages (expect empty) -- (none) -- meta.json valid -- pages: 60 | community-savings present: false | crewai: true | autogen: true -- Callout balance (open == close) -- docs/content/docs/proxy.mdx open=6 close=6 docs/content/docs/cache-optimization.mdx open=1 close=1 ``` ## Real Behavior Proof - Environment: docs are static MDX (Fumadocs/Next.js); no runtime behavior. Corrections were checked against `headroom/` source. - Exact command / steps: grepped for references to deleted components/pages; validated `meta.json` parses and no longer contains `community-savings`; confirmed `<Callout>` open/close balance and frontmatter on every edited page; verified every corrected API name/field/import against the source modules (`text_crusher.py`, `search_compressor.py`, `memory/__init__.py`, `code_compressor.py`). - Observed result: no dangling references; nav valid; balanced JSX; corrected code samples match the real importable API. - Not tested: full `next build` / `npm run types:check` — `docs/node_modules` is not installed in this environment. Recommend a Vercel preview deploy (or `cd docs && npm i && npm run types:check`) as the merge gate. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have commented my code, particularly in hard-to-understand areas — N/A (docs) - [x] I have made corresponding changes to the documentation — this *is* the documentation - [x] My changes generate no new warnings - [ ] I have added tests — N/A (docs-only) - [x] New and existing unit tests pass locally with my changes — N/A, no code changed - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes - Docs-only; no `headroom/` package code touched, so the pytest/ruff/mypy items are N/A. - The full Next.js build was not run locally (deps not installed) — a Vercel preview is the recommended gate. - Org normalization assumes `headroomlabs-ai` is canonical (matches CI/GHCR + the newer docs). If `chopratejas/headroom` is still the canonical **public** repo, revert the `docs/lib/*.ts` + install/docker link changes. - Heads-up: a separate `docs` branch exists on the remote — if the Vercel docs site deploys from `docs` rather than `main`, retarget this PR there.
187 lines
5.7 KiB
TypeScript
187 lines
5.7 KiB
TypeScript
import Link from 'next/link';
|
|
import { Button } from './button';
|
|
import { CodeBlock } from './code-block';
|
|
|
|
// --- 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>
|
|
);
|
|
}
|