Molecule.dev

@molecule/api-ai-openai

Provider bond · ai · API (Node) · v1.4.3 · Apache-2.0

Openai ai-openai provider for molecule.dev.

npm install @molecule/api-ai-openai

npm · Source on GitHub · Implements @molecule/api-ai

How it works

@molecule/api-ai-openai is a provider bond on the API (Node) side: it implements the ai core interface (@molecule/api-ai) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

// npm install @molecule/api-ai-openai --workspace=api
import { setProvider, requireProvider } from '@molecule/api-ai'
import { provider } from '@molecule/api-ai-openai'

// Named registration — several AI providers can be bonded side by side
// (getProviderByName('openai') targets this one); the FIRST one
// registered also answers requireProvider() (see @molecule/api-ai).
setProvider('openai', provider) // reads OPENAI_API_KEY from the environment

let reply = ''
for await (const event of requireProvider().chat({
  messages: [{ role: 'user', content: 'Hello!' }],
})) {
  if (event.type === 'text') reply += event.content // or forward the chunk to the client (SSE)
}

Works with: @molecule/api-bond, @molecule/api-secrets

Secrets: OPENAI_API_KEY

Live demos

Running apps built with Molecule that install this package — open the app or study the template.

Reference

OpenAI (GPT) AI provider for molecule.dev.

Quick Start

// npm install @molecule/api-ai-openai --workspace=api
import { setProvider, requireProvider } from '@molecule/api-ai'
import { provider } from '@molecule/api-ai-openai'

// Named registration — several AI providers can be bonded side by side
// (getProviderByName('openai') targets this one); the FIRST one
// registered also answers requireProvider() (see @molecule/api-ai).
setProvider('openai', provider) // reads OPENAI_API_KEY from the environment

let reply = ''
for await (const event of requireProvider().chat({
  messages: [{ role: 'user', content: 'Hello!' }],
})) {
  if (event.type === 'text') reply += event.content // or forward the chunk to the client (SSE)
}

Type

provider

Installation

npm install @molecule/api-ai-openai @molecule/api-ai @molecule/api-bond @molecule/api-secrets

API

Interfaces

OpenaiConfig

OpenAI provider configuration.

interface OpenaiConfig {
  /** Override the API key (defaults to `process.env.OPENAI_API_KEY`). */
  apiKey?: string
  /** Default model when callers don't specify one. */
  defaultModel?: string
  /** Default max output tokens. */
  maxTokens?: number
  /** Override the API base URL (for proxies / Azure). */
  baseUrl?: string
  /** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
  onRateLimit?: AiRateLimitCallback
  /**
   * Which OpenAI endpoint to call. Defaults to `'responses'` (`/v1/responses`)
   * when the base URL is OpenAI's own API, and to `'chat-completions'`
   * (`/v1/chat/completions`) for any other base URL, since OpenAI-compatible
   * servers generally implement only chat/completions.
   */
  api?: OpenaiApi
}

ProcessEnv

Environment variables read by this provider.

interface ProcessEnv {
  /** OpenAI API key (required unless `config.apiKey` is passed). */
  OPENAI_API_KEY: string
  /** Base URL override (for proxies / Azure-compatible gateways). Defaults to `https://api.openai.com`. */
  OPENAI_BASE_URL?: string
}

Types

OpenaiApi

The OpenAI endpoint a provider instance calls.

type OpenaiApi = 'responses' | 'chat-completions'

Classes

OpenaiAIProvider

OpenAI Chat Completions provider implementing the AIProvider interface.

Functions

createProvider(config)

Create an OpenAI AI provider instance.

function createProvider(config?: OpenaiConfig): AIProvider
  • config — OpenAI-specific configuration.

Returns: An AIProvider backed by OpenAI's Chat Completions API.

Constants

aiOpenaiSecretDefinitions

Secret definitions required by the OpenAI AI bond.

const aiOpenaiSecretDefinitions: SecretDefinition[]

provider

The provider implementation.

const provider: AIProvider

Core Interface

Implements @molecule/api-ai interface.

Bond Wiring

Setup function to register this provider with the bond system:

import { bond } from '@molecule/api-bond'
import { provider } from '@molecule/api-ai-openai'

export function setupAiOpenai(): void {
  bond('ai', 'openai', provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/api-ai ^1.0.1
  • @molecule/api-bond ^1.0.1
  • @molecule/api-secrets ^1.0.1

Environment Variables

  • OPENAI_API_KEY (required) — OpenAI API key

Runtime Dependencies

  • @molecule/api-ai
  • @molecule/api-bond
  • @molecule/api-secrets

Config: OPENAI_API_KEY (SERVER-side only) plus an optional default model id/base URL.

Endpoint: on OpenAI's own API (https://api.openai.com, the default) the provider calls the Responses API (/v1/responses); on any other baseUrl it calls /v1/chat/completions, the endpoint OpenAI-compatible servers (Ollama, LM Studio, gateways) implement. Override with api: 'responses' | 'chat-completions'. Current OpenAI reasoning models only accept function tools together with reasoning on /v1/responses (gpt-6-astra rejects every tool-carrying request on chat/completions), and only Responses carries OpenAI's server-side tools (serverTools, e.g. { type: 'web_search', name: 'web_search' }); chat/completions ignores serverTools. extraBody is merged into whichever endpoint's body is sent, so its keys must be that endpoint's params (e.g. reasoning, not reasoning_effort, on Responses).

Missing OPENAI_API_KEY fails fast: the provider throws naming the exact env var on first use (the exported provider is a lazy proxy, so this fires on the first chat() call, not at bond/module-load time) — it never silently sends an empty key.

Error message disambiguation: a plain 400 that ISN'T a context-length error (bad param, malformed tool schema) gets its own non-retryable message distinct from the generic "AI service error. Please try again." used for retryable failures.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual chat/AI screens, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip. The sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:

  • A message sent through the real chat UI comes back as a RELEVANT AI reply — not an echo of the prompt, a hardcoded stub, or an empty bubble. Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm the response actually contains it ("4"), proving a live model answered.
  • If the app streams, tokens render INCREMENTALLY — text grows word by word in the UI, not one final blob dumped after a long frozen spinner. (A streamed chat() yields text chunks then a final done; a single late blob means the reply was awaited whole and streaming is broken.)
  • Multi-turn CONTEXT is preserved: a follow-up that refers back to the previous turn (e.g. after "2 + 2", ask "now double that" -> understood as 8) works — proving the full messages history is sent, not just the last line.
  • A provider failure (bad/missing key, rate limit, timeout) surfaces as a graceful in-UI error message, NOT a crash, blank screen, a spinner that never resolves, or an unhandled 500. Force one and watch the UI recover.
  • The provider key + the provider call are SERVER-side only: the key never reaches the browser (check the network tab, the JS bundle, and page globals), and no route proxies arbitrary prompts to the model without auth
    • a token cap — an open AI endpoint is an unbounded bill and abuse vector.