headroom/docs/components/marketing.tsx
Tejas Chopra 5a0a5a79cd
docs: sync Vercel docs with current code and add in-depth proxy config (#2475)
## 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.
2026-07-21 16:26:56 -07:00

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 &rarr;
</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 &rarr;
</Link>
</div>
)),
)}
</div>
<Button variant="link" size="sm" asChild>
<Link href="/docs/quickstart">
All integration patterns &rarr;
</Link>
</Button>
</div>
);
}