@memberjunction/ai-mistral 2.43.0 → 2.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ai-mistral",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction Wrapper for Mistral AI's AI Models",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,8 +19,8 @@
     "typescript": "^5.4.5"
   },
   "dependencies": {
-    "@memberjunction/ai": "2.43.0",
-    "@memberjunction/global": "2.43.0",
+    "@memberjunction/ai": "2.44.0",
+    "@memberjunction/global": "2.44.0",
     "@mistralai/mistralai": "^1.6.0",
     "axios-retry": "4.3.0"
   }

package/readme.md

@@ -1,15 +1,18 @@
 # @memberjunction/ai-mistral
 
-A comprehensive wrapper for Mistral AI's models, enabling seamless integration with the MemberJunction AI framework for natural language processing tasks.
+A comprehensive wrapper for Mistral AI's models, enabling seamless integration with the MemberJunction AI framework for natural language processing and embedding tasks.
 
 ## Features
 
-- **Mistral AI Integration**: Connect to Mistral's powerful language models
-- **Standardized Interface**: Implements MemberJunction's BaseLLM abstract class
+- **Mistral AI Integration**: Connect to Mistral's powerful language models and embedding models
+- **Standardized Interface**: Implements MemberJunction's BaseLLM and BaseEmbeddings abstract classes
+- **Streaming Support**: Full support for streaming chat completions
 - **Token Usage Tracking**: Automatic tracking of prompt and completion tokens
 - **Response Format Control**: Support for standard text and JSON response formats
+- **Multi-Modal Support**: Handles text, images, and documents in chat messages
 - **Error Handling**: Robust error handling with detailed reporting
 - **Chat Completion**: Full support for chat-based interactions with Mistral models
+- **Text Embeddings**: Generate vector embeddings for text using Mistral's embedding models
 
 ## Installation
 
@@ -20,8 +23,9 @@ npm install @memberjunction/ai-mistral
 ## Requirements
 
 - Node.js 16+
+- TypeScript 5.4.5+
 - A Mistral AI API key
-- MemberJunction Core libraries
+- MemberJunction Core libraries (@memberjunction/ai, @memberjunction/global)
 
 ## Usage
 
@@ -37,14 +41,14 @@ const mistralLLM = new MistralLLM('your-mistral-api-key');
 ### Chat Completion
 
 ```typescript
-import { ChatParams } from '@memberjunction/ai';
+import { ChatParams, ChatMessageRole } from '@memberjunction/ai';
 
 // Create chat parameters
 const chatParams: ChatParams = {
   model: 'mistral-large-latest',  // or other models like 'open-mistral-7b', 'mistral-small-latest'
   messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'What are the main principles of machine learning?' }
+    { role: ChatMessageRole.system, content: 'You are a helpful assistant.' },
+    { role: ChatMessageRole.user, content: 'What are the main principles of machine learning?' }
   ],
   temperature: 0.7,
   maxOutputTokens: 1000
@@ -72,8 +76,8 @@ try {
 const jsonParams: ChatParams = {
   model: 'mistral-large-latest',
   messages: [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'Give me data about the top 3 machine learning algorithms in JSON format' }
+    { role: ChatMessageRole.system, content: 'You are a helpful assistant that responds in JSON format.' },
+    { role: ChatMessageRole.user, content: 'Give me data about the top 3 machine learning algorithms in JSON format' }
   ],
   maxOutputTokens: 1000,
   responseFormat: 'JSON'  // This will add the appropriate response_format parameter
@@ -88,6 +92,101 @@ if (jsonResponse.success) {
 }
 ```
 
+### Streaming Chat Completion
+
+```typescript
+// Mistral supports streaming responses
+const streamParams: ChatParams = {
+  model: 'mistral-large-latest',
+  messages: [
+    { role: ChatMessageRole.system, content: 'You are a helpful assistant.' },
+    { role: ChatMessageRole.user, content: 'Write a short story about AI' }
+  ],
+  maxOutputTokens: 1000,
+  stream: true,  // Enable streaming
+  streamCallback: (content: string) => {
+    // Handle each chunk of streamed content
+    process.stdout.write(content);
+  }
+};
+
+const streamResponse = await mistralLLM.ChatCompletion(streamParams);
+console.log('\nStreaming complete!');
+console.log('Total tokens:', streamResponse.data.usage);
+```
+
+### Multi-Modal Messages
+
+```typescript
+// Mistral supports images and documents in messages
+const multiModalParams: ChatParams = {
+  model: 'mistral-large-latest',
+  messages: [
+    {
+      role: ChatMessageRole.user,
+      content: [
+        { type: 'text', content: 'What do you see in this image?' },
+        { type: 'image_url', content: 'https://example.com/image.jpg' }
+      ]
+    }
+  ],
+  maxOutputTokens: 1000
+};
+
+// For documents
+const documentParams: ChatParams = {
+  model: 'mistral-large-latest',
+  messages: [
+    {
+      role: ChatMessageRole.user,
+      content: [
+        { type: 'text', content: 'Summarize this document' },
+        { type: 'file_url', content: 'https://example.com/document.pdf' }  // Converted to document_url for Mistral
+      ]
+    }
+  ],
+  maxOutputTokens: 1000
+};
+```
+
+### Text Embeddings
+
+```typescript
+import { MistralEmbedding } from '@memberjunction/ai-mistral';
+import { EmbedTextParams, EmbedTextsParams } from '@memberjunction/ai';
+
+// Initialize the embedding client
+const mistralEmbedding = new MistralEmbedding('your-mistral-api-key');
+
+// Embed a single text
+const embedParams: EmbedTextParams = {
+  text: 'Machine learning is a subset of artificial intelligence.',
+  model: 'mistral-embed'  // Optional, defaults to 'mistral-embed'
+};
+
+const embedResult = await mistralEmbedding.EmbedText(embedParams);
+console.log('Embedding vector dimensions:', embedResult.vector.length);  // 1024 dimensions
+console.log('Token usage:', embedResult.ModelUsage);
+
+// Embed multiple texts
+const multiEmbedParams: EmbedTextsParams = {
+  texts: [
+    'Natural language processing enables computers to understand human language.',
+    'Deep learning uses neural networks with multiple layers.',
+    'Computer vision allows machines to interpret visual information.'
+  ],
+  model: 'mistral-embed'
+};
+
+const multiEmbedResult = await mistralEmbedding.EmbedTexts(multiEmbedParams);
+console.log('Number of embeddings:', multiEmbedResult.vectors.length);
+console.log('Total token usage:', multiEmbedResult.ModelUsage);
+
+// Get available embedding models
+const embeddingModels = await mistralEmbedding.GetEmbeddingModels();
+console.log('Available models:', embeddingModels);
+```
+
 ### Direct Access to Mistral Client
 
 ```typescript
@@ -95,7 +194,7 @@ if (jsonResponse.success) {
 const mistralClient = mistralLLM.Client;
 
 // Use the client directly if needed
-const modelList = await mistralClient.listModels();
+const modelList = await mistralClient.models.list();
 console.log('Available models:', modelList);
 ```
 
@@ -126,13 +225,34 @@ new MistralLLM(apiKey: string)
 #### Properties
 
 - `Client`: (read-only) Returns the underlying Mistral client instance
+- `SupportsStreaming`: (read-only) Returns `true` - Mistral supports streaming
 
 #### Methods
 
-- `ChatCompletion(params: ChatParams): Promise<ChatResult>` - Perform a chat completion
+- `ChatCompletion(params: ChatParams): Promise<ChatResult>` - Perform a chat completion (supports both streaming and non-streaming)
 - `SummarizeText(params: SummarizeParams): Promise<SummarizeResult>` - Not implemented yet
 - `ClassifyText(params: ClassifyParams): Promise<ClassifyResult>` - Not implemented yet
 
+### MistralEmbedding Class
+
+A class that extends BaseEmbeddings to provide Mistral embedding functionality.
+
+#### Constructor
+
+```typescript
+new MistralEmbedding(apiKey: string)
+```
+
+#### Properties
+
+- `Client`: (read-only) Returns the underlying Mistral client instance
+
+#### Methods
+
+- `EmbedText(params: EmbedTextParams): Promise<EmbedTextResult>` - Generate embedding for a single text
+- `EmbedTexts(params: EmbedTextsParams): Promise<EmbedTextsResult>` - Generate embeddings for multiple texts
+- `GetEmbeddingModels(): Promise<any>` - Get list of available embedding models
+
 ## Response Format Control
 
 The wrapper supports different response formats:
@@ -181,23 +301,85 @@ if (response.success) {
 }
 ```
 
+## Special Behaviors
+
+### Message Formatting
+- The wrapper automatically ensures Mistral's requirement that the last message must be from 'user' or 'tool'
+- If the last message is not from a user, a placeholder user message "ok" is automatically appended
+
+### Multi-Modal Content
+- Image URLs are passed through as `image_url` type
+- File URLs are converted to `document_url` type for Mistral compatibility
+- Unsupported content types are filtered out with a warning
+
 ## Limitations
 
 Currently, the wrapper implements:
-- Chat completion functionality with token usage tracking
+- Chat completion functionality with full streaming support
+- Text embedding functionality with single and batch processing
+- Token usage tracking for both chat and embeddings
 
-Future implementations may include:
+Not yet implemented:
 - `SummarizeText` functionality
 - `ClassifyText` functionality
-- Streaming responses
+- `effortLevel`/`reasoning_effort` parameter (not currently supported by Mistral API)
+
+## Integration with MemberJunction
+
+This package is designed to work seamlessly with the MemberJunction AI framework:
+
+### Class Registration
+Both `MistralLLM` and `MistralEmbedding` are automatically registered with the MemberJunction class factory using the `@RegisterClass` decorator:
+
+```typescript
+// Classes are registered and can be instantiated via the class factory
+import { ClassFactory } from '@memberjunction/global';
+
+const mistralLLM = ClassFactory.CreateInstance<BaseLLM>(BaseLLM, 'MistralLLM', apiKey);
+const mistralEmbedding = ClassFactory.CreateInstance<BaseEmbeddings>(BaseEmbeddings, 'MistralEmbedding', apiKey);
+```
+
+### Tree-Shaking Prevention
+The package exports loader functions to prevent tree-shaking:
+
+```typescript
+import { LoadMistralLLM, LoadMistralEmbedding } from '@memberjunction/ai-mistral';
+
+// Call these in your application initialization to ensure classes are registered
+LoadMistralLLM();
+LoadMistralEmbedding();
+```
 
 ## Dependencies
 
-- `@mistralai/mistralai`: Official Mistral AI Node.js SDK
-- `@memberjunction/ai`: MemberJunction AI core framework
-- `@memberjunction/global`: MemberJunction global utilities
-- `axios-retry`: Retry mechanism for API calls
+- `@mistralai/mistralai`: ^1.6.0 - Official Mistral AI Node.js SDK
+- `@memberjunction/ai`: 2.43.0 - MemberJunction AI core framework
+- `@memberjunction/global`: 2.43.0 - MemberJunction global utilities
+- `axios-retry`: 4.3.0 - Retry mechanism for API calls
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Development Mode
+
+```bash
+npm start
+```
 
 ## License
 
-ISC
+ISC
+
+## Contributing
+
+When contributing to this package:
+1. Follow the MemberJunction code style guide
+2. Ensure all TypeScript types are properly defined
+3. Add appropriate error handling
+4. Update documentation for any new features
+5. Test with various Mistral models