sap-cloud-sdk-ai

# SAP Cloud SDK for AI

## Related Skills

- **sap-cap-capire**: Use for building CAP applications that consume AI services, including event handler patterns and async LLM orchestration
- **sap-ai-core**: Use for AI Core platform setup, orchestration configuration, and model deployment
- **dependency-upgrade**: Hardening guidance for npm package upgrades, lockfile policies, and secure dependency workflows

The official SDK for SAP AI Core, SAP Generative AI Hub, and Orchestration Service.

## When to Use This Skill

Use this skill when:
- Integrating AI/LLM capabilities into SAP BTP applications
- Building chat completion or embedding features
- Using GPT-4o, Claude, Gemini, or other models via SAP AI Core
- Implementing content filtering, data masking, or document grounding
- Creating agentic workflows with LangChain or Spring AI
- Managing prompts via Prompt Registry
- Deploying AI models on SAP AI Core

## Table of Contents
- [Quick Start](#quick-start)
- [Prerequisites](#prerequisites)
- [Connection Setup](#connection-setup)
- [Available Packages](#available-packages)
- [Supported Models](#supported-models)
- [Core Features](#core-features)
- [Bundled Resources](#bundled-resources)

## Quick Start

> **Note**: This skill uses SAP Cloud SDK for AI JavaScript v2.11.0+ and Java v1.19.0+. If you're migrating from v1.x, see [V1 to V2 Migration Guide](references/v1-to-v2-migration.md) for breaking changes.

### JavaScript/TypeScript

```bash
npm install @sap-ai-sdk/orchestration@^2
```

```typescript
import { OrchestrationClient } from '@sap-ai-sdk/orchestration';

const client = new OrchestrationClient({
  promptTemplating: {
    model: { name: 'gpt-4o' },
    prompt: [{ role: 'user', content: '{{?question}}' }]
  }
});

const response = await client.chatCompletion({
  placeholderValues: { question: 'What is SAP?' }
});
console.log(response.getContent());
```

### Java

```xml
<dependency>
  <groupId>com.sap.ai.sdk</groupId>
  <artifactId>orchestration</artifactId>
  <version>${ai-sdk.version}</version>
</dependency>
```

```java
var client = new OrchestrationClient();
var config = new OrchestrationModuleConfig()
    .withLlmConfig(OrchestrationAiModel.GPT_4O);
var prompt = new OrchestrationPrompt("What is SAP?");
var result = client.chatCompletion(prompt, config);
System.out.println(result.getContent());
```

## Prerequisites

- **Node.js 20+** (JavaScript) or **Java 17+** (Java)
- **SAP AI Core** service instance (extended or sap-internal plan)
- **Orchestration deployment** in AI Core (default resource group has this)

## Connection Setup

### BTP Runtime (Cloud Foundry/Kyma)
Bind AI Core service instance to your application. SDK auto-detects via `VCAP_SERVICES` or mounted secrets.

### Local Development
Set environment variable:
```bash
export AICORE_SERVICE_KEY='{"clientid":"...","clientsecret":"...","url":"...","serviceurls":{"AI_API_URL":"..."}}'
```

Or use CAP hybrid mode:
```bash
# JavaScript
cds bind -2 <AICORE_INSTANCE> && cds-tsx watch --profile hybrid

# Java
cds bind --to aicore --exec mvn spring-boot:run
```

For detailed connection options, see `references/connecting-to-ai-core.md`

## Available Packages

### JavaScript/TypeScript
| Package | Purpose |
|---------|---------|
| `@sap-ai-sdk/orchestration` | Chat completion, filtering, grounding |
| `@sap-ai-sdk/foundation-models` | Direct model access (OpenAI) |
| `@sap-ai-sdk/langchain` | LangChain integration |
| `@sap-ai-sdk/ai-api` | Deployments, artifacts, configurations |
| `@sap-ai-sdk/document-grounding` | Pipeline, Vector, Retrieval APIs |
| `@sap-ai-sdk/prompt-registry` | Prompt template management |

### Java
| Artifact | Purpose |
|----------|---------|
| `orchestration` | Chat completion, filtering, grounding |
| `openai` (foundationmodels) | Direct OpenAI model access |
| `core` | Base connectivity |
| `document-grounding` | Pipeline, Vector, Retrieval APIs |
| `prompt-registry` | Prompt template management |

## Supported Models

### Recommended
- **OpenAI**: gpt-4o, gpt-4o-mini, o1, o3-mini
- **Anthropic (AWS)**: Claude 3.5 Sonnet, Claude 4
- **Amazon**: Nova Pro, Nova Lite, Nova Micro
- **Google**: Gemini 2.5 Flash, Gemini 2.0 Flash
- **Mistral**: Medium, Large

### Deprecated Models (Use Replacements)
| Deprecated | Use Instead |
|------------|-------------|
| text-embedding-ada-002 | text-embedding-3-small/large |
| gpt-35-turbo (all variants) | gpt-4o-mini |
| gpt-4-32k | gpt-4o |
| gpt-4 (base) | gpt-4o or gpt-4.1 |
| gemini-1.0-pro | gemini-2.0-flash |
| gemini-1.5-pro/flash | gemini-2.5-flash |
| mistralai--mixtral-8x7b | mistralai--mistral-small-instruct |

## Core Features

### Chat Completion with Streaming

```typescript
// JavaScript
const stream = client.stream({
  placeholderValues: { question: 'Explain SAP CAP' }
});

for await (const chunk of stream.toContentStream()) {
  process.stdout.write(chunk);
}
```

```java
// Java
client.streamChatCompletion(prompt, config)
    .forEach(chunk -> System.out.print(chunk.getDeltaContent()));
```

### Function/Tool Calling

```typescript
// JavaScript
const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    parameters: { type: 'object', properties: { city: { type: 'string' } } }
  }
}];

const response = await client.chatCompletion({
  placeholderValues: { question: 'Weather in Berlin?' }
}, { tools });

const toolCalls = response.getToolCalls();
```

### Content Filtering

```typescript
// JavaScript
import { buildAzureContentSafetyFilter } from '@sap-ai-sdk/orchestration';

const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  filtering: {
    input: buildAzureContentSafetyFilter({ Hate: 'ALLOW_SAFE' }),
    output: buildAzureContentSafetyFilter({ Violence: 'ALLOW_SAFE' })
  }
});
```

### Data Masking

```typescript
// JavaScript
const client = new OrchestrationClient({
  promptTemplating: { model: { name: 'gpt-4o' } },
  masking: {
    masking_providers: [{
      type: 'sap_data_privacy_