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

package/README.md

@@ -3,6 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@mymediset/sap-ai-provider/latest?label=npm&color=blue)](https://www.npmjs.com/package/@mymediset/sap-ai-provider)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![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.
 
@@ -12,15 +13,40 @@ A community provider for SAP AI Core that integrates seamlessly with the Vercel
 - [Quick Start](#quick-start)
 - [Quick Reference](#quick-reference)
 - [Installation](#installation)
+- [Provider Creation](#provider-creation)
+  - [Option 1: Factory Function (Recommended for Custom Configuration)](#option-1-factory-function-recommended-for-custom-configuration)
+  - [Option 2: Default Instance (Quick Start)](#option-2-default-instance-quick-start)
 - [Authentication](#authentication)
 - [Basic Usage](#basic-usage)
+  - [Text Generation](#text-generation)
+  - [Chat Conversations](#chat-conversations)
+  - [Streaming Responses](#streaming-responses)
+  - [Model Configuration](#model-configuration)
 - [Supported Models](#supported-models)
 - [Advanced Features](#advanced-features)
+  - [Tool Calling](#tool-calling)
+  - [Multi-modal Input (Images)](#multi-modal-input-images)
+  - [Data Masking (SAP DPI)](#data-masking-sap-dpi)
+  - [Content Filtering](#content-filtering)
+  - [Document Grounding (RAG)](#document-grounding-rag)
+  - [Translation](#translation)
 - [Configuration Options](#configuration-options)
 - [Error Handling](#error-handling)
+- [Troubleshooting](#troubleshooting)
+- [Performance](#performance)
+- [Security](#security)
+- [Debug Mode](#debug-mode)
 - [Examples](#examples)
 - [Migration Guides](#migration-guides)
+  - [Upgrading from v3.x to v4.x](#upgrading-from-v3x-to-v4x)
+  - [Upgrading from v2.x to v3.x](#upgrading-from-v2x-to-v3x)
+  - [Upgrading from v1.x to v2.x](#upgrading-from-v1x-to-v2x)
+- [Important Note](#important-note)
 - [Contributing](#contributing)
+- [Resources](#resources)
+  - [Documentation](#documentation)
+  - [Community](#community)
+  - [Related Projects](#related-projects)
 - [License](#license)
 
 ## Features
@@ -29,11 +55,12 @@ A community provider for SAP AI Core that integrates seamlessly with the Vercel
 - 🎯 **Tool Calling Support** - Full tool/function calling capabilities
 - 🧠 **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
+- 📡 **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
 
 ## Quick Start
 
@@ -149,87 +176,56 @@ Authentication is handled automatically by the SAP AI SDK using the `AICORE_SERV
 
 ### Text Generation
 
-```typescript
-import "dotenv/config"; // Load environment variables
-import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
-import { generateText } from "ai";
-import { APICallError } from "@ai-sdk/provider";
+**Complete example:** [examples/example-generate-text.ts](./examples/example-generate-text.ts)
 
-const provider = createSAPAIProvider();
-
-try {
-  const result = await generateText({
-    model: provider("gpt-4o"),
-    prompt: "Write a short story about a robot learning to paint.",
-  });
-
-  console.log(result.text);
-} catch (error) {
-  if (error instanceof APICallError) {
-    console.error("API error:", error.message, "- Status:", error.statusCode);
-  }
-  throw error;
-}
+```typescript
+const result = await generateText({
+  model: provider("gpt-4o"),
+  prompt: "Write a short story about a robot learning to paint.",
+});
+console.log(result.text);
 ```
 
+**Run it:** `npx tsx examples/example-generate-text.ts`
+
 ### Chat Conversations
 
+**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.
 
 ```typescript
-import "dotenv/config"; // Load environment variables
-import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
-import { generateText } from "ai";
-import { APICallError } from "@ai-sdk/provider";
-
-const provider = createSAPAIProvider();
-
-try {
-  const result = await generateText({
-    model: provider("anthropic--claude-3.5-sonnet"),
-    messages: [
-      { role: "system", content: "You are a helpful coding assistant." },
-      {
-        role: "user",
-        content: "How do I implement binary search in TypeScript?",
-      },
-    ],
-  });
-} catch (error) {
-  if (error instanceof APICallError) {
-    console.error("API error:", error.message, "- Status:", error.statusCode);
-  }
-  throw error;
-}
+const result = await generateText({
+  model: provider("anthropic--claude-3.5-sonnet"),
+  messages: [
+    { role: "system", content: "You are a helpful coding assistant." },
+    {
+      role: "user",
+      content: "How do I implement binary search in TypeScript?",
+    },
+  ],
+});
 ```
 
-### Streaming Responses
+**Run it:** `npx tsx examples/example-simple-chat-completion.ts`
 
-```typescript
-import "dotenv/config"; // Load environment variables
-import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
-import { streamText } from "ai";
-import { APICallError } from "@ai-sdk/provider";
+### Streaming Responses
 
-const provider = createSAPAIProvider();
+**Complete example:** [examples/example-streaming-chat.ts](./examples/example-streaming-chat.ts)
 
-try {
-  const result = streamText({
-    model: provider("gpt-4o"),
-    prompt: "Explain machine learning concepts.",
-  });
+```typescript
+const result = streamText({
+  model: provider("gpt-4o"),
+  prompt: "Explain machine learning concepts.",
+});
 
-  for await (const delta of result.textStream) {
-    process.stdout.write(delta);
-  }
-} catch (error) {
-  if (error instanceof APICallError) {
-    console.error("API error:", error.message, "- Status:", error.statusCode);
-  }
-  throw error;
+for await (const delta of result.textStream) {
+  process.stdout.write(delta);
 }
 ```
 
+**Run it:** `npx tsx examples/example-streaming-chat.ts`
+
 ### Model Configuration
 
 ```typescript
@@ -263,13 +259,13 @@ This provider supports all models available through SAP AI Core Orchestration se
 **Popular models:**
 
 - **OpenAI**: gpt-4o, gpt-4o-mini, gpt-4.1, o1, o3 (recommended for multi-tool apps)
-- **Anthropic Claude**: claude-3.5-sonnet, claude-4-opus
+- **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**: nova-pro, nova-lite
-- **Open Source**: mistralai-mistral-large, llama3.1-70b
+- **Amazon Nova**: amazon--nova-pro, amazon--nova-lite
+- **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.
 
@@ -289,27 +285,14 @@ The following helper functions are exported by this package for convenient confi
 
 > **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 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
-import "dotenv/config"; // Load environment variables
-import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
-import { generateText, tool } from "ai";
-import { z } from "zod";
-
-const provider = createSAPAIProvider();
-
-const weatherSchema = z.object({
-  location: z.string(),
-});
-
 const weatherTool = tool({
   description: "Get weather for a location",
-  inputSchema: weatherSchema,
-  execute: (args: z.infer<typeof weatherSchema>) => {
-    const { location } = args;
-    return `Weather in ${location}: sunny, 72°F`;
-  },
+  inputSchema: z.object({ location: z.string() }),
+  execute: (args) => `Weather in ${args.location}: sunny, 72°F`,
 });
 
 const result = await generateText({
@@ -318,21 +301,17 @@ const result = await generateText({
   tools: { getWeather: weatherTool },
   maxSteps: 3,
 });
-
-console.log(result.text);
 ```
 
+**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.
 
 ### Multi-modal Input (Images)
 
-```typescript
-import "dotenv/config"; // Load environment variables
-import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
-import { generateText } from "ai";
-
-const provider = createSAPAIProvider();
+**Complete example:** [examples/example-image-recognition.ts](./examples/example-image-recognition.ts)
 
+```typescript
 const result = await generateText({
   model: provider("gpt-4o"),
   messages: [
@@ -347,6 +326,8 @@ const result = await generateText({
 });
 ```
 
+**Run it:** `npx tsx examples/example-image-recognition.ts`
+
 ### Data Masking (SAP DPI)
 
 Use SAP's Data Privacy Integration to mask sensitive data:
@@ -387,6 +368,69 @@ const provider = createSAPAIProvider({
 });
 ```
 
+**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)
+
+```typescript
+const provider = createSAPAIProvider({
+  defaultSettings: {
+    grounding: buildDocumentGroundingConfig({
+      filters: [
+        {
+          id: "vector-store-1", // Your vector database ID
+          data_repositories: ["*"], // Search all repositories
+        },
+      ],
+      placeholders: {
+        input: ["?question"],
+        output: "groundingOutput",
+      },
+    }),
+  },
+});
+
+// Queries are now grounded in your documents
+const model = provider("gpt-4o");
+```
+
+**Run it:** `npx tsx examples/example-document-grounding.ts`
+
+### Translation
+
+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)
+
+```typescript
+const provider = createSAPAIProvider({
+  defaultSettings: {
+    translation: {
+      // Translate user input from German to English
+      input: buildTranslationConfig("input", {
+        sourceLanguage: "de",
+        targetLanguage: "en",
+      }),
+      // Translate model output from English to German
+      output: buildTranslationConfig("output", {
+        targetLanguage: "de",
+      }),
+    },
+  },
+});
+
+// Model handles German input/output automatically
+const model = provider("gpt-4o");
+```
+
+**Run it:** `npx tsx examples/example-translation.ts`
+
 ## Configuration Options
 
 The provider and models can be configured with various settings for authentication, model parameters, data masking, content filtering, and more.
@@ -496,6 +540,23 @@ npx tsx examples/example-generate-text.ts
 
 ## 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.**
+
+**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
+- **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`)
+- 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.**
@@ -526,34 +587,28 @@ Version 2.0 uses the official SAP AI SDK. **See the [Migration Guide](./MIGRATIO
 
 We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
 
-## License
-
-Apache License 2.0 - see [LICENSE](./LICENSE.md) for details.
-
-## Support
-
-- 📖 [Documentation](https://github.com/BITASIA/sap-ai-provider)
-- 🐛 [Issue Tracker](https://github.com/BITASIA/sap-ai-provider/issues)
-
-## Documentation
-
-### Guides
-
-- [Environment Setup](./ENVIRONMENT_SETUP.md) - Authentication and configuration setup
-- [Migration Guide](./MIGRATION_GUIDE.md) - Upgrading from v1.x to v2.x with step-by-step instructions
-- [curl API Testing](./CURL_API_TESTING_GUIDE.md) - Direct API testing for debugging
+## Resources
 
-### Reference
+### 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
+- [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
 
-### Contributing
+### Community
 
-- [Contributing Guide](./CONTRIBUTING.md) - How to contribute to this project
+- 🐛 [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
 
-## Related
+### 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
+
+## License
+
+Apache License 2.0 - see [LICENSE](./LICENSE.md) for details.