@memberjunction/ai-mistral 4.0.0 → 4.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @memberjunction/ai-mistral
+
+MemberJunction AI provider for Mistral AI. This package provides both LLM and embedding capabilities using Mistral's models, implementing `BaseLLM` and `BaseEmbeddings` from `@memberjunction/ai`.
+
+## Architecture
+
+```mermaid
+graph TD
+    A["MistralLLM<br/>(Provider)"] -->|extends| B["BaseLLM<br/>(@memberjunction/ai)"]
+    C["MistralEmbedding<br/>(Provider)"] -->|extends| D["BaseEmbeddings<br/>(@memberjunction/ai)"]
+    A -->|wraps| E["Mistral Client<br/>(@mistralai/mistralai)"]
+    C -->|wraps| E
+    A -->|provides| F["Chat Completions<br/>+ Streaming"]
+    C -->|provides| G["Text Embeddings"]
+    B -->|registered via| H["@RegisterClass"]
+    D -->|registered via| H
+
+    style A fill:#7c5295,stroke:#563a6b,color:#fff
+    style C fill:#7c5295,stroke:#563a6b,color:#fff
+    style B fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style D fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style E fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style F fill:#b8762f,stroke:#8a5722,color:#fff
+    style G fill:#b8762f,stroke:#8a5722,color:#fff
+    style H fill:#b8762f,stroke:#8a5722,color:#fff
+```
+
+## Features
+
+- **Chat Completions**: Conversational AI with Mistral Large, Medium, Small, and open models
+- **Streaming**: Real-time response streaming support
+- **Text Embeddings**: Vector embeddings via Mistral's embedding models
+- **Thinking/Reasoning**: Extraction of thinking content from reasoning models
+- **JSON Mode**: Response format control for structured outputs
+- **Multimodal Support**: Handling of image content in messages
+
+## Installation
+
+```bash
+npm install @memberjunction/ai-mistral
+```
+
+## Usage
+
+### Chat Completion
+
+```typescript
+import { MistralLLM } from '@memberjunction/ai-mistral';
+
+const llm = new MistralLLM('your-mistral-api-key');
+
+const result = await llm.ChatCompletion({
+    model: 'mistral-large-latest',
+    messages: [
+        { role: 'user', content: 'Explain transformers in machine learning.' }
+    ],
+    temperature: 0.7
+});
+
+if (result.success) {
+    console.log(result.data.choices[0].message.content);
+}
+```
+
+### Streaming
+
+```typescript
+const result = await llm.ChatCompletion({
+    model: 'mistral-small-latest',
+    messages: [{ role: 'user', content: 'Write a poem.' }],
+    streaming: true,
+    streamingCallbacks: {
+        OnContent: (content) => process.stdout.write(content),
+        OnComplete: () => console.log('\nDone!')
+    }
+});
+```
+
+### Embeddings
+
+```typescript
+import { MistralEmbedding } from '@memberjunction/ai-mistral';
+
+const embedder = new MistralEmbedding('your-mistral-api-key');
+
+const result = await embedder.EmbedText({
+    text: 'Sample text for embedding',
+    model: 'mistral-embed'
+});
+
+console.log(`Dimensions: ${result.vector.length}`);
+```
+
+## Supported Parameters
+
+| Parameter | Supported | Notes |
+|-----------|-----------|-------|
+| temperature | Yes | Controls randomness |
+| maxOutputTokens | Yes | Maximum response length |
+| topP | Yes | Nucleus sampling |
+| seed | Yes | Deterministic outputs |
+| responseFormat | Yes | JSON mode support |
+| streaming | Yes | Real-time streaming |
+
+## Class Registration
+
+- `MistralLLM` -- Registered via `@RegisterClass(BaseLLM, 'MistralLLM')`
+- `MistralEmbedding` -- Registered via `@RegisterClass(BaseEmbeddings, 'MistralEmbedding')`
+
+## Dependencies
+
+- `@memberjunction/ai` - Core AI abstractions
+- `@memberjunction/global` - Class registration
+- `@mistralai/mistralai` - Official Mistral AI SDK

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-mistral",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "MemberJunction Wrapper for Mistral AI's AI Models",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,8 +20,8 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/ai": "4.0.0",
-    "@memberjunction/global": "4.0.0",
+    "@memberjunction/ai": "4.1.0",
+    "@memberjunction/global": "4.1.0",
     "@mistralai/mistralai": "^1.14.0",
     "axios-retry": "4.5.0"
   },

package/readme.md

@@ -1,18 +1,38 @@
 # @memberjunction/ai-mistral
 
-A comprehensive wrapper for Mistral AI's models, enabling seamless integration with the MemberJunction AI framework for natural language processing and embedding tasks.
+MemberJunction AI provider for Mistral AI. This package provides both LLM and embedding capabilities using Mistral's models, implementing `BaseLLM` and `BaseEmbeddings` from `@memberjunction/ai`.
+
+## Architecture
+
+```mermaid
+graph TD
+    A["MistralLLM<br/>(Provider)"] -->|extends| B["BaseLLM<br/>(@memberjunction/ai)"]
+    C["MistralEmbedding<br/>(Provider)"] -->|extends| D["BaseEmbeddings<br/>(@memberjunction/ai)"]
+    A -->|wraps| E["Mistral Client<br/>(@mistralai/mistralai)"]
+    C -->|wraps| E
+    A -->|provides| F["Chat Completions<br/>+ Streaming"]
+    C -->|provides| G["Text Embeddings"]
+    B -->|registered via| H["@RegisterClass"]
+    D -->|registered via| H
+
+    style A fill:#7c5295,stroke:#563a6b,color:#fff
+    style C fill:#7c5295,stroke:#563a6b,color:#fff
+    style B fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style D fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style E fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style F fill:#b8762f,stroke:#8a5722,color:#fff
+    style G fill:#b8762f,stroke:#8a5722,color:#fff
+    style H fill:#b8762f,stroke:#8a5722,color:#fff
+```
 
 ## Features
 
-- **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
+- **Chat Completions**: Conversational AI with Mistral Large, Medium, Small, and open models
+- **Streaming**: Real-time response streaming support
+- **Text Embeddings**: Vector embeddings via Mistral's embedding models
+- **Thinking/Reasoning**: Extraction of thinking content from reasoning models
+- **JSON Mode**: Response format control for structured outputs
+- **Multimodal Support**: Handling of image content in messages
 
 ## Installation
 
@@ -20,384 +40,75 @@ A comprehensive wrapper for Mistral AI's models, enabling seamless integration w
 npm install @memberjunction/ai-mistral
 ```
 
-## Requirements
-
-- Node.js 16+
-- TypeScript 5.4.5+
-- A Mistral AI API key
-- MemberJunction Core libraries (@memberjunction/ai, @memberjunction/global)
-
 ## Usage
 
-### Basic Setup
-
-```typescript
-import { MistralLLM } from '@memberjunction/ai-mistral';
-
-// Initialize with your Mistral API key
-const mistralLLM = new MistralLLM('your-mistral-api-key');
-```
-
 ### Chat Completion
 
 ```typescript
-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: 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
-};
-
-// Get a response
-try {
-  const response = await mistralLLM.ChatCompletion(chatParams);
-  if (response.success) {
-    console.log('Response:', response.data.choices[0].message.content);
-    console.log('Token Usage:', response.data.usage);
-    console.log('Time Elapsed (ms):', response.timeElapsed);
-  } else {
-    console.error('Error:', response.errorMessage);
-  }
-} catch (error) {
-  console.error('Exception:', error);
-}
-```
-
-### JSON Response Format
+import { MistralLLM } from '@memberjunction/ai-mistral';
 
-```typescript
-// Request a structured JSON response
-const jsonParams: ChatParams = {
-  model: 'mistral-large-latest',
-  messages: [
-    { 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
-};
+const llm = new MistralLLM('your-mistral-api-key');
 
-const jsonResponse = await mistralLLM.ChatCompletion(jsonParams);
+const result = await llm.ChatCompletion({
+    model: 'mistral-large-latest',
+    messages: [
+        { role: 'user', content: 'Explain transformers in machine learning.' }
+    ],
+    temperature: 0.7
+});
 
-// Parse the JSON response
-if (jsonResponse.success) {
-  const structuredData = JSON.parse(jsonResponse.data.choices[0].message.content);
-  console.log('Structured Data:', structuredData);
+if (result.success) {
+    console.log(result.data.choices[0].message.content);
 }
 ```
 
-### 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
+### Streaming
 
 ```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' }
-      ]
+const result = await llm.ChatCompletion({
+    model: 'mistral-small-latest',
+    messages: [{ role: 'user', content: 'Write a poem.' }],
+    streaming: true,
+    streamingCallbacks: {
+        OnContent: (content) => process.stdout.write(content),
+        OnComplete: () => console.log('\nDone!')
     }
-  ],
-  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
+### 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);
+const embedder = new MistralEmbedding('your-mistral-api-key');
 
-// Get available embedding models
-const embeddingModels = await mistralEmbedding.GetEmbeddingModels();
-console.log('Available models:', embeddingModels);
-```
-
-### Direct Access to Mistral Client
-
-```typescript
-// Access the underlying Mistral client for advanced usage
-const mistralClient = mistralLLM.Client;
+const result = await embedder.EmbedText({
+    text: 'Sample text for embedding',
+    model: 'mistral-embed'
+});
 
-// Use the client directly if needed
-const modelList = await mistralClient.models.list();
-console.log('Available models:', modelList);
-```
-
-## Supported Models
-
-Mistral AI offers several models with different capabilities and price points:
-
-- `mistral-large-latest`: Mistral's most powerful model (at the time of writing)
-- `mistral-medium-latest`: Mid-tier model balancing performance and cost
-- `mistral-small-latest`: Smaller, more efficient model
-- `open-mistral-7b`: Open-source 7B parameter model
-- `open-mixtral-8x7b`: Open-source mixture-of-experts model
-
-Check the [Mistral AI documentation](https://docs.mistral.ai/) for the latest list of supported models.
-
-## API Reference
-
-### MistralLLM Class
-
-A class that extends BaseLLM to provide Mistral-specific functionality.
-
-#### Constructor
-
-```typescript
-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 (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:
-
-```typescript
-// For JSON responses
-const params: ChatParams = {
-  // ...other parameters
-  responseFormat: 'JSON'
-};
-
-// For regular text responses (default)
-const textParams: ChatParams = {
-  // ...other parameters
-  // No need to specify responseFormat for regular text
-};
-```
-
-## Error Handling
-
-The wrapper provides detailed error information:
-
-```typescript
-try {
-  const response = await mistralLLM.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);
-}
-```
-
-## Token Usage Tracking
-
-Monitor token usage for billing and quota management:
-
-```typescript
-const response = await mistralLLM.ChatCompletion(params);
-if (response.success) {
-  console.log('Prompt Tokens:', response.data.usage.promptTokens);
-  console.log('Completion Tokens:', response.data.usage.completionTokens);
-  console.log('Total Tokens:', response.data.usage.totalTokens);
-}
-```
-
-## 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 full streaming support
-- Text embedding functionality with single and batch processing
-- Token usage tracking for both chat and embeddings
-
-Not yet implemented:
-- `SummarizeText` functionality
-- `ClassifyText` functionality
-- `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`: ^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
+console.log(`Dimensions: ${result.vector.length}`);
 ```
 
 ## Supported Parameters
 
-The Mistral provider supports the following LLM parameters:
+| Parameter | Supported | Notes |
+|-----------|-----------|-------|
+| temperature | Yes | Controls randomness |
+| maxOutputTokens | Yes | Maximum response length |
+| topP | Yes | Nucleus sampling |
+| seed | Yes | Deterministic outputs |
+| responseFormat | Yes | JSON mode support |
+| streaming | Yes | Real-time streaming |
 
-**Supported:**
-- `temperature` - Controls randomness in the output (0.0-1.0)
-- `maxOutputTokens` - Maximum number of tokens to generate
-- `topP` - Nucleus sampling threshold (0.0-1.0)
-- `topK` - Limits vocabulary to top K tokens
-- `seed` - For deterministic outputs (passed as `randomSeed` to Mistral API)
-- `stopSequences` - Array of sequences where the API will stop generating
-- `responseFormat` - Output format (Text or JSON)
+## Class Registration
 
-**Not Supported:**
-- `frequencyPenalty` - Not available in Mistral API
-- `presencePenalty` - Not available in Mistral API
-- `minP` - Not available in Mistral API
+- `MistralLLM` -- Registered via `@RegisterClass(BaseLLM, 'MistralLLM')`
+- `MistralEmbedding` -- Registered via `@RegisterClass(BaseEmbeddings, 'MistralEmbedding')`
 
-## License
-
-ISC
-
-## Contributing
+## Dependencies
 
-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
+- `@memberjunction/ai` - Core AI abstractions
+- `@memberjunction/global` - Class registration
+- `@mistralai/mistralai` - Official Mistral AI SDK