@use-crux/google

Google message content supports native image, audio, video, and documents. Specialized exports include Imagen/Gemini-native generateImage(), finite Interactions streamImage(), native Gemini generateSpeech() (including two-speaker configuration), finite TTS streamSpeech(), and composed transcribe(). Composed transcription returns text with no word timing or diarization and rejects those requests before I/O. Endpoint-specific options stay separated in typed extra records. All five specialized media operations use the portable media-operation Safety contracts; canonical audits are returned in result.safety, while provider-native raw values remain unguarded. See the content-primitive matrix.

Peer dependency: @google/genai (^2.0.0)

import {
  createGoogle,
  embedding,
  googleProviderRuntime,
  googleTranscript,
  toMessages,
  fromMessages,
} from "@use-crux/google";
import { createGenerateObjectFn, createGenerateTextFn } from "@use-crux/google";

Request capacity and counting

The adapter exposes adapter.capacity(model) and the standalone googleModelCapacity(model) helper. Capacity lookup is synchronous and does not create or read CachedContent.

import { googleModelCapacity } from "@use-crux/google";

const profile = googleModelCapacity("gemini-2.5-flash");

Versioned aliases inherit their family profile. Unknown identifiers use a conservative 32,768-token window with an 8,192-token reserve. Known profiles report countingConfidence: "estimated"; the fallback reports "conservative".

The adapter does not call a provider token-count endpoint. Crux estimates the complete request and reports the applied margin in request inspection. Cached input can reduce provider billing, but it does not reduce the model context capacity used for fit.

createGoogle(client, opts?)

Create an adapter bound to a Google GenAI client with optional CachedContent configuration.

createGoogle() is the package's mapped single-turn bundle factory: it resolves the CachedContent option into a single GoogleCachedContentLifecycle, passes it into the provider runtime, and returns the bound adapter. The lifecycle owns prefix detection, cache keying/reuse, SDK cache operations, and fallback policy, and returns a request-ready config patch that both generate() and stream() merge. The package-owned googleTranscript owns Content[] conversion plus assistant text/function-call extraction. The Google package still owns the SDK request shape, function-call normalization, and response metadata normalization; the provider runtime supplies the adapter shell and default tool-round formatting.

Google content support maps image/file data to inlineData and URL-backed image/file parts to fileData when mediaType is present. URL-backed parts without a MIME type fail before the provider call. Assistant inline/file media decodes back into canonical content, and function-response media uses the same part table as messages.

GoogleCacheConfig:

GoogleCachedContentCachePort:

interface GoogleCachedContentCachePort {
  create(input: {
    model: string;
    systemInstruction: string;
    ttlSeconds: number;
  }): Promise<GoogleCacheName | undefined>;
  delete(input: { name: GoogleCacheName }): Promise<void>;
}

Returns:

import { createGoogle } from "@use-crux/google";
import { GoogleGenAI } from "@google/genai";

const adapter = createGoogle(
  new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY }),
);

const result = await adapter.generate(sentiment, {
  model: "gemini-2.5-flash",
  input: { text: "Great product!" },
});
result.text;
result.usage;
result.finalStep;

// Custom CachedContent configuration
const adapter = createGoogle(client, {
  cachedContent: { defaultTtlSeconds: 600, maxEntries: 100 },
});

// Surface cache failures instead of silently falling back
const strict = createGoogle(client, { cachedContent: { onError: "throw" } });

// Disable caching entirely
const adapter = createGoogle(client, { cachedContent: false });

// Back caching with a custom cache port, or pass a fully custom lifecycle
const custom = createGoogle(client, { cachedContent: { port: myCachePort } });

// Skip or tune cache lifecycle for one request
await adapter.generate(prompt, {
  model: "gemini-2.5-flash",
  extra: { cachedContent: { ttlSeconds: 600 } },
});

adapter.generate(prompt, options)

Returns: normalized Crux generate result with:

• result.text: extracted assistant text
• result.usage: accumulated usage when every provider-call step reported usage
• result.cost: provider-reported cost when available
• result.finalStep: final provider-call text, usage, finish reason, response id, and actual model id
• result.raw: raw Google SDK response
• result._meta: retained trace metadata for observability plumbing
• result.usage?.inputTokenDetails.cacheReadTokens: tokens served from cache when available

adapter.stream(prompt, options)

Stream a prompt execution.

Returns: StreamResult<TOutput, TPartial>:

• result.textStream: published, Safety-final text deltas
• result.fullStream: every published logical event in canonical order
• result.partialOutputStream: canonical partial z.input for a structured prompt
• result.completion: promise resolving to the canonical completion envelope (text, optional object, optional usage, optional cost, steps, finalStep, messages, and pending approvals)
• result.cancel(reason?): abort the whole logical operation, including the active provider attempt

There is deliberately no raw on a managed stream: a provider stream resolves before terminal Safety and describes only one attempt, so exposing it would bypass guardrail holds, structured occurrence gating, commit gates, and validation retry.

Media operations

Completed and streaming image, transcription, and speech behavior is documented separately in Google media operations. That page owns native endpoints, typed extra namespaces, model gates, terminal raw types, stream framing, and composed-transcription limits.

toParams(resolved, options) / fromResponse(response)

toParams() converts a ResolvedPrompt plus { model, settings?, extra? } into Google generateContent params. ResolvedPrompt does not include a model, so options.model is required. Pass cachedContentLifecycle when codec calls should use a Google CachedContent planner; otherwise the codec uses the inline disabled-cache fallback.

fromResponse() normalizes a Google response into Crux AdapterResponse facts. These codecs are translation-only. Use managed generate()/stream() when Crux should run tools, approvals, validation retry, memory capture, safety, and observability.

adapter.prepare(prompt, options)

Prepare a headless Google call. Crux resolves the prompt and returns public Google params without making the SDK call. Feed a raw GenerateContentResponse back with finish(response), or use step(response) when tools, validation retry, or approval suspension may need another provider turn.

generate(prompt, { ...options, transport }) is the BYO-wire mode where Crux keeps owning the loop and invokes your callback for each Google request. stream() with transport is intentionally unsupported and rejects with CruxTransportStreamUnsupportedError.

adapter.retrievalModel(config)

Create a core RetrievalModel from the adapter instance.

const retrievalModel = adapter.retrievalModel({ model: "gemini-2.5-flash" });

Use it as a recipe-level model or step-level model.

adapter.reranker(config)

Create a core Reranker for rerank({ engine }).

const engine = adapter.reranker({
  model: "gemini-2.5-flash",
  topN: 12,
});

Google's direct SDK adapter does not expose a native rerank endpoint. adapter.reranker() uses Crux's judgeReranker() over the configured Google model, so each rerank call spends generation tokens.

toMessages(sdkMessages)

Convert Google Content[] to canonical Message[].

Returns: Message[]

fromMessages(messages)

Convert canonical Message[] to Google Content[].

Returns: Content[]

Assistant tool calls become functionCall parts and tool results become functionResponse parts. When Google does not provide a tool-call id, the adapter synthesizes stable per-turn ids such as tc_0 for the Crux tool round.

googleTranscript is the lower-level NativeTranscriptCodec used by createGoogle(). The public toMessages() and fromMessages() wrappers delegate to it.

createGenerateObjectFn(client)

Create a provider-native GenerateObjectFn bound only to a client. Every call must supply a non-empty Google model id.

Returns: GenerateObjectFn

const generateObject = createGenerateObjectFn(client);
const { object } = await generateObject({
  model: "gemini-2.5-flash",
  messages,
  schema,
});

This helper uses the same native chat profile and media codec as createGoogle(). It accepts exactly one of prompt or canonical messages, uses Google GenAI structured JSON output, and returns { object } while preserving provider errors. It does not run Crux prompt resolution, validation retry, safety, tools, memory capture, or instrumentation.

createGenerateTextFn(client, model)

Create a GenerateTextFn bound to a client and model.

Returns: GenerateTextFn

embedding(client, config)

Create a dense Crux embedding backed by client.models.embedContent().

import { GoogleGenAI } from "@google/genai";
import { embedding } from "@use-crux/google";

const client = new GoogleGenAI({ apiKey: process.env.GOOGLE_API_KEY });

const docsEmbedding = embedding(client, {
  model: "gemini-embedding-2",
});

await docsEmbedding.embed("dog", { role: "query" });
await docsEmbedding.embed({ type: "image", source: dogPhoto });

Known literal model ids infer verified modality tuples. gemini-embedding-2 defaults to text, image, audio, video, and document inputs, the model id as its Crux name, 3072 dimensions, and an 8192-token text limit. Unknown or dynamic model ids conservatively default to text-only and require explicit sizing. Google's SDK returns token counts per embedded input when available, and the Crux helper aggregates them into embedding usage metadata automatically.

The helper fingerprint includes model, both role task types, title, MIME type, and auto-truncation behavior, then appends version when supplied. Operational batch settings do not change that identity. Gemini Embedding 2 does not accept taskType; put its text retrieval instruction in the input instead.

Types

import type {
  CreateGoogleOptions,
  GoogleCacheConfig,
  GoogleCacheName,
  GoogleCachedContentCachePort,
  GoogleCachedContentCallOptions,
  GoogleCachedContentErrorMode,
  GoogleCachedContentLifecycle,
  GoogleCachedContentOption,
  GoogleCachedContentPlan,
  GoogleCachedContentPrepareArgs,
  GoogleEmbeddingConfig,
  GoogleExtra,
  GoogleFunctionDeclaration,
  GoogleRequest,
} from "@use-crux/google";

Related

• Guide: Execution
• Guide: Embeddings
• Reference: Prompts
• Reference: @use-crux/ai (Vercel AI SDK)