@ai-sdk/provider 4.0.14 → 4.0.16

package/src/evaluation-model/v4/evaluation-model-v4-question.ts

@@ -0,0 +1,32 @@
+import type { JSONObject, JSONValue } from '../../json-value';
+
+/** Shared state or structured instructions for an evaluation. */
+export type EvaluationModelV4Input =
+  | string
+  | Readonly<JSONObject>
+  | readonly JSONValue[];
+
+/** A judgment to make about the shared state. */
+export type EvaluationModelV4Question =
+  | {
+      readonly type: 'choice';
+      readonly instructions: EvaluationModelV4Input;
+      /** Nonempty map of option names to descriptions. Null means no description. */
+      readonly criteria: Readonly<
+        Record<string, EvaluationModelV4Input | null>
+      >;
+    }
+  | {
+      readonly type: 'score';
+      readonly instructions: EvaluationModelV4Input;
+      /** At least two ordered levels, indexed from zero. */
+      readonly criteria: readonly (EvaluationModelV4Input | null)[];
+    }
+  | {
+      readonly type: 'boolean';
+      readonly instructions: EvaluationModelV4Input;
+      readonly criteria?: {
+        readonly true?: EvaluationModelV4Input | null;
+        readonly false?: EvaluationModelV4Input | null;
+      };
+    };

package/src/evaluation-model/v4/evaluation-model-v4-result.ts

@@ -0,0 +1,56 @@
+import type {
+  SharedV4Headers,
+  SharedV4ProviderMetadata,
+  SharedV4Warning,
+} from '../../shared/v4';
+
+export type EvaluationModelV4Answer =
+  | {
+      type: 'choice';
+      /** The selected option, with maximal probability when a distribution exists. */
+      choice: string;
+      /** Complete distribution over the question's options, when available. */
+      probabilities?: Record<string, number>;
+    }
+  | {
+      type: 'score';
+      /** Fractional position in [0, number of levels - 1]. */
+      score: number;
+      /**
+       * Complete distribution, keyed by zero-based level indices as strings.
+       * When supplied, score is its probability-weighted mean.
+       */
+      probabilities?: Record<string, number>;
+    }
+  | {
+      type: 'boolean';
+      /** Model-estimated P(true), in [0, 1]. Not confidence in either outcome. */
+      probability: number;
+    };
+
+export type EvaluationModelV4Result = {
+  /** Exactly one answer per question, under the original question IDs. */
+  answers: Record<string, EvaluationModelV4Answer>;
+  /**
+   * Decimal places used when the provider rounds its output. Omit for full
+   * precision. Core allows half a unit in the last place per rounded value
+   * when checking distribution sums and weighted scores, preserving the values.
+   */
+  rounding?: {
+    probabilityDecimals?: number;
+    scoreDecimals?: number;
+  };
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+  };
+  warnings: SharedV4Warning[];
+  providerMetadata?: SharedV4ProviderMetadata;
+  response?: {
+    id?: string;
+    timestamp?: Date;
+    modelId?: string;
+    headers?: SharedV4Headers;
+    body?: unknown;
+  };
+};

package/src/evaluation-model/v4/evaluation-model-v4.ts

@@ -0,0 +1,16 @@
+import type { EvaluationModelV4CallOptions } from './evaluation-model-v4-call-options';
+import type { EvaluationModelV4Question } from './evaluation-model-v4-question';
+import type { EvaluationModelV4Result } from './evaluation-model-v4-result';
+
+/** Experimental evaluation model contract. May change in patch releases. */
+export type EvaluationModelV4 = {
+  readonly specificationVersion: 'v4';
+  readonly provider: string;
+  readonly modelId: string;
+  /** Supported question types, used to reject unsupported calls before any I/O. */
+  readonly supportedQuestionTypes: readonly EvaluationModelV4Question['type'][];
+  /** Evaluate every question against the same state. No partial results. */
+  doEvaluate(
+    options: EvaluationModelV4CallOptions,
+  ): PromiseLike<EvaluationModelV4Result>;
+};

package/src/evaluation-model/v4/index.ts

@@ -0,0 +1,10 @@
+export type { EvaluationModelV4 as Experimental_EvaluationModelV4 } from './evaluation-model-v4';
+export type { EvaluationModelV4CallOptions as Experimental_EvaluationModelV4CallOptions } from './evaluation-model-v4-call-options';
+export type {
+  EvaluationModelV4Input as Experimental_EvaluationModelV4Input,
+  EvaluationModelV4Question as Experimental_EvaluationModelV4Question,
+} from './evaluation-model-v4-question';
+export type {
+  EvaluationModelV4Answer as Experimental_EvaluationModelV4Answer,
+  EvaluationModelV4Result as Experimental_EvaluationModelV4Result,
+} from './evaluation-model-v4-result';

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './batch/index';
 export * from './embedding-model/index';
 export * from './errors/index';
+export * from './evaluation-model/v4/index';
 export * from './files/index';
 export * from './image-model/index';
 export * from './image-model-middleware/index';

package/src/json-value/json-value.ts

@@ -7,8 +7,8 @@ export type JSONValue =
   | string
   | number
   | boolean
-  | JSONObject
-  | JSONArray;
+  | Readonly<JSONObject>
+  | readonly JSONValue[];
 
 export type JSONObject = {
   [key: string]: JSONValue | undefined;

package/src/realtime-model/v4/realtime-model-v4-client-event.ts

@@ -1,3 +1,4 @@
+import type { SharedV4ProviderOptions } from '../../shared/v4/shared-v4-provider-options';
 import type { RealtimeModelV4ConversationItem } from './realtime-model-v4-conversation-item';
 import type { RealtimeModelV4SessionConfig } from './realtime-model-v4-session-config';
 
@@ -12,6 +13,31 @@ export type RealtimeModelV4ClientEvent =
   | {
       type: 'session-update';
       config: RealtimeModelV4SessionConfig;
+      eventId?: string;
+    }
+  | {
+      type: 'session-start';
+      config: RealtimeModelV4SessionConfig;
+      eventId?: string;
+    }
+  | {
+      type: 'session-close';
+      eventId?: string;
+    }
+  | {
+      type: 'input-audio-mute';
+      eventId?: string;
+    }
+  | {
+      type: 'input-audio-unmute';
+      eventId?: string;
+    }
+  | {
+      type: 'context-append';
+      content: string;
+      delegationId: string | null;
+      eventId?: string;
+      providerOptions?: SharedV4ProviderOptions;
     }
 
   // ── Input audio buffer ─────────────────────────────────────────────
@@ -22,6 +48,7 @@ export type RealtimeModelV4ClientEvent =
        * Base64-encoded audio chunk to append to the input buffer.
        */
       audio: string;
+      eventId?: string;
     }
   | {
       type: 'input-audio-commit';

package/src/realtime-model/v4/realtime-model-v4-server-event.ts

@@ -6,8 +6,55 @@
  * event data for debugging and provider-specific access.
  */
 export type RealtimeModelV4ServerEvent =
+  | {
+      type: 'session-started';
+      sessionId: string;
+      delegationMode?: 'client' | 'provider';
+      raw: unknown;
+    }
+  | {
+      type: 'session-closed';
+      sessionId?: string;
+      usage: { seconds: number };
+      reason: string;
+      raw: unknown;
+    }
+  | {
+      type: 'session-usage';
+      /** Cumulative duration snapshot, not an increment. */
+      usage: { seconds: number };
+      contextWindowUsageRatio?: number;
+      raw: unknown;
+    }
+  | {
+      type: 'audio-chunk';
+      delta: string;
+      raw: unknown;
+    }
+  | {
+      type: 'transcript-fragment';
+      speaker: 'user' | 'assistant';
+      delta: string;
+      startMs: number;
+      endMs: number;
+      raw: unknown;
+    }
+  | {
+      type: 'delegation-created';
+      delegationId: string;
+      target?: 'client' | 'provider';
+      offsetMs?: number;
+      responseId?: string;
+      raw: unknown;
+    }
+  | {
+      type: 'command-acknowledged';
+      /** Provider-native command name that was acknowledged. */
+      command: string;
+      clientEventId?: string;
+      raw: unknown;
+    }
   // ── Session lifecycle ──────────────────────────────────────────────
-
   | {
       type: 'session-created';
       sessionId?: string;
@@ -184,6 +231,7 @@ export type RealtimeModelV4ServerEvent =
       type: 'error';
       message: string;
       code?: string;
+      clientEventId?: string;
       raw: unknown;
     }
 

package/src/realtime-model/v4/realtime-model-v4.ts

@@ -29,6 +29,37 @@ export type RealtimeModelV4 = {
    */
   readonly modelId: string;
 
+  /** Conversation semantics and supported transports, when declared. */
+  readonly capabilities?: {
+    conversation: 'continuous' | 'turn-based';
+    transports: readonly ('websocket' | 'webrtc')[];
+    /** Omission preserves the legacy client-secret WebSocket connection. */
+    connections?: readonly (
+      | 'client-secret-websocket'
+      | 'server-websocket'
+      | 'webrtc'
+    )[];
+    /** Omission preserves session-update startup. WebRTC setup may start the session. */
+    startup?: 'session-start' | 'session-update';
+    /** Omission preserves transport-close finalization. */
+    finalization?: 'session-close' | 'transport-close';
+  };
+
+  /** Server-only connection settings. Headers can contain long-lived credentials. */
+  getServerWebSocketConfig?():
+    | { url: string; headers: Record<string, string> }
+    | PromiseLike<{ url: string; headers: Record<string, string> }>;
+
+  /** Provider-specific setup for the WebRTC event channel. */
+  getWebRTCConfig?(): { dataChannelLabel: string };
+
+  /** Server-side SDP exchange. Return only the answer and session ID to the client. */
+  doCreateWebRTCSession?(options: {
+    sdp: string;
+    sessionConfig?: RealtimeModelV4SessionConfig;
+    abortSignal?: AbortSignal;
+  }): PromiseLike<{ sessionId: string; sdp: string }>;
+
   /**
    * Server-side: Creates an ephemeral client secret for authenticating
    * browser-side WebSocket connections. The secret is short-lived and
@@ -36,7 +67,7 @@ export type RealtimeModelV4 = {
    *
    * Naming: "do" prefix to prevent accidental direct usage by the user.
    */
-  doCreateClientSecret(
+  doCreateClientSecret?(
     options: RealtimeModelV4ClientSecretOptions,
   ): PromiseLike<RealtimeModelV4ClientSecretResult>;
 
@@ -45,7 +76,7 @@ export type RealtimeModelV4 = {
    * when connecting. Each provider has its own authentication mechanism
    * (e.g. OpenAI uses subprotocol headers, xAI may use query params).
    */
-  getWebSocketConfig(options: { token: string; url: string }): {
+  getWebSocketConfig?(options: { token: string; url: string }): {
     url: string;
     protocols?: string[];
   };
@@ -63,6 +94,11 @@ export type RealtimeModelV4 = {
     raw: unknown,
   ): RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
 
+  /** Create a raw-event parser per connection and discard it on disconnect. */
+  createServerEventParser?(): (
+    raw: unknown,
+  ) => RealtimeModelV4ServerEvent | RealtimeModelV4ServerEvent[];
+
   /**
    * Browser-side: Serializes a normalized client event into the
    * provider's native JSON format for sending over the WebSocket.