@jerome-benoit/sap-ai-provider 4.0.0-rc.1 → 4.0.0-rc.2

package/dist/index.d.ts

@@ -1,9 +1,38 @@
-import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult, ProviderV3 } from '@ai-sdk/provider';
-import { HttpDestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity';
-import { ResourceGroupConfig, DeploymentIdConfig } from '@sap-ai-sdk/ai-api/internal.js';
-import { MaskingModule, FilteringModule, ChatCompletionTool, ChatModel } from '@sap-ai-sdk/orchestration';
+import { FilteringModule, GroundingModule, MaskingModule, ChatCompletionTool, TranslationModule, ChatModel } from '@sap-ai-sdk/orchestration';
 export { AssistantChatMessage, ChatCompletionRequest, ChatCompletionTool, ChatMessage, DeveloperChatMessage, DocumentTranslationApplyToSelector, FilteringModule, FunctionObject, GroundingModule, LlmModelDetails, LlmModelParams, MaskingModule, OrchestrationClient, OrchestrationConfigRef, OrchestrationErrorResponse, OrchestrationModuleConfig, OrchestrationResponse, OrchestrationStreamChunkResponse, OrchestrationStreamResponse, PromptTemplatingModule, SystemChatMessage, ToolChatMessage, TranslationApplyToCategory, TranslationInputParameters, TranslationModule, TranslationOutputParameters, TranslationTargetLanguage, UserChatMessage, buildAzureContentSafetyFilter, buildDocumentGroundingConfig, buildDpiMaskingProvider, buildLlamaGuard38BFilter, buildTranslationConfig, isConfigReference } from '@sap-ai-sdk/orchestration';
+import { DeploymentIdConfig, ResourceGroupConfig } from '@sap-ai-sdk/ai-api/internal.js';
+import { HttpDestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity';
+import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult, ProviderV3 } from '@ai-sdk/provider';
 
+/**
+ * Supported model IDs in SAP AI Core.
+ *
+ * These models are available through the SAP AI Core Orchestration service.
+ * **Note:** The models listed here are representative examples. Actual model availability
+ * depends on your SAP AI Core tenant configuration, region, and subscription.
+ *
+ * @see {@link https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/models-and-scenarios SAP AI Core Models Documentation}
+ *
+ * **Azure OpenAI Models:**
+ * - gpt-4o, gpt-4o-mini
+ * - gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
+ * - o1, o3, o3-mini, o4-mini
+ *
+ * **Google Vertex AI Models:**
+ * - gemini-2.0-flash, gemini-2.0-flash-lite
+ * - gemini-2.5-flash, gemini-2.5-pro
+ *
+ * **AWS Bedrock Models:**
+ * - anthropic--claude-3-haiku, anthropic--claude-3-sonnet, anthropic--claude-3-opus
+ * - anthropic--claude-3.5-sonnet, anthropic--claude-3.7-sonnet
+ * - anthropic--claude-4-sonnet, anthropic--claude-4-opus
+ * - amazon--nova-pro, amazon--nova-lite, amazon--nova-micro, amazon--nova-premier
+ *
+ * **AI Core Open Source Models:**
+ * - mistralai--mistral-large-instruct, mistralai--mistral-medium-instruct, mistralai--mistral-small-instruct
+ * - cohere--command-a-reasoning
+ */
+type SAPAIModelId = ChatModel;
 /**
  * Settings for configuring SAP AI Core model behavior.
  *
@@ -55,10 +84,61 @@ export { AssistantChatMessage, ChatCompletionRequest, ChatCompletionTool, ChatMe
  */
 interface SAPAISettings {
     /**
-     * Specific version of the model to use.
-     * If not provided, the latest version will be used.
+     * Filtering configuration for input and output content safety.
+     * Supports Azure Content Safety and Llama Guard filters.
+     *
+     * @see {@link https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/content-filtering SAP Content Filtering Documentation}
+     *
+     * @example
+     * ```typescript
+     * import { buildAzureContentSafetyFilter } from '@sap-ai-sdk/orchestration';
+     *
+     * const model = provider('gpt-4o', {
+     *   filtering: {
+     *     input: {
+     *       filters: [
+     *         buildAzureContentSafetyFilter('input', {
+     *           hate: 'ALLOW_SAFE',
+     *           violence: 'ALLOW_SAFE_LOW_MEDIUM'
+     *         })
+     *       ]
+     *     }
+     *   }
+     * });
+     * ```
      */
-    modelVersion?: string;
+    filtering?: FilteringModule;
+    /**
+     * Grounding module configuration for document-based retrieval (RAG).
+     * Enables retrieval-augmented generation using SAP Document Grounding Service.
+     *
+     * Use `buildDocumentGroundingConfig()` to create the configuration.
+     *
+     * @see {@link https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/document-grounding SAP Document Grounding Documentation}
+     *
+     * @example
+     * ```typescript
+     * import { buildDocumentGroundingConfig } from '@mymediset/sap-ai-provider';
+     *
+     * const model = provider('gpt-4o', {
+     *   grounding: buildDocumentGroundingConfig({
+     *     filters: [
+     *       {
+     *         id: 'my-vector-store',
+     *         data_repository_type: 'vector',
+     *         data_repositories: ['document-repo-1'],
+     *         chunk_overlap: 50
+     *       }
+     *     ],
+     *     placeholders: {
+     *       input: ['?question'],
+     *       output: 'groundingOutput'
+     *     }
+     *   })
+     * });
+     * ```
+     */
+    grounding?: GroundingModule;
     /**
      * Whether to include assistant reasoning parts in the SAP prompt conversion.
      *
@@ -94,27 +174,34 @@ interface SAPAISettings {
      * ```
      */
     includeReasoning?: boolean;
+    /**
+     * Masking configuration for SAP AI Core orchestration.
+     * When provided, sensitive information in prompts can be anonymized or
+     * pseudonymized by SAP Data Privacy Integration (DPI).
+     *
+     * @see {@link https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/data-privacy-integration SAP DPI Documentation}
+     *
+     * @example
+     * ```typescript
+     * import { buildDpiMaskingProvider } from '@sap-ai-sdk/orchestration';
+     *
+     * const model = provider('gpt-4o', {
+     *   masking: {
+     *     masking_providers: [
+     *       buildDpiMaskingProvider({
+     *         method: 'anonymization',
+     *         entities: ['profile-email', 'profile-phone']
+     *       })
+     *     ]
+     *   }
+     * });
+     * ```
+     */
+    masking?: MaskingModule;
     /**
      * Model generation parameters that control the output.
      */
     modelParams?: {
-        /**
-         * Maximum number of tokens to generate.
-         * Higher values allow for longer responses but increase latency and cost.
-         */
-        maxTokens?: 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;
-        /**
-         * 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;
         /**
          * Frequency penalty between -2.0 and 2.0.
          * Positive values penalize tokens based on their frequency.
@@ -122,11 +209,10 @@ interface SAPAISettings {
          */
         frequencyPenalty?: number;
         /**
-         * 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).
+         * Maximum number of tokens to generate.
+         * Higher values allow for longer responses but increase latency and cost.
          */
-        presencePenalty?: number;
+        maxTokens?: number;
         /**
          * Number of completions to generate.
          * Multiple completions provide alternative responses.
@@ -141,52 +227,30 @@ interface SAPAISettings {
          * Note: This uses the SAP/OpenAI-style key `parallel_tool_calls`.
          */
         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;
+        /**
+         * 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;
+        /**
+         * 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;
     };
     /**
-     * Masking configuration for SAP AI Core orchestration.
-     * When provided, sensitive information in prompts can be anonymized or
-     * pseudonymized by SAP Data Privacy Integration (DPI).
-     *
-     * @example
-     * ```typescript
-     * import { buildDpiMaskingProvider } from '@sap-ai-sdk/orchestration';
-     *
-     * const model = provider('gpt-4o', {
-     *   masking: {
-     *     masking_providers: [
-     *       buildDpiMaskingProvider({
-     *         method: 'anonymization',
-     *         entities: ['profile-email', 'profile-phone']
-     *       })
-     *     ]
-     *   }
-     * });
-     * ```
-     */
-    masking?: MaskingModule;
-    /**
-     * Filtering configuration for input and output content safety.
-     * Supports Azure Content Safety and Llama Guard filters.
-     *
-     * @example
-     * ```typescript
-     * import { buildAzureContentSafetyFilter } from '@sap-ai-sdk/orchestration';
-     *
-     * const model = provider('gpt-4o', {
-     *   filtering: {
-     *     input: {
-     *       filters: [
-     *         buildAzureContentSafetyFilter('input', {
-     *           hate: 'ALLOW_SAFE',
-     *           violence: 'ALLOW_SAFE_LOW_MEDIUM'
-     *         })
-     *       ]
-     *     }
-     *   }
-     * });
-     * ```
+     * Specific version of the model to use.
+     * If not provided, the latest version will be used.
      */
-    filtering?: FilteringModule;
+    modelVersion?: string;
     /**
      * Response format for templating prompt (OpenAI-compatible)
      * Allows specifying structured output formats
@@ -206,17 +270,17 @@ interface SAPAISettings {
      * ```
      */
     responseFormat?: {
-        type: "text";
-    } | {
-        type: "json_object";
-    } | {
-        type: "json_schema";
         json_schema: {
-            name: string;
             description?: string;
+            name: string;
             schema?: unknown;
             strict?: boolean | null;
         };
+        type: "json_schema";
+    } | {
+        type: "json_object";
+    } | {
+        type: "text";
     };
     /**
      * Tool definitions in SAP AI SDK format
@@ -251,43 +315,42 @@ interface SAPAISettings {
      * ```
      */
     tools?: ChatCompletionTool[];
+    /**
+     * Translation module configuration for input/output translation.
+     * Enables automatic translation using SAP Document Translation service.
+     *
+     * Use `buildTranslationConfig()` to create input/output configurations.
+     *
+     * @see {@link https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/translation SAP Translation Documentation}
+     *
+     * @example
+     * ```typescript
+     * import { buildTranslationConfig } from '@mymediset/sap-ai-provider';
+     *
+     * const model = provider('gpt-4o', {
+     *   translation: {
+     *     input: buildTranslationConfig('input', {
+     *       sourceLanguage: 'de-DE',
+     *       targetLanguage: 'en-US'
+     *     }),
+     *     output: buildTranslationConfig('output', {
+     *       targetLanguage: 'de-DE'
+     *     })
+     *   }
+     * });
+     * ```
+     */
+    translation?: TranslationModule;
 }
-/**
- * Supported model IDs in SAP AI Core.
- *
- * These models are available through the SAP AI Core Orchestration service.
- * **Note:** The models listed here are representative examples. Actual model availability
- * depends on your SAP AI Core tenant configuration, region, and subscription.
- *
- * **Azure OpenAI Models:**
- * - gpt-4o, gpt-4o-mini
- * - gpt-4.1, gpt-4.1-mini, gpt-4.1-nano
- * - o1, o3, o3-mini, o4-mini
- *
- * **Google Vertex AI Models:**
- * - gemini-2.0-flash, gemini-2.0-flash-lite
- * - gemini-2.5-flash, gemini-2.5-pro
- *
- * **AWS Bedrock Models:**
- * - anthropic--claude-3-haiku, anthropic--claude-3-sonnet, anthropic--claude-3-opus
- * - anthropic--claude-3.5-sonnet, anthropic--claude-3.7-sonnet
- * - anthropic--claude-4-sonnet, anthropic--claude-4-opus
- * - amazon--nova-pro, amazon--nova-lite, amazon--nova-micro, amazon--nova-premier
- *
- * **AI Core Open Source Models:**
- * - mistralai--mistral-large-instruct, mistralai--mistral-medium-instruct, mistralai--mistral-small-instruct
- * - cohere--command-a-reasoning
- */
-type SAPAIModelId = ChatModel;
 
 /**
  * Internal configuration for the SAP AI Chat Language Model.
  * @internal
  */
 interface SAPAIConfig {
-    provider: string;
-    deploymentConfig: ResourceGroupConfig | DeploymentIdConfig;
+    deploymentConfig: DeploymentIdConfig | ResourceGroupConfig;
     destination?: HttpDestinationOrFetchOptions;
+    provider: string;
 }
 /**
  * SAP AI Chat Language Model implementation.
@@ -309,6 +372,9 @@ interface SAPAIConfig {
  * - AWS Bedrock models (anthropic--claude-*, amazon--nova-*, etc.)
  * - AI Core open source models (mistralai--, cohere--, etc.)
  *
+ * @see {@link https://sdk.vercel.ai/docs/ai-sdk-core/language-model-v3 Vercel AI SDK LanguageModelV3}
+ * @see {@link https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/orchestration SAP AI Core Orchestration}
+ *
  * @example
  * ```typescript
  * // Create via provider
@@ -324,35 +390,27 @@ interface SAPAIConfig {
  *
  * @implements {LanguageModelV3}
  */
-declare class SAPAIChatLanguageModel implements LanguageModelV3 {
-    readonly specificationVersion = "v3";
+declare class SAPAILanguageModel implements LanguageModelV3 {
     readonly modelId: SAPAIModelId;
-    private readonly config;
-    private readonly settings;
-    /**
-     * Creates a new SAP AI Chat Language Model instance.
-     *
-     * @param modelId - The model identifier
-     * @param settings - Model-specific configuration settings
-     * @param config - Internal configuration (deployment config, destination, etc.)
-     *
-     * @internal This constructor is not meant to be called directly.
-     * Use the provider function instead.
-     */
-    constructor(modelId: SAPAIModelId, settings: SAPAISettings, config: SAPAIConfig);
-    /**
-     * Checks if a URL is supported for file/image uploads.
-     *
-     * @param url - The URL to check
-     * @returns True if the URL protocol is HTTPS or data with valid image format
-     */
-    supportsUrl(url: URL): boolean;
+    readonly specificationVersion = "v3";
     /**
-     * Returns supported URL patterns for different content types.
+     * Model capabilities.
      *
-     * @returns Record of content types to regex patterns
+     * These defaults assume “modern” model behavior to avoid maintaining a
+     * per-model capability matrix. If a deployment doesn't support a feature,
+     * SAP AI Core will fail the request at runtime.
      */
-    get supportedUrls(): Record<string, RegExp[]>;
+    readonly supportsImageUrls: boolean;
+    /** Multiple completions via the `n` parameter (provider-specific support). */
+    readonly supportsMultipleCompletions: boolean;
+    /** Parallel tool calls. */
+    readonly supportsParallelToolCalls: boolean;
+    /** Streaming responses. */
+    readonly supportsStreaming: boolean;
+    /** Structured JSON outputs (json_schema response format). */
+    readonly supportsStructuredOutputs: boolean;
+    /** Tool/function calling. */
+    readonly supportsToolCalls: boolean;
     /**
      * Generates text completion using SAP AI Core's Orchestration API.
      *
@@ -396,39 +454,24 @@ declare class SAPAIChatLanguageModel implements LanguageModelV3 {
      */
     get provider(): string;
     /**
-     * Model capabilities.
+     * Returns supported URL patterns for different content types.
      *
-     * These defaults assume “modern” model behavior to avoid maintaining a
-     * per-model capability matrix. If a deployment doesn't support a feature,
-     * SAP AI Core will fail the request at runtime.
+     * @returns Record of content types to regex patterns
      */
-    readonly supportsImageUrls: boolean;
-    /** Structured JSON outputs (json_schema response format). */
-    readonly supportsStructuredOutputs: boolean;
-    /** Tool/function calling. */
-    readonly supportsToolCalls: boolean;
-    /** Streaming responses. */
-    readonly supportsStreaming: boolean;
-    /** Multiple completions via the `n` parameter (provider-specific support). */
-    readonly supportsMultipleCompletions: boolean;
-    /** Parallel tool calls. */
-    readonly supportsParallelToolCalls: boolean;
+    get supportedUrls(): Record<string, RegExp[]>;
+    private readonly config;
+    private readonly settings;
     /**
-     * Builds orchestration module config for SAP AI SDK.
+     * Creates a new SAP AI Chat Language Model instance.
      *
-     * @param options - Call options from the AI SDK
-     * @returns Object containing orchestration config, messages, and warnings
-     * @internal
-     */
-    private buildOrchestrationConfig;
-    /**
-     * Creates an OrchestrationClient instance.
+     * @param modelId - The model identifier
+     * @param settings - Model-specific configuration settings
+     * @param config - Internal configuration (deployment config, destination, etc.)
      *
-     * @param config - Orchestration module configuration
-     * @returns OrchestrationClient instance
-     * @internal
+     * @internal This constructor is not meant to be called directly.
+     * Use the provider function instead.
      */
-    private createClient;
+    constructor(modelId: SAPAIModelId, settings: SAPAISettings, config: SAPAIConfig);
     /**
      * Generates a single completion (non-streaming).
      *
@@ -489,6 +532,8 @@ declare class SAPAIChatLanguageModel implements LanguageModelV3 {
      * - Usage format: `{ inputTokens: { total, ... }, outputTokens: { total, ... } }`
      * - Warnings only in `stream-start` event
      *
+     * @see {@link https://sdk.vercel.ai/docs/ai-sdk-core/streaming Vercel AI SDK Streaming}
+     *
      * @param options - Streaming options including prompt, tools, and settings
      * @returns Promise resolving to stream and request metadata
      *
@@ -513,8 +558,35 @@ declare class SAPAIChatLanguageModel implements LanguageModelV3 {
      * @since 4.0.0
      */
     doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
+    /**
+     * Checks if a URL is supported for file/image uploads.
+     *
+     * @param url - The URL to check
+     * @returns True if the URL protocol is HTTPS or data with valid image format
+     */
+    supportsUrl(url: URL): boolean;
+    /**
+     * Builds orchestration module config for SAP AI SDK.
+     *
+     * @param options - Call options from the AI SDK
+     * @returns Object containing orchestration config, messages, and warnings
+     * @internal
+     */
+    private buildOrchestrationConfig;
+    /**
+     * Creates an OrchestrationClient instance.
+     *
+     * @param config - Orchestration module configuration
+     * @returns OrchestrationClient instance
+     * @internal
+     */
+    private createClient;
 }
 
+/**
+ * Deployment configuration type used by SAP AI SDK.
+ */
+type DeploymentConfig = DeploymentIdConfig | ResourceGroupConfig;
 /**
  * SAP AI Provider interface.
  *
@@ -547,7 +619,7 @@ interface SAPAIProvider extends ProviderV3 {
      * @param settings - Optional model configuration settings
      * @returns Configured SAP AI chat language model instance
      */
-    (modelId: SAPAIModelId, settings?: SAPAISettings): SAPAIChatLanguageModel;
+    (modelId: SAPAIModelId, settings?: SAPAISettings): SAPAILanguageModel;
     /**
      * Explicit method for creating chat models.
      *
@@ -558,7 +630,7 @@ interface SAPAIProvider extends ProviderV3 {
      * @param settings - Optional model configuration settings
      * @returns Configured SAP AI chat language model instance
      */
-    chat(modelId: SAPAIModelId, settings?: SAPAISettings): SAPAIChatLanguageModel;
+    chat(modelId: SAPAIModelId, settings?: SAPAISettings): SAPAILanguageModel;
 }
 /**
  * Configuration settings for the SAP AI Provider.
@@ -587,28 +659,10 @@ interface SAPAIProvider extends ProviderV3 {
  */
 interface SAPAIProviderSettings {
     /**
-     * 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;
-    /**
-     * SAP AI Core resource group.
-     *
-     * Logical grouping of AI resources in SAP AI Core.
-     * Used for resource isolation and access control.
-     * Different resource groups can have different permissions and quotas.
-     *
-     * @default 'default'
-     * @example
-     * ```typescript
-     * resourceGroup: 'default'     // Default resource group
-     * resourceGroup: 'production'  // Production environment
-     * resourceGroup: 'development' // Development environment
-     * ```
+     * Default model settings applied to every model instance created by this provider.
+     * Per-call settings provided to the model will override these.
      */
-    resourceGroup?: string;
+    defaultSettings?: SAPAISettings;
     /**
      * SAP AI Core deployment ID.
      *
@@ -638,15 +692,29 @@ interface SAPAIProviderSettings {
      */
     destination?: HttpDestinationOrFetchOptions;
     /**
-     * Default model settings applied to every model instance created by this provider.
-     * Per-call settings provided to the model will override these.
+     * SAP AI Core resource group.
+     *
+     * Logical grouping of AI resources in SAP AI Core.
+     * Used for resource isolation and access control.
+     * Different resource groups can have different permissions and quotas.
+     *
+     * @default 'default'
+     * @example
+     * ```typescript
+     * resourceGroup: 'default'     // Default resource group
+     * resourceGroup: 'production'  // Production environment
+     * resourceGroup: 'development' // Development environment
+     * ```
      */
-    defaultSettings?: SAPAISettings;
+    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;
 }
-/**
- * Deployment configuration type used by SAP AI SDK.
- */
-type DeploymentConfig = ResourceGroupConfig | DeploymentIdConfig;
 /**
  * Creates a SAP AI Core provider instance for use with the AI SDK.
  *