@aeye/openai 0.3.9 → 0.4.0

package/dist/openai.d.ts

@@ -1,12 +1,14 @@
 /**
  * OpenAI Provider
  *
- * Provider for OpenAI's GPT models, DALL-E, Whisper, and TTS.
- * Also serves as base class for OpenAI-compatible providers.
+ * Provider for OpenAI's chat (Chat Completions and Responses), GPT Image,
+ * transcription, speech, and embedding models. Also serves as base class for
+ * OpenAI-compatible providers.
  */
-import type { AIContextAny, AIMetadataAny, EmbeddingRequest, EmbeddingResponse, ImageAnalyzeRequest, ImageEditRequest, ImageGenerationRequest, ImageGenerationResponse, Message, ModelInfo, Provider, SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse } from '@aeye/ai';
-import { BaseRequest, type Chunk, type DescriptorFamily, type Executor, type MessageContent, ModelInput, type Request, type Response, SchemaBudget, type Streamer, type ToolCall } from '@aeye/core';
+import type { AIContextAny, AIMetadataAny, BatchJob, BatchResult, DecisionRequest, DecisionResponse, EmbeddingRequest, EmbeddingResponse, ImageEditRequest, ImageGenerationRequest, ImageGenerationResponse, Message, ModelInfo, Provider, RerankRequest, RerankResponse, SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse } from '@aeye/ai';
+import { BaseRequest, type Chunk, type DescriptorFamily, type Executor, type MessageContent, type Model, ModelInput, type Request, type Response, type SchemaBudget, type SchemaRejectedError, type Streamer, type ToolCall } from '@aeye/core';
 import OpenAI from 'openai';
+import { type OpenAIDecisionParams, type SystemOneDecisionParams } from './decisions';
 import { type RetryConfig, type RetryEvents } from './retry';
 /**
  * Hook called before a request is made to the provider.
@@ -18,7 +20,7 @@ import { type RetryConfig, type RetryEvents } from './retry';
  * @param ctx - The context object
  * @param metadata - Optional metadata
  */
-export type PreRequestHook<TRequest = any, TParams = any> = (request: TRequest, params: TParams, ctx: AIContextAny, metadata?: AIMetadataAny) => void | Promise<void>;
+export type PreRequestHook<TRequest, TParams> = (request: TRequest, params: TParams, ctx: AIContextAny, metadata?: AIMetadataAny) => void | Promise<void>;
 /**
  * Hook called after a response is received from the provider.
  *
@@ -31,7 +33,7 @@ export type PreRequestHook<TRequest = any, TParams = any> = (request: TRequest,
  * @param ctx - The context object
  * @param metadata - Optional metadata
  */
-export type PostRequestHook<TRequest = any, TParams = any, TResponse = any> = (request: TRequest, params: TParams, response: TResponse, ctx: AIContextAny, metadata?: AIMetadataAny) => void | Promise<void>;
+export type PostRequestHook<TRequest, TParams, TResponse> = (request: TRequest, params: TParams, response: TResponse, ctx: AIContextAny, metadata?: AIMetadataAny) => void | Promise<void>;
 /**
  * Hook called when an error occurs during a request to the provider.
  *
@@ -43,47 +45,82 @@ export type PostRequestHook<TRequest = any, TParams = any, TResponse = any> = (r
  * @param ctx - The context object
  * @param metadata - Optional metadata
  */
-export type ErrorHook<TRequest = any, TParams = any> = (request: TRequest, params: TParams, error: Error, ctx: AIContextAny, metadata?: AIMetadataAny) => void | Promise<void>;
+export type ErrorHook<TRequest, TParams> = (request: TRequest, params: TParams, error: Error, ctx: AIContextAny, metadata?: AIMetadataAny) => void | Promise<void>;
 /**
- * Hooks for different operation types.
+ * Each operation's @aeye request, the parameters sent for it, and its @aeye response.
  */
-export interface OpenAIHooks {
-    chat?: {
-        beforeRequest?: PreRequestHook<Request, OpenAI.Chat.ChatCompletionCreateParams>;
-        afterRequest?: PostRequestHook<Request, OpenAI.Chat.ChatCompletionCreateParams, Response>;
-        onError?: ErrorHook<Request, OpenAI.Chat.ChatCompletionCreateParams>;
+export interface OpenAIOperations {
+    chat: {
+        request: Request;
+        params: OpenAI.Chat.ChatCompletionCreateParams;
+        response: Response;
     };
-    imageGenerate?: {
-        beforeRequest?: PreRequestHook<ImageGenerationRequest, OpenAI.Images.ImageGenerateParams>;
-        afterRequest?: PostRequestHook<ImageGenerationRequest, OpenAI.Images.ImageGenerateParams, ImageGenerationResponse>;
-        onError?: ErrorHook<ImageGenerationRequest, OpenAI.Images.ImageGenerateParams>;
+    responses: {
+        request: Request;
+        params: OpenAI.Responses.ResponseCreateParams;
+        response: Response;
     };
-    imageEdit?: {
-        beforeRequest?: PreRequestHook<ImageEditRequest, OpenAI.Images.ImageEditParams>;
-        afterRequest?: PostRequestHook<ImageEditRequest, OpenAI.Images.ImageEditParams, ImageGenerationResponse>;
-        onError?: ErrorHook<ImageEditRequest, OpenAI.Images.ImageEditParams>;
+    imageGenerate: {
+        request: ImageGenerationRequest;
+        params: OpenAI.Images.ImageGenerateParams;
+        response: ImageGenerationResponse;
     };
-    imageAnalyze?: {
-        beforeRequest?: PreRequestHook<ImageAnalyzeRequest, OpenAI.Chat.ChatCompletionCreateParams>;
-        afterRequest?: PostRequestHook<ImageAnalyzeRequest, OpenAI.Chat.ChatCompletionCreateParams, Response>;
-        onError?: ErrorHook<ImageAnalyzeRequest, OpenAI.Chat.ChatCompletionCreateParams>;
+    imageEdit: {
+        request: ImageEditRequest;
+        params: OpenAI.Images.ImageEditParams;
+        response: ImageGenerationResponse;
     };
-    transcribe?: {
-        beforeRequest?: PreRequestHook<TranscriptionRequest, OpenAI.Audio.TranscriptionCreateParams>;
-        afterRequest?: PostRequestHook<TranscriptionRequest, OpenAI.Audio.TranscriptionCreateParams, TranscriptionResponse>;
-        onError?: ErrorHook<TranscriptionRequest, OpenAI.Audio.TranscriptionCreateParams>;
+    transcribe: {
+        request: TranscriptionRequest;
+        params: OpenAI.Audio.TranscriptionCreateParams;
+        response: TranscriptionResponse;
     };
-    speech?: {
-        beforeRequest?: PreRequestHook<SpeechRequest, OpenAI.Audio.Speech.SpeechCreateParams>;
-        afterRequest?: PostRequestHook<SpeechRequest, OpenAI.Audio.Speech.SpeechCreateParams, SpeechResponse>;
-        onError?: ErrorHook<SpeechRequest, OpenAI.Audio.Speech.SpeechCreateParams>;
+    speech: {
+        request: SpeechRequest;
+        params: OpenAI.Audio.SpeechCreateParams;
+        response: SpeechResponse;
     };
-    embed?: {
-        beforeRequest?: PreRequestHook<EmbeddingRequest, OpenAI.EmbeddingCreateParams>;
-        afterRequest?: PostRequestHook<EmbeddingRequest, OpenAI.EmbeddingCreateParams, EmbeddingResponse>;
-        onError?: ErrorHook<EmbeddingRequest, OpenAI.EmbeddingCreateParams>;
+    embed: {
+        request: EmbeddingRequest;
+        params: OpenAI.EmbeddingCreateParams;
+        response: EmbeddingResponse;
     };
+    rerank: {
+        request: RerankRequest;
+        params: RerankParams;
+        response: RerankResponse;
+    };
+    decide: {
+        request: DecisionRequest;
+        params: OpenAIDecisionParams | SystemOneDecisionParams;
+        response: DecisionResponse;
+    };
+}
+/**
+ * Parameters of a rerank request, in the shape OpenAI-compatible rerank
+ * endpoints (OpenRouter's among them) take.
+ */
+export interface RerankParams {
+    model: string;
+    query: string;
+    documents: string[];
+    top_n?: number;
 }
+/**
+ * Hooks around one operation.
+ */
+export interface OperationHooks<TOperation extends OpenAIOperations[keyof OpenAIOperations]> {
+    beforeRequest?: PreRequestHook<TOperation['request'], TOperation['params']>;
+    afterRequest?: PostRequestHook<TOperation['request'], TOperation['params'], TOperation['response']>;
+    onError?: ErrorHook<TOperation['request'], TOperation['params']>;
+}
+/**
+ * Hooks for different operation types. Image analysis runs as chat, so
+ * it reports through the chat (or responses) hooks.
+ */
+export type OpenAIHooks = {
+    [K in keyof OpenAIOperations]?: OperationHooks<OpenAIOperations[K]>;
+};
 /**
  * Configuration options for the OpenAI provider.
  *
@@ -123,6 +160,7 @@ export interface OpenAIConfig {
     organization?: string;
     project?: string;
     store?: boolean;
+    api?: 'auto' | 'chat' | 'responses';
     retry?: RetryConfig;
     retryEvents?: RetryEvents;
     hooks?: OpenAIHooks;
@@ -134,12 +172,141 @@ export interface OpenAIConfig {
         transcription?: ModelInput;
         speech?: ModelInput;
         embedding?: ModelInput;
+        decision?: ModelInput;
+        rerank?: ModelInput;
     };
 }
+/**
+ * Default model for each operation.
+ */
+export type DefaultModels = NonNullable<OpenAIConfig['defaultModels']>;
+/**
+ * Everything one API call needs, resolved once from the request, context,
+ * and config.
+ */
+export interface OperationRun<TConfig> {
+    config: TConfig;
+    client: OpenAI;
+    ctx: AIContextAny;
+    metadata?: AIMetadataAny;
+    model: Model;
+    modelInfo?: ModelInfo;
+    signal?: AbortSignal;
+    retry<R>(call: (signal?: AbortSignal) => Promise<R>): Promise<R>;
+}
+/**
+ * The requests of a batch, as OpenAI and OpenRouter both take them: one
+ * endpoint and model, and each request's call parameters by id.
+ */
+export interface BatchSubmission {
+    endpoint: '/v1/chat/completions' | '/v1/responses';
+    model: string;
+    lines: Array<{
+        custom_id: string;
+        body: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming | OpenAI.Responses.ResponseCreateParamsNonStreaming;
+    }>;
+}
+/**
+ * One result of a batch, as OpenAI's output files and OpenRouter's results
+ * both carry it. A failed request has an error, or an error body.
+ */
+export interface BatchOutputLine {
+    custom_id: string;
+    response?: {
+        status_code: number;
+        body: OpenAI.Chat.ChatCompletion | OpenAI.Responses.Response | {
+            error: {
+                message: string;
+            };
+        };
+    } | null;
+    error?: {
+        message: string;
+    } | null;
+}
+/**
+ * OpenAI provider implementation for the @aeye framework.
+ *
+ * Supports the full range of OpenAI capabilities including:
+ * - Chat through Chat Completions, or the Responses API when a model or
+ *   request needs it (hosted tools, reasoning summaries or reasoning with
+ *   tools, Responses-only models)
+ * - Function calling and structured outputs, streaming, and reasoning
+ * - Image, audio, and file input; audio output
+ * - Image generation and editing with GPT Image
+ * - Transcription (with speaker diarization) and speech synthesis
+ * - Text embeddings
+ *
+ * Can be extended by other OpenAI-compatible providers (e.g., Azure OpenAI, OpenRouter).
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { OpenAIProvider } from '@aeye/openai';
+ *
+ * const provider = new OpenAIProvider({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ * });
+ *
+ * // Create an executor for chat completions
+ * const executor = provider.createExecutor();
+ *
+ * const response = await executor(
+ *   {
+ *     messages: [
+ *       { role: 'user', content: 'Hello!' }
+ *     ]
+ *   },
+ *   {},
+ *   { model: 'gpt-5.4-mini' }
+ * );
+ * ```
+ *
+ * @example With function calling
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const response = await executor(
+ *   {
+ *     messages: [
+ *       { role: 'user', content: 'What is the weather in San Francisco?' }
+ *     ],
+ *     tools: [
+ *       {
+ *         name: 'get_weather',
+ *         description: 'Get current weather',
+ *         parameters: z.object({
+ *           location: z.string(),
+ *         }),
+ *       }
+ *     ],
+ *     toolChoice: 'auto',
+ *   },
+ *   {},
+ *   { model: 'gpt-5.4-mini' }
+ * );
+ * ```
+ *
+ * @example Extending for custom providers
+ * ```typescript
+ * class CustomProvider extends OpenAIProvider {
+ *   readonly name = 'custom';
+ *
+ *   protected createClient(config: OpenAIConfig) {
+ *     return new OpenAI({
+ *       apiKey: config.apiKey,
+ *       baseURL: 'https://custom-api.example.com/v1',
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @template TConfig Configuration type extending OpenAIConfig
+ */
 export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig> implements Provider<TConfig> {
     readonly name: string;
     readonly config: TConfig;
     defaultMetadata?: Provider['defaultMetadata'];
+    protected readonly defaults: DefaultModels;
     constructor(config: TConfig);
     /**
      * Create OpenAI client from provider config.
@@ -149,16 +316,6 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      *
      * @param config Provider configuration
      * @returns Configured OpenAI client instance
-     *
-     * @example
-     * ```typescript
-     * protected createClient(config: OpenAIConfig): OpenAI {
-     *   return new OpenAI({
-     *     apiKey: config.apiKey,
-     *     baseURL: 'https://custom-endpoint.example.com/v1',
-     *   });
-     * }
-     * ```
      */
     protected createClient(config: TConfig): OpenAI;
     /**
@@ -174,41 +331,41 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
     /**
      * Customize image generation params before sending to API.
      *
-     * @param params Image generation parameters
+     * @param params Image generation parameters (mutate in place)
+     * @param request Original @aeye request
      * @param config Provider configuration
-     * @returns Modified parameters
      */
     protected augmentImageGenerateRequest?<TParams extends OpenAI.ImageGenerateParams>(params: TParams, request: ImageGenerationRequest, config: TConfig): void;
     /**
      * Customize image edit params before sending to API.
      *
-     * @param params Image generation parameters
+     * @param params Image edit parameters (mutate in place)
+     * @param request Original @aeye request
      * @param config Provider configuration
-     * @returns Modified parameters
      */
     protected augmentImageEditRequest?<TParams extends OpenAI.ImageEditParams>(params: TParams, request: ImageEditRequest, config: TConfig): void;
     /**
      * Customize transcription params before sending to API.
      *
-     * @param params Transcription parameters
+     * @param params Transcription parameters (mutate in place)
+     * @param request Original @aeye request
      * @param config Provider configuration
-     * @returns Modified parameters
      */
     protected augmentTranscriptionRequest?<TParams extends OpenAI.Audio.TranscriptionCreateParams>(params: TParams, request: TranscriptionRequest, config: TConfig): void;
     /**
      * Customize speech generation params before sending to API.
      *
-     * @param params Speech synthesis parameters
+     * @param params Speech synthesis parameters (mutate in place)
+     * @param request Original @aeye request
      * @param config Provider configuration
-     * @returns Modified parameters
      */
     protected augmentSpeechRequest?<TParams extends OpenAI.Audio.SpeechCreateParams>(params: TParams, request: SpeechRequest, config: TConfig): void;
     /**
      * Customize embedding params before sending to API.
      *
-     * @param params Embedding parameters
+     * @param params Embedding parameters (mutate in place)
+     * @param request Original @aeye request
      * @param config Provider configuration
-     * @returns Modified parameters
      */
     protected augmentEmbeddingRequest?<TParams extends OpenAI.EmbeddingCreateParams>(params: TParams, request: EmbeddingRequest, config: TConfig): void;
     /**
@@ -218,11 +375,17 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      * or to add provider-specific features.
      *
      * @param params OpenAI chat completion parameters
-     * @param config Provider configuration
      * @param request Original @aeye request
-     * @returns Modified parameters
+     * @param config Provider configuration
      */
     protected augmentChatRequest<TParams extends OpenAI.Chat.ChatCompletionCreateParams>(params: TParams, request: Request, config: TConfig): void;
+    /**
+     * Extra HTTP headers for a chat completion request, such as a router's
+     * feature flags. None by default.
+     *
+     * @param params The params about to be sent
+     */
+    protected chatHeaders(params: OpenAI.Chat.ChatCompletionCreateParams): Record<string, string> | undefined;
     /**
      * Augment chat message with provider-specific data.
      *
@@ -233,11 +396,6 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
     protected augmentChatMessage<TMessage extends OpenAI.Chat.ChatCompletionMessageParam>(chatMessage: TMessage, message: Message, config: TConfig): void;
     /**
      * Get augmented chat message with provider-specific data.
-     *
-     * @param chatMessage - OpenAI chat message
-     * @param message - Original @aeye message
-     * @param config - Provider configuration
-     * @returns
      */
     private getChatMessage;
     /**
@@ -249,47 +407,46 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      */
     protected augmentChatContent<TContent extends OpenAI.Chat.Completions.ChatCompletionContentPart>(chatContent: TContent, content: MessageContent, config: TConfig): void;
     /**
-     * Get augmented chat content part with provider-specific data.
-     *
-     * @param chatContent - OpenAI chat content part
-     * @param content - Original @aeye message content
-     * @param config - Provider configuration
-     * @returns
+     * Get augmented chat content part with provider-specific data. A cache
+     * breakpoint on the content marks the part.
      */
     private getChatContent;
     /**
      * Augment chat chunk with provider-specific data.
      *
-     * @param expected
-     * @param chunk
+     * @param expected - The chunk as received
+     * @param chunk - @aeye chunk to augment
+     * @param config - Provider configuration
      */
     protected augmentChatChunk<TParams extends OpenAI.Chat.Completions.ChatCompletionChunk>(expected: TParams, chunk: Chunk, config: TConfig): void;
     /**
      * Augment chat response with provider-specific data.
      *
-     * @param openai OpenAI chat completion response
-     * @param response @aeye response object to augment
-     * @returns
+     * @param expected - The completion as received
+     * @param response - @aeye response object to augment
+     * @param config - Provider configuration
      */
     protected augmentChatResponse<TParams extends OpenAI.Chat.Completions.ChatCompletion>(expected: TParams, response: Response, config: TConfig): void;
     /**
-     * Convert @aeye MessageContent to OpenAI text content format.
-     * @param x
-     * @param name
-     * @returns
+     * Convert @aeye MessageContent to OpenAI text content format, for roles
+     * that only accept text.
+     *
+     * @param x - Message content
+     * @param name - Who sent it, for placeholder text
+     * @param config - Provider configuration
      */
-    protected convertContentText(x: string | MessageContent[], name: string, config: TConfig): string | OpenAI.Chat.Completions.ChatCompletionContentPartText[];
+    protected convertContentText(x: string | MessageContent[], name: string, config: TConfig): OpenAI.Chat.Completions.ChatCompletionContentPartText[];
     /**
      * Convert @aeye MessageContent to OpenAI format.
-     * @param x
-     * @param name
-     * @returns
+     *
+     * @param x - Message content
+     * @param name - Who sent it, for placeholder text
+     * @param config - Provider configuration
      */
-    protected convertContent(x: string | MessageContent[], name: string, config: TConfig): Promise<string | OpenAI.Chat.Completions.ChatCompletionContentPart[]>;
+    protected convertContent(x: string | MessageContent[], name: string, config: TConfig): Promise<OpenAI.Chat.Completions.ChatCompletionContentPart[]>;
     /**
      * Convert @aeye ToolCall to OpenAI format.
      * @param x ToolCall object
-     * @returns
      */
     protected convertToolCall(x: ToolCall): OpenAI.Chat.ChatCompletionMessageToolCall;
     /**
@@ -301,15 +458,25 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      */
     protected convertName(name: string | undefined): string | undefined;
     /**
-     * Convert @aeye Request messages to OpenAI format.
+     * Convert @aeye Request messages to Chat Completions messages.
      *
      * Handles conversion of all message types (system, user, assistant, tool)
      * and content types (text, image, audio, file).
      *
      * @param request @aeye request object
+     * @param config Provider configuration
      * @returns Array of OpenAI-formatted messages
      */
     protected convertMessages(request: Request, config: TConfig): Promise<OpenAI.Chat.ChatCompletionMessageParam[]>;
+    /**
+     * Convert @aeye Request messages to Responses API input items. Assistant
+     * turns replay their Responses reasoning so stateless requests keep it, and
+     * tool results may carry images and files.
+     *
+     * @param request @aeye request object
+     * @param config Provider configuration
+     */
+    protected convertResponsesInput(request: Request, config: TConfig): Promise<OpenAI.Responses.ResponseInputItem[]>;
     /**
      * Convert @aeye tool definitions to OpenAI format.
      *
@@ -326,10 +493,9 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      *
      * @param request @aeye request (mutated: each tool's `descriptor` field is
      *                pinned for the validation roundtrip)
-     * @param model   the resolved model the request is targeting
      * @param budget  shared allocator (also fed by `convertResponseFormat`)
      */
-    protected convertTools(request: Request, model?: ModelInfo, budget?: SchemaBudget): OpenAI.Chat.ChatCompletionTool[] | undefined;
+    protected convertTools(request: Request, budget: SchemaBudget): OpenAI.Chat.ChatCompletionFunctionTool[] | undefined;
     /**
      * The set of strict descriptor families this provider can speak on the
      * wire. Defaults to `['openai']` — the OpenAI Chat Completions API only
@@ -339,29 +505,13 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      */
     protected supportedStrictFamilies: ReadonlySet<DescriptorFamily>;
     /**
-     * Build a SchemaBudget tuned to the strictest of the model's tool /
-     * structured-output families. Anthropic-style per-request limits apply
-     * across BOTH tool schemas and the response_format schema, so the budget
-     * is shared between `convertTools` and `convertResponseFormat`.
-     *
-     * Strict mode engages only when the model's resolved family is in
-     * `supportedStrictFamilies` AND the model has the corresponding
-     * capability (`'toolsStrict'` for tools, `'structured'` for output).
-     * Mismatched families fall back to LENIENT silently — protects the
-     * wire from receiving a dialect the API doesn't understand.
-     */
-    protected buildSchemaBudget(model?: ModelInfo): SchemaBudget;
-    /**
-     * Allocate per-tool descriptors in descending-priority order, then return
-     * them in original declaration order. Mutates `request.tools[i].descriptor`
-     * to record the chosen id for the Prompt's validation roundtrip.
+     * The schema budget for a call: from the selected model, or from the model
+     * id alone.
      */
-    private allocateToolDescriptors;
+    private schemaBudget;
     /**
      * Convert @aeye tool choice to OpenAI format.
      *
-     * Supports auto, required, none, and specific tool selection.
-     *
      * @param request @aeye request object
      * @returns OpenAI-formatted tool choice option or undefined
      */
@@ -378,10 +528,10 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      * matching strictify before parsing model output.
      *
      * @param request @aeye request object (mutated to record descriptor)
-     * @param model the resolved model the request is targeting
+     * @param budget shared allocator (also fed by `convertTools`)
      * @returns OpenAI-formatted response format or undefined
      */
-    protected convertResponseFormat(request: Request, model?: ModelInfo, budget?: SchemaBudget): OpenAI.Chat.ChatCompletionCreateParams['response_format'] | undefined;
+    protected convertResponseFormat(request: Request, budget: SchemaBudget): OpenAI.ResponseFormatText | OpenAI.ResponseFormatJSONObject | OpenAI.ResponseFormatJSONSchema | undefined;
     /**
      * List available models from OpenAI.
      *
@@ -398,194 +548,290 @@ export declare class OpenAIProvider<TConfig extends OpenAIConfig = OpenAIConfig>
      */
     checkHealth(config?: TConfig): Promise<boolean>;
     /**
-     * Get request data common to all request types.
+     * Resolve what one API call needs: the effective config and its client,
+     * the model (request, then context, then metadata, then configured and
+     * built-in defaults), and retries.
      *
+     * @param operation - Operation name for retry events and errors
      * @param request - The request
      * @param ctx - The context
-     * @param effectiveConfig - The effective configuration
-     * @param defaultModel - Optional default model
-     * @returns
-     */
-    getRequestData<R>(request: BaseRequest, requestSignal: AbortSignal | undefined, ctx: AIContextAny, effectiveConfig: TConfig, operation: string, defaultModel?: ModelInput): {
-        model: import("@aeye/core").Model;
-        retry: (fn: (signal?: AbortSignal) => Promise<R>) => Promise<R>;
-        signal: AbortSignal | undefined;
-    };
+     * @param metadata - Request metadata, for chat
+     * @param config - Per-call config override
+     * @param signal - Per-call abort signal
+     * @param defaultModel - Which configured default model applies
+     */
+    protected prepare(operation: string, request: BaseRequest, ctx: AIContextAny, metadata: AIMetadataAny | undefined, config: TConfig | undefined, signal: AbortSignal | undefined, defaultModel: keyof DefaultModels): OperationRun<TConfig>;
+    /**
+     * Send one API call with retries, around the operation's before and error
+     * hooks. A context-window rejection becomes a ContextWindowError.
+     */
+    protected send<K extends keyof OpenAIOperations, R>(op: K, run: OperationRun<TConfig>, request: OpenAIOperations[K]['request'], params: OpenAIOperations[K]['params'], call: (signal?: AbortSignal) => Promise<R>): Promise<R>;
+    /**
+     * Report a response to the operation's after hook and return it.
+     */
+    protected finish<K extends keyof OpenAIOperations>(op: K, run: OperationRun<TConfig>, request: OpenAIOperations[K]['request'], params: OpenAIOperations[K]['params'], response: OpenAIOperations[K]['response']): Promise<OpenAIOperations[K]['response']>;
+    /**
+     * The schema a bad request rejected, if any. OpenAI names it in the error
+     * message; OpenAI-compatible providers can look further.
+     *
+     * @param request - The request as sent
+     * @param error - The API's 400 or 422 error
+     */
+    protected rejectedSchema(request: Request, error: Error): SchemaRejectedError | undefined;
+    /**
+     * Send a chat call. A request that overflows the context window ends as
+     * `length` rather than failing, so the prompt loop can trim and retry. A
+     * rejected schema becomes a SchemaRejectedError.
+     */
+    private sendChat;
+    /**
+     * Relay streamed chunks, then report the assembled response to the after
+     * hook (even when the stream fails part way) and return it.
+     */
+    private relay;
+    /**
+     * Whether a chat request goes to the Responses API: always or never when
+     * configured, otherwise when the model is Responses-only or the request
+     * uses something only Responses offers.
+     *
+     * @param request - The request
+     * @param modelId - The model it targets
+     * @param config - Provider configuration
+     * @param model - The full model, whose registry entry says whether it is
+     *   Responses-only; the model id decides otherwise
+     */
+    protected usesResponses(request: Request, modelId: string, config: TConfig, model?: ModelInfo): boolean;
     /**
-     * Create an executor for chat completion requests.
+     * Chat Completions parameters for a request, before the stream flag.
      *
-     * The executor handles non-streaming chat completions with support for:
-     * - Multi-turn conversations
-     * - Function calling
-     * - Structured outputs
-     * - Vision (images)
-     * - Audio inputs
+     * @param request - The request
+     * @param run - The resolved call
+     * @param streaming - Whether the response will stream (audio output
+     *   streams only as PCM)
+     */
+    protected buildChatParams(request: Request, run: OperationRun<TConfig>, streaming: boolean): Promise<OpenAI.Chat.ChatCompletionCreateParamsNonStreaming>;
+    /**
+     * Responses API parameters for a request, before the stream flag.
+     * Reasoning comes back encrypted unless responses are stored, so later
+     * turns can replay it.
+     *
+     * @param request - The request
+     * @param run - The resolved call
+     */
+    protected buildResponsesParams(request: Request, run: OperationRun<TConfig>): Promise<OpenAI.Responses.ResponseCreateParamsNonStreaming>;
+    /**
+     * Map a Chat Completions result to a @aeye response.
+     */
+    private chatResponse;
+    /**
+     * Turn a Chat Completions stream into chunks.
+     *
+     * Tool calls are finalized only on positive evidence they're done: a
+     * finish reason on the chunk (the whole response is done), or a higher
+     * tool-call index (tool calls arrive in index order). Providers interleave
+     * usage-only and keep-alive chunks, so "not updated this chunk" is not
+     * evidence. Anything unfinished when the stream completes is finalized
+     * then; a stream that fails leaves its calls unfinished.
+     */
+    private chatChunks;
+    /**
+     * Run a chat request through Chat Completions.
+     */
+    private complete;
+    /**
+     * Stream a chat request through Chat Completions.
+     */
+    private completeStream;
+    /**
+     * Run a chat request through the Responses API.
+     */
+    private respond;
+    /**
+     * Stream a chat request through the Responses API.
+     */
+    private respondStream;
+    /**
+     * Create an executor for chat requests.
      *
      * @param config Optional configuration override
-     * @returns Executor function for chat completions
+     * @returns Executor function for chat
      * @throws {ProviderError} If request fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     createExecutor(config?: TConfig): Executor<AIContextAny, AIMetadataAny>;
     /**
-     * Create a streamer for streaming chat completion requests.
-     *
-     * The streamer yields chunks as they arrive from OpenAI, enabling
-     * real-time response rendering.
+     * Create a streamer for streaming chat requests.
      *
      * @param config Optional configuration override
      * @returns Streamer async generator function
      * @throws {ProviderError} If request fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     createStreamer(config?: TConfig): Streamer<AIContextAny, AIMetadataAny>;
     /**
-     * Get image generation parameters based on model and request.
-     *
-     * @param request - Image generation request
-     * @param model - Model ID
-     * @returns
+     * Relay image generation or edit progress, then report the final images
+     * to the after hook.
      */
-    getGenerateParameters(request: ImageGenerationRequest, model: string): OpenAI.Images.ImageGenerateParams;
+    private imageProgress;
     /**
      * Generate images.
      *
      * @param request Image generation request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Generated image URLs or base64 data
+     * @returns Generated images
      * @throws {ProviderError} If generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     generateImage: Provider['generateImage'];
     /**
-     * Generate images with streaming progress updates.
-     *
-     * Note: OpenAI's API doesn't natively support streaming image generation,
-     * so this implementation polls for progress or returns the result immediately.
+     * Generate images with streaming partial images.
      *
      * @param request Image generation request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
      * @returns Async generator yielding progress chunks
      * @throws {ProviderError} If generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     generateImageStream: Provider['generateImageStream'];
     /**
-     * Get image generation parameters based on model and request.
-     *
-     * @param request - Image generation request
-     * @param model - Model ID
-     * @returns
+     * Image edit parameters shared by the streaming and non-streaming paths.
      */
-    getEditParameters(request: ImageEditRequest, model: string): Omit<OpenAI.Images.ImageEditParams, 'image'>;
+    private editParams;
     /**
-     * Edit images using DALL-E models.
-     *
-     * Supports image editing with text prompts and optional masks.
+     * Edit or combine images with a text prompt and an optional mask.
      *
      * @param request Image edit request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Edited image URLs or base64 data
+     * @returns Edited images
      * @throws {ProviderError} If editing fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     editImage: Provider['editImage'];
     /**
-     * Edit images with streaming progress updates.
-     *
-     * Note: OpenAI's API doesn't natively support streaming image editing,
-     * so this implementation returns the result with progress indicators.
+     * Edit images with streaming partial images.
      *
      * @param request Image edit request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
      * @returns Async generator yielding progress chunks
      * @throws {ProviderError} If editing fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     editImageStream: Provider['editImageStream'];
     /**
-     * Transcribe audio to text using Whisper models.
-     *
-     * Supports multiple audio formats and optional timestamps.
+     * Transcription parameters shared by the streaming and non-streaming
+     * paths. Diarization needs chunking, and known speakers go as data URLs.
+     */
+    private transcriptionParams;
+    /**
+     * Transcribe audio to text, with timed and speaker-labeled segments when
+     * the response format provides them.
      *
      * @param request Transcription request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Transcription text and optional metadata
+     * @returns Transcription text and segments
      * @throws {ProviderError} If transcription fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     transcribe: Provider['transcribe'];
     /**
-     * Transcribe audio with streaming progress updates.
-     *
-     * Note: OpenAI's API doesn't natively support streaming transcription,
-     * so this implementation returns the result with progress indicators.
+     * Transcribe audio with streaming text and segments.
      *
      * @param request Transcription request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
      * @returns Async generator yielding transcription chunks
      * @throws {ProviderError} If transcription fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     transcribeStream: Provider['transcribeStream'];
     /**
-     * Generate speech from text using TTS models.
-     *
-     * Supports multiple voices and audio formats.
+     * Generate speech from text.
      *
      * @param request Speech synthesis request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Audio buffer and content type
+     * @returns Audio stream and its format
      * @throws {ProviderError} If speech generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     speech: Provider['speech'];
     /**
      * Generate text embeddings for semantic search and similarity.
      *
-     * Supports text-embedding-3-small, text-embedding-3-large, and ada-002 models.
-     *
      * @param request Embedding request parameters
-     * @param ctx Context object (not used)
+     * @param ctx Context object
      * @param config Optional configuration override
      * @returns Array of embeddings with usage information
      * @throws {ProviderError} If embedding generation fails
-     * @throws {RateLimitError} If rate limit is exceeded
      */
     embed: Provider['embed'];
     /**
-     * Analyze images using vision-capable models.
+     * Typed answers about an input. A conversation goes in as Responses input.
      *
-     * This method converts the image analysis request into a chat request
-     * with image content and calls the chat API internally.
-     *
-     * @param request Image analysis request parameters
-     * @param ctx Context object (not used)
+     * @param request Decision request parameters
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Analysis response with text content
-     * @throws {ProviderError} If analysis fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     * @returns Answers by question name
      */
-    analyzeImage: Provider['analyzeImage'];
+    decide: Provider['decide'];
     /**
-     * Analyze images with streaming response.
+     * Run chat requests as one batch on one model. Each request becomes the
+     * same call a direct request would make, through Responses when any of
+     * them needs it.
      *
-     * This method converts the image analysis request into a chat request
-     * with image content and calls the streaming chat API internally.
+     * @param requests Chat requests, whose results come back in this order
+     * @param ctx Context object
+     * @param config Optional configuration override
+     * @returns The submitted batch
+     */
+    submitBatch: Provider['submitBatch'];
+    /**
+     * A batch as it stands now, with its results once it completes.
      *
-     * @param request Image analysis request parameters
-     * @param ctx Context object (not used)
+     * @param job The batch from submitBatch
+     * @param ctx Context object
      * @param config Optional configuration override
-     * @returns Async generator yielding response chunks
-     * @throws {ProviderError} If analysis fails
-     * @throws {RateLimitError} If rate limit is exceeded
+     */
+    getBatch: Provider['getBatch'];
+    /**
+     * Start a batch: OpenAI takes the requests as an uploaded JSONL file.
+     *
+     * @param batch The requests
+     * @param run The resolved call
+     */
+    protected createBatch(batch: BatchSubmission, run: OperationRun<TConfig>): Promise<BatchJob>;
+    /**
+     * Read a batch: OpenAI writes results, and failed requests, to files.
+     *
+     * @param job The batch
+     * @param run The resolved call
+     */
+    protected retrieveBatch(job: BatchJob, run: OperationRun<TConfig>): Promise<BatchJob>;
+    /**
+     * A batch as @aeye reports it.
+     */
+    private batchJob;
+    /**
+     * Results in request order, each mapped as its direct call would be.
+     *
+     * @param lines The results, in any order
+     * @param total How many requests the batch had
+     * @param run The resolved call
+     */
+    protected batchResults(lines: BatchOutputLine[], total: number, run: OperationRun<TConfig>): BatchResult[];
+    /**
+     * One batch result body as a @aeye response.
+     */
+    private batchResponse;
+    /**
+     * An image analysis request as a chat request, and the metadata naming
+     * the configured analysis model as the fallback.
+     */
+    private analysisChat;
+    /**
+     * Analyze images with a vision model. Runs as a chat request, reported
+     * through the chat hooks.
+     */
+    analyzeImage: Provider['analyzeImage'];
+    /**
+     * Analyze images with a vision model, streaming the answer. Runs as a
+     * chat request, reported through the chat hooks.
      */
     analyzeImageStream: Provider['analyzeImageStream'];
 }