# @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