@starya/nebulaos-openai

Official OpenAI provider implementation for the NebulaOS ecosystem. This package connects @starya/nebulaos-core to the OpenAI API, supporting all modern features like Streaming, Tools, and JSON Mode.

Installation

pnpm add @starya/nebulaos-openai

Usage

import { OpenAI } from "@starya/nebulaos-openai";
import { Agent, InMemory } from "@starya/nebulaos-core";

// 1. Instantiate the Provider
const provider = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o-mini", // Default model
  clientOptions: { 
    // Optional: OpenAI client options (timeout, headers, baseURL, etc)
    timeout: 30000 
  }
});

// 2. Use in an Agent
const agent = new Agent({
  name: "gpt-agent",
  model: provider,
  memory: new InMemory(),
  instructions: "Be concise."
});

✨ Features Overview

Core Capabilities

• ✅ Text Generation - Standard chat completions
• ✅ Streaming - Real-time token streaming with generateStream()
• ✅ Tool Calling - Single and parallel function calling
• ✅ Structured Outputs - Guaranteed JSON mode with schema validation
• ✅ Multimodal Input - Image support (GPT-4o Vision, base64 or URLs)
• ✅ Reasoning Tokens - o1-preview/o1-mini reasoning token tracking

Streaming Protocol

• ✅ content_delta - Text chunks as they arrive
• ✅ tool_call_start - Tool invocation begins
• ✅ tool_call_delta - Incremental tool arguments
• ✅ tool_call_end - Tool invocation complete
• ✅ finish - Final chunk with usage stats and finish reason

Advanced Features

• ✅ Token Usage Tracking - Detailed breakdown (prompt, completion, reasoning)
• ✅ Error Handling - OpenAI SDK error passthrough
• ✅ Type Safety - Full TypeScript support with OpenAI SDK types
• ✅ Custom Endpoints - Support for Azure OpenAI and custom base URLs

Configuration Options

OpenAIConfig

• apiKey (required): Your OpenAI API key.
• model (required): Model name (e.g., "gpt-4o", "gpt-4o-mini", "o1-preview").
• clientOptions (optional): Pass-through options to the OpenAI SDK:
  • baseURL: Custom API endpoint
  • organization: OpenAI organization ID
  • timeout: Request timeout in milliseconds
  • maxRetries: Number of automatic retries

Testing

This package uses the @starya/nebulaos-core compliance test suite to ensure consistent behavior across providers.

To run live integration tests:

1. Create a .env file in the package root with OPENAI_API_KEY.
2. Run:

pnpm test:live

Supported Models

• GPT-4o series: gpt-4o, gpt-4o-mini, gpt-4o-2024-08-06
• GPT-4 series: gpt-4-turbo, gpt-4
• GPT-3.5: gpt-3.5-turbo
• o1 series (reasoning): o1-preview, o1-mini