feat: (Grounding) Initial client classes with generated API and model

.pipeline/checkstyle-suppressions.xml

@@ -10,6 +10,8 @@
   <suppress files="[/\\]core[/\\]model[/\\]" checks=".*"/>
   <suppress files="[/\\]openai[/\\]generated[/\\]model[/\\]" checks=".*"/>
   <suppress files="[/\\]orchestration[/\\]model[/\\]" checks=".*"/>
+  <suppress files="[/\\]grounding[/\\]api[/\\]" checks=".*"/>
+  <suppress files="[/\\]grounding[/\\]model[/\\]" checks=".*"/>
   <!-- Suppress TODOs -->
   <suppress files="OpenAiChatMessage.java" checks="TodoComment" lines="257,7" />
   <suppress files="ChatCompletionResponseMessage.java" checks="TodoComment" lines="53,34" />

.pipeline/spotbugs-exclusions.xml

@@ -5,6 +5,8 @@
       <Package name="com.sap.ai.sdk.core.client"/>
       <Package name="com.sap.ai.sdk.core.model"/>
       <Package name="com.sap.ai.sdk.orchestration.model"/>
+      <Package name="com.sap.ai.sdk.grounding.client"/>
+      <Package name="com.sap.ai.sdk.grounding.model"/>
     </Or>
   </Match>
 </FindBugsFilter>

README.md

@@ -136,6 +136,7 @@ For more detailed information and advanced usage, please refer to the following:
 - [<img src="sample-code/spring-app/src/main/resources/static/Open-AI-Logo.svg" width="16"/> OpenAI Chat Completion](docs/guides/OPENAI_CHAT_COMPLETION.md)
 - [<img src="https://spring.io/favicon-32x32.png" width="16"/> Spring AI Integration](docs/guides/SPRING_AI_INTEGRATION.md)
 - [🧰 AI Core Deployment](docs/guides/AI_CORE_DEPLOYMENT.md)
+- [<img src="sample-code/spring-app/src/main/resources/static/grounding.png" width="16"/> AI Core Grounding](docs/guides/GROUNDING.md)
 
 For updating versions, please refer to the [**Release Notes**](docs/release-notes/release-notes-0-to-14.md).
 

docs/guides/GROUNDING.md

@@ -0,0 +1,155 @@
+# Grounding Services
+
+## Table of Contents
+
+- [Introduction](#introduction)
+    - [Prerequisites](#prerequisites)
+        - [Maven Dependencies](#maven-dependencies)
+- [Usage](#usage)
+    - [Data Ingestion](#data-ingestion)
+        - [Pipeline API](#pipeline-api)
+        - [Vector API](#vector-api)
+    - [Data Retrieval](#retrieval-api)
+        - [Retrieval API](#create-a-deployment)
+        - [Grounding via Orchestration](#grounding-via-orchestration)
+
+## Introduction
+
+This guide provides examples on how to manage data in SAP Document Grounding.
+It's divided into two main sections: Data Ingestion and Data Retrieval.
+
+> [!WARNING]  
+> The below examples rely on generated model classes.
+> Please be aware of the [implications described here](/README.md#general-requirements).
+
+## Prerequisites
+
+Before using the Grounding module, ensure that you have met all the general requirements outlined in the [README.md](../../README.md#general-requirements).
+Additionally, include the necessary Maven dependency in your project.
+
+### Maven Dependencies
+
+Add the following dependency to your `pom.xml` file:
+
+```xml
+<dependency>
+    <groupId>com.sap.ai.sdk</groupId>
+    <artifactId>grounding</artifactId>
+    <version>${ai-sdk.version}</version>
+</dependency>
+```
+
+See [an example pom in our Spring Boot application](../../sample-code/spring-app/pom.xml)
+
+## Usage
+
+In addition to the prerequisites above, we assume you have already set up the following to carry out the examples in this guide:
+
+- A running instance of SAP AI Core with correctly setup credentials, including a resource group id.
+
+## Data Ingestion
+
+The following APIs are available for data ingestion: Pipeline and Vector.
+
+### Pipeline API
+
+Consider the following code sample to read pipelines, create a new one and get its status:
+
+```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());
+```
+
+### Vector API
+
+```java
+var api = new GroundingClient().vector();
+var resourceGroupId = "default";
+
+// resolve collection id
+var collectionId = UUID.fromString("12345-123-123-123-0123456abcdef");
+
+var request = DocumentCreateRequest.create()
+  .documents(BaseDocument.create()
+      .chunks(TextOnlyBaseChunk.create()
+          .content("The dog makes _woof_")
+          .metadata(KeyValueListPair.create()
+              .key("animal").value("dog")))
+      .metadata(DocumentKeyValueListPair.create()
+          .key("topic").value("sound")));
+DocumentsListResponse response = api.createDocuments(resourceGroupId, collectionId, request);
+```
+
+Refer to the [DeploymentController.java](../../sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/DeploymentController.java) in our Spring Boot application for a complete example.
+
+## Data Retrieval
+
+The following APIs are available for data retrieval: Retrieval and Orchestration.
+
+
+### Retrieval API
+
+Consider the following code sample to search for relevant grounding data based on a query:
+
+```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);
+```
+
+### Grounding via Orchestration
+
+You can use the grounding service via orchestration.
+Please find the [documentation on Orchestration client in the dedicated document](ORCHESTRATION_CHAT_COMPLETION.md).
+
+```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);
+```

grounding/pom.xml

@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>com.sap.ai.sdk</groupId>
+    <artifactId>sdk-parent</artifactId>
+    <version>1.4.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>grounding</artifactId>
+  <name>Grounding client</name>
+  <description>SAP Cloud SDK for AI is the official Software Development Kit (SDK) for SAP AI Core, SAP Generative AI Hub, and Orchestration Service. This is the client for the Grounding Service.</description>
+
+  <url>https://github.com/SAP/ai-sdk-java?tab=readme-ov-file#documentation</url>
+  <organization>
+    <name>SAP SE</name>
+    <url>https://www.sap.com</url>
+  </organization>
+  <licenses>
+    <license>
+      <name>The Apache Software License, Version 2.0</name>
+      <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
+    </license>
+  </licenses>
+  <developers>
+    <developer>
+      <name>SAP</name>
+      <email>[email protected]</email>
+      <organization>SAP SE</organization>
+      <organizationUrl>https://www.sap.com</organizationUrl>
+    </developer>
+  </developers>
+  <properties>
+    <project.rootdir>${project.basedir}/../</project.rootdir>
+    <coverage.complexity>80%</coverage.complexity>
+    <coverage.line>71%</coverage.line>
+    <coverage.instruction>85%</coverage.instruction>
+    <coverage.branch>100%</coverage.branch>
+    <coverage.method>80%</coverage.method>
+    <coverage.class>100%</coverage.class>
+  </properties>
+
+  <dependencies>
+    <!-- used by generated API classes -->
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-core</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-web</artifactId>
+    </dependency>
+    <!-- scope "compile" -->
+    <dependency>
+      <groupId>com.sap.ai.sdk</groupId>
+      <artifactId>core</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.sap.cloud.sdk.cloudplatform</groupId>
+      <artifactId>cloudplatform-connectivity</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.sap.cloud.sdk.datamodel</groupId>
+      <artifactId>openapi-core</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.google.code.findbugs</groupId>
+      <artifactId>jsr305</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-annotations</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.google.guava</groupId>
+      <artifactId>guava</artifactId>
+    </dependency>
+    <!-- scope "provided" -->
+    <dependency>
+      <groupId>org.projectlombok</groupId>
+      <artifactId>lombok</artifactId>
+      <scope>provided</scope>
+    </dependency>
+    <!-- scope "test" -->
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.wiremock</groupId>
+      <artifactId>wiremock</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.assertj</groupId>
+      <artifactId>assertj-core</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <profiles>
+    <profile>
+      <id>generate</id>
+      <activation>
+        <activeByDefault>false</activeByDefault>
+        <property>
+          <name>generate</name>
+        </property>
+      </activation>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>com.sap.cloud.sdk.datamodel</groupId>
+            <artifactId>openapi-generator-maven-plugin</artifactId>
+            <configuration>
+              <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
+              <apiMaturity>beta</apiMaturity>
+              <enableOneOfAnyOfGeneration>true</enableOneOfAnyOfGeneration>
+              <compileScope>COMPILE</compileScope>
+              <deleteOutputDirectory>true</deleteOutputDirectory>
+            </configuration>
+            <executions>
+              <execution>
+                <id>orchestration</id>
+                <goals>
+                  <goal>generate</goal>
+                </goals>
+                <phase>generate-sources</phase>
+                <configuration>
+                  <inputSpec>${project.basedir}/src/main/resources/spec/grounding.yaml</inputSpec>
+                  <apiPackage>com.sap.ai.sdk.grounding.client</apiPackage>
+                  <modelPackage>com.sap.ai.sdk.grounding.model</modelPackage>
+                  <additionalProperties>
+                    <pojoBuilderMethodName>create</pojoBuilderMethodName>
+                    <pojoBuildMethodName/>
+                    <pojoConstructorVisibility>protected</pojoConstructorVisibility>
+                    <enumUnknownDefaultCase>true</enumUnknownDefaultCase>
+                    <useOneOfInterfaces>true</useOneOfInterfaces>
+                  </additionalProperties>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
+</project>