npm package: @openpets/google-gemini
Description: Google Gemini AI provider for OpenCode
Latest version: 1.0.1

# Google Gemini AI Provider

Google Gemini AI client for OpenCode plugins, extending the BaseAIClient architecture.

## Features

- **Provider-Agnostic Tools**: Automatically selects between Google Gemini and FAL AI based on available API keys
- **Single Tool Architecture**: Import ready-to-use tools that handle provider selection
- Text-to-image generation with automatic provider fallback
- Image-to-image transformations (FAL AI)
- Text-to-video generation (FAL AI)
- Built-in error handling and logging
- Cross-platform media viewing support

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Get API Key

Get your Google API key from [Google AI Studio](https://makersuite.google.com/app/apikey)

### 3. Configure Environment

```bash
GOOGLE_API_KEY=your_google_api_key_here
```

## Usage

### Option 1: Direct Tool Import (Recommended)

Import the tools directly from this self-contained plugin:

```typescript
import {
  createGeminiTextToImageTool,
  createGeminiImageToImageTool,
  createGeminiTextToVideoTool
} from "pets/google-gemini"
import { createPlugin } from "@/core/plugin-factory"

export const MyPlugin = async () => {
  const tools = [
    createGeminiTextToImageTool(),
    createGeminiImageToImageTool(),
    createGeminiTextToVideoTool()
  ]

  return createPlugin(tools)
}
```

**Benefits:**
- Self-contained plugin with all dependencies
- No external utility dependencies
- Factory-based architecture
- Type-safe with Zod schemas
- Works out of the box

### Option 2: Direct Client Usage

For more control, use the client directly:

```typescript
import { createGoogleGeminiClient } from "pets/google-gemini"

const client = createGoogleGeminiClient()

const result = await client.generateImage({
  prompt: "A serene mountain landscape at sunset",
  aspect_ratio: "16:9",
  num_images: 1
})
```

### Option 3: As MCP Server Plugin

Use this plugin in an MCP server:

```typescript
import { createGeminiTextToImageTool } from "pets/google-gemini"

const tools = [createGeminiTextToImageTool()]
export default createPlugin(tools)
```

## Configuration Options

### Image Generation

```typescript
interface GeminiImageGenerationOptions {
  prompt: string                  // Required: Image description
  model?: string                  // Model to use (default: gemini-2.0-flash-exp)
  num_images?: number             // Number of images (default: 1)
  aspect_ratio?: string           // 1:1, 16:9, 9:16, 4:3, 3:4
  negative_prompt?: string        // What to avoid in the image
}
```

### Supported Aspect Ratios

- `1:1` or `square` - Square images
- `16:9` or `landscape` - Landscape widescreen
- `9:16` or `portrait` - Portrait vertical
- `4:3` - Standard landscape
- `3:4` - Standard portrait

## API Methods

### `generateImage(options)`

Generate an image from text description.

**Returns:** `AIImageResult`

```typescript
{
  success: boolean
  images?: AIImageData[]
  error?: string
  metadata?: AIGenerationMetadata
}
```

### `generateAndOpenImage(options, openInViewer)`

Generate and automatically open the image in your default viewer.

**Parameters:**
- `options`: GeminiImageGenerationOptions
- `openInViewer`: boolean (default: true)

**Returns:** `AIImageResult & { localPath?: string }`

## Integration with Plugins

The Google Gemini client extends `BaseAIClient` and follows the same interface as other AI providers:

```typescript
import { createGoogleGeminiClient } from "pets/google-gemini"

const geminiClient = createGoogleGeminiClient()

const result = await geminiClient.generateAndOpenImage({
  prompt: args.prompt,
  aspect_ratio: args.aspect_ratio,
  num_images: args.num_images
}, args.open_in_viewer)
```

## Important Notes

⚠️ **Current Limitations:**

1. **Image Generation**: Gemini 2.0 Flash currently focuses on text generation. For actual image generation, Google offers:
   - **Imagen 3** through Vertex AI
   - **Gemini Pro Vision** for image understanding

2. **Video Generation**: Not yet supported by the Gemini API

3. **API Evolution**: This integration is prepared for future image generation capabilities as Google expands Gemini's multimodal features.

## Error Handling

The client includes comprehensive error handling:

```typescript
try {
  const result = await client.generateImage(options)

  if (!result.success) {
    console.error("Generation failed:", result.error)
  }
} catch (error) {
  console.error("Client error:", error.message)
}
```

## Architecture

### Self-Contained Plugin Design

This plugin follows the OpenPets factory-based architecture pattern where all functionality is contained within the plugin itself:

```
pets/google-gemini/
├── index.ts              # Main plugin with client and tools
├── package.json         # Plugin dependencies
├── .env.example         # Configuration template
└── README.md           # This file
```

### Key Design Principles

1. **Factory Pattern**: Uses `createSingleTool()` from `@/core/plugin-factory` for consistent tool creation
2. **Self-Sufficient**: No dependencies on `src/utils/` - everything needed is in the plugin
3. **Type-Safe**: Zod schemas for all tool parameters
4. **Provider Integration**: Extends `BaseAIClient` for consistent AI provider interface
5. **Future-Ready**: Prepared for Imagen 3 and video generation capabilities

### Class Hierarchy

```
BaseAIClient (abstract)
  └── GoogleGeminiClient
```

### Provider Name

The client uses `"google-gemini"` as its provider identifier, used for:
- Logging and debugging
- Output file naming
- Provider tracking in results

### Migration from Utils

This plugin was previously located in `src/utils/google-gemini/`. It has been migrated to be fully self-contained following the pet-creator pattern:

- ✅ All client logic moved from `src/utils/google-gemini/` to `pets/google-gemini/`
- ✅ Dependencies added to plugin's `package.json`
- ✅ Plugin is now independent and can be used without external utilities
- ✅ Uses factory pattern with `createSingleTool()` for tool creation

## Development

### Running Tests

```bash
npm test
```

### Debugging

Enable debug mode:

```typescript
const client = new GoogleGeminiClient(apiKey)
client.debug = true
```

## Single Tool Functions

The provider exports ready-to-use single tool creation functions:

### `createGeminiTextToImageTool()`
- ✅ **Available**: Uses Gemini 2.0 Flash for prompt enhancement
- Generates detailed image descriptions and prompts
- Perfect for brainstorming and refining concepts

### `createGeminiImageToImageTool()`
- ❌ **Not Yet Available**: Placeholder for future Imagen 3 support
- Will enable image transformations and variations
- Currently returns error with helpful message

### `createGeminiTextToVideoTool()`
- ❌ **Not Yet Available**: Placeholder for future video capabilities
- Will enable video generation from text
- Currently returns error with helpful message

**Import Example:**
```typescript
import { createGeminiTextToImageTool, createGoogleGeminiClient } from "pets/google-gemini"

const tool = createGeminiTextToImageTool()

const client = createGoogleGeminiClient()
```

## Complete File Structure

```
pets/google-gemini/
├── index.ts                    # GoogleGeminiClient class + tool creation functions
├── package.json               # Dependencies (@google/generative-ai, zod)
├── tsconfig.json
└── README.md                  # This file
```

## Future Enhancements

- [ ] Integration with Imagen 3 for actual image generation
- [ ] Support for image editing and variations
- [ ] Video generation when API supports it
- [ ] Advanced prompting features
- [ ] Style transfer capabilities

**Note**: Placeholder tools (`image-to-image`, `text-to-video`) are included to maintain API consistency and will automatically work when Google adds these capabilities.

## Resources

- [Google AI Studio](https://makersuite.google.com/)
- [Gemini API Documentation](https://ai.google.dev/gemini-api/docs)
- [API Reference](https://ai.google.dev/api)

## License

MIT