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

package/README.md

@@ -5,7 +5,10 @@
 [![Vercel AI SDK](https://img.shields.io/badge/Vercel%20AI%20SDK-6.0+-black.svg)](https://sdk.vercel.ai/docs)
 [![Language Model](https://img.shields.io/badge/Language%20Model-V3-green.svg)](https://sdk.vercel.ai/docs/ai-sdk-core/provider-management)
 
-A community provider for SAP AI Core that integrates seamlessly with the Vercel AI SDK. Built on top of the official **@sap-ai-sdk/orchestration** package, this provider enables you to use SAP's enterprise-grade AI models through the familiar Vercel AI SDK interface.
+A community provider for SAP AI Core that integrates seamlessly with the Vercel
+AI SDK. Built on top of the official **@sap-ai-sdk/orchestration** package, this
+provider enables you to use SAP's enterprise-grade AI models through the
+familiar Vercel AI SDK interface.
 
 ## Table of Contents
 
@@ -51,16 +54,19 @@ A community provider for SAP AI Core that integrates seamlessly with the Vercel
 
 ## Features
 
-- 🔐 **Simplified Authentication** - Uses SAP AI SDK's built-in credential handling
+- 🔐 **Simplified Authentication** - Uses SAP AI SDK's built-in credential
+  handling
 - 🎯 **Tool Calling Support** - Full tool/function calling capabilities
-- 🧠 **Reasoning-Safe by Default** - Assistant reasoning parts are not forwarded unless enabled
+- 🧠 **Reasoning-Safe by Default** - Assistant reasoning parts are not forwarded
+  unless enabled
 - 🖼️ **Multi-modal Input** - Support for text and image inputs
 - 📡 **Streaming Support** - Real-time text generation with structured V3 blocks
 - 🔒 **Data Masking** - Built-in SAP DPI integration for privacy
 - 🛡️ **Content Filtering** - Azure Content Safety and Llama Guard support
 - 🔧 **TypeScript Support** - Full type safety and IntelliSense
 - 🎨 **Multiple Models** - Support for GPT-4, Claude, Gemini, Nova, and more
-- ⚡ **Language Model V3** - Latest Vercel AI SDK specification with enhanced streaming
+- ⚡ **Language Model V3** - Latest Vercel AI SDK specification with enhanced
+  streaming
 
 ## Quick Start
 
@@ -95,7 +101,8 @@ try {
 }
 ```
 
-> **Note:** Requires `AICORE_SERVICE_KEY` environment variable. See [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
+> **Note:** Requires `AICORE_SERVICE_KEY` environment variable. See
+> [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
 
 ## Quick Reference
 
@@ -158,11 +165,13 @@ const result = await generateText({
 });
 ```
 
-The `sapai` export provides a convenient default provider instance with automatic configuration from environment variables or service bindings.
+The `sapai` export provides a convenient default provider instance with
+automatic configuration from environment variables or service bindings.
 
 ## Authentication
 
-Authentication is handled automatically by the SAP AI SDK using the `AICORE_SERVICE_KEY` environment variable.
+Authentication is handled automatically by the SAP AI SDK using the
+`AICORE_SERVICE_KEY` environment variable.
 
 **Quick Setup:**
 
@@ -170,13 +179,15 @@ Authentication is handled automatically by the SAP AI SDK using the `AICORE_SERV
 2. Add your SAP AI Core service key JSON to `AICORE_SERVICE_KEY`
 3. Import in code: `import "dotenv/config";`
 
-**For complete setup instructions, SAP BTP deployment, troubleshooting, and advanced scenarios, see the [Environment Setup Guide](./ENVIRONMENT_SETUP.md).**
+**For complete setup instructions, SAP BTP deployment, troubleshooting, and
+advanced scenarios, see the [Environment Setup Guide](./ENVIRONMENT_SETUP.md).**
 
 ## Basic Usage
 
 ### Text Generation
 
-**Complete example:** [examples/example-generate-text.ts](./examples/example-generate-text.ts)
+**Complete example:**
+[examples/example-generate-text.ts](./examples/example-generate-text.ts)
 
 ```typescript
 const result = await generateText({
@@ -190,9 +201,12 @@ console.log(result.text);
 
 ### Chat Conversations
 
-**Complete example:** [examples/example-simple-chat-completion.ts](./examples/example-simple-chat-completion.ts)
+**Complete example:**
+[examples/example-simple-chat-completion.ts](./examples/example-simple-chat-completion.ts)
 
-Note: assistant `reasoning` parts are dropped by default. Set `includeReasoning: true` on the model settings if you explicitly want to forward them.
+Note: assistant `reasoning` parts are dropped by default. Set
+`includeReasoning: true` on the model settings if you explicitly want to forward
+them.
 
 ```typescript
 const result = await generateText({
@@ -211,7 +225,8 @@ const result = await generateText({
 
 ### Streaming Responses
 
-**Complete example:** [examples/example-streaming-chat.ts](./examples/example-streaming-chat.ts)
+**Complete example:**
+[examples/example-streaming-chat.ts](./examples/example-streaming-chat.ts)
 
 ```typescript
 const result = streamText({
@@ -254,20 +269,24 @@ const result = await generateText({
 
 ## Supported Models
 
-This provider supports all models available through SAP AI Core Orchestration service, including:
+This provider supports all models available through SAP AI Core Orchestration
+service, including:
 
 **Popular models:**
 
-- **OpenAI**: gpt-4o, gpt-4o-mini, gpt-4.1, o1, o3 (recommended for multi-tool apps)
+- **OpenAI**: gpt-4o, gpt-4o-mini, gpt-4.1, o1, o3, o4-mini (recommended for
+  multi-tool apps)
 - **Anthropic Claude**: anthropic--claude-3.5-sonnet, anthropic--claude-4-opus
 - **Google Gemini**: gemini-2.5-pro, gemini-2.0-flash
 
 ⚠️ **Important:** Google Gemini models have a 1 tool limit per request.
 
 - **Amazon Nova**: amazon--nova-pro, amazon--nova-lite
-- **Open Source**: mistralai--mistral-large-instruct, meta--llama3.1-70b-instruct
+- **Open Source**: mistralai--mistral-large-instruct,
+  meta--llama3.1-70b-instruct
 
-> **Note:** Model availability depends on your SAP AI Core tenant configuration, region, and subscription.
+> **Note:** Model availability depends on your SAP AI Core tenant configuration,
+> region, and subscription.
 
 **To discover available models in your environment:**
 
@@ -275,18 +294,26 @@ This provider supports all models available through SAP AI Core Orchestration se
 curl "https://<AI_API_URL>/v2/lm/deployments" -H "Authorization: Bearer $TOKEN"
 ```
 
-For complete model details, capabilities comparison, and limitations, see **[API Reference: SAPAIModelId](./API_REFERENCE.md#sapaimodelid)**.
+For complete model details, capabilities comparison, and limitations, see
+**[API Reference: SAPAIModelId](./API_REFERENCE.md#sapaimodelid)**.
 
 ## Advanced Features
 
-The following helper functions are exported by this package for convenient configuration of SAP AI Core features. These builders provide type-safe configuration for data masking, content filtering, grounding, and translation modules.
+The following helper functions are exported by this package for convenient
+configuration of SAP AI Core features. These builders provide type-safe
+configuration for data masking, content filtering, grounding, and translation
+modules.
 
 ### Tool Calling
 
-> **Note on Terminology:** This documentation uses "tool calling" (Vercel AI SDK convention), equivalent to "function calling" in OpenAI documentation. Both terms refer to the same capability of models invoking external functions.
+> **Note on Terminology:** This documentation uses "tool calling" (Vercel AI SDK
+> convention), equivalent to "function calling" in OpenAI documentation. Both
+> terms refer to the same capability of models invoking external functions.
 
-📖 **Complete guide:** [API Reference - Tool Calling](./API_REFERENCE.md#tool-calling-function-calling)  
-**Complete example:** [examples/example-chat-completion-tool.ts](./examples/example-chat-completion-tool.ts)
+📖 **Complete guide:**
+[API Reference - Tool Calling](./API_REFERENCE.md#tool-calling-function-calling)\
+**Complete example:**
+[examples/example-chat-completion-tool.ts](./examples/example-chat-completion-tool.ts)
 
 ```typescript
 const weatherTool = tool({
@@ -305,11 +332,15 @@ const result = await generateText({
 
 **Run it:** `npx tsx examples/example-chat-completion-tool.ts`
 
-⚠️ **Important:** Gemini models support only 1 tool per request. For multi-tool applications, use GPT-4o, Claude, or Amazon Nova models. See [API Reference - Tool Calling](./API_REFERENCE.md#tool-calling-function-calling) for complete model comparison.
+⚠️ **Important:** Gemini models support only 1 tool per request. For multi-tool
+applications, use GPT-4o, Claude, or Amazon Nova models. See
+[API Reference - Tool Calling](./API_REFERENCE.md#tool-calling-function-calling)
+for complete model comparison.
 
 ### Multi-modal Input (Images)
 
-**Complete example:** [examples/example-image-recognition.ts](./examples/example-image-recognition.ts)
+**Complete example:**
+[examples/example-image-recognition.ts](./examples/example-image-recognition.ts)
 
 ```typescript
 const result = await generateText({
@@ -341,13 +372,14 @@ const dpiConfig = buildDpiMaskingProvider({
 });
 ```
 
-**Full documentation:** [API_REFERENCE.md - Data Masking](./API_REFERENCE.md#builddpimaskingproviderconfig)
+**Full documentation:**
+[API_REFERENCE.md - Data Masking](./API_REFERENCE.md#builddpimaskingproviderconfig)
 
 ### Content Filtering
 
 ```typescript
 import "dotenv/config"; // Load environment variables
-import { createSAPAIProvider, buildAzureContentSafetyFilter } from "@mymediset/sap-ai-provider";
+import { buildAzureContentSafetyFilter, createSAPAIProvider } from "@mymediset/sap-ai-provider";
 
 const provider = createSAPAIProvider({
   defaultSettings: {
@@ -365,14 +397,17 @@ const provider = createSAPAIProvider({
 });
 ```
 
-**Full documentation:** [API_REFERENCE.md - Content Filtering](./API_REFERENCE.md#buildazurecontentsafetyfiltertype-config)
+**Full documentation:**
+[API_REFERENCE.md - Content Filtering](./API_REFERENCE.md#buildazurecontentsafetyfiltertype-config)
 
 ### Document Grounding (RAG)
 
 Ground LLM responses in your own documents using vector databases.
 
-**Complete example:** [examples/example-document-grounding.ts](./examples/example-document-grounding.ts)  
-**Complete documentation:** [API Reference - Document Grounding](./API_REFERENCE.md#builddocumentgroundingconfigconfig)
+**Complete example:**
+[examples/example-document-grounding.ts](./examples/example-document-grounding.ts)\
+**Complete documentation:**
+[API Reference - Document Grounding](./API_REFERENCE.md#builddocumentgroundingconfigconfig)
 
 ```typescript
 const provider = createSAPAIProvider({
@@ -402,8 +437,10 @@ const model = provider("gpt-4o");
 
 Automatically translate user queries and model responses.
 
-**Complete example:** [examples/example-translation.ts](./examples/example-translation.ts)  
-**Complete documentation:** [API Reference - Translation](./API_REFERENCE.md#buildtranslationconfigtype-config)
+**Complete example:**
+[examples/example-translation.ts](./examples/example-translation.ts)\
+**Complete documentation:**
+[API Reference - Translation](./API_REFERENCE.md#buildtranslationconfigtype-config)
 
 ```typescript
 const provider = createSAPAIProvider({
@@ -430,7 +467,8 @@ const model = provider("gpt-4o");
 
 ## Configuration Options
 
-The provider and models can be configured with various settings for authentication, model parameters, data masking, content filtering, and more.
+The provider and models can be configured with various settings for
+authentication, model parameters, data masking, content filtering, and more.
 
 **Common Configuration:**
 
@@ -440,11 +478,14 @@ The provider and models can be configured with various settings for authenticati
 - `masking`: SAP Data Privacy Integration (DPI) configuration
 - `filtering`: Content safety filters (Azure Content Safety, Llama Guard)
 
-For complete configuration reference including all available options, types, and examples, see **[API Reference - Configuration](./API_REFERENCE.md#sapaiprovidersettings)**.
+For complete configuration reference including all available options, types, and
+examples, see
+**[API Reference - Configuration](./API_REFERENCE.md#sapaiprovidersettings)**.
 
 ## Error Handling
 
-The provider uses standard Vercel AI SDK error types for consistent error handling.
+The provider uses standard Vercel AI SDK error types for consistent error
+handling.
 
 **Quick Example:**
 
@@ -470,9 +511,12 @@ try {
 
 **Complete reference:**
 
-- **[API Reference - Error Handling](./API_REFERENCE.md#error-handling-examples)** - Complete examples with all error properties
-- **[API Reference - HTTP Status Codes](./API_REFERENCE.md#http-status-code-reference)** - Status code reference table
-- **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Detailed solutions for each error type
+- **[API Reference - Error Handling](./API_REFERENCE.md#error-handling-examples)** -
+  Complete examples with all error properties
+- **[API Reference - HTTP Status Codes](./API_REFERENCE.md#http-status-code-reference)** -
+  Status code reference table
+- **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Detailed solutions for
+  each error type
 
 ## Troubleshooting
 
@@ -481,9 +525,11 @@ try {
 - **Authentication (401)**: Check `AICORE_SERVICE_KEY` or `VCAP_SERVICES`
 - **Model not found (404)**: Confirm tenant/region supports the model ID
 - **Rate limit (429)**: Automatic retry with exponential backoff
-- **Streaming**: Iterate `textStream` correctly; don't mix `generateText` and `streamText`
+- **Streaming**: Iterate `textStream` correctly; don't mix `generateText` and
+  `streamText`
 
-**For comprehensive troubleshooting, see [Troubleshooting Guide](./TROUBLESHOOTING.md)** with detailed solutions for:
+**For comprehensive troubleshooting, see
+[Troubleshooting Guide](./TROUBLESHOOTING.md)** with detailed solutions for:
 
 - [Authentication Failed (401)](./TROUBLESHOOTING.md#problem-authentication-failed-or-401-errors)
 - [Model Not Found (404)](./TROUBLESHOOTING.md#problem-404-modeldeployment-not-found)
@@ -492,31 +538,42 @@ try {
 - [Streaming Issues](./TROUBLESHOOTING.md#streaming-issues)
 - [Tool Calling Problems](./TROUBLESHOOTING.md#tool-calling-issues)
 
-Error code reference table: [API Reference - HTTP Status Codes](./API_REFERENCE.md#http-status-code-reference)
+Error code reference table:
+[API Reference - HTTP Status Codes](./API_REFERENCE.md#http-status-code-reference)
 
 ## Performance
 
 - Prefer streaming (`streamText`) for long outputs to reduce latency and memory.
-- Tune `modelParams` carefully: lower `temperature` for deterministic results; set `maxTokens` to expected response size.
-- Use `defaultSettings` at provider creation for shared knobs across models to avoid per-call overhead.
-- Avoid unnecessary history: keep `messages` concise to reduce prompt size and cost.
+- Tune `modelParams` carefully: lower `temperature` for deterministic results;
+  set `maxTokens` to expected response size.
+- Use `defaultSettings` at provider creation for shared knobs across models to
+  avoid per-call overhead.
+- Avoid unnecessary history: keep `messages` concise to reduce prompt size and
+  cost.
 
 ## Security
 
-- Do not commit `.env` or credentials; use environment variables and secrets managers.
-- Treat `AICORE_SERVICE_KEY` as sensitive; avoid logging it or including in crash reports.
-- Mask PII with DPI: configure `masking.masking_providers` using `buildDpiMaskingProvider()`.
+- Do not commit `.env` or credentials; use environment variables and secrets
+  managers.
+- Treat `AICORE_SERVICE_KEY` as sensitive; avoid logging it or including in
+  crash reports.
+- Mask PII with DPI: configure `masking.masking_providers` using
+  `buildDpiMaskingProvider()`.
 - Validate and sanitize tool outputs before executing any side effects.
 
 ## Debug Mode
 
-- Use the curl guide `CURL_API_TESTING_GUIDE.md` to diagnose raw API behavior independent of the SDK.
-- Log request IDs from `error.responseBody` (parse JSON for `request_id`) to correlate with backend traces.
-- Temporarily enable verbose logging in your app around provider calls; redact secrets.
+- Use the curl guide `CURL_API_TESTING_GUIDE.md` to diagnose raw API behavior
+  independent of the SDK.
+- Log request IDs from `error.responseBody` (parse JSON for `request_id`) to
+  correlate with backend traces.
+- Temporarily enable verbose logging in your app around provider calls; redact
+  secrets.
 
 ## Examples
 
-The `examples/` directory contains complete, runnable examples demonstrating key features:
+The `examples/` directory contains complete, runnable examples demonstrating key
+features:
 
 | Example                             | Description                 | Key Features                            |
 | ----------------------------------- | --------------------------- | --------------------------------------- |
@@ -535,30 +592,41 @@ The `examples/` directory contains complete, runnable examples demonstrating key
 npx tsx examples/example-generate-text.ts
 ```
 
-> **Note:** Examples require `AICORE_SERVICE_KEY` environment variable. See [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
+> **Note:** Examples require `AICORE_SERVICE_KEY` environment variable. See
+> [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
 
 ## Migration Guides
 
 ### Upgrading from v3.x to v4.x
 
-Version 4.0 migrates from **LanguageModelV2** to **LanguageModelV3** specification (AI SDK 6.0+). **See the [Migration Guide](./MIGRATION_GUIDE.md#version-3x-to-4x-breaking-changes) for complete upgrade instructions.**
+Version 4.0 migrates from **LanguageModelV2** to **LanguageModelV3**
+specification (AI SDK 6.0+). **See the
+[Migration Guide](./MIGRATION_GUIDE.md#version-3x-to-4x-breaking-changes) for
+complete upgrade instructions.**
 
 **Key changes:**
 
-- **Finish Reason**: Changed from string to object (`result.finishReason.unified`)
-- **Usage Structure**: Nested format with detailed token breakdown (`result.usage.inputTokens.total`)
-- **Stream Events**: Structured blocks (`text-start`, `text-delta`, `text-end`) instead of simple deltas
+- **Finish Reason**: Changed from string to object
+  (`result.finishReason.unified`)
+- **Usage Structure**: Nested format with detailed token breakdown
+  (`result.usage.inputTokens.total`)
+- **Stream Events**: Structured blocks (`text-start`, `text-delta`, `text-end`)
+  instead of simple deltas
 - **Warning Types**: Updated format with `feature` field for categorization
 
 **Impact by user type:**
 
-- High-level API users (`generateText`/`streamText`): ✅ Minimal impact (likely no changes)
-- Direct provider users: ⚠️ Update type imports (`LanguageModelV2` → `LanguageModelV3`)
+- High-level API users (`generateText`/`streamText`): ✅ Minimal impact (likely
+  no changes)
+- Direct provider users: ⚠️ Update type imports (`LanguageModelV2` →
+  `LanguageModelV3`)
 - Custom stream parsers: ⚠️ Update parsing logic for V3 structure
 
 ### Upgrading from v2.x to v3.x
 
-Version 3.0 standardizes error handling to use Vercel AI SDK native error types. **See the [Migration Guide](./MIGRATION_GUIDE.md#v2x--v30) for complete upgrade instructions.**
+Version 3.0 standardizes error handling to use Vercel AI SDK native error types.
+**See the [Migration Guide](./MIGRATION_GUIDE.md#v2x--v30) for complete upgrade
+instructions.**
 
 **Key changes:**
 
@@ -568,7 +636,9 @@ Version 3.0 standardizes error handling to use Vercel AI SDK native error types.
 
 ### Upgrading from v1.x to v2.x
 
-Version 2.0 uses the official SAP AI SDK. **See the [Migration Guide](./MIGRATION_GUIDE.md#v1x--v20) for complete upgrade instructions.**
+Version 2.0 uses the official SAP AI SDK. **See the
+[Migration Guide](./MIGRATION_GUIDE.md#v1x--v20) for complete upgrade
+instructions.**
 
 **Key changes:**
 
@@ -576,37 +646,48 @@ Version 2.0 uses the official SAP AI SDK. **See the [Migration Guide](./MIGRATIO
 - Synchronous provider creation: `createSAPAIProvider()` (no await)
 - Helper functions from SAP AI SDK
 
-**For detailed migration instructions with code examples, see the [complete Migration Guide](./MIGRATION_GUIDE.md).**
+**For detailed migration instructions with code examples, see the
+[complete Migration Guide](./MIGRATION_GUIDE.md).**
 
 ## Important Note
 
-> **Third-Party Provider**: This SAP AI Core provider (`@mymediset/sap-ai-provider`) is developed and maintained by mymediset, not by SAP SE. While it uses the official SAP AI SDK and integrates with SAP AI Core services, it is not an official SAP product.
+> **Third-Party Provider**: This SAP AI Core provider
+> (`@mymediset/sap-ai-provider`) is developed and maintained by mymediset, not
+> by SAP SE. While it uses the official SAP AI SDK and integrates with SAP AI
+> Core services, it is not an official SAP product.
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
+We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md)
+for details.
 
 ## Resources
 
 ### Documentation
 
-- [Migration Guide](./MIGRATION_GUIDE.md) - Version upgrade instructions (v1.x → v2.x → v3.x → v4.x)
-- [API Reference](./API_REFERENCE.md) - Complete API documentation with all types and functions
-- [Environment Setup](./ENVIRONMENT_SETUP.md) - Authentication and configuration setup
+- [Migration Guide](./MIGRATION_GUIDE.md) - Version upgrade instructions (v1.x →
+  v2.x → v3.x → v4.x)
+- [API Reference](./API_REFERENCE.md) - Complete API documentation with all
+  types and functions
+- [Environment Setup](./ENVIRONMENT_SETUP.md) - Authentication and configuration
+  setup
 - [Troubleshooting](./TROUBLESHOOTING.md) - Common issues and solutions
-- [Architecture](./ARCHITECTURE.md) - Internal architecture, design decisions, and request flows
-- [curl API Testing](./CURL_API_TESTING_GUIDE.md) - Direct API testing for debugging
+- [Architecture](./ARCHITECTURE.md) - Internal architecture, design decisions,
+  and request flows
+- [curl API Testing](./CURL_API_TESTING_GUIDE.md) - Direct API testing for
+  debugging
 
 ### Community
 
-- 🐛 [Issue Tracker](https://github.com/BITASIA/sap-ai-provider/issues) - Report bugs and request features
-- 💬 [Discussions](https://github.com/BITASIA/sap-ai-provider/discussions) - Ask questions and share ideas
+- 🐛 [Issue Tracker](https://github.com/BITASIA/sap-ai-provider/issues) - Report
+  bugs, request features, and ask questions
 
 ### Related Projects
 
 - [Vercel AI SDK](https://sdk.vercel.ai/) - The AI SDK this provider extends
 - [SAP AI SDK](https://sap.github.io/ai-sdk/) - Official SAP Cloud SDK for AI
-- [SAP AI Core Documentation](https://help.sap.com/docs/ai-core) - Official SAP AI Core docs
+- [SAP AI Core Documentation](https://help.sap.com/docs/ai-core) - Official SAP
+  AI Core docs
 
 ## License