@memberjunction/ai-gemini NPM

@memberjunction/ai-gemini

A comprehensive wrapper for Google's Gemini AI models that seamlessly integrates with the MemberJunction AI framework, providing access to Google's powerful generative AI capabilities.

Features

Google Gemini Integration: Connect to Google's state-of-the-art Gemini models using the official @google/genai SDK
Standardized Interface: Implements MemberJunction's BaseLLM abstract class
Streaming Support: Full support for streaming responses with real-time token generation
Multimodal Support: Handle text, images, audio, video, and file content
Message Formatting: Automatic conversion between MemberJunction and Gemini message formats
Effort Level Support: Leverage Gemini's reasoning mode for higher-quality responses
Error Handling: Robust error handling with detailed reporting
Chat Support: Full support for chat-based interactions with conversation history
Temperature Control: Fine-tune generation creativity
Response Format Control: Request specific response MIME types

Installation

npm install @memberjunction/ai-gemini

Requirements

Node.js 16+
A Google AI Studio API key
MemberJunction Core libraries

Usage

Basic Setup

import { GeminiLLM } from '@memberjunction/ai-gemini';

// Initialize with your Google AI API key
const geminiLLM = new GeminiLLM('your-google-ai-api-key');

Chat Completion

import { ChatParams } from '@memberjunction/ai';

// Create chat parameters
const chatParams: ChatParams = {
  model: 'gemini-pro',  // or 'gemini-pro-vision' for multimodal
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What are the key features of the Gemini AI model?' }
  ],
  temperature: 0.7,
  maxOutputTokens: 1000
};

// Get a response
try {
  const response = await geminiLLM.ChatCompletion(chatParams);
  if (response.success) {
    console.log('Response:', response.data.choices[0].message.content);
    console.log('Time elapsed:', response.timeElapsed, 'ms');
  } else {
    console.error('Error:', response.errorMessage);
  }
} catch (error) {
  console.error('Exception:', error);
}

Streaming Chat Completion

import { StreamingChatCallbacks } from '@memberjunction/ai';

// Define streaming callbacks
const streamCallbacks: StreamingChatCallbacks = {
  onToken: (token: string) => {
    process.stdout.write(token); // Print each token as it arrives
  },
  onComplete: (fullResponse: string) => {
    console.log('\n\nComplete response received');
  },
  onError: (error: Error) => {
    console.error('Streaming error:', error);
  }
};

// Use streaming
const streamParams: ChatParams = {
  model: 'gemini-pro',
  messages: [
    { role: 'user', content: 'Write a short story about a robot.' }
  ],
  streaming: true,
  streamingCallbacks: streamCallbacks
};

await geminiLLM.ChatCompletion(streamParams);

Multimodal Content

import { ChatMessageContent } from '@memberjunction/ai';

// Create multimodal content
const multimodalContent: ChatMessageContent = [
  { type: 'text', content: 'What do you see in this image?' },
  { type: 'image_url', content: 'base64_encoded_image_data_here' }
];

const multimodalParams: ChatParams = {
  model: 'gemini-pro-vision',
  messages: [
    { role: 'user', content: multimodalContent }
  ]
};

const response = await geminiLLM.ChatCompletion(multimodalParams);

Enhanced Reasoning with Effort Level

// Use effort level to enable Gemini's full reasoning mode
const reasoningParams: ChatParams = {
  model: 'gemini-pro',
  messages: [
    { role: 'user', content: 'Solve this complex logic puzzle...' }
  ],
  effortLevel: 'high' // Enables full reasoning mode
};

const response = await geminiLLM.ChatCompletion(reasoningParams);

Direct Access to Gemini Client

// Access the underlying GoogleGenAI client for advanced usage
const geminiClient = geminiLLM.GeminiClient;

// Use the client directly if needed for custom operations
const chat = geminiClient.chats.create({
  model: 'gemini-pro',
  history: []
});

Supported Models

Google Gemini provides several models with different capabilities:

gemini-pro: General-purpose text model
gemini-pro-vision: Multimodal model that can process images and text
gemini-ultra: Google's most advanced model (when available)

Check the Google AI documentation for the latest list of supported models.

API Reference

GeminiLLM Class

A class that extends BaseLLM to provide Google Gemini-specific functionality.

Constructor

new GeminiLLM(apiKey: string)

Creates a new instance of the Gemini LLM wrapper.

Parameters:

apiKey: Your Google AI Studio API key

Properties

GeminiClient: (read-only) Returns the underlying GoogleGenAI client instance
SupportsStreaming: (read-only) Returns true - Gemini supports streaming responses

Methods

ChatCompletion(params: ChatParams): Promise

Perform a chat completion with Gemini models.

Parameters:

params: Chat parameters including model, messages, temperature, etc.

Returns:

Promise resolving to a ChatResult with the model's response

SummarizeText(params: SummarizeParams): Promise

Not implemented yet - will throw an error if called.

ClassifyText(params: ClassifyParams): Promise

Not implemented yet - will throw an error if called.

Static Methods

MapMJMessageToGeminiHistoryEntry(message: ChatMessage): Content

Converts a MemberJunction ChatMessage to Gemini's Content format.

Parameters:

message: MemberJunction ChatMessage object

Returns:

Gemini Content object with proper role mapping

MapMJContentToGeminiParts(content: ChatMessageContent): Array

Converts MemberJunction message content to Gemini Parts array.

Parameters:

content: String or array of content parts

Returns:

Array of Gemini Part objects

Response Format Control

Control the format of Gemini responses using the responseFormat parameter:

const params: ChatParams = {
  // ...other parameters
  responseFormat: 'text/plain',  // Regular text response
};

// For structured data
const jsonParams: ChatParams = {
  // ...other parameters
  responseFormat: 'application/json',  // Request JSON response
};

Error Handling

The wrapper provides detailed error information:

try {
  const response = await geminiLLM.ChatCompletion(params);
  if (!response.success) {
    console.error('Error:', response.errorMessage);
    console.error('Status:', response.statusText);
    console.error('Exception:', response.exception);
  }
} catch (error) {
  console.error('Exception occurred:', error);
}

Message Handling

The wrapper handles proper message formatting and role conversion between MemberJunction's format and Google Gemini's expected format:

MemberJunction's system and user roles are converted to Gemini's user role
MemberJunction's assistant role is converted to Gemini's model role
Messages are automatically spaced to ensure alternating roles as required by Gemini
Multimodal content is properly converted with appropriate MIME types

Content Type Support

The wrapper supports various content types with automatic MIME type mapping:

Text: Standard text messages
Images: image_url type → image/jpeg MIME type
Audio: audio_url type → audio/mpeg MIME type
Video: video_url type → video/mp4 MIME type
Files: file_url type → application/octet-stream MIME type

Integration with MemberJunction

This package is designed to work seamlessly with the MemberJunction AI framework:

import { AIEngine } from '@memberjunction/ai';
import { GeminiLLM } from '@memberjunction/ai-gemini';

// Register the Gemini provider with the AI engine
const aiEngine = new AIEngine();
const geminiProvider = new GeminiLLM('your-api-key');

// Use through the AI engine's unified interface
const result = await aiEngine.ChatCompletion({
  provider: 'GeminiLLM',
  model: 'gemini-pro',
  messages: [/* ... */]
});

Performance Considerations

Streaming: Use streaming for long responses to improve perceived performance
Effort Level: Use the effortLevel parameter judiciously as it increases latency and cost
Model Selection: Choose the appropriate model based on your needs (text-only vs multimodal)
Message Spacing: The wrapper automatically handles message spacing, adding minimal overhead