@memberjunction/ai-openai

Back to AI Framework Overview | All Providers

@memberjunction/ai-openai

MemberJunction AI provider for OpenAI. Implements BaseLLM, BaseEmbeddings, BaseImageGenerator, and BaseAudio from @memberjunction/ai. This is the foundational LLM provider in MemberJunction -- many other providers (Groq, Cerebras, Fireworks, OpenRouter, LMStudio, xAI) extend this package since they use OpenAI-compatible APIs.

Architecture

graph TD
    A["OpenAILLM<br/>(Provider)"] -->|extends| B["BaseLLM<br/>(@memberjunction/ai)"]
    C["OpenAIEmbedding<br/>(Provider)"] -->|extends| D["BaseEmbeddings<br/>(@memberjunction/ai)"]
    A -->|wraps| E["OpenAI SDK<br/>(openai npm)"]
    C -->|wraps| E
    A -->|provides| F["Chat + Streaming"]
    A -->|provides| G["Thinking Extraction"]
    A -->|provides| H["JSON / Response<br/>Format Control"]
    B -->|registered via| I["@RegisterClass"]
    D -->|registered via| I

    subgraph Subclasses["OpenAI-Compatible Subclasses"]
        J["GroqLLM"]
        K["CerebrasLLM"]
        L["FireworksLLM"]
        M["OpenRouterLLM"]
        N["LMStudioLLM"]
        O["xAILLM"]
    end
    J -->|extends| A
    K -->|extends| A
    L -->|extends| A
    M -->|extends| A
    N -->|extends| A
    O -->|extends| A

    style A fill:#7c5295,stroke:#563a6b,color:#fff
    style C fill:#7c5295,stroke:#563a6b,color:#fff
    style B fill:#2d6a9f,stroke:#1a4971,color:#fff
    style D fill:#2d6a9f,stroke:#1a4971,color:#fff
    style E fill:#2d8659,stroke:#1a5c3a,color:#fff
    style F fill:#b8762f,stroke:#8a5722,color:#fff
    style G fill:#b8762f,stroke:#8a5722,color:#fff
    style H fill:#b8762f,stroke:#8a5722,color:#fff
    style I fill:#b8762f,stroke:#8a5722,color:#fff

Features

• Chat Completions: Full support for GPT-4.1, GPT-4o, o1, o3, o4-mini, and other OpenAI models
• Streaming: Real-time response streaming with chunk processing
• Thinking/Reasoning: Extraction of thinking content from reasoning model responses
• Embeddings: Text embedding generation via text-embedding-3-small/large and other models
• Image Generation: DALL-E integration via BaseImageGenerator
• Audio: Text-to-speech and speech-to-text via BaseAudio
• Multimodal Input: Support for text, image, audio, and file content in messages
• Response Formats: JSON mode, text, and structured output controls
• Effort Level: Maps MJ effort levels to OpenAI reasoning effort parameters
• Error Analysis: Integrated error analysis via ErrorAnalyzer
• Extensible Base: Designed as the foundation for any OpenAI-compatible provider

Installation

npm install @memberjunction/ai-openai

Usage

Chat Completion

import { OpenAILLM } from "@memberjunction/ai-openai";

const llm = new OpenAILLM("your-openai-api-key");

const result = await llm.ChatCompletion({
    model: "gpt-4.1",
    messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "Explain quantum computing." },
    ],
    temperature: 0.7,
    maxOutputTokens: 1000,
});

if (result.success) {
    console.log(result.data.choices[0].message.content);
}

Streaming

const result = await llm.ChatCompletion({
    model: "gpt-4.1",
    messages: [{ role: "user", content: "Write a detailed essay." }],
    streaming: true,
    streamingCallbacks: {
        OnContent: (content) => process.stdout.write(content),
        OnComplete: (result) => console.log("\nDone!"),
    },
});

Embeddings

import { OpenAIEmbedding } from "@memberjunction/ai-openai";

const embedder = new OpenAIEmbedding("your-openai-api-key");

const result = await embedder.EmbedText({
    text: "Sample text for embedding",
    model: "text-embedding-3-small",
});

console.log(`Dimensions: ${result.vector.length}`);

Supported Parameters

Parameter	Supported	Notes
temperature	Yes	0.0 - 2.0
maxOutputTokens	Yes	Maximum tokens to generate
topP	Yes	Nucleus sampling
frequencyPenalty	Yes	-2.0 to 2.0
presencePenalty	Yes	-2.0 to 2.0
seed	Yes	Deterministic outputs
stopSequences	Yes	Custom stop sequences
responseFormat	Yes	JSON, text modes
streaming	Yes	Real-time streaming
effortLevel	Yes	Maps to reasoning_effort
topK	No	Not supported by OpenAI
minP	No	Not supported by OpenAI

Extending for Compatible APIs

This provider is designed as a base class for any OpenAI-compatible API. Override the base URL to point to a different service:

import { OpenAILLM } from "@memberjunction/ai-openai";
import { RegisterClass } from "@memberjunction/global";
import { BaseLLM } from "@memberjunction/ai";
import OpenAI from "openai";

@RegisterClass(BaseLLM, "MyProviderLLM")
export class MyProviderLLM extends OpenAILLM {
    constructor(apiKey: string) {
        super(apiKey);
        this._openai = new OpenAI({
            apiKey,
            baseURL: "https://api.my-provider.com/v1",
        });
    }
}

Class Registration

• OpenAILLM -- Registered via @RegisterClass(BaseLLM, OpenAILLM)
• OpenAIEmbedding -- Registered via @RegisterClass(BaseEmbeddings, OpenAIEmbedding)

Dependencies

• @memberjunction/ai - Core AI abstractions
• @memberjunction/global - Class registration
• openai - Official OpenAI SDK

Realtime driver family (OpenAIRealtime)

OpenAIRealtime / OpenAIRealtimeSession implement the OpenAI GA Realtime API wire protocol ONCE, parameterized by an OpenAIRealtimeProfile (transcription model, turn detection, config timing, live-reconfigure support, GA feature gates, effort mapping). OpenAI-compatible providers subclass this driver with their own profile instead of cloning it — xAI Grok Voice (@memberjunction/ai-xai) via the same SDK socket, and self-hosted HuggingFace (@memberjunction/ai-huggingface) via the exported RawRealtimeWebSocketConnection adapter (raw WS speaking OpenAI frames → IOpenAIRealtimeConnection, with send-buffering until open and SDK-mirroring dual error channels).

Session Config bag keys

MJ-idiomatic keys are extracted (ExtractRealtimeFeatures), translated to provider-native fields only when the profile confirms support, and always scrubbed so raw keys never reach a provider:

Key	Meaning
effortLevel	MJ-normalized effort (ChatParams.effortLevel vocabulary: numeric 1–100 or named). Mapped per provider via the profile's mapEffortLevel seam — OpenAI: quintiles over minimal/low/medium/high/xhigh (MapEffortLevelToOpenAIRealtime).
reasoningEffort	Provider-native effort literal — explicit override, wins over effortLevel.
parallelToolCalls	→ parallel_tool_calls.
mcpTools	Remote MCP server tools appended to session.tools. No approval UX exists yet — approval requests are AUTO-DENIED (the model voices the refusal); declare servers with require_approval: 'never'.
inputTranscriptionModel	Per-session ASR override (falls back to the profile's model; natively-transcribing profiles send no block).
voice / disableAutoResponse	Output voice / meeting-mode gating (as before).
endpoint, sampleRate, proxyBaseUrl	MJ-side transport settings — always scrubbed.

Protected wire fields: type, instructions, and tools can never be overridden through the bag (scrubbed with a diag log); audio remains the one documented override channel. Residual provider-native keys (tool_choice, output_modalities, …) spread into the session payload identically on both topologies (server-bridged session.update and the client-direct minted SessionConfig).

Readiness, usage, and lifecycle

• WaitForConfigApplied() resolves once the initial config is on the socket (deferred to session.created on OpenAI). A 15s readiness deadline (configReadinessTimeoutMs, overridable) rejects awaiting callers on a silent endpoint WITHOUT cancelling the deferred apply.
• response.done usage surfaces per-modality token detail (RealtimeUsage.InputTokenDetails/OutputTokenDetails: text/audio/image/cached) — required for multi-channel cost attribution (audio-in bills ~8× text-in on GPT Realtime 2.1).
• Capabilities.CanReconfigureTurnMode is profile-gated (supportsLiveReconfigure); Reconfigure no-ops on profiles that declare no support.