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

package/dist/index.d.cts

@@ -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 };