viho-llm 0.1.5 → 0.1.6

package/README.md

@@ -1,6 +1,10 @@
-# viho-llm
+<p align="center">
+  <img src="https://static-small.vincentqiao.com/viho/logo.png" alt="viho logo" width="200"/>
+</p>
 
-Utility library for working with Google Gemini AI, providing common tools and helpers for AI interactions.
+<h1 align="center">viho-llm</h1>
+
+<p align="center">Utility library for working with Google Gemini AI, providing common tools and helpers for AI interactions.</p>
 
 ## Installation
 
@@ -10,17 +14,26 @@ npm install viho-llm
 
 ## Prerequisites
 
-You need to have a Google AI API key. Get one from [Google AI Studio](https://makersuite.google.com/app/apikey).
+This library supports two ways to access Google Gemini AI:
+
+1. **Google AI Studio (GeminiAPI)** - For personal development and prototyping
+   - Get an API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
+
+2. **Vertex AI (GeminiVertex)** - For enterprise applications with advanced features
+   - Requires a Google Cloud project with Vertex AI enabled
+   - Supports context caching for cost optimization
 
 ## Usage
 
-### Basic Example
+### Basic Example with GeminiAPI
+
+Using Google AI Studio API Key (recommended for development):
 
 ```javascript
-import { Gemini } from 'viho-llm';
+import { GeminiAPI } from 'viho-llm';
 
-// Initialize Gemini client
-const gemini = Gemini({
+// Initialize Gemini client with API Key
+const gemini = GeminiAPI({
   apiKey: 'your-google-api-key',
   modelName: 'gemini-pro',
 });
@@ -38,17 +51,38 @@ const response = await gemini.chat({
 console.log(response);
 ```
 
-### Streaming Example
+### Basic Example with GeminiVertex
+
+Using Vertex AI (recommended for production):
 
 ```javascript
-import { Gemini } from 'viho-llm';
+import { GeminiVertex } from 'viho-llm';
 
-// Initialize Gemini client
-const gemini = Gemini({
-  apiKey: 'your-google-api-key',
+// Initialize Gemini client with Vertex AI
+const gemini = GeminiVertex({
+  projectId: 'your-gcp-project-id',
+  location: 'us-east1',
   modelName: 'gemini-pro',
 });
 
+// Send a chat message
+const response = await gemini.chat({
+  contents: [
+    {
+      role: 'user',
+      parts: [{ text: 'Hello, how are you?' }],
+    },
+  ],
+});
+
+console.log(response);
+```
+
+### Streaming Example
+
+Both GeminiAPI and GeminiVertex support streaming responses:
+
+```javascript
 // Send a chat message with streaming
 await gemini.chatWithStreaming(
   {
@@ -79,11 +113,44 @@ await gemini.chatWithStreaming(
 );
 ```
 
+### Context Caching Example (Vertex AI Only)
+
+GeminiVertex supports context caching to reduce costs and latency when using large contexts:
+
+```javascript
+import { GeminiVertex } from 'viho-llm';
+
+const gemini = GeminiVertex({
+  projectId: 'your-gcp-project-id',
+  location: 'us-east1',
+  modelName: 'gemini-1.5-flash-002',
+});
+
+// Add a new cache
+const cache = await gemini.cacheAdd({
+  gsPath: 'gs://your-bucket/large-document.pdf',
+  systemPrompt: 'You are an expert at analyzing technical documents.',
+  cacheName: 'my-document-cache',
+  cacheTTL: '3600s', // 1 hour
+});
+
+console.log('Cache created:', cache.name);
+
+// List all caches
+const caches = await gemini.cacheList();
+console.log('Available caches:', caches);
+
+// Update cache TTL
+await gemini.cacheUpdate(cache.name, {
+  ttl: '7200s', // Extend to 2 hours
+});
+```
+
 ## API Reference
 
-### `Gemini(options)`
+### `GeminiAPI(options)`
 
-Creates a new Gemini client instance.
+Creates a new Gemini client instance using Google AI Studio API.
 
 #### Parameters
 
@@ -172,6 +239,98 @@ await gemini.chatWithStreaming(
 );
 ```
 
+---
+
+### `GeminiVertex(options)`
+
+Creates a new Gemini client instance using Vertex AI. Includes all features of GeminiAPI plus context caching support.
+
+#### Parameters
+
+- `options` (Object) - Configuration options
+  - `projectId` (string) **required** - Your Google Cloud project ID
+  - `location` (string) **required** - GCP region (e.g., 'us-east1', 'us-central1')
+  - `modelName` (string) **required** - Model name (e.g., 'gemini-1.5-flash-002', 'gemini-1.5-pro-002')
+
+#### Returns
+
+Returns a Gemini client object with the following methods:
+
+##### `client.chat(chatOptions)`
+
+Same as GeminiAPI.chat(). See above for details.
+
+##### `client.chatWithStreaming(chatOptions, callbackOptions)`
+
+Same as GeminiAPI.chatWithStreaming(). See above for details.
+
+##### `client.cacheAdd(cacheOptions)`
+
+Creates a new context cache for frequently used content.
+
+**Parameters:**
+
+- `cacheOptions` (Object)
+  - `gsPath` (string) **required** - Google Cloud Storage path (e.g., 'gs://bucket/file.pdf')
+  - `systemPrompt` (string) **required** - System instruction for the cached context
+  - `cacheName` (string) **required** - Display name for the cache
+  - `cacheTTL` (string) **required** - Time-to-live (e.g., '3600s' for 1 hour)
+
+**Returns:**
+
+- (Promise\<Object\>) - Cache object with name and metadata
+
+**Example:**
+
+```javascript
+const cache = await gemini.cacheAdd({
+  gsPath: 'gs://my-bucket/documentation.pdf',
+  systemPrompt: 'You are a helpful documentation assistant.',
+  cacheName: 'docs-cache',
+  cacheTTL: '3600s',
+});
+```
+
+##### `client.cacheList()`
+
+Lists all available caches in the project.
+
+**Parameters:** None
+
+**Returns:**
+
+- (Promise\<Array\>) - Array of cache objects with `name` and `displayName` properties
+
+**Example:**
+
+```javascript
+const caches = await gemini.cacheList();
+console.log(caches);
+// [{ name: 'projects/.../cachedContents/...', displayName: 'docs-cache' }]
+```
+
+##### `client.cacheUpdate(cacheName, cacheOptions)`
+
+Updates an existing cache configuration.
+
+**Parameters:**
+
+- `cacheName` (string) **required** - The cache name to update
+- `cacheOptions` (Object) **required** - Update configuration
+  - `ttl` (string) - New time-to-live value (e.g., '7200s')
+
+**Returns:**
+
+- (Promise\<Object\>) - Updated cache object
+
+**Example:**
+
+```javascript
+await gemini.cacheUpdate('projects/.../cachedContents/abc123', {
+  ttl: '7200s', // Extend to 2 hours
+});
+```
+
 ## License
 
 MIT

package/index.js

@@ -36,10 +36,16 @@ const chat = async (client, modelName, chatOptions) => {
   }
 
   try {
-    const response = await client.models.generateContent({
-      model: modelName,
-      contents: chatOptions.contents,
-    });
+    // options
+    const options = Object.assign(
+      {
+        model: modelName,
+      },
+      chatOptions,
+    );
+
+    // gen
+    const response = await client.models.generateContent(options);
     if (!response || !response.text) {
       logger$2.error(methodName, 'invalid response');
       return;
@@ -92,11 +98,19 @@ const chatWithStreaming = async (client, modelName, chatOptions, callbackOptions
   const firstContentCallback = callbackOptions.firstContentCallback;
 
   try {
+    // begin
     if (beginCallback) beginCallback();
-    const response = await client.models.generateContentStream({
-      model: modelName,
-      contents: chatOptions.contents,
-    });
+
+    // options
+    const options = Object.assign(
+      {
+        model: modelName,
+      },
+      chatOptions,
+    );
+
+    // gen
+    const response = await client.models.generateContentStream(options);
 
     // go
     let firstContent = true;
@@ -131,6 +145,14 @@ const cacheAdd = async (client, modelName, cacheOptions) => {
   const methodName = 'cacheAdd';
 
   // check
+  if (!client) {
+    logger$2.error(methodName, 'need client');
+    return;
+  }
+  if (!modelName) {
+    logger$2.error(methodName, 'need modelName');
+    return;
+  }
   if (!cacheOptions) {
     logger$2.error(methodName, 'need cacheOptions');
     return;
@@ -175,6 +197,71 @@ const cacheAdd = async (client, modelName, cacheOptions) => {
   }
 };
 
+/**
+ * cacheList
+ * @param {*} client
+ * @returns
+ */
+const cacheList = async (client) => {
+  const methodName = 'cacheList';
+
+  // check
+  if (!client) {
+    logger$2.error(methodName, 'need client');
+    return;
+  }
+
+  // cache list
+  try {
+    const cacheList = await client.caches.list();
+    const cacheObjs = cacheList?.pageInternal?.map((contentCache) => ({
+      name: contentCache.name,
+      displayName: contentCache.displayName,
+    }));
+
+    return cacheObjs;
+  } catch (error) {
+    logger$2.error(methodName, 'error', error);
+  }
+};
+
+/**
+ * cacheUpdate
+ * @param {*} client
+ * @param {*} cacheName
+ * @param {*} cacheOptions
+ * @returns
+ */
+const cacheUpdate = async (client, cacheName, cacheOptions) => {
+  const methodName = 'cacheUpdate';
+
+  // check
+  if (!client) {
+    logger$2.error(methodName, 'need client');
+    return;
+  }
+  if (!cacheName) {
+    logger$2.error(methodName, 'need cacheName');
+    return;
+  }
+  if (!cacheOptions) {
+    logger$2.error(methodName, 'need cacheOptions');
+    return;
+  }
+
+  // cache update
+  try {
+    const res = await client.caches.update({
+      name: cacheName,
+      config: cacheOptions,
+    });
+
+    return res;
+  } catch (error) {
+    logger$2.error(methodName, 'error', error);
+  }
+};
+
 // gemini
 const logger$1 = qiao_log_js.Logger('gemini-api.js');
 
@@ -267,6 +354,12 @@ const GeminiVertex = (options) => {
   gemini.cacheAdd = async (cacheOptions) => {
     return await cacheAdd(gemini.client, options.modelName, cacheOptions);
   };
+  gemini.cacheList = async () => {
+    return await cacheList(gemini.client);
+  };
+  gemini.cacheUpdate = async (cacheName, cacheOptions) => {
+    return await cacheUpdate(gemini.client, cacheName, cacheOptions);
+  };
 
   // r
   return gemini;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viho-llm",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Utility library for working with Google Gemini AI, providing common tools and helpers for AI interactions",
   "keywords": [
     "llm",
@@ -61,5 +61,5 @@
       }
     }
   },
-  "gitHead": "b37b523239fe354f991017387e95a6314e994981"
+  "gitHead": "d77d2ba692eac3cd5262f55ade7cf74b84172385"
 }

package/src/models/gemini-util.js

@@ -37,10 +37,16 @@ export const chat = async (client, modelName, chatOptions) => {
   }
 
   try {
-    const response = await client.models.generateContent({
-      model: modelName,
-      contents: chatOptions.contents,
-    });
+    // options
+    const options = Object.assign(
+      {
+        model: modelName,
+      },
+      chatOptions,
+    );
+
+    // gen
+    const response = await client.models.generateContent(options);
     if (!response || !response.text) {
       logger.error(methodName, 'invalid response');
       return;
@@ -93,11 +99,19 @@ export const chatWithStreaming = async (client, modelName, chatOptions, callback
   const firstContentCallback = callbackOptions.firstContentCallback;
 
   try {
+    // begin
     if (beginCallback) beginCallback();
-    const response = await client.models.generateContentStream({
-      model: modelName,
-      contents: chatOptions.contents,
-    });
+
+    // options
+    const options = Object.assign(
+      {
+        model: modelName,
+      },
+      chatOptions,
+    );
+
+    // gen
+    const response = await client.models.generateContentStream(options);
 
     // go
     let firstContent = true;
@@ -132,6 +146,14 @@ export const cacheAdd = async (client, modelName, cacheOptions) => {
   const methodName = 'cacheAdd';
 
   // check
+  if (!client) {
+    logger.error(methodName, 'need client');
+    return;
+  }
+  if (!modelName) {
+    logger.error(methodName, 'need modelName');
+    return;
+  }
   if (!cacheOptions) {
     logger.error(methodName, 'need cacheOptions');
     return;
@@ -175,3 +197,68 @@ export const cacheAdd = async (client, modelName, cacheOptions) => {
     logger.error(methodName, 'error', error);
   }
 };
+
+/**
+ * cacheList
+ * @param {*} client
+ * @returns
+ */
+export const cacheList = async (client) => {
+  const methodName = 'cacheList';
+
+  // check
+  if (!client) {
+    logger.error(methodName, 'need client');
+    return;
+  }
+
+  // cache list
+  try {
+    const cacheList = await client.caches.list();
+    const cacheObjs = cacheList?.pageInternal?.map((contentCache) => ({
+      name: contentCache.name,
+      displayName: contentCache.displayName,
+    }));
+
+    return cacheObjs;
+  } catch (error) {
+    logger.error(methodName, 'error', error);
+  }
+};
+
+/**
+ * cacheUpdate
+ * @param {*} client
+ * @param {*} cacheName
+ * @param {*} cacheOptions
+ * @returns
+ */
+export const cacheUpdate = async (client, cacheName, cacheOptions) => {
+  const methodName = 'cacheUpdate';
+
+  // check
+  if (!client) {
+    logger.error(methodName, 'need client');
+    return;
+  }
+  if (!cacheName) {
+    logger.error(methodName, 'need cacheName');
+    return;
+  }
+  if (!cacheOptions) {
+    logger.error(methodName, 'need cacheOptions');
+    return;
+  }
+
+  // cache update
+  try {
+    const res = await client.caches.update({
+      name: cacheName,
+      config: cacheOptions,
+    });
+
+    return res;
+  } catch (error) {
+    logger.error(methodName, 'error', error);
+  }
+};

package/src/models/gemini-vertex.js

@@ -2,7 +2,7 @@
 import { GoogleGenAI } from '@google/genai';
 
 // util
-import { chat, chatWithStreaming, cacheAdd } from './gemini-util.js';
+import { chat, chatWithStreaming, cacheAdd, cacheList, cacheUpdate } from './gemini-util.js';
 
 // Logger
 import { Logger } from 'qiao.log.js';
@@ -54,6 +54,12 @@ export const GeminiVertex = (options) => {
   gemini.cacheAdd = async (cacheOptions) => {
     return await cacheAdd(gemini.client, options.modelName, cacheOptions);
   };
+  gemini.cacheList = async () => {
+    return await cacheList(gemini.client);
+  };
+  gemini.cacheUpdate = async (cacheName, cacheOptions) => {
+    return await cacheUpdate(gemini.client, cacheName, cacheOptions);
+  };
 
   // r
   return gemini;