@jerome-benoit/sap-ai-provider-v2 5.0.0 → 5.0.2

package/dist/index.d.cts

@@ -6,7 +6,7 @@ export { HttpDestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity';
 import { AzureOpenAiChatCompletionParameters } from '@sap-ai-sdk/foundation-models';
 import { OrchestrationConfigRefOverride, OrchestrationModuleConfig, FilteringModule, GroundingModule, MaskingModule, OrchestrationConfigRefById, OrchestrationConfigRefByName, ChatCompletionTool, TranslationModule, ChatModel } from '@sap-ai-sdk/orchestration';
 export { AssistantChatMessage, ChatCompletionRequest, ChatCompletionTool, ChatMessage, ChatMessageContent, ChatMessages, Citation, DeveloperChatMessage, DocumentTranslationApplyToSelector, FileContent, FilteringModule, FunctionObject, GroundingModule, ImageContentUrl, LlmModelDetails, LlmModelParams, MaskingModule, OrchestrationClient, OrchestrationConfigRef, OrchestrationConfigRefById, OrchestrationConfigRefByName, OrchestrationConfigRefOverride, OrchestrationEmbeddingClient, OrchestrationEmbeddingResponse, OrchestrationError, OrchestrationErrorResponse, OrchestrationModuleConfig, OrchestrationModuleConfigList, OrchestrationResponse, OrchestrationStream, OrchestrationStreamChunkResponse, OrchestrationStreamResponse, PromptTemplatingModule, SystemChatMessage, ToolChatMessage, TranslationApplyToCategory, TranslationInputParameters, TranslationModule, TranslationOutputParameters, TranslationTargetLanguage, UserChatMessage, UserChatMessageContent, UserChatMessageContentItem, buildAzureContentSafetyFilter, buildDocumentGroundingConfig, buildDpiMaskingProvider, buildLlamaGuard38BFilter, buildTranslationConfig } from '@sap-ai-sdk/orchestration';
-import { SharedV3Warning, LanguageModelV3StreamPart, LanguageModelV2 as LanguageModelV2$1, LanguageModelV2CallOptions as LanguageModelV2CallOptions$1, LanguageModelV3CallOptions } from '@ai-sdk/provider';
+import { LanguageModelV2 as LanguageModelV2$1, LanguageModelV2CallOptions as LanguageModelV2CallOptions$1, LanguageModelV3CallOptions } from '@ai-sdk/provider';
 import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
 import { InferSchema } from '@ai-sdk/provider-utils';
 
@@ -15,7 +15,7 @@ declare const SAP_AI_PROVIDER_NAME: "sap-ai";
 /**
  * Extracts the provider name from a provider identifier (e.g., "sap-ai.chat" → "sap-ai").
  * @param providerIdentifier - The full provider identifier string.
- * @returns The provider name without any suffix.
+ * @returns The prefix before the first dot, or the unchanged identifier when no dot exists.
  */
 declare function getProviderName(providerIdentifier: string): string;
 /** @internal */
@@ -1682,8 +1682,8 @@ type AzureOpenAiChatExtensionConfiguration = NonNullable<AzureOpenAiChatCompleti
 /**
  * Common model parameters shared between both APIs.
  *
- * These parameters control text generation behavior and are validated by Zod schemas
- * when passed via `providerOptions`.
+ * Known parameters are validated by Zod in constructor settings and per-call
+ * `modelParams` provider options; additional model-specific keys are passed through.
  */
 interface CommonModelParams {
     /**
@@ -1698,7 +1698,7 @@ interface CommonModelParams {
     readonly maxTokens?: number;
     /**
      * Number of completions to generate.
-     * Not supported by Amazon/Anthropic models.
+     * Availability depends on the selected SAP API and model; no model-family filtering is applied.
      * Range: Positive integer
      */
     readonly n?: number;
@@ -1749,7 +1749,10 @@ interface FoundationModelsModelSettings {
     readonly api: "foundation-models";
     /** Azure OpenAI "On Your Data" configuration for RAG scenarios. */
     readonly dataSources?: AzureOpenAiChatExtensionConfiguration[];
-    /** @default false */
+    /**
+     * Forward assistant reasoning from the input history as text; does not enable reasoning output.
+     * @default false
+     */
     readonly includeReasoning?: boolean;
     readonly modelParams?: FoundationModelsModelParams;
     readonly modelVersion?: string;
@@ -1769,7 +1772,7 @@ interface OrchestrationModelSettings {
     readonly escapeTemplatePlaceholders?: boolean;
     /**
      * Additional module configurations for prompt module fallback.
-     * The SDK tries the primary configuration first, then each fallback in order until one succeeds.
+     * These entries follow the primary configuration in the list passed to the SAP SDK.
      * Each entry is a full `OrchestrationModuleConfig` with its own model, prompt, and modules.
      * @example
      * ```ts
@@ -1786,7 +1789,10 @@ interface OrchestrationModelSettings {
     readonly fallbackModuleConfigs?: OrchestrationModuleConfig[];
     readonly filtering?: FilteringModule;
     readonly grounding?: GroundingModule;
-    /** @default false */
+    /**
+     * Forward assistant reasoning from the input history as text; does not enable reasoning output.
+     * @default false
+     */
     readonly includeReasoning?: boolean;
     readonly masking?: MaskingModule | {
         providers: MaskingModule["masking_providers"];
@@ -1797,7 +1803,8 @@ interface OrchestrationModelSettings {
      * Reference to a complete orchestration configuration stored in SAP AI Core Prompt Registry.
      * When provided, local module settings (filtering, masking, grounding, translation, tools,
      * promptTemplateRef, responseFormat) are ignored as the full configuration is managed
-     * by the referenced config. Only `placeholderValues` and messages are passed through.
+     * by the referenced config. The reference, including its explicit `overrideConfig`,
+     * is passed to the SAP SDK; messages and `placeholderValues` remain request inputs.
      * @example { id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" }
      * @example { scenario: "customer-support", name: "prod-config", version: "1.0.0" }
      */
@@ -1806,8 +1813,8 @@ interface OrchestrationModelSettings {
     readonly promptTemplateRef?: PromptTemplateRef;
     readonly responseFormat?: ResponseFormat;
     /**
-     * Options for streaming behavior with post-LLM modules.
-     * Only applies when using `streamText()` with orchestration modules.
+     * Options for streaming behavior with locally configured post-LLM modules.
+     * Includes direct `doStream()` calls; ignored when `orchestrationConfigRef` is used.
      */
     readonly streamOptions?: OrchestrationStreamOptions;
     readonly tools?: ChatCompletionTool[];
@@ -1816,6 +1823,8 @@ interface OrchestrationModelSettings {
 /**
  * Stream options for orchestration post-LLM module processing.
  * Controls chunking behavior for translation, filtering, and other modules during streaming.
+ * Ignored with `orchestrationConfigRef`; configure streaming in the stored
+ * configuration or its `overrideConfig` instead.
  */
 interface OrchestrationStreamOptions {
     /**
@@ -1825,7 +1834,7 @@ interface OrchestrationStreamOptions {
     readonly chunkSize?: number;
     /**
      * Delimiters for splitting stream into chunks (e.g., sentence boundaries).
-     * Required when translation module is configured.
+     * Recommended for translation; the provider warns when local translation settings lack them.
      * @example ["\n", ".", "?", "!"]
      */
     readonly delimiters?: readonly string[];
@@ -1869,12 +1878,18 @@ interface SAPAIEmbeddingSettings {
     readonly masking?: MaskingModule | {
         providers: MaskingModule["masking_providers"];
     };
-    /** @default 2048 */
+    /**
+     * Maximum batch size: a positive integer, or `Infinity` for no provider-side limit.
+     * @default 2048
+     */
     readonly maxEmbeddingsPerCall?: number;
     readonly modelParams?: FoundationModelsEmbeddingParams | Record<string, unknown>;
     readonly modelVersion?: string;
     readonly [key: string]: unknown;
-    /** @default 'text' */
+    /**
+     * Orchestration embedding input type; ignored by Foundation Models.
+     * @default 'text'
+     */
     readonly type?: "document" | "query" | "text";
 }
 /**
@@ -1908,7 +1923,10 @@ interface SAPAISettings {
     readonly filtering?: FilteringModule;
     /** Orchestration API only. */
     readonly grounding?: GroundingModule;
-    /** @default false */
+    /**
+     * Forward assistant reasoning from the input history as text; does not enable reasoning output.
+     * @default false
+     */
     readonly includeReasoning?: boolean;
     /** Orchestration API only. */
     readonly masking?: MaskingModule | {
@@ -1923,7 +1941,7 @@ interface SAPAISettings {
     /** Orchestration API only. */
     readonly promptTemplateRef?: PromptTemplateRef;
     readonly responseFormat?: ResponseFormat;
-    /** Orchestration API only. */
+    /** Orchestration API only; ignored when `orchestrationConfigRef` is used. */
     readonly streamOptions?: OrchestrationStreamOptions;
     /** Orchestration API only. */
     readonly tools?: ChatCompletionTool[];
@@ -2068,7 +2086,7 @@ declare class ApiSwitchError extends Error {
  * @example
  * ```typescript
  * throw new UnsupportedFeatureError("Content filtering", "foundation-models", "orchestration");
- * // "Content filtering is only available with Orchestration API and will be ignored by Foundation Models API."
+ * // Rejects the request: content filtering requires the Orchestration API.
  * ```
  * @see {@link validateSettings} - Main validation function that throws this error
  * @see {@link ApiSwitchError} - Related error for API switching conflicts
@@ -2080,45 +2098,25 @@ declare class UnsupportedFeatureError extends Error {
     /**
      * Creates a new UnsupportedFeatureError.
      * @param feature - The name of the unsupported feature (e.g., "Content filtering").
-     * @param api - The API being used where the feature will be ignored.
+     * @param api - The API being used that does not support the feature.
      * @param suggestedApi - The API that supports this feature.
      */
     constructor(feature: string, api: SAPAIApiType, suggestedApi: SAPAIApiType);
 }
 
-/** Adapters to convert internal (V3) formats to LanguageModelV2 formats for the V2 facade. */
+/** Adapters for the semantic differences between the V3 core and V2 facade. */
 
+/** Stream events supported by the V2 facade. */
 type ConvertedV2StreamPart = Exclude<LanguageModelV2StreamPart, {
     type: "stream-start";
 }> | {
     type: "stream-start";
-    warnings: ReturnType<typeof convertWarningsToV2>;
+    warnings: ConvertedV2Warning[];
 };
-/**
- * Converts internal warnings array to V2 warnings array.
- * @param internalWarnings - Internal warning objects.
- * @returns V2 warning objects.
- * @internal
- */
-declare function convertWarningsToV2(internalWarnings: SharedV3Warning[]): ReturnType<typeof convertWarningToV2>[];
-/**
- * Converts internal warning to V2 warning format.
- *
- * Maps `unsupported`/`compatibility` warnings to V2 `other` type with descriptive message.
- * @param internalWarning - Internal warning object.
- * @returns V2 warning object.
- * @internal
- */
-declare function convertWarningToV2(internalWarning: SharedV3Warning): Extract<LanguageModelV2CallWarning, {
+/** V2 warning representation used when adapting V3 feature diagnostics. */
+type ConvertedV2Warning = Extract<LanguageModelV2CallWarning, {
     type: "other";
 }>;
-/**
- * Transforms internal stream to V2 ReadableStream.
- * @param internalStream - Internal ReadableStream to transform.
- * @returns V2-formatted ReadableStream.
- * @internal
- */
-declare function createV2StreamFromInternal(internalStream: ReadableStream<LanguageModelV3StreamPart>): ReadableStream<ConvertedV2StreamPart>;
 
 /**
  * SAP AI Language Model V2 - Vercel AI SDK LanguageModelV2 implementation for SAP AI Core.
@@ -2202,7 +2200,7 @@ declare class SAPAILanguageModelV2 implements LanguageModelV2$1 {
             headers?: SharedV2Headers;
         };
         usage: LanguageModelV2Usage;
-        warnings: ReturnType<typeof convertWarningsToV2>;
+        warnings: ConvertedV2Warning[];
     }>;
     doStream(options: CompatibleV2CallOptions): Promise<{
         request?: {
@@ -2211,7 +2209,7 @@ declare class SAPAILanguageModelV2 implements LanguageModelV2$1 {
         response?: {
             headers?: SharedV2Headers;
         };
-        stream: ReturnType<typeof createV2StreamFromInternal>;
+        stream: ReadableStream<ConvertedV2StreamPart>;
     }>;
 }
 
@@ -2223,14 +2221,15 @@ type DeploymentConfig = DeploymentIdConfig | ResourceGroupConfig;
  */
 interface SAPAIProviderSettings {
     /**
-     * SAP AI Core API to use for all models created by this provider.
-     * Can be overridden at model creation time or per-call via providerOptions.
+     * Default SAP AI Core API for models created by this provider.
+     * `defaultSettings.api`, per-model `api`, and per-call `providerOptions` take precedence.
+     * This option does not enable automatic failover between APIs.
      * - `'orchestration'` (default): SAP AI Core Orchestration API - supports filtering, grounding, masking, translation
      * - `'foundation-models'`: SAP AI Core Foundation Models API - supports dataSources, logprobs, seed, etc.
      * @default 'orchestration'
      */
     readonly api?: SAPAIApiType;
-    /** Default model settings applied to every model instance. Per-call settings override these. */
+    /** Default model settings; settings supplied at model creation override these. */
     readonly defaultSettings?: SAPAISettings;
     /** SAP AI Core deployment ID. If not provided, the SDK resolves deployment automatically. */
     readonly deploymentId?: string;
@@ -2238,13 +2237,16 @@ interface SAPAIProviderSettings {
     readonly destination?: HttpDestinationOrFetchOptions;
     /**
      * Log level for SAP Cloud SDK loggers.
-     * Controls verbosity of internal SAP SDK logging (e.g., authentication, service binding).
+     * Controls process-wide SAP SDK logging (e.g., authentication, service binding).
+     * Creating another provider resets this level, using warn when logLevel is omitted.
      * Note: SAP_CLOUD_SDK_LOG_LEVEL environment variable takes precedence if set.
      * @default 'warn'
      */
     readonly logLevel?: "debug" | "error" | "info" | "warn";
     /**
-     * Provider name used as key for `providerOptions` and `providerMetadata`.
+     * Name used in model provider identifiers. Call-level `providerOptions` and
+     * `providerMetadata` keys use the prefix before the first dot; avoid dots in names.
+     * Per-part prompt-cache directives always use the fixed `sap-ai` key.
      * @default 'sap-ai'
      */
     readonly name?: string;
@@ -2254,8 +2256,10 @@ interface SAPAIProviderSettings {
      *
      * Provider-level only (not overridable per-call via `providerOptions['sap-ai']`). The
      * AI SDK `abortSignal` option always wins over any `signal` on `requestConfig`; the
-     * latter is dropped before the request is forwarded. Node-only knobs (`httpAgent`,
-     * `httpsAgent`) are silently ignored on Edge / Cloudflare Workers runtimes.
+     * latter is dropped before the request is forwarded. Standard AI SDK call-level
+     * `headers` override matching `requestConfig.headers` case-insensitively. Other
+     * options, including Node-only agents (`httpAgent`, `httpsAgent`), are forwarded
+     * unchanged. The published package and SAP SDK transport require a Node-compatible runtime.
      *
      * See the "Note on `requestConfig`" section under `SAPAIProviderSettings` in
      * `API_REFERENCE.md` for the full SAP AI Core `AI-*` header guidance.
@@ -2271,6 +2275,7 @@ interface SAPAIProviderSettings {
     /** Whether to emit warnings for ambiguous configurations (e.g. both deploymentId and resourceGroup). */
     readonly warnOnAmbiguousConfig?: boolean;
 }
+
 /** SAP AI Provider interface extending Vercel AI SDK ProviderV2. */
 interface SAPAIProviderV2 extends ProviderV2 {
     (modelId: SAPAIModelId, settings?: SAPAISettings): SAPAILanguageModelV2;
@@ -2290,12 +2295,12 @@ interface SAPAIProviderV2 extends ProviderV2 {
  * @param options - Provider configuration options.
  * @param options.api - Default API type: `'orchestration'` (default) or `'foundation-models'`.
  * @param options.defaultSettings - Default model settings applied to every model instance.
- * @param options.deploymentId - SAP AI Core deployment ID for automatic deployment resolution.
+ * @param options.deploymentId - Explicit SAP AI Core deployment ID; omit for automatic deployment resolution.
  * @param options.destination - Custom SAP Cloud SDK destination configuration.
  * @param options.logLevel - Log level for SAP Cloud SDK loggers (`'debug'`, `'info'`, `'warn'`, `'error'`).
- * @param options.name - Provider name used as key in `providerOptions` (default: `'sap-ai'`).
+ * @param options.name - Provider name (default: `'sap-ai'`); see {@link SAPAIProviderSettings.name} for namespace rules.
  * @param options.requestConfig - Provider-level custom request configuration. See {@link SAPAIProviderSettings.requestConfig} for scope, portability, and abort semantics.
- * @param options.resourceGroup - SAP AI Core resource group (default: `'default'`).
+ * @param options.resourceGroup - SAP AI Core resource group (default: `'default'`); ignored when deploymentId is set.
  * @param options.warnOnAmbiguousConfig - Whether to warn when both deploymentId and resourceGroup are set.
  * @returns A configured SAP AI provider instance that can be used as a callable or via methods.
  * @example

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { HttpDestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity';
 import { AzureOpenAiChatCompletionParameters } from '@sap-ai-sdk/foundation-models';
 import { OrchestrationConfigRefOverride, OrchestrationModuleConfig, FilteringModule, GroundingModule, MaskingModule, OrchestrationConfigRefById, OrchestrationConfigRefByName, ChatCompletionTool, TranslationModule, ChatModel } from '@sap-ai-sdk/orchestration';
 export { AssistantChatMessage, ChatCompletionRequest, ChatCompletionTool, ChatMessage, ChatMessageContent, ChatMessages, Citation, DeveloperChatMessage, DocumentTranslationApplyToSelector, FileContent, FilteringModule, FunctionObject, GroundingModule, ImageContentUrl, LlmModelDetails, LlmModelParams, MaskingModule, OrchestrationClient, OrchestrationConfigRef, OrchestrationConfigRefById, OrchestrationConfigRefByName, OrchestrationConfigRefOverride, OrchestrationEmbeddingClient, OrchestrationEmbeddingResponse, OrchestrationError, OrchestrationErrorResponse, OrchestrationModuleConfig, OrchestrationModuleConfigList, OrchestrationResponse, OrchestrationStream, OrchestrationStreamChunkResponse, OrchestrationStreamResponse, PromptTemplatingModule, SystemChatMessage, ToolChatMessage, TranslationApplyToCategory, TranslationInputParameters, TranslationModule, TranslationOutputParameters, TranslationTargetLanguage, UserChatMessage, UserChatMessageContent, UserChatMessageContentItem, buildAzureContentSafetyFilter, buildDocumentGroundingConfig, buildDpiMaskingProvider, buildLlamaGuard38BFilter, buildTranslationConfig } from '@sap-ai-sdk/orchestration';
-import { SharedV3Warning, LanguageModelV3StreamPart, LanguageModelV2 as LanguageModelV2$1, LanguageModelV2CallOptions as LanguageModelV2CallOptions$1, LanguageModelV3CallOptions } from '@ai-sdk/provider';
+import { LanguageModelV2 as LanguageModelV2$1, LanguageModelV2CallOptions as LanguageModelV2CallOptions$1, LanguageModelV3CallOptions } from '@ai-sdk/provider';
 import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
 import { InferSchema } from '@ai-sdk/provider-utils';
 
@@ -15,7 +15,7 @@ declare const SAP_AI_PROVIDER_NAME: "sap-ai";
 /**
  * Extracts the provider name from a provider identifier (e.g., "sap-ai.chat" → "sap-ai").
  * @param providerIdentifier - The full provider identifier string.
- * @returns The provider name without any suffix.
+ * @returns The prefix before the first dot, or the unchanged identifier when no dot exists.
  */
 declare function getProviderName(providerIdentifier: string): string;
 /** @internal */
@@ -1682,8 +1682,8 @@ type AzureOpenAiChatExtensionConfiguration = NonNullable<AzureOpenAiChatCompleti
 /**
  * Common model parameters shared between both APIs.
  *
- * These parameters control text generation behavior and are validated by Zod schemas
- * when passed via `providerOptions`.
+ * Known parameters are validated by Zod in constructor settings and per-call
+ * `modelParams` provider options; additional model-specific keys are passed through.
  */
 interface CommonModelParams {
     /**
@@ -1698,7 +1698,7 @@ interface CommonModelParams {
     readonly maxTokens?: number;
     /**
      * Number of completions to generate.
-     * Not supported by Amazon/Anthropic models.
+     * Availability depends on the selected SAP API and model; no model-family filtering is applied.
      * Range: Positive integer
      */
     readonly n?: number;
@@ -1749,7 +1749,10 @@ interface FoundationModelsModelSettings {
     readonly api: "foundation-models";
     /** Azure OpenAI "On Your Data" configuration for RAG scenarios. */
     readonly dataSources?: AzureOpenAiChatExtensionConfiguration[];
-    /** @default false */
+    /**
+     * Forward assistant reasoning from the input history as text; does not enable reasoning output.
+     * @default false
+     */
     readonly includeReasoning?: boolean;
     readonly modelParams?: FoundationModelsModelParams;
     readonly modelVersion?: string;
@@ -1769,7 +1772,7 @@ interface OrchestrationModelSettings {
     readonly escapeTemplatePlaceholders?: boolean;
     /**
      * Additional module configurations for prompt module fallback.
-     * The SDK tries the primary configuration first, then each fallback in order until one succeeds.
+     * These entries follow the primary configuration in the list passed to the SAP SDK.
      * Each entry is a full `OrchestrationModuleConfig` with its own model, prompt, and modules.
      * @example
      * ```ts
@@ -1786,7 +1789,10 @@ interface OrchestrationModelSettings {
     readonly fallbackModuleConfigs?: OrchestrationModuleConfig[];
     readonly filtering?: FilteringModule;
     readonly grounding?: GroundingModule;
-    /** @default false */
+    /**
+     * Forward assistant reasoning from the input history as text; does not enable reasoning output.
+     * @default false
+     */
     readonly includeReasoning?: boolean;
     readonly masking?: MaskingModule | {
         providers: MaskingModule["masking_providers"];
@@ -1797,7 +1803,8 @@ interface OrchestrationModelSettings {
      * Reference to a complete orchestration configuration stored in SAP AI Core Prompt Registry.
      * When provided, local module settings (filtering, masking, grounding, translation, tools,
      * promptTemplateRef, responseFormat) are ignored as the full configuration is managed
-     * by the referenced config. Only `placeholderValues` and messages are passed through.
+     * by the referenced config. The reference, including its explicit `overrideConfig`,
+     * is passed to the SAP SDK; messages and `placeholderValues` remain request inputs.
      * @example { id: "f47ac10b-58cc-4372-a567-0e02b2c3d479" }
      * @example { scenario: "customer-support", name: "prod-config", version: "1.0.0" }
      */
@@ -1806,8 +1813,8 @@ interface OrchestrationModelSettings {
     readonly promptTemplateRef?: PromptTemplateRef;
     readonly responseFormat?: ResponseFormat;
     /**
-     * Options for streaming behavior with post-LLM modules.
-     * Only applies when using `streamText()` with orchestration modules.
+     * Options for streaming behavior with locally configured post-LLM modules.
+     * Includes direct `doStream()` calls; ignored when `orchestrationConfigRef` is used.
      */
     readonly streamOptions?: OrchestrationStreamOptions;
     readonly tools?: ChatCompletionTool[];
@@ -1816,6 +1823,8 @@ interface OrchestrationModelSettings {
 /**
  * Stream options for orchestration post-LLM module processing.
  * Controls chunking behavior for translation, filtering, and other modules during streaming.
+ * Ignored with `orchestrationConfigRef`; configure streaming in the stored
+ * configuration or its `overrideConfig` instead.
  */
 interface OrchestrationStreamOptions {
     /**
@@ -1825,7 +1834,7 @@ interface OrchestrationStreamOptions {
     readonly chunkSize?: number;
     /**
      * Delimiters for splitting stream into chunks (e.g., sentence boundaries).
-     * Required when translation module is configured.
+     * Recommended for translation; the provider warns when local translation settings lack them.
      * @example ["\n", ".", "?", "!"]
      */
     readonly delimiters?: readonly string[];
@@ -1869,12 +1878,18 @@ interface SAPAIEmbeddingSettings {
     readonly masking?: MaskingModule | {
         providers: MaskingModule["masking_providers"];
     };
-    /** @default 2048 */
+    /**
+     * Maximum batch size: a positive integer, or `Infinity` for no provider-side limit.
+     * @default 2048
+     */
     readonly maxEmbeddingsPerCall?: number;
     readonly modelParams?: FoundationModelsEmbeddingParams | Record<string, unknown>;
     readonly modelVersion?: string;
     readonly [key: string]: unknown;
-    /** @default 'text' */
+    /**
+     * Orchestration embedding input type; ignored by Foundation Models.
+     * @default 'text'
+     */
     readonly type?: "document" | "query" | "text";
 }
 /**
@@ -1908,7 +1923,10 @@ interface SAPAISettings {
     readonly filtering?: FilteringModule;
     /** Orchestration API only. */
     readonly grounding?: GroundingModule;
-    /** @default false */
+    /**
+     * Forward assistant reasoning from the input history as text; does not enable reasoning output.
+     * @default false
+     */
     readonly includeReasoning?: boolean;
     /** Orchestration API only. */
     readonly masking?: MaskingModule | {
@@ -1923,7 +1941,7 @@ interface SAPAISettings {
     /** Orchestration API only. */
     readonly promptTemplateRef?: PromptTemplateRef;
     readonly responseFormat?: ResponseFormat;
-    /** Orchestration API only. */
+    /** Orchestration API only; ignored when `orchestrationConfigRef` is used. */
     readonly streamOptions?: OrchestrationStreamOptions;
     /** Orchestration API only. */
     readonly tools?: ChatCompletionTool[];
@@ -2068,7 +2086,7 @@ declare class ApiSwitchError extends Error {
  * @example
  * ```typescript
  * throw new UnsupportedFeatureError("Content filtering", "foundation-models", "orchestration");
- * // "Content filtering is only available with Orchestration API and will be ignored by Foundation Models API."
+ * // Rejects the request: content filtering requires the Orchestration API.
  * ```
  * @see {@link validateSettings} - Main validation function that throws this error
  * @see {@link ApiSwitchError} - Related error for API switching conflicts
@@ -2080,45 +2098,25 @@ declare class UnsupportedFeatureError extends Error {
     /**
      * Creates a new UnsupportedFeatureError.
      * @param feature - The name of the unsupported feature (e.g., "Content filtering").
-     * @param api - The API being used where the feature will be ignored.
+     * @param api - The API being used that does not support the feature.
      * @param suggestedApi - The API that supports this feature.
      */
     constructor(feature: string, api: SAPAIApiType, suggestedApi: SAPAIApiType);
 }
 
-/** Adapters to convert internal (V3) formats to LanguageModelV2 formats for the V2 facade. */
+/** Adapters for the semantic differences between the V3 core and V2 facade. */
 
+/** Stream events supported by the V2 facade. */
 type ConvertedV2StreamPart = Exclude<LanguageModelV2StreamPart, {
     type: "stream-start";
 }> | {
     type: "stream-start";
-    warnings: ReturnType<typeof convertWarningsToV2>;
+    warnings: ConvertedV2Warning[];
 };
-/**
- * Converts internal warnings array to V2 warnings array.
- * @param internalWarnings - Internal warning objects.
- * @returns V2 warning objects.
- * @internal
- */
-declare function convertWarningsToV2(internalWarnings: SharedV3Warning[]): ReturnType<typeof convertWarningToV2>[];
-/**
- * Converts internal warning to V2 warning format.
- *
- * Maps `unsupported`/`compatibility` warnings to V2 `other` type with descriptive message.
- * @param internalWarning - Internal warning object.
- * @returns V2 warning object.
- * @internal
- */
-declare function convertWarningToV2(internalWarning: SharedV3Warning): Extract<LanguageModelV2CallWarning, {
+/** V2 warning representation used when adapting V3 feature diagnostics. */
+type ConvertedV2Warning = Extract<LanguageModelV2CallWarning, {
     type: "other";
 }>;
-/**
- * Transforms internal stream to V2 ReadableStream.
- * @param internalStream - Internal ReadableStream to transform.
- * @returns V2-formatted ReadableStream.
- * @internal
- */
-declare function createV2StreamFromInternal(internalStream: ReadableStream<LanguageModelV3StreamPart>): ReadableStream<ConvertedV2StreamPart>;
 
 /**
  * SAP AI Language Model V2 - Vercel AI SDK LanguageModelV2 implementation for SAP AI Core.
@@ -2202,7 +2200,7 @@ declare class SAPAILanguageModelV2 implements LanguageModelV2$1 {
             headers?: SharedV2Headers;
         };
         usage: LanguageModelV2Usage;
-        warnings: ReturnType<typeof convertWarningsToV2>;
+        warnings: ConvertedV2Warning[];
     }>;
     doStream(options: CompatibleV2CallOptions): Promise<{
         request?: {
@@ -2211,7 +2209,7 @@ declare class SAPAILanguageModelV2 implements LanguageModelV2$1 {
         response?: {
             headers?: SharedV2Headers;
         };
-        stream: ReturnType<typeof createV2StreamFromInternal>;
+        stream: ReadableStream<ConvertedV2StreamPart>;
     }>;
 }
 
@@ -2223,14 +2221,15 @@ type DeploymentConfig = DeploymentIdConfig | ResourceGroupConfig;
  */
 interface SAPAIProviderSettings {
     /**
-     * SAP AI Core API to use for all models created by this provider.
-     * Can be overridden at model creation time or per-call via providerOptions.
+     * Default SAP AI Core API for models created by this provider.
+     * `defaultSettings.api`, per-model `api`, and per-call `providerOptions` take precedence.
+     * This option does not enable automatic failover between APIs.
      * - `'orchestration'` (default): SAP AI Core Orchestration API - supports filtering, grounding, masking, translation
      * - `'foundation-models'`: SAP AI Core Foundation Models API - supports dataSources, logprobs, seed, etc.
      * @default 'orchestration'
      */
     readonly api?: SAPAIApiType;
-    /** Default model settings applied to every model instance. Per-call settings override these. */
+    /** Default model settings; settings supplied at model creation override these. */
     readonly defaultSettings?: SAPAISettings;
     /** SAP AI Core deployment ID. If not provided, the SDK resolves deployment automatically. */
     readonly deploymentId?: string;
@@ -2238,13 +2237,16 @@ interface SAPAIProviderSettings {
     readonly destination?: HttpDestinationOrFetchOptions;
     /**
      * Log level for SAP Cloud SDK loggers.
-     * Controls verbosity of internal SAP SDK logging (e.g., authentication, service binding).
+     * Controls process-wide SAP SDK logging (e.g., authentication, service binding).
+     * Creating another provider resets this level, using warn when logLevel is omitted.
      * Note: SAP_CLOUD_SDK_LOG_LEVEL environment variable takes precedence if set.
      * @default 'warn'
      */
     readonly logLevel?: "debug" | "error" | "info" | "warn";
     /**
-     * Provider name used as key for `providerOptions` and `providerMetadata`.
+     * Name used in model provider identifiers. Call-level `providerOptions` and
+     * `providerMetadata` keys use the prefix before the first dot; avoid dots in names.
+     * Per-part prompt-cache directives always use the fixed `sap-ai` key.
      * @default 'sap-ai'
      */
     readonly name?: string;
@@ -2254,8 +2256,10 @@ interface SAPAIProviderSettings {
      *
      * Provider-level only (not overridable per-call via `providerOptions['sap-ai']`). The
      * AI SDK `abortSignal` option always wins over any `signal` on `requestConfig`; the
-     * latter is dropped before the request is forwarded. Node-only knobs (`httpAgent`,
-     * `httpsAgent`) are silently ignored on Edge / Cloudflare Workers runtimes.
+     * latter is dropped before the request is forwarded. Standard AI SDK call-level
+     * `headers` override matching `requestConfig.headers` case-insensitively. Other
+     * options, including Node-only agents (`httpAgent`, `httpsAgent`), are forwarded
+     * unchanged. The published package and SAP SDK transport require a Node-compatible runtime.
      *
      * See the "Note on `requestConfig`" section under `SAPAIProviderSettings` in
      * `API_REFERENCE.md` for the full SAP AI Core `AI-*` header guidance.
@@ -2271,6 +2275,7 @@ interface SAPAIProviderSettings {
     /** Whether to emit warnings for ambiguous configurations (e.g. both deploymentId and resourceGroup). */
     readonly warnOnAmbiguousConfig?: boolean;
 }
+
 /** SAP AI Provider interface extending Vercel AI SDK ProviderV2. */
 interface SAPAIProviderV2 extends ProviderV2 {
     (modelId: SAPAIModelId, settings?: SAPAISettings): SAPAILanguageModelV2;
@@ -2290,12 +2295,12 @@ interface SAPAIProviderV2 extends ProviderV2 {
  * @param options - Provider configuration options.
  * @param options.api - Default API type: `'orchestration'` (default) or `'foundation-models'`.
  * @param options.defaultSettings - Default model settings applied to every model instance.
- * @param options.deploymentId - SAP AI Core deployment ID for automatic deployment resolution.
+ * @param options.deploymentId - Explicit SAP AI Core deployment ID; omit for automatic deployment resolution.
  * @param options.destination - Custom SAP Cloud SDK destination configuration.
  * @param options.logLevel - Log level for SAP Cloud SDK loggers (`'debug'`, `'info'`, `'warn'`, `'error'`).
- * @param options.name - Provider name used as key in `providerOptions` (default: `'sap-ai'`).
+ * @param options.name - Provider name (default: `'sap-ai'`); see {@link SAPAIProviderSettings.name} for namespace rules.
  * @param options.requestConfig - Provider-level custom request configuration. See {@link SAPAIProviderSettings.requestConfig} for scope, portability, and abort semantics.
- * @param options.resourceGroup - SAP AI Core resource group (default: `'default'`).
+ * @param options.resourceGroup - SAP AI Core resource group (default: `'default'`); ignored when deploymentId is set.
  * @param options.warnOnAmbiguousConfig - Whether to warn when both deploymentId and resourceGroup are set.
  * @returns A configured SAP AI provider instance that can be used as a callable or via methods.
  * @example