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

package/README.md

@@ -3,7 +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-interfaces)
+[![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.
 
@@ -28,6 +28,8 @@ A community provider for SAP AI Core that integrates seamlessly with the Vercel
   - [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)
@@ -174,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";
-
-const provider = createSAPAIProvider();
+**Complete example:** [examples/example-generate-text.ts](./examples/example-generate-text.ts)
 
-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
@@ -314,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({
@@ -343,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: [
@@ -372,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:
@@ -391,10 +347,7 @@ const dpiConfig = buildDpiMaskingProvider({
 
 ```typescript
 import "dotenv/config"; // Load environment variables
-import {
-  createSAPAIProvider,
-  buildAzureContentSafetyFilter,
-} from "@mymediset/sap-ai-provider";
+import { createSAPAIProvider, buildAzureContentSafetyFilter } from "@mymediset/sap-ai-provider";
 
 const provider = createSAPAIProvider({
   defaultSettings: {
@@ -412,6 +365,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.
@@ -502,14 +518,16 @@ Error code reference table: [API Reference - HTTP Status Codes](./API_REFERENCE.
 
 The `examples/` directory contains complete, runnable examples demonstrating key features:
 
-| Example                             | Description                 | Key Features                           |
-| ----------------------------------- | --------------------------- | -------------------------------------- |
-| `example-generate-text.ts`          | Basic text generation       | Simple prompts, synchronous generation |
-| `example-simple-chat-completion.ts` | Simple chat conversation    | System messages, user prompts          |
-| `example-chat-completion-tool.ts`   | Tool calling with functions | Weather API tool, function execution   |
-| `example-streaming-chat.ts`         | Streaming responses         | Real-time text generation, SSE         |
-| `example-image-recognition.ts`      | Multi-modal with images     | Vision models, image analysis          |
-| `example-data-masking.ts`           | Data privacy integration    | DPI masking, anonymization             |
+| Example                             | Description                 | Key Features                            |
+| ----------------------------------- | --------------------------- | --------------------------------------- |
+| `example-generate-text.ts`          | Basic text generation       | Simple prompts, synchronous generation  |
+| `example-simple-chat-completion.ts` | Simple chat conversation    | System messages, user prompts           |
+| `example-chat-completion-tool.ts`   | Tool calling with functions | Weather API tool, function execution    |
+| `example-streaming-chat.ts`         | Streaming responses         | Real-time text generation, SSE          |
+| `example-image-recognition.ts`      | Multi-modal with images     | Vision models, image analysis           |
+| `example-data-masking.ts`           | Data privacy integration    | DPI masking, anonymization              |
+| `example-document-grounding.ts`     | Document grounding (RAG)    | Vector store, retrieval-augmented gen   |
+| `example-translation.ts`            | Input/output translation    | Multi-language support, SAP translation |
 
 **Running Examples:**