@ank1015/agents-provider-openai-spec

Static OpenAI provider metadata for the @ank1015/agents packages.

This package contains no live OpenAI client. It provides provider identity, config types, provider-specific type augmentation, and a static model catalog that other packages can consume without depending on the OpenAI runtime adapter.

Install

pnpm add @ank1015/agents-provider-openai-spec

What This Package Provides

• OPENAI_PROVIDER provider id.
• openAIProviderConfigSchema for provider config validation.
• OpenAIProviderOptions based on OpenAI Responses API request options.
• OpenAINativeMessage based on OpenAI SDK response objects.
• OPENAI_MODELS static model catalog.
• OpenAIModelId literal union derived from the catalog.
• Contract augmentation for @ank1015/agents-contracts.

Import Paths

import {
  OPENAI_MODELS,
  OPENAI_PROVIDER,
  getOpenAIModel,
} from '@ank1015/agents-provider-openai-spec';

import { openAIProviderConfigSchema } from '@ank1015/agents-provider-openai-spec/config';
import type { OpenAIModelId } from '@ank1015/agents-provider-openai-spec/models';

Provider Config

OpenAI provider config uses a secret reference for the API key. Environment references keep keys out of config:

import {
  OPENAI_PROVIDER,
  openAIProviderConfigSchema,
} from '@ank1015/agents-provider-openai-spec';

const config = openAIProviderConfigSchema.parse({
  provider: OPENAI_PROVIDER,
  apiKey: {
    type: 'env',
    name: 'OPENAI_API_KEY',
  },
});

The live adapter resolves the referenced environment variable when it creates the OpenAI SDK client. Callers that already have a key from another secret source can pass a direct value reference:

const config = openAIProviderConfigSchema.parse({
  provider: OPENAI_PROVIDER,
  apiKey: {
    type: 'value',
    value: openAIKey,
  },
});

Model Catalog

OPENAI_MODELS is a static snapshot used for model lookup, UI metadata, defaults, and compile-time model-id narrowing:

import {
  OPENAI_MODELS,
  getOpenAIModel,
} from '@ank1015/agents-provider-openai-spec';

const model = getOpenAIModel('gpt-5.6-terra');

The catalog currently includes:

• gpt-5.6-sol
• gpt-5.6-terra
• gpt-5.6-luna
• gpt-5.5
• gpt-5.4-mini
• gpt-5.4-nano

Static model metadata can age as providers release or retire models. Treat pricing, context windows, and max-token metadata as package-versioned snapshot data. GPT-5.6 Sol, Terra, Luna, and GPT-5.5 include long-context tiers: prompts over 272K input tokens use 2x input/cache rates and 1.5x output rates for the full request. GPT-5.4 mini and nano remain flat-priced.

Type Augmentation

Importing this package augments @ank1015/agents-contracts so OpenAI requests can narrow provider-specific fields:

import type { LLMRequest } from '@ank1015/agents-contracts';
import type { OpenAIProvider } from '@ank1015/agents-provider-openai-spec';

const request: LLMRequest<OpenAIProvider> = {
  provider: 'openai',
  modelId: 'gpt-5.6-sol',
  messages: [],
  providerOptions: {
    reasoning: {
      effort: 'max',
      mode: 'pro',
      context: 'all_turns',
    },
    prompt_cache_key: 'tenant:example',
    prompt_cache_options: {
      mode: 'implicit',
      ttl: '30m',
    },
  },
};

Versioning

This package is currently 0.1.1. Until 1.0.0, model metadata and provider option types may evolve as the surrounding agent runtime settles.