### Install SAP AI SDK Locally

Source: https://github.com/sap/ai-sdk-java/blob/main/sample-code/spring-app/README.md

Install the AI SDK into your local Maven repository before running the sample app. Ensure you pull the latest SDK changes if needed.

```bash
mvn install -DskipTests
```

--------------------------------

### Run Sample App

Source: https://github.com/sap/ai-sdk-java/blob/main/sample-code/spring-app/README.md

Start the Spring Boot sample application from its directory. Access the available endpoints via your browser.

```bash
mvn spring-boot:run
```

--------------------------------

### Log Request Start

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/adrs/006-logging-strategy.md

Log at the start of a request to provide immediate visibility that an operation has begun. This helps users understand that their request is being processed.

```text
[callId=e3eaa45c] Starting OpenAI synchronous request to /v1/chat/completions, destination=<some-uri>.
```

--------------------------------

### Build Project with Maven

Source: https://github.com/sap/ai-sdk-java/blob/main/README.md

Build the project using Maven, which includes running tests and installing the SNAPSHOT version into your local Maven repository.

```shell
mvn clean install -DskipTests
```

--------------------------------

### Initialize OrchestrationClient

Source: https://github.com/sap/ai-sdk-java/blob/main/README.md

Instantiate the OrchestrationClient to interact with the Orchestration service. No specific setup is required for basic usage.

```java
var client = new OrchestrationClient();
```

--------------------------------

### OpenAiClient - Chat Completion with System Prompt

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Shows how to use a system prompt to guide the AI's behavior during a chat completion.

```APIDOC
### With system prompt shortcut
```java
// ... other imports

String answer = OpenAiClient.forModel(OpenAiModel.GPT_5_MINI)
    .withSystemPrompt("You are a senior Java architect.")
    .streamChatCompletion("What are the trade-offs of microservices?")
    .collect(java.util.stream.Collectors.joining());
```
```

--------------------------------

### Create Deployment in SAP AI Core

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/blog/Introducing.md

Example SDK code to create a deployment in SAP AI Core using the `DeploymentApi`. Requires a resource group ID and a configuration ID.

```java
var api = new DeploymentApi();
var resourceGroupId = "default";
var request =
  AiDeploymentCreationRequest.create().configurationId("12345-123-123-123-123456abcdefg");

AiDeploymentCreationResponse deployment = api.create(resourceGroupId, request);
String id = deployment.getId();
AiExecutionStatus status = deployment.getStatus();
```

--------------------------------

### Configure Orchestration Module with GPT-4o

Source: https://github.com/sap/ai-sdk-java/blob/main/README.md

Specify the AI model to be used for the orchestration. This example uses the GPT-4o model.

```java
var config = new OrchestrationModuleConfig()
        .withLlmConfig(OrchestrationAiModel.GPT_4O);
```

--------------------------------

### Example Log Message with Metric Pattern

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/adrs/006-logging-strategy.md

Illustrates the recommended format for log messages, including a call identifier and structured details using the `metric=value` pattern for extensibility.

```text
[callId=e3eaa45c] OpenAI request completed successfully with duration=1628ms, responseSize=1.2KB.
```

--------------------------------

### Chat Completion with System Prompt

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Utilize a system prompt to guide the AI's persona or behavior for chat completions. This is a shortcut for setting up the initial system message.

```java
// --- With system prompt shortcut ---
String answer = OpenAiClient.forModel(OpenAiModel.GPT_5_MINI)
    .withSystemPrompt("You are a senior Java architect.")
    .streamChatCompletion("What are the trade-offs of microservices?")
    .collect(java.util.stream.Collectors.joining());
```

--------------------------------

### Vector Store Grounding with Metadata Filter

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Implement RAG by grounding prompts with context from a vector store. This example shows how to filter documents based on metadata, such as category, and control the number of chunks retrieved.

```java
import com.sap.ai.sdk.orchestration.*;
import com.sap.ai.sdk.orchestration.model.*;
import java.util.List;

var client = new OrchestrationClient();
var baseConfig = new OrchestrationModuleConfig().withLlmConfig(OrchestrationAiModel.GPT_5_MINI);

// --- Vector store grounding with metadata filter ---
var docMetaFilter = SearchDocumentKeyValueListPair.create()
    .key("category")
    .value("product-docs")
    .addSelectModeItem(SearchSelectOptionEnum.IGNORE_IF_KEY_ABSENT);

var groundingFilter = DocumentGroundingFilter.create()
    .dataRepositoryType(DataRepositoryType.VECTOR)
    .searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(5))
    .addDocumentMetadataItem(docMetaFilter);

var groundingConfig = Grounding.create()
    .filters(groundingFilter)
    .metadataParams("*"); // include all metadata in response

// createGroundingPrompt wraps the user query to extract grounding context
var prompt = groundingConfig.createGroundingPrompt("What are the system requirements?")
    .messageHistory(List.of(Message.system("Include all relevant metadata in your response.")));

var configWithGrounding = baseConfig.withGrounding(groundingConfig);
String answer = client.chatCompletion(prompt, configWithGrounding).getContent();
```

--------------------------------

### Send Prompt and Get Chat Completion

Source: https://github.com/sap/ai-sdk-java/blob/main/README.md

Create a prompt and send it to the configured AI model via the Orchestration service. The response content is then retrieved.

```java
var prompt = new OrchestrationPrompt("Hello world! Why is this phrase so famous?");

var result = client.chatCompletion(prompt, config).getContent();
```

--------------------------------

### Perform Chat Completion with Orchestration Service

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/blog/Introducing.md

Example SDK code to perform a chat completion using the `OrchestrationClient`. Specify the LLM configuration and provide a prompt.

```java
var client = new OrchestrationClient();
var config = new OrchestrationModuleConfig().withLlmConfig(OrchestrationAiModel.GPT_4O);
var prompt = new OrchestrationPrompt("Hello world! Why is this phrase so famous?");
var result = client.chatCompletion(prompt, config);

String messageResult = result.getContent();
```

--------------------------------

### Run Sample App with MCP Profile

Source: https://github.com/sap/ai-sdk-java/blob/main/sample-code/spring-app/README.md

To test the MCP integration, run the sample app with the 'mcp' Spring profile activated. This configures the application for MCP-specific functionality.

```bash
mvn spring-boot:run -Dspring-boot.run.arguments="--spring.profiles.active=mcp"
```

--------------------------------

### Grounding via help.sap.com

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Utilize the Grounding feature to retrieve context directly from help.sap.com. This is useful for answering questions related to SAP product documentation and support.

```java
// --- Grounding via help.sap.com ---
var helpFilter = DocumentGroundingFilter.create()
    .dataRepositoryType(DataRepositoryType.HELP_SAP_COM);
var helpGrounding = Grounding.create().filters(helpFilter);
var helpPrompt = helpGrounding.createGroundingPrompt("How do I create an AI Core deployment?");
var helpConfig = baseConfig.withGrounding(helpGrounding);
String helpAnswer = client.chatCompletion(helpPrompt, helpConfig).getContent();
```

--------------------------------

### OrchestrationChatResponse - Structured JSON Output

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Shows how to define a JSON schema and use it with OrchestrationChatResponse to get structured JSON output from the LLM, such as translated text.

```APIDOC
## `OrchestrationChatResponse` — Response Parsing (Structured JSON)

// --- Structured JSON output via JSON schema ---
record Translation(
    @com.fasterxml.jackson.annotation.JsonProperty(required = true) String translation,
    @com.fasterxml.jackson.annotation.JsonProperty(required = true) String language) {}

var schema = ResponseJsonSchema.fromType(Translation.class)
    .withDescription("Language translation output")
    .withStrict(true);
var configWithSchema = new OrchestrationModuleConfig()
    .withLlmConfig(OrchestrationAiModel.GPT_5_MINI)
    .withTemplateConfig(TemplateConfig.create().withJsonSchemaResponse(schema));

OrchestrationChatResponse schemaResponse = client.chatCompletion(
    new OrchestrationPrompt(
        Message.user("Translate 'Good morning' to French."),
        Message.system("You are a translator.")),
    configWithSchema);

Translation result = schemaResponse.asEntity(Translation.class);
System.out.printf("Translation: %s (%s)%n", result.translation(), result.language());
// → Translation: Bonjour (French)
```

--------------------------------

### DeploymentApi - Managing AI Core Deployments

Source: https://context7.com/sap/ai-sdk-java/llms.txt

This section demonstrates how to use the DeploymentApi to create, query, modify, and delete AI Core deployments programmatically. It includes steps for creating a model configuration and then deploying it.

```APIDOC
## `DeploymentApi` — AI Core Deployment Management

`DeploymentApi` is a generated client for creating, querying, modifying, and deleting SAP AI Core deployments programmatically.

```java
import com.sap.ai.sdk.core.client.*;
import com.sap.ai.sdk.core.model.*;
import com.sap.ai.sdk.foundationmodels.openai.OpenAiModel;

var deploymentApi = new DeploymentApi();
var configApi = new ConfigurationApi();
String resourceGroup = "default";

// 1. Create a configuration for a model
var modelName = AiParameterArgumentBinding.create().key("model").value(OpenAiModel.GPT_4O.name());
var modelVersion = AiParameterArgumentBinding.create().key("modelVersion").value("latest");
var configData = AiConfigurationBaseData.create()
    .name("my-gpt4o-config")
    .executableId("azure-openai")
    .scenarioId("foundation-models")
    .addParameterBindingsItem(modelName)
    .addParameterBindingsItem(modelVersion);

AiConfigurationCreationResponse config = configApi.create(resourceGroup, configData);
System.out.println("Config ID: " + config.getId());

// 2. Create a deployment from the configuration
AiDeploymentCreationResponse deployment = deploymentApi.create(resourceGroup,
    AiDeploymentCreationRequest.create().configurationId(config.getId()));
System.out.println("Deployment ID: " + deployment.getId());

// 3. List all deployments
AiDeploymentList list = deploymentApi.query(resourceGroup);
list.getResources().forEach(d ->
    System.out.printf("ID: %s, Status: %s, Config: %s%n",
        d.getId(), d.getStatus(), d.getConfigurationId()));

// 4. Stop a running deployment
deploymentApi.modify(resourceGroup, deployment.getId(),
    AiDeploymentModificationRequest.create()
        .targetStatus(AiDeploymentTargetStatus.STOPPED));

// 5. Delete a stopped deployment
AiDeploymentDeletionResponse deletion = deploymentApi.delete(resourceGroup, deployment.getId());
System.out.println("Deletion message: " + deletion.getMessage());
```
```

--------------------------------

### PromptClient Operations

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Demonstrates how to use the PromptClient to create, update, list, parse, import, export, and delete prompt templates.

```APIDOC
## PromptClient Operations

### Description
This section covers the usage of the `PromptClient` for managing versioned prompt templates within the SAP Prompt Registry.

### Methods
- `createUpdatePromptTemplate`: Creates a new prompt template or updates an existing one.
- `listPromptTemplates`: Retrieves a list of all available prompt templates.
- `parsePromptTemplateById`: Substitutes parameters in a prompt template and returns the result.
- `importPromptTemplate`: Imports a prompt template from a YAML file.
- `exportPromptTemplate`: Exports a prompt template to a YAML format.
- `deletePromptTemplate`: Deletes a specified prompt template.

### Example Usage (Java)
```java
import com.sap.ai.sdk.prompt.registry.*;
import com.sap.ai.sdk.prompt.registry.model.*;
import java.util.Map;

var promptClient = new PromptClient();

// --- Create/update a prompt template ---
var spec = PromptTemplateSpec.create()
    .template(
        SingleChatTemplate.create().role("system")
            .content("Classify text into: {{?categories}}"),
        SingleChatTemplate.create().role("user")
            .content("{{?inputExample}}")
    )
    .defaults(Map.of("categories", "Finance, Tech, Sports"));

var createRequest = PromptTemplatePostRequest.create()
    .name("text-classifier")
    .version("0.0.1")
    .scenario("categorization")
    .spec(spec);

PromptTemplatePostResponse created = promptClient.createUpdatePromptTemplate(createRequest);
System.out.println("Template ID: " + created.getId());

// --- List templates ---
PromptTemplateListResponse templates = promptClient.listPromptTemplates();
templates.getResources().forEach(t ->
    System.out.printf("Name: %s v%s%n", t.getName(), t.getVersion()));

// --- Substitute/preview a template ---
PromptTemplateSubstitutionResponse substituted = promptClient.parsePromptTemplateById(
    created.getId(), "default", null, false,
    PromptTemplateSubstitutionRequest.create()
        .inputParams(Map.of("inputExample", "I love football")));
System.out.println("Substituted: " + substituted);

// --- Import/export YAML template ---
byte[] yamlTemplate = new java.io.File("prompt-template.yaml").getBytes();  // load YAML
PromptTemplatePostResponse imported = promptClient.importPromptTemplate("default", null, yamlTemplate);
byte[] exported = promptClient.exportPromptTemplate(imported.getId());

// --- Delete a template ---
promptClient.deletePromptTemplate(created.getId());
```
```

--------------------------------

### Centralized MDC Management in Java

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/adrs/006-logging-strategy.md

Demonstrates the difference between using magic strings and a centralized utility class for setting MDC values. Use a utility class to ensure discoverability and prevent refactoring errors.

```java
// Bad: Magic strings scattered in code
MDC.put("service", "OpenAI");
log.debug("Service {}", MDC.get("service"));

// Good: Centralized in utility class
RequestLogContext.setService(Service.OPENAI);
log.debug("Service {}", RequestLogContext.get(MdcKeys.SERVICE));
```

--------------------------------

### Manage Prompt Templates with PromptClient

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Use PromptClient to create, update, list, substitute, import, export, and delete prompt templates in the SAP Prompt Registry. Ensure necessary imports are included.

```java
import com.sap.ai.sdk.prompt.registry.*;
import com.sap.ai.sdk.prompt.registry.model.*;
import java.util.Map;

var promptClient = new PromptClient();
var orchConfigClient = new OrchestrationConfigClient();

// --- Create/update a prompt template ---
var spec = PromptTemplateSpec.create()
    .template(
        SingleChatTemplate.create().role("system")
            .content("Classify text into: {{?categories}}"),
        SingleChatTemplate.create().role("user")
            .content("{{?inputExample}}")
    )
    .defaults(Map.of("categories", "Finance, Tech, Sports"));

var createRequest = PromptTemplatePostRequest.create()
    .name("text-classifier")
    .version("0.0.1")
    .scenario("categorization")
    .spec(spec);

PromptTemplatePostResponse created = promptClient.createUpdatePromptTemplate(createRequest);
System.out.println("Template ID: " + created.getId());

// --- List templates ---
PromptTemplateListResponse templates = promptClient.listPromptTemplates();
templates.getResources().forEach(t ->
    System.out.printf("Name: %s v%s%n", t.getName(), t.getVersion()));

// --- Substitute/preview a template ---
PromptTemplateSubstitutionResponse substituted = promptClient.parsePromptTemplateById(
    created.getId(), "default", null, false,
    PromptTemplateSubstitutionRequest.create()
        .inputParams(Map.of("inputExample", "I love football")));
System.out.println("Substituted: " + substituted);

// --- Import/export YAML template ---
byte[] yamlTemplate = new java.io.File("prompt-template.yaml").getBytes();  // load YAML
PromptTemplatePostResponse imported = promptClient.importPromptTemplate("default", null, yamlTemplate);
byte[] exported = promptClient.exportPromptTemplate(imported.getId());

// --- Delete a template ---
promptClient.deletePromptTemplate(created.getId());
```

```java
// --- Create an Orchestration Config (LLM + template bundled together) ---
var message = UserChatMessage.create()
    .content(new UserChatMessageContent.InnerString("Paraphrase: {{?phrase}}"))
    .role(UserChatMessage.RoleEnum.USER);
var orchestrationConfig = OrchestrationConfig.create()
    .modules(OrchestrationConfigModules.createInnerModuleConfigs(
        ModuleConfigs.create()
            .promptTemplating(PromptTemplatingModuleConfig.create()
                .prompt(Template.create().template(message))
                .model(LLMModelDetails.create().name("gpt-5-mini")))));

OrchestrationConfigPostResponse orchResp = orchConfigClient.createUpdateOrchestrationConfig(
    OrchestrationConfigPostRequest.create()
        .name("paraphrase-config")
        .version("0.0.1")
        .scenario("my-scenario")
        .spec(orchestrationConfig));
System.out.println("Orch Config ID: " + orchResp.getId());

// --- List and delete orchestration configs ---
OrchestrationConfigListResponse configs = orchConfigClient.listOrchestrationConfigs();
configs.getResources().stream()
    .filter(c -> "paraphrase-config".equals(c.getName()))
    .forEach(c -> orchConfigClient.deleteOrchestrationConfig(c.getId()));
```

--------------------------------

### Execute Request with Raw JSON Module Config

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Submit an orchestration request using a raw JSON module configuration string. This is useful for exporting configurations from AI Launchpad or using features not yet available in the Java API. The prompt should be empty of messages, with template parameters provided separately.

```java
import com.sap.ai.sdk.orchestration.*;
import java.util.Map;

var client = new OrchestrationClient();

// Exported JSON config from AI Launchpad
String jsonConfig = """
    {
      "llm": { "model_name": "gpt-5-mini", "model_params": {}, "model_version": "latest" },
      "templating": {
        "template": [{ "role": "user", "content": "Summarize {{?topic}} in one sentence." }]
      }
    }
    """;

// Prompt must be empty of messages; template parameters are provided here
var prompt = new OrchestrationPrompt(Map.of("topic", "quantum computing"));

OrchestrationChatResponse response = client.executeRequestFromJsonModuleConfig(prompt, jsonConfig);
System.out.println(response.getContent());
// → "Quantum computing uses quantum-mechanical phenomena to perform computations..."
```

--------------------------------

### Manage AI Core Deployments with DeploymentApi

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Use DeploymentApi to create, query, modify, and delete AI Core deployments. Requires configuration creation first.

```java
import com.sap.ai.sdk.core.client.*;
import com.sap.ai.sdk.core.model.*;
import com.sap.ai.sdk.foundationmodels.openai.OpenAiModel;

var deploymentApi = new DeploymentApi();
var configApi = new ConfigurationApi();
String resourceGroup = "default";

// 1. Create a configuration for a model
var modelName = AiParameterArgumentBinding.create().key("model").value(OpenAiModel.GPT_4O.name());
var modelVersion = AiParameterArgumentBinding.create().key("modelVersion").value("latest");
var configData = AiConfigurationBaseData.create()
    .name("my-gpt4o-config")
    .executableId("azure-openai")
    .scenarioId("foundation-models")
    .addParameterBindingsItem(modelName)
    .addParameterBindingsItem(modelVersion);

AiConfigurationCreationResponse config = configApi.create(resourceGroup, configData);
System.out.println("Config ID: " + config.getId());

// 2. Create a deployment from the configuration
AiDeploymentCreationResponse deployment = deploymentApi.create(resourceGroup,
    AiDeploymentCreationRequest.create().configurationId(config.getId()));
System.out.println("Deployment ID: " + deployment.getId());

// 3. List all deployments
AiDeploymentList list = deploymentApi.query(resourceGroup);
list.getResources().forEach(d ->
    System.out.printf("ID: %s, Status: %s, Config: %s%n",
        d.getId(), d.getStatus(), d.getConfigurationId()));

// 4. Stop a running deployment
deploymentApi.modify(resourceGroup, deployment.getId(),
    AiDeploymentModificationRequest.create()
        .targetStatus(AiDeploymentTargetStatus.STOPPED));

// 5. Delete a stopped deployment
AiDeploymentDeletionResponse deletion = deploymentApi.delete(resourceGroup, deployment.getId());
System.out.println("Deletion message: " + deletion.getMessage());

```

--------------------------------

### OpenAiClient - Basic Chat Completion

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Demonstrates how to perform a basic chat completion using a specified OpenAI model.

```APIDOC
## `OpenAiClient` — Direct OpenAI Foundation Model Access

`OpenAiClient` provides direct access to Azure OpenAI models deployed on SAP AI Core, bypassing the Orchestration Service for use cases requiring raw OpenAI API compatibility.

### Basic chat completion
```java
import com.sap.ai.sdk.foundationmodels.openai.*;
import com.sap.ai.sdk.core.AiCoreService;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Stream;

OpenAiChatCompletionResponse response = OpenAiClient.forModel(OpenAiModel.GPT_5_MINI)
    .chatCompletion(new OpenAiChatCompletionRequest("Explain Java records briefly."));
System.out.println(response.getContent());
```
```

--------------------------------

### Configure OrchestrationAiModel with Parameters

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Use pre-defined constants for models or specify custom models by name. Tune model parameters like max tokens and temperature using the fluent API.

```java
import com.sap.ai.sdk.orchestration.OrchestrationAiModel;
import static com.sap.ai.sdk.orchestration.OrchestrationAiModel.Parameter.*;

// Pre-defined model constants
var gpt5Mini    = OrchestrationAiModel.GPT_5_MINI;
var gpt4o       = OrchestrationAiModel.GPT_4O;
var gpt41       = OrchestrationAiModel.GPT_41;
var claude4     = OrchestrationAiModel.CLAUDE_4_SONNET;
var gemini25Pro = OrchestrationAiModel.GEMINI_2_5_PRO;
var novaPro     = OrchestrationAiModel.NOVA_PRO;
var sonar       = OrchestrationAiModel.SONAR; // Perplexity with citations
var sapAbap     = OrchestrationAiModel.SAP_ABAP_1;

// Model with typed parameter constants
var tuned = OrchestrationAiModel.GPT_5_MINI
    .withParam(MAX_TOKENS, 200)
    .withParam(TEMPERATURE, 0.1)
    .withParam(FREQUENCY_PENALTY, 0.5)
    .withParam(PRESENCE_PENALTY, 0.0)
    .withParam(TOP_P, 0.9);

// Custom/arbitrary model by name
var customModel = new OrchestrationAiModel("my-fine-tuned-model",
    java.util.Map.of("temperature", 0.5), "latest");

var config = new OrchestrationModuleConfig().withLlmConfig(tuned);
var client = new OrchestrationClient();
String response = client.chatCompletion(
    new OrchestrationPrompt("Explain recursion in one sentence."), config).getContent();
```

--------------------------------

### Construct OrchestrationPrompt for Chat Completions

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Create prompts for simple strings, multi-message conversations, or templates with variable substitution. Supports message history for multi-turn dialogues and multi-modal content.

```java
import com.sap.ai.sdk.orchestration.*;
import java.util.List;
import java.util.Map;

var client = new OrchestrationClient();
var config = new OrchestrationModuleConfig().withLlmConfig(OrchestrationAiModel.GPT_5_MINI);

// 1. Simple string prompt
var p1 = new OrchestrationPrompt("What is the capital of France?");

// 2. Multi-message prompt
var p2 = new OrchestrationPrompt(
    Message.system("You are a geography expert."),
    Message.user("Name three rivers in Germany.")
);

// 3. Template with variable substitution — define template in config, provide values in prompt
var template = Message.user("Translate '{{?text}}' to {{?language}}.");
var templateConfig = TemplateConfig.create().withMessages(template);
var configWithTemplate = config.withTemplateConfig(templateConfig);
var p3 = new OrchestrationPrompt(Map.of("text", "Good morning", "language", "Spanish"));
String translated = client.chatCompletion(p3, configWithTemplate).getContent();

// 4. Multi-turn conversation with message history
var firstPrompt = new OrchestrationPrompt(Message.user("Tell me about Paris."));
var firstResponse = client.chatCompletion(firstPrompt, config);
var followUp = new OrchestrationPrompt(Message.user("What is its most famous landmark?"))
    .messageHistory(firstResponse.getAllMessages()); // carry forward entire conversation
String landmark = client.chatCompletion(followUp, config).getContent();

// 5. Multi-modal: user message with an image
var imageMsg = Message.user("What is in this image?")
    .withImage("https://example.com/image.jpg", ImageItem.DetailLevel.LOW);
var p5 = new OrchestrationPrompt(imageMsg);

// 6. User message with a file (PDF)
var fileMsg = Message.user("Summarize this document.")
    .withFileUrl("https://example.com/report.pdf", "report.pdf");

```

--------------------------------

### Manage Document Grounding with GroundingClient

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Use GroundingClient to manage vector collections, upload documents, and perform semantic searches. Requires initialization of VectorApi, RetrievalApi, and PipelinesApi.

```java
import com.sap.ai.sdk.grounding.*;
import com.sap.ai.sdk.grounding.client.*;
import com.sap.ai.sdk.grounding.model.*;
import java.util.List;
import java.util.UUID;

var groundingClient = new GroundingClient();
String resourceGroup = "default";

VectorApi vectorApi = groundingClient.vector();
RetrievalApi retrievalApi = groundingClient.retrieval();
PipelinesApi pipelinesApi = groundingClient.pipelines();

// 1. Create a vector collection
var embeddingConfig = EmbeddingConfig.create()
    .modelName("text-embedding-3-small");
var collectionRequest = CollectionRequest.create()
    .embeddingConfig(embeddingConfig)
    .title("my-knowledge-base");
var createResp = vectorApi.createCollection(resourceGroup, collectionRequest);
// Extract UUID from Location header
String collectionId = createResp.getHeaders().get("Location").get(0)
    .replaceAll("^.*?/([a-f0-9-]+)/.*?$", "$1");

// 2. Upload a document with chunks
var chunkMeta = VectorKeyValueListPair.create().key("section").value("introduction");
var chunk = TextOnlyBaseChunkCreate.create()
    .content("SAP AI Core is an enterprise AI platform.")
    .addMetadataItem(chunkMeta);
var docMeta = VectorDocumentKeyValueListPair.create().key("type").value("overview")
    .matchMode(FilterMatchModeEnum.ANY);
var doc = BaseDocument.create().chunks(chunk).addMetadataItem(docMeta);
vectorApi.createDocuments(resourceGroup, UUID.fromString(collectionId),
    DocumentCreateRequest.create().documents(doc));

// 3. Semantic search across repositories
var searchFilter = FiltersInner.create()
    .id("search-1")
    .dataRepositoryType(DataRepositoryType.VECTOR)
    .dataRepositories(List.of("*"))
    .searchConfiguration(RetrievalSearchConfiguration.create().maxChunkCount(5));
var searchInput = RetrievalSearchInput.create()
    .query("What is SAP AI Core?")
    .filters(searchFilter);
var searchResults = retrievalApi.search(resourceGroup, searchInput);
searchResults.getResults().forEach(r ->
    r.getResults().forEach(res ->
        res.getDataRepository().getDocuments().forEach(d ->
            d.getChunks().forEach(chunk2 ->
                System.out.println("Chunk: " + chunk2.getContent())))));

// 4. List all data repositories
var repositories = retrievalApi.getDataRepositories(resourceGroup);
repositories.getResources().forEach(repo ->
    System.out.println("Repository: " + repo.getTitle()));

// 5. List grounding pipelines (MSSharePoint, S3, SFTP)
var pipelines = pipelinesApi.getAllPipelines(resourceGroup, null, 10, 0, true);
System.out.println("Total pipelines: " + pipelines.getResources().size());

```

--------------------------------

### OrchestrationClient.chatCompletion with Fallback Configs

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Demonstrates how to use multiple OrchestrationModuleConfig instances as fallback configurations for chat completion. If the primary configuration fails, the SDK automatically tries the next available configuration.

```APIDOC
## `OrchestrationClient.chatCompletion` with Fallback Configs

Pass multiple `OrchestrationModuleConfig` instances as fallback configurations. If the primary config fails (e.g., model not available), the next config is tried automatically.

```java
import com.sap.ai.sdk.orchestration.*;

var client = new OrchestrationClient();
var prompt = new OrchestrationPrompt("What is the meaning of life?");

// Primary config (intentionally broken to demonstrate fallback)
var primaryConfig = new OrchestrationModuleConfig()
    .withLlmConfig(new OrchestrationAiModel("non-existent-model",
        java.util.Map.of(), "latest"));

// First fallback
var fallback1 = new OrchestrationModuleConfig()
    .withLlmConfig(new OrchestrationAiModel("also-broken", java.util.Map.of(), "latest"));

// Second fallback (working)
var fallback2 = new OrchestrationModuleConfig()
    .withLlmConfig(OrchestrationAiModel.GPT_5_MINI);

// Varargs: primary + any number of fallbacks
OrchestrationChatResponse response = client.chatCompletion(prompt,
    primaryConfig, fallback1, fallback2);
System.out.println(response.getContent()); // answered by GPT_5_MINI fallback

// Fallback also works for streaming
java.util.stream.Stream<String> stream = client.streamChatCompletion(prompt,
    primaryConfig, fallback2);
stream.forEach(System.out::print);
```
```

--------------------------------

### OrchestrationConfigClient Operations

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Demonstrates how to use the OrchestrationConfigClient to create, update, list, and delete orchestration configurations.

```APIDOC
## OrchestrationConfigClient Operations

### Description
This section details the usage of the `OrchestrationConfigClient` for managing server-side orchestration configurations, which bundle LLM and templating settings.

### Methods
- `createUpdateOrchestrationConfig`: Creates a new orchestration configuration or updates an existing one.
- `listOrchestrationConfigs`: Retrieves a list of all available orchestration configurations.
- `deleteOrchestrationConfig`: Deletes a specified orchestration configuration.

### Example Usage (Java)
```java
import com.sap.ai.sdk.prompt.registry.*;
import com.sap.ai.sdk.prompt.registry.model.*;
import java.util.Map;

var orchConfigClient = new OrchestrationConfigClient();

// --- Create an Orchestration Config (LLM + template bundled together) ---
var message = UserChatMessage.create()
    .content(new UserChatMessageContent.InnerString("Paraphrase: {{?phrase}}"))
    .role(UserChatMessage.RoleEnum.USER);
var orchestrationConfig = OrchestrationConfig.create()
    .modules(OrchestrationConfigModules.createInnerModuleConfigs(
        ModuleConfigs.create()
            .promptTemplating(PromptTemplatingModuleConfig.create()
                .prompt(Template.create().template(message))
                .model(LLMModelDetails.create().name("gpt-5-mini")))));

OrchestrationConfigPostResponse orchResp = orchConfigClient.createUpdateOrchestrationConfig(
    OrchestrationConfigPostRequest.create()
        .name("paraphrase-config")
        .version("0.0.1")
        .scenario("my-scenario")
        .spec(orchestrationConfig));
System.out.println("Orch Config ID: " + orchResp.getId());

// --- List and delete orchestration configs ---
OrchestrationConfigListResponse configs = orchConfigClient.listOrchestrationConfigs();
configs.getResources().stream()
    .filter(c -> "paraphrase-config".equals(c.getName()))
    .forEach(c -> orchConfigClient.deleteOrchestrationConfig(c.getId()));
```
```

--------------------------------

### AzureContentFilter - Input and Output Filtering

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Demonstrates how to configure and apply the Azure Content Filter to both the input prompt and the output response to detect and block harmful content.

```APIDOC
## `AzureContentFilter` — Content Filtering

Content filters can be applied to the input (before sending to the LLM) and/or the output (before returning the response). Supported providers: Azure Content Safety and Meta Llama Guard 3.

```java
import com.sap.ai.sdk.orchestration.*;

var client = new OrchestrationClient();
var baseConfig = new OrchestrationModuleConfig().withLlmConfig(OrchestrationAiModel.GPT_5_MINI);

// --- Azure Content Filter ---
var azureFilter = new AzureContentFilter()
    .hate(AzureFilterThreshold.ALLOW_SAFE)          // block all hate content
    .violence(AzureFilterThreshold.ALLOW_SAFE)
    .sexual(AzureFilterThreshold.ALLOW_SAFE_LOW)     // allow safe and low-severity sexual content
    .selfHarm(AzureFilterThreshold.ALLOW_SAFE)
    .promptShield(true)                             // enable prompt injection detection (input only)
    .protectedMaterialCode(true);                   // detect copyrighted code (output only)

var configWithFilter = baseConfig
    .withInputFiltering(azureFilter)
    .withOutputFiltering(azureFilter);

try {
    String answer = client.chatCompletion(
        new OrchestrationPrompt("How do I make a cake?"), configWithFilter).getContent();
    System.out.println(answer);
} catch (OrchestrationFilterException.Input e) {
    System.err.println("Input was blocked by content filter: " + e.getMessage());
} catch (OrchestrationFilterException.Output e) {
    System.err.println("Output was blocked by content filter: " + e.getMessage());
    System.err.println("Filter details: " + e.getFilterDetails());
}
```
```

--------------------------------

### Perform Chat Completion with OpenAI

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/blog/Introducing.md

Use the `OpenAiClient` to perform a chat completion. Ensure you have the necessary model (e.g., GPT_4O_MINI) and provide a system prompt and user message.

```java
var result =
  OpenAiClient.forModel(GPT_4O_MINI)
    .withSystemPrompt("You are a helpful AI")
    .chatCompletion("Hello World! Why is this phrase so famous?");

String resultMessage = result.getContent();
```

--------------------------------

### AI Core Deployments by Config

Source: https://github.com/sap/ai-sdk-java/blob/main/sample-code/spring-app/src/main/resources/static/index.html

Manage Java-specific AI deployments using their configuration IDs.

```APIDOC
## POST /deployments/by-config/[...]/createDelete

### Description
Create and delete a deployment with the Java specific configuration ID.

### Method
POST

### Endpoint
/deployments/by-config/[...]/createDelete
```

```APIDOC
## POST /deployments/by-config/[...]/stop

### Description
Stop all deployments with the Java specific configuration ID. Only RUNNING deployments can be STOPPED.

### Method
POST

### Endpoint
/deployments/by-config/[...]/stop
```

```APIDOC
## POST /deployments/by-config/[...]/delete

### Description
Delete all deployments with the Java specific configuration ID. Only UNKNOWN and STOPPED deployments can be DELETED.

### Method
POST

### Endpoint
/deployments/by-config/[...]/delete
```

```APIDOC
## GET /deployments/by-config/[...]/getAll

### Description
Get all deployments with the Java specific configuration ID.

### Method
GET

### Endpoint
/deployments/by-config/[...]/getAll
```

--------------------------------

### Exception Logging with SLF4J

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/adrs/006-logging-strategy.md

Demonstrates the correct way to log exceptions using SLF4J's standard methods, passing the exception object directly to avoid potential sensitive data exposure through serialization.

```java
log.debug("Connection lost.", exception);
```

--------------------------------

### Granular MDC Clearing in Java

Source: https://github.com/sap/ai-sdk-java/blob/main/docs/adrs/006-logging-strategy.md

Illustrates the correct way to clear specific MDC entries versus clearing the entire context. Always clear entries key-by-key to preserve unrelated context items.

```java
// Bad: Risk clearing useful context entries from other components
MDC.clear();

// Good: Clear only your own entries, centralized in utility class
class RequestLogContext { 
   //...
   static void clear(){
    MDC.remove(MdcKeys.CALL_ID);
    MDC.remove(MdcKeys.SERVICE);
  }
}
```

--------------------------------

### Configuring Orchestration Pipeline with OrchestrationModuleConfig

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Build a comprehensive pipeline configuration using `OrchestrationModuleConfig`. Chain multiple modules for LLM settings, input/output filtering, masking, grounding, and translation.

```java
import com.sap.ai.sdk.orchestration.*;

// Chain multiple configuration modules together (each `with*` returns a new instance)
var config = new OrchestrationModuleConfig()
    .withLlmConfig(OrchestrationAiModel.GPT_5_MINI
        .withParam(OrchestrationAiModel.Parameter.MAX_TOKENS, 500)
        .withParam(OrchestrationAiModel.Parameter.TEMPERATURE, 0.3))
    .withInputFiltering(
        new AzureContentFilter().hate(AzureFilterThreshold.ALLOW_SAFE).violence(AzureFilterThreshold.ALLOW_SAFE))
    .withOutputFiltering(
        new AzureContentFilter().hate(AzureFilterThreshold.ALLOW_SAFE).violence(AzureFilterThreshold.ALLOW_SAFE))
    .withMaskingConfig(
        DpiMasking.anonymization().withEntities(
            com.sap.ai.sdk.orchestration.model.DPIEntities.PERSON,
            com.sap.ai.sdk.orchestration.model.DPIEntities.EMAIL))
    .withGrounding(
        Grounding.create().filters(
            com.sap.ai.sdk.orchestration.model.DocumentGroundingFilter.create()
                .dataRepositoryType(com.sap.ai.sdk.orchestration.model.DataRepositoryType.VECTOR)))
    .withInputTranslationConfig(
        TranslationConfig.translateInputTo("en-US").withSourceLanguage("de-DE"))
    .withOutputTranslationConfig(
        TranslationConfig.translateOutputTo("de-DE").withSourceLanguage("en-US"));

// Use config in a chat completion
var client = new OrchestrationClient();
var prompt = new OrchestrationPrompt("Was ist die Hauptstadt von Deutschland?");
String answer = client.chatCompletion(prompt, config).getContent();
System.out.println(answer); // Response translated back to German
```

--------------------------------

### AI Core All Deployments

Source: https://github.com/sap/ai-sdk-java/blob/main/sample-code/spring-app/src/main/resources/static/index.html

Retrieve all deployments, including non-Java specific ones.

```APIDOC
## GET /deployments/getAll

### Description
Get all deployments, including non-Java specific deployments.

### Method
GET

### Endpoint
/deployments/getAll
```

--------------------------------

### Use Prompt Templates with OrchestrationClient

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Define reusable prompt templates with variable placeholders, control JSON response format, and reference externally stored templates from the Prompt Registry.

```java
import com.sap.ai.sdk.orchestration.*;
import java.util.Map;

var client = new OrchestrationClient();
var baseConfig = new OrchestrationModuleConfig().withLlmConfig(OrchestrationAiModel.GPT_5_MINI);

// --- Inline template with variables ---
var template = TemplateConfig.create().withMessages(
    Message.system("You are a translator. Translate to {{?language}}."),
    Message.user("{{?input}}")
);
var configWithTemplate = baseConfig.withTemplateConfig(template);
var prompt = new OrchestrationPrompt(Map.of("language", "Italian", "input", "Good morning"));
System.out.println(client.chatCompletion(prompt, configWithTemplate).getContent());

// --- JSON object response format ---
var jsonConfig = baseConfig.withTemplateConfig(
    TemplateConfig.create()
        .withMessages(Message.user("What is 'Apple' in French?"))
        .withJsonResponse() // tells LLM to respond in JSON
);
var jsonPrompt = new OrchestrationPrompt(
    Message.system("Reply as JSON: {\"word\": ..., \"translation\": ...}"));
System.out.println(client.chatCompletion(jsonPrompt, jsonConfig).getContent());

// --- Reference template stored in Prompt Registry by ID (tenant-level) ---
var refByIdConfig = baseConfig.withTemplateConfig(
    TemplateConfig.reference().byId("21cb1358-0bf1-4f43-870b-00f14d0f9f16")
);
var refPrompt = new OrchestrationPrompt(Map.of("language", "Italian", "input", "AI features"));
System.out.println(client.chatCompletion(refPrompt, refByIdConfig).getContent());

// --- Reference template by scenario/name/version (resource-group scope) ---
var refByScenarioConfig = baseConfig.withTemplateConfig(
    TemplateConfig.reference()
        .byScenario("categorization")
        .name("example-prompt-template")
        .version("0.0.1")
        .withScope(com.sap.ai.sdk.orchestration.OrchestrationTemplateReference.ScopeEnum.RESOURCE_GROUP)
);

```

--------------------------------

### TemplateConfig

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Explains how to use `TemplateConfig` for defining reusable prompt templates with variable placeholders, controlling JSON response formats, and referencing templates stored in the Prompt Registry.

```APIDOC
## `TemplateConfig` — Prompt Templates (Inline and Registry-Referenced)

`TemplateConfig` defines reusable prompt templates with variable placeholders (`{{?varName}}`), JSON response format control, and references to externally stored templates in the Prompt Registry.

```java
import com.sap.ai.sdk.orchestration.*;
import java.util.Map;

var client = new OrchestrationClient();
var baseConfig = new OrchestrationModuleConfig().withLlmConfig(OrchestrationAiModel.GPT_5_MINI);

// --- Inline template with variables ---
var template = TemplateConfig.create().withMessages(
    Message.system("You are a translator. Translate to {{?language}}."),
    Message.user("{{?input}}")
);
var configWithTemplate = baseConfig.withTemplateConfig(template);
var prompt = new OrchestrationPrompt(Map.of("language", "Italian", "input", "Good morning"));
System.out.println(client.chatCompletion(prompt, configWithTemplate).getContent());

// --- JSON object response format ---
var jsonConfig = baseConfig.withTemplateConfig(
    TemplateConfig.createМа()
        .withMessages(Message.user("What is 'Apple' in French?"))
        .withJsonResponse() // tells LLM to respond in JSON
);
var jsonPrompt = new OrchestrationPrompt(
    Message.system("Reply as JSON: {\"word\": ..., \"translation\": ...}"));
System.out.println(client.chatCompletion(jsonPrompt, jsonConfig).getContent());

// --- Reference template stored in Prompt Registry by ID (tenant-level) ---
var refByIdConfig = baseConfig.withTemplateConfig(
    TemplateConfig.reference().byId("21cb1358-0bf1-4f43-870b-00f14d0f9f16")
);
var refPrompt = new OrchestrationPrompt(Map.of("language", "Italian", "input", "AI features"));
System.out.println(client.chatCompletion(refPrompt, refByIdConfig).getContent());

// --- Reference template by scenario/name/version (resource-group scope) ---
var refByScenarioConfig = baseConfig.withTemplateConfig(
    TemplateConfig.reference()
        .byScenario("categorization")
        .name("example-prompt-template")
        .version("0.0.1")
        .withScope(com.sap.ai.sdk.orchestration.OrchestrationTemplateReference.ScopeEnum.RESOURCE_GROUP)
);
```
```

--------------------------------

### Maven Dependencies for SAP Cloud SDK for AI

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Add these dependencies to your pom.xml to include specific modules of the SAP Cloud SDK for AI. The orchestration module is recommended as the primary entry point.

```xml
<!-- Orchestration (chat completion, filtering, grounding, masking, translation) -->
<dependency>
    <groupId>com.sap.ai.sdk</groupId>
    <artifactId>orchestration</artifactId>
    <version>1.3.0</version>
</dependency>

<!-- Direct OpenAI access -->
<dependency>
    <groupId>com.sap.ai.sdk.foundationmodels</groupId>
    <artifactId>openai</artifactId>
    <version>1.3.0</version>
</dependency>

<!-- AI Core management APIs (deployments, configurations, executions) -->
<dependency>
    <groupId>com.sap.ai.sdk</groupId>
    <artifactId>core</artifactId>
    <version>1.3.0</version>
</dependency>

<!-- Document grounding / vector store -->
<dependency>
    <groupId>com.sap.ai.sdk</groupId>
    <artifactId>document-grounding</artifactId>
    <version>1.3.0</version>
</dependency>

<!-- Prompt Registry -->
<dependency>
    <groupId>com.sap.ai.sdk</groupId>
    <artifactId>prompt-registry</artifactId>
    <version>1.3.0</version>
</dependency>
```

--------------------------------

### OpenAiClient - Image Input for Chat Completion

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Demonstrates how to include image data in a chat completion request.

```APIDOC
### Image input
```java
// ... other imports

var imageMsg = OpenAiMessage.user("Describe this image.")
    .withImage("https://example.com/photo.jpg", OpenAiImageItem.DetailLevel.HIGH);
OpenAiChatCompletionResponse imgResponse = OpenAiClient.forModel(OpenAiModel.GPT_4O)
    .chatCompletion(new OpenAiChatCompletionRequest(imageMsg));
```
```

--------------------------------

### Basic Chat Completion with OpenAI

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Perform a basic chat completion request to an OpenAI model. Ensure the model is deployed on SAP AI Core.

```java
import com.sap.ai.sdk.foundationmodels.openai.*;
import com.sap.ai.sdk.core.AiCoreService;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Stream;

// --- Basic chat completion ---
OpenAiChatCompletionResponse response = OpenAiClient.forModel(OpenAiModel.GPT_5_MINI)
    .chatCompletion(new OpenAiChatCompletionRequest("Explain Java records briefly."));
System.out.println(response.getContent());
```

--------------------------------

### Chat Completion with Fallback Configurations

Source: https://context7.com/sap/ai-sdk-java/llms.txt

Pass multiple OrchestrationModuleConfig instances as fallback configurations. If the primary config fails, the next config is tried automatically. Fallback also works for streaming.

```java
import com.sap.ai.sdk.orchestration.*;

var client = new OrchestrationClient();
var prompt = new OrchestrationPrompt("What is the meaning of life?");

// Primary config (intentionally broken to demonstrate fallback)
var primaryConfig = new OrchestrationModuleConfig()
    .withLlmConfig(new OrchestrationAiModel("non-existent-model",
        java.util.Map.of(), "latest"));

// First fallback
var fallback1 = new OrchestrationModuleConfig()
    .withLlmConfig(new OrchestrationAiModel("also-broken", java.util.Map.of(), "latest"));

// Second fallback (working)
var fallback2 = new OrchestrationModuleConfig()
    .withLlmConfig(OrchestrationAiModel.GPT_5_MINI);

// Varargs: primary + any number of fallbacks
OrchestrationChatResponse response = client.chatCompletion(prompt,
    primaryConfig, fallback1, fallback2);
System.out.println(response.getContent()); // answered by GPT_5_MINI fallback

// Fallback also works for streaming
java.util.stream.Stream<String> stream = client.streamChatCompletion(prompt,
    primaryConfig, fallback2);
stream.forEach(System.out::print);
```

--------------------------------

### AI Core Configurations

Source: https://github.com/sap/ai-sdk-java/blob/main/sample-code/spring-app/src/main/resources/static/index.html

Endpoint to retrieve the list of available configurations.

```APIDOC
## GET /configurations

### Description
Get the list of configurations.

### Method
GET

### Endpoint
/configurations
```