@robota-sdk/openai

OpenAI Provider for Robota SDK - Complete type-safe integration with OpenAI's GPT models, featuring function calling, streaming, and advanced AI capabilities.

🚀 Features

$3

- 🎯 Type-Safe Integration: Complete TypeScript support with zero any types
- 🤖 GPT Model Support: GPT-4, GPT-3.5 Turbo, and all OpenAI models
- ⚡ Real-Time Streaming: Asynchronous streaming responses with proper error handling
- 🛠️ Function Calling: Native OpenAI function calling with type validation
- 🔄 Provider-Agnostic Design: Seamless integration with other Robota providers
- 📊 Payload Logging: Optional API request/response logging for debugging

$3

- Generic Type Parameters: Full BaseAIProvider implementation
- Facade Pattern: Modular design with separated concerns
- Error Safety: Comprehensive error handling without any-type compromises
- OpenAI SDK Compatibility: Direct integration with official OpenAI SDK types

📦 Installation

``bash
npm install @robota-sdk/openai @robota-sdk/agents openai
`

🔧 Basic Usage

$3

`typescript
import { Robota } from '@robota-sdk/agents';
import { OpenAIProvider } from '@robota-sdk/openai';

// Create type-safe OpenAI provider
const provider = new OpenAIProvider({
apiKey: process.env.OPENAI_API_KEY
});

// Create Robota agent with OpenAI provider
const agent = new Robota({
name: 'MyAgent',
aiProviders: [provider],
defaultModel: {
provider: 'openai',
model: 'gpt-4',
temperature: 0.7,
systemMessage: 'You are a helpful AI assistant specialized in technical topics.'
}
});

// Execute conversation
const response = await agent.run('Explain the benefits of TypeScript over JavaScript');
console.log(response);

// Clean up
await agent.destroy();
`

$3

`typescript
// Real-time streaming for immediate feedback
const stream = await agent.runStream('Write a detailed explanation of machine learning');

for await (const chunk of stream) {
if (chunk.content) {
process.stdout.write(chunk.content);
}

// Handle streaming metadata
if (chunk.metadata?.isComplete) {
console.log('\n✓ Stream completed');
}
}
`

🛠️ Function Calling

OpenAI Provider supports type-safe function calling with automatic parameter validation:

`typescript
import { FunctionTool } from '@robota-sdk/agents';
import { z } from 'zod';

// Define type-safe function tools
const weatherTool = new FunctionTool({
name: 'getWeather',
description: 'Get current weather information for a location',
parameters: z.object({
location: z.string().describe('City name'),
unit: z.enum(['celsius', 'fahrenheit']).default('celsius')
}),
handler: async ({ location, unit }) => {
// Type-safe handler implementation
const weatherData = await fetchWeatherAPI(location, unit);
return {
temperature: weatherData.temp,
condition: weatherData.condition,
location,
unit
};
}
});

const calculatorTool = new FunctionTool({
name: 'calculate',
description: 'Perform mathematical operations',
parameters: z.object({
operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
a: z.number(),
b: z.number()
}),
handler: async ({ operation, a, b }) => {
const operations = {
add: a + b,
subtract: a - b,
multiply: a * b,
divide: a / b
};
return { result: operations[operation] };
}
});

// Register tools with the agent
agent.registerTool(weatherTool);
agent.registerTool(calculatorTool);

// Execute with function calling
const result = await agent.run(
'What\'s the weather in Tokyo and what\'s 25 * 4?'
);
`

🔄 Multi-Provider Architecture

Seamlessly integrate with other providers:

`typescript
import { AnthropicProvider } from '@robota-sdk/anthropic';
import { GoogleProvider } from '@robota-sdk/google';

const openaiProvider = new OpenAIProvider({
apiKey: process.env.OPENAI_API_KEY
});

const anthropicProvider = new AnthropicProvider({
apiKey: process.env.ANTHROPIC_API_KEY
});

const googleProvider = new GoogleProvider({
apiKey: process.env.GOOGLE_AI_API_KEY
});

const agent = new Robota({
name: 'MultiProviderAgent',
aiProviders: [openaiProvider, anthropicProvider, googleProvider],
defaultModel: {
provider: 'openai',
model: 'gpt-4'
}
});

// Dynamic provider switching
const openaiResponse = await agent.run('Respond using GPT-4');

agent.setModel({ provider: 'anthropic', model: 'claude-3-sonnet-20240229' });
const claudeResponse = await agent.run('Respond using Claude');
`

⚙️ Configuration Options

`typescript
interface OpenAIProviderOptions {
// Required
client: OpenAI; // OpenAI SDK client instance

// Model Configuration
model?: string; // Default: 'gpt-4'
temperature?: number; // 0-1, default: 0.7
maxTokens?: number; // Maximum tokens to generate

// API Configuration
apiKey?: string; // API key (if not set in client)
organization?: string; // OpenAI organization ID
timeout?: number; // Request timeout (ms)
baseURL?: string; // Custom API base URL

// Response Configuration
responseFormat?: 'text' | 'json_object' | 'json_schema';
jsonSchema?: { // For structured outputs
name: string;
description?: string;
schema?: Record;
strict?: boolean;
};

// Debugging & Logging
payloadLogger?: PayloadLogger; // Environment-specific payload logger

// Interface-based logger implementations:
// - FilePayloadLogger: Node.js file-based logging
// - ConsolePayloadLogger: Browser console-based logging
// - Custom: Implement PayloadLogger interface
}
`

📋 Supported Models

| Model | Description | Use Cases |
|-------|-------------|-----------|
| gpt-4 | Most capable model | Complex reasoning, analysis, creative tasks |
| gpt-4-turbo | Faster GPT-4 variant | Balanced performance and cost |
| gpt-3.5-turbo | Fast and efficient | Simple conversations, basic tasks |
| gpt-4-vision-preview | Vision capabilities | Image analysis and understanding |

🔍 API Reference

$3

`typescript
class OpenAIProvider extends BaseAIProvider<
OpenAIProviderOptions,
UniversalMessage,
UniversalMessage
> {
// Core methods
async chat(messages: UniversalMessage[], options?: ChatOptions): Promise
async chatStream(messages: UniversalMessage[], options?: ChatOptions): AsyncIterable

// Provider information
readonly name: string = 'openai'
readonly version: string = '1.0.0'

// Utility methods
supportsTools(): boolean
validateConfig(): boolean
async dispose(): Promise
}
`

$3

`typescript
// Chat Options
interface ChatOptions {
tools?: ToolSchema[];
maxTokens?: number;
temperature?: number;
model?: string;
}

// OpenAI-specific types
interface OpenAIToolCall {
id: string;
type: 'function';
function: {
name: string;
arguments: string;
};
}

interface OpenAILogData {
model: string;
messagesCount: number;
hasTools: boolean;
temperature?: number;
maxTokens?: number;
timestamp: string;
requestId?: string;
}
`

🐛 Debugging & Logging

$3

The OpenAI Provider supports environment-specific payload logging through interface-based dependency injection:

#### Node.js Environment (File-Based Logging)
`typescript
import { OpenAIProvider } from '@robota-sdk/openai';
import { FilePayloadLogger } from '@robota-sdk/openai/loggers/file';

const provider = new OpenAIProvider({
client: openaiClient,
model: 'gpt-4',
payloadLogger: new FilePayloadLogger({
logDir: './logs/openai-api',
enabled: true,
includeTimestamp: true
})
});
`

#### Browser Environment (Console-Based Logging)
`typescript
import { OpenAIProvider } from '@robota-sdk/openai';
import { ConsolePayloadLogger } from '@robota-sdk/openai/loggers/console';

const provider = new OpenAIProvider({
client: openaiClient,
model: 'gpt-4',
payloadLogger: new ConsolePayloadLogger({
enabled: true,
includeTimestamp: true
})
});
`

#### No Logging (Both Environments)
`typescript
const provider = new OpenAIProvider({
client: openaiClient,
model: 'gpt-4'
// payloadLogger: undefined (default - no logging)
});
`

$3

You can create custom logger implementations by implementing the PayloadLogger interface:

`typescript
import type { PayloadLogger, OpenAILogData } from '@robota-sdk/openai';

class CustomPayloadLogger implements PayloadLogger {
isEnabled(): boolean {
return true;
}

async logPayload(payload: OpenAILogData, type: 'chat' | 'stream'): Promise {
// Custom logging implementation
console.log([Custom Logger] ${type}:, payload);
}
}

const provider = new OpenAIProvider({
client: openaiClient,
payloadLogger: new CustomPayloadLogger()
});
`

This creates detailed logs of all API requests and responses for debugging purposes.

🔒 Security Best Practices

$3


`typescript
// ✅ Good: Use environment variables
const client = new OpenAI({
apiKey: process.env.OPENAI_API_KEY
});

// ❌ Bad: Hardcoded keys
const client = new OpenAI({
apiKey: 'sk-...' // Never do this!
});
`

$3


`typescript
try {
const response = await agent.run('Your query');
} catch (error) {
if (error instanceof Error) {
console.error('AI Error:', error.message);
}
// Handle specific OpenAI errors
}
`

📊 Performance Optimization

$3

`typescript
const provider = new OpenAIProvider({
client: openaiClient,
model: 'gpt-4',
maxTokens: 1000, // Limit response length
temperature: 0.3 // More deterministic responses
});
`

$3

- Use gpt-3.5-turbo for simple tasks
- Use gpt-4 for complex reasoning
- Use gpt-4-turbo for balanced performance

🤝 Contributing

This package follows strict type safety guidelines:
- Zero any or unknown` types allowed
- Complete TypeScript coverage
- Comprehensive error handling
- Provider-agnostic design principles

📄 License

MIT License - see LICENSE file for details.

🔗 Related Packages

- @robota-sdk/agents: Core agent framework
- @robota-sdk/anthropic: Anthropic Claude provider
- @robota-sdk/google: Google AI provider
- @robota-sdk/team: Multi-agent collaboration

---

For complete documentation and examples, visit the Robota SDK Documentation.