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

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { LanguageModelV2, LanguageModelV2CallOptions, LanguageModelV2Content, LanguageModelV2FinishReason, LanguageModelV2Usage, JSONValue, LanguageModelV2CallWarning, LanguageModelV2StreamPart, ProviderV2 } from '@ai-sdk/provider';
+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';
@@ -292,7 +292,7 @@ interface SAPAIConfig {
 /**
  * SAP AI Chat Language Model implementation.
  *
- * This class implements the AI SDK's `LanguageModelV2` interface,
+ * This class implements the AI SDK's `LanguageModelV3` interface,
  * providing a bridge between the AI SDK and SAP AI Core's Orchestration API
  * using the official SAP AI SDK (@sap-ai-sdk/orchestration).
  *
@@ -322,10 +322,10 @@ interface SAPAIConfig {
  * });
  * ```
  *
- * @implements {LanguageModelV2}
+ * @implements {LanguageModelV3}
  */
-declare class SAPAIChatLanguageModel implements LanguageModelV2 {
-    readonly specificationVersion = "v2";
+declare class SAPAIChatLanguageModel implements LanguageModelV3 {
+    readonly specificationVersion = "v3";
     readonly modelId: SAPAIModelId;
     private readonly config;
     private readonly settings;
@@ -344,7 +344,7 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      * 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 (content-type rules are enforced via supportedUrls)
+     * @returns True if the URL protocol is HTTPS or data with valid image format
      */
     supportsUrl(url: URL): boolean;
     /**
@@ -354,9 +354,45 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      */
     get supportedUrls(): Record<string, RegExp[]>;
     /**
-     * Gets the provider identifier.
+     * Generates text completion using SAP AI Core's Orchestration API.
      *
-     * @returns The provider name ('sap-ai')
+     * 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
      */
     get provider(): string;
     /**
@@ -396,7 +432,7 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
     /**
      * Generates a single completion (non-streaming).
      *
-     * This method implements the `LanguageModelV2.doGenerate` interface,
+     * This method implements the `LanguageModelV3.doGenerate` interface,
      * sending a request to SAP AI Core and returning the complete response.
      *
      * **Features:**
@@ -404,6 +440,13 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      * - Multi-modal input (text + images)
      * - Data masking (if configured)
      * - Content filtering (if configured)
+     * - Abort signal support (via Promise.race)
+     *
+     * **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.
      *
      * @param options - Generation options including prompt, tools, and settings
      * @returns Promise resolving to the generation result with content, usage, and metadata
@@ -420,38 +463,32 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      * console.log(result.usage);   // Token usage
      * ```
      */
-    doGenerate(options: LanguageModelV2CallOptions): Promise<{
-        content: LanguageModelV2Content[];
-        finishReason: LanguageModelV2FinishReason;
-        usage: LanguageModelV2Usage;
-        providerMetadata?: Record<string, Record<string, JSONValue>>;
-        request: {
-            body?: unknown;
-        };
-        response: {
-            timestamp: Date;
-            modelId: string;
-            headers?: Record<string, string>;
-            body?: unknown;
-        };
-        warnings: LanguageModelV2CallWarning[];
-    }>;
+    doGenerate(options: LanguageModelV3CallOptions): Promise<LanguageModelV3GenerateResult>;
     /**
      * Generates a streaming completion.
      *
-     * This method implements the `LanguageModelV2.doStream` interface,
+     * This method implements the `LanguageModelV3.doStream` interface,
      * sending a streaming request to SAP AI Core and returning a stream of response parts.
      *
      * **Stream Events:**
-     * - `stream-start` - Stream initialization
+     * - `stream-start` - Stream initialization with warnings
      * - `response-metadata` - Response metadata (model, timestamp)
-     * - `text-start` - Text generation starts
-     * - `text-delta` - Incremental text chunks
-     * - `text-end` - Text generation completes
-     * - `tool-call` - Tool call detected
+     * - `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
+     * - `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
+     *
      * @param options - Streaming options including prompt, tools, and settings
      * @returns Promise resolving to stream and request metadata
      *
@@ -467,26 +504,22 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      *   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
      */
-    doStream(options: LanguageModelV2CallOptions): Promise<{
-        stream: ReadableStream<LanguageModelV2StreamPart>;
-        request?: {
-            body?: unknown;
-        };
-        response?: {
-            headers?: Record<string, string>;
-        };
-        warnings: LanguageModelV2CallWarning[];
-    }>;
+    doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
 }
 
 /**
  * SAP AI Provider interface.
  *
  * This is the main interface for creating and configuring SAP AI Core models.
- * It extends the standard AI SDK ProviderV2 interface with SAP-specific functionality.
+ * It extends the standard AI SDK ProviderV3 interface with SAP-specific functionality.
  *
  * @example
  * ```typescript
@@ -506,7 +539,7 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
  * const chatModel = provider.chat('gpt-4o');
  * ```
  */
-interface SAPAIProvider extends ProviderV2 {
+interface SAPAIProvider extends ProviderV3 {
     /**
      * Create a language model instance.
      *

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LanguageModelV2, LanguageModelV2CallOptions, LanguageModelV2Content, LanguageModelV2FinishReason, LanguageModelV2Usage, JSONValue, LanguageModelV2CallWarning, LanguageModelV2StreamPart, ProviderV2 } from '@ai-sdk/provider';
+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';
@@ -292,7 +292,7 @@ interface SAPAIConfig {
 /**
  * SAP AI Chat Language Model implementation.
  *
- * This class implements the AI SDK's `LanguageModelV2` interface,
+ * This class implements the AI SDK's `LanguageModelV3` interface,
  * providing a bridge between the AI SDK and SAP AI Core's Orchestration API
  * using the official SAP AI SDK (@sap-ai-sdk/orchestration).
  *
@@ -322,10 +322,10 @@ interface SAPAIConfig {
  * });
  * ```
  *
- * @implements {LanguageModelV2}
+ * @implements {LanguageModelV3}
  */
-declare class SAPAIChatLanguageModel implements LanguageModelV2 {
-    readonly specificationVersion = "v2";
+declare class SAPAIChatLanguageModel implements LanguageModelV3 {
+    readonly specificationVersion = "v3";
     readonly modelId: SAPAIModelId;
     private readonly config;
     private readonly settings;
@@ -344,7 +344,7 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      * 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 (content-type rules are enforced via supportedUrls)
+     * @returns True if the URL protocol is HTTPS or data with valid image format
      */
     supportsUrl(url: URL): boolean;
     /**
@@ -354,9 +354,45 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      */
     get supportedUrls(): Record<string, RegExp[]>;
     /**
-     * Gets the provider identifier.
+     * Generates text completion using SAP AI Core's Orchestration API.
      *
-     * @returns The provider name ('sap-ai')
+     * 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
      */
     get provider(): string;
     /**
@@ -396,7 +432,7 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
     /**
      * Generates a single completion (non-streaming).
      *
-     * This method implements the `LanguageModelV2.doGenerate` interface,
+     * This method implements the `LanguageModelV3.doGenerate` interface,
      * sending a request to SAP AI Core and returning the complete response.
      *
      * **Features:**
@@ -404,6 +440,13 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      * - Multi-modal input (text + images)
      * - Data masking (if configured)
      * - Content filtering (if configured)
+     * - Abort signal support (via Promise.race)
+     *
+     * **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.
      *
      * @param options - Generation options including prompt, tools, and settings
      * @returns Promise resolving to the generation result with content, usage, and metadata
@@ -420,38 +463,32 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      * console.log(result.usage);   // Token usage
      * ```
      */
-    doGenerate(options: LanguageModelV2CallOptions): Promise<{
-        content: LanguageModelV2Content[];
-        finishReason: LanguageModelV2FinishReason;
-        usage: LanguageModelV2Usage;
-        providerMetadata?: Record<string, Record<string, JSONValue>>;
-        request: {
-            body?: unknown;
-        };
-        response: {
-            timestamp: Date;
-            modelId: string;
-            headers?: Record<string, string>;
-            body?: unknown;
-        };
-        warnings: LanguageModelV2CallWarning[];
-    }>;
+    doGenerate(options: LanguageModelV3CallOptions): Promise<LanguageModelV3GenerateResult>;
     /**
      * Generates a streaming completion.
      *
-     * This method implements the `LanguageModelV2.doStream` interface,
+     * This method implements the `LanguageModelV3.doStream` interface,
      * sending a streaming request to SAP AI Core and returning a stream of response parts.
      *
      * **Stream Events:**
-     * - `stream-start` - Stream initialization
+     * - `stream-start` - Stream initialization with warnings
      * - `response-metadata` - Response metadata (model, timestamp)
-     * - `text-start` - Text generation starts
-     * - `text-delta` - Incremental text chunks
-     * - `text-end` - Text generation completes
-     * - `tool-call` - Tool call detected
+     * - `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
+     * - `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
+     *
      * @param options - Streaming options including prompt, tools, and settings
      * @returns Promise resolving to stream and request metadata
      *
@@ -467,26 +504,22 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
      *   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
      */
-    doStream(options: LanguageModelV2CallOptions): Promise<{
-        stream: ReadableStream<LanguageModelV2StreamPart>;
-        request?: {
-            body?: unknown;
-        };
-        response?: {
-            headers?: Record<string, string>;
-        };
-        warnings: LanguageModelV2CallWarning[];
-    }>;
+    doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
 }
 
 /**
  * SAP AI Provider interface.
  *
  * This is the main interface for creating and configuring SAP AI Core models.
- * It extends the standard AI SDK ProviderV2 interface with SAP-specific functionality.
+ * It extends the standard AI SDK ProviderV3 interface with SAP-specific functionality.
  *
  * @example
  * ```typescript
@@ -506,7 +539,7 @@ declare class SAPAIChatLanguageModel implements LanguageModelV2 {
  * const chatModel = provider.chat('gpt-4o');
  * ```
  */
-interface SAPAIProvider extends ProviderV2 {
+interface SAPAIProvider extends ProviderV3 {
     /**
      * Create a language model instance.
      *