### Create Prompt and Get Completion (Java)

Source: https://sap.github.io/ai-sdk/docs/java/getting-started

This Java code snippet illustrates how to create a prompt for the AI model and then use the `OrchestrationClient` to get a chat completion response from the configured AI model.

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

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

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

### Run Spring Boot Application with Maven

Source: https://sap.github.io/ai-sdk/docs/java/getting-started

This command shows how to run a Spring Boot application locally using Maven. It assumes you are in the application's directory and have set up the necessary environment variables.

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

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

### Initialize Orchestration Client (Java)

Source: https://sap.github.io/ai-sdk/docs/java/getting-started

This Java code snippet demonstrates how to create an instance of the `OrchestrationClient`, which is used to interact with the AI Core Orchestration service.

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

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

### Set AI Core Service Key Environment Variable (Bash)

Source: https://sap.github.io/ai-sdk/docs/java/getting-started

This bash command demonstrates how to set the `AICORE_SERVICE_KEY` environment variable, which is required for authenticating your application with the AI Core service instance when running locally.

```bash
export AICORE_SERVICE_KEY='{ "clientid": "...", "clientsecret": "...", "url": "...", "serviceurls": { "AI_API_URL": "..." } }'
```

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

### Example AI Core Configuration

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/ai-core-deployment

This JSON object represents an example configuration for SAP AI Core. It includes details like executable ID, name, and parameter bindings for a model.

```json
{
  "createdAt": "2024-07-03T12:44:08Z",
  "executableId": "azure-openai",
  "id": "12345-123-123-123-123456abcdefg",
  "inputArtifactBindings": [],
  "name": "gpt-4o-mini",
  "parameterBindings": [
    {
      "key": "modelName",
      "value": "gpt-4o-mini"
    },
    {
      "key": "modelVersion",
      "value": "latest"
    }
  ],
  "scenarioId": "foundation-models"
}
```

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

### Configure AI Model (Java)

Source: https://sap.github.io/ai-sdk/docs/java/getting-started

This Java code snippet shows how to configure the orchestration module to use a specific AI model, in this case, the OpenAI GPT-4o model.

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

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

### Pipeline API

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

Manage pipelines for data ingestion, including reading, creating, and getting the status of pipelines.

```APIDOC
## GET /pipelines

### Description
Retrieves all pipelines for a given resource group.

### Method
GET

### Endpoint
`/pipelines`

### Parameters
#### Path Parameters
- **resourceGroupId** (string) - Required - The ID of the resource group.

### Response
#### Success Response (200)
- **pipelines** (Pipelines) - A list of pipelines.

#### Response Example
```json
{
  "pipelines": [
    {
      "pipelineId": "pipeline-123",
      "type": "MSSharePoint",
      "status": "RUNNING"
    }
  ]
}
```

## POST /pipelines

### Description
Creates a new pipeline for data ingestion.

### Method
POST

### Endpoint
`/pipelines`

### Parameters
#### Path Parameters
- **resourceGroupId** (string) - Required - The ID of the resource group.

#### Request Body
- **type** (string) - Required - The type of the pipeline (e.g., "MSSharePoint", "S3", "SFTP").
- **configuration** (PipelinePostRequstConfiguration) - Required - Configuration details for the pipeline.

### Request Example
```json
{
  "type": "MSSharePoint",
  "configuration": {
    "destination": "my-secret-name"
  }
}
```

### Response
#### Success Response (200)
- **pipelineId** (string) - The ID of the newly created pipeline.

#### Response Example
```json
{
  "pipelineId": "pipeline-456"
}
```

## GET /pipelines/{pipelineId}/status

### Description
Retrieves the status of a specific pipeline.

### Method
GET

### Endpoint
`/pipelines/{pipelineId}/status`

### Parameters
#### Path Parameters
- **resourceGroupId** (string) - Required - The ID of the resource group.
- **pipelineId** (string) - Required - The ID of the pipeline.

### Response
#### Success Response (200)
- **status** (string) - The current status of the pipeline (e.g., "RUNNING", "COMPLETED", "FAILED").

#### Response Example
```json
{
  "status": "RUNNING"
}
```
```

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

### Java Mock Restaurant Tool for Agentic Workflows

Source: https://sap.github.io/ai-sdk/docs/java/tutorials/agentic-workflows

Defines a mock tool to recommend restaurants based on a city. It includes request and response records and a static method annotated with @Tool for integration with agentic workflows. Dependencies include Java's List and Map, along with SAP AI SDK's @Tool and @ToolParam annotations.

```java
class RestaurantMethod {
  
  /**
   * Request for list of restaurants
   *
   * @param location the city
   */
  record Request(String location) {}

  /**
   * Response for restaurant recommendations
   *
   * @param restaurants the list of restaurants
   */
  record Response(List<String> restaurants) {}

  @Nonnull
  @Tool(description = "Get recommended restaurants for a location")
  static RestaurantMethod.Response getRestaurants(
      @ToolParam @Nonnull final RestaurantMethod.Request request) {
    var recommendations =
        Map.of(
            "paris",
            List.of("Le Comptoir du Relais", "L'As du Fallafel", "Breizh Café"),
            "reykjavik",
            List.of("Dill Restaurant", "Fish Market", "Grillmarkaðurinn"));
    return new RestaurantMethod.Response(
        recommendations.getOrDefault(
            request.location.toLowerCase(Locale.ROOT), List.of("No recommendations for this city.")));
  }
}
```

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

### Grounding AI Models with help.sap.com Java

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

This example demonstrates how to configure grounding for AI models using SAP-specific information from help.sap.com. It utilizes the `DocumentGroundingFilter` with the `HELP_SAP_COM` data repository type.

```Java
var groundingHelpSapCom =  
        DocumentGroundingFilter.create()  
                .dataRepositoryType(DataRepositoryType.HELP_SAP_COM);
var groundingConfig = Grounding.create().filters(groundingHelpSapCom);
var configWithGrounding = config.withGrounding(groundingConfig);  

var prompt = groundingConfig.createGroundingPrompt("What is a fuzzy search?");  
var response = client.chatCompletion(prompt, configWithGrounding);
```

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

### Spring AI Prompt Template Usage Example

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

Demonstrates initializing a Spring AI ChatClient with memory and advisors, then using a PromptClient to process a named prompt template with input parameters and generate a response.

```java
OpenAiClient openAiClient = OpenAiClient.forModel(OpenAiModel.GPT_4O_MINI);
ChatModel client = new OpenAiChatModel(openAiClient);

var repository = new InMemoryChatMemoryRepository();
var memory = MessageWindowChatMemory.builder().chatMemoryRepository(repository).build();
var advisor = MessageChatMemoryAdvisor.builder(memory).build();
var cl = ChatClient.builder(client).defaultAdvisors(advisor).build();

var promptResponse =
        new PromptClient()
            .parsePromptTemplateByNameVersion(
                "scenario",
                "0.0.1",
                "template_name",
                "resource-group",// usually "default"
                false,
                PromptTemplateSubstitutionRequest.create()
                    .inputParams(Map.of("parameter1", "value1")));

List<Message> messages = SpringAiConverter.promptTemplateToMessages(promptResponse);
var prompt = new Prompt(messages);

Generation response = cl.prompt(prompt).call().chatResponse().getResult();
```

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

### Add SAP AI SDK Orchestration Dependency (Maven)

Source: https://sap.github.io/ai-sdk/docs/java/getting-started

This snippet shows how to add the SAP AI SDK orchestration dependency to your Maven project's `pom.xml` file. It specifies the group ID, artifact ID, and the version to be used.

```xml
<dependency>
    <groupId>com.sap.ai.sdk</groupId>
    <artifactId>orchestration</artifactId>
    <!-- Use the latest version here -->
    <version>${ai-sdk.version}</version>
</dependency>
```

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

### Get Prompt Templates

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

Retrieves a list of all prompt templates.

```APIDOC
## GET /prompt-template

### Description
Retrieves a list of all prompt templates.

### Method
GET

### Endpoint
`/prompt-template`

### Response
#### Success Response (200)
- **templates** (array) - A list of prompt templates.
  - **id** (string) - The unique identifier of the prompt template.
  - **name** (string) - The name of the prompt template.
  - **version** (string) - The version of the prompt template.
  - **scenario** (string) - The scenario associated with the prompt template.

#### Response Example
```json
{
  "templates": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "name": "template-name",
      "version": "0.0.1",
      "scenario": "categorization"
    }
  ]
}
```
```

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

### Get a List of Prompt Templates using Java

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

This Java snippet demonstrates how to retrieve a list of all available prompt templates. It uses the `listPromptTemplates` method of the `PromptClient`.

```java
PromptClient client = new PromptClient();

PromptTemplateListResponse templates = client.listPromptTemplates();
```

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

### Java Spring Service for Agentic Workflows

Source: https://sap.github.io/ai-sdk/docs/java/tutorials/agentic-workflows

Sets up a Spring service to run agentic workflows using SAP AI SDK and Spring AI. It configures a chat model, memory, and advisors, then integrates mock tools (WeatherMethod and RestaurantMethod). The `runAgent` method initiates the workflow with user input. Requires Spring annotations like @Service and SAP AI SDK components.

```java
@Service
public class SpringAiAgenticWorkflowService {
  private final ChatModel client = new OrchestrationChatModel();
  private final OrchestrationModuleConfig config =
      new OrchestrationModuleConfig().withLlmConfig(GPT_4O_MINI);
  
  public ChatResponse runAgent(String userInput) {

    //    Configure chat memory
    var memory = new InMemoryChatMemory();
    var advisor = new MessageChatMemoryAdvisor(memory);
    var cl = ChatClient.builder(client).defaultAdvisors(advisor).build();
  
    //    Add (mocked) tools
    var options = new OrchestrationChatOptions(config);
    options.setToolCallbacks(
        List.of(ToolCallbacks.from(new WeatherMethod(), new RestaurantMethod())));
    options.setInternalToolExecutionEnabled(true);
  
    //    The actual agentic workflow will be added here.
  
    return null;
  }
}
```

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

### Search Documents with Retrieval API (Java)

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

This Java code demonstrates searching for relevant document grounding data using the Retrieval API. It includes setting up search filters, specifying a query, and executing the search.

```java
var api = new GroundingClient().retrieval();
var resourceGroupId = "default";

var filter = 
    RetrievalSearchFilter.create() 
        .id("question") 
        .dataRepositoryType(DataRepositoryType.VECTOR) 
        .dataRepositories(List.of("* ")) 
        .searchConfiguration(SearchConfiguration.create().maxChunkCount(10));
var search = RetrievalSearchInput.create().query("What is SAP Cloud SDK for AI?").filters(filter);
RetievalSearchResults results = api.search(resourceGroupId, search);
```

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

### Java Method to Run Agentic Workflow

Source: https://sap.github.io/ai-sdk/docs/java/tutorials/agentic-workflows

Demonstrates how to execute the agentic workflow by calling the `runAgent` method of the `SpringAiAgenticWorkflowService`. It takes user input as a String and returns the processed response.

```java
@Autowired
private SpringAiAgenticWorkflowService service;

String runChainWorkflow() {
  final var response = service.runAgent("I want to do a one-day trip to Paris. Help me make an itinerary, please");
  return response;
}
```

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

### Grounding via Orchestration

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

Utilize the grounding service via orchestration with configurable filters and LLM settings.

```APIDOC
## POST /chat/completion

### Description
Performs a chat completion using a configured prompt and grounding settings.

### Method
POST

### Endpoint
`/chat/completion`

### Parameters
#### Request Body
- **prompt** (OrchestrationPrompt) - Required - The prompt for the chat completion.
  - **inputParams** (Map<string, string>) - Required - Input parameters for the prompt.
  - **systemMessage** (string) - Required - The system message, potentially including grounding results.
- **configuration** (OrchestrationModuleConfig) - Required - Configuration for the orchestration, including grounding settings.
  - **llmConfig** (object) - Required - LLM configuration (e.g., GPT_4O).
  - **groundingConfig** (GroundingModuleConfig) - Optional - Grounding service configuration.
    - **type** (string) - Required - Type of grounding module (e.g., "DOCUMENT_GROUNDING_SERVICE").
    - **config** (GroundingModuleConfigConfig) - Required - Specific configuration for the grounding module.
      - **inputParams** (List<string>) - Required - Input parameters for grounding.
      - **outputParam** (string) - Required - Output parameter name for grounding results.
      - **filters** (List<DocumentGroundingFilter>) - Optional - Filters for grounding.
        - **dataRepositoryType** (string) - Optional - Type of data repository (e.g., "VECTOR").
        - **searchConfig** (GroundingFilterSearchConfiguration) - Optional - Search configuration for filters.
          - **maxChunkCount** (integer) - Optional - Maximum number of chunks to retrieve.

### Request Example
```json
{
  "prompt": {
    "inputParams": {
      "query": "What is SAP Cloud SDK for AI?"
    },
    "systemMessage": "Context message with embedded grounding results. {{?results}}"
  },
  "configuration": {
    "llmConfig": "GPT_4O",
    "groundingConfig": {
      "type": "DOCUMENT_GROUNDING_SERVICE",
      "config": {
        "inputParams": ["query"],
        "outputParam": "results",
        "filters": [
          {
            "dataRepositoryType": "VECTOR",
            "searchConfig": {
              "maxChunkCount": 3
            }
          }
        ]
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **response** (OrchestrationChatResponse) - The chat completion response, potentially including grounding results.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "SAP Cloud SDK for AI is a tool that helps integrate AI services into your applications. It allows you to leverage features like document grounding to find relevant information."
      }
    }
  ]
}
```
```

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

### Document Grounding Pipeline Creation in Java

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

Enhances the `PipelineApi` with new pipeline creation requests: `SDMPipelineCreateRequest` and `WorkZonePipelineCreateRequest`. This allows for easier setup of document grounding pipelines for various data sources.

```Java
pipelinesApi.createPipeline(new SDMPipelineCreateRequest(...));
pipelinesApi.createPipeline(new WorkZonePipelineCreateRequest(...));
```

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

### Java Agentic Workflow Implementation with Spring AI

Source: https://sap.github.io/ai-sdk/docs/java/tutorials/agentic-workflows

Implements a chain-like agentic workflow using SAP AI SDK. It configures a chat client with memory, advisors, and tools (WeatherMethod, RestaurantMethod). The workflow iterates through system prompts, using the previous LLM output as input for the next, and returns the final response.

```java
@Service
public class SpringAiAgenticWorkflowService {
  private final ChatModel client = new OrchestrationChatModel();
  private final OrchestrationModuleConfig config =
      new OrchestrationModuleConfig().withLlmConfig(GPT_4O_MINI);

  @Nonnull
  public String runAgent(String userInput) {

    //    Configure chat memory
    val repository = new InMemoryChatMemoryRepository();
    val memory = MessageWindowChatMemory.builder().chatMemoryRepository(repository).build();
    val advisor = MessageChatMemoryAdvisor.builder(memory).build();
    var cl = ChatClient.builder(client).defaultAdvisors(advisor).build();

    //    Add (mocked) tools
    var options = new OrchestrationChatOptions(config);
    options.setToolCallbacks(
        List.of(ToolCallbacks.from(new WeatherMethod(), new RestaurantMethod())));
    options.setInternalToolExecutionEnabled(true);

    //    Prompts for the chain workflow
    List<String> systemPrompts =
        List.of(
            "You are a traveling planning agent for a single day trip. Where appropriate, use the provided tools. First, start by suggesting some restaurants for the mentioned city.",
            "Now, check the whether for the city.",
            "Finally, combine the suggested itinerary from this conversation into a short, one-sentence plan for the day trip.");

    //    Perform the chain workflow
    String responseText = userInput;

    for (String systemPrompt : systemPrompts) {

      // Combine the pre-defined prompt with the previous answer to get the new input
      String input = String.format("{%s}\n {%s}", systemPrompt, responseText);
      var prompt = new Prompt(input, options);

      // Make a call to the LLM with the new input
      var response =
          Objects.requireNonNull(
              cl.prompt(prompt).call().chatResponse(), "Chat response is null.");
      responseText = response.getResult().getOutput().getText();
    }

    return responseText;
  }
}
```

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

### Vector API

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

Ingest documents into the vector database for retrieval.

```APIDOC
## POST /collections/{collectionId}/documents

### Description
Ingests documents into a specified collection in the vector database.

### Method
POST

### Endpoint
`/collections/{collectionId}/documents`

### Parameters
#### Path Parameters
- **resourceGroupId** (string) - Required - The ID of the resource group.
- **collectionId** (UUID) - Required - The ID of the collection to ingest documents into.

#### Request Body
- **documents** (BaseDocument) - Required - A list of documents to ingest. Each document can contain chunks with content and metadata.

### Request Example
```json
{
  "documents": [
    {
      "chunks": [
        {
          "content": "The dog makes _woof_",
          "metadata": [
            {
              "key": "animal",
              "value": "dog"
            }
          ]
        }
      ],
      "metadata": [
        {
          "key": "topic",
          "value": "sound"
        }
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **response** (DocumentsListResponse) - Confirmation of document ingestion.

#### Response Example
```json
{
  "message": "Documents ingested successfully."
}
```
```

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

### Retrieval API

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

Search for relevant document grounding data based on a query with optional filters.

```APIDOC
## POST /search

### Description
Searches for relevant document grounding data based on a query and filters.

### Method
POST

### Endpoint
`/search`

### Parameters
#### Path Parameters
- **resourceGroupId** (string) - Required - The ID of the resource group.

#### Request Body
- **query** (string) - Required - The search query.
- **filters** (RetrievalSearchFilter) - Optional - Filters to refine the search.
  - **id** (string) - Optional - Filter by document ID.
  - **dataRepositoryType** (string) - Optional - Filter by data repository type (e.g., "VECTOR").
  - **dataRepositories** (List<string>) - Optional - List of data repositories to search within.
  - **searchConfiguration** (SearchConfiguration) - Optional - Configuration for the search.
    - **maxChunkCount** (integer) - Optional - Maximum number of chunks to return.

### Request Example
```json
{
  "query": "What is SAP Cloud SDK for AI?",
  "filters": {
    "id": "question",
    "dataRepositoryType": "VECTOR",
    "dataRepositories": ["*"],
    "searchConfiguration": {
      "maxChunkCount": 10
    }
  }
}
```

### Response
#### Success Response (200)
- **results** (RetievalSearchResults) - The search results containing relevant document grounding data.

#### Response Example
```json
{
  "results": [
    {
      "chunk": {
        "content": "SAP Cloud SDK for AI helps integrate AI services.",
        "metadata": [
          {"key": "topic", "value": "AI"}
        ]
      },
      "score": 0.95
    }
  ]
}
```
```

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

### Java Mock Weather Tool for Agentic Workflows

Source: https://sap.github.io/ai-sdk/docs/java/tutorials/agentic-workflows

Defines a mock tool to retrieve weather information for a given city and temperature unit. It includes an enum for temperature units, and request/response records for weather data. The tool's current weather method is annotated with @Tool for agentic workflow integration. Requires Java's enum and record features.

```java
class WeatherMethod {
  
  /** Unit of temperature */
  enum Unit {
    /** Celsius */
    C,
    /** Fahrenheit */
    F
  }
  
  /**
   * Request for the weather
   *
   * @param location the city
   * @param unit the unit of temperature
   */
  record Request(String location, Unit unit) {}
  
  /**
   * Response for the weather
   *
   * @param temp the temperature
   * @param unit the unit of temperature
   */
  record Response(double temp, Unit unit) {}
  
  @Nonnull
  @Tool(description = "Get the weather in location")
  static Response getCurrentWeather(@ToolParam @Nonnull final Request request) {
    final int temperature = request.location.hashCode() % 30;
    return new Response(temperature, request.unit);
  }
}
```

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

### Grounding AI Models with Vector Data Repository Java

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

This example demonstrates how to configure grounding for an AI model using a vector data repository. It includes optional filters for collections and document chunks, specifying metadata and repository type.

```Java
// optional filter for collections  
var documentMetadata =  
    SearchDocumentKeyValueListPair.create()  
        .key("my-collection")  
        .value("value")  
        .addSelectModeItem(SearchSelectOptionEnum.IGNORE_IF_KEY_ABSENT);
// optional filter for document chunks  
var databaseFilter =  
    DocumentGroundingFilter.create()  
        .id("")  
        .dataRepositoryType(DataRepositoryType.VECTOR)  
        .addDocumentMetadataItem(documentMetadata);

var groundingConfig = Grounding.create().filter(databaseFilter);
var prompt = groundingConfig.createGroundingPrompt("What does Joule do?");  
var configWithGrounding = config.withGrounding(groundingConfig);

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

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

### Grounding AI Models with SharePoint Java

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

This example illustrates how to use files stored in SharePoint as a source for grounding AI models. It involves adding the SharePoint's data repository ID to the `DocumentGroundingFilter`.

```Java
var dataRepositoryId = "SharePoint ID here";  
var filter =  
    DocumentGroundingFilter.create()  
        .dataRepositoryType(DataRepositoryType.VECTOR)  
        .dataRepositories(List.of(dataRepositoryId));  
var groundingConfig = Grounding.create().filters(filter);
var prompt = groundingConfig.createGroundingPrompt("What is the information stored in the sharepoint?");  
var configWithGrounding = config.withGrounding(groundingConfig);
var result = client.chatCompletion(prompt, configWithGrounding);
```

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

### Manage Pipelines in SAP Document Grounding (Java)

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

This Java code demonstrates how to interact with the Pipeline API for SAP Document Grounding. It covers fetching all pipelines, creating a new pipeline with a specified type and secret, and retrieving the status of a created pipeline.

```java
var api = new GroundingClient().pipelines();
var resourceGroupId = "default";

// get all pipelines
Pipelines pipelines = api.getAllPipelines(resourceGroupId);

// create new pipeline
var type = "MSSharePoint"; // or "S3" or "SFTP"
var pipelineSecret = "my-secret-name";
var config = PipelinePostRequstConfiguration.create().destination(pipelineSecret);
var request = PipelinePostRequst.create().type(type)._configuration(config);
PipelineId pipeline = api.createPipeline(resourceGroupId, request);

// get pipeline status
PipelineStatus status = api.getPipelineStatus(resourceGroupId, pipeline.getPipelineId());
```

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

### Initialize Orchestration Client for Custom Resource Group

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

This example demonstrates how to initialize an OrchestrationClient when using a custom resource group. It involves retrieving an inference destination specific to the resource group and scenario.

```java
var destination = new AiCoreService().getInferenceDestination("myResourceGroup").forScenario("orchestration");
var client = new OrchestrationClient(destination);
```

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

### Grounding via Orchestration (Java)

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

This Java code shows how to perform grounding through orchestration. It configures an orchestration client with document grounding settings, including filters and input/output parameters, and then makes a chat completion request.

```java
OrchestrationClient client;

var databaseFilter = 
    DocumentGroundingFilter.create() 
        .dataRepositoryType(DataRepositoryType.VECTOR) 
        .searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(3));
var groundingConfigConfig = 
    GroundingModuleConfigConfig.create() 
        .inputParams(List.of("query")) 
        .outputParam("results") 
        .addFiltersItem(databaseFilter);
var groundingConfig = 
    GroundingModuleConfig.create() 
        .type(GroundingModuleConfig.TypeEnum.DOCUMENT_GROUNDING_SERVICE) 
        .config(groundingConfigConfig);
var configWithGrounding = 
    new OrchestrationModuleConfig() 
        .withLlmConfig(GPT_4O) 
        .withGroundingConfig(groundingConfig);

var inputParams = Map.of("query", "What is SAP Cloud SDK for AI?");

var prompt = 
    new OrchestrationPrompt(
        inputParams,
        Message.system("Context message with embedded grounding results. {{?results}}"));

OrchestrationChatResponse response = client.chatCompletion(prompt, configWithGrounding);
```

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

### Example Deployed OpenAI Model from AI Core

Source: https://sap.github.io/ai-sdk/docs/java/foundation-models/openai/chat-completion

This JSON object represents a deployed OpenAI model in SAP AI Core, including its ID, deployment URL, and configuration details. This information is needed to connect the SDK to your deployed model.

```json
{
  "id": "d123456abcdefg",
  "deploymentUrl": "https://api.ai.region.aws.ml.hana.ondemand.com/v2/inference/deployments/d123456abcdefg",
  "configurationId": "12345-123-123-123-123456abcdefg",
  "configurationName": "gpt-4o-mini",
  "scenarioId": "foundation-models",
  "status": "RUNNING",
  "statusMessage": null,
  "targetStatus": "RUNNING",
  "lastOperation": "CREATE",
  "latestRunningConfigurationId": "12345-123-123-123-123456abcdefg",
  "ttl": null,
  "details": {
    "scaling": {
      "backendDetails": {}
    },
    "resources": {
      "backendDetails": {
        "model": {
          "name": "gpt-4o-mini",
          "version": "latest"
        }
      }
    }
  },
  "createdAt": "2024-07-03T12:44:22Z",
  "modifiedAt": "2024-07-16T12:44:19Z",
  "submissionTime": "2024-07-03T12:44:51Z",
  "startTime": "2024-07-03T12:45:56Z",
  "completionTime": null
}
```

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

### Mask Grounding and Prompt with Sensitive Data

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

This example demonstrates how to mask sensitive data and grounding information in a prompt using the DpiMasking and DPIEntities classes. It also shows how to enable masking for grounding and apply an allow list for specific entities.

```java
var maskingConfig =  
    DpiMasking.anonymization()  
        .withEntities(DPIEntities.SENSITIVE_DATA)  
        .withMaskGroundingEnabled()  
        .withAllowList(List.of("SAP", "Joule"));  
var maskedGroundingConfig = groundingConfig.withMaskingConfig(maskingConfig);  
  
var result = client.chatCompletion(prompt, maskedGroundingConfig);
```

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

### Add Maven Dependency for Document Grounding

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/document-grounding

This snippet shows the Maven dependency required to include the SAP Document Grounding SDK in your Java project. Ensure you have a `pom.xml` file in your project.

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

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

### Implement Tool Calling with OpenAI

Source: https://sap.github.io/ai-sdk/docs/java/spring-ai/openai

Provides an example of how to enable the LLM to call tools. This involves defining a Java class with methods annotated with @Tool and @ToolParam, and then passing an instance of this class to the chat model's options.

```java
class WeatherMethod {
  enum Unit {C,F}
  record Request(String location, Unit unit) {}
  record Response(double temp, Unit unit) {}

  @Tool(description = "Get the weather in location")
  Response getCurrentWeather(@ToolParam Request request) {
    int temperature = request.location.hashCode() % 30;
    return new Response(temperature, request.unit);
  }
}

OpenAiClient openAiClient = OpenAiClient.forModel(OpenAiModel.GPT_4O_MINI);
ChatModel client = new OpenAiChatModel(openAiClient);
var options = new DefaultToolCallingChatOptions();

options.setToolCallbacks(List.of(ToolCallbacks.from(new WeatherMethod())));

Prompt prompt = new Prompt("What is the weather in Potsdam and in Toulouse?", options);

ChatResponse response = client.call(prompt);
```

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

### Use AI Launchpad Configuration

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

This snippet demonstrates how to use a configuration generated from AI Launchpad. It involves loading the configuration JSON (either directly as a string or from a file) and then executing a request using this configuration.

```java
var configJson = "... paste your configuration JSON in here ...";
// or load your config from a file, e.g.
// configJson = Files.readString(Paths.get("path/to/my/orchestration-config.json"));

var prompt = new OrchestrationPrompt(Map.of("your-input-parameter", "your-param-value"));

new OrchestrationClient().executeRequestFromJsonModuleConfig(prompt, configJson);
```

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

### Prompt Registry - Prompt Management

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

APIs for managing prompt templates, including importing and parsing prompts with resource group support.

```APIDOC
## POST /prompts/import

### Description
Imports a prompt template.

### Method
POST

### Endpoint
/prompts/import

### Parameters
#### Query Parameters
- **resourceGroup** (string) - Optional - The resource group for the prompt template. Defaults to "default".

#### Request Body
- **templateFile** (file) - Required - The file containing the prompt template.

### Request Example
```json
{
  "templateFile": "@/path/to/your/prompt_template.json"
}
```

### Response
#### Success Response (200)
- **status** (string) - The import status.

#### Response Example
```json
{
  "status": "imported"
}
```
```

```APIDOC
## GET /prompts/parse/{id}

### Description
Parses a prompt template by its ID.

### Method
GET

### Endpoint
/prompts/parse/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the prompt template to parse.

#### Query Parameters
- **resourceGroup** (string) - Optional - The resource group for the prompt template. Defaults to "default".
- **resolveParameters** (boolean) - Optional - Whether to resolve template parameters.

#### Request Body
- **inputParameters** (object) - Optional - Input parameters for resolving the prompt template.
  - **key** (string) - Required - The parameter key.
  - **value** (string) - Required - The parameter value.

### Request Example
```json
{
  "inputParameters": [
    {
      "key": "userName",
      "value": "Alice"
    }
  ]
}
```

### Response
#### Success Response (200)
- **parsedPrompt** (string) - The parsed prompt content.

#### Response Example
```json
{
  "parsedPrompt": "Hello, Alice!"
}
```
```

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

### Use Prepared Template with Input Parameters in Java

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

Demonstrates how to use a prepared prompt template by passing input parameters directly. It replaces placeholders in the template with provided values.

```java
var message = Message.user("Reply with 'Orchestration Service is working!' in {{?language}}");
var templatingConfig = TemplateConfig.create().withMessages(message);
var configWithTemplate = config.withTemplateConfig(templatingConfig);

var inputParams = Map.of("language", "German");
var prompt = new OrchestrationPrompt(inputParams);

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

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

### Load and Test Prompt Template from YAML in Java

Source: https://sap.github.io/ai-sdk/docs/java/orchestration/chat-completion

Illustrates how to load and test a prompt template defined in a YAML file locally without relying on the Prompt Registry. This facilitates quick iteration on templates.

```java
String promptTemplate = Files.readString(Path.of("path/to/my/prompt-template.yaml"));
var template = TemplateConfig.create().fromYaml(promptTemplate);
var configWithTemplate = config.withTemplateConfig(template);

var inputParams = Map.of("language", "German");
var prompt = new OrchestrationPrompt(inputParams);
var response = client.chatCompletion(prompt, configWithTemplate);
```

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

### Prompt Registry Client

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

Information on the addition of the Prompt Registry client.

```APIDOC
## ✨ New Functionality - Prompt Registry

### Description
Introduces the Prompt Registry client for managing prompt templates.

### Method
N/A (Information about SDK features)

### Endpoint
N/A (Information about SDK features)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Artifact:
- `com.sap.ai.sdk:prompt-registry:1.6.0`
```

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

### Use a Prompt Template

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

Fills a prompt template with provided parameters. Can be done by template ID or by name, scenario, and version.

```APIDOC
## POST /prompt-template/substitute/{id}

### Description
Substitutes placeholders in a prompt template with provided input parameters.

### Method
POST

### Endpoint
`/prompt-template/substitute/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the prompt template.

#### Request Body
- **inputParams** (object) - Required - A map of placeholder names to their values.

### Request Example
```json
{
  "inputParams": {
    "inputExample": "I love football"
  }
}
```

### Response
#### Success Response (200)
- **substitutedTemplate** (string) - The prompt template with placeholders substituted.

#### Response Example
```json
{
  "substitutedTemplate": "You classify input text into the two following categories: Finance, Tech, Sports. I love football"
}
```
```

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

### Create a Prompt Template using Java

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

This Java code demonstrates how to create a reusable prompt template with placeholders. It defines a system and user role message, specifies default values for categories, and sets the template's name, version, and scenario.

```java
PromptClient client = new PromptClient();

var spec =
    PromptTemplateSpec.create()
        .template(
            SingleChatTemplate.create()
                .role("system")
                .content(
                    "You classify input text into the two following categories: {{?categories}}"),
            SingleChatTemplate.create().role("user").content("{{?inputExample}}"))
        .defaults(Map.of("categories", "Finance, Tech, Sports"));

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

PromptTemplatePostResponse response = client.createUpdatePromptTemplate(template);
```

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

### Document Grounding Pipeline Data Source Configuration in Java

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

Extends S3 and SFTP pipeline configurations with `S3Configuration` and `SFTPConfiguration`. These classes enable the inclusion of specific data source details when setting up pipelines.

```Java
S3Configuration s3Config = new S3Configuration(...);
SFTPConfiguration sftpConfig = new SFTPConfiguration(...);
```

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

### Get Prompt Template History

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

Retrieves the history of edits for a specific prompt template, applicable only to imperatively managed prompt templates.

```APIDOC
## GET /prompt-template/history/{scenario}/{version}/{name}

### Description
Retrieves the edit history for a specific prompt template.

### Method
GET

### Endpoint
`/prompt-template/history/{scenario}/{version}/{name}`

### Parameters
#### Path Parameters
- **scenario** (string) - Required - The scenario of the prompt template.
- **version** (string) - Required - The version of the prompt template.
- **name** (string) - Required - The name of the prompt template.

### Response
#### Success Response (200)
- **history** (array) - A list of prompt template edit history entries.
  - **timestamp** (string) - The timestamp of the edit.
  - **change** (string) - Description of the change.

#### Response Example
```json
{
  "history": [
    {
      "timestamp": "2023-10-27T10:00:00Z",
      "change": "Initial creation"
    }
  ]
}
```
```

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

### Using BTP Destination Service for AI Core (Java)

Source: https://sap.github.io/ai-sdk/docs/java/connecting-to-ai-core

Demonstrates how to retrieve a destination from the BTP Destination Service and use it to initialize an AiCoreService for connecting to AI Core. This method is suitable when destinations are pre-configured in the SAP BTP Cockpit.

```java
Destination destination = DestinationAccessor.getDestination("my-aicore").asHttp();
AiCoreService aiCoreService = new AiCoreService().withBaseDestination(destination);
```

```java
// To create an OpenAiClient:
var openAiDestination = aiCoreService.getInferenceDestination().forModel(OpenAiModel.TEXT_EMBEDDING_3_LARGE);
var client = OpenAiClient.withCustomDestination(openAiDestination);

// To create an OrchestrationClient:
var orchestrationDestination = aiCoreService.getInferenceDestination().forScenario("orchestration");
var client = new OrchestrationClient(orchestrationDestination);

// To create any of the com.sap.ai.sdk.core.client.* classes (e.g. DeploymentApi):
new DeploymentApi(aiCoreService);
```

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

### Using Prompt Registry Templates in Spring AI (Java)

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

Explains how to utilize Prompt Registry Templates within a Spring AI context using the `SpringAiConverter`. This allows for easier management and use of predefined prompts.

```java
import com.sap.cloud.ai.ai_sdk.prompt_registry.core.converter.SpringAiConverter;
// ...

@Configuration
public class PromptConfig {

    @Bean
    public SpringAiConverter springAiConverter() {
        return new SpringAiConverter();
    }
}
```

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

### Document Grounding Retrieval Class Renaming in Java

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

Typo fix in Document Grounding: classes containing 'Retrieval' have been renamed. For example, `RetievalSearchResults` is now `RetrievalSearchResults`.

```Java
// Renamed from RetievalSearchResults to RetrievalSearchResults
```

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

### Integrate a Tool with the OrchestrationChatModel in Java

Source: https://sap.github.io/ai-sdk/docs/java/spring-ai/orchestration

Configures and calls the `OrchestrationChatModel` with a defined tool (`WeatherMethod`). It sets up the model configuration, options, and tool callbacks before making a prompt to get weather information.

```java
ChatModel client = new OrchestrationChatModel();
OrchestrationModuleConfig config = new OrchestrationModuleConfig().withLlmConfig(GPT_4O_MINI);
OrchestrationChatOptions opts = new OrchestrationChatOptions(config);

options.setToolCallbacks(List.of(ToolCallbacks.from(new WeatherMethod())));

Prompt prompt = new Prompt("What is the weather in Potsdam and in Toulouse?", options);

ChatResponse response = client.call(prompt);
```

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

### Import a Prompt Template

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

Imports a prompt template from a file in YAML format.

```APIDOC
## POST /prompt-template/import

### Description
Imports a prompt template from a YAML file.

### Method
POST

### Endpoint
`/prompt-template/import`

### Parameters
#### Request Body
- **file** (file) - Required - The YAML file containing the prompt template.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the imported prompt template.

#### Response Example
```json
{
  "id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1"
}
```
```

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

### Configure Data Masking for Chat Completion

Source: https://sap.github.io/ai-sdk/docs/java/spring-ai/orchestration

Shows how to configure data masking within the Orchestration client. This example masks personal identifiable information like email, address, and location from the prompt.

```java
ChatModel client = new OrchestrationChatModel();
OrchestrationModuleConfig config = new OrchestrationModuleConfig().withLlmConfig(GPT_4O_MINI);

var masking = 
    DpiMasking.anonymization()
        .withEntities(DPIEntities.EMAIL, DPIEntities.ADDRESS, DPIEntities.LOCATION);

var opts = new OrchestrationChatOptions(config.withMaskingConfig(masking));
var prompt = 
    new Prompt(
        "Please write 'Hello World!' to me via email. My email address is foo.bar@baz.ai",
        opts);

ChatResponse response = client.call(prompt);
```

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

### Orchestration Grounding via _help.sap.com_ (Java)

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

Enables grounding via _help.sap.com_ within the Orchestration module. This allows orchestration workflows to access and utilize information from SAP's help portal.

```java
/*
 * Grounding via _help.sap.com_ is enabled.
 */
// This feature likely provides a mechanism to query and retrieve relevant information from SAP's help documentation to augment AI responses.

```

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

### OpenAI Tool Choice Configuration (Java)

Source: https://sap.github.io/ai-sdk/docs/java/release-notes

Introduces `OpenAiToolChoice` for configuring chat completion requests with tool selection strategies. This allows precise control over how OpenAI models choose and utilize tools.

```java
/*
 * OpenAiToolChoice for configuring chat completion requests with tool selection strategy.
 */
// Example of configuring tool choice:
// OpenAiToolChoice toolChoice = OpenAiToolChoice.auto(); // or OpenAiToolChoice.required("tool_name")
// OpenAiChatCompletionRequest request = OpenAiChatCompletionRequest.builder()
//    .withToolChoice(toolChoice)
//    .build();

```

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

### Get Prompt Template History using Java

Source: https://sap.github.io/ai-sdk/docs/java/ai-core/prompt-registry

This Java code retrieves the edit history for a specific prompt template. It requires the scenario, version, and name of the prompt template and uses the `listPromptTemplateHistory` method.

```java
PromptClient client = new PromptClient();

PromptTemplateListResponse history = client.listPromptTemplateHistory("categorization", "0.0.1", NAME);
```