@ai-sdk/gateway 4.0.0-beta.39 → 4.0.0-beta.40

package/docs/00-ai-gateway.mdx

@@ -176,6 +176,34 @@ const { text } = await generateText({
 
 AI Gateway language models can also be used in the `streamText` function and support structured data generation with [`Output`](/docs/reference/ai-sdk-core/output) (see [AI SDK Core](/docs/ai-sdk-core)).
 
+## Reranking Models
+
+You can create reranking models using the `rerankingModel` method on the provider instance:
+
+```ts
+import { rerank } from 'ai';
+import { gateway } from '@ai-sdk/gateway';
+
+const { ranking } = await rerank({
+  model: gateway.rerankingModel('cohere/rerank-v3.5'),
+  query: 'What is the capital of France?',
+  documents: [
+    'Paris is the capital of France.',
+    'Berlin is the capital of Germany.',
+    'Madrid is the capital of Spain.',
+  ],
+  topN: 2,
+});
+
+console.log(ranking);
+// [
+//   { originalIndex: 0, score: 0.89, document: 'Paris is the capital of France.' },
+//   { originalIndex: 2, score: 0.15, document: 'Madrid is the capital of Spain.' },
+// ]
+```
+
+Reranking models are useful for improving search results in retrieval-augmented generation (RAG) pipelines by re-scoring candidate documents after an initial retrieval step.
+
 ## Available Models
 
 The AI Gateway supports models from OpenAI, Anthropic, Google, Meta, xAI, Mistral, DeepSeek, Amazon Bedrock, Cohere, Perplexity, Alibaba, and other providers.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.0-beta.39",
+  "version": "4.0.0-beta.40",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

package/src/gateway-provider.ts

@@ -27,8 +27,10 @@ import { GatewayLanguageModel } from './gateway-language-model';
 import { GatewayEmbeddingModel } from './gateway-embedding-model';
 import { GatewayImageModel } from './gateway-image-model';
 import { GatewayVideoModel } from './gateway-video-model';
+import { GatewayRerankingModel } from './gateway-reranking-model';
 import type { GatewayEmbeddingModelId } from './gateway-embedding-model-settings';
 import type { GatewayImageModelId } from './gateway-image-model-settings';
+import type { GatewayRerankingModelId } from './gateway-reranking-model-settings';
 import type { GatewayVideoModelId } from './gateway-video-model-settings';
 import { gatewayTools } from './gateway-tools';
 import { getVercelOidcToken, getVercelRequestId } from './vercel-environment';
@@ -37,6 +39,7 @@ import type {
   LanguageModelV4,
   EmbeddingModelV4,
   ImageModelV4,
+  RerankingModelV4,
   Experimental_VideoModelV4,
   ProviderV4,
 } from '@ai-sdk/provider';
@@ -117,6 +120,16 @@ export interface GatewayProvider extends ProviderV4 {
    */
   videoModel(modelId: GatewayVideoModelId): Experimental_VideoModelV4;
 
+  /**
+   * Creates a model for reranking documents.
+   */
+  reranking(modelId: GatewayRerankingModelId): RerankingModelV4;
+
+  /**
+   * Creates a model for reranking documents.
+   */
+  rerankingModel(modelId: GatewayRerankingModelId): RerankingModelV4;
+
   /**
    * Gateway-specific tools executed server-side.
    */
@@ -354,6 +367,17 @@ export function createGatewayProvider(
       o11yHeaders: createO11yHeaders(),
     });
   };
+  const createRerankingModel = (modelId: GatewayRerankingModelId) => {
+    return new GatewayRerankingModel(modelId, {
+      provider: 'gateway',
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+      o11yHeaders: createO11yHeaders(),
+    });
+  };
+  provider.rerankingModel = createRerankingModel;
+  provider.reranking = createRerankingModel;
   provider.chat = provider.languageModel;
   provider.embedding = provider.embeddingModel;
   provider.image = provider.imageModel;

package/src/gateway-reranking-model-settings.ts

@@ -0,0 +1 @@
+export type GatewayRerankingModelId = 'cohere/rerank-v3.5' | (string & {});

package/src/gateway-reranking-model.ts

@@ -0,0 +1,114 @@
+import type {
+  RerankingModelV4,
+  SharedV4ProviderMetadata,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  lazySchema,
+  postJsonToApi,
+  resolve,
+  zodSchema,
+  type Resolvable,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { asGatewayError } from './errors';
+import { parseAuthMethod } from './errors/parse-auth-method';
+import type { GatewayConfig } from './gateway-config';
+
+export class GatewayRerankingModel implements RerankingModelV4 {
+  readonly specificationVersion = 'v4';
+
+  constructor(
+    readonly modelId: string,
+    private readonly config: GatewayConfig & {
+      provider: string;
+      o11yHeaders: Resolvable<Record<string, string>>;
+    },
+  ) {}
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  async doRerank({
+    documents,
+    query,
+    topN,
+    headers,
+    abortSignal,
+    providerOptions,
+  }: Parameters<RerankingModelV4['doRerank']>[0]): Promise<
+    Awaited<ReturnType<RerankingModelV4['doRerank']>>
+  > {
+    const resolvedHeaders = await resolve(this.config.headers());
+    try {
+      const {
+        responseHeaders,
+        value: responseBody,
+        rawValue,
+      } = await postJsonToApi({
+        url: this.getUrl(),
+        headers: combineHeaders(
+          resolvedHeaders,
+          headers ?? {},
+          this.getModelConfigHeaders(),
+          await resolve(this.config.o11yHeaders),
+        ),
+        body: {
+          documents,
+          query,
+          ...(topN != null ? { topN } : {}),
+          ...(providerOptions ? { providerOptions } : {}),
+        },
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewayRerankingResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        ...(abortSignal && { abortSignal }),
+        fetch: this.config.fetch,
+      });
+
+      return {
+        ranking: responseBody.ranking,
+        providerMetadata:
+          responseBody.providerMetadata as unknown as SharedV4ProviderMetadata,
+        response: { headers: responseHeaders, body: rawValue },
+        warnings: [],
+      };
+    } catch (error) {
+      throw await asGatewayError(error, await parseAuthMethod(resolvedHeaders));
+    }
+  }
+
+  private getUrl() {
+    return `${this.config.baseURL}/reranking-model`;
+  }
+
+  private getModelConfigHeaders() {
+    return {
+      'ai-reranking-model-specification-version': '4',
+      'ai-model-id': this.modelId,
+    };
+  }
+}
+
+const gatewayRerankingResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      ranking: z.array(
+        z.object({
+          index: z.number(),
+          relevanceScore: z.number(),
+        }),
+      ),
+      providerMetadata: z
+        .record(z.string(), z.record(z.string(), z.unknown()))
+        .optional(),
+    }),
+  ),
+);

package/src/index.ts

@@ -1,4 +1,5 @@
 export type { GatewayModelId } from './gateway-language-model-settings';
+export type { GatewayRerankingModelId } from './gateway-reranking-model-settings';
 export type { GatewayVideoModelId } from './gateway-video-model-settings';
 export type {
   GatewayLanguageModelEntry,