@use-crux/google

Google message content supports native image, audio, video, and documents. Specialized exports include Imagen/Gemini-native generateImage(), native Gemini generateSpeech() (including two-speaker configuration), 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.

Peer dependency: @google/genai (^1.0.0 || ^2.0.0)

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

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<TRawStream>:

• result.textStream: provider-neutral text deltas
• result.raw: raw Google GenAI stream
• result.completion: promise resolving to the canonical completion envelope (text, optional usage, optional cost, steps, finalStep, messages, and pending approvals)

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, model)

Create a GenerateObjectFn bound to a client and model.

Returns: GenerateObjectFn

This is a provider-native helper. It uses Google GenAI structured JSON output and returns the parsed { object }, preserving provider errors. It does not run Crux prompt resolution, validation retry, safety, cassettes, tools, memory capture, or instrumentation. Use createGenerateObjectFnFromGenerate(generate) from @use-crux/core/compaction when a GenerateObjectFn needs full adapter runtime behavior.

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, {
  name: "docs-embedding",
  model: "text-embedding-004",
  dimensions: 768,
  maxInputTokens: 2048,
  taskType: "RETRIEVAL_DOCUMENT",
});

This helper is dense-only. Google's SDK returns token counts per embedded input when available, and the Crux helper aggregates them into embedding usage metadata automatically.

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)