@tanstack/openai-base 0.2.1 → 0.3.1

package/README.md

@@ -0,0 +1,121 @@
+# @tanstack/openai-base
+
+Shared base adapters for providers that drive the official `openai` SDK
+against a different `baseURL`.
+
+## TL;DR
+
+Several providers ship endpoints that the official `openai` Node SDK can
+talk to verbatim — you just point it at a different `baseURL`. xAI's Grok
+endpoint, Groq's `/openai/v1` endpoint, and OpenAI itself all fall in this
+camp. This package contains the shared logic for both wire formats those
+endpoints expose:
+
+- `OpenAIBaseChatCompletionsTextAdapter` — for `/v1/chat/completions`
+- `OpenAIBaseResponsesTextAdapter` — for `/v1/responses`
+
+Provider packages (`@tanstack/ai-openai`, `@tanstack/ai-groq`,
+`@tanstack/ai-grok`) construct an `OpenAI` client with their own `baseURL`,
+pass it to the relevant base adapter, and override a small set of
+protected hooks for SDK-shape variance and provider-specific quirks.
+
+## Why this package exists
+
+Every text adapter in TanStack AI — regardless of provider — emits
+[AG-UI](https://github.com/CopilotKit/ag-ui) events (`RUN_STARTED`,
+`TEXT_MESSAGE_*`, `TOOL_CALL_*`, `RUN_FINISHED`, …) as its output stream.
+That is the universal unification.
+
+Input protocols differ. The OpenAI Chat Completions and Responses wire
+formats both have multiple implementers in the ecosystem, so it pays to
+write the streaming-chunk assembly, partial-JSON tool-arg buffering,
+tool-call deduplication, and structured-output coercion once and share
+it. That shared code lives here.
+
+Providers whose native API doesn't match either OpenAI wire format
+(Anthropic, Gemini, Ollama's native API, OpenRouter's own SDK) extend
+`BaseTextAdapter` from `@tanstack/ai` directly — there's nothing to
+share, so they don't pay the indirection cost.
+
+## What goes here vs. in `@tanstack/ai-openai`
+
+| Belongs in `@tanstack/openai-base`                                                                  | Belongs in `@tanstack/ai-openai`                                                                                              |
+| --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| Logic for the Chat Completions wire format                                                          | OpenAI-specific tool types (`web_search_preview`, `code_interpreter`, `local_shell`, `apply_patch`, `computer_use`, `mcp`, …) |
+| Logic for the Responses wire format                                                                 | OpenAI model metadata, model lists, capability matrices                                                                       |
+| Streaming chunk assembly, AG-UI lifecycle, partial-JSON tool-arg buffering, tool-call deduplication | OpenAI-only request/response fields that no other consumer of the base sets                                                   |
+| Schema converters and structured-output coercion that all consumers accept                          | OpenAI's media adapters (image/TTS/video/transcription) that Grok/Groq don't implement                                        |
+
+**Rule of thumb**: if a field would be useful to at least two of the
+consuming packages (`ai-openai`, `ai-grok`, `ai-groq`), it belongs here.
+Otherwise it belongs in the provider's own package, plumbed in via a
+subclass override or a hook.
+
+## How providers extend the bases
+
+The base constructor takes a pre-built `OpenAI` client. Subclasses
+construct the SDK with their own `baseURL` (and any other client
+options) and pass it to `super`:
+
+```ts
+class GrokTextAdapter extends OpenAIBaseChatCompletionsTextAdapter<…> {
+  constructor(config: GrokConfig, model: TModel) {
+    super(model, 'grok', new OpenAI(withGrokDefaults(config)))
+  }
+}
+```
+
+Per-provider quirks are handled via protected hooks:
+
+- `convertMessage`, `mapOptionsToRequest` — bridge request-shape
+  differences (extra fields, omitted fields, alternative encodings).
+- `extractReasoning` — surface a provider's reasoning channel into the
+  shared `REASONING_*` AG-UI lifecycle.
+- `transformStructuredOutput`, `makeStructuredOutputCompatible` —
+  adjust structured-output handling for provider quirks (e.g. Groq's
+  schema-shape requirements).
+- `processStreamChunks` — wrap the shared chunk processor for last-mile
+  fixups (e.g. Groq's `x_groq.usage` → `chunk.usage` promotion).
+- `extractTextFromResponse` — pull the assistant text out of the
+  provider's non-streaming response shape.
+
+Each provider typically overrides 2–6 hooks and inherits everything else.
+
+## Architecture
+
+```
+@tanstack/ai
+└── BaseTextAdapter  (abstract — emits AG-UI events)
+    │
+    ├── @tanstack/openai-base::OpenAIBaseChatCompletionsTextAdapter
+    │   ├── ai-groq
+    │   └── ai-grok
+    │
+    ├── @tanstack/openai-base::OpenAIBaseResponsesTextAdapter
+    │   └── ai-openai (Responses is OpenAI's preferred API)
+    │
+    ├── ai-anthropic::AnthropicTextAdapter   extends BaseTextAdapter directly
+    ├── ai-gemini::GeminiTextAdapter         extends BaseTextAdapter directly
+    ├── ai-ollama::OllamaTextAdapter         extends BaseTextAdapter directly
+    └── ai-openrouter (text + responses)     extends BaseTextAdapter directly
+                                              (uses @openrouter/sdk natively)
+```
+
+Note: `ai-openai` ships only the Responses-based text adapter. For pure
+Chat Completions use cases without OpenAI-specific behaviour, use
+`ai-grok` or `ai-groq`, or build a new provider package extending
+`OpenAIBaseChatCompletionsTextAdapter`.
+
+## Direct use
+
+Most users don't import from this package directly; they install a
+provider package and the adapter from there does the work.
+
+If you're building an adapter for a new endpoint that the official
+`openai` SDK can talk to verbatim (vLLM, Together, Fireworks, a
+self-hosted gateway, …), import the abstract adapters from this package
+and subclass them. The existing providers are worked examples —
+`@tanstack/ai-grok` is the simplest (xAI's API is a near-direct OpenAI
+Chat Completions clone), `@tanstack/ai-groq` shows the
+`processStreamChunks` and `makeStructuredOutputCompatible` override
+pattern.

package/dist/esm/adapters/chat-completions-text.d.ts

@@ -1,25 +1,18 @@
 import { BaseTextAdapter, StructuredOutputOptions, StructuredOutputResult } from '@tanstack/ai/adapters';
-import { default as OpenAI_SDK } from 'openai';
+import { default as OpenAI } from 'openai';
+import { ChatCompletionChunk, ChatCompletionContentPart, ChatCompletionCreateParamsStreaming, ChatCompletionMessageParam } from 'openai/resources/chat/completions/completions';
 import { ContentPart, DefaultMessageMetadataByModality, Modality, ModelMessage, StreamChunk, TextOptions } from '@tanstack/ai';
-import { OpenAICompatibleClientConfig } from '../types/config.js';
 /**
- * OpenAI-compatible Chat Completions Text Adapter
- *
- * A generalized base class for providers that use the OpenAI Chat Completions API
- * (`/v1/chat/completions`). Providers like Grok, Groq, OpenRouter, and others can
- * extend this class and only need to:
- * - Set `baseURL` in the config
- * - Lock the generic type parameters to provider-specific types
- * - Override specific methods for quirks
- *
- * All methods that build requests or process responses are `protected` so subclasses
- * can override them.
+ * Shared implementation of the OpenAI Chat Completions API. Holds the
+ * stream-accumulator + AG-UI lifecycle logic and calls the OpenAI SDK
+ * directly. Subclasses (ai-openai, ai-grok, ai-groq) construct an OpenAI
+ * client with their provider-specific `baseURL` / headers and pass it in.
  */
-export declare class OpenAICompatibleChatCompletionsTextAdapter<TModel extends string, TProviderOptions extends Record<string, any> = Record<string, any>, TInputModalities extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TMessageMetadata extends DefaultMessageMetadataByModality = DefaultMessageMetadataByModality, TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>> extends BaseTextAdapter<TModel, TProviderOptions, TInputModalities, TMessageMetadata, TToolCapabilities> {
+export declare abstract class OpenAIBaseChatCompletionsTextAdapter<TModel extends string, TProviderOptions extends Record<string, unknown> = Record<string, unknown>, TInputModalities extends ReadonlyArray<Modality> = ReadonlyArray<Modality>, TMessageMetadata extends DefaultMessageMetadataByModality = DefaultMessageMetadataByModality, TToolCapabilities extends ReadonlyArray<string> = ReadonlyArray<string>> extends BaseTextAdapter<TModel, TProviderOptions, TInputModalities, TMessageMetadata, TToolCapabilities> {
     readonly kind: "text";
     readonly name: string;
-    protected client: OpenAI_SDK;
-    constructor(config: OpenAICompatibleClientConfig, model: TModel, name?: string);
+    protected client: OpenAI;
+    constructor(model: TModel, name: string, client: OpenAI);
     chatStream(options: TextOptions<TProviderOptions>): AsyncIterable<StreamChunk>;
     /**
      * Generate structured output using the provider's JSON Schema response format.
@@ -34,36 +27,71 @@ export declare class OpenAICompatibleChatCompletionsTextAdapter<TModel extends s
      * We apply provider-specific transformations for structured output compatibility.
      */
     structuredOutput(options: StructuredOutputOptions<TProviderOptions>): Promise<StructuredOutputResult<unknown>>;
+    /**
+     * Stream structured output. Single Chat Completions request with
+     * `response_format: json_schema` + `stream: true`. Emits the standard
+     * AG-UI lifecycle (`RUN_STARTED` → `REASONING_*?` → `TEXT_MESSAGE_*`
+     * carrying raw JSON deltas → terminal `CUSTOM 'structured-output.complete'`
+     * → `RUN_FINISHED`). Subclasses use the same SDK-call / reasoning /
+     * structured-output-transform hooks as `chatStream` / `structuredOutput` —
+     * no per-subclass override should be needed.
+     */
+    structuredOutputStream(options: StructuredOutputOptions<TProviderOptions>): AsyncIterable<StreamChunk>;
+    /**
+     * Cross-SDK abort detection for `structuredOutputStream`. Default duck-types
+     * on `name === 'APIUserAbortError'` (OpenAI SDK), `code === 'ERR_CANCELED'`,
+     * and standard `AbortError`s. Subclasses with proprietary error types (e.g.
+     * `@openrouter/sdk`'s `RequestAbortedError`) override to extend the check.
+     */
+    protected isAbortError(error: unknown): boolean;
     /**
      * Applies provider-specific transformations for structured output compatibility.
      * Override this in subclasses to handle provider-specific quirks.
      */
     protected makeStructuredOutputCompatible(schema: Record<string, any>, originalRequired?: Array<string>): Record<string, any>;
+    /**
+     * Extract reasoning content from a stream chunk. Default returns
+     * `undefined` because the OpenAI Chat Completions chunk shape doesn't
+     * carry reasoning. The chunk param is typed `unknown` so an override can
+     * narrow to its own SDK chunk type without an `as` dance — the base only
+     * passes through `processStreamChunks`'s structurally-iterated chunk.
+     */
+    protected extractReasoning(_chunk: unknown): {
+        text: string;
+    } | undefined;
+    /**
+     * Final shaping pass applied to parsed structured-output JSON before it is
+     * returned to the caller. Default converts `null` values to `undefined` so
+     * the result aligns with the original Zod schema's optional-field
+     * semantics. Subclasses with different conventions (OpenRouter historically
+     * preserves nulls) can override.
+     */
+    protected transformStructuredOutput(parsed: unknown): unknown;
     /**
      * Processes streamed chunks from the Chat Completions API and yields AG-UI events.
      * Override this in subclasses to handle provider-specific stream behavior.
      */
-    protected processStreamChunks(stream: AsyncIterable<OpenAI_SDK.Chat.Completions.ChatCompletionChunk>, options: TextOptions, aguiState: {
+    protected processStreamChunks(stream: AsyncIterable<ChatCompletionChunk>, options: TextOptions, aguiState: {
         runId: string;
+        threadId: string;
         messageId: string;
-        timestamp: number;
         hasEmittedRunStarted: boolean;
     }): AsyncIterable<StreamChunk>;
     /**
      * Maps common TextOptions to Chat Completions API request format.
      * Override this in subclasses to add provider-specific options.
      */
-    protected mapOptionsToRequest(options: TextOptions): OpenAI_SDK.Chat.Completions.ChatCompletionCreateParamsStreaming;
+    protected mapOptionsToRequest(options: TextOptions): ChatCompletionCreateParamsStreaming;
     /**
      * Converts a single ModelMessage to the Chat Completions API message format.
      * Override this in subclasses to handle provider-specific message formats.
      */
-    protected convertMessage(message: ModelMessage): OpenAI_SDK.Chat.Completions.ChatCompletionMessageParam;
+    protected convertMessage(message: ModelMessage): ChatCompletionMessageParam;
     /**
      * Converts a single ContentPart to the Chat Completions API content part format.
      * Override this in subclasses to handle additional content types or provider-specific metadata.
      */
-    protected convertContentPart(part: ContentPart): OpenAI_SDK.Chat.Completions.ChatCompletionContentPart | null;
+    protected convertContentPart(part: ContentPart): ChatCompletionContentPart | null;
     /**
      * Normalizes message content to an array of ContentPart.
      * Handles backward compatibility with string content.