@crux/google

Peer dependency: @google/genai

import { createGoogle, embedding, googleProviderRuntime, googleTranscript, toMessages, fromMessages } from '@crux/google'
import { createGenerateObjectFn, createGenerateTextFn } from '@crux/google'

createGoogle(client, opts?)

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

createGoogle() binds googleProviderRuntime.create(client, { cacheManager }) after resolving cache options. 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, response metadata normalization, and CachedContent manager; the provider runtime supplies the adapter shell and default tool-round formatting.

GoogleCacheConfig:

Returns:

import { createGoogle } from '@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._meta.usage

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

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

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

adapter.generate(prompt, options)

Returns: normalized Crux generate result with:

• result.text — extracted assistant text
• result.raw — raw Google SDK response
• result._meta — normalized usage, finish reason, tool calls, and model metadata
• result._meta.usage.cacheReadTokens — tokens served from cache when available

adapter.stream(prompt, options)

Stream a prompt execution.

Returns: Google GenAI stream.

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 @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 '@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,
  GoogleEmbeddingConfig,
  GoogleExtra,
  GoogleFunctionDeclaration,
  GoogleRequest,
} from '@crux/google'

Related

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