feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing

[Brad Huffman (ppsplus-bradh)]

Adds native support for two Google Gemini providers via the official @langchain/google package, and routes the enterprise provider across every Vertex AI Model Garden surface:

• gemini (Google AI Studio) — developer setups using GEMINI_API_KEY.
• gemini-enterprise (Gemini Enterprise Agent Platform / Vertex AI) — enterprise setups using Application Default Credentials (ADC) + GOOGLE_CLOUD_PROJECT, reaching Gemini/Gemma and partner models (Claude, Llama, Mistral, DeepSeek, Qwen) through one provider.

Background

This revives Ernani Joppert Pontes Martins (@ernani)'s #36 (which addresses #29) and folds in the follow-up fix from ernani/openwiki#1, rebased onto current main (#36 was based on the 0.0.1 release, before #110/#54/#57/#113 landed in the same files). Full credit to Ernani Joppert Pontes Martins (@ernani) for the original implementation — co-authored on the commit.

What's here

• Unified dependency: @langchain/google, covering both providers under one SDK (platformType: "gai" for AI Studio, "gcp" for Vertex).
• Explicit Vertex project via googleAuthOptions: { projectId } (from the @langchain/google/node entrypoint, since the default entrypoint types authOptions as never) rather than relying on ambient process.env.
• No setup-time network ping — the original onboarding validation call (which mutated process.env.GOOGLE_CLOUD_PROJECT and added a round-trip no other provider performs) is dropped.
• ADC hardening: the enterprise path passes apiKey: "" so a stray GOOGLE_API_KEY in the environment can't silently hijack it into Vertex Express mode (the node client resolves apiKey ?? GOOGLE_API_KEY and prefers the API-key header over ADC; hasApiKey() treats "" as "no key").
• Optional region step: interactive onboarding collects GOOGLE_CLOUD_LOCATION for gemini-enterprise (blank → defaults to us-central1). Kept out of needsCredentialSetup so it never nags on later runs.
• Current model defaults: gemini-3.5-flash (default), gemini-3.1-pro, gemini-3-flash, gemini-3.1-flash-lite.
• Tidy-up: the invalid-provider CLI message is now derived from SELECTABLE_OPENWIKI_PROVIDERS instead of a hand-maintained list.

Vertex model-family routing (5655b26)

Vertex Model Garden serves different model families over different API surfaces, and ChatGoogle only speaks the native generateContent surface. This commit lets gemini-enterprise reach any Model Garden model by dispatching on the model ID to the correct LangChain client — one provider, one ADC credential, and uniform LangSmith tracing (every path stays a BaseChatModel):

Model family	Vertex surface	Client
Gemini, Gemma	generateContent	ChatGoogle (existing)
Anthropic Claude	rawPredict	ChatAnthropic + AnthropicVertex (@anthropic-ai/vertex-sdk)
Llama, Mistral, DeepSeek, Qwen (MaaS)	OpenAI-compatible /endpoints/openapi/chat/completions	ChatOpenAI + per-request ADC bearer-token fetch

The surface is resolved from the model ID by resolveVertexSurface() (src/agent/vertex-surface.ts); publisher-pathed IDs (publishers/…/models/…) are normalized per surface. Users pick any of these through the existing Custom model ID step — no onboarding-flow changes.

Additional details:

• No JS-native Claude-on-Vertex class exists (langchain-google-vertexai's ChatAnthropicVertex is Python-only), so Claude is bridged via ChatAnthropic's createClient hook + the Anthropic Vertex SDK.
• Anthropic env-leak fix: AnthropicVertex extends the base Anthropic SDK, which reads ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN from the environment and would send them as an Authorization header — clobbering the Google OAuth token (ACCESS_TOKEN_TYPE_UNSUPPORTED). Those options are Omitted by the Vertex client, so they're neutralized around its (synchronous) constructor. This matters when a user previously configured the anthropic provider and left ANTHROPIC_API_KEY in ~/.openwiki/.env.
• MaaS auth: the OpenAI-compatible endpoint authenticates via a fetch wrapper that injects a fresh ADC bearer token per request (GoogleAuth.getAccessToken() caches/refreshes), keeping createModel synchronous and surviving token expiry.
• Fail-fast + validation: gemini-enterprise now errors clearly if GOOGLE_CLOUD_PROJECT is unset, and model-ID validation permits @ for versioned Vertex Claude IDs (e.g. claude-sonnet-4-5@20250929).

Verification

pnpm typecheck, pnpm lint, and pnpm test (107/107) pass. Unit tests cover the surface resolver, model-ID normalization, the project-id guard, auth-env neutralization, and the bearer-token fetch wrapper. All three surfaces were also live-verified against real Vertex (construction + streaming + tool-calling + token usage):

• Gemini — gemini-2.5-pro ✅
• Claude — claude-sonnet-4-5@20250929 ✅ (env-leak fix confirmed with ANTHROPIC_AUTH_TOKEN present)
• Llama 3.3 70B MaaS — meta/llama-3.3-70b-instruct-maas ✅

A full openwiki --update documentation run also completed end-to-end driving Claude-on-Vertex. Earlier runtime smoke tests confirm both providers construct and that the enterprise path stays on proper Vertex + ADC even with GOOGLE_API_KEY set.

Closes #29.

🤖 Generated with Claude Code

[Brad Huffman (ppsplus-bradh)]

Flagging overlap with other in-flight Gemini/Vertex PRs to help maintainers coordinate a direction:

• feat: add support for Gemini (AI Studio) and Gemini Enterprise (Vertex AI) #36 (Ernani Joppert Pontes Martins (@ernani)) — the original Gemini support this PR revives and rebases onto current main; feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing #154 is intended to supersede it (co-authored).
• feat: add google vertex ai (claude) provider #179 (SadriG91) — adds a dedicated Vertex Claude provider. feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing #154 overlaps but takes a different shape: rather than a Claude-specific provider, the single gemini-enterprise provider routes Claude — plus Llama/Mistral/DeepSeek/Qwen (MaaS) — through the same ADC + project + region, dispatching to the right client per model ID (resolveVertexSurface).
• feat: add Vertex AI and Bedrock model providers #238 (Dipjyoti Metia (@dipjyotimetia)) — Vertex AI + Bedrock providers.
• feat: add Vertex AI provider for enterprise grade GCP integration #228 (realtusharnargunde) — Vertex AI (enterprise) provider.

All of these touch the same provider/config surface (src/constants.ts, src/agent/index.ts), so whichever lands first will likely conflict with the rest. Raising it so a single approach can be chosen rather than merging overlapping ones — happy to rebase/adjust #154 to fit whatever direction you prefer.

[Brad Huffman (ppsplus-bradh)]

Brace Sproul (@bracesproul) - Thoughts on any of the various GCP/Vertex AI related implementations?

[Paul (avidspartan1)]

Hey Brad Huffman (@ppsplus-bradh) - love the PR and I gave it a whirl. Native Gemini works through the first tool call, but Gemini 3.1 fails on the next turn because the thought_signature from the model’s functionCall is not preserved in conversation history:

Function call is missing a thought_signature in functionCall parts.
Additional data, function call `default_api:ls`

Reproduced with gemini-3.1-flash-lite, @langchain/google@0.2.1, and OpenWiki’s DeepAgents flow. Switching to gemini-2.5-flash-lite, where signature validation is not strict, works as a temporary workaround for me.

[Brad Huffman (ppsplus-bradh)]

Paul (@avidspartan1) - Taking a look. Thanks!

[SadriG91]

Reciprocating the cross-reference from your comment above — I took a proper look at #154 from the #179 side:

The resolveVertexSurface() routing is a genuinely nice design — one ADC credential reaching every Model Garden surface with uniform tracing, and the per-request ADC bearer fetch for the MaaS path is the right way to survive token expiry. We also independently hit the same ANTHROPIC_AUTH_TOKEN-clobbers-Vertex-OAuth bug you reported on #179 — both PRs now neutralize it, which is good mutual confirmation the guard is needed.

One thing you may want to fix regardless of how consolidation shakes out: the blank-region default of us-central1 won't serve the Claude models (nor most MaaS partner models). Verified live with both claude-haiku-4-5@20251001 and claude-sonnet-5: in us-central1 both fail with 400 FAILED_PRECONDITION: Publisher Model ... is not servable in region us-central1, while the same calls through global succeed. Claude on Vertex is served from global, us-east5, and europe-west1 — which is why #179 defaults to global.

On consolidation: #179's apiKeyEnvKey?-optional + getMissingProviderEnvKey() abstraction now coexists with upstream's new authMethod discriminant from the ChatGPT OAuth work, so the "keyless provider" plumbing (gates, onboarding steps, diagnostics) is generic rather than Claude-specific. If maintainers take that base first, your surface routing should drop on top cleanly — your project-as-credential handling collapses into the shared helpers. Happy to coordinate the rebase either direction.

[Brad Huffman (ppsplus-bradh)]

Paul (@avidspartan1) — fix is in place on this branch (commit f47d876) if you'd like to validate. 🙏

Root cause (matches upstream langchain-ai/langchainjs#11181): LangChain core's streaming aggregator (ChatModelStream._assembleMessage) rebuilds the streamed model message as v1 standard content blocks and drops Gemini's provider-specific thoughtSignature — on both the thought parts and the functionCall parts. @langchain/google's v1 outbound converter also does not re-emit it. So on the next turn Gemini 3.x 400s with "Function call is missing a thought_signature." Gemini 2.5 tolerated the missing signature, which is why it looked fine there.

Fix here: set disableStreaming: true + outputVersion: "v0" on the Gemini ChatGoogle clients (native gemini and the gemini-enterprise Gemini surface). That routes calls through invoke()/generate, which honors v0 and preserves the raw Gemini content parts (signature intact) that the v0 converter round-trips correctly. Tradeoff: intra-message token streaming is disabled for Gemini models (graph/tool/step events still stream); Claude and OpenAI-compatible MaaS surfaces are unaffected.

Verified end-to-end against Vertex gemini-3.1-flash-lite across 5+ tool turns — no more thought_signature errors.

This is a workaround pending the upstream streaming fix (langchain-ai/langchainjs#11149 / #10480, both open); once that lands and releases, we can drop disableStreaming and get token streaming back. To try it, run this branch with OPENWIKI_MODEL_ID=gemini-3.1-flash-lite. Thanks again for the clean repro!

[Brad Huffman (ppsplus-bradh)]

SadriG91 — thanks, this is a great read of how the two PRs fit together, and I agree with the layering.

Region: fixed here — the blank-region default is now global (commit 7db41f9) instead of us-central1, since global serves both Gemini and the Vertex Anthropic (Claude) surface. MaaS partner models stay region-specific, so those users set GOOGLE_CLOUD_LOCATION explicitly. Good catch.

Env neutralization: confirming #154 already handles the ANTHROPIC_AUTH_TOKEN/ANTHROPIC_API_KEY-clobbers-Vertex-OAuth problem — withAnthropicAuthEnvNeutralized() in vertex-surface.ts saves/deletes those env vars around the synchronous AnthropicVertex construction and restores them in finally, so the base Anthropic SDK can't send them as Authorization over the Google OAuth token. Happy to align on whichever implementation we keep.

Consolidation — I think a stack beats folding. Per CONTRIBUTING ("one PR = one change"), bundling the generic keyless/project-credential base (getMissingProviderEnvKey(), optional apiKeyEnvKey, the env-neutralize gate) together with the Vertex multi-surface routing (resolveVertexSurface() → Gemini/Claude/MaaS) in a single PR risks a split-request. They layer cleanly instead:

• Base PR: your feat: add google vertex ai (claude) provider #179 generic keyless-provider support.
• Top PR: feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing #154 Vertex surface routing, rebased onto the base.

The one wrinkle is that GitHub can't base a PR on a branch in another fork, so a true side-by-side stack needs both branches in one fork. Two ways to do it:

1. True stack: I host both branches in my fork — base branch = your keyless-provider work (with you as co-author), top branch = the Vertex routing based on it — and open the two stacked PRs. You keep authorship credit on the base.
2. Sequential: feat: add google vertex ai (claude) provider #179 merges to main first, then I rebase feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing #154 on top and drop the overlap. Less coordination, but no parallel review and feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing #154 waits on feat: add google vertex ai (claude) provider #179.

I'm happy to do the hosting for option 1 if you're up for it, or go with option 2 if you'd rather keep #179 as-is — whichever you and the maintainers prefer. Either way I'll rebase the Vertex routing to sit cleanly on your base. WDYT?

[SadriG91]

Thanks for the quick region fix and for confirming the env-neutralization equivalence — either implementation works for me; whichever PR lands second just drops its copy.

On the stack: I'd go with option 2 (sequential). #179 is already rebased onto current main, green, and live-tested, so keeping it as the base PR means zero re-review churn — and reviewers can effectively evaluate the two in parallel today anyway, since your surface-routing commits are cleanly separable from the overlapping base. Once #179 lands I'm glad to help with the rebase of #154 on top if useful.

That said, the sequencing question is really Brace Sproul (@bracesproul)'s call — if the maintainers prefer a single stacked series in one fork, I'm fine with option 1 too, with the base commit co-authored as you proposed.

[Paul (avidspartan1)]

hey Brad Huffman (@ppsplus-bradh) - confirmed the 3.1 fix worked. Thanks!

Next issue, may be out of scope of this PR, but thought I'd mention it:

Gemini does not currently appear to honor OpenWiki’s provider retry configuration for 429 responses.

I reproduced this with gemini-3.1-flash-lite: Gemini returned a 429 requesting a retry in ~23 seconds, but OpenWiki exited with code 1 after ~1.8 seconds. Manually retrying after the requested cooldown succeeded.

createModel() builds retryOptions from OPENWIKI_PROVIDER_RETRY_ATTEMPTS, but neither the gemini ChatGoogle constructor nor the gemini-enterprise path receives those options.

Could the Gemini constructors pass through ...retryOptions and include a test confirming that 429 responses back off and retry—ideally honoring Gemini’s server-provided retry delay?

[Colin Francis (colifran)]

Hey all - thanks for the in depth review of everything open. I'd like to prioritize these. Is my read of #179 first followed by this one correct? If so, I'll dig into #179 now.

cc: Brad Huffman (@ppsplus-bradh) SadriG91

[Colin Francis (colifran)]

and sorry for the delay!

[SadriG91]

Colin Francis (@colifran) Yes, exactly right — #179 first (the keyless-provider base + Claude on Vertex), then Brad Huffman (@ppsplus-bradh) rebases #154's Gemini + multi-surface routing on top and drops the overlapping base. That's the order we converged on above. #179 is rebased onto today's main (55d868f) with your retryOptions fix applied, so it's ready for your pass. Thanks for picking these up!

[Colin Francis (colifran)]

#179 has been merged. This one is next on my list once it gets rebased!

[Brad Huffman (ppsplus-bradh)]

#179 has been merged. This one is next on my list once it gets rebased!

On it.

[Brad Huffman (ppsplus-bradh)]

Colin Francis (@colifran) SadriG91 — thanks for merging #179, and before I push the rebase I want to float one adjustment to the plan we'd converged on, because the ground shifted slightly.

The naming. Since we settled on "#179 as the vertex base, #154 on top," Google retired the Vertex AI product name — at Cloud Next 2026 it was folded into the Gemini Enterprise Agent Platform, and Claude is now a partner model in the Gemini Enterprise Model Garden (Google's Claude-on-Gemini-Enterprise docs). The plumbing is unchanged — same *-aiplatform.googleapis.com endpoints, same rawPredict surface via the Anthropic Vertex SDK — and "Vertex" still shows up in hostnames, SDK class names, and doc URLs, so it's not gone by any means. But the umbrella product users now see is "Gemini Enterprise."

The proposal. Rather than land a second Claude-on-Vertex path next to #179's vertex provider, consolidate both under a single gemini-enterprise provider that routes by model family — Claude → Anthropic Vertex SDK, Gemini/Gemma → ChatGoogle, partner/open-weight → the OpenAI-compatible MaaS surface. #154's router already covers all three surfaces, using the same AnthropicVertex construction and ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN env-neutralization as #179's Claude path, plus publisher-path stripping — so consolidating loses no capability. It would mean dropping the discrete vertex provider #179 just added.

Concretely, this builds on #179 rather than reverting it — I'd rebase and adopt #179's base where it's cleaner than what #154 has today:

• the keyless-provider plumbing (projectEnvKey/locationEnvKey/defaultLocation, getMissingProviderEnvKey, resolveProviderLocation, getProviderCredentialHint), which is cleaner than feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing #154's current approach of overloading apiKeyEnvKey to carry the (non-secret) GOOGLE_CLOUD_PROJECT;
• the gcp-project / gcp-location onboarding steps and CLI/startup credential gates;
• feat: add google vertex ai (claude) provider #179's curated Claude model picker (Haiku/Sonnet/Opus), moved onto gemini-enterprise.

I'd also fold in the fix Paul (@avidspartan1) flagged. The root cause is narrow: createModel never wires maxRetries into the Gemini constructors (the gemini ChatGoogle and all three gemini-enterprise surfaces are the only ones that omit ...retryOptions), so OPENWIKI_PROVIDER_RETRY_ATTEMPTS is silently ignored on those paths and a 429 fails fast. Good news on the "honor the server-provided delay" part: @langchain/core's AsyncCaller already parses Retry-After and waits max(exponential backoff, Retry-After) for hints ≤ 60s — so simply wiring maxRetries through should let that existing handling engage (your 429 asked for ~23s, well under the cap). I'll wire it into both Gemini paths, add a test that the constructor receives the configured retry count, and validate the live 429 back-off; if the header turns out not to reach AsyncCaller on the Google client, honoring the delay explicitly becomes a follow-up.

The alternative is the lower-touch hybrid: keep vertex for Claude and narrow gemini-enterprise to Gemini + MaaS only. That avoids removing anything you just merged, at the cost of the retired name sitting alongside the current one and two overlapping Claude paths.

I lean toward consolidation for the cleaner end state and the branding alignment, but dropping a provider you merged today is your call — happy to go either way. WDYT?

[Colin Francis (colifran)]

Brad Huffman (@ppsplus-bradh) love this! great suggestion. let's do it

[Brad Huffman (ppsplus-bradh)]

Rebased onto latest main (7bd512f) and pushed — the PR is green-mergeable again. I went ahead with the consolidation approach from my note above; happy to revisit if you'd prefer the hybrid, but this felt like the cleaner end state.

Colin Francis (@colifran) — heads up: this force-push replaced your Merge branch 'main' into feat/gemini-provider (f4f3335). Nothing was lost — its only real content was #279 (0c0639e), which is already in main and so is in the rebase. I swapped the merge for a rebase since that's what we'd agreed the branch needed.

What's in the two commits:

1. feat: add Gemini providers and consolidate Vertex Claude into gemini-enterprise — adds gemini (AI Studio, single API key) and gemini-enterprise (keyless, ADC). gemini-enterprise routes each model ID to the right Model Garden surface — Gemini/Gemma → ChatGoogle, Claude → Anthropic Vertex SDK, partner/open-weight → OpenAI-compatible MaaS. It supersedes the vertex provider from feat: add google vertex ai (claude) provider #179: it reaches Claude through the same AnthropicVertex construction and ANTHROPIC_* env-neutralization (plus publisher-path stripping), so no capability is lost, and it builds on your feat: add google vertex ai (claude) provider #179 keyless plumbing and gcp-project/gcp-location onboarding rather than feat: add gemini (ai studio) and gemini enterprise (vertex ai) providers with vertex model-family routing #154's old apiKeyEnvKey-overload. The rename tracks Google's Cloud Next 2026 rebrand while keeping the unchanged API surface.

2. test: verify provider retry attempts reach the Gemini constructors — the Paul (@avidspartan1) 429 fix. createModel now spreads ...retryOptions into every Gemini surface (they were the only constructors omitting it), so OPENWIKI_PROVIDER_RETRY_ATTEMPTS is honored. Once maxRetries is wired through, @langchain/core's AsyncCaller already respects a server-provided Retry-After (≤ 60s), which covers the ~23s hint you saw, Paul (@avidspartan1) — worth a re-test when you get a chance.

Verification: pnpm typecheck clean and full pnpm test green (284 tests, incl. new surface-dispatch and retry-passthrough tests).

One open question for reviewers: I kept the onboarding prompt wording as "Vertex AI access / Vertex AI location" since that's still what the GCP console and IAM roles (roles/aiplatform.user) call it — the provider is branded Gemini Enterprise but the resource names users navigate to are still Vertex. Happy to change if you'd rather it read purely "Gemini Enterprise."

[SadriG91]

Brad Huffman (@ppsplus-bradh) nice touch the consolidation under gemini-enterprise is a clean way forward.

[Brad Huffman (ppsplus-bradh)]

Running some reviews. Identified a gap on the MaaS path. Fix forthcoming.

[Brad Huffman (ppsplus-bradh)]

Pushed a round of self-review fixes (force-push, same 2-commit shape). Ran the change through a few review passes and caught one real default-config bug plus some hardening. All four CI gates pass locally — prettier --check, eslint, tsc --noEmit, and vitest (297 tests, up from 284).

Bug — MaaS on the default global location hit an invalid host. vertexOpenAIBaseUrl interpolated the location as a host prefix (https://global-aiplatform.googleapis.com/…), but the global endpoint is served from the unprefixed aiplatform.googleapis.com (regional locations keep the ${location}- prefix). Since global is the default, any MaaS model would have failed out of the box. The Claude and Gemini surfaces were already fine — their SDKs special-case global internally — so I mirrored that in vertexOpenAIBaseUrl. Same trap cline #10287 and pipecat #2710 hit.

Hardening:

• The Gemini surface now strips a publisher-pathed ID (publishers/google/models/gemini-3-pro → gemini-3-pro) the same way the Claude and MaaS branches normalize theirs — otherwise ChatGoogle built a malformed model path.
• resolveVertexSurface now lists codellama explicitly, so a bare codellama-* ID routes to MaaS instead of falling through to the Gemini default (the (^|/) boundary meant the llama token didn't match after the code prefix).
• Removed a dead ANTHROPIC_API_KEY_ENV_KEY import (was tripping no-unused-vars), extracted the shared Gemini thought-signature options into one constant so the two ChatGoogle surfaces can't drift, and reused the env-key constant in the neutralizer.

New test coverage for the above plus gaps the review flagged: AI Studio gemini construction, the Claude surface's env-neutralization + project/region passthrough (asserts ANTHROPIC_* are actually hidden during AnthropicVertex construction and restored after), global vs regional URL building, resolveConfiguredProvider for the new providers, and the classifier boundary cases.

Diff vs main is 14 files, +988/−69.

[Colin Francis (colifran)]

Thanks Brad Huffman (@ppsplus-bradh)! I'm taking a look!

[Colin Francis (colifran)]

Looks great - great work on this one!

[Colin Francis (colifran)]

Thank you Brad Huffman (@ppsplus-bradh)! If you have an x account you want to share we'd love to shout you out. Same to you SadriG91!

[D. Corto (dcorto)]

amazing work here! <3

[Ernani Joppert Pontes Martins (ernani)]

Hello Colin Francis (@colifran)

I am glad to see that this evolved in such a rapid pace! I've had some 10 days vacation and I can see how far this went through! Glad to collaborate and benefit all Gemini users with Openwiki! Thanks for catching up this PR!

[SadriG91]

Thanks Colin Francis (@colifran)! It's @sadrig91 — same as my GitHub handle. Would be honored. Great collaborating with you and Brad Huffman (@ppsplus-bradh) on this one; the way #179 and #154 converged is open source working exactly as it should.

[Brad Huffman (ppsplus-bradh)]

Colin Francis (@colifran) - X is Brad Huffman (@bradhuffman) Awesome work, all involved. Excited to see the continued evolution of this project.

[realtusharnargunde]

Kudos guys, this is a useful addition. Cheers and hope to collaborate on this project in future.

Closed the related PR author'd by me.