@jerome-benoit/sap-ai-provider 4.0.0 → 4.0.1

package/dist/index.d.ts

@@ -10,7 +10,6 @@ import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateRes
  * 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:**
@@ -21,6 +20,7 @@ import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateRes
  * **Google Vertex AI Models:**
  * - gemini-2.0-flash, gemini-2.0-flash-lite
  * - gemini-2.5-flash, gemini-2.5-pro
+ * - ⚠️ **Limitation:** Gemini models support only 1 tool per request
  *
  * **AWS Bedrock Models:**
  * - anthropic--claude-3-haiku, anthropic--claude-3-sonnet, anthropic--claude-3-opus
@@ -30,6 +30,7 @@ import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateRes
  *
  * **AI Core Open Source Models:**
  * - mistralai--mistral-large-instruct, mistralai--mistral-medium-instruct, mistralai--mistral-small-instruct
+ * - meta--llama3.1-70b-instruct
  * - cohere--command-a-reasoning
  */
 type SAPAIModelId = ChatModel;
@@ -39,7 +40,6 @@ type SAPAIModelId = ChatModel;
  * These settings control model parameters, data masking, content filtering,
  * and tool usage. Settings can be provided at provider-level (defaults) or
  * per-model call (overrides).
- *
  * @example
  * **Basic usage with model parameters**
  * ```typescript
@@ -50,7 +50,6 @@ type SAPAIModelId = ChatModel;
  *   }
  * });
  * ```
- *
  * @example
  * **With data masking (DPI)**
  * ```typescript
@@ -67,7 +66,6 @@ type SAPAIModelId = ChatModel;
  *   }
  * });
  * ```
- *
  * @example
  * **With content filtering**
  * ```typescript
@@ -86,9 +84,7 @@ interface SAPAISettings {
     /**
      * 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';
@@ -113,9 +109,7 @@ interface SAPAISettings {
      * 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';
@@ -142,35 +136,14 @@ interface SAPAISettings {
     /**
      * Whether to include assistant reasoning parts in the SAP prompt conversion.
      *
-     * Reasoning parts contain internal model chain-of-thought reasoning that may not be
-     * suitable for end-user display or persistence. When disabled (default), only the
-     * final response content is forwarded.
-     *
-     * **Default:** `false` (recommended for production)
-     *
-     * **When to enable:**
-     * - Debugging model behavior
-     * - Analyzing reasoning patterns
-     * - Research and development
-     *
-     * **When to keep disabled:**
-     * - Production applications
-     * - User-facing chatbots
-     * - When storing conversation history
-     *
+     * Reasoning parts contain internal model chain-of-thought reasoning. When disabled,
+     * only the final response content is forwarded. Enable for debugging/analysis;
+     * disable for production applications and user-facing chatbots.
+     * @default false
      * @example
      * ```typescript
-     * // Enable for debugging (see model's reasoning)
-     * const debugModel = provider('gpt-4o', {
-     *   includeReasoning: true
-     * });
-     *
-     * // Disabled by default (production use)
-     * const prodModel = provider('gpt-4o');
-     * // or explicitly:
-     * const prodModel2 = provider('gpt-4o', {
-     *   includeReasoning: false
-     * });
+     * const debugModel = provider('gpt-4o', { includeReasoning: true });
+     * const prodModel = provider('gpt-4o'); // includeReasoning defaults to false
      * ```
      */
     includeReasoning?: boolean;
@@ -178,9 +151,7 @@ interface SAPAISettings {
      * 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';
@@ -216,7 +187,9 @@ interface SAPAISettings {
         /**
          * Number of completions to generate.
          * Multiple completions provide alternative responses.
-         * Note: Not supported by Amazon and Anthropic models.
+         *
+         * Note: Not supported by Amazon and Anthropic models. When used with these
+         * models, the parameter is silently omitted from the request.
          * If not specified, typically defaults to 1 on the model side.
          */
         n?: number;
@@ -254,8 +227,6 @@ interface SAPAISettings {
     /**
      * Response format for templating prompt (OpenAI-compatible)
      * Allows specifying structured output formats
-     *
-  
      * @example
      * ```typescript
      * const model = provider('gpt-4o', {
@@ -285,13 +256,12 @@ interface SAPAISettings {
     /**
      * Tool definitions in SAP AI SDK format
      *
-  
+     *
      * Use this to pass tools directly with proper JSON Schema definitions.
      * This bypasses the AI SDK's Zod conversion which may have issues.
      *
      * Note: This should be used in conjunction with AI SDK's tool handling
      * to provide the actual tool implementations (execute functions).
-     *
      * @example
      * ```typescript
      * const model = provider('gpt-4o', {
@@ -320,9 +290,7 @@ interface SAPAISettings {
      * 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';
@@ -371,10 +339,8 @@ interface SAPAIConfig {
  * - Google Vertex AI models (gemini-2.0-flash, gemini-2.5-pro, etc.)
  * - 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
@@ -387,8 +353,6 @@ interface SAPAIConfig {
  *   prompt: 'Hello, world!'
  * });
  * ```
- *
- * @implements {LanguageModelV3}
  */
 declare class SAPAILanguageModel implements LanguageModelV3 {
     readonly modelId: SAPAIModelId;
@@ -401,7 +365,11 @@ declare class SAPAILanguageModel implements LanguageModelV3 {
      * SAP AI Core will fail the request at runtime.
      */
     readonly supportsImageUrls: boolean;
-    /** Multiple completions via the `n` parameter (provider-specific support). */
+    /**
+     * Multiple completions via the `n` parameter.
+     * Note: Amazon and Anthropic models do not support this feature.
+     * The provider silently omits the parameter for unsupported models.
+     */
     readonly supportsMultipleCompletions: boolean;
     /** Parallel tool calls. */
     readonly supportsParallelToolCalls: boolean;
@@ -412,50 +380,12 @@ declare class SAPAILanguageModel implements LanguageModelV3 {
     /** Tool/function calling. */
     readonly supportsToolCalls: boolean;
     /**
-     * Generates text completion using SAP AI Core's Orchestration API.
-     *
-     * This method implements the `LanguageModelV3.doGenerate` interface,
-     * providing synchronous (non-streaming) text generation with support for:
-     * - Multi-turn conversations with system/user/assistant messages
-     * - Tool calling (function calling) with structured outputs
-     * - Multi-modal inputs (text + images)
-     * - Data masking via SAP DPI
-     * - Content filtering via Azure Content Safety or Llama Guard
-     *
-     * **Return Structure:**
-     * - Finish reason: `{ unified: string, raw?: string }`
-     * - Usage: Nested structure with token breakdown `{ inputTokens: { total, ... }, outputTokens: { total, ... } }`
-     * - Warnings: Array of warnings with `type` and optional `feature` field
-     *
-     * @param options - Generation options including prompt, tools, temperature, etc.
-     * @returns Promise resolving to generation result with content, usage, and metadata
-     *
-     * @throws {InvalidPromptError} If prompt format is invalid
-     * @throws {InvalidArgumentError} If arguments are malformed
-     * @throws {APICallError} If the SAP AI Core API call fails
-     *
-     * @example
-     * ```typescript
-     * const result = await model.doGenerate({
-     *   prompt: [
-     *     { role: 'user', content: [{ type: 'text', text: 'Hello!' }] }
-     *   ],
-     *   temperature: 0.7,
-     *   maxTokens: 100
-     * });
-     *
-     * console.log(result.content); // Array of V3 content parts
-     * console.log(result.finishReason.unified); // "stop", "length", "tool-calls", etc.
-     * console.log(result.usage.inputTokens.total); // Total input tokens
-     * ```
-     *
-     * @since 1.0.0
-     * @since 4.0.0 Updated to LanguageModelV3 interface
+     * Returns the provider identifier.
+     * @returns The provider name
      */
     get provider(): string;
     /**
      * Returns supported URL patterns for different content types.
-     *
      * @returns Record of content types to regex patterns
      */
     get supportedUrls(): Record<string, RegExp[]>;
@@ -463,13 +393,10 @@ declare class SAPAILanguageModel implements LanguageModelV3 {
     private readonly settings;
     /**
      * Creates a new SAP AI Chat Language Model instance.
-     *
+     * @internal
      * @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);
     /**
@@ -487,15 +414,12 @@ declare class SAPAILanguageModel implements LanguageModelV3 {
      *
      * **Note on Abort Signal:**
      * The abort signal implementation uses Promise.race to reject the promise when
-     * the signal is aborted. However, this does not cancel the underlying HTTP request
-     * to SAP AI Core - the request continues executing on the server. This is a
-     * limitation of the SAP AI SDK's chatCompletion API.
-     *
-     * @see https://github.com/SAP/ai-sdk-js/issues/1429 for tracking true cancellation support
-     *
+     * aborted. However, this does not cancel the underlying HTTP request to SAP AI Core -
+     * the request continues executing on the server. This is a current limitation of the
+     * SAP AI SDK's API. See https://github.com/SAP/ai-sdk-js/issues/1429
      * @param options - Generation options including prompt, tools, and settings
      * @returns Promise resolving to the generation result with content, usage, and metadata
-     *
+     * @since 1.0.0
      * @example
      * ```typescript
      * const result = await model.doGenerate({
@@ -512,40 +436,29 @@ declare class SAPAILanguageModel implements LanguageModelV3 {
     /**
      * Generates a streaming completion.
      *
-     * This method implements the `LanguageModelV3.doStream` interface,
-     * sending a streaming request to SAP AI Core and returning a stream of response parts.
+     * Implements `LanguageModelV3.doStream`, sending a streaming request to SAP AI Core
+     * and returning a stream of response parts.
      *
      * **Stream Events:**
-     * - `stream-start` - Stream initialization with warnings
-     * - `response-metadata` - Response metadata (model, timestamp)
+     * - `stream-start` - Initialization with warnings
+     * - `response-metadata` - Model, timestamp, response ID
      * - `text-start` - Text block begins (with unique ID)
-     * - `text-delta` - Incremental text chunks (with block ID)
-     * - `text-end` - Text block completes (with accumulated text)
-     * - `tool-input-start` - Tool input begins
-     * - `tool-input-delta` - Tool input chunk
-     * - `tool-input-end` - Tool input completes
+     * - `text-delta` - Incremental text chunks
+     * - `text-end` - Text block completes
+     * - `tool-input-start/delta/end` - Tool input lifecycle
      * - `tool-call` - Complete tool call
      * - `finish` - Stream completes with usage and finish reason
      * - `error` - Error occurred
      *
-     * **Stream Structure:**
-     * - Text blocks have explicit lifecycle with unique IDs
-     * - Finish reason format: `{ unified: string, raw?: string }`
-     * - Usage format: `{ inputTokens: { total, ... }, outputTokens: { total, ... } }`
-     * - Warnings only in `stream-start` event
+     * **Response ID:**
+     * Client-generated UUID in `response-metadata.id` and `providerMetadata['sap-ai'].responseId`.
+     * TODO: Use backend's `x-request-id` when `OrchestrationStreamResponse` exposes `rawResponse`.
      *
-     * **Note on Abort Signal:**
-     * The abort signal implementation uses Promise.race to reject the promise when
-     * the signal is aborted. However, this does not cancel the underlying HTTP request
-     * to SAP AI Core - the request continues executing on the server. This is a
-     * limitation of the SAP AI SDK's chatCompletion API.
-     *
-     * @see https://github.com/SAP/ai-sdk-js/issues/1429 for tracking true cancellation support
+     * **Abort Signal:**
+     * Same limitation as `doGenerate` - see its documentation for details.
      * @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
-     *
      * @example
      * ```typescript
      * const { stream } = await model.doStream({
@@ -558,25 +471,19 @@ declare class SAPAILanguageModel implements LanguageModelV3 {
      *   if (part.type === 'text-delta') {
      *     process.stdout.write(part.delta);
      *   }
-     *   if (part.type === 'text-end') {
-     *     console.log('Block complete:', part.id, part.text);
-     *   }
      * }
      * ```
-     *
-     * @since 4.0.0
+     * @since 1.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
@@ -584,7 +491,6 @@ declare class SAPAILanguageModel implements LanguageModelV3 {
     private buildOrchestrationConfig;
     /**
      * Creates an OrchestrationClient instance.
-     *
      * @param config - Orchestration module configuration
      * @returns OrchestrationClient instance
      * @internal
@@ -601,7 +507,6 @@ type DeploymentConfig = DeploymentIdConfig | ResourceGroupConfig;
  *
  * This is the main interface for creating and configuring SAP AI Core models.
  * It extends the standard AI SDK ProviderV3 interface with SAP-specific functionality.
- *
  * @example
  * ```typescript
  * const provider = createSAPAIProvider({
@@ -623,7 +528,6 @@ type DeploymentConfig = DeploymentIdConfig | ResourceGroupConfig;
 interface SAPAIProvider extends ProviderV3 {
     /**
      * Create a language model instance.
-     *
      * @param modelId - The SAP AI Core model identifier (e.g., 'gpt-4o', 'anthropic--claude-3.5-sonnet')
      * @param settings - Optional model configuration settings
      * @returns Configured SAP AI chat language model instance
@@ -634,7 +538,6 @@ interface SAPAIProvider extends ProviderV3 {
      *
      * This method is equivalent to calling the provider function directly,
      * but provides a more explicit API for chat-based interactions.
-     *
      * @param modelId - The SAP AI Core model identifier
      * @param settings - Optional model configuration settings
      * @returns Configured SAP AI chat language model instance
@@ -645,9 +548,7 @@ interface SAPAIProvider extends ProviderV3 {
  * Configuration settings for the SAP AI Provider.
  *
  * This interface defines all available options for configuring the SAP AI Core connection
- * using the official SAP AI SDK. The SDK handles authentication automatically when
- * running on SAP BTP (via service binding) or locally (via AICORE_SERVICE_KEY env var).
- *
+ * using the official SAP AI SDK. See {@link createSAPAIProvider} for authentication details.
  * @example
  * ```typescript
  * // Using default configuration (auto-detects service binding or env var)
@@ -677,7 +578,6 @@ interface SAPAIProviderSettings {
      *
      * A specific deployment ID to use for orchestration requests.
      * If not provided, the SDK will resolve the deployment automatically.
-     *
      * @example
      * ```typescript
      * deploymentId: 'd65d81e7c077e583'
@@ -691,7 +591,6 @@ interface SAPAIProviderSettings {
      * - Custom proxy configurations
      * - Non-standard SAP AI Core setups
      * - Testing environments
-     *
      * @example
      * ```typescript
      * destination: {
@@ -706,7 +605,6 @@ interface SAPAIProviderSettings {
      * 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
@@ -743,10 +641,8 @@ interface SAPAIProviderSettings {
  * - Tool calling support
  * - Data masking (DPI)
  * - Content filtering
- *
  * @param options - Configuration options for the provider
  * @returns A configured SAP AI provider
- *
  * @example
  * **Basic Usage**
  * ```typescript
@@ -760,7 +656,6 @@ interface SAPAIProviderSettings {
  *   prompt: 'Hello, world!'
  * });
  * ```
- *
  * @example
  * **With Resource Group**
  * ```typescript
@@ -775,7 +670,6 @@ interface SAPAIProviderSettings {
  *   }
  * });
  * ```
- *
  * @example
  * **With Default Settings**
  * ```typescript
@@ -792,9 +686,8 @@ declare function createSAPAIProvider(options?: SAPAIProviderSettings): SAPAIProv
 /**
  * Default SAP AI provider instance.
  *
- * Uses the default configuration which auto-detects authentication
- * from service binding (SAP BTP) or AICORE_SERVICE_KEY environment variable.
- *
+ * Uses default configuration with automatic authentication.
+ * See {@link createSAPAIProvider} for authentication details.
  * @example
  * ```typescript
  * import { sapai } from '@mymediset/sap-ai-provider';