### Multi-Provider AI with Fallbacks and First-to-Finish

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Sets up and uses `MultiProviderAi` to interact with multiple AI services (OpenRouter, Mistral, Groq) concurrently, utilizing fallback models and returning the first successful response. Includes examples for chat, transcription, and classification.

```javascript
// Multi-provider setup with fallbacks
const multiAi = new MultiProviderAi({
  apiKeys: {
    openrouter: 'your-openrouter-key',
    mistral: 'your-mistral-key',
    groq: 'your-groq-key'
  },
  model: {
    provider: 'mistral',
    name: 'mistral-small-latest'
  },
  fallbackModels: {
    openrouter: ['meta-llama/llama-3.3-70b-instruct:free'],
    mistral: ['mistral-large-latest'],
    groq: ['llama-3.1-70b-versatile']
  },
  firstToFinish: true // Race all providers
});

const response = await multiAi.ask({
  user: 'Explain quantum computing',
  system: 'You are a physics professor.'
});

// Transcription using any available provider
const transcription = await multiAi.transcribe({
  file: audioBuffer,
  model: 'whisper-large-v3-turbo'
});

// Classification using Mistral
const moderation = await multiAi.classify([
  'This is a safe message',
  'This contains harmful content'
]);
```

--------------------------------

### Submit Attachments to AI with User Prompt

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Example of how to use the 'ask' method with an array of attachments, including images and videos, along with a user prompt.

```javascript
const attachments = [imageAttachment, videoAttachment];

const response = await ai.ask({
  user: 'Describe this image and what happens in the video',
  attachments
});
```

--------------------------------

### Install @oof2510/llmjs with npm, yarn, or pnpm

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Instructions for installing the @oof2510/llmjs library using popular JavaScript package managers.

```bash
npm install @oof2510/llmjs
```

```bash
yarn add @oof2510/llmjs
```

```bash
pnpm add @oof2510/llmjs
```

--------------------------------

### Mistral AI for Content Generation and Moderation

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

Shows how to use Mistral's AI API for creative text generation and content classification. The example demonstrates generating a story and then using the classify method to evaluate user inputs for different categories like violence and hate speech.

```javascript
const { MistralAi } = require('@oof2510/llmjs');

const mistralAi = new MistralAi({
  apiKey: process.env.MISTRAL_API_KEY,
  model: 'mistral-small-latest',
  fallbackModels: ['mistral-large-latest', 'mistral-medium-latest'],
  maxTokens: 500
});

(async () => {
  // Generate content
  const story = await mistralAi.ask({
    user: 'Write a short story about a robot learning to paint.'
  });
  console.log(story);

  // Content moderation
  const userInputs = [
    'This is a friendly message about technology.',
    'I want to harm someone',
    'Check out this amazing recipe!'
  ];

  const moderationResults = await mistralAi.classify(userInputs, {
    model: 'mistral-moderation-latest'
  });

  console.log('Categories:', moderationResults.categories);
  // Output: { sexual: false, violence: true, hate: false, ... }
  console.log('Scores:', moderationResults.scores);
  // Output: { sexual: 0.02, violence: 0.95, hate: 0.01, ... }
})();
```

--------------------------------

### Multi-Provider AI with Persistent History using JavaScript

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

Integrates multiple AI providers with conversation memory for resilient, context-aware interactions. It utilizes AiMemoryStore for persistence and MultiProviderAiWithHistory for managing different models and fallbacks. Inputs include conversation history and user queries, with outputs being AI-generated responses. This setup is suitable for building robust chat applications.

```javascript
const { AiMemoryStore, MultiProviderAiWithHistory } = require('@oof2510/llmjs');

const memoryStore = new AiMemoryStore({
  uri: 'mongodb://localhost:27017',
  dbName: 'multi_provider_chat',
  collectionName: 'ai_conversations'
});

const multiAiHistory = new MultiProviderAiWithHistory({
  apiKeys: {
    openrouter: process.env.OPENROUTER_API_KEY,
    mistral: process.env.MISTRAL_API_KEY,
    groq: process.env.GROQ_API_KEY
  },
  model: {
    provider: 'groq',
    name: 'llama-3.1-70b-versatile'
  },
  fallbackModels: {
    openrouter: ['meta-llama/llama-3.3-70b-instruct:free'],
    mistral: ['mistral-small-latest'],
    groq: ['mixtral-8x7b-32768']
  },
  memoryStore: memoryStore,
  memoryScope: 'support_agent',
  historyLimit: 30,
  firstToFinish: false, // Sequential fallbacks
  temperature: 0.6
});

(async () => {
  const userId = 'customer_789';

  // Start a support conversation
  await multiAiHistory.ask(userId, {
    system: 'You are a technical support agent. Be helpful and concise.',
    user: 'My application keeps crashing when I upload large files.'
  });

  // Continue conversation with context
  await multiAiHistory.ask(userId, {
    user: 'The files are around 500MB each.'
  });

  const finalResponse = await multiAiHistory.ask(userId, {
    user: 'What are the recommended file size limits?'
  });

  console.log('Support response:', finalResponse);

  // Clear this customer's conversation
  await multiAiHistory.clear(userId);
  await memoryStore.disconnect();
})();
```

--------------------------------

### Get Ordered Providers with MultiProviderAi

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Retrieves the list of configured AI providers in their order of preference using the `getOrderedProviders` method of the `MultiProviderAi` class. This is useful for understanding the fallback or priority order when making requests.

```javascript
const providers = ai.getOrderedProviders();
console.log('Ordered Providers:', providers);
```

--------------------------------

### Multi-Provider AI with Parallel Racing using llmjs

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

Configure and utilize multiple AI providers simultaneously, racing them to get the fastest response. This feature supports parallel requests for both text generation and transcription, with fallback models and customizable timeouts. It requires API keys for the providers to be set as environment variables.

```javascript
const { MultiProviderAi } = require('@oof2510/llmjs');

const multiAi = new MultiProviderAi({
  apiKeys: {
    openrouter: process.env.OPENROUTER_API_KEY,
    mistral: process.env.MISTRAL_API_KEY,
    groq: process.env.GROQ_API_KEY
  },
  model: {
    provider: 'mistral',
    name: 'mistral-small-latest'
  },
  fallbackModels: {
    openrouter: ['meta-llama/llama-3.3-70b-instruct:free'],
    mistral: ['mistral-large-latest'],
    groq: ['llama-3.1-70b-versatile', 'mixtral-8x7b-32768']
  },
  firstToFinish: true, // Race all providers in parallel
  temperature: 0.8,
  requestTimeoutMs: 15000
});

(async () => {
  // The request goes to all configured providers simultaneously
  const response = await multiAi.ask({
    system: 'You are a creative writing assistant.',
    user: 'Generate a catchy tagline for a space exploration startup.'
  });
  console.log('First provider to respond:', response);
  // Output from whichever provider finishes first

  // Transcription with automatic provider selection
  const audioBuffer = require('fs').readFileSync('./audio.mp3');
  const transcript = await multiAi.transcribe({
    file: audioBuffer,
    model: 'whisper-large-v3-turbo'
  });
  console.log('Transcription:', transcript);

  // Content classification (uses Mistral automatically)
  const moderation = await multiAi.classify([
    'This is a normal comment',
    'This contains offensive language'
  ]);
  console.log('Moderation results:', moderation);
})();
```

--------------------------------

### Initialize MultiProviderAiWithHistory

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Creates an instance of `MultiProviderAiWithHistory`, which extends `MultiProviderAi` by adding persistent memory capabilities. It requires an `AiMemoryStore` instance and allows configuration of memory scope, history limit, and other `MultiProviderAi` options. An error is thrown if the `memoryStore` is not provided.

```javascript
const memoryStore = new YourAiMemoryStoreImplementation(); // Replace with your actual memory store

const aiWithHistory = new MultiProviderAiWithHistory({
  memoryStore: memoryStore,
  memoryScope: 'user-session-123',
  historyLimit: 20,
  // ... other MultiProviderAi options
});
```

--------------------------------

### Initialize MultiProviderAi

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Instantiates the MultiProviderAi class, which acts as a high-level helper for communicating with multiple AI providers. It supports unified API calls, cross-provider fallbacks, and optional first-to-finish response racing. Configuration options include API keys, primary and fallback models, temperature, max tokens, and request timeout.

```javascript
const ai = new MultiProviderAi({
  apiKeys: {
    openrouter: 'YOUR_OPENROUTER_API_KEY',
    mistral: 'YOUR_MISTRAL_API_KEY',
    groq: 'YOUR_GROQ_API_KEY'
  },
  model: {
    provider: 'mistral',
    name: 'mistral-small-latest'
  },
  fallbackModels: {
    openrouter: ['mistralai/mistral-7b-instruct-v0.1']
  },
  temperature: 0.7,
  maxTokens: 1000,
  requestTimeoutMs: 20000,
  firstToFinish: true
});
```

--------------------------------

### Send Prompt with MultiProviderAi

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Uses the `ask` method of the `MultiProviderAi` class to send a prompt to configured AI providers. It supports system prompts, user messages, additional message history, and attachments. The method returns the AI's response as text and throws an error if no providers are configured or all fail.

```javascript
const response = await ai.ask({
  system: 'You are a helpful assistant.',
  user: 'What is the weather today?',
  messages: [
    // Previous messages can be added here
  ],
  attachments: [
    // AiAttachment objects can be added here
  ]
});
console.log(response);
```

--------------------------------

### Configure AI with Multiple Models and Parallel Racing

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Demonstrates configuring an AI client with a primary model, fallback models, and enabling `firstToFinish` for parallel racing. This configuration is applicable to both 'ask' and 'transcribe' methods.

```javascript
const ai = new Ai({
  apiKey: 'your-openrouter-api-key',
  model: 'primary-model',
  fallbackModels: ['fallback-1', 'fallback-2'],
  firstToFinish: true, // race all three models
});

const answer = await ai.ask({ user: 'Explain event loops in JS.' });

const groq = new GroqAi({
  apiKey: process.env.GROQ_API_KEY,
  fallbackModels: ['llama-3.1-70b-versatile', 'llama-3.1-8b-instant'],
  firstToFinish: true,
});

// Also used for transcription: will race across configured transcription models
const text = await groq.transcribe({ file: 'audio.wav' });

const mistral = new MistralAi({
  apiKey: process.env.MISTRAL_API_KEY,
  fallbackModels: ['mistral-small-latest', 'mistral-large-latest'],
  firstToFinish: true,
});

const mistralAnswer = await mistral.ask({ user: 'Summarize this article.' });
```

--------------------------------

### Configure AI with Fallback Models

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Sets up an AI client with a primary model and a list of fallback models to be used sequentially if the primary model fails.

```javascript
const ai = new Ai({
  apiKey: 'your-api-key',
  model: 'primary-model',
  fallbackModels: ['fallback1', 'fallback2', 'fallback3']
});
```

--------------------------------

### Basic OpenRouter AI Query with Fallbacks

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

Demonstrates sending a simple prompt to OpenRouter's language models. It includes configuration for a primary model and fallback models to ensure request success. The function handles system and user prompts, returning the AI's response or an error.

```javascript
const { Ai } = require('@oof2510/llmjs');

const ai = new Ai({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: 'meta-llama/llama-3.3-70b-instruct:free',
  fallbackModels: ['anthropic/claude-3-haiku', 'google/gemini-pro'],
  temperature: 0.7,
  maxTokens: 1000,
  requestTimeoutMs: 20000
});

(async () => {
  try {
    const response = await ai.ask({
      system: 'You are a helpful coding assistant specialized in JavaScript.',
      user: 'Explain how async/await works in JavaScript with an example.'
    });
    console.log(response);
    // Output: "Async/await is syntactic sugar built on top of Promises..."
  } catch (error) {
    console.error('AI request failed:', error.message);
  }
})();
```

--------------------------------

### JavaScript: Implement AI Error Handling and Fallback Models

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

This snippet demonstrates how to configure the Ai client with primary and fallback models, request timeouts, and temperature settings. It includes a try-catch block to handle potential errors during AI requests, automatically falling back to alternative models if the primary one fails. It also shows a function for safe AI responses with application-level fallbacks.

```javascript
const { Ai } = require('@oof2510/llmjs');

const ai = new Ai({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: 'expensive-premium-model', // Primary model might fail
  fallbackModels: [
    'mid-tier-model',
    'fast-basic-model',
    'free-model'
  ],
  requestTimeoutMs: 10000, // 10 second timeout
  temperature: 0.7
});

(async () => {
  try {
    // Library automatically tries fallback models if primary fails
    const response = await ai.ask({
      system: 'You are a data analyst.',
      user: 'Analyze the following sales data and provide insights: Q1: $50k, Q2: $75k, Q3: $90k, Q4: $120k'
    });
    console.log('Analysis:', response);
  } catch (error) {
    // All models failed or other critical error
    console.error('Request failed after all retries');
    console.error('Error message:', error.message);

    if (error.status) {
      console.error('HTTP status:', error.status);
    }

    if (error.original) {
      console.error('Original error:', error.original);
    }

    // Implement application-level fallback
    console.log('Falling back to cached response or default message');
  }

  // Example with async/await pattern in a function
  async function getSafeAiResponse(prompt) {
    try {
      return await ai.ask({ user: prompt });
    } catch (error) {
      console.warn('AI unavailable, using fallback');
      return 'I apologize, but I am temporarily unavailable. Please try again later.';
    }
  }

  const safeResponse = await getSafeAiResponse('What is machine learning?');
  console.log(safeResponse);
})();
```

--------------------------------

### AiMemoryStore Class

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

A MongoDB-based memory storage solution for managing AI conversation history.

```APIDOC
## AiMemoryStore Class

MongoDB-based memory storage for conversation history.

### Constructor

#### `new AiMemoryStore(options)`

Creates a new memory store for AI conversation history.

- **Parameters**
  - `options` (object)
    - `uri` (string, required) - MongoDB connection URI
    - `dbName` (string, required) - Database name
    - `collectionName` (string, optional) - Collection name (default: "ai_memory")

- **Throws**
  - Error if uri or dbName missing

### Methods

#### `connect()`

Connects to MongoDB and returns the collection.

- **Returns**
  - Promise<Collection> - MongoDB collection

#### `disconnect()`

Closes the MongoDB connection.

- **Returns**
  - Promise<void>

#### `getHistory(chatId, scope, limit)`

Retrieves recent chat messages for context.

- **Parameters**
  - `chatId` (string|number, required) - Conversation identifier
  - `scope` (string, required) - Context scope
  - `limit` (number, optional) - Maximum messages to retrieve (default: 10)

- **Returns**
  - Promise<Array<{ role: string, content: string|Array|Record<string, any> }>> - Message history

#### `appendMessages(chatId, scope, messages)`

Saves new messages and prunes old ones.

- **Parameters**
  - `chatId` (string|number, required) - Conversation identifier
  - `scope` (string, required) - Context scope
  - `messages` (Array<{ role: string, content: string|Array|Record<string, any> }>, optional) - Messages to save

- **Returns**
  - Promise<void>

#### `clearHistory(chatId, scope)`

Clears all stored history for a conversation.

- **Parameters**
  - `chatId` (string|number, required) - Conversation identifier
  - `scope` (string, required) - Context scope

- **Returns**
  - Promise<void>
```

--------------------------------

### Groq AI Ask Function

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Sends a prompt to Groq models with optional system messages, user messages, message history, and attachments. It supports fallback models if the primary model fails. Returns a promise that resolves with the AI's response string. Throws an error if no models are configured or all fail.

```typescript
import { GroqAi } from "@llmjs/groq";

const groq = new GroqAi({
  apiKey: "YOUR_GROQ_API_KEY",
  model: "llama3-70b-8192",
  fallbackModels: ["mixtral-8x7b-32768", "gemma-7b-it"]
});

async function askGroq() {
  const response = await groq.ask({
    system: "You are a helpful assistant.",
    user: "What is the weather today?",
    messages: [
      { role: "user", content: "Hello" },
      { role: "assistant", content: "Hi there! How can I help you?" }
    ]
  });
  console.log(response);
}
```

--------------------------------

### Basic AI Usage with OpenRouter in ES6/TypeScript

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Illustrates initializing and using the Ai class for basic chat interactions with OpenRouter in an ES6/TypeScript environment. Requires an API key and model specification.

```typescript
import { Ai } from '@oof2510/llmjs';

// Basic AI usage
const ai = new Ai({
  apiKey: 'your-openrouter-api-key',
  model: 'meta-llama/llama-3.3-70b-instruct:free'
});

const response = await ai.ask({
  user: 'Hello, how are you?',
  system: 'You are a helpful assistant.'
});

console.log(response);
```

--------------------------------

### Basic AI Usage with OpenRouter in CommonJS

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Demonstrates initializing and using the Ai class for basic chat interactions with OpenRouter in a CommonJS environment. Requires an API key and specifies the model.

```javascript
const { Ai } = require('@oof2510/llmjs');

// Basic AI usage
const ai = new Ai({
  apiKey: 'your-openrouter-api-key',
  model: 'meta-llama/llama-3.3-70b-instruct:free'
});

const response = await ai.ask({
  user: 'Hello, how are you?',
  system: 'You are a helpful assistant.'
});

console.log(response);
```

--------------------------------

### Initialize MongoDB Memory Store

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Configures and initializes an AI memory store using MongoDB. Requires connection URI, database name, and optionally a collection name.

```javascript
const memoryStore = new AiMemoryStore({
  uri: 'mongodb://localhost:27017',
  dbName: 'myapp',
  collectionName: 'ai_memory'
});
```

--------------------------------

### Multimodal Input (Images/Videos) with JavaScript

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

Enables sending images and videos along with text prompts to vision-enabled AI models. It supports analysis from URLs and local files (buffers) for both images and videos. The output is the AI's interpretation of the provided media. This is useful for applications requiring visual understanding.

```javascript
const { Ai } = require('@oof2510/llmjs');
const fs = require('fs');

const ai = new Ai({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: 'anthropic/claude-3-opus', // Vision-capable model
  maxTokens: 2000
});

(async () => {
  // Image analysis from URL
  const response1 = await ai.ask({
    user: 'Describe what you see in this image and identify any objects.',
    attachments: [
      {
        type: 'image',
        url: 'https://example.com/product-photo.jpg'
      }
    ]
  });
  console.log('Image analysis:', response1);

  // Image analysis from local file
  const imageBuffer = fs.readFileSync('./screenshot.png');
  const response2 = await ai.ask({
    user: 'What programming language is shown in this code screenshot?',
    attachments: [
      {
        type: 'image',
        data: imageBuffer,
        mimeType: 'image/png'
      }
    ]
  });
  console.log('Code analysis:', response2);

  // Video analysis
  const videoBuffer = fs.readFileSync('./demo-video.mp4');
  const response3 = await ai.ask({
    user: 'Summarize the main actions happening in this video.',
    attachments: [
      {
        type: 'video',
        data: videoBuffer,
        format: 'mp4'
      }
    ]
  });
  console.log('Video analysis:', response3);

  // Multiple attachments
  const response4 = await ai.ask({
    user: 'Compare these two product images and tell me the differences.',
    attachments: [
      {
        type: 'image',
        url: 'https://example.com/product-v1.jpg'
      },
      {
        type: 'image',
        url: 'https://example.com/product-v2.jpg'
      }
    ]
  });
  console.log('Comparison:', response4);
})();
```

--------------------------------

### AI Chat with Memory Operations

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Demonstrates initializing an AI client with history, performing chat operations with memory, and clearing memory for a specific scope.

```javascript
// Store with memory
const ai = new AiWithHistory({
  apiKey: 'your-api-key',
  memoryStore,
  memoryScope: 'user123',
  historyLimit: 20
});

// Chat with memory
await ai.ask('chat123', { user: 'Remember this' });
await ai.ask('chat123', { user: 'What did I say before?' });

// Clear memory
await ai.clear('chat123');
```

--------------------------------

### Groq AI for Text Generation and Audio Transcription

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

Utilizes Groq's API for both generating text responses and transcribing audio files using the Whisper model. It shows how to instantiate GroqAi with API keys and model configurations, then perform separate ask and transcribe operations.

```javascript
const { GroqAi } = require('@oof2510/llmjs');
const fs = require('fs');

const groqAi = new GroqAi({
  apiKey: process.env.GROQ_API_KEY,
  model: 'llama-3.1-70b-versatile',
  fallbackModels: ['llama-3.1-8b-instant', 'mixtral-8x7b-32768'],
  temperature: 0.5
});

(async () => {
  // Text generation
  const textResponse = await groqAi.ask({
    system: 'You are a technical documentation writer.',
    user: 'Write a brief description of REST APIs.'
  });
  console.log('Text response:', textResponse);

  // Audio transcription
  const audioBuffer = fs.readFileSync('./meeting-recording.wav');
  const transcription = await groqAi.transcribe({
    file: audioBuffer,
    model: 'whisper-large-v3-turbo',
    temperature: 0
  });
  console.log('Transcription:', transcription);
  // Output: "Welcome everyone to today's meeting. Let's start with..."
})();
```

--------------------------------

### Mistral AI Ask Function

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Sends a prompt to Mistral models with optional system messages, user messages, message history, and attachments. Supports fallback models and a `firstToFinish` option for parallel model execution. Returns a promise that resolves with the AI's response string. Throws an error if no models are configured or all fail.

```typescript
import { MistralAi } from "@llmjs/mistral";

const mistral = new MistralAi({
  apiKey: "YOUR_MISTRAL_API_KEY",
  model: "mistral-large-latest",
  fallbackModels: ["mistral-small-latest"],
  temperature: 0.8,
  firstToFinish: true
});

async function askMistral() {
  const response = await mistral.ask({
    system: "You are a creative writer.",
    user: "Write a short poem about the sea."
  });
  console.log(response);
}
```

--------------------------------

### Message and Payload Preparation

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Functions for preparing messages and payloads for AI consumption, including user messages with attachments and constructing message arrays for LangChain.

```APIDOC
## Message and Payload Preparation

### `buildUserMessagePayload(options)`

Prepares user message with attachments for API consumption.

- **Parameters**
  - `options` (object, optional)
    - `user` (any) - User message
    - `attachments` (AiAttachment[]) - Attachments

- **Returns**
  - { message: HumanMessage|null, contentForHistory: string|Array|Record<string, any>|null }

### `buildMessages(params)`

Constructs message array in format expected by LangChain.

- **Parameters**
  - `params` (object)
    - `system` (string, optional) - System prompt
    - `messages` (BaseMessage[], optional) - Message history
    - `user` (any, optional) - User message
    - `attachments` (AiAttachment[], optional) - Attachments

- **Returns**
  - BaseMessage[] - Formatted messages
```

--------------------------------

### Send Prompt with MultiProviderAiWithHistory

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Sends a prompt using the `ask` method of `MultiProviderAiWithHistory`, incorporating conversation history. This method automatically manages context from the specified `chatId`, sends the query to multiple providers, stores the response, and returns the AI's answer. It supports system prompts, user messages, and attachments.

```javascript
const chatId = 'chat-abc';

const response = await aiWithHistory.ask(chatId, {
  system: 'You are a helpful assistant.',
  user: 'Tell me more about that.',
  attachments: [
    // AiAttachment objects can be added here
  ]
});
console.log(response);
```

--------------------------------

### Create Video Attachment for AI Prompt

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Defines a video attachment object for use in AI prompts. Supports both remote URLs and inline data. The format of the video must be specified.

```javascript
const videoAttachment = {
  type: 'video',
  // Option 1: Remote URL
  url: 'https://example.com/video.mp4',
  // Option 2: Inline data
  data: videoBuffer,
  format: 'mp4'
};
```

--------------------------------

### Groq AI With History Class

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Extends GroqAi with memory capabilities to maintain conversation history. Requires an AiMemoryStore instance during construction. Provides an `ask` method that includes chat history context and stores the response. Also includes a `clear` method to remove history for a specific chat.

```typescript
import { GroqAiWithHistory } from "@llmjs/groq";
import { InMemoryAiMemoryStore } from "@llmjs/core";

const memoryStore = new InMemoryAiMemoryStore();
const groqAiWithHistory = new GroqAiWithHistory({
  apiKey: "YOUR_GROQ_API_KEY",
  memoryStore: memoryStore,
  historyLimit: 5
});

async function askWithHistory() {
  const chatId = "user123";
  const response = await groqAiWithHistory.ask(chatId, {
    user: "Tell me a joke."
  });
  console.log(response);
  await groqAiWithHistory.clear(chatId);
}
```

--------------------------------

### AI Client and Response Handling

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Utilities for retrieving AI clients and extracting plain text from AI responses.

```APIDOC
## AI Client and Response Handling

### `getClient(model)`

Retrieves a cached LangChain client for the specified model.

- **Parameters**
  - `model` (string) - Model identifier

- **Returns**
  - ChatOpenAI - Configured client

### `extractText(aiMessage)`

Extracts plain text from AI response.

- **Parameters**
  - `aiMessage` (AIMessage|string|undefined) - AI response

- **Returns**
  - string - Extracted text
```

--------------------------------

### Classify Content with MultiProviderAi

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Employs the `classify` method of the `MultiProviderAi` class for content classification. It uses the first available provider that supports classification (currently Mistral). The method accepts text inputs and optional classification parameters, returning classification results including categories and scores. Errors are thrown if inputs are missing or no suitable providers are found.

```javascript
const inputsToClassify = ['This is a positive review.', 'I am very unhappy with the service.'];

try {
  const classification = await ai.classify(inputsToClassify, {
    model: 'mistralai/mistral-7b-instruct-v0.1',
    requestTimeoutMs: 10000
  });
  console.log('Classification Results:', classification);
} catch (error) {
  console.error('Content classification failed:', error);
}
```

--------------------------------

### Create Image Attachment

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Demonstrates how to create an `AiAttachment` object for an image. It shows two common methods: referencing an image via a remote URL and providing the image data directly as a Buffer or base64 string. The `mimeType` is optionally specified for clarity.

```javascript
// Option 1: Remote URL
const imageUrlAttachment = {
  type: 'image',
  url: 'https://example.com/image.jpg',
  mimeType: 'image/jpeg'
};

// Option 2: Inline data (assuming imageBuffer is a Buffer or base64 string)
const imageDataAttachment = {
  type: 'image',
  data: imageBuffer, 
  mimeType: 'image/jpeg'
};
```

--------------------------------

### Handle AI Request Errors

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Illustrates how to use a try-catch block to handle potential errors during AI requests, logging specific error details like message, status, and the original error.

```javascript
try {
  const response = await ai.ask({ user: 'Hello!' });
} catch (error) {
  console.error('AI request failed:', error.message);
  console.error('Status code:', error.status);
  console.error('Original error:', error.original);
}
```

--------------------------------

### Data Conversion Utilities

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Utility functions for converting data to base64 encoding, creating data URIs, and converting MIME types to format strings.

```APIDOC
## Data Conversion Utilities

### `toBase64(data)`

Converts data to base64 encoding.

- **Parameters**
  - `data` (string|Buffer|undefined) - Input data

- **Returns**
  - string|null - Base64 string or null

### `toDataUri(data, mimeType)`

Creates data URI from binary data.

- **Parameters**
  - `data` (string|Buffer|undefined) - Input data
  - `mimeType` (string) - MIME type

- **Returns**
  - string|null - Data URI or null

### `mimeTypeToFormat(mimeType)`

Converts MIME type to format string.

- **Parameters**
  - `mimeType` (string) - MIME type

- **Returns**
  - string|undefined - Format string
```

--------------------------------

### Transcribe Audio with MultiProviderAi

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Utilizes the `transcribe` method of the `MultiProviderAi` class to attempt audio transcription. This functionality is available through providers that support it, such as Groq and Mistral. The method returns the transcribed text and throws an error if no suitable providers are configured or if all transcription attempts fail.

```javascript
try {
  const transcription = await ai.transcribe({
    // Provider-specific transcription parameters can be added here
  });
  console.log('Transcription:', transcription);
} catch (error) {
  console.error('Transcription failed:', error);
}
```

--------------------------------

### GroqAi Class

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

A specialized AI implementation for Groq, offering the same API as the base `Ai` class but tailored for Groq's models and services.

```APIDOC
## GroqAi Class

Groq-specific AI implementation with same API as Ai class.

### Constructor

#### `new GroqAi(options)`

Creates a new Groq AI instance.

- **Parameters**
  - `options` (object)
    - `apiKey` (string, required) - Groq API key
    - `model` (string, optional) - Default model (default: "llama-3.1-70b-versatile")
    - `fallbackModels` (string[], optional) - Fallback models
    - `temperature` (number, optional) - Sampling temperature (default: 0.7)
    - `maxTokens` (number, optional) - Maximum tokens (default: 1000)
    - `requestTimeoutMs` (number, optional) - Request timeout (default: 20000)
    - `firstToFinish` (boolean, optional) - When true, races all configured Groq models in parallel for each call and returns the first successful result

- **Throws**
  - Error if apiKey missing
```

--------------------------------

### Multi-Provider AI with Conversation History Management

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Demonstrates using `MultiProviderAiWithHistory` to manage conversation history across multiple AI providers. It integrates with a MongoDB `AiMemoryStore` for persistence and allows for specifying memory scope and history limits.

```javascript
const memoryStore = new AiMemoryStore({
  uri: 'mongodb://localhost:27017',
  dbName: 'myapp',
  collectionName: 'ai_memory'
});

const multiAiWithHistory = new MultiProviderAiWithHistory({
  apiKeys: {
    openrouter: 'your-openrouter-key',
    mistral: 'your-mistral-key',
    groq: 'your-groq-key'
  },
  model: {
    provider: 'openrouter',
    name: 'meta-llama/llama-3.3-70b-instruct:free'
  },
  memoryStore,
  memoryScope: 'user123',
  historyLimit: 20
});

// Chat with memory across providers
await multiAiWithHistory.ask('chat1', {
  user: 'Remember my favorite color is blue'
});

await multiAiWithHistory.ask('chat1', {
  user: 'What did I tell you about my preferences?'
});

// Clear conversation history
await multiAiWithHistory.clear('chat1');
```

--------------------------------

### Groq AI Transcribe Function

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Transcribes audio files using the Groq Whisper model. Accepts a file path, buffer, or stream, and allows specifying a transcription model and temperature. Returns a promise that resolves with the transcribed text. Throws an error if the file is missing or transcription fails.

```typescript
import { GroqAi } from "@llmjs/groq";
import * as fs from 'fs';

const groq = new GroqAi({
  apiKey: "YOUR_GROQ_API_KEY"
});

async function transcribeAudio() {
  const audioFile = fs.readFileSync("./audio.mp3");
  const transcription = await groq.transcribe({
    file: audioFile,
    model: "whisper-large-v3-turbo",
    temperature: 0.2
  });
  console.log(transcription);
}
```

--------------------------------

### Mistral AI With History Class

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Extends MistralAi with memory capabilities to maintain conversation history. Requires an AiMemoryStore instance during construction. Provides an `ask` method that includes chat history context and stores the response. Also includes a `clear` method to remove history for a specific chat.

```typescript
import { MistralAiWithHistory } from "@llmjs/mistral";
import { RedisAiMemoryStore } from "@llmjs/redis";

const memoryStore = new RedisAiMemoryStore({ url: "redis://localhost:6379" });
const mistralAiWithHistory = new MistralAiWithHistory({
  apiKey: "YOUR_MISTRAL_API_KEY",
  memoryStore: memoryStore,
  memoryScope: "chat-session-1",
  historyLimit: 20
});

async function askMistralWithHistory() {
  const chatId = "user456";
  const response = await mistralAiWithHistory.ask(chatId, {
    user: "What is the capital of France?"
  });
  console.log(response);
  await mistralAiWithHistory.clear(chatId);
}
```

--------------------------------

### JavaScript: Manage AI Conversation Context with Custom Message History

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

This snippet demonstrates how to use custom message history with the Ai client for managing conversation context. It shows the creation of a history array using SystemMessage, HumanMessage, and AIMessage from '@langchain/core/messages', and how to pass this history to the `ai.ask` method to maintain conversational flow. It also shows how to prepend a system prompt to an existing history.

```javascript
const { Ai } = require('@oof2510/llmjs');
const { HumanMessage, AIMessage, SystemMessage } = require('@langchain/core/messages');

const ai = new Ai({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: 'meta-llama/llama-3.3-70b-instruct:free'
});

(async () => {
  // Build custom conversation history
  const conversationHistory = [
    new SystemMessage('You are a knowledgeable history teacher.'),
    new HumanMessage('Who was the first president of the United States?'),
    new AIMessage('George Washington was the first president of the United States, serving from 1789 to 1797.'),
    new HumanMessage('What were his major accomplishments?'),
    new AIMessage('Washington established many precedents including the cabinet system, set the two-term tradition, maintained neutrality in foreign conflicts, and successfully led the nation through its formative years.')
  ];

  // Continue the conversation with context
  const response = await ai.ask({
    messages: conversationHistory,
    user: 'Did he have any military experience before becoming president?'
  });

  console.log('Response:', response);
  // Output: "Yes, George Washington was a highly experienced military leader..."

  // Add system prompt to existing history
  const response2 = await ai.ask({
    system: 'Focus on economic aspects in your answers.',
    messages: conversationHistory,
    user: 'How did his policies affect the economy?'
  });

  console.log('Economic analysis:', response2);
})();
```

--------------------------------

### Mistral AI Transcribe Function

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Transcribes audio files using Mistral Voxtral. Accepts a file path, buffer, or stream, and allows specifying a transcription model, language, and timestamp granularities. Returns a promise that resolves with the transcribed text. Throws an error if the file is missing or transcription fails.

```typescript
import { MistralAi } from "@llmjs/mistral";
import * as fs from 'fs';

const mistral = new MistralAi({
  apiKey: "YOUR_MISTRAL_API_KEY"
});

async function transcribeMistralAudio() {
  const audioStream = fs.createReadStream("./audio.wav");
  const transcription = await mistral.transcribe({
    file: audioStream,
    model: "voxtral-mini-latest",
    language: "en",
    timestamp_granularities: ["word"]
  });
  console.log(transcription);
}
```

--------------------------------

### AiWithHistory Class

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Extends the base `Ai` class with persistent memory capabilities for managing conversation history.

```APIDOC
## AiWithHistory Class

Extends `Ai` with persistent memory capabilities.

### Constructor

#### `new AiWithHistory(options)`

Creates a new AI instance with conversation history support.

- **Parameters**
  - `options` (object)
    - `memoryStore` (AiMemoryStore, required) - Memory store instance
    - `memoryScope` (string, optional) - Memory namespace (default: "default")
    - `historyLimit` (number, optional) - Messages to remember (default: 10)
    - `...other Ai options`

### Methods

#### `ask(chatId, options)`

Fetches chat history, asks AI, and stores both user and bot messages.

- **Parameters**
  - `chatId` (string|number, required) - Conversation identifier
  - `options` (object, optional)
    - `system` (string, optional) - System prompt
    - `user` (any, optional) - User message
    - `attachments` (AiAttachment[], optional) - Attachments

- **Returns**
  - Promise<string> - AI response

- **Throws**
  - Error if chatId missing

#### `clear(chatId)`

Clears conversation history for a chat.

- **Parameters**
  - `chatId` (string|number, required) - Conversation identifier

- **Returns**
  - Promise<void>
```

--------------------------------

### Define AiAttachment Interface

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Defines the `AiAttachment` interface, which specifies the structure for multimodal inputs like images and videos. Attachments can be provided via a remote URL or raw data (string or Buffer), along with optional MIME type and format hints.

```typescript
interface AiAttachment {
  type: "image" | "video";
  url?: string; // Remote URL
  data?: string | Buffer; // Raw file contents
  mimeType?: string; // MIME type hint
  format?: string; // Format override
}
```

--------------------------------

### Mistral AI Classify Function

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Classifies text inputs using Mistral moderation models. Accepts a single string or an array of strings, and allows specifying the moderation model and request timeout. Returns a promise that resolves with classification results, including categories and scores. Throws an error if inputs are missing or invalid.

```typescript
import { MistralAi } from "@llmjs/mistral";

const mistral = new MistralAi({
  apiKey: "YOUR_MISTRAL_API_KEY"
});

async function classifyText() {
  const inputs = [
    "This is a safe message.",
    "This is a harmful message."
  ];
  const results = await mistral.classify(inputs, {
    model: "mistral-moderation-latest"
  });
  console.log(results);
}
```

--------------------------------

### Conversation History with MongoDB using llmjs

Source: https://context7.com/oof2510/llmjs-npm/llms.txt

Maintain persistent conversation context across multiple interactions using MongoDB storage. This feature allows an AI to remember previous parts of a conversation, enabling more coherent and context-aware responses. It requires a running MongoDB instance and proper connection URI.

```javascript
const { AiMemoryStore, AiWithHistory } = require('@oof2510/llmjs');

// Initialize MongoDB memory store
const memoryStore = new AiMemoryStore({
  uri: 'mongodb://localhost:27017',
  dbName: 'chatbot_db',
  collectionName: 'conversations'
});

const aiWithHistory = new AiWithHistory({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: 'meta-llama/llama-3.3-70b-instruct:free',
  memoryStore: memoryStore,
  memoryScope: 'user_12345', // Unique scope per user
  historyLimit: 20, // Remember last 20 messages
  temperature: 0.7
});

(async () => {
  try {
    // First conversation
    const response1 = await aiWithHistory.ask('chat_session_1', {
      system: 'You are a helpful shopping assistant.',
      user: 'I need a laptop for video editing. My budget is $2000.'
    });
    console.log('Bot:', response1);
    // Output: "For video editing at that budget, I'd recommend..."

    // Second message - AI remembers context
    const response2 = await aiWithHistory.ask('chat_session_1', {
      user: 'What about battery life?'
    });
    console.log('Bot:', response2);
    // Output: "For video editing laptops in your $2000 budget range..."

    // Third message - continues remembering
    const response3 = await aiWithHistory.ask('chat_session_1', {
      user: 'Which brand is most reliable?'
    });
    console.log('Bot:', response3);

    // Clear conversation history
    await aiWithHistory.clear('chat_session_1');
    console.log('Conversation history cleared');

    // Cleanup
    await memoryStore.disconnect();
  } catch (error) {
    console.error('Error:', error.message);
    await memoryStore.disconnect();
  }
})();
```

--------------------------------

### Clear Chat History with MultiProviderAiWithHistory

Source: https://github.com/oof2510/llmjs-npm/blob/main/README.md

Removes conversation history for a specific chat across all configured providers using the `clear` method of `MultiProviderAiWithHistory`. This operation is asynchronous and returns a Promise that resolves when the history has been cleared.

```javascript
const chatId = 'chat-abc';

await aiWithHistory.clear(chatId);
console.log(`Conversation history for ${chatId} cleared.`);
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.