tessl/npm-google--genai

Google Gen AI JavaScript SDK for building applications powered by Gemini with content generation, image/video generation, function calling, caching, and real-time live sessions

Overview

Eval results

Files

Context Caching

Name: tessl/npm-google--genai
Author: tessl

The Caches module provides context caching functionality to improve efficiency and reduce costs by caching large context data that is reused across multiple requests.

Capabilities

create

Create a new cached content instance.

/**
 * Create cached content
 * @param params - Cache creation parameters
 * @returns Promise resolving to cached content
 */
function create(
  params: CreateCachedContentParameters
): Promise<CachedContent>;

interface CreateCachedContentParameters {
  /** Model name (e.g., 'gemini-2.0-flash-001') */
  model: string;
  /** Content to cache */
  contents: ContentListUnion;
  /** Cache configuration */
  config?: CachedContentConfig;
}

interface CachedContent {
  /** Cache name (unique identifier) */
  name?: string;
  /** Model name */
  model?: string;
  /** Creation timestamp */
  createTime?: string;
  /** Last update timestamp */
  updateTime?: string;
  /** Expiration timestamp */
  expireTime?: string;
  /** Time to live (e.g., '3600s') */
  ttl?: string;
  /** Cached contents */
  contents?: Content[];
  /** Tools in cache */
  tools?: Tool[];
  /** Tool configuration */
  toolConfig?: ToolConfig;
  /** System instruction in cache */
  systemInstruction?: Content;
}

Usage Examples:

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// Create cache with large document
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [
    {
      role: 'user',
      parts: [{
        text: 'Here is a large document...' // Large context
      }]
    }
  ],
  config: {
    ttl: '3600s' // Cache for 1 hour
  }
});

console.log('Cache created:', cache.name);

// Use cache in generation
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Summarize the document',
  config: {
    cachedContent: cache.name
  }
});

console.log(response.text);

list

List all cached contents with pagination.

/**
 * List cached contents
 * @param params - List parameters
 * @returns Promise resolving to pager of cached contents
 */
function list(
  params?: ListCachedContentsParameters
): Promise<Pager<CachedContent>>;

interface ListCachedContentsParameters {
  /** Page size */
  pageSize?: number;
  /** Page token for pagination */
  pageToken?: string;
}

Usage Examples:

// List all caches
const pager = await client.caches.list({
  pageSize: 10
});

for await (const cache of pager) {
  console.log(`Cache: ${cache.name}`);
  console.log(`  Model: ${cache.model}`);
  console.log(`  Expires: ${cache.expireTime}`);
}

// Manual pagination
const page1 = await client.caches.list({ pageSize: 5 });
console.log('First page:', page1.page);

if (page1.hasNextPage()) {
  const page2 = await page1.nextPage();
  console.log('Second page:', page2);
}

get

Retrieve a specific cached content by name.

/**
 * Get cached content by name
 * @param params - Get parameters
 * @returns Promise resolving to cached content
 */
function get(
  params: GetCachedContentParameters
): Promise<CachedContent>;

interface GetCachedContentParameters {
  /** Cache name */
  cachedContent: string;
}

Usage Examples:

// Get cache details
const cache = await client.caches.get({
  cachedContent: 'cachedContents/abc123'
});

console.log('Cache:', cache);
console.log('TTL:', cache.ttl);
console.log('Contents:', cache.contents);

update

Update cached content metadata (mainly TTL).

/**
 * Update cached content (TTL, etc.)
 * @param params - Update parameters
 * @returns Promise resolving to updated cached content
 */
function update(
  params: UpdateCachedContentParameters
): Promise<CachedContent>;

interface UpdateCachedContentParameters {
  /** Cache name */
  cachedContent: string;
  /** New time to live */
  ttl?: string;
}

Usage Examples:

// Extend cache TTL
const updated = await client.caches.update({
  cachedContent: 'cachedContents/abc123',
  ttl: '7200s' // Extend to 2 hours
});

console.log('New expiration:', updated.expireTime);

delete

Delete a cached content.

/**
 * Delete cached content
 * @param params - Delete parameters
 * @returns Promise resolving to deletion response
 */
function delete(
  params: DeleteCachedContentParameters
): Promise<DeleteCachedContentResponse>;

interface DeleteCachedContentParameters {
  /** Cache name */
  cachedContent: string;
}

interface DeleteCachedContentResponse {
  /** Empty response on success */
}

Usage Examples:

// Delete cache
await client.caches.delete({
  cachedContent: 'cachedContents/abc123'
});

console.log('Cache deleted');

Types

CachedContentConfig

Configuration for cache creation.

interface CachedContentConfig {
  /** Time to live (e.g., '3600s', '1h') */
  ttl?: string;
  /** Expiration time (absolute timestamp) */
  expireTime?: string;
  /** Display name for cache */
  displayName?: string;
  /** System instruction */
  systemInstruction?: Content | string;
  /** Tools to cache */
  tools?: ToolListUnion;
  /** Tool configuration */
  toolConfig?: ToolConfig;
}

Content

Cached content structure.

interface Content {
  /** List of content parts */
  parts?: Part[];
  /** Role ('user' or 'model') */
  role?: string;
}

interface Part {
  /** Text content */
  text?: string;
  /** Inline binary data */
  inlineData?: Blob;
  /** File reference */
  fileData?: FileData;
}

Complete Examples

Cache Large Document

import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';

const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// Read large document
const largeDocument = fs.readFileSync('./large_document.txt', 'utf-8');

// Create cache
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [{
    role: 'user',
    parts: [{ text: largeDocument }]
  }],
  config: {
    displayName: 'Large Document Cache',
    ttl: '7200s' // 2 hours
  }
});

console.log('Cache created:', cache.name);

// Use cache for multiple queries
const queries = [
  'Summarize the main points',
  'What are the key findings?',
  'Extract action items'
];

for (const query of queries) {
  const response = await client.models.generateContent({
    model: 'gemini-2.0-flash',
    contents: query,
    config: {
      cachedContent: cache.name
    }
  });

  console.log(`\nQuery: ${query}`);
  console.log(`Response: ${response.text}`);

  // Check token savings
  if (response.usageMetadata?.cachedContentTokenCount) {
    console.log(`Cached tokens: ${response.usageMetadata.cachedContentTokenCount}`);
  }
}

Cache with System Instructions and Tools

import { Type } from '@google/genai';

// Create cache with system instruction and tools
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [{
    role: 'user',
    parts: [{ text: 'Product catalog data...' }]
  }],
  config: {
    displayName: 'Product Catalog Cache',
    ttl: '3600s',
    systemInstruction: 'You are a product recommendation assistant.',
    tools: [{
      functionDeclarations: [{
        name: 'searchProducts',
        description: 'Search product catalog',
        parameters: {
          type: Type.OBJECT,
          properties: {
            query: { type: Type.STRING }
          }
        }
      }]
    }]
  }
});

// Use cache with tools
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Find laptops under $1000',
  config: {
    cachedContent: cache.name
  }
});

Manage Cache Lifecycle

// Create cache
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [{ role: 'user', parts: [{ text: 'Context data' }] }],
  config: {
    ttl: '1800s' // 30 minutes
  }
});

console.log('Cache created:', cache.name);
console.log('Expires at:', cache.expireTime);

// Use cache
const response1 = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Question 1',
  config: { cachedContent: cache.name }
});

// Check if still valid
const currentCache = await client.caches.get({
  cachedContent: cache.name!
});

console.log('Cache still valid:', new Date(currentCache.expireTime!) > new Date());

// Extend TTL if needed
if (new Date(currentCache.expireTime!) < new Date(Date.now() + 600000)) {
  const extended = await client.caches.update({
    cachedContent: cache.name!,
    ttl: '3600s'
  });
  console.log('Cache extended to:', extended.expireTime);
}

// Use more
const response2 = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Question 2',
  config: { cachedContent: cache.name }
});

// Clean up when done
await client.caches.delete({
  cachedContent: cache.name!
});

console.log('Cache deleted');

Cache Multiple Files

// Upload files first
const file1 = await client.files.upload({
  file: './document1.pdf',
  mimeType: 'application/pdf'
});

const file2 = await client.files.upload({
  file: './document2.pdf',
  mimeType: 'application/pdf'
});

// Create cache with multiple files
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [{
    role: 'user',
    parts: [
      { text: 'Analyze these documents:' },
      {
        fileData: {
          fileUri: file1.uri!,
          mimeType: 'application/pdf'
        }
      },
      {
        fileData: {
          fileUri: file2.uri!,
          mimeType: 'application/pdf'
        }
      }
    ]
  }],
  config: {
    displayName: 'Multi-Document Cache',
    ttl: '7200s'
  }
});

// Query across cached documents
const response = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Compare the two documents',
  config: {
    cachedContent: cache.name
  }
});

List and Clean Up Old Caches

// List all caches
const caches = await client.caches.list();

const now = new Date();

for await (const cache of caches) {
  const expireTime = new Date(cache.expireTime!);

  console.log(`Cache: ${cache.name}`);
  console.log(`  Expires: ${cache.expireTime}`);

  // Delete expired or soon-to-expire caches
  if (expireTime < new Date(now.getTime() + 300000)) { // 5 minutes
    console.log('  Deleting...');
    await client.caches.delete({
      cachedContent: cache.name!
    });
  }
}

Token Usage with Caching

const largeContext = 'Large document content...'; // 10000+ tokens

// Create cache
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [{ role: 'user', parts: [{ text: largeContext }] }],
  config: { ttl: '3600s' }
});

// First request without cache
const response1 = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: [
    { role: 'user', parts: [{ text: largeContext }] },
    { role: 'user', parts: [{ text: 'Question?' }] }
  ]
});

console.log('Without cache:');
console.log('  Prompt tokens:', response1.usageMetadata?.promptTokenCount);

// Second request with cache
const response2 = await client.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: 'Question?',
  config: { cachedContent: cache.name }
});

console.log('With cache:');
console.log('  Prompt tokens:', response2.usageMetadata?.promptTokenCount);
console.log('  Cached tokens:', response2.usageMetadata?.cachedContentTokenCount);

// Token savings
const savings = (response1.usageMetadata?.promptTokenCount || 0) -
                (response2.usageMetadata?.promptTokenCount || 0);
console.log('Token savings:', savings);

Cache for Chat Sessions

// Create cache with conversation context
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [
    { role: 'user', parts: [{ text: 'Background context...' }] },
    { role: 'model', parts: [{ text: 'I understand the context.' }] }
  ],
  config: {
    displayName: 'Conversation Context',
    ttl: '1800s',
    systemInstruction: 'You are a helpful assistant with this context.'
  }
});

// Create chat using cached context
const chat = client.chats.create({
  model: 'gemini-2.0-flash',
  config: {
    cachedContent: cache.name
  }
});

// Chat benefits from cached context
const r1 = await chat.sendMessage({ message: 'Question 1?' });
const r2 = await chat.sendMessage({ message: 'Question 2?' });

console.log('Chat responses use cached context');

Error Handling

try {
  // Create cache
  const cache = await client.caches.create({
    model: 'gemini-2.0-flash-001',
    contents: [{ role: 'user', parts: [{ text: 'Context' }] }],
    config: { ttl: '3600s' }
  });

  // Use cache
  const response = await client.models.generateContent({
    model: 'gemini-2.0-flash',
    contents: 'Query',
    config: { cachedContent: cache.name }
  });

  console.log(response.text);
} catch (error) {
  if (error.status === 404) {
    console.error('Cache not found or expired');
  } else if (error.status === 400) {
    console.error('Invalid cache configuration');
  } else {
    console.error('Cache error:', error);
  }
}

Batch Operations with Shared Cache

// Create shared cache for batch processing
const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [{
    role: 'user',
    parts: [{ text: 'Reference documentation...' }]
  }],
  config: {
    displayName: 'Batch Processing Cache',
    ttl: '7200s'
  }
});

// Process multiple items using shared cache
const items = ['Item 1', 'Item 2', 'Item 3', 'Item 4'];

const results = await Promise.all(
  items.map(item =>
    client.models.generateContent({
      model: 'gemini-2.0-flash',
      contents: `Process: ${item}`,
      config: { cachedContent: cache.name }
    })
  )
);

results.forEach((result, index) => {
  console.log(`Result ${index + 1}:`, result.text);
  console.log(`  Cached tokens: ${result.usageMetadata?.cachedContentTokenCount}`);
});

// Clean up
await client.caches.delete({ cachedContent: cache.name! });

Using expireTime Instead of TTL

// Set absolute expiration time
const expirationDate = new Date();
expirationDate.setHours(expirationDate.getHours() + 2);

const cache = await client.caches.create({
  model: 'gemini-2.0-flash-001',
  contents: [{ role: 'user', parts: [{ text: 'Context' }] }],
  config: {
    expireTime: expirationDate.toISOString()
  }
});

console.log('Cache expires at:', cache.expireTime);

Install with Tessl CLI