mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
2 commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
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. |
||
|
JD Davis
|
8cea290a15
|
docs(ci): add CI/CD flow diagrams (#1062)
## Description
Adds a visual CI/CD flow reference for Headroom so contributors can
quickly understand the gated PR, release, Docker, docs deploy, fork
approval, and manual validation paths. Also updates the release
documentation to match the current release-please release flow instead
of the stale push-to-main release model.
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- Added `docs/content/docs/ci-cd-flows.mdx` with Mermaid diagrams and
decision trees for PR review, release publishing, Docker publishing,
docs deploys, fork workflow approval, and manual validation.
- Updated `docs/content/docs/releases.mdx` to describe the current
`release-please` -> GitHub Release -> `release.yml` publishing path.
- Added the CI/CD flow page and existing release page to docs
navigation.
- Added Mermaid to the docs code highlighter language list.
- Restored missing docs helper modules and aligned Fumadocs dependencies
so the docs app can install, generate sources, type-check, and build.
## Testing
- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ npm ci
> headroom-docs@0.0.0 postinstall
> fumadocs-mdx
[MDX] generated files
added 365 packages, and audited 367 packages
$ npm run types:check
> fumadocs-mdx && next typegen && tsc --noEmit
[MDX] generated files
Generating route types...
✓ Types generated successfully
$ npm run build
> next build
✓ Compiled successfully
Running TypeScript ...
Generating static pages ...
✓ Generating static pages (122/122)
Note: next build completed successfully and emitted two existing Recharts container-size warnings during static generation.
$ git diff --check
# no output
$ act workflow_dispatch -W .github/workflows/docs.yml -n
*DRYRUN* [Deploy Documentation/deploy] 🏁 Job succeeded
```
## Real Behavior Proof
- Environment: Windows local checkout, branch `docs-ci-flow`, Node.js
v22.22.0, `act` 0.2.87.
- Exact command / steps: Ran `npm ci`, `npm run types:check`, and `npm
run build` from `docs/`; ran `git diff --check` and `act
workflow_dispatch -W .github/workflows/docs.yml -n` from the repository
root.
- Observed result: Docs dependencies install, Fumadocs source generation
includes `ci-cd-flows.mdx`, TypeScript passes, Next production build
completes, whitespace check passes, and the docs workflow dry-run
succeeds under `act`.
- Not tested: Full live GitHub Pages deploy and registry/release
publishing, because this PR only changes docs and docs build wiring.
## 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
- [x] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable
## Screenshots (if applicable)
N/A. This is documentation and build wiring; the diagrams are Mermaid
source blocks in the docs page.
## Additional Notes
- No issue is linked because this PR was not opened for a specific
tracked issue.
- `npm run build` still reports two pre-existing Recharts container-size
warnings while completing successfully.
- Python unit/lint/type checks and changelog updates are not applicable
to this docs-only change.
|