mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
45a5a33b33
## Description Documents the Vertex AI proxy backend properly, fixing #2393. Following the docs verbatim (`pip install "headroom-ai[proxy]"` + `headroom proxy --backend vertex_ai`) currently fails with `vertexai import failed`, and the LiteLLM-specific `VERTEXAI_PROJECT`/`VERTEXAI_LOCATION` env vars are documented nowhere — risking requests silently resolving against the ADC default quota project and billing the wrong GCP project. All documented behavior was verified against source: alias normalization in `headroom/providers/registry.py` (`vertex`/`google-vertex`/`googlevertex` → `vertex_ai`), the always-registered native publisher passthrough routes in `headroom/providers/proxy_routes.py`, and `pyproject.toml` (no extra pulls in `google-cloud-aiplatform`). ## Type of Change - [ ] Bug fix - [ ] New feature - [x] Documentation update - [ ] Refactor - [ ] Other ## Changes Made - `docs/content/docs/proxy.mdx`: new **Google Vertex AI** subsection under Cloud providers — `google-cloud-aiplatform>=1.38` requirement (not in any extra or Docker image), `VERTEXAI_PROJECT`/`VERTEXAI_LOCATION` env vars with a warning about silent ADC quota-project fallback and their distinction from the standard `GOOGLE_CLOUD_PROJECT`/`GOOGLE_CLOUD_LOCATION` vars, backend name alias equivalence (`vertex_ai` / `vertex` / `google-vertex` / `googlevertex` / `litellm-vertex` / `litellm-vertex_ai`), and cross-links to the Claude Code on Vertex page and the LiteLLM callback page. - `docs/content/docs/proxy.mdx`: new **Native Vertex passthrough routes** subsection documenting the unconditionally registered `/{api_version}/projects/{project}/locations/{location}/publishers/{publisher}/models/{model}:*` routes and the `publisher=google` (Gemini handler) vs `publisher=anthropic` (LiteLLM-Vertex path) branching. - `docs/content/docs/installation.mdx`: added `VERTEXAI_PROJECT` and `VERTEXAI_LOCATION` rows to the LLM provider keys table, plus a pointer to the new Vertex section for the SDK dependency. - `docs/content/docs/litellm.mdx`: cross-reference callout distinguishing the LiteLLM callback integration from the proxy's `litellm-*` backends (issue gap #5). ## Testing - [x] Docs build passes locally **Test Output** ``` $ npm run build # docs/ — same as CI validate-nextjs ✓ Static + SSG pages generated (exit code 0), /docs/proxy, /docs/installation, /docs/litellm prerendered $ mkdocs build # same as CI validate-mkdocs INFO - Documentation built in 8.32 seconds ``` ## Real Behavior Proof - Environment: Windows 11, Node 20, npm 10, Python 3.13, mkdocs-material (latest), branch `docs/2393-vertex-ai-backend` off `upstream/main`. - Exact command / steps: `cd docs && npm ci && npm run build`; `mkdocs build` from repo root; manually re-verified each documented claim against `headroom/providers/registry.py` (alias normalization), `headroom/providers/proxy_routes.py` (publisher passthrough routes), and `pyproject.toml` `[project.optional-dependencies]` (no vertex SDK in any extra). - Observed result: Both docs builds succeed; new sections render with valid internal anchors (`/docs/proxy#google-vertex-ai`, `/docs/proxy#cloud-providers`, `/docs/claude-code-vertex`, `/docs/litellm`). - Not tested: Live end-to-end Vertex AI request through the proxy (no GCP project available); error messages and env-var behavior are taken from the issue reporter's verified reproduction on v0.32.0 and cross-checked against LiteLLM's Vertex provider docs. ## Review Readiness - [x] I have performed a self-review - [x] This PR is ready for human review Co-authored-by: Claude Fable 5 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| app | ||
| components | ||
| content/docs | ||
| lib | ||
| overrides | ||
| screenshots | ||
| .gitignore | ||
| bun.lock | ||
| claude-code-bedrock-headroom.md | ||
| next.config.mjs | ||
| observability.md | ||
| package-lock.json | ||
| package.json | ||
| platform-feature-matrix.json | ||
| platform-stabilization.md | ||
| postcss.config.mjs | ||
| proxy.ts | ||
| README.md | ||
| rtk-architecture.md | ||
| source.config.ts | ||
| tsconfig.json | ||
| vercel.json | ||
docs
This is a Next.js application generated with Create Fumadocs.
Run development server:
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()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 for further details.
Learn More
To learn more about Next.js and Fumadocs, take a look at the following resources:
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
- Fumadocs - learn about Fumadocs