@llm-ports/adapter-openai weekly downloads statistics

@llm-ports/adapter-openai

OpenAI SDK adapter for llm-ports. Implements LLMPort and EmbeddingsPort. The same adapter serves OpenAI plus 12+ OpenAI-compatible providers via baseURL, including Groq, Together AI, Fireworks AI, Cerebras, Clarifai, and SambaNova.

Install

pnpm add @llm-ports/core @llm-ports/adapter-openai openai zod

Configure

import { createRegistryFromEnv } from "@llm-ports/core";
import { createOpenAIAdapter } from "@llm-ports/adapter-openai";

const registry = createRegistryFromEnv({
  adapters: {
    openai: createOpenAIAdapter({
      apiKey: process.env.OPENAI_API_KEY!,
    }),
  },
});

const llm = registry.getPort();
const embed = registry.getEmbeddingsPort();

Compat providers

The same adapter works for any provider that exposes an OpenAI-shaped API. Just supply a baseURL:

Provider	baseURL
OpenAI (default)	(none)
Azure OpenAI	https://<resource>.openai.azure.com/openai/deployments/<deployment>
Groq	https://api.groq.com/openai/v1
Together AI	https://api.together.xyz/v1
Fireworks AI	https://api.fireworks.ai/inference/v1
DeepInfra	https://api.deepinfra.com/v1/openai
Perplexity	https://api.perplexity.ai
Cerebras	https://api.cerebras.ai/v1
Clarifai	https://api.clarifai.com/v2/ext/openai/v1
SambaNova	https://api.sambanova.ai/v1
LiteLLM proxy	self-hosted, e.g. http://localhost:4000
Ollama compat-mode	http://localhost:11434/v1 (prefer adapter-ollama for native API)

Each compatible provider has its own pricing — supply via pricingOverrides:

createOpenAIAdapter({
  apiKey: process.env.GROQ_API_KEY!,
  baseURL: "https://api.groq.com/openai/v1",
  displayName: "groq",
  pricingOverrides: {
    "llama-3.3-70b-versatile": { inputPer1M: 0.59, outputPer1M: 0.79 },
  },
});

Adapter options

interface OpenAIAdapterOptions {
  apiKey: string;
  baseURL?: string;                            // for OpenAI-compat providers
  fetch?: typeof fetch;                        // inject custom fetch (tests, proxies)
  validationStrategy?: ValidationStrategy;
  pricingOverrides?: Record<string, ModelPricing>;
  displayName?: string;                        // friendlier alias in error messages
  imageSizeLimitBytes?: number;                // default 20 MB
  dangerouslyAllowBrowser?: boolean;           // opt in to browser execution (alpha.9)
  maxRetries?: number;                         // SDK-level retries (default 2)
  transientAuthRetries?: number;               // project-key 401 burst retries (default 2)
  transientAuthBackoffMs?: (attempt: number) => number;
  onRetry?: OnRetry;                           // observability hook
}

dangerouslyAllowBrowser (alpha.9+)

The OpenAI SDK refuses to construct in a browser environment unless dangerouslyAllowBrowser: true is passed explicitly. Set this option only when the API key is NOT a long-lived secret: short-lived proxy tokens, BYO-key UIs where the end user supplies their own key, or trusted internal tools running behind auth. For server-side proxy patterns where the secret stays on the server, leave it unset.

const adapter = createOpenAIAdapter({
  apiKey: ephemeralUserKey,
  dangerouslyAllowBrowser: true,
});

Bundled pricing

The bundled OPENAI_PRICING table covers GPT-5 family (gpt-5, gpt-5-mini, gpt-5-nano), GPT-4o family, o3 / o3-mini, and the embedding models. Override per model via pricingOverrides.

Bundled pricing does NOT cover compat-provider models (Groq, Together AI, Fireworks, Cerebras, Clarifai, SambaNova, LiteLLM proxy, etc.) — supply pricingOverrides for those.

Supported features

Feature	Status
generateText	✓
generateStructured (Zod schemas)	✓ (uses native response_format: json_object + retry-with-feedback)
streamText	✓ (alpha.25+: emits onCost + onTokenUsage at natural completion)
streamStructured (partial JSON)	✓ (best-effort partial parse; alpha.25+: same streamed cost surface)
runAgent (multi-turn tool use)	✓
generateEmbedding / generateEmbeddings	✓ (text-embedding-3-small / -large)
Vision input — base64 images	✓ (data URI)
Vision input — URL images	✓
Audio input — base64 wav/mp3	✓
Audio input — base64 ogg	✗ (OpenAI doesn't support ogg)
Audio input — URL audio	✗ (OpenAI requires base64)
Prompt caching	✓ — reported via cachedTokens
AbortSignal cancellation	✓ entry + in-flight (alpha.6)

Content blocks supported

text, image (base64 → data URI; URL passthrough), audio (base64 wav/mp3 only), tool_use, tool_result. Throws ContentBlockUnsupportedError for unsupported variants.

Capability detection — three-tier architecture (alpha.24+)

Reasoning models consume output tokens on hidden chain-of-thought before producing visible text. The adapter detects this and retries once with the budget expanded by a headroom multiplier.

The detection mechanism has three tiers (see Capability Detection for the full design):

1. Runtime detection (alpha.22+) — universal correctness path. Every successful response is inspected for four CoT field shapes (usage.completion_tokens_details.reasoning_tokens, message.reasoning, message.reasoning_content, inline <think>). Catches every reasoning model with zero maintenance.
2. Behavioral fingerprint cache (alpha.24+) — opt-in cross-process optimization. createOpenAIAdapter({ fingerprintCache }) skips the first-call discovery penalty.
3. Static catalog (KNOWN_REASONING_MODELS, FROZEN) — cheap shortcut for the stable well-known cases. Closed to new entries.

Behavioral fingerprint cache…