@fevex/openai

Official OpenAI ModelGateway adapter for Fevex. See the compatibility and release policy.

npm install @fevex/core @fevex/openai

import { createOpenAI } from '@fevex/openai';

const model = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  organization: process.env.OPENAI_ORG_ID,
  project: process.env.OPENAI_PROJECT_ID,
  schemaPolicy: 'strict',
})('gpt-5.6');

The adapter uses native fetch and implements only the Fevex model contract. Runtime behavior such as tool execution, validation, events and retries belongs to @fevex/core. Returned gateways include metadata: { provider: "openai", model: modelId } for traces, eval cost calculators and OpenTelemetry export.

Text, tools and continuation

Without outputSchema, OpenAI text is returned as the exact string supplied by the Responses API, even when it looks like JSON. With outputSchema, the adapter requires valid JSON before Fevex performs local schema validation. Refusals, incomplete responses and malformed function calls fail explicitly.

During tool loops the adapter stores the original response items, including reasoning items required by Responses API, in opaque providerState. Fevex returns that state to the next model step automatically. Direct ModelGateway consumers must do the same; the state is run-local and must not be inspected. The adapter's stateCodec lets Fevex persist it only inside a private durable checkpoint.

Core reasoning efforts are forwarded to reasoning.effort; provider-default leaves provider options untouched. The core contract includes none, minimal, low, medium, high, xhigh and max so current GPT-5.6 models can use their documented effort levels. Model-specific support still belongs to OpenAI, so an unsupported value is reported by the API. Provider-only settings can be supplied through modelOptions.reasoning.

createOpenAI receives the connection settings (apiKey, optional organization, project, baseURL, schema policy and fetch) and the model ID is supplied when creating the gateway. Reasoning effort is intentionally a per-request setting forwarded through ModelInput, not a factory setting.

The adapter always uses the Responses streaming API. It emits only response.output_text.delta as visible output and builds the terminal result from response.completed; reasoning and partial function arguments remain private.

Tool names and schemaName must match [A-Za-z0-9_-]{1,64}. Fevex-owned fields such as model, input, tools, tool choice, schema format, parallel calls and output caps override conflicting modelOptions. Background provider jobs and built-in tools remain outside this gateway.

Schema policy

schemaPolicy defaults to "strict". Before sending a request, the adapter checks tool inputs and final outputs against OpenAI's documented Structured Outputs subset. Every schema must have an object root; every object must require all its properties and set additionalProperties: false. Unsupported keywords and documented size limits throw OpenAIError with code: "PROVIDER_SCHEMA_UNSUPPORTED" before fetch runs.

Set schemaPolicy: "best-effort" to send tools with strict: false. Object outputs use JSON mode and other JSON values use a schema instruction. Fevex still validates the returned value locally, but OpenAI does not guarantee schema adherence in this mode, so the caller may need to retry an invalid result.