@jerome-benoit/sap-ai-provider-v2 5.0.0 → 5.0.2

package/README.md

@@ -46,6 +46,7 @@ SAP's enterprise-grade AI models through the familiar Vercel AI SDK interface.
 - [Debug Mode](#debug-mode)
 - [Examples](#examples)
 - [Migration Guides](#migration-guides)
+  - [Upgrading from v4.x to v5.x](#upgrading-from-v4x-to-v5x)
   - [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)
@@ -82,7 +83,7 @@ SAP's enterprise-grade AI models through the familiar Vercel AI SDK interface.
 ## Quick Start
 
 ```bash
-npm install @jerome-benoit/sap-ai-provider ai@^6
+npm install @jerome-benoit/sap-ai-provider ai@^6 dotenv
 ```
 
 ```typescript
@@ -103,16 +104,17 @@ try {
 
   console.log(result.text);
 } catch (error) {
-  if (error instanceof APICallError) {
-    console.error("SAP AI Core API error:", error.message);
-    console.error("Status:", error.statusCode);
+  process.exitCode = 1;
+  if (APICallError.isInstance(error)) {
+    console.error("SAP AI Core API error:", error.statusCode, error.name);
   } else {
-    console.error("Unexpected error:", error);
+    console.error("Unexpected error:", error instanceof Error ? error.name : "Unknown error");
   }
 }
 ```
 
-> **Note:** Requires `AICORE_SERVICE_KEY` environment variable. See
+> **Note:** For local service-key setup, set `AICORE_SERVICE_KEY`. SAP BTP service
+> bindings and custom destinations are alternatives. See
 > [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
 
 ## Quick Reference
@@ -125,8 +127,8 @@ try {
 | **Text Generation** | `generateText({ model: provider("gpt-4.1"), prompt })`           | [Basic Usage](#text-generation)                               |
 | **Streaming**       | `streamText({ model: provider("gpt-4.1"), 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)                           |
+| **Error Handling**  | `if (APICallError.isInstance(error)) { /* handle error */ }`     | [API Reference](./API_REFERENCE.md#error-handling--reference) |
+| **Choose Model**    | Discover models available in your tenant                         | [Models](./API_REFERENCE.md#models)                           |
 | **Embeddings**      | `embed({ model: provider.embedding("text-embedding-3-small") })` | [Embeddings](#embeddings)                                     |
 
 ## Installation
@@ -134,11 +136,20 @@ try {
 **Requirements:** Node.js 22.12+. The provider entrypoint must match the installed
 AI SDK major.
 
-| AI SDK | Install                                            | Provider import                     |
-| ------ | -------------------------------------------------- | ----------------------------------- |
-| 7      | `npm install @jerome-benoit/sap-ai-provider ai@^7` | `@jerome-benoit/sap-ai-provider/v4` |
-| 6      | `npm install @jerome-benoit/sap-ai-provider ai@^6` | `@jerome-benoit/sap-ai-provider`    |
-| 5      | `npm install @jerome-benoit/sap-ai-provider ai@^5` | `@jerome-benoit/sap-ai-provider/v2` |
+The published package targets Node.js. Its ESM output uses Node
+`module.createRequire`, and the SAP SDK dependency chain relies on Node APIs.
+The source-level Edge test suite does not establish deployability to pure Edge
+runtimes such as Cloudflare Workers; use a Node.js server runtime for deployment.
+
+| AI SDK | Install                                            | Provider import                                                         |
+| ------ | -------------------------------------------------- | ----------------------------------------------------------------------- |
+| 7      | `npm install @jerome-benoit/sap-ai-provider ai@^7` | `@jerome-benoit/sap-ai-provider/v4`                                     |
+| 6      | `npm install @jerome-benoit/sap-ai-provider ai@^6` | `@jerome-benoit/sap-ai-provider` or `@jerome-benoit/sap-ai-provider/v3` |
+| 5      | `npm install @jerome-benoit/sap-ai-provider ai@^5` | `@jerome-benoit/sap-ai-provider/v2`                                     |
+
+`/v3` is an explicit alias for the AI SDK 6 root entrypoint. Both resolve to
+the same runtime modules and TypeScript declarations, including the same `sapai`
+instance within each module format; existing root imports remain valid.
 
 The Quick Start and inline snippets on this page use AI SDK 6 with the root V3
 entrypoint. The runnable files in `examples/` use the repository's installed
@@ -269,7 +280,7 @@ The provider is callable and also exposes explicit methods:
 const chatModel = provider("gpt-4.1");
 
 // Explicit method syntax
-const chatModel = provider.chat("gpt-4.1");
+const explicitChatModel = provider.chat("gpt-4.1");
 const embeddingModel = provider.embedding("text-embedding-3-small");
 ```
 
@@ -350,24 +361,31 @@ import { streamText } from "ai";
 import { APICallError } from "@ai-sdk/provider";
 
 try {
+  let streamError: unknown;
   const result = streamText({
     model: provider("gpt-4.1"),
     prompt: "Explain machine learning concepts.",
+    onError({ error }) {
+      streamError = error;
+    },
   });
 
   for await (const delta of result.textStream) {
     process.stdout.write(delta);
   }
 
-  // Await final result to catch any errors that occurred during streaming
-  const finalResult = await result;
-  console.log("\n\nUsage:", finalResult.usage);
+  // textStream does not throw stream errors; preserve the original API error.
+  if (streamError !== undefined) throw streamError;
+
+  // streamText returns a result object; its usage property is a promise.
+  console.log("\n\nUsage:", await result.usage);
 } catch (error) {
-  if (error instanceof APICallError) {
-    console.error("API Error:", error.message);
-    // See Error Handling section for complete error type reference
+  process.exitCode = 1;
+  if (APICallError.isInstance(error)) {
+    console.error("API error:", error.statusCode, error.name);
+  } else {
+    console.error("Streaming failed:", error instanceof Error ? error.name : "Unknown error");
   }
-  throw error;
 }
 ```
 
@@ -495,7 +513,7 @@ const result = await generateText({
 
 ⚠️ **Model Limitations:** Some models have tool calling restrictions. See
 [API Reference - Model-Specific Tool Limitations](./API_REFERENCE.md#model-specific-tool-limitations)
-for the complete comparison table.
+for upstream support documentation.
 
 ### Multi-modal Input (Images)
 
@@ -563,7 +581,7 @@ Ground LLM responses in your own documents using vector databases.
 const provider = createSAPAIProvider({
   defaultSettings: {
     grounding: buildDocumentGroundingConfig({
-      filters: [{ id: "vector-store-1", data_repositories: ["*"] }],
+      filters: [{ id: "knowledge-filter", data_repositories: ["*"] }],
       placeholders: { input: ["groundingRequest"], output: "groundingOutput" },
     }),
   },
@@ -621,7 +639,10 @@ const model = provider("gpt-4.1");
 ### Provider Options (Per-Call Overrides)
 
 Override constructor settings on a per-call basis using `providerOptions`.
-Options are validated at runtime with Zod schemas.
+Only the documented per-call fields are supported: unknown top-level fields
+are stripped by the Zod schemas, while additional `modelParams` keys pass
+through. Standard AI SDK generation options (for example, `temperature`) take
+precedence over the corresponding `providerOptions` model parameters.
 
 ```typescript
 import { generateText } from "ai";
@@ -654,13 +675,14 @@ authentication, model parameters, data masking, content filtering, and more.
 
 **Common Configuration:**
 
-- `name`: Provider name (default: `'sap-ai'`). Used as key in
-  `providerOptions`/`providerMetadata`.
+- `name`: Provider identifier prefix (default: `'sap-ai'`). The segment before
+  the first dot is used as the key in `providerOptions`/`providerMetadata`.
 - `resourceGroup`: SAP AI Core resource group (default: 'default')
 - `deploymentId`: Specific deployment ID (auto-resolved if not set)
 - `requestConfig`: Custom HTTP request configuration (headers, params, timeout, etc.)
   forwarded to the underlying SAP AI SDK client on every call. Provider-level scope
-  only; use `requestConfig.headers` for SAP-specific headers such as
+  only; per-call `headers` can override individual headers. Use `requestConfig.headers`
+  for SAP-specific headers such as
   `AI-Object-Store-Secret-Name` (feedback service). See
   [API Reference](./API_REFERENCE.md#sapaiprovidersettings) for portability caveats.
 - `modelParams`: Temperature, maxTokens, topP, and other generation parameters
@@ -690,7 +712,9 @@ error handling across providers.
 
 - **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
+- **Rate limit (429)**: High-level AI SDK calls retry eligible errors with
+  exponential backoff, bounded by `maxRetries`; direct provider calls do not
+  implement retries
 - **Streaming**: Iterate `textStream` correctly; don't mix `generateText` and
   `streamText`
 
@@ -704,10 +728,10 @@ streaming, and tool calling.
 ## Performance
 
 - Prefer streaming (`streamText`) for long outputs to reduce latency and memory.
-- Tune `modelParams` carefully: lower `temperature` for deterministic results;
+- Tune `modelParams` carefully: lower `temperature` for less variable results;
   set `maxTokens` to expected response size.
-- Use `defaultSettings` at provider creation for shared knobs across models to
-  avoid per-call overhead.
+- Use `defaultSettings` at provider creation to share configuration across models;
+  settings are still merged and validated when models and calls are prepared.
 - Avoid unnecessary history: keep `messages` concise to reduce prompt size and
   cost.
 
@@ -734,19 +758,19 @@ repository's AI SDK 7 dependency and the local `../src/index-v4` entrypoint.
 In an AI SDK 7 application, import from `@jerome-benoit/sap-ai-provider/v4`.
 See [Installation](#installation) for other AI SDK versions.
 
-| 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-content-filtering.ts`      | Content filtering           | Azure Content Safety, orchestration     |
-| `example-document-grounding.ts`     | Document grounding (RAG)    | Vector store, retrieval-augmented gen   |
-| `example-translation.ts`            | Input/output translation    | Multi-language support, SAP translation |
-| `example-embeddings.ts`             | Text embeddings             | Vector generation, semantic similarity  |
-| `example-foundation-models.ts`      | Foundation Models API       | Direct model access, logprobs, seed     |
+| Example                             | Description                 | Key Features                             |
+| ----------------------------------- | --------------------------- | ---------------------------------------- |
+| `example-generate-text.ts`          | Basic text generation       | Simple prompts, non-streaming generation |
+| `example-simple-chat-completion.ts` | Simple chat conversation    | System messages, user prompts            |
+| `example-chat-completion-tool.ts`   | Tool calling with functions | Demo weather 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-content-filtering.ts`      | Content filtering           | Azure Content Safety, orchestration      |
+| `example-document-grounding.ts`     | Document grounding (RAG)    | Vector store, retrieval-augmented gen    |
+| `example-translation.ts`            | Input/output translation    | Multi-language support, SAP translation  |
+| `example-embeddings.ts`             | Text embeddings             | Vector generation, semantic similarity   |
+| `example-foundation-models.ts`      | Foundation Models API       | Direct model access, logprobs, seed      |
 
 **Running Examples:**
 
@@ -754,11 +778,29 @@ See [Installation](#installation) for other AI SDK versions.
 npx tsx examples/example-generate-text.ts
 ```
 
-> **Note:** Examples require `AICORE_SERVICE_KEY` environment variable. See
-> [Environment Setup](./ENVIRONMENT_SETUP.md) for configuration.
+> **Note:** Configure `AICORE_SERVICE_KEY` locally or bind the application to
+> SAP AI Core on SAP BTP. See [Environment Setup](./ENVIRONMENT_SETUP.md).
 
 ## Migration Guides
 
+### Upgrading from v4.x to v5.x
+
+Version 5.0 adds **AI SDK 7** support through the **V4** facade and requires
+**Node.js 22.12 or newer** for both packages. The root entrypoint remains
+**V3 for AI SDK 6**; upgrading the provider does not require switching SDKs.
+
+**Key changes:**
+
+- **Runtime**: Upgrade local, CI and deployment environments from Node.js 20
+  to Node.js 22.12 or newer.
+- **Entrypoints**: Use `/v4` with SDK 7, the root with SDK 6, or `/v2` with
+  SDK 5. The standalone V2 package remains available for SDK 5/6.
+- **Multimodal inputs**: V4 tagged JPEG/PDF inputs are normalized correctly;
+  unsupported binary objects are rejected instead of silently stringified.
+
+See the [4.x to 5.x migration guide](./MIGRATION_GUIDE.md#version-4x-to-5x-breaking-changes)
+for installation commands, compatibility details and the migration checklist.
+
 ### Upgrading from v3.x to v4.x
 
 Version 4.0 migrates from **LanguageModelV2** to **LanguageModelV3**
@@ -796,7 +838,7 @@ complete upgrade instructions.**
 
 - `SAPAIError` removed → Use `APICallError` from `@ai-sdk/provider`
 - Error properties: `error.code` → `error.statusCode`
-- Automatic retries for rate limits (429) and server errors (5xx)
+- Retryable error classification for the AI SDK's rate-limit/server-error retries
 
 ### Upgrading from v1.x to v2.x
 
@@ -830,7 +872,7 @@ for details.
 ### Documentation
 
 - [Migration Guide](./MIGRATION_GUIDE.md) - Version upgrade instructions (v1.x →
-  v2.x → v3.x → v4.x)
+  v2.x → v3.x → v4.x → v5.x)
 - [API Reference](./API_REFERENCE.md) - Complete API documentation with all
   types and functions
 - [Environment Setup](./ENVIRONMENT_SETUP.md) - Authentication and configuration