@jerome-benoit/sap-ai-provider 3.0.0-rc.4 → 3.0.0-rc.6

package/README.md

@@ -2,37 +2,15 @@
 
 [![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)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![Vercel AI SDK](https://img.shields.io/badge/Vercel%20AI%20SDK-6.0+-black.svg)](https://sdk.vercel.ai/docs)
 
 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.
 
-> **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.
-
-## ⚠️ Breaking Changes in v3.0.0-rc.1
-
-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:**
-
-- `SAPAIError` removed → Use `APICallError` from `@ai-sdk/provider`
-- Error properties: `error.code` → `error.statusCode`
-- Automatic retries for rate limits (429) and server errors (5xx)
-
-## ⚠️ Breaking Changes in v2.0
-
-Version 2.0 uses the official SAP AI SDK. **See the [Migration Guide](./MIGRATION_GUIDE.md#v1x--v20) for complete upgrade instructions.**
-
-**Key changes:**
-
-- Authentication via `AICORE_SERVICE_KEY` environment variable
-- Synchronous provider creation: `createSAPAIProvider()` (no await)
-- Helper functions from SAP AI SDK
-
 ## Table of Contents
 
 - [Features](#features)
 - [Quick Start](#quick-start)
+- [Quick Reference](#quick-reference)
 - [Installation](#installation)
 - [Authentication](#authentication)
 - [Basic Usage](#basic-usage)
@@ -41,7 +19,7 @@ Version 2.0 uses the official SAP AI SDK. **See the [Migration Guide](./MIGRATIO
 - [Configuration Options](#configuration-options)
 - [Error Handling](#error-handling)
 - [Examples](#examples)
-- [Migration Guides (v1→v2, v2→v3)](./MIGRATION_GUIDE.md)
+- [Migration Guides](#migration-guides)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -67,21 +45,43 @@ npm install @mymediset/sap-ai-provider ai
 import "dotenv/config"; // Load environment variables
 import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
 import { generateText } from "ai";
+import { APICallError } from "@ai-sdk/provider";
 
 // Create provider (authentication via AICORE_SERVICE_KEY env var)
 const provider = createSAPAIProvider();
 
-// Generate text with gpt-4o
-const result = await generateText({
-  model: provider("gpt-4o"),
-  prompt: "Explain quantum computing in simple terms.",
-});
+try {
+  // Generate text with gpt-4o
+  const result = await generateText({
+    model: provider("gpt-4o"),
+    prompt: "Explain quantum computing in simple terms.",
+  });
 
-console.log(result.text);
+  console.log(result.text);
+} catch (error) {
+  if (error instanceof APICallError) {
+    console.error("SAP AI Core API error:", error.message);
+    console.error("Status:", error.statusCode);
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
 ```
 
-> **Setup:** Create a `.env` file with your `AICORE_SERVICE_KEY`. You can copy from `.env.example`: `cp .env.example .env`  
-> **Full Setup Guide:** See [ENVIRONMENT_SETUP.md](./ENVIRONMENT_SETUP.md) for detailed authentication configuration.
+> **Note:** Requires `AICORE_SERVICE_KEY` environment variable. See [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
+
+## Quick Reference
+
+| Task                | Code Pattern                                          | Documentation                                                 |
+| ------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
+| **Install**         | `npm install @mymediset/sap-ai-provider ai`           | [Installation](#installation)                                 |
+| **Auth Setup**      | Add `AICORE_SERVICE_KEY` to `.env`                    | [Environment Setup](./ENVIRONMENT_SETUP.md)                   |
+| **Create Provider** | `createSAPAIProvider()` or use `sapai`                | [Provider Creation](#provider-creation)                       |
+| **Text Generation** | `generateText({ model: provider("gpt-4o"), prompt })` | [Basic Usage](#text-generation)                               |
+| **Streaming**       | `streamText({ model: provider("gpt-4o"), prompt })`   | [Streaming](#streaming-responses)                             |
+| **Tool Calling**    | `generateText({ tools: { myTool: tool({...}) } })`    | [Tool Calling](#tool-calling)                                 |
+| **Error Handling**  | `catch (error instanceof APICallError)`               | [API Reference](./API_REFERENCE.md#error-handling--reference) |
+| **Choose Model**    | See 80+ models (GPT, Claude, Gemini, Llama)           | [Models](./API_REFERENCE.md#models)                           |
 
 ## Installation
 
@@ -108,6 +108,7 @@ You can create an SAP AI provider in two ways:
 ### Option 1: Factory Function (Recommended for Custom Configuration)
 
 ```typescript
+import "dotenv/config"; // Load environment variables
 import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
 
 const provider = createSAPAIProvider({
@@ -119,6 +120,7 @@ const provider = createSAPAIProvider({
 ### Option 2: Default Instance (Quick Start)
 
 ```typescript
+import "dotenv/config"; // Load environment variables
 import { sapai } from "@mymediset/sap-ai-provider";
 import { generateText } from "ai";
 
@@ -151,15 +153,23 @@ Authentication is handled automatically by the SAP AI SDK using the `AICORE_SERV
 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();
 
-const result = await generateText({
-  model: provider("gpt-4o"),
-  prompt: "Write a short story about a robot learning to paint.",
-});
+try {
+  const result = await generateText({
+    model: provider("gpt-4o"),
+    prompt: "Write a short story about a robot learning to paint.",
+  });
 
-console.log(result.text);
+  console.log(result.text);
+} catch (error) {
+  if (error instanceof APICallError) {
+    console.error("API error:", error.message, "- Status:", error.statusCode);
+  }
+  throw error;
+}
 ```
 
 ### Chat Conversations
@@ -170,19 +180,27 @@ Note: assistant `reasoning` parts are dropped by default. Set `includeReasoning:
 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();
 
-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?",
-    },
-  ],
-});
+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;
+}
 ```
 
 ### Streaming Responses
@@ -191,16 +209,24 @@ const result = await generateText({
 import "dotenv/config"; // Load environment variables
 import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
 import { streamText } from "ai";
+import { APICallError } from "@ai-sdk/provider";
 
 const provider = createSAPAIProvider();
 
-const result = streamText({
-  model: provider("gpt-4o"),
-  prompt: "Explain machine learning concepts.",
-});
+try {
+  const result = streamText({
+    model: provider("gpt-4o"),
+    prompt: "Explain machine learning concepts.",
+  });
 
-for await (const delta of result.textStream) {
-  process.stdout.write(delta);
+  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;
 }
 ```
 
@@ -238,11 +264,14 @@ This provider supports all models available through SAP AI Core Orchestration se
 
 - **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
-- **Google Gemini**: gemini-2.5-pro, gemini-2.0-flash (⚠️ 1 tool limit)
+- **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
 
-**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:**
 
@@ -258,6 +287,10 @@ The following helper functions are exported by this package for convenient confi
 
 ### 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.
+
+📖 **Complete guide:** [API Reference - Tool Calling](./API_REFERENCE.md#tool-calling-function-calling)
+
 ```typescript
 import "dotenv/config"; // Load environment variables
 import { createSAPAIProvider } from "@mymediset/sap-ai-provider";
@@ -289,7 +322,7 @@ const result = await generateText({
 console.log(result.text);
 ```
 
-> Known limitations: Gemini models currently support only one function tool per request. For multiple tools, use OpenAI models (e.g., `gpt-4o`) or consolidate tools.
+⚠️ **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)
 
@@ -459,9 +492,31 @@ 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 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.**
+
+**Key changes:**
+
+- `SAPAIError` removed → Use `APICallError` from `@ai-sdk/provider`
+- Error properties: `error.code` → `error.statusCode`
+- Automatic retries for rate limits (429) and server errors (5xx)
+
+### 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.**
+
+**Key changes:**
+
+- Authentication via `AICORE_SERVICE_KEY` environment variable
+- Synchronous provider creation: `createSAPAIProvider()` (no await)
+- Helper functions from SAP AI SDK
 
-**Upgrading from v1 or v2?** See the [Migration Guide](./MIGRATION_GUIDE.md) for detailed instructions (v1→v2, v2→v3).
+**For detailed migration instructions with code examples, see the [complete Migration Guide](./MIGRATION_GUIDE.md).**
 
 ## Important Note
 

package/dist/index.cjs

@@ -29737,16 +29737,17 @@ var require_dist = __commonJS({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  OrchestrationClient: () => import_orchestration4.OrchestrationClient,
-  OrchestrationResponse: () => import_orchestration3.OrchestrationResponse,
-  OrchestrationStreamChunkResponse: () => import_orchestration3.OrchestrationStreamChunkResponse,
-  OrchestrationStreamResponse: () => import_orchestration3.OrchestrationStreamResponse,
+  OrchestrationClient: () => import_orchestration5.OrchestrationClient,
+  OrchestrationResponse: () => import_orchestration4.OrchestrationResponse,
+  OrchestrationStreamChunkResponse: () => import_orchestration4.OrchestrationStreamChunkResponse,
+  OrchestrationStreamResponse: () => import_orchestration4.OrchestrationStreamResponse,
   buildAzureContentSafetyFilter: () => import_orchestration2.buildAzureContentSafetyFilter,
   buildDocumentGroundingConfig: () => import_orchestration2.buildDocumentGroundingConfig,
   buildDpiMaskingProvider: () => import_orchestration2.buildDpiMaskingProvider,
   buildLlamaGuard38BFilter: () => import_orchestration2.buildLlamaGuard38BFilter,
   buildTranslationConfig: () => import_orchestration2.buildTranslationConfig,
   createSAPAIProvider: () => createSAPAIProvider,
+  isConfigReference: () => import_orchestration3.isConfigReference,
   sapai: () => sapai
 });
 module.exports = __toCommonJS(index_exports);
@@ -30909,11 +30910,14 @@ var sapai = createSAPAIProvider();
 // src/sap-ai-chat-settings.ts
 var import_orchestration2 = require("@sap-ai-sdk/orchestration");
 
-// src/types/completion-response.ts
+// src/types/completion-request.ts
 var import_orchestration3 = require("@sap-ai-sdk/orchestration");
 
-// src/index.ts
+// src/types/completion-response.ts
 var import_orchestration4 = require("@sap-ai-sdk/orchestration");
+
+// src/index.ts
+var import_orchestration5 = require("@sap-ai-sdk/orchestration");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   OrchestrationClient,
@@ -30926,6 +30930,7 @@ var import_orchestration4 = require("@sap-ai-sdk/orchestration");
   buildLlamaGuard38BFilter,
   buildTranslationConfig,
   createSAPAIProvider,
+  isConfigReference,
   sapai
 });
 /*! Bundled license information: