@aetheros/provider-google

Google Gemini adapter for AetherOS and Aevron (Generative Language API or Vertex AI): streaming, structured output, tools, thinking controls, documents and prompt caching.

import {fromEnvironment} from '@aetheros/provider-google';
const gemini = fromEnvironment(process.env, {model: '<gemini model id>'}); // GEMINI_API_KEY or GOOGLE_API_KEY
engine.registerProvider(gemini);

• Streaming (onEvent) and structured output (responseFormat); system prompt from context.system.
• Images and documents: a message's content may be a list of {type: 'text', text}, {type: 'image', mediaType, data} and {type: 'document', mediaType, data, name?} blocks (base64); they go to Gemini as inline data. Documents may be PDF, plain text, Markdown, CSV, HTML, XML, RTF or JSON; other types are refused with unsupported, and images plus documents over 20 MB with request_too_large (larger files need Gemini's file upload, not built).
• The key goes in a request header, never in the URL, and is never logged.
• Safety blocks come back as refusal, not as an error.
• Errors carry code, status and retryable, so @aetheros/models fallbacks know when another model may help.
• Tools: every call goes through the toolset Aevron hands over, so the host's approval, actor and tenant checks apply. Tool ids with dots become function names with _. Gemini's own turn is sent back unchanged between rounds, which keeps its thought signatures. At most 8 tool rounds by default (maxToolRounds).
• Thinking: effort: 'low' | 'medium' | 'high' (constructor, request or context) becomes thinkingConfig.thinkingLevel (Gemini 3 and later) or a thinkingBudget of 1024, 8192 or 24576 tokens (Gemini 2.5). Models without thinking (Gemini 2.0 and older, Gemma) refuse it with unsupported.
• Prompt caching (on by default): when the system prompt and tool declarations together are large (cacheMinTokens, default 4096, estimated at four characters a token), they are stored once as cached content (cacheTtlSeconds, default 300) and later requests refer to it. If the model or size does not allow it, the request goes out normally and that prefix is not tried again for ten minutes. Gemini's implicit caching works either way. usage.cachedInputTokens reports cached tokens (they are part of usage.inputTokens). Turn it off with promptCache: false. Cached content is also billed for storage while it lives.

Vertex AI

new GoogleProvider({platform: 'vertex', project: 'my-project', region: 'us-central1', model: 'gemini-3.6-flash'});

• Address: https://{region}-aiplatform.googleapis.com (https://aiplatform.googleapis.com for the default region global); endpoint overrides it (https only).

• Access token from GOOGLE_CLOUD_ACCESS_TOKEN or accessToken: async () => token (a credential helper you write). It is read before each request and never stored on public fields. A token from gcloud lasts one hour:

  export GOOGLE_CLOUD_ACCESS_TOKEN="$(gcloud auth print-access-token)"

  PowerShell: $env:GOOGLE_CLOUD_ACCESS_TOKEN = gcloud auth print-access-token

• fromEnvironment() uses Vertex AI when GEMINI_PLATFORM=vertex or GOOGLE_GENAI_USE_VERTEXAI=true, with GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION.