@bernierllc/ai-provider-openai 1.0.0

package/.eslintrc.js

@@ -0,0 +1,35 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code only within the scope of the project it was delivered for.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking'
+  ],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json',
+    tsconfigRootDir: __dirname
+  },
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'warn',
+    '@typescript-eslint/no-unused-vars': ['error', {
+      argsIgnorePattern: '^_',
+      varsIgnorePattern: '^_'
+    }]
+  },
+  env: {
+    node: true,
+    jest: true
+  }
+};

package/README.md

@@ -0,0 +1,294 @@
+# @bernierllc/ai-provider-openai
+
+OpenAI API adapter implementing the unified AI provider interface for seamless integration across BernierLLC projects.
+
+## Installation
+
+```bash
+npm install @bernierllc/ai-provider-openai
+# or
+pnpm add @bernierllc/ai-provider-openai
+```
+
+## Features
+
+- **Complete OpenAI API Support**: GPT-4, GPT-3.5, embeddings, moderation, vision
+- **Streaming Completions**: Real-time text generation with async generators
+- **Function Calling**: Support for OpenAI function calling capabilities
+- **Vision Analysis**: GPT-4 Vision for image understanding
+- **Cost Estimation**: Accurate token and cost estimation before requests
+- **Type Safety**: Full TypeScript support with strict typing
+- **Error Handling**: Comprehensive error handling with retry logic
+- **Health Monitoring**: API health checks and availability detection
+
+## Usage
+
+### Basic Completion
+
+```typescript
+import { OpenAIProvider } from '@bernierllc/ai-provider-openai';
+
+const provider = new OpenAIProvider({
+  providerName: 'openai',
+  apiKey: process.env.OPENAI_API_KEY!,
+  defaultModel: 'gpt-4-turbo',
+  timeout: 30000,
+  maxRetries: 3
+});
+
+// Generate completion
+const response = await provider.complete({
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'Explain TypeScript generics in simple terms.' }
+  ],
+  maxTokens: 500,
+  temperature: 0.7
+});
+
+if (response.success) {
+  console.log(response.content);
+  console.log(`Tokens used: ${response.usage?.totalTokens}`);
+}
+```
+
+### Streaming Completion
+
+```typescript
+console.log('Generating response...\n');
+
+for await (const chunk of provider.streamComplete({
+  messages: [
+    { role: 'user', content: 'Write a short poem about coding' }
+  ]
+})) {
+  process.stdout.write(chunk.delta);
+
+  if (chunk.finishReason) {
+    console.log(`\n\nFinished: ${chunk.finishReason}`);
+    if (chunk.usage) {
+      console.log(`Tokens: ${chunk.usage.totalTokens}`);
+    }
+  }
+}
+```
+
+### Function Calling
+
+```typescript
+const response = await provider.completionWithFunctions({
+  messages: [
+    { role: 'user', content: 'What is the weather in San Francisco?' }
+  ],
+  functions: [
+    {
+      name: 'get_weather',
+      description: 'Get the current weather for a location',
+      parameters: {
+        type: 'object',
+        properties: {
+          location: {
+            type: 'string',
+            description: 'The city and state, e.g. San Francisco, CA'
+          },
+          unit: {
+            type: 'string',
+            enum: ['celsius', 'fahrenheit']
+          }
+        },
+        required: ['location']
+      }
+    }
+  ]
+});
+
+if (response.metadata?.functionCall) {
+  console.log('Function call:', response.metadata.functionCall);
+  // { name: 'get_weather', arguments: '{"location":"San Francisco, CA"}' }
+}
+```
+
+### Vision Analysis
+
+```typescript
+const analysis = await provider.analyzeImage(
+  'https://example.com/image.jpg',
+  'What objects do you see in this image?',
+  'gpt-4-vision-preview'
+);
+
+if (analysis.success) {
+  console.log(analysis.content);
+}
+```
+
+### Embeddings
+
+```typescript
+const embeddings = await provider.generateEmbeddings({
+  input: [
+    'TypeScript is a typed superset of JavaScript',
+    'Python is a high-level programming language'
+  ],
+  model: 'text-embedding-3-small'
+});
+
+if (embeddings.success) {
+  console.log(`Generated ${embeddings.embeddings?.length} embeddings`);
+  console.log(`Dimensions: ${embeddings.embeddings?.[0].length}`);
+}
+```
+
+### Content Moderation
+
+```typescript
+const moderation = await provider.moderate(
+  'Some content to check for policy violations'
+);
+
+if (moderation.success) {
+  console.log(`Flagged: ${moderation.flagged}`);
+  if (moderation.flagged) {
+    console.log('Violated categories:', moderation.categories);
+  }
+}
+```
+
+### Cost Estimation
+
+```typescript
+const request = {
+  messages: [
+    { role: 'user', content: 'Write a detailed article about TypeScript' }
+  ],
+  maxTokens: 2000
+};
+
+const cost = provider.estimateCost(request);
+console.log(`Estimated cost: $${cost.estimatedCostUSD.toFixed(4)}`);
+console.log(`Input tokens: ${cost.inputTokens}`);
+console.log(`Output tokens: ${cost.outputTokens}`);
+```
+
+## API
+
+### Constructor
+
+```typescript
+new OpenAIProvider(config: OpenAIProviderConfig)
+```
+
+Configuration options:
+
+- `providerName`: Must be `'openai'`
+- `apiKey`: OpenAI API key (required)
+- `defaultModel`: Default model to use (optional, defaults to 'gpt-4-turbo')
+- `organizationId`: OpenAI organization ID (optional)
+- `baseURL`: Custom API base URL (optional)
+- `timeout`: Request timeout in milliseconds (optional, default: 60000)
+- `maxRetries`: Maximum retry attempts (optional, default: 3)
+
+### Methods
+
+#### Core Methods (Implements AIProvider interface)
+
+- `complete(request: CompletionRequest): Promise<CompletionResponse>` - Generate text completion
+- `streamComplete(request: CompletionRequest): AsyncGenerator<StreamChunk>` - Stream completion chunks
+- `generateEmbeddings(request: EmbeddingRequest): Promise<EmbeddingResponse>` - Generate embeddings
+- `moderate(content: string): Promise<ModerationResponse>` - Check content moderation
+- `getAvailableModels(): Promise<ModelInfo[]>` - List available models
+- `checkHealth(): Promise<HealthStatus>` - Check API health
+- `estimateCost(request: CompletionRequest): CostEstimate` - Estimate request cost
+
+#### OpenAI-Specific Methods
+
+- `completionWithFunctions(request & { functions }): Promise<CompletionResponse>` - Chat completion with function calling
+- `analyzeImage(imageUrl: string, prompt: string, model?: string): Promise<CompletionResponse>` - Analyze image with GPT-4 Vision
+
+## Available Models
+
+### Chat Models
+
+- **gpt-4-turbo** - 128K context, latest GPT-4 with improved performance
+- **gpt-4** - 8K context, powerful reasoning and understanding
+- **gpt-4-32k** - 32K context, extended context window
+- **gpt-3.5-turbo** - 16K context, fast and cost-effective
+- **gpt-4-vision-preview** - GPT-4 with vision capabilities
+
+### Embedding Models
+
+- **text-embedding-3-small** - 1536 dimensions, cost-effective embeddings
+- **text-embedding-3-large** - 3072 dimensions, higher quality embeddings
+- **text-embedding-ada-002** - 1536 dimensions, legacy embedding model
+
+## Pricing
+
+Pricing is automatically handled based on the model used:
+
+- **GPT-4 Turbo**: $0.01/1K input tokens, $0.03/1K output tokens
+- **GPT-4**: $0.03/1K input tokens, $0.06/1K output tokens
+- **GPT-3.5 Turbo**: $0.0005/1K input tokens, $0.0015/1K output tokens
+- **Embeddings (3-small)**: $0.00002/1K tokens
+- **Embeddings (3-large)**: $0.00013/1K tokens
+
+## Error Handling
+
+The package provides comprehensive error handling:
+
+```typescript
+try {
+  const response = await provider.complete({ messages: [...] });
+  if (!response.success) {
+    console.error('Error:', response.error);
+  }
+} catch (error) {
+  // Handles network errors, timeouts, etc.
+  console.error('Request failed:', error);
+}
+```
+
+Error codes:
+- `INVALID_REQUEST` - Invalid request parameters
+- `AUTHENTICATION_ERROR` - Invalid API key
+- `PERMISSION_DENIED` - Insufficient permissions
+- `NOT_FOUND` - Model or resource not found
+- `RATE_LIMIT_ERROR` - Rate limit exceeded (retryable)
+- `SERVER_ERROR` - OpenAI server error (retryable)
+- `TIMEOUT_ERROR` - Request timeout (retryable)
+
+## Integration Status
+
+- **Logger**: Required - Uses @bernierllc/logger for operation logging
+- **Docs-Suite**: Ready - Full API documentation available
+- **NeverHub**: Optional - Service discovery and event publishing supported
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build package
+pnpm run build
+
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm run test:coverage
+
+# Lint code
+pnpm run lint
+```
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+This package is part of the BernierLLC tools monorepo and follows the unified AI provider interface pattern for seamless provider switching and integration.
+
+## See Also
+
+- [@bernierllc/ai-provider-core](../ai-provider-core) - Abstract AI provider interface
+- [@bernierllc/ai-provider-anthropic](../ai-provider-anthropic) - Anthropic Claude provider
+- [@bernierllc/ai-content-generator](../../service/ai-content-generator) - AI-powered content generation service