feat: migrate to LanguageModelV3 (v4.0.0)

.cursor/rules/ai-sdk-integration.mdc

@@ -1,23 +1,30 @@
 ---
 description: Guidance for integrating with the Vercel AI SDK
 ---
+
 # AI SDK Integration
 
-The provider implements the `LanguageModelV2` contract and is designed to work with the Vercel AI SDK.
+The provider implements the `LanguageModelV3` and `EmbeddingModelV3` contracts
+and is designed to work with the Vercel AI SDK 5.0+.
 
 ## Key Points
 
-- Create models via the provider function: `const model = provider("gpt-4o")`.
-- Supported operations include `doGenerate` and `doStream` (see [src/sap-ai-chat-language-model.ts](mdc:src/sap-ai-chat-language-model.ts)).
+- Create language models via the provider function: `const model = provider("gpt-4o")`.
+- Create embedding models via: `const model = provider.embedding("text-embedding-ada-002")`.
+- Supported operations include `doGenerate` and `doStream` for language models,
+  `doEmbed` for embedding models (see
+  [src/sap-ai-language-model.ts](mdc:src/sap-ai-language-model.ts) and
+  [src/sap-ai-embedding-model.ts](mdc:src/sap-ai-embedding-model.ts)).
 - Tool calling is supported by passing `tools` in call options.
-- Structured outputs (JSON schema response_format) are enabled for most models except Anthropic and Amazon families.
+- Structured outputs (JSON schema response_format) are enabled for most models
+  except Anthropic and Amazon families.
 - `n` (multi-choice) is disabled for Amazon models.
 
 ## Recommended API Usage
 
 - Text generation: `generateText` with `model: provider("<modelId>")`.
 - Streaming: `streamText` for SSE token streams.
 - Structured outputs: `generateObject` when the model supports JSON schema.
+- Embeddings: `embed` or `embedMany` with `model: provider.embedding("<modelId>")`.
 
 Refer to examples in [README.md](mdc:README.md) and [examples/](mdc:examples/).
-

.cursor/rules/build-and-publish.mdc

@@ -1,24 +1,28 @@
 ---
 description: Build, type-check, test, and publish workflow for the package
 ---
+
 # Build and Publish
 
 ## Build Outputs
 
-- Bundler: tsup (CJS + ESM + DTS + sourcemaps) — see [tsup.config.ts](mdc:tsup.config.ts)
+- Bundler: tsup (CJS + ESM + DTS + sourcemaps) — see
+  [tsup.config.ts](mdc:tsup.config.ts)
 - Output dir: [dist/](mdc:dist/)
 - Package exports configured in [package.json](mdc:package.json)
 
 ## Commands
 
-- Clean: `npm run clean`
 - Build: `npm run build`
 - Type-check: `npm run type-check`
 - Lint: `npm run lint`
-- Prettier check/fix: `npm run prettier-check` / `npm run prettier-fix`
-- Test (all): `npm test`
+- Lint-fix: `npm run lint-fix`
+- Prettier-check: `npm run prettier-check`
+- Prettier-fix: `npm run prettier-fix`
+- Test: `npm test`
 
-`prepublishOnly` enforces type-check, tests, and build before publish (see [package.json](mdc:package.json)).
+`prepublishOnly` enforces type-check, lint, test, build and check-build before
+publish (see [package.json](mdc:package.json)).
 
 ## Node Engine
 
@@ -27,4 +31,3 @@ description: Build, type-check, test, and publish workflow for the package
 ## Verification
 
 - Verify distribution artifacts exist: `npm run check-build`.
-

.cursor/rules/environment-and-config.mdc

@@ -1,31 +1,61 @@
 ---
 description: Environment variables, credentials, and configuration guidance
 ---
+
 # Environment and Configuration
 
 ## Credentials
 
-- Preferred: Provide an SAP AI Core service key JSON to `createSAPAIProvider({ serviceKey })` (see [src/sap-ai-provider.ts](mdc:src/sap-ai-provider.ts)).
-- Alternative: Provide an OAuth token via `createSAPAIProviderSync({ token })` or set `SAP_AI_TOKEN`.
+The SAP AI SDK (`@sap-ai-sdk/orchestration`) handles authentication
+automatically:
 
-## Environment Variables
+1. **On SAP BTP**: Uses service binding from `VCAP_SERVICES`
+2. **Locally**: Uses `AICORE_SERVICE_KEY` environment variable containing the
+   full JSON service key
 
-See details in [README.md](mdc:README.md).
+## Provider Configuration
 
-- `SAP_AI_SERVICE_KEY` — full JSON string of your service key.
-- `SAP_AI_TOKEN` — direct OAuth token (used by default instance `sapai`).
-- `SAP_AI_BASE_URL` — override base URL if needed.
+Configure the provider using `createSAPAIProvider(options)`:
 
-Do not commit secrets. Prefer local `.env` and CI secrets. `dotenv` is available for local development.
+```typescript
+import { createSAPAIProvider } from "@jerome-benoit/sap-ai-provider";
 
-## Deployment and Resource Group
+// Default configuration (auto-detects authentication)
+const provider = createSAPAIProvider();
+
+// With specific resource group
+const provider = createSAPAIProvider({
+  resourceGroup: "production",
+});
+
+// With specific deployment ID
+const provider = createSAPAIProvider({
+  deploymentId: "d65d81e7c077e583",
+});
+
+// With custom destination
+const provider = createSAPAIProvider({
+  destination: {
+    url: "https://api.ai.prod.eu-central-1.aws.ml.hana.ondemand.com",
+  },
+});
+```
 
-- Default `deploymentId`: `d65d81e7c077e583`
-- Default `resourceGroup`: `default`
+## Environment Variables
+
+- `AICORE_SERVICE_KEY` — Full JSON string of your SAP AI Core service key (used
+  by SAP AI SDK)
+
+Do not commit secrets. Prefer local `.env` and CI secrets. `dotenv` is available
+for local development.
+
+## Deployment and Resource Group
 
-Both can be overridden in provider settings or via environment variables in your host app.
+- Default `resourceGroup`: `'default'`
 
-## SAP BTP (xsenv)
+Both `resourceGroup` and `deploymentId` can be configured in provider settings.
 
-For BTP environments, consider loading credentials from `VCAP_SERVICES` via `@sap/xsenv` as shown in [README.md](mdc:README.md).
+## SAP BTP (VCAP_SERVICES)
 
+For BTP environments, the SAP AI SDK automatically reads credentials from
+`VCAP_SERVICES` when the application is bound to an AI Core service instance.

.cursor/rules/project-structure.mdc

@@ -1,33 +1,46 @@
 ---
 alwaysApply: true
 ---
+
 # Project Structure Guide
 
-This repository provides an SAP AI Core provider compatible with the Vercel AI SDK. Use these anchors to navigate the codebase quickly.
+This repository provides an SAP AI Core provider compatible with the Vercel AI
+SDK. Use these anchors to navigate the codebase quickly.
 
 ## Entry Points and Core Modules
 
 - Main package entry: [src/index.ts](mdc:src/index.ts)
   - Re-exports provider factory and types.
-- Provider factory and default instance: [src/sap-ai-provider.ts](mdc:src/sap-ai-provider.ts)
-  - `createSAPAIProvider(options)` returns a function for model creation (async; handles OAuth when given a service key).
-  - `createSAPAIProviderSync(options)` for token-based sync usage.
-  - `sapai` default instance reads `SAP_AI_TOKEN` at call time.
-- Chat LLM implementation: [src/sap-ai-chat-language-model.ts](mdc:src/sap-ai-chat-language-model.ts)
-  - Implements Vercel AI SDK `LanguageModelV2` contract.
-  - Supports text, tool calls, streaming, structured outputs (varies by model family).
-- Message templating: [src/convert-to-sap-messages.ts](mdc:src/convert-to-sap-messages.ts)
-- Settings and model IDs: [src/sap-ai-chat-settings.ts](mdc:src/sap-ai-chat-settings.ts)
+- Provider factory and default instance:
+  [src/sap-ai-provider.ts](mdc:src/sap-ai-provider.ts)
+  - `createSAPAIProvider(options)` returns a provider function for model
+    creation.
+  - `sapai` default instance uses default configuration (auto-detects service
+    binding or AICORE_SERVICE_KEY env var).
+- Language model implementation:
+  [src/sap-ai-language-model.ts](mdc:src/sap-ai-language-model.ts)
+  - Implements Vercel AI SDK `LanguageModelV3` contract (v4.0.0+).
+  - Supports text, tool calls, streaming, structured outputs (varies by model
+    family).
+- Embedding model implementation:
+  [src/sap-ai-embedding-model.ts](mdc:src/sap-ai-embedding-model.ts)
+  - Implements Vercel AI SDK `EmbeddingModelV3` contract.
+  - Supports single and batch embedding generation.
+- Message templating:
+  [src/convert-to-sap-messages.ts](mdc:src/convert-to-sap-messages.ts)
+- Settings and model IDs: [src/sap-ai-settings.ts](mdc:src/sap-ai-settings.ts)
+  - Also re-exports all SAP AI SDK types for convenience.
 - Error handling helpers: [src/sap-ai-error.ts](mdc:src/sap-ai-error.ts)
-- Types: [src/types/completion-response.ts](mdc:src/types/completion-response.ts), [src/types/completion-request.ts](mdc:src/types/completion-request.ts)
 
 ## Build, Types, and Distribution
 
 - TypeScript config: [tsconfig.json](mdc:tsconfig.json)
 - Build config (CJS+ESM+DTS): [tsup.config.ts](mdc:tsup.config.ts)
 - ESLint config: [eslint.config.mjs](mdc:eslint.config.mjs)
-- Output: [dist/](mdc:dist/) produces `index.js`, `index.mjs`, `index.d.ts` with sourcemaps.
-- `package.json` exports are aligned for Node and ESM: [package.json](mdc:package.json)
+- Output: [dist/](mdc:dist/) produces `index.js`, `index.cjs`, `index.d.ts` with
+  sourcemaps.
+- `package.json` exports are aligned for Node and ESM:
+  [package.json](mdc:package.json)
 
 ## Testing
 
@@ -37,14 +50,38 @@ This repository provides an SAP AI Core provider compatible with the Vercel AI S
 ## Examples and Docs
 
 - README with usage and configuration: [README.md](mdc:README.md)
+- Complete API reference: [API_REFERENCE.md](mdc:API_REFERENCE.md)
+- Architecture documentation: [ARCHITECTURE.md](mdc:ARCHITECTURE.md)
+- Contribution guidelines: [CONTRIBUTING.md](mdc:CONTRIBUTING.md)
+- Environment setup guide: [ENVIRONMENT_SETUP.md](mdc:ENVIRONMENT_SETUP.md)
+- Troubleshooting guide: [TROUBLESHOOTING.md](mdc:TROUBLESHOOTING.md)
+- Migration guide: [MIGRATION_GUIDE.md](mdc:MIGRATION_GUIDE.md)
+- cURL API testing guide:
+  [CURL_API_TESTING_GUIDE.md](mdc:CURL_API_TESTING_GUIDE.md)
+- AI agent instructions: [AGENTS.md](mdc:AGENTS.md)
 - Examples: [examples/](mdc:examples/)
-  - Chat completion: [examples/example-simple-chat-completion.ts](mdc:examples/example-simple-chat-completion.ts)
-  - Tool calling: [examples/example-chat-completion-tool.ts](mdc:examples/example-chat-completion-tool.ts)
-  - Image recognition: [examples/example-image-recognition.ts](mdc:examples/example-image-recognition.ts)
-  - Text generation: [examples/example-generate-text.ts](mdc:examples/example-generate-text.ts)
+  - Chat completion:
+    [examples/example-simple-chat-completion.ts](mdc:examples/example-simple-chat-completion.ts)
+  - Tool calling:
+    [examples/example-chat-completion-tool.ts](mdc:examples/example-chat-completion-tool.ts)
+  - Image recognition:
+    [examples/example-image-recognition.ts](mdc:examples/example-image-recognition.ts)
+  - Text generation:
+    [examples/example-generate-text.ts](mdc:examples/example-generate-text.ts)
+  - Data masking:
+    [examples/example-data-masking.ts](mdc:examples/example-data-masking.ts)
+  - Streaming:
+    [examples/example-streaming-chat.ts](mdc:examples/example-streaming-chat.ts)
+  - Document grounding (RAG):
+    [examples/example-document-grounding.ts](mdc:examples/example-document-grounding.ts)
+  - Translation:
+    [examples/example-translation.ts](mdc:examples/example-translation.ts)
+  - Embeddings:
+    [examples/example-embeddings.ts](mdc:examples/example-embeddings.ts)
 
 ## Runtime Requirements
 
 - Node.js >= 18 (see `engines` in [package.json](mdc:package.json)).
-- Environment variables are used for credentials when no service key is provided.
-
+- Authentication is handled automatically by SAP AI SDK:
+  - On SAP BTP: Uses service binding (VCAP_SERVICES)
+  - Locally: Uses AICORE_SERVICE_KEY environment variable

.cursor/rules/testing.mdc

@@ -1,14 +1,16 @@
 ---
 globs: **/*.test.ts,**/*.test.tsx
 ---
+
 # Testing Guide (Vitest)
 
 ## Test Environments
 
 - Node tests: [vitest.node.config.js](mdc:vitest.node.config.js)
 - Edge runtime tests: [vitest.edge.config.js](mdc:vitest.edge.config.js)
 
-Use Node environment for most unit tests. Use Edge runtime when covering streaming or runtime-specific behaviors.
+Use Node environment for most unit tests. Use Edge runtime when covering
+streaming or runtime-specific behaviors.
 
 ## Commands
 
@@ -19,12 +21,17 @@ Use Node environment for most unit tests. Use Edge runtime when covering streami
 
 ## Stubbing Network
 
-- Prefer injecting a custom `fetch` via provider settings for deterministic tests (see [src/sap-ai-provider.ts](mdc:src/sap-ai-provider.ts)).
-- For streaming flows, assert `LanguageModelV2StreamPart` events via the `doStream` pipeline (see [src/sap-ai-chat-language-model.ts](mdc:src/sap-ai-chat-language-model.ts)).
+- Prefer injecting a custom `fetch` via provider settings for deterministic
+  tests (see [src/sap-ai-provider.ts](mdc:src/sap-ai-provider.ts)).
+- For streaming flows, assert `LanguageModelV3StreamPart` events via the
+  `doStream` pipeline (see
+  [src/sap-ai-language-model.ts](mdc:src/sap-ai-language-model.ts)).
 
 ## Test Patterns
 
-- Validate message templating: cover [src/convert-to-sap-messages.ts](mdc:src/convert-to-sap-messages.ts).
-- Validate error propagation using helpers in [src/sap-ai-error.ts](mdc:src/sap-ai-error.ts).
-- Assert structured output behavior varies by model family (Anthropic/Amazon do not support JSON schema formatting).
-
+- Validate message templating: cover
+  [src/convert-to-sap-messages.ts](mdc:src/convert-to-sap-messages.ts).
+- Validate error propagation using helpers in
+  [src/sap-ai-error.ts](mdc:src/sap-ai-error.ts).
+- Assert structured output behavior varies by model family (Anthropic/Amazon do
+  not support JSON schema formatting).

.cursor/rules/typescript-style.mdc

@@ -1,9 +1,11 @@
 ---
 globs: *.ts,*.tsx,*.mts,*.cts
 ---
+
 # TypeScript Style Guide
 
-Follow these conventions across TypeScript sources to align with the existing configuration and code style.
+Follow these conventions across TypeScript sources to align with the existing
+configuration and code style.
 
 ## Language and Types
 
@@ -20,17 +22,23 @@ Follow these conventions across TypeScript sources to align with the existing co
 
 ## Errors and Handling
 
-- Do not swallow errors. Propagate or wrap with context via `SAPAIError` utilities when applicable (see [src/sap-ai-error.ts](mdc:src/sap-ai-error.ts)).
-- Only use `try/catch` where meaningful recovery or re-throw with context is performed.
+- Do not swallow errors. Propagate or wrap with context using Vercel AI SDK
+  standard errors (`APICallError`, `LoadAPIKeyError`, `NoSuchModelError` from
+  `@ai-sdk/provider`).
+- Only use `try/catch` where meaningful recovery or re-throw with context is
+  performed.
 
 ## Formatting and Linting
 
-- Respect [eslint.config.mjs](mdc:eslint.config.mjs) and Prettier (see `prettier-*` scripts in [package.json](mdc:package.json)).
+- Respect [eslint.config.mjs](mdc:eslint.config.mjs) and Prettier (see
+  `prettier-*` scripts in [package.json](mdc:package.json)).
 - Keep lines readable; prefer multi-line over dense one-liners.
 - Avoid inline explanatory comments; add brief comments above non-obvious logic.
 
 ## Provider-specific Conventions
 
-- The provider function must not be invoked with `new` (explicitly guarded in [src/sap-ai-provider.ts](mdc:src/sap-ai-provider.ts)).
-- When adding model capabilities, ensure `SAPAIChatLanguageModel` maintains the `LanguageModelV2` contract (see [src/sap-ai-chat-language-model.ts](mdc:src/sap-ai-chat-language-model.ts)).
-
+- The provider function must not be invoked with `new` (explicitly guarded in
+  [src/sap-ai-provider.ts](mdc:src/sap-ai-provider.ts)).
+- When adding model capabilities, ensure `SAPAILanguageModel` maintains the
+  `LanguageModelV3` contract (see
+  [src/sap-ai-language-model.ts](mdc:src/sap-ai-language-model.ts)).

.cursor/rules/usage-and-examples.mdc

@@ -1,22 +1,40 @@
 ---
 description: How to use the provider and where to find examples
 ---
+
 # Usage and Examples
 
-Start with the README’s Quick Start and Advanced sections: [README.md](mdc:README.md).
+Start with the README’s Quick Start and Advanced sections:
+[README.md](mdc:README.md).
 
 ## Examples
 
-- Simple chat completion: [examples/example-simple-chat-completion.ts](mdc:examples/example-simple-chat-completion.ts)
-- Tool calling: [examples/example-chat-completion-tool.ts](mdc:examples/example-chat-completion-tool.ts)
-- Image recognition: [examples/example-image-recognition.ts](mdc:examples/example-image-recognition.ts)
-- Text generation: [examples/example-generate-text.ts](mdc:examples/example-generate-text.ts)
+- Simple chat completion:
+  [examples/example-simple-chat-completion.ts](mdc:examples/example-simple-chat-completion.ts)
+- Tool calling:
+  [examples/example-chat-completion-tool.ts](mdc:examples/example-chat-completion-tool.ts)
+- Image recognition:
+  [examples/example-image-recognition.ts](mdc:examples/example-image-recognition.ts)
+- Text generation:
+  [examples/example-generate-text.ts](mdc:examples/example-generate-text.ts)
+- Data masking:
+  [examples/example-data-masking.ts](mdc:examples/example-data-masking.ts)
+- Streaming chat:
+  [examples/example-streaming-chat.ts](mdc:examples/example-streaming-chat.ts)
+- Document grounding (RAG):
+  [examples/example-document-grounding.ts](mdc:examples/example-document-grounding.ts)
+- Translation:
+  [examples/example-translation.ts](mdc:examples/example-translation.ts)
+- Embeddings:
+  [examples/example-embeddings.ts](mdc:examples/example-embeddings.ts)
 
 ## Common Patterns
 
-- Create provider with service key: `createSAPAIProvider({ serviceKey })`.
-- Default instance with env token: `sapai("gpt-4o")`.
-- Use with Vercel AI SDK: `generateText`, `streamText`, `generateObject`.
+- Create provider: `createSAPAIProvider()` (auto-detects AICORE_SERVICE_KEY from
+  environment)
+- With options:
+  `createSAPAIProvider({ resourceGroup: 'production', deploymentId: 'abc123' })`
+- Default instance: `sapai("gpt-4o")` (uses default configuration)
+- Use with Vercel AI SDK: `generateText`, `streamText`, `generateObject`
 
 See exported APIs: [src/index.ts](mdc:src/index.ts)
-