mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
feat/https-compose-caddy
5
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
4288fbd903 |
docs(teams): replace the 3-months-free perk with a talk-to-us pitch (#4524)
## Description Removes the "3 months free with a 12-month plan" offer and every headroom-perks.vercel.app link. Each place now says: not seeing the savings you want? Headroom OSS is a framework built to show what's possible, so it saves less; Headroom Enterprise saves more and adds more cost savings, tokens secured, on premise deployment, deep attribution and many more features. Teams and enterprises: talk to us at hello@headroomlabs.ai or https://headroomlabs.ai. ## 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 - README banner (`.github/assets/enterprise-perk.svg`): redrawn simple, in the `hero.svg` type scale (title 42/700, lead 14.5, eyebrow 10.5); no animation or chips. - README "Headroom for teams" section and docs Teams page: the OSS-vs-Enterprise table is replaced by the pitch, feature list and contact. - Docs site banner (`docs/app/layout.tsx`): new copy and link; new banner id so people who dismissed the old one see it. - Local dashboard offer (unlicensed installs only): new copy and link; new localStorage dismissal key (`headroom-teams-contact-dismissed`) so people who dismissed the old offer see the new one. - Release-notes footer (`release.yml`) and `llms.txt`: same pitch, email and site. - `tests/test_dashboard_teams_perk.py`: asserts the contact email instead of the perks URL. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [ ] Type checking passes (`mypy headroom`) (no Python source changed) - [ ] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest -q tests/test_dashboard_teams_perk.py -k "not route" 4 passed, 4 deselected in 0.49s $ ruff check headroom/dashboard tests/test_dashboard_teams_perk.py All checks passed! ``` The 4 `/dashboard` route tests fail locally with `CancelledError` at proxy startup; they fail the same way on unmodified `main` in the same venv, so CI is the judge for those. ## Real Behavior Proof - Environment: macOS, Python venv of this repo, headless Chrome. - Exact command / steps: rendered `get_dashboard_html(licensed=False/True)` and checked the offer block; rendered the banner with `Google Chrome --headless=new --screenshot --window-size=900,220 file://.github/assets/enterprise-perk.svg`; `grep -rn "headroom-perks\|3 months"` over README, docs, llms.txt, headroom/ and .github/. - Observed result: unlicensed: offer shown, contact email present, no perks link, new dismissal key. Licensed: offer removed. Banner renders cleanly within 880×200 with text in the hero font. The grep finds nothing. - Not tested: the docs site build (`docs/`) and the release-notes footer step (runs only on release). ## Runtime Rollout Safety - Rollout-managed feature(s): none - Minimum rollout channel: n/a - Stable/default behavior changed: only the text and link of the dashboard offer on unlicensed installs - Kill switch / disable path: setting `HEADROOM_LICENSE` removes the offer, as before - Unsafe override required: no - Qualification impact: none - Rollback path: revert this PR ## 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 - [ ] I have commented my code, particularly in hard-to-understand areas - [x] I have made corresponding changes to the documentation - [x] My changes generate no new warnings - [ ] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Additional Notes No test was added for the new dismissal key: it is browser localStorage read by Alpine, which the Python tests do not run. Past release notes still carry the old footer; editing them is a separate one-off. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> |
||
|
|
1ad92f0cbc |
feat: show the Headroom for Teams offer in the dashboard, docs, llms.txt and release notes (#3991)
## Description This PR puts the Headroom for Teams offer (3 months of Enterprise free with a 12-month plan) in the places people go after the README (#3990): the dashboard, the docs site, `llms.txt` and the release notes. Each link carries its own `utm_source`/`utm_medium`, so we can see which surface converts. No linked issue. ## Type of Change - [ ] Bug fix (non-breaking change that fixes an issue) - [x] 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 - **Dashboard:** a slim, dismissible banner under the header. It shows the user's savings when they are $1 or more. It is a plain link, so nothing is fetched or reported. - The banner is removed server-side on any **licensed** proxy, using the running proxy's effective licence: `ProxyConfig.license_key`, `HEADROOM_LICENSE`, or the deprecated `HEADROOM_LICENSE_KEY`. `create_app` resolves the licence once and passes it to `get_dashboard_html(licensed=...)`. This is a review fix: before, only `HEADROOM_LICENSE` was checked. - This only hides a promotion. OSS still needs no licence and checks none; licences belong to the Enterprise plugins. - **Docs site:** a dismissible top banner, a sidebar link and a new `/docs/teams` page. - The page's Open source vs Enterprise table now states what OSS already ships (tool search on Anthropic requests; opt-in, rule-based model routing) and what Enterprise adds. This is a review fix. - **`llms.txt`:** a Headroom for Teams section, with the same accuracy fix. - **Release notes:** a `release.yml` step appends one footer line under the changelog. It is keyed on its own marker, `<!-- headroom-teams-footer -->`, rather than on the perks link, so a changelog entry that mentions the link no longer suppresses the footer. This is a review fix. - **Telemetry opt-out:** `llms.txt` and `docs/content/docs/proxy.mdx` named a `--offline` flag that does not exist. The switch is `HEADROOM_OFFLINE=1`. ## Testing - [x] Unit tests pass (`pytest`) - [x] Linting passes (`ruff check .`) - [x] Type checking passes (`mypy headroom`) - [x] New tests added for new functionality - [x] Manual testing performed ### Test Output ```text $ pytest -q tests/test_dashboard_teams_perk.py tests/test_dashboard_static_assets.py ============================= 17 passed in 18.40s ============================== # test_dashboard_teams_perk.py: renderer, with and without each licence env var and with an explicit flag; # /dashboard route, unlicensed, with ProxyConfig.license_key, with HEADROOM_LICENSE, with HEADROOM_LICENSE_KEY $ pytest -q tests -k "dashboard or release or license" 4 failed, 305 passed, 1 skipped # the 4 failures are tests/test_dashboard/test_live_feed.py (Playwright browser tests). They fail identically # on this branch without the review commit; it is this machine's browser setup. $ ruff check headroom/dashboard/__init__.py headroom/proxy/server.py tests/test_dashboard_teams_perk.py All checks passed! $ mypy headroom/dashboard/__init__.py --ignore-missing-imports Success: no issues found in 1 source file # release footer step, simulated twice on notes that already link the perks page: appended skipped # re-run is a no-op; footer present exactly once ``` ## Real Behavior Proof - Environment: macOS 26.6 (arm64), Python 3.12.13, FastAPI `TestClient` against `create_app`. - Exact command / steps: `pytest -q tests/test_dashboard_teams_perk.py`. The release step's shell was run twice against a notes file that already mentions `headroom-perks.vercel.app`. - Observed result: the `/dashboard` route serves the banner unlicensed, and strips it for each of the three licence sources while leaving the rest of the page intact. The footer is appended once and is not duplicated on a re-run. - Not tested: the release step against a real GitHub release (it runs on the next release), and the docs `next build` after this commit (only Markdown/MDX text changed). ## Runtime Rollout Safety - Rollout-managed feature(s): none. - Minimum rollout channel: stable. - Stable/default behavior changed: yes. Unlicensed dashboards show a dismissible banner, and the docs site shows a dismissible banner. - Kill switch / disable path: set any licence token to hide the dashboard banner. It is a plain link, with no network calls. - Unsafe override required: no. - Qualification impact: none. - Rollback path: revert this PR. ## 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 - [x] My changes generate no new warnings - [x] I have added tests that prove my fix is effective or that my feature works - [x] New and existing unit tests pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` — it is generated by release-please from my Conventional Commit PR title (a CI guard enforces this) ## Screenshots (if applicable) N/A ## Additional Notes - **Review fixes are in `eeb0008a`:** @JerrettDavis's two points (the effective licence source, and the OSS routing row) and Devin's footer-marker and `--offline` findings. - **Not changed:** Devin's suggestion to show sub-dollar savings. The $1 floor is deliberate, because "you saved $0.40" weakens the offer, and the cost card still shows the exact amount. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: JD Davis <mxjerrett@gmail.com> |
||
|
|
4bca514acd |
docs: correct the published site against the code (#3388)
Audited all 52 pages of docs.headroomlabs.ai/docs against source, executing code rather than reading it. **36 pages changed.** Every figure that could not be traced to a benchmark, a test, or a committed artifact was measured or removed — none was replaced with a different guess. ## The site was telling users things that were not true **Telemetry.** `proxy.mdx` stated *"nothing is sent to Headroom Labs"* and that the anonymous beacon *"has been removed from the code."* Neither is true — `BEACON_DEFAULT_ON = True` (`headroom/telemetry/beacon.py:56`), `is_beacon_enabled()` is fail-open, and there is a live POST at `headroom/telemetry/session.py:75`. `proxy.mdx` and `limitations.mdx` now describe both switches accurately, say why the beacon exists (compression quality is the product; it shows when a release regresses a ratio across real workloads), and list the 12 fields the collector allowlists instead of asserting "content-free". The install id is disclosed for what it is: a random UUID, not a machine fingerprint, resettable by deleting the file. **Numbers.** The landing page's "Proof" table claimed 92/92/47/73% savings from a harness that seeded nothing, so it could not reproduce a figure even in principle. | Scenario | Claimed | Measured | |---|---|---| | Code search (100 results) | 92% | **21%** | | SRE incident debugging | 92% | **57%** | | Codebase exploration | 47% | **42%** | | GitHub issue triage | 73% | **30%** | `real_world_agent_benchmark.py` now seeds, and `benchmarks/index_proof_table.py` measures the same four scenarios through the real tokenizer and the real `compress()` path with no network call. Stable across five seeds; the page cites the command. Latency was wrong in the *other* direction — 189 ms and 943 ms published against **0.21 ms and 0.80 ms** measured. The docs made the product look ~1000× slower than it is. **Examples.** Every `agno` example was broken at line one, including Quick Start: `HeadroomAgnoModel`'s first dataclass field is `id`, so a positional wrapped model bound to the wrong field and raised `ValueError`. `api-reference.mdx` — the canonical signature reference — had 13 broken examples, including three `AttributeError`s in the first three lines of its `simulate()` block. Four integration pages omitted the `[proxy]` extra and then told the reader to run `headroom proxy`, which fails immediately. `ccr.mdx` showed SDK-level retrieval that only exists in the proxy handlers. Also: six Prometheus metric names that are never emitted, a Grafana dashboard filtering on a label no metric carries, a documented deploy workflow that does not exist, a 365-day retention default the code caps at 30, and CCR TTL stated as 5 minutes against an actual 1800s. ## Canonical URL bug `robots.ts`, `sitemap.ts` and `layout.tsx` fell back to a hardcoded `headroom-docs.vercel.app` when `NEXT_PUBLIC_SITE_URL` was unset — so the live site served a sitemap and `Host:` on the wrong domain and pointed crawlers at the wrong canonical. Verified in the build output: robots and all 53 sitemap URLs now carry `docs.headroomlabs.ai`. Setting `NEXT_PUBLIC_SITE_URL=https://docs.headroomlabs.ai` in Vercel is still worth doing so previews match, but the code no longer depends on it. ## Verification Four adversarial judges re-checked this work. They confirmed the landing-page table reproduces digit-for-digit across five seeds, found **zero cross-page contradictions**, independently regenerated all nine surviving compression percentages, and proved `headroom_keep_turns` dead at runtime with a mocked-transport test. They also caught two links this audit had reversed to the deprecated org, and 18 examples it had missed — both fixed here. `next build` passes with all 52 pages prerendered, matching the pre-change baseline. ## Follow-up, not in this PR - GitHub org migration (`chopratejas` → `headroomlabs-ai`) across source, manifests and packaging, plus stale-domain fixes in `llms.txt`, the dashboard UI and `pyproject.toml`. - `wiki/` disposition: it is unpublished and unbuilt, and `wiki/benchmarks.md` carried an invented production-telemetry section (250+ instances, 1.4 billion tokens saved) that exists nowhere in the repo. - `langchain.mdx` imports are dead against LangChain 1.x (`langchain.memory`, `langchain.retrievers`, `create_openai_tools_agent`). Needs a pin-vs-rewrite decision. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
|
c1d2eec588 |
docs: improve discoverability for AI agents and search crawlers
Several signals AI agents and search engines use to discover and install a project were misaligned or missing: * ``docs/app/layout.tsx`` set ``metadataBase`` to ``https://chopratejas.github.io/headroom/`` while the live docs run on Vercel — every page's ``og:url`` and ``twitter:url`` resolved to a URL that returns 404 for ``/llms.txt``. Now points at the live Vercel host (overridable via ``NEXT_PUBLIC_SITE_URL`` for a future custom domain). Adds explicit ``openGraph`` and ``twitter`` metadata so social shares render a card with the project's pitch. * No ``llms.txt`` at the GitHub repo root. AI agents crawling ``github.com/chopratejas/headroom/`` saw only the README. The new ``llms.txt`` follows the llmstxt.org convention: 1-line pitch, canonical docs links, copy-paste install commands (pip / npm / Docker / proxy / ``headroom wrap``), and entry points for the library, proxy, MCP server, and SDK integrations. Points at the Fumadocs-generated ``/llms.txt`` and ``/llms-full.txt`` for the full picture. * ``pyproject.toml`` ``Documentation`` URL pointed at the GitHub README anchor. Updated to point at the docs site so PyPI visitors land on searchable docs, and adds an ``AI / LLM Index`` URL pointing at the Fumadocs ``/llms.txt``. * No explicit AI-bot allow list. Added ``docs/app/robots.ts`` (Next 13+ App Router convention) with explicit allows for GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot, ChatGPT-User, Cohere-AI, CCBot, and Applebot-Extended. Wildcard allow as the catch-all. Advertises the sitemap. * No ``sitemap.xml`` route. Added ``docs/app/sitemap.ts`` that pulls every Fumadocs page out of ``source`` (same source backing ``/llms.txt``, search, and OG images) so search and AI crawlers can enumerate doc pages without scraping HTML. * README didn't tell AI agents where to look. Added a 2-line pointer near the top nav row: read ``/llms.txt`` here, or fetch the live index / full docs blob. Also tightened the GitHub repo description and added five topics (``claude-code``, ``cursor``, ``tokens``, ``prompt-engineering``, ``typescript``) via ``gh repo edit`` — that's already live on the repo, not part of this commit. No Python or Rust code changes; ``make ci-precheck`` was run to confirm the test slice still passes. |
||
|
|
911eb85a44 | new docs UI + ts doc coverage |