@memberjunction/ai-vertex 2.43.0 → 2.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ai-vertex",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction Wrapper for Google Vertex AI Models",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@google-cloud/vertexai": "^1.8.1",
-    "@memberjunction/ai": "2.43.0",
-    "@memberjunction/global": "2.43.0"
+    "@memberjunction/ai": "2.44.0",
+    "@memberjunction/global": "2.44.0"
   }
 }

package/readme.md

@@ -11,7 +11,7 @@ A comprehensive wrapper for Google Vertex AI services, enabling seamless integra
 - **Response Format Control**: Support for various response formats including text and structured data
 - **Error Handling**: Robust error handling with detailed reporting
 - **Chat Completion**: Full support for chat-based interactions with supported models
-- **Embedding Generation**: Generate text embeddings for semantic search and other applications
+- **Embedding Generation**: Generate text embeddings for semantic search and other applications (currently simulated, pending full Vertex AI embedding API support)
 - **Streaming Support**: Stream responses for real-time UI experiences
 
 ## Installation
@@ -36,10 +36,11 @@ import { VertexLLM, VertexEmbedding } from '@memberjunction/ai-vertex';
 // Path to Google Cloud service account key file
 const keyFilePath = '/path/to/service-account-key.json';
 const projectId = 'your-google-cloud-project-id';
+const location = 'us-central1'; // Optional, defaults to 'us-central1'
 
 // Initialize with your Google Cloud credentials
-const vertexLLM = new VertexLLM(keyFilePath, projectId, 'us-central1');
-const vertexEmbedding = new VertexEmbedding(keyFilePath, projectId, 'us-central1');
+const vertexLLM = new VertexLLM(keyFilePath, projectId, location);
+const vertexEmbedding = new VertexEmbedding(keyFilePath, projectId, location);
 ```
 
 ### Chat Completion with PaLM Models
@@ -125,6 +126,8 @@ await vertexLLM.ChatCompletion(streamingParams);
 
 ### Text Embedding
 
+**Note**: The embedding functionality is currently simulated as the Google Vertex AI SDK for Node.js does not yet provide direct access to embedding endpoints. This will be updated once the SDK supports native embedding generation.
+
 ```typescript
 import { EmbedTextParams, EmbedTextsParams } from '@memberjunction/ai';
 
@@ -160,10 +163,11 @@ Google Vertex AI offers a variety of foundation models. Here are some of the key
 - **PaLM 2 Family**: text-bison, chat-bison, text-unicorn
 - **Gemini Family**: gemini-pro, gemini-pro-vision, gemini-ultra
 - **Code Generation**: code-bison, codechat-bison
-- **Third-party Models**: claude-3-haiku, claude-3-sonnet, claude-3-opus (Anthropic Claude via Vertex)
+- **Third-party Models**: Models from other providers may be available through Vertex AI
 
-### Embedding Models
+### Embedding Models (Simulated)
 - **Text Embeddings**: textembedding-gecko, textembedding-gecko-multilingual
+  - *Note: Currently simulated pending SDK support*
 
 ### Multimodal Models
 - **Gemini Vision**: gemini-pro-vision
@@ -183,13 +187,18 @@ A class that extends BaseLLM to provide Google Vertex AI-specific functionality.
 new VertexLLM(apiKey: string, projectId: string, location: string = 'us-central1')
 ```
 
+- `apiKey`: Path to the Google Cloud service account key file
+- `projectId`: Your Google Cloud project ID
+- `location`: The Google Cloud region for Vertex AI (defaults to 'us-central1')
+
 #### Properties
 
 - `Client`: (read-only) Returns the underlying Vertex AI client instance
+- `SupportsStreaming`: (read-only) Returns `true` - Google Vertex AI supports streaming
 
 #### Methods
 
-- `ChatCompletion(params: ChatParams): Promise<ChatResult>` - Perform a chat completion
+- `ChatCompletion(params: ChatParams): Promise<ChatResult>` - Perform a chat completion with optional streaming support
 - `SummarizeText(params: SummarizeParams): Promise<SummarizeResult>` - Not implemented yet
 - `ClassifyText(params: ClassifyParams): Promise<ClassifyResult>` - Not implemented yet
 
@@ -203,16 +212,34 @@ A class that extends BaseEmbeddings to provide Google Vertex AI embedding functi
 new VertexEmbedding(apiKey: string, projectId: string, location: string = 'us-central1')
 ```
 
+- `apiKey`: Path to the Google Cloud service account key file
+- `projectId`: Your Google Cloud project ID
+- `location`: The Google Cloud region for Vertex AI (defaults to 'us-central1')
+
 #### Properties
 
 - `Client`: (read-only) Returns the underlying Vertex AI client instance
 
 #### Methods
 
-- `EmbedText(params: EmbedTextParams): Promise<EmbedTextResult>` - Generate embeddings for a single text
-- `EmbedTexts(params: EmbedTextsParams): Promise<EmbedTextsResult>` - Generate embeddings for multiple texts
+- `EmbedText(params: EmbedTextParams): Promise<EmbedTextResult>` - Generate embeddings for a single text (currently simulated)
+- `EmbedTexts(params: EmbedTextsParams): Promise<EmbedTextsResult>` - Generate embeddings for multiple texts (currently simulated)
 - `GetEmbeddingModels(): Promise<any>` - Get available embedding models
 
+### Loader Functions
+
+The package exports loader functions to prevent tree-shaking of the registered classes:
+
+```typescript
+import { LoadVertexLLM, LoadVertexEmbedding } from '@memberjunction/ai-vertex';
+
+// Call these functions if you need to ensure the classes are registered
+LoadVertexLLM();
+LoadVertexEmbedding();
+```
+
+These functions are typically not needed in normal usage as importing the classes will automatically register them.
+
 ## Error Handling
 
 The wrapper provides detailed error information:
@@ -247,13 +274,15 @@ if (response.success) {
 
 Currently, the wrapper implements:
 - Chat completion functionality with token usage tracking
-- Embedding functionality
 - Streaming response support
+- Simulated embedding functionality (pending native SDK support)
 
 Future implementations may include:
+- Native embedding functionality (once supported by the Google Cloud Vertex AI SDK)
 - `SummarizeText` functionality
 - `ClassifyText` functionality
 - Support for image generation models
+- Support for multimodal inputs
 
 ## Dependencies
 
@@ -261,4 +290,62 @@ Future implementations may include:
 - `@memberjunction/ai`: MemberJunction AI core framework
 - `@memberjunction/global`: MemberJunction global utilities
 
+## Integration with MemberJunction
+
+This package integrates seamlessly with the MemberJunction AI framework:
+
+1. **Standardized Interface**: Implements the same interface as other AI providers in the MemberJunction ecosystem
+2. **Provider Registration**: Classes are automatically registered using the `@RegisterClass` decorator
+3. **Model Management**: Compatible with MemberJunction's AI model management system
+4. **Token Tracking**: Integrates with MemberJunction's usage tracking and billing systems
+
+### Using with MemberJunction AI Core
+
+```typescript
+import { GetAIAPIKey } from '@memberjunction/ai';
+import { VertexLLM } from '@memberjunction/ai-vertex';
+
+// Get API key from MemberJunction configuration
+const apiKey = GetAIAPIKey('vertex');
+const projectId = 'your-project-id';
+
+// Create provider instance
+const vertex = new VertexLLM(apiKey, projectId);
+
+// Use with MemberJunction AI services
+// The provider will be automatically available through the AI factory system
+```
+
+## Implementation Notes
+
+### Authentication
+The package expects the `apiKey` parameter to be a path to a Google Cloud service account key file, not an API key string. This file should contain the credentials for accessing Vertex AI services.
+
+### Model Name Mapping
+The package automatically handles different model types based on their name prefix:
+- Models starting with `gemini-` are handled as Gemini models
+- Models starting with `text-` are handled as text generation models
+- Models starting with `code-` are handled as code generation models
+
+### Message Role Mapping
+The package maps MemberJunction message roles to Vertex AI format:
+- `system` → `system`
+- `assistant` → `model`
+- `user` → `user`
+
+## Building and Development
+
+```bash
+# Build the package
+npm run build
+
+# Watch mode for development
+npm run watch
+
+# Run type checking
+tsc --noEmit
+```
+
+## License
+
 See the [repository root](../../../LICENSE) for license information.