@jerome-benoit/sap-ai-provider-v2 4.1.2 → 4.2.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EmbeddingModelV2, SharedV2ProviderOptions, SharedV2ProviderMetadata, SharedV2Headers, LanguageModelV2, LanguageModelV2CallOptions, LanguageModelV2Content, LanguageModelV2FinishReason, LanguageModelV2ResponseMetadata, LanguageModelV2Usage, LanguageModelV2CallWarning, LanguageModelV2StreamPart } from '@ai-sdk/provider';
+import { EmbeddingModelV2, SharedV2ProviderOptions, SharedV2ProviderMetadata, SharedV2Headers, LanguageModelV2, LanguageModelV2CallOptions, LanguageModelV2Content, LanguageModelV2FinishReason, LanguageModelV2ResponseMetadata, LanguageModelV2Usage, LanguageModelV2CallWarning, LanguageModelV2StreamPart, ProviderV2, ImageModelV2 } from '@ai-sdk/provider';
 import { DeploymentIdConfig, ResourceGroupConfig } from '@sap-ai-sdk/ai-api/internal.js';
 import { HttpDestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity';
 import { EmbeddingModelParams, FilteringModule, GroundingModule, MaskingModule, ChatCompletionTool, TranslationModule, ChatModel } from '@sap-ai-sdk/orchestration';
@@ -6,6 +6,15 @@ export { AssistantChatMessage, ChatCompletionRequest, ChatCompletionTool, ChatMe
 import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
 import { InferSchema } from '@ai-sdk/provider-utils';
 
+/**
+ * SAP AI Embedding Model implementation.
+ *
+ * This module provides an EmbeddingModelV3 implementation that bridges
+ * the Vercel AI SDK with SAP AI Core's Orchestration API for generating
+ * text embeddings using the official SAP AI SDK (@sap-ai-sdk/orchestration).
+ * @module sap-ai-embedding-model
+ */
+
 /**
  * Model ID type for SAP AI embedding models.
  *
@@ -23,16 +32,16 @@ interface SAPAIEmbeddingSettings {
      * Maximum number of embeddings per API call.
      * @default 2048
      */
-    maxEmbeddingsPerCall?: number;
+    readonly maxEmbeddingsPerCall?: number;
     /**
      * Additional model parameters passed to the embedding API.
      */
-    modelParams?: EmbeddingModelParams;
+    readonly modelParams?: EmbeddingModelParams;
     /**
      * Embedding task type.
      * @default 'text'
      */
-    type?: "document" | "query" | "text";
+    readonly type?: "document" | "query" | "text";
 }
 
 /**
@@ -53,9 +62,9 @@ interface SAPAIEmbeddingSettings {
  * @internal
  */
 interface SAPAIEmbeddingConfig {
-    deploymentConfig: DeploymentIdConfig | ResourceGroupConfig;
-    destination?: HttpDestinationOrFetchOptions;
-    provider: string;
+    readonly deploymentConfig: DeploymentIdConfig | ResourceGroupConfig;
+    readonly destination?: HttpDestinationOrFetchOptions;
+    readonly provider: string;
 }
 /**
  * SAP AI Core Embedding Model implementing the Vercel AI SDK EmbeddingModelV2 interface.
@@ -128,6 +137,7 @@ declare class SAPAIEmbeddingModelV2 implements EmbeddingModelV2<string> {
      * @param options.providerOptions - Optional provider-specific options
      * @param options.headers - Optional HTTP headers
      * @returns Promise resolving to embeddings and metadata in V2 format
+     * @since 1.0.0
      */
     doEmbed(options: {
         abortSignal?: AbortSignal;
@@ -148,8 +158,9 @@ declare class SAPAIEmbeddingModelV2 implements EmbeddingModelV2<string> {
 }
 
 /**
- * The provider identifier used for provider options.
- * Use this key in `providerOptions` to pass SAP AI-specific options.
+ * Default provider name.
+ *
+ * Use this as key in `providerOptions` and `providerMetadata` when using the default provider name.
  * @example
  * ```typescript
  * providerOptions: {
@@ -158,6 +169,22 @@ declare class SAPAIEmbeddingModelV2 implements EmbeddingModelV2<string> {
  * ```
  */
 declare const SAP_AI_PROVIDER_NAME: "sap-ai";
+/**
+ * Extracts the provider name from a provider identifier.
+ *
+ * Following the AI SDK convention, provider identifiers use the format `{name}.{type}`
+ * (e.g., `"openai.chat"`, `"anthropic.messages"`). This function extracts the provider name
+ * for use with `providerOptions` and `providerMetadata`, which use the provider name as key.
+ * @param providerIdentifier - The provider identifier (e.g., `"sap-ai.chat"`, `"sap-ai.embedding"`)
+ * @returns The provider name (e.g., `"sap-ai"`)
+ * @example
+ * ```typescript
+ * getProviderName("sap-ai.chat") // => "sap-ai"
+ * getProviderName("sap-ai-core.embedding") // => "sap-ai-core"
+ * getProviderName("sap-ai") // => "sap-ai" (no type suffix)
+ * ```
+ */
+declare function getProviderName(providerIdentifier: string): string;
 /**
  * Zod schema for SAP AI language model provider options.
  *
@@ -327,7 +354,7 @@ interface SAPAISettings {
      * });
      * ```
      */
-    filtering?: FilteringModule;
+    readonly filtering?: FilteringModule;
     /**
      * Grounding module configuration for document-based retrieval (RAG).
      * Enables retrieval-augmented generation using SAP Document Grounding Service.
@@ -356,7 +383,7 @@ interface SAPAISettings {
      * });
      * ```
      */
-    grounding?: GroundingModule;
+    readonly grounding?: GroundingModule;
     /**
      * Whether to include assistant reasoning parts in the SAP prompt conversion.
      *
@@ -370,7 +397,7 @@ interface SAPAISettings {
      * const prodModel = provider('gpt-4o'); // includeReasoning defaults to false
      * ```
      */
-    includeReasoning?: boolean;
+    readonly includeReasoning?: boolean;
     /**
      * Masking configuration for SAP AI Core orchestration.
      * When provided, sensitive information in prompts can be anonymized or
@@ -392,22 +419,22 @@ interface SAPAISettings {
      * });
      * ```
      */
-    masking?: MaskingModule;
+    readonly masking?: MaskingModule;
     /**
      * Model generation parameters that control the output.
      */
-    modelParams?: {
+    readonly modelParams?: {
         /**
          * Frequency penalty between -2.0 and 2.0.
          * Positive values penalize tokens based on their frequency.
          * If not specified, the model's default is used (typically 0).
          */
-        frequencyPenalty?: number;
+        readonly frequencyPenalty?: number;
         /**
          * Maximum number of tokens to generate.
          * Higher values allow for longer responses but increase latency and cost.
          */
-        maxTokens?: number;
+        readonly maxTokens?: number;
         /**
          * Number of completions to generate.
          * Multiple completions provide alternative responses.
@@ -416,38 +443,38 @@ interface SAPAISettings {
          * models, the parameter is silently omitted from the request.
          * If not specified, typically defaults to 1 on the model side.
          */
-        n?: number;
+        readonly n?: number;
         /**
          * Whether to enable parallel tool calls.
          * When enabled, the model can call multiple tools in parallel.
          *
          * Note: This uses the SAP/OpenAI-style key `parallel_tool_calls`.
          */
-        parallel_tool_calls?: boolean;
+        readonly parallel_tool_calls?: boolean;
         /**
          * Presence penalty between -2.0 and 2.0.
          * Positive values penalize tokens that have appeared in the text.
          * If not specified, the model's default is used (typically 0).
          */
-        presencePenalty?: number;
+        readonly presencePenalty?: number;
         /**
          * Sampling temperature between 0 and 2.
          * Higher values make output more random, lower values more deterministic.
          * If not specified, the model's default temperature is used.
          */
-        temperature?: number;
+        readonly temperature?: number;
         /**
          * Nucleus sampling parameter between 0 and 1.
          * Controls diversity via cumulative probability cutoff.
          * If not specified, the model's default topP is used (typically 1).
          */
-        topP?: number;
+        readonly topP?: number;
     };
     /**
      * Specific version of the model to use.
      * If not provided, the latest version will be used.
      */
-    modelVersion?: string;
+    readonly modelVersion?: string;
     /**
      * Response format for templating prompt (OpenAI-compatible)
      * Allows specifying structured output formats
@@ -464,18 +491,18 @@ interface SAPAISettings {
      * });
      * ```
      */
-    responseFormat?: {
-        json_schema: {
-            description?: string;
-            name: string;
-            schema?: unknown;
-            strict?: boolean | null;
+    readonly responseFormat?: {
+        readonly json_schema: {
+            readonly description?: string;
+            readonly name: string;
+            readonly schema?: unknown;
+            readonly strict?: boolean | null;
         };
-        type: "json_schema";
+        readonly type: "json_schema";
     } | {
-        type: "json_object";
+        readonly type: "json_object";
     } | {
-        type: "text";
+        readonly type: "text";
     };
     /**
      * Tool definitions in SAP AI SDK format
@@ -508,7 +535,7 @@ interface SAPAISettings {
      * });
      * ```
      */
-    tools?: ChatCompletionTool[];
+    readonly tools?: ChatCompletionTool[];
     /**
      * Translation module configuration for input/output translation.
      * Enables automatic translation using SAP Document Translation service.
@@ -532,7 +559,7 @@ interface SAPAISettings {
      * });
      * ```
      */
-    translation?: TranslationModule;
+    readonly translation?: TranslationModule;
 }
 
 /**
@@ -553,9 +580,9 @@ interface SAPAISettings {
  * @internal
  */
 interface SAPAIConfig {
-    deploymentConfig: DeploymentIdConfig | ResourceGroupConfig;
-    destination?: HttpDestinationOrFetchOptions;
-    provider: string;
+    readonly deploymentConfig: DeploymentIdConfig | ResourceGroupConfig;
+    readonly destination?: HttpDestinationOrFetchOptions;
+    readonly provider: string;
 }
 /**
  * SAP AI Language Model V2 implementation.
@@ -767,7 +794,7 @@ interface SAPAIProviderSettings {
      * Default model settings applied to every model instance created by this provider.
      * Per-call settings provided to the model will override these.
      */
-    defaultSettings?: SAPAISettings;
+    readonly defaultSettings?: SAPAISettings;
     /**
      * SAP AI Core deployment ID.
      *
@@ -778,7 +805,7 @@ interface SAPAIProviderSettings {
      * deploymentId: 'd65d81e7c077e583'
      * ```
      */
-    deploymentId?: string;
+    readonly deploymentId?: string;
     /**
      * Custom destination configuration for SAP AI Core.
      *
@@ -793,7 +820,32 @@ interface SAPAIProviderSettings {
      * }
      * ```
      */
-    destination?: HttpDestinationOrFetchOptions;
+    readonly destination?: HttpDestinationOrFetchOptions;
+    /**
+     * Provider name.
+     *
+     * Used as the key for `providerOptions` and `providerMetadata` in AI SDK calls.
+     * The provider identifier (exposed via `model.provider`) follows the AI SDK convention
+     * `{name}.{type}` (e.g., `"sap-ai.chat"`, `"sap-ai.embedding"`).
+     * @default 'sap-ai'
+     * @example
+     * ```typescript
+     * const provider = createSAPAIProvider({ name: 'sap-ai-core' });
+     * const model = provider('gpt-4o');
+     *
+     * console.log(model.provider); // => "sap-ai-core.chat"
+     *
+     * // Use provider name in providerOptions:
+     * await generateText({
+     *   model,
+     *   prompt: 'Hello',
+     *   providerOptions: {
+     *     'sap-ai-core': { includeReasoning: true }
+     *   }
+     * });
+     * ```
+     */
+    readonly name?: string;
     /**
      * SAP AI Core resource group.
      *
@@ -808,14 +860,14 @@ interface SAPAIProviderSettings {
      * resourceGroup: 'development' // Development environment
      * ```
      */
-    resourceGroup?: string;
+    readonly resourceGroup?: string;
     /**
      * Whether to emit warnings for ambiguous configurations.
      *
      * When enabled (default), the provider will warn when mutually-exclusive
      * settings are provided (e.g. both `deploymentId` and `resourceGroup`).
      */
-    warnOnAmbiguousConfig?: boolean;
+    readonly warnOnAmbiguousConfig?: boolean;
 }
 /**
  * SAP AI Provider V2 interface.
@@ -843,7 +895,7 @@ interface SAPAIProviderSettings {
  * const chatModel = provider.languageModel('gpt-4o');
  * ```
  */
-interface SAPAIProviderV2 {
+interface SAPAIProviderV2 extends ProviderV2 {
     /**
      * Create a language model instance (V2).
      * @param modelId - The SAP AI Core model identifier (e.g., 'gpt-4o', 'anthropic--claude-3.5-sonnet')
@@ -868,12 +920,37 @@ interface SAPAIProviderV2 {
      * @param modelId - The embedding model identifier (e.g., 'text-embedding-ada-002')
      * @param settings - Optional embedding model settings
      * @returns Configured SAP AI embedding model instance (V2)
+     * @example
+     * ```typescript
+     * import { embed } from 'ai';
+     *
+     * const { embedding } = await embed({
+     *   model: provider.embedding('text-embedding-ada-002'),
+     *   value: 'Hello, world!'
+     * });
+     * ```
      */
     embedding(modelId: SAPAIEmbeddingModelId, settings?: SAPAIEmbeddingSettings): SAPAIEmbeddingModelV2;
+    /**
+     * Image model stub for ProviderV2 interface compliance.
+     *
+     * SAP AI Core Orchestration Service does not currently support image generation.
+     * This method always throws a `NoSuchModelError` to indicate that image generation
+     * is not available through this provider.
+     * @param modelId - The image model identifier (not used)
+     * @throws {NoSuchModelError} Always throws - image generation is not supported
+     * @example
+     * ```typescript
+     * // This will always throw NoSuchModelError
+     * provider.imageModel('dall-e-3'); // throws NoSuchModelError
+     * ```
+     */
+    imageModel(modelId: string): ImageModelV2;
     /**
      * Create a language model instance (V2).
      *
-     * This is the standard method for creating language models.
+     * Standard ProviderV2 method for creating language models.
+     * Equivalent to calling the provider function directly or using `chat()`.
      * @param modelId - The SAP AI Core model identifier
      * @param settings - Optional model configuration settings
      * @returns Configured SAP AI language model instance (V2)
@@ -882,7 +959,8 @@ interface SAPAIProviderV2 {
     /**
      * Create a text embedding model instance (V2).
      *
-     * Alias for the embedding() method. Provides compatibility with common provider patterns.
+     * Standard ProviderV2 method for creating embedding models.
+     * Equivalent to calling `embedding()`.
      * @param modelId - The embedding model identifier
      * @param settings - Optional embedding model settings
      * @returns Configured SAP AI embedding model instance (V2)
@@ -969,4 +1047,4 @@ declare function createSAPAIProvider(options?: SAPAIProviderSettings): SAPAIProv
  */
 declare const sapai: SAPAIProviderV2;
 
-export { type DeploymentConfig, SAPAIEmbeddingModelV2 as SAPAIEmbeddingModel, type SAPAIEmbeddingModelId, type SAPAIEmbeddingProviderOptions, type SAPAIEmbeddingSettings, type SAPAILanguageModelProviderOptions, type SAPAIModelId, type SAPAIProviderV2 as SAPAIProvider, type SAPAIProviderSettings, type SAPAISettings, SAP_AI_PROVIDER_NAME, createSAPAIProvider, sapAIEmbeddingProviderOptions, sapAILanguageModelProviderOptions, sapai };
+export { type DeploymentConfig, SAPAIEmbeddingModelV2 as SAPAIEmbeddingModel, type SAPAIEmbeddingModelId, type SAPAIEmbeddingProviderOptions, type SAPAIEmbeddingSettings, type SAPAILanguageModelProviderOptions, type SAPAIModelId, type SAPAIProviderV2 as SAPAIProvider, type SAPAIProviderSettings, type SAPAISettings, SAP_AI_PROVIDER_NAME, createSAPAIProvider, getProviderName, sapAIEmbeddingProviderOptions, sapAILanguageModelProviderOptions, sapai };

package/dist/index.js

@@ -30207,6 +30207,10 @@ function tryExtractSAPErrorFromMessage(message) {
 import { lazySchema, zodSchema } from "@ai-sdk/provider-utils";
 import { z } from "zod";
 var SAP_AI_PROVIDER_NAME = "sap-ai";
+function getProviderName(providerIdentifier) {
+  const dotIndex = providerIdentifier.indexOf(".");
+  return dotIndex === -1 ? providerIdentifier : providerIdentifier.slice(0, dotIndex);
+}
 var modelParamsSchema = z.object({
   /**
    * Frequency penalty between -2.0 and 2.0.
@@ -30381,6 +30385,7 @@ var SAPAIEmbeddingModel = class {
    * the SAP AI SDK's OrchestrationEmbeddingClient.
    * @param options - The embedding request options
    * @returns Promise resolving to embeddings and usage information
+   * @since 1.0.0
    * @example
    * ```typescript
    * const result = await model.doEmbed({
@@ -30393,8 +30398,9 @@ var SAPAIEmbeddingModel = class {
    */
   async doEmbed(options) {
     const { abortSignal, providerOptions, values } = options;
+    const providerName = getProviderName(this.config.provider);
     const sapOptions = await parseProviderOptions({
-      provider: SAP_AI_PROVIDER_NAME,
+      provider: providerName,
       providerOptions,
       schema: sapAIEmbeddingProviderOptions
     });
@@ -30424,7 +30430,7 @@ var SAPAIEmbeddingModel = class {
         (data) => this.normalizeEmbedding(data.embedding)
       );
       const providerMetadata = {
-        "sap-ai": {
+        [providerName]: {
           model: this.modelId
         }
       };
@@ -30523,6 +30529,7 @@ var SAPAIEmbeddingModelV2 = class {
    * @param options.providerOptions - Optional provider-specific options
    * @param options.headers - Optional HTTP headers
    * @returns Promise resolving to embeddings and metadata in V2 format
+   * @since 1.0.0
    */
   async doEmbed(options) {
     const v3Options = {
@@ -30563,6 +30570,9 @@ function castProviderMetadataV3ToV2(v3Metadata) {
   return v3Metadata;
 }
 
+// src/sap-ai-provider-v2.ts
+import { NoSuchModelError as NoSuchModelError2 } from "@ai-sdk/provider";
+
 // src/sap-ai-language-model.ts
 import { parseProviderOptions as parseProviderOptions2 } from "@ai-sdk/provider-utils";
 import {
@@ -30947,11 +30957,12 @@ var SAPAILanguageModel = class {
         tokenUsage,
         toolCalls
       };
+      const providerName = getProviderName(this.config.provider);
       return {
         content,
         finishReason,
         providerMetadata: {
-          "sap-ai": {
+          [providerName]: {
             finishReason: finishReasonRaw ?? "unknown",
             finishReasonMapped: finishReason,
             ...typeof responseHeaders?.["x-request-id"] === "string" ? { requestId: responseHeaders["x-request-id"] } : {}
@@ -31082,6 +31093,7 @@ var SAPAILanguageModel = class {
       const toolCallsInProgress = /* @__PURE__ */ new Map();
       const sdkStream = streamResponse.stream;
       const modelId = this.modelId;
+      const providerName = getProviderName(this.config.provider);
       const warningsSnapshot = [...warnings];
       const warningsOut = [...warningsSnapshot];
       const transformedStream = new ReadableStream({
@@ -31270,7 +31282,7 @@ var SAPAILanguageModel = class {
             controller.enqueue({
               finishReason: streamState.finishReason,
               providerMetadata: {
-                "sap-ai": {
+                [providerName]: {
                   finishReason: streamState.finishReason.raw,
                   responseId
                 }
@@ -31326,8 +31338,9 @@ var SAPAILanguageModel = class {
    * @internal
    */
   async buildOrchestrationConfig(options) {
+    const providerName = getProviderName(this.config.provider);
     const sapOptions = await parseProviderOptions2({
-      provider: SAP_AI_PROVIDER_NAME,
+      provider: providerName,
       providerOptions: options.providerOptions,
       schema: sapAILanguageModelProviderOptions
     });
@@ -31449,21 +31462,26 @@ var SAPAILanguageModel = class {
         type: "unsupported"
       });
     }
+    let responseFormat;
     if (options.responseFormat?.type === "json") {
+      responseFormat = options.responseFormat.schema ? {
+        json_schema: {
+          description: options.responseFormat.description,
+          name: options.responseFormat.name ?? "response",
+          schema: options.responseFormat.schema,
+          strict: null
+        },
+        type: "json_schema"
+      } : { type: "json_object" };
+    } else if (this.settings.responseFormat) {
+      responseFormat = this.settings.responseFormat;
+    }
+    if (responseFormat && responseFormat.type !== "text") {
       warnings.push({
         message: "responseFormat JSON mode is forwarded to the underlying model; support and schema adherence depend on the model/deployment.",
         type: "other"
       });
     }
-    const responseFormat = options.responseFormat?.type === "json" ? options.responseFormat.schema ? {
-      json_schema: {
-        description: options.responseFormat.description,
-        name: options.responseFormat.name ?? "response",
-        schema: options.responseFormat.schema,
-        strict: null
-      },
-      type: "json_schema"
-    } : { type: "json_object" } : void 0;
     const orchestrationConfig = {
       promptTemplating: {
         model: {
@@ -31745,6 +31763,7 @@ function createSAPAIProvider(options = {}) {
   if (options.defaultSettings?.modelParams) {
     validateModelParamsSettings(options.defaultSettings.modelParams);
   }
+  const providerName = options.name ?? SAP_AI_PROVIDER_NAME;
   const resourceGroup = options.resourceGroup ?? "default";
   const warnOnAmbiguousConfig = options.warnOnAmbiguousConfig ?? true;
   if (warnOnAmbiguousConfig && options.deploymentId && options.resourceGroup) {
@@ -31769,14 +31788,14 @@ function createSAPAIProvider(options = {}) {
     return new SAPAILanguageModelV2(modelId, mergedSettings, {
       deploymentConfig,
       destination: options.destination,
-      provider: "sap-ai"
+      provider: `${providerName}.chat`
     });
   };
   const createEmbeddingModel = (modelId, settings = {}) => {
     return new SAPAIEmbeddingModelV2(modelId, settings, {
       deploymentConfig,
       destination: options.destination,
-      provider: "sap-ai"
+      provider: `${providerName}.embedding`
     });
   };
   const provider = function(modelId, settings) {
@@ -31785,10 +31804,17 @@ function createSAPAIProvider(options = {}) {
     }
     return createModel(modelId, settings);
   };
-  provider.languageModel = createModel;
   provider.chat = createModel;
+  provider.languageModel = createModel;
   provider.embedding = createEmbeddingModel;
   provider.textEmbeddingModel = createEmbeddingModel;
+  provider.imageModel = (modelId) => {
+    throw new NoSuchModelError2({
+      message: `SAP AI Core Orchestration Service does not support image generation. Model '${modelId}' is not available.`,
+      modelId,
+      modelType: "imageModel"
+    });
+  };
   return provider;
 }
 var sapai = createSAPAIProvider();
@@ -31824,6 +31850,7 @@ export {
   buildLlamaGuard38BFilter,
   buildTranslationConfig,
   createSAPAIProvider,
+  getProviderName,
   isConfigReference,
   sapAIEmbeddingProviderOptions,
   sapAILanguageModelProviderOptions,