@crux/openai

Peer dependency: openai

import { createOpenAI, embedding, openaiProviderRuntime, openAITranscript, toMessages, fromMessages } from '@crux/openai'
import { createGenerateObjectFn, createGenerateTextFn } from '@crux/openai'

createOpenAI(client)

Create an adapter bound to an OpenAI client.

createOpenAI() is openaiProviderRuntime.create. The package-owned openAITranscript owns message conversion plus assistant text/tool-call extraction; response metadata normalization, stream deltas, and settings/schema mapping stay in this package too. Crux still owns prompt resolution, tool loops, safety, validation retry, memory capture, and observability.

Returns:

import { createOpenAI } from '@crux/openai'
import OpenAI from 'openai'

const adapter = createOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }))

const result = await adapter.generate(editDraft, {
  model: 'gpt-4o',
  input: { instruction: 'Fix the intro' },
})
result.text
result._meta.usage

adapter.generate(prompt, options)

Returns: normalized Crux generate result with:

• result.text — extracted assistant text
• result.raw — raw OpenAI SDK response
• result._meta — normalized usage, finish reason, tool calls, and model metadata

When the prompt has an output schema, the provider-parsed value remains available on result.raw.choices[0].message.parsed.

adapter.stream(prompt, options)

Stream a prompt execution.

Returns: OpenAI stream.

toMessages(sdkMessages)

Convert OpenAI ChatCompletionMessageParam[] to canonical Message[].

Returns: Message[]

fromMessages(messages)

Convert canonical Message[] to OpenAI ChatCompletionMessageParam[].

Returns: ChatCompletionMessageParam[]

Assistant tool calls become OpenAI tool_calls; tool results become tool role messages with tool_call_id. Rich tool-result content is rendered to deterministic text parts because Chat Completions does not accept native image/PDF tool-result blocks.

openAITranscript is the lower-level NativeTranscriptCodec used by createOpenAI(). The public toMessages() and fromMessages() wrappers delegate to it.

createGenerateObjectFn(client, model)

Create a GenerateObjectFn bound to a client and model.

Returns: GenerateObjectFn

This is a provider-native helper generated from the same native chat profile as createOpenAI(). It uses OpenAI's structured parse surface and returns the parsed { object }, preserving provider errors. It does not run Crux prompt resolution, validation retry, safety, cassettes, tools, memory capture, or instrumentation. Use createGenerateObjectFnFromGenerate(generate) from @crux/core/compaction when a GenerateObjectFn needs full adapter runtime behavior.

createGenerateTextFn(client, model)

Create a GenerateTextFn bound to a client and model.

Returns: GenerateTextFn

This helper is also generated from the native chat profile, so text helper calls and adapter calls share request construction and response extraction.

embedding(client, config)

Create a dense Crux embedding backed by client.embeddings.create().

import OpenAI from 'openai'
import { embedding } from '@crux/openai'

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

const docsEmbedding = embedding(client, {
  name: 'docs-embedding',
  model: 'text-embedding-3-small',
})

Known OpenAI embedding models infer their default dimensions automatically. For custom model IDs, pass dimensions explicitly.

Types

import type { OpenAIChatRequest, OpenAIEmbeddingConfig, OpenAIExtra } from '@crux/openai'

Related

• Guide: Execution
• Guide: Embeddings
• Reference: Prompts
• Reference: @crux/ai (Vercel AI SDK)