@jerome-benoit/sap-ai-provider-v2 4.1.2-rc.1

package/dist/index.d.ts

@@ -0,0 +1,972 @@
+import { EmbeddingModelV2, SharedV2ProviderOptions, SharedV2ProviderMetadata, SharedV2Headers, LanguageModelV2, LanguageModelV2CallOptions, LanguageModelV2Content, LanguageModelV2FinishReason, LanguageModelV2ResponseMetadata, LanguageModelV2Usage, LanguageModelV2CallWarning, LanguageModelV2StreamPart } from '@ai-sdk/provider';
+import { DeploymentIdConfig, ResourceGroupConfig } from '@sap-ai-sdk/ai-api/internal.js';
+import { HttpDestinationOrFetchOptions } from '@sap-cloud-sdk/connectivity';
+import { EmbeddingModelParams, FilteringModule, GroundingModule, MaskingModule, ChatCompletionTool, TranslationModule, ChatModel } from '@sap-ai-sdk/orchestration';
+export { AssistantChatMessage, ChatCompletionRequest, ChatCompletionTool, ChatMessage, DeveloperChatMessage, DocumentTranslationApplyToSelector, FilteringModule, FunctionObject, GroundingModule, LlmModelDetails, LlmModelParams, MaskingModule, OrchestrationClient, OrchestrationConfigRef, OrchestrationEmbeddingClient, 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 * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
+import { InferSchema } from '@ai-sdk/provider-utils';
+
+/**
+ * Model ID type for SAP AI embedding models.
+ *
+ * Common embedding models available in SAP AI Core:
+ * - `text-embedding-ada-002` - OpenAI Ada v2
+ * - `text-embedding-3-small` - OpenAI v3 small
+ * - `text-embedding-3-large` - OpenAI v3 large
+ */
+type SAPAIEmbeddingModelId = string;
+/**
+ * Settings for the SAP AI Embedding Model.
+ */
+interface SAPAIEmbeddingSettings {
+    /**
+     * Maximum number of embeddings per API call.
+     * @default 2048
+     */
+    maxEmbeddingsPerCall?: number;
+    /**
+     * Additional model parameters passed to the embedding API.
+     */
+    modelParams?: EmbeddingModelParams;
+    /**
+     * Embedding task type.
+     * @default 'text'
+     */
+    type?: "document" | "query" | "text";
+}
+
+/**
+ * SAP AI Embedding Model V2 implementation.
+ *
+ * This module provides an EmbeddingModelV2 facade that wraps the internal
+ * EmbeddingModelV3 implementation and transforms the output to V2 format.
+ *
+ * This approach allows us to:
+ * - Reuse all SAP AI Core business logic from the V3 implementation
+ * - Present a V2 API to users (compatible with AI SDK 5.x)
+ * - Keep the upstream V3 code unchanged for easy git merges
+ * @module sap-ai-embedding-model-v2
+ */
+
+/**
+ * Internal configuration for the SAP AI Embedding Model.
+ * @internal
+ */
+interface SAPAIEmbeddingConfig {
+    deploymentConfig: DeploymentIdConfig | ResourceGroupConfig;
+    destination?: HttpDestinationOrFetchOptions;
+    provider: string;
+}
+/**
+ * SAP AI Core Embedding Model implementing the Vercel AI SDK EmbeddingModelV2 interface.
+ *
+ * This class implements the AI SDK's `EmbeddingModelV2` interface (for AI SDK 5.x),
+ * providing a bridge between AI SDK 5.x and SAP AI Core's Orchestration API
+ * using the official SAP AI SDK (@sap-ai-sdk/orchestration).
+ *
+ * **Architecture:**
+ * This is a thin facade that delegates to the internal V3 implementation
+ * (SAPAIEmbeddingModel) and transforms the output to V2 format.
+ *
+ * **Features:**
+ * - Text embedding generation (single and batch)
+ * - Multiple embedding types (query, document)
+ * - Parallel batch processing
+ *
+ * **Model Support:**
+ * - Azure OpenAI embeddings (text-embedding-ada-002, text-embedding-3-small, text-embedding-3-large)
+ * - Anthropic embeddings (if available through SAP AI Core)
+ * - Other embedding models available in SAP AI Core
+ * @see {@link https://sdk.vercel.ai/docs/ai-sdk-core/embeddings Vercel AI SDK Embeddings}
+ * @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
+ * const provider = createSAPAIProvider();
+ *
+ * // Single embedding
+ * const { embedding } = await embed({
+ *   model: provider.textEmbedding('text-embedding-ada-002'),
+ *   value: 'Hello, world!'
+ * });
+ *
+ * // Multiple embeddings
+ * const { embeddings } = await embedMany({
+ *   model: provider.textEmbedding('text-embedding-3-small'),
+ *   values: ['Hello', 'World', 'AI']
+ * });
+ * ```
+ */
+declare class SAPAIEmbeddingModelV2 implements EmbeddingModelV2<string> {
+    readonly maxEmbeddingsPerCall: number | undefined;
+    readonly modelId: string;
+    readonly provider: string;
+    readonly specificationVersion: "v2";
+    readonly supportsParallelCalls: boolean;
+    /** Internal V3 model instance that handles all SAP AI Core logic */
+    private readonly v3Model;
+    /**
+     * Creates a new SAP AI Embedding Model V2 instance.
+     * @internal
+     * @param modelId - The embedding model identifier (e.g., 'text-embedding-ada-002')
+     * @param settings - Model-specific configuration settings
+     * @param config - Internal configuration (deployment config, destination, etc.)
+     */
+    constructor(modelId: string, settings: SAPAIEmbeddingSettings, config: SAPAIEmbeddingConfig);
+    /**
+     * Generates embeddings for the given text values.
+     *
+     * Implements `EmbeddingModelV2.doEmbed`, delegating to the internal V3 implementation
+     * and transforming the response to V2 format.
+     *
+     * The main differences between V2 and V3:
+     * - V3 includes a `warnings` array that needs to be converted
+     * - Provider metadata and headers use different type definitions
+     * @param options - Embedding options including values and headers
+     * @param options.values - Array of text values to embed
+     * @param options.abortSignal - Optional abort signal for cancelling the operation
+     * @param options.providerOptions - Optional provider-specific options
+     * @param options.headers - Optional HTTP headers
+     * @returns Promise resolving to embeddings and metadata in V2 format
+     */
+    doEmbed(options: {
+        abortSignal?: AbortSignal;
+        headers?: Record<string, string | undefined>;
+        providerOptions?: SharedV2ProviderOptions;
+        values: string[];
+    }): Promise<{
+        embeddings: number[][];
+        providerMetadata?: SharedV2ProviderMetadata;
+        response?: {
+            body?: unknown;
+            headers?: SharedV2Headers;
+        };
+        usage?: {
+            tokens: number;
+        };
+    }>;
+}
+
+/**
+ * The provider identifier used for provider options.
+ * Use this key in `providerOptions` to pass SAP AI-specific options.
+ * @example
+ * ```typescript
+ * providerOptions: {
+ *   [SAP_AI_PROVIDER_NAME]: { includeReasoning: true }
+ * }
+ * ```
+ */
+declare const SAP_AI_PROVIDER_NAME: "sap-ai";
+/**
+ * Zod schema for SAP AI language model provider options.
+ *
+ * These options can be passed per-call via `providerOptions['sap-ai']` to override
+ * constructor settings or provide request-specific configuration.
+ * @example
+ * ```typescript
+ * const result = await generateText({
+ *   model: provider('gpt-4o'),
+ *   prompt: 'Hello',
+ *   providerOptions: {
+ *     'sap-ai': {
+ *       includeReasoning: true,
+ *       modelParams: { temperature: 0.7, maxTokens: 1000 }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const sapAILanguageModelProviderOptions: _ai_sdk_provider_utils.LazySchema<{
+    includeReasoning?: boolean | undefined;
+    modelParams?: {
+        [x: string]: unknown;
+        frequencyPenalty?: number | undefined;
+        maxTokens?: number | undefined;
+        n?: number | undefined;
+        parallel_tool_calls?: boolean | undefined;
+        presencePenalty?: number | undefined;
+        temperature?: number | undefined;
+        topP?: number | undefined;
+    } | undefined;
+}>;
+/**
+ * TypeScript type for SAP AI language model provider options.
+ * Inferred from the Zod schema for type safety.
+ */
+type SAPAILanguageModelProviderOptions = InferSchema<typeof sapAILanguageModelProviderOptions>;
+/**
+ * Zod schema for SAP AI embedding model provider options.
+ *
+ * These options can be passed per-call via `providerOptions['sap-ai']` to override
+ * constructor settings or provide request-specific configuration.
+ * @example
+ * ```typescript
+ * const { embedding } = await embed({
+ *   model: provider.embedding('text-embedding-ada-002'),
+ *   value: 'Hello, world!',
+ *   providerOptions: {
+ *     'sap-ai': {
+ *       type: 'query'
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare const sapAIEmbeddingProviderOptions: _ai_sdk_provider_utils.LazySchema<{
+    modelParams?: {
+        [x: string]: unknown;
+        dimensions?: number | undefined;
+        encoding_format?: "base64" | "binary" | "float" | undefined;
+        normalize?: boolean | undefined;
+    } | undefined;
+    type?: "document" | "query" | "text" | undefined;
+}>;
+/**
+ * TypeScript type for SAP AI embedding model provider options.
+ * Inferred from the Zod schema for type safety.
+ */
+type SAPAIEmbeddingProviderOptions = InferSchema<typeof sapAIEmbeddingProviderOptions>;
+
+/**
+ * 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
+ * - ⚠️ **Limitation:** Gemini models support only 1 tool per request
+ *
+ * **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
+ * - meta--llama3.1-70b-instruct
+ * - cohere--command-a-reasoning
+ */
+type SAPAIModelId = ChatModel;
+/**
+ * Settings for configuring SAP AI Core model behavior.
+ *
+ * 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
+ * const model = provider('gpt-4o', {
+ *   modelParams: {
+ *     temperature: 0.7,
+ *     maxTokens: 2000
+ *   }
+ * });
+ * ```
+ * @example
+ * **With data masking (DPI)**
+ * ```typescript
+ * import { buildDpiMaskingProvider } from '@mymediset/sap-ai-provider';
+ *
+ * const model = provider('gpt-4o', {
+ *   masking: {
+ *     masking_providers: [
+ *       buildDpiMaskingProvider({
+ *         method: 'anonymization',
+ *         entities: ['profile-email', 'profile-person']
+ *       })
+ *     ]
+ *   }
+ * });
+ * ```
+ * @example
+ * **With content filtering**
+ * ```typescript
+ * import { buildAzureContentSafetyFilter } from '@mymediset/sap-ai-provider';
+ *
+ * const model = provider('gpt-4o', {
+ *   filtering: {
+ *     input: {
+ *       filters: [buildAzureContentSafetyFilter('input', { hate: 'ALLOW_SAFE' })]
+ *     }
+ *   }
+ * });
+ * ```
+ */
+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';
+     *
+     * const model = provider('gpt-4o', {
+     *   filtering: {
+     *     input: {
+     *       filters: [
+     *         buildAzureContentSafetyFilter('input', {
+     *           hate: 'ALLOW_SAFE',
+     *           violence: 'ALLOW_SAFE_LOW_MEDIUM'
+     *         })
+     *       ]
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    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.
+     *
+     * 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
+     * const debugModel = provider('gpt-4o', { includeReasoning: true });
+     * const prodModel = provider('gpt-4o'); // includeReasoning defaults to false
+     * ```
+     */
+    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?: {
+        /**
+         * Frequency penalty between -2.0 and 2.0.
+         * Positive values penalize tokens based on their frequency.
+         * If not specified, the model's default is used (typically 0).
+         */
+        frequencyPenalty?: number;
+        /**
+         * Maximum number of tokens to generate.
+         * Higher values allow for longer responses but increase latency and cost.
+         */
+        maxTokens?: number;
+        /**
+         * Number of completions to generate.
+         * Multiple completions provide alternative responses.
+         *
+         * 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;
+        /**
+         * Whether to enable parallel tool calls.
+         * When enabled, the model can call multiple tools in parallel.
+         *
+         * Note: This uses the SAP/OpenAI-style key `parallel_tool_calls`.
+         */
+        parallel_tool_calls?: boolean;
+        /**
+         * 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;
+    };
+    /**
+     * Specific version of the model to use.
+     * If not provided, the latest version will be used.
+     */
+    modelVersion?: string;
+    /**
+     * Response format for templating prompt (OpenAI-compatible)
+     * Allows specifying structured output formats
+     * @example
+     * ```typescript
+     * const model = provider('gpt-4o', {
+     *   responseFormat: {
+     *     type: 'json_schema',
+     *     json_schema: {
+     *       name: 'response',
+     *       schema: { type: 'object', properties: { answer: { type: 'string' } } }
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    responseFormat?: {
+        json_schema: {
+            description?: string;
+            name: string;
+            schema?: unknown;
+            strict?: boolean | null;
+        };
+        type: "json_schema";
+    } | {
+        type: "json_object";
+    } | {
+        type: "text";
+    };
+    /**
+     * 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', {
+     *   tools: [
+     *     {
+     *       type: 'function',
+     *       function: {
+     *         name: 'get_weather',
+     *         description: 'Get weather for a location',
+     *         parameters: {
+     *           type: 'object',
+     *           properties: {
+     *             location: { type: 'string', description: 'City name' }
+     *           },
+     *           required: ['location']
+     *         }
+     *       }
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    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;
+}
+
+/**
+ * SAP AI Language Model V2 implementation.
+ *
+ * This module provides a LanguageModelV2 facade that wraps the internal
+ * LanguageModelV3 implementation and transforms the output to V2 format.
+ *
+ * This approach allows us to:
+ * - Reuse all SAP AI Core business logic from the V3 implementation
+ * - Present a V2 API to users (compatible with AI SDK 5.x)
+ * - Keep the upstream V3 code unchanged for easy git merges
+ * @module sap-ai-language-model-v2
+ */
+
+/**
+ * Internal configuration for the SAP AI Language Model.
+ * @internal
+ */
+interface SAPAIConfig {
+    deploymentConfig: DeploymentIdConfig | ResourceGroupConfig;
+    destination?: HttpDestinationOrFetchOptions;
+    provider: string;
+}
+/**
+ * SAP AI Language Model V2 implementation.
+ *
+ * This class implements the AI SDK's `LanguageModelV2` interface (for AI SDK 5.x),
+ * providing a bridge between AI SDK 5.x and SAP AI Core's Orchestration API
+ * using the official SAP AI SDK (@sap-ai-sdk/orchestration).
+ *
+ * **Architecture:**
+ * This is a thin facade that delegates to the internal V3 implementation
+ * (SAPAILanguageModel) and transforms the output to V2 format.
+ *
+ * **Features:**
+ * - Text generation (streaming and non-streaming)
+ * - Tool calling (function calling)
+ * - Multi-modal input (text + images)
+ * - Data masking (SAP DPI)
+ * - Content filtering
+ *
+ * **Model Support:**
+ * - Azure OpenAI models (gpt-4o, gpt-4o-mini, o1, o3, etc.)
+ * - 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-v2 Vercel AI SDK LanguageModelV2}
+ * @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
+ * const provider = createSAPAIProvider();
+ * const model = provider('gpt-4o');
+ *
+ * // Use with AI SDK 5.x
+ * const result = await generateText({
+ *   model,
+ *   prompt: 'Hello, world!'
+ * });
+ * ```
+ */
+declare class SAPAILanguageModelV2 implements LanguageModelV2 {
+    readonly modelId: SAPAIModelId;
+    readonly specificationVersion: "v2";
+    /**
+     * 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[]>;
+    /** Internal V3 model instance that handles all SAP AI Core logic */
+    private readonly v3Model;
+    /**
+     * Creates a new SAP AI Language Model V2 instance.
+     * @internal
+     * @param modelId - The model identifier
+     * @param settings - Model-specific configuration settings
+     * @param config - Internal configuration (deployment config, destination, etc.)
+     * @throws {z.ZodError} If modelParams contains invalid values
+     */
+    constructor(modelId: SAPAIModelId, settings: SAPAISettings, config: SAPAIConfig);
+    /**
+     * Generates a single completion (non-streaming).
+     *
+     * This method implements the `LanguageModelV2.doGenerate` interface,
+     * delegating to the internal V3 implementation and transforming the result
+     * to V2 format.
+     *
+     * **Features:**
+     * - Tool calling support
+     * - 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
+     * 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
+     * @see {@link convertFinishReasonV3ToV2} for finish reason transformation
+     * @see {@link convertUsageV3ToV2} for usage statistics transformation
+     * @see {@link convertWarningsV3ToV2} for warnings transformation
+     * @since 1.0.0
+     * @example
+     * ```typescript
+     * const result = await model.doGenerate({
+     *   prompt: [
+     *     { role: 'user', content: [{ type: 'text', text: 'Hello!' }] }
+     *   ]
+     * });
+     *
+     * console.log(result.content);      // Generated content
+     * console.log(result.usage);        // Token usage (V2 format)
+     * console.log(result.finishReason); // 'stop' (V2 string format)
+     * ```
+     */
+    doGenerate(options: LanguageModelV2CallOptions): Promise<{
+        content: LanguageModelV2Content[];
+        finishReason: LanguageModelV2FinishReason;
+        providerMetadata?: SharedV2ProviderMetadata;
+        request?: {
+            body?: unknown;
+        };
+        response?: LanguageModelV2ResponseMetadata & {
+            body?: unknown;
+            headers?: SharedV2Headers;
+        };
+        usage: LanguageModelV2Usage;
+        warnings: LanguageModelV2CallWarning[];
+    }>;
+    /**
+     * Generates a streaming completion.
+     *
+     * Implements `LanguageModelV2.doStream`, delegating to the internal V3 implementation
+     * and transforming the stream to V2 format.
+     *
+     * **Stream Events:**
+     * - `stream-start` - Initialization with warnings
+     * - `response-metadata` - Model, timestamp, response ID
+     * - `text-start` - Text block begins (with unique ID)
+     * - `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 (V2 format) and finish reason (V2 string)
+     * - `error` - Error occurred
+     *
+     * **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`.
+     * @see https://github.com/SAP/ai-sdk-js/issues/1429 - Enhancement request for rawResponse access
+     *
+     * **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}
+     * @see {@link convertStreamV3ToV2} for stream transformation logic
+     * @see {@link convertStreamPartV3ToV2} for individual stream part conversion
+     * @param options - Streaming options including prompt, tools, and settings
+     * @returns Promise resolving to stream and request metadata
+     * @example
+     * ```typescript
+     * const { stream } = await model.doStream({
+     *   prompt: [
+     *     { role: 'user', content: [{ type: 'text', text: 'Write a story' }] }
+     *   ]
+     * });
+     *
+     * for await (const part of stream) {
+     *   if (part.type === 'text-delta') {
+     *     process.stdout.write(part.delta);
+     *   }
+     * }
+     * ```
+     * @since 1.0.0
+     */
+    doStream(options: LanguageModelV2CallOptions): Promise<{
+        request?: {
+            body?: unknown;
+        };
+        response?: {
+            headers?: SharedV2Headers;
+        };
+        stream: ReadableStream<LanguageModelV2StreamPart>;
+    }>;
+}
+
+/**
+ * SAP AI Provider V2 implementation.
+ *
+ * This module provides a ProviderV2-compatible factory that creates
+ * LanguageModelV2 instances for use with AI SDK 5.x.
+ * @module sap-ai-provider-v2
+ */
+
+/**
+ * Deployment configuration type used by SAP AI SDK.
+ */
+type DeploymentConfig = DeploymentIdConfig | ResourceGroupConfig;
+/**
+ * Configuration settings for the SAP AI Provider V2.
+ *
+ * This interface defines all available options for configuring the SAP AI Core connection
+ * using the official SAP AI SDK. See {@link createSAPAIProvider} for authentication details.
+ * @example
+ * ```typescript
+ * // Using default configuration (auto-detects service binding or env var)
+ * const provider = createSAPAIProvider();
+ *
+ * // With specific resource group
+ * const provider = createSAPAIProvider({
+ *   resourceGroup: 'production'
+ * });
+ *
+ * // With custom destination
+ * const provider = createSAPAIProvider({
+ *   destination: {
+ *     url: 'https://my-ai-core-instance.cfapps.eu10.hana.ondemand.com'
+ *   }
+ * });
+ * ```
+ */
+interface SAPAIProviderSettings {
+    /**
+     * Default model settings applied to every model instance created by this provider.
+     * Per-call settings provided to the model will override these.
+     */
+    defaultSettings?: SAPAISettings;
+    /**
+     * SAP AI Core deployment ID.
+     *
+     * A specific deployment ID to use for orchestration requests.
+     * If not provided, the SDK will resolve the deployment automatically.
+     * @example
+     * ```typescript
+     * deploymentId: 'd65d81e7c077e583'
+     * ```
+     */
+    deploymentId?: string;
+    /**
+     * Custom destination configuration for SAP AI Core.
+     *
+     * Override the default destination detection. Useful for:
+     * - Custom proxy configurations
+     * - Non-standard SAP AI Core setups
+     * - Testing environments
+     * @example
+     * ```typescript
+     * destination: {
+     *   url: 'https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com'
+     * }
+     * ```
+     */
+    destination?: HttpDestinationOrFetchOptions;
+    /**
+     * 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
+     * ```
+     */
+    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;
+}
+/**
+ * SAP AI Provider V2 interface.
+ *
+ * This is the main interface for creating and configuring SAP AI Core models
+ * compatible with AI SDK 5.x (LanguageModelV2 and EmbeddingModelV2).
+ * @example
+ * ```typescript
+ * const provider = createSAPAIProvider({
+ *   resourceGroup: 'default'
+ * });
+ *
+ * // Create a language model instance
+ * const model = provider('gpt-4o', {
+ *   modelParams: {
+ *     temperature: 0.7,
+ *     maxTokens: 1000
+ *   }
+ * });
+ *
+ * // Create an embedding model instance
+ * const embeddingModel = provider.textEmbedding('text-embedding-ada-002');
+ *
+ * // Or use the explicit languageModel or chat method
+ * const chatModel = provider.languageModel('gpt-4o');
+ * ```
+ */
+interface SAPAIProviderV2 {
+    /**
+     * Create a language model instance (V2).
+     * @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 (V2)
+     */
+    (modelId: SAPAIModelId, settings?: SAPAISettings): SAPAILanguageModelV2;
+    /**
+     * Explicit method for creating chat models (V2).
+     *
+     * This method is equivalent to calling languageModel() or 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 (V2)
+     */
+    chat(modelId: SAPAIModelId, settings?: SAPAISettings): SAPAILanguageModelV2;
+    /**
+     * Create an embedding model instance (V2).
+     *
+     * This method creates text embedding models compatible with AI SDK 5.x.
+     * @param modelId - The embedding model identifier (e.g., 'text-embedding-ada-002')
+     * @param settings - Optional embedding model settings
+     * @returns Configured SAP AI embedding model instance (V2)
+     */
+    embedding(modelId: SAPAIEmbeddingModelId, settings?: SAPAIEmbeddingSettings): SAPAIEmbeddingModelV2;
+    /**
+     * Create a language model instance (V2).
+     *
+     * This is the standard method for creating language models.
+     * @param modelId - The SAP AI Core model identifier
+     * @param settings - Optional model configuration settings
+     * @returns Configured SAP AI language model instance (V2)
+     */
+    languageModel(modelId: SAPAIModelId, settings?: SAPAISettings): SAPAILanguageModelV2;
+    /**
+     * Create a text embedding model instance (V2).
+     *
+     * Alias for the embedding() method. Provides compatibility with common provider patterns.
+     * @param modelId - The embedding model identifier
+     * @param settings - Optional embedding model settings
+     * @returns Configured SAP AI embedding model instance (V2)
+     */
+    textEmbeddingModel(modelId: SAPAIEmbeddingModelId, settings?: SAPAIEmbeddingSettings): SAPAIEmbeddingModelV2;
+}
+/**
+ * Creates a SAP AI Core provider instance for use with AI SDK 5.x (LanguageModelV2).
+ *
+ * This is the main entry point for integrating SAP AI Core with AI SDK 5.x.
+ * It uses the official SAP AI SDK (@sap-ai-sdk/orchestration) under the hood,
+ * which handles authentication and API communication automatically.
+ *
+ * **Authentication:**
+ * The SAP AI SDK automatically handles authentication:
+ * 1. On SAP BTP: Uses service binding (VCAP_SERVICES)
+ * 2. Locally: Uses AICORE_SERVICE_KEY environment variable
+ *
+ * **Key Features:**
+ * - Automatic authentication via SAP AI SDK
+ * - Support for all SAP AI Core orchestration models
+ * - Streaming and non-streaming responses
+ * - Tool calling support
+ * - Data masking (DPI)
+ * - Content filtering
+ * @param options - Configuration options for the provider
+ * @returns A configured SAP AI provider (V2)
+ * @example
+ * **Basic Usage (AI SDK 5.x)**
+ * ```typescript
+ * import { createSAPAIProvider } from '@mymediset/sap-ai-provider';
+ * import { generateText } from 'ai'; // SDK 5.x
+ *
+ * const provider = createSAPAIProvider();
+ *
+ * const result = await generateText({
+ *   model: provider('gpt-4o'),
+ *   prompt: 'Hello, world!'
+ * });
+ * ```
+ * @example
+ * **With Resource Group**
+ * ```typescript
+ * const provider = createSAPAIProvider({
+ *   resourceGroup: 'production'
+ * });
+ *
+ * const model = provider('anthropic--claude-3.5-sonnet', {
+ *   modelParams: {
+ *     temperature: 0.3,
+ *     maxTokens: 2000
+ *   }
+ * });
+ * ```
+ * @example
+ * **With Default Settings**
+ * ```typescript
+ * const provider = createSAPAIProvider({
+ *   defaultSettings: {
+ *     modelParams: {
+ *       temperature: 0.7
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function createSAPAIProvider(options?: SAPAIProviderSettings): SAPAIProviderV2;
+/**
+ * Default SAP AI provider instance (V2).
+ *
+ * Uses default configuration with automatic authentication.
+ * Compatible with AI SDK 5.x (LanguageModelV2).
+ * See {@link createSAPAIProvider} for authentication details.
+ * @example
+ * ```typescript
+ * import { sapai } from '@mymediset/sap-ai-provider';
+ * import { generateText } from 'ai'; // SDK 5.x
+ *
+ * const result = await generateText({
+ *   model: sapai('gpt-4o'),
+ *   prompt: 'Hello!'
+ * });
+ * ```
+ */
+declare const sapai: SAPAIProviderV2;
+
+export { type DeploymentConfig, SAPAIEmbeddingModelV2 as SAPAIEmbeddingModel, type SAPAIEmbeddingModelId, type SAPAIEmbeddingProviderOptions, type SAPAIEmbeddingSettings, type SAPAILanguageModelProviderOptions, type SAPAIModelId, type SAPAIProviderV2 as SAPAIProvider, type SAPAIProviderSettings, type SAPAISettings, SAP_AI_PROVIDER_NAME, createSAPAIProvider, sapAIEmbeddingProviderOptions, sapAILanguageModelProviderOptions, sapai };