Use and adapt AI-Model-Wrapper-for-OpenAI

Use the documented interfaces and source layout for AI-Model-Wrapper-for-OpenAI. The sections below retain the README’s examples and configuration details.

Usage Examples

1. Basic Text Conversations

1// Method 1: One-liner approach
2const response1 = await ai.sendTextMessage('Tell me a joke about programming');
3 
4// Method 2: Conversation chain
5const response2 = await ai
6  .addUserMessage('Hello!')
7  .addAssistantMessage('Hi there! How can I help you?')
8  .addUserMessage('What is the capital of France?')
9  .send();
10 
11// Method 3: Multiple messages at once
12const response3 = await ai.sendMultipleMessages([
13  { role: 'user', content: 'Hello' },
14  { role: 'assistant', content: 'Hi! How can I help?' },
15  { role: 'user', content: 'Tell me about TypeScript' }
16]);

2. Image Analysis

1// Analyze image with text question
2const imageResponse = await ai.sendImageMessage(
3  'What do you see in this image? Describe the main elements.',
4  'https://example.com/image.jpg'
5);
6 
7// Or use the chain method
8const imageAnalysis = await ai
9  .addImageMessage('Analyze this image', 'https://example.com/photo.jpg')
10  .send();

3. Streaming Responses

1// Stream response in real-time
2const fullResponse = await ai.stream((chunk) => {
3  process.stdout.write(chunk); // Print as it comes
4});
5 
6// Streaming with custom options
7const streamedText = await ai.stream(
8  (chunk) => console.log('Chunk:', chunk),
9  { temperature: 0.9, maxTokens: 500 }
10);

4. System Prompts and Context

1// Set AI personality/behavior
2const aiWithPersonality = new AIModel({
3  apiKey: 'your-key',
4  provider: 'openai'
5}).setSystemPrompt(`
6  You are a knowledgeable historian specializing in European history.
7  Provide detailed, accurate information with dates and context.
8  Be engaging but factual in your responses.
9`);
10 
11const historyResponse = await aiWithPersonality
12  .addUserMessage('Tell me about the Renaissance period')
13  .send();

5. Configuration Management

1import { ConfigManager } from './ai-model-lib';
2 
3// Global configuration
4const config = ConfigManager.getInstance();
5config.setDefaultConfig({
6  temperature: 0.7,
7  maxTokens: 1500,
8  debug: process.env.NODE_ENV === 'development',
9  retryAttempts: 5
10});
11 
12// Create pre-configured models
13const ai = config.createModel({
14  apiKey: process.env.OPENAI_API_KEY,
15  model: 'gpt-4'
16});

6. Error Handling and Retries

1try {
2  const response = await ai
3    .addUserMessage('Generate a long story about space exploration')
4    .send({ maxTokens: 2000 });
5    
6  console.log('Success:', response.content);
7  
8} catch (error) {
9  if (error.message.includes('API key')) {
10    console.error('Authentication failed - check your API key');
11  } else if (error.message.includes('rate limit')) {
12    console.error('Rate limit exceeded - try again later');
13  } else if (error.message.includes('timeout')) {
14    console.error('Request timed out - check your connection');
15  } else {
16    console.error('Unexpected error:', error.message);
17  }
18}

7. Advanced Conversation Management

1// Complex conversation with context
2const conversation = await ai
3  .setSystemPrompt('You are a helpful travel assistant. Provide concise, practical advice.')
4  .addUserMessage('I want to visit Japan next month')
5  .addAssistantMessage('Great choice! Japan is wonderful. What cities are you thinking of visiting?')
6  .addUserMessage('Tokyo and Kyoto for 10 days')
7  .addAssistantMessage('Excellent itinerary. Tokyo for modern experiences, Kyoto for tradition.')
8  .addUserMessage('What should I pack for April?')
9  .send();
10 
11console.log('Travel advice:', conversation.content);
12 
13// Check conversation history
14const messages = ai.getMessages();
15messages.forEach((msg, index) => {
16  console.log(`${index + 1}. ${msg.role}: ${msg.content}`);
17});

Configuration

Model Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	Required	Provider API key
`provider`	`string`	`"openrouter"`	Provider ID
`model`	`string`	Provider default	Specific model name
`temperature`	`number`	`0.7`	Creativity (0.0-1.0)
`maxTokens`	`number`	`1000`	Response length limit
`systemPrompt`	`string`	`""`	AI context/behavior
`debug`	`boolean`	`false`	Enable logging
`timeout`	`number`	`30000`	Request timeout (ms)
`retryAttempts`	`number`	`3`	Retry attempts on failure

Provider Configuration

1import { ProviderRegistry } from './ai-model-lib';
2 
3// Register custom provider
4ProviderRegistry.registerProvider('my-provider', {
5  name: 'My AI Service',
6  baseURL: 'https://api.my-ai.com/v1',
7  defaultModel: 'my-model-v1',
8  headers: {
9    'X-Custom-Header': 'value'
10  }
11});

Core Concepts

Message Types

Type	Description	Example
Text Message	Simple text content	`"Hello world"`
Image Message	Text + image URL	`{ text: "Describe this", imageUrl: "..." }`
System Prompt	AI behavior/context	`"You are a helpful assistant"`
Structured Message	Multiple content parts	`[{ type: "text", text: "..." }, { type: "image_url", ... }]`

Provider Support

Provider	Default Model	Base URL	Features
OpenRouter	`mistralai/mistral-small-3.1-24b-instruct:free`	`https://openrouter.ai/api/v1`	Multiple models, free tier
OpenAI	`gpt-3.5-turbo`	`https://api.openai.com/v1`	GPT models, vision
Anthropic	`claude-3-haiku-20240307`	`https://api.anthropic.com/v1`	Claude models
Custom	User-defined	User-defined	Any OpenAI-compatible API

API Reference

AIModel Class

Constructor

1new AIModel(config: AIModelConfig, logger?: Logger)

Parameter	Type	Required	Description
`config`	`AIModelConfig`	Yes	Model configuration
`logger`	`Logger`	No	Custom logger instance

Core Methods

Method	Returns	Description
`send(options?)`	`Promise<AIResponse>`	Send conversation and get response
`stream(onChunk, options?)`	`Promise<string>`	Stream response in real-time
`sendTextMessage(text, options?)`	`Promise<AIResponse>`	Quick text message and response
`sendImageMessage(text, imageUrl, options?)`	`Promise<AIResponse>`	Quick image analysis
`sendMultipleMessages(messages, options?)`	`Promise<AIResponse>`	Send multiple messages at once

Message Management

Method	Returns	Description
`addMessage(content, role)`	`this`	Add message to conversation
`addUserMessage(content)`	`this`	Add user message
`addAssistantMessage(content)`	`this`	Add assistant message
`addTextMessage(text, role)`	`this`	Add text message
`addImageMessage(text, imageUrl)`	`this`	Add image with text
`getMessages()`	`Message[]`	Get all messages
`clearMessages()`	`this`	Clear conversation history
`reset()`	`this`	Reset model (messages + system prompt)

Configuration Methods

Method	Returns	Description
`setSystemPrompt(prompt)`	`this`	Set/update system prompt
`getSystemPrompt()`	`string`	Get current system prompt
`updateConfig(config)`	`this`	Update model configuration
`getConfig()`	`AIModelConfig`	Get current configuration
`enableDebug(enable)`	`this`	Enable/disable debug logging

Static Factory Methods

Method	Returns	Description
`create(config, logger?)`	`AIModel`	Create new instance
`createFromEnv(provider?, overrides?, logger?)`	`AIModel`	Create from environment variables
`createForProvider(providerId, apiKey, overrides?, logger?)`	`AIModel`	Create for specific provider

AIResponse Interface

Property	Type	Description
`content`	`string`	Generated text response
`usage.promptTokens`	`number`	Input tokens used
`usage.completionTokens`	`number`	Output tokens used
`usage.totalTokens`	`number`	Total tokens used
`model`	`string`	Model that generated response
`finishReason`	`string`	Reason generation stopped

ProviderRegistry Class

Method	Returns	Description
`registerProvider(id, config)`	`void`	Register new provider
`getProvider(id)`	`AIProviderConfig	undefined`
`getAllProviders()`	`Map<string, AIProviderConfig>`	Get all providers
`updateProvider(id, config)`	`boolean`	Update provider config
`hasProvider(id)`	`boolean`	Check if provider exists
`removeProvider(id)`	`boolean`	Remove provider

Error Handling

Common Error Types

Error Type	Cause	Solution
AuthenticationError	Invalid API key	Check API key validity
RateLimitError	Too many requests	Implement backoff, upgrade plan
TimeoutError	Request timeout	Increase timeout, check network
ModelNotFound	Invalid model name	Check provider model list
ProviderNotFound	Unknown provider	Register provider or check spelling

Retry Configuration

1const resilientAI = new AIModel({
2  apiKey: 'your-key',
3  provider: 'openai',
4  retryAttempts: 5,           // 5 retry attempts
5  timeout: 60000,             // 60 second timeout
6  debug: true
7});
8 
9// Automatic retry with exponential backoff:
10// Attempt 1: Immediate
11// Attempt 2: 2 second delay  
12// Attempt 3: 4 second delay
13// Attempt 4: 8 second delay
14// Attempt 5: 16 second delay

Troubleshooting

Common Issues

Issue	Solution
Module not found	Check import path, ensure dependencies installed
API key errors	Verify API key, check provider requirements
Network timeouts	Increase timeout setting, check firewall
Model not available	Check provider documentation for available models
TypeScript errors	Ensure proper types are imported

Debug Mode

1// Enable debug logging
2const ai = new AIModel({
3  apiKey: 'your-key',
4  provider: 'openai',
5  debug: true  // Enable detailed logging
6});
7 
8// Or enable later
9ai.enableDebug(true);

Source and help

Use the documented interfaces and source layout for AI-Model-Wrapper-for-OpenAI. The sections below retain the README’s examples and configuration details.

Usage Examples

1. Basic Text Conversations

1// Method 1: One-liner approach
2const response1 = await ai.sendTextMessage('Tell me a joke about programming');
3 
4// Method 2: Conversation chain
5const response2 = await ai
6  .addUserMessage('Hello!')
7  .addAssistantMessage('Hi there! How can I help you?')
8  .addUserMessage('What is the capital of France?')
9  .send();
10 
11// Method 3: Multiple messages at once
12const response3 = await ai.sendMultipleMessages([
13  { role: 'user', content: 'Hello' },
14  { role: 'assistant', content: 'Hi! How can I help?' },
15  { role: 'user', content: 'Tell me about TypeScript' }
16]);

2. Image Analysis

1// Analyze image with text question
2const imageResponse = await ai.sendImageMessage(
3  'What do you see in this image? Describe the main elements.',
4  'https://example.com/image.jpg'
5);
6 
7// Or use the chain method
8const imageAnalysis = await ai
9  .addImageMessage('Analyze this image', 'https://example.com/photo.jpg')
10  .send();

3. Streaming Responses

1// Stream response in real-time
2const fullResponse = await ai.stream((chunk) => {
3  process.stdout.write(chunk); // Print as it comes
4});
5 
6// Streaming with custom options
7const streamedText = await ai.stream(
8  (chunk) => console.log('Chunk:', chunk),
9  { temperature: 0.9, maxTokens: 500 }
10);

4. System Prompts and Context

1// Set AI personality/behavior
2const aiWithPersonality = new AIModel({
3  apiKey: 'your-key',
4  provider: 'openai'
5}).setSystemPrompt(`
6  You are a knowledgeable historian specializing in European history.
7  Provide detailed, accurate information with dates and context.
8  Be engaging but factual in your responses.
9`);
10 
11const historyResponse = await aiWithPersonality
12  .addUserMessage('Tell me about the Renaissance period')
13  .send();

5. Configuration Management

1import { ConfigManager } from './ai-model-lib';
2 
3// Global configuration
4const config = ConfigManager.getInstance();
5config.setDefaultConfig({
6  temperature: 0.7,
7  maxTokens: 1500,
8  debug: process.env.NODE_ENV === 'development',
9  retryAttempts: 5
10});
11 
12// Create pre-configured models
13const ai = config.createModel({
14  apiKey: process.env.OPENAI_API_KEY,
15  model: 'gpt-4'
16});

6. Error Handling and Retries

1try {
2  const response = await ai
3    .addUserMessage('Generate a long story about space exploration')
4    .send({ maxTokens: 2000 });
5    
6  console.log('Success:', response.content);
7  
8} catch (error) {
9  if (error.message.includes('API key')) {
10    console.error('Authentication failed - check your API key');
11  } else if (error.message.includes('rate limit')) {
12    console.error('Rate limit exceeded - try again later');
13  } else if (error.message.includes('timeout')) {
14    console.error('Request timed out - check your connection');
15  } else {
16    console.error('Unexpected error:', error.message);
17  }
18}

7. Advanced Conversation Management

1// Complex conversation with context
2const conversation = await ai
3  .setSystemPrompt('You are a helpful travel assistant. Provide concise, practical advice.')
4  .addUserMessage('I want to visit Japan next month')
5  .addAssistantMessage('Great choice! Japan is wonderful. What cities are you thinking of visiting?')
6  .addUserMessage('Tokyo and Kyoto for 10 days')
7  .addAssistantMessage('Excellent itinerary. Tokyo for modern experiences, Kyoto for tradition.')
8  .addUserMessage('What should I pack for April?')
9  .send();
10 
11console.log('Travel advice:', conversation.content);
12 
13// Check conversation history
14const messages = ai.getMessages();
15messages.forEach((msg, index) => {
16  console.log(`${index + 1}. ${msg.role}: ${msg.content}`);
17});

Configuration

Model Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	Required	Provider API key
`provider`	`string`	`"openrouter"`	Provider ID
`model`	`string`	Provider default	Specific model name
`temperature`	`number`	`0.7`	Creativity (0.0-1.0)
`maxTokens`	`number`	`1000`	Response length limit
`systemPrompt`	`string`	`""`	AI context/behavior
`debug`	`boolean`	`false`	Enable logging
`timeout`	`number`	`30000`	Request timeout (ms)
`retryAttempts`	`number`	`3`	Retry attempts on failure

Provider Configuration

1import { ProviderRegistry } from './ai-model-lib';
2 
3// Register custom provider
4ProviderRegistry.registerProvider('my-provider', {
5  name: 'My AI Service',
6  baseURL: 'https://api.my-ai.com/v1',
7  defaultModel: 'my-model-v1',
8  headers: {
9    'X-Custom-Header': 'value'
10  }
11});

Core Concepts

Message Types

Type	Description	Example
Text Message	Simple text content	`"Hello world"`
Image Message	Text + image URL	`{ text: "Describe this", imageUrl: "..." }`
System Prompt	AI behavior/context	`"You are a helpful assistant"`
Structured Message	Multiple content parts	`[{ type: "text", text: "..." }, { type: "image_url", ... }]`

Provider Support

Provider	Default Model	Base URL	Features
OpenRouter	`mistralai/mistral-small-3.1-24b-instruct:free`	`https://openrouter.ai/api/v1`	Multiple models, free tier
OpenAI	`gpt-3.5-turbo`	`https://api.openai.com/v1`	GPT models, vision
Anthropic	`claude-3-haiku-20240307`	`https://api.anthropic.com/v1`	Claude models
Custom	User-defined	User-defined	Any OpenAI-compatible API

API Reference

AIModel Class

Constructor

1new AIModel(config: AIModelConfig, logger?: Logger)

Parameter	Type	Required	Description
`config`	`AIModelConfig`	Yes	Model configuration
`logger`	`Logger`	No	Custom logger instance

Core Methods

Method	Returns	Description
`send(options?)`	`Promise<AIResponse>`	Send conversation and get response
`stream(onChunk, options?)`	`Promise<string>`	Stream response in real-time
`sendTextMessage(text, options?)`	`Promise<AIResponse>`	Quick text message and response
`sendImageMessage(text, imageUrl, options?)`	`Promise<AIResponse>`	Quick image analysis
`sendMultipleMessages(messages, options?)`	`Promise<AIResponse>`	Send multiple messages at once

Message Management

Method	Returns	Description
`addMessage(content, role)`	`this`	Add message to conversation
`addUserMessage(content)`	`this`	Add user message
`addAssistantMessage(content)`	`this`	Add assistant message
`addTextMessage(text, role)`	`this`	Add text message
`addImageMessage(text, imageUrl)`	`this`	Add image with text
`getMessages()`	`Message[]`	Get all messages
`clearMessages()`	`this`	Clear conversation history
`reset()`	`this`	Reset model (messages + system prompt)

Configuration Methods

Method	Returns	Description
`setSystemPrompt(prompt)`	`this`	Set/update system prompt
`getSystemPrompt()`	`string`	Get current system prompt
`updateConfig(config)`	`this`	Update model configuration
`getConfig()`	`AIModelConfig`	Get current configuration
`enableDebug(enable)`	`this`	Enable/disable debug logging

Static Factory Methods

Method	Returns	Description
`create(config, logger?)`	`AIModel`	Create new instance
`createFromEnv(provider?, overrides?, logger?)`	`AIModel`	Create from environment variables
`createForProvider(providerId, apiKey, overrides?, logger?)`	`AIModel`	Create for specific provider

AIResponse Interface

Property	Type	Description
`content`	`string`	Generated text response
`usage.promptTokens`	`number`	Input tokens used
`usage.completionTokens`	`number`	Output tokens used
`usage.totalTokens`	`number`	Total tokens used
`model`	`string`	Model that generated response
`finishReason`	`string`	Reason generation stopped

ProviderRegistry Class

Method	Returns	Description
`registerProvider(id, config)`	`void`	Register new provider
`getProvider(id)`	`AIProviderConfig	undefined`
`getAllProviders()`	`Map<string, AIProviderConfig>`	Get all providers
`updateProvider(id, config)`	`boolean`	Update provider config
`hasProvider(id)`	`boolean`	Check if provider exists
`removeProvider(id)`	`boolean`	Remove provider

Error Handling

Common Error Types

Error Type	Cause	Solution
AuthenticationError	Invalid API key	Check API key validity
RateLimitError	Too many requests	Implement backoff, upgrade plan
TimeoutError	Request timeout	Increase timeout, check network
ModelNotFound	Invalid model name	Check provider model list
ProviderNotFound	Unknown provider	Register provider or check spelling

Retry Configuration

1const resilientAI = new AIModel({
2  apiKey: 'your-key',
3  provider: 'openai',
4  retryAttempts: 5,           // 5 retry attempts
5  timeout: 60000,             // 60 second timeout
6  debug: true
7});
8 
9// Automatic retry with exponential backoff:
10// Attempt 1: Immediate
11// Attempt 2: 2 second delay  
12// Attempt 3: 4 second delay
13// Attempt 4: 8 second delay
14// Attempt 5: 16 second delay

Troubleshooting

Common Issues

Issue	Solution
Module not found	Check import path, ensure dependencies installed
API key errors	Verify API key, check provider requirements
Network timeouts	Increase timeout setting, check firewall
Model not available	Check provider documentation for available models
TypeScript errors	Ensure proper types are imported

Debug Mode

1// Enable debug logging
2const ai = new AIModel({
3  apiKey: 'your-key',
4  provider: 'openai',
5  debug: true  // Enable detailed logging
6});
7 
8// Or enable later
9ai.enableDebug(true);