# @standardagents/google

Google Gemini and Imagen provider for Standard Agents.

This package exports a Standard Agents provider factory for Google's Gemini chat/multimodal models and Imagen image models. It handles:

- model discovery via the Google model list API
- Standard Agents message and tool translation to Google `generateContent` requests
- Gemini text, JSON, tools, and multimodal inputs
- Imagen generation and image-edit style requests
- usage and cost calculation from Google usage metadata

## Install

```bash
npm install @standardagents/google @standardagents/spec
```

## Usage

```ts
import { google } from '@standardagents/google';

const provider = google({
  apiKey: process.env.GOOGLE_API_KEY!,
});

const result = await provider.generate({
  model: 'gemini-2.5-flash',
  messages: [
    {
      role: 'user',
      content: 'Write a one sentence summary of Saturn.',
    },
  ],
});

console.log(result.content);
console.log(result.usage?.cost);
```

## Factory

The package exports:

- `google(config)` - provider factory
- `GoogleProvider` - provider class
- `googleProviderOptions` - Zod schema for provider-specific options
- pricing helpers from `@standardagents/google/pricing`

Factory config follows `ProviderFactoryConfig` from `@standardagents/spec`:

```ts
type ProviderFactoryConfig = {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
};
```

## Supported Features

The provider exposes capabilities per model where available. In practice:

- Gemini models support text generation, streaming, tool calling, and multimodal input
- Gemma hosted models support text and selected multimodal inputs, with more limited tool support
- Imagen models support image generation/edit-style requests and are handled as non-streaming image models

Use `getModels()` and `getModelCapabilities()` to inspect the currently available surface:

```ts
const models = await provider.getModels?.();
const capabilities = await provider.getModelCapabilities?.('gemini-2.5-pro');
```

## Provider Options

This package validates Google-specific provider options through `google.providerOptions`.

Common options:

- `candidateCount`
- `responseModalities`
- `safetySettings`
- `thinkingConfig`
- `imageConfig`
- `numberOfImages`
- `aspectRatio`
- `negativePrompt`
- `guidanceScale`
- `outputMimeType`
- `language`
- `editMode`

Example:

```ts
const result = await provider.generate({
  model: 'gemini-2.5-pro',
  messages: [
    { role: 'user', content: 'Return valid JSON with a title and summary.' },
  ],
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: {
        title: { type: 'string' },
        summary: { type: 'string' },
      },
      required: ['title', 'summary'],
    },
  },
  providerOptions: {
    candidateCount: 1,
    safetySettings: [
      { category: 'HARM_CATEGORY_HARASSMENT', threshold: 'BLOCK_ONLY_HIGH' },
    ],
  },
});
```

## Images

For multimodal Gemini requests, pass Standard Agents image parts or image attachments and the provider will translate them to Google inline parts. For Imagen requests, the provider will route through the image generation path automatically when the target model is an Imagen model.

For tool results with image attachments, the provider keeps the internal Standard Agents message shape unchanged and applies a Google-only request transform at send time:

- Gemini 3 series models keep image data nested inside `functionResponse.parts`
- Older Google chat models receive a text-only `functionResponse`, with image attachments lifted into sibling inline image parts so the request remains accepted by those models

## Debugging

Use `inspectRequest()` to view the transformed Google-native request body:

```ts
const inspected = await provider.inspectRequest?.({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: 'hello' }],
});

console.log(inspected?.body);
```

## Notes

- Model IDs are normalized so variants like `google/...`, `models/...`, and `publishers/google/models/...` resolve to the same pricing and capability entries where possible.
- Cost is computed from Google usage metadata and pricing tables when available; Google does not currently return a direct monetary cost field for Gemini requests.
- The same pricing helpers are exported from the package root and the pure `@standardagents/google/pricing` subpath for consumers that need identical cost math without importing provider runtime code.
- Gemini thought signatures attached to tool-call parts are preserved through Standard Agents history so multi-step Google tool calling can continue across turns.