Add Conversation AI to Java SDK #1235

siri-varma · 2025-03-06T16:51:30Z

PR Overview: Conversation AI SDK Integration

This PR introduces the Conversation AI SDK with the Converse API. The implementation is structured into the following categories:

Core Logic
Models
Unit Tests

Core Logic

The core logic is implemented in a key class, as detailed below:

Class	Description	Details
DaprConversationClient	Manages the Conversation API. Handles validations and async calls.	- Calls the Conversation API asynchronously. - Validates inputs and manages job execution.

API Contracts

The following is the method signature for the Dapr Converse API:

Dapr Converse API

This method interacts with the Dapr Converse API.

Mono<DaprConversationResponse> converse(
    String conversationComponentName,
    List<DaprConversationInput> daprConversationInputs,
    String contextId,
    boolean scrubPii,
    double temperature
);

Parameter	Description
`conversationComponentName`	Name of the conversation component.
`daprConversationInputs`	List of prompts that are part of the conversation.
`contextId`	Identifier for an existing chat session (e.g., similar to ChatGPT).
`scrubPii`	Whether to scrub personally identifiable information (PII) from responses.
`temperature`	Controls response randomness (lower = more predictable, higher = more creative).
Returns	`DaprConversationResponse`

Models

The SDK follows the builder pattern for constructing models, ensuring cleaner and more maintainable object creation.

Tests

The testing strategy includes:

Unit Tests: Validate individual components and business logic.

Issue Reference

We ensure that all PRs are linked to a relevant issue where the problem or feature has been discussed before implementation.

This PR closes the following issue: #1101

Checklist ✅

Please confirm the following before merging:

Code compiles correctly
Created/updated tests
Extended the documentation

siri-varma · 2025-03-06T16:56:29Z

@salaboy, @artur-ciocanu please let me know what you think. Working on integration and unit tests in the meanwhile

yaron2 · 2025-03-06T17:36:13Z

Great contribution, thanks @siri-varma

Signed-off-by: Siri Varma Vegiraju <[email protected]> Signed-off-by: sirivarma <[email protected]>

salaboy · 2025-03-06T22:18:56Z

this is great @siri-varma ! I will start reviewing soon!

Signed-off-by: sirivarma <[email protected]>

siri-varma · 2025-03-07T18:05:38Z

For integration tests, we must spin up a mock for third party LLM endpoint. Do we have similar patterns in the current setup? (where dapr is talking to a third party api and receiving responses)

salaboy · 2025-03-13T14:12:25Z

sdk-ai/src/main/java/io/dapr/ai/client/DaprConversationClient.java

+import java.util.Map;
+import java.util.function.Consumer;
+
+public class DaprConversationClient implements AutoCloseable, DaprAiClient {


@siri-varma I assume that you know that we had a previewClient, why is this introducing a new separated client for the conversation API? I would assume that we want to include this in PreviewClient first. @yaron2 we might need your help here.

and sorry for the confusion if the PreviewClient is an old thing that we are not supposed to use anymore. As the workflows now have their own separate client, this might be the way to go.

Just to clarify, we are fine with current approach right ?

sdk-ai/pom.xml

salaboy · 2025-03-13T14:17:30Z

@siri-varma this is looking good, I left some comments that basically highlight my doubts about some JDK general topics. But this is looking really good, are you planning to add integration tests inside the sdk-tests too? We have some Spring Boot tests using Testcontainers, I was thinking that you might want to test the APIs against a local model running in a docker container to see that everything works as expected.

siri-varma · 2025-03-14T00:08:01Z

@salaboy I have tested the code by running it locally and using my OpenAI API Key.

~~Regarding the integration test, I think we will need an LLM model for daprd to communicate with, which unfortunately are huge in size. That is why I did not add the integration tests~~

Will get back to you on the integ tests

Signed-off-by: sirivarma <[email protected]>

…om/siri-varma/java-sdk into users/svegiraju/conversation-api-2

salaboy · 2025-03-14T07:59:57Z

Yeah check this https://java.testcontainers.org/modules/ollama/

siri-varma · 2025-03-14T14:54:16Z

@salaboy thank you for providing the testcontainer urls.

Like how we have url overrides for Scheduler, I was looking one for conversation too because we will have to point dapr to the local llm model. But could not find any

I tried looking in the below places and could not find anything. https://github.com/dapr/dapr/blob/2e7c61e933099b9d40fcdefbd57cc3e81069915a/pkg/injector/annotations/annotations.go#L73
https://github.com/dapr/dapr/blob/2e7c61e933099b9d40fcdefbd57cc3e81069915a/pkg/injector/consts/consts.go#L51
https://docs.dapr.io/reference/arguments-annotations-overview/

@salaboy or @cicoyle Would you folks know about this ?

artur-ciocanu · 2025-03-17T18:15:02Z

@siri-varma thanks a lot for your contribution. I have reviewed your PR and I have a few comments similar to #1255:

Let's make sure the Conversation API is part of the DaprPreviewClient
Let's make sure that we use the Alpha1 suffix for the Conversation API
Let's make sure we keep everything under sdk module and we don't create a separate module for Conversation API
For the Conversation API converse let's make sure we add private methods to validate all the input parameters, before invoking the GRPC API
For Conversation API converse method let's ensure we keep number of parameters to a minimum, having to pass 5 parameters is too much. I think a better option is to have a builder for ConversationRequest which should be part of the model classes for DaprClient. This way we can have sane defaults, but allow users to override some of the values if desired.

CC: @salaboy @cicoyle

artur-ciocanu

@siri-varma thanks a lot for your contribution, I have left a longer comment with some of my thoughts.

Please take a look and let me know what you think.

Signed-off-by: sirivarma <[email protected]>

Signed-off-by: siri-varma <[email protected]>

siri-varma · 2025-03-18T20:43:47Z

@siri-varma thanks a lot for your contribution. I have reviewed your PR and I have a few comments similar to #1255:

Let's make sure the Conversation API is part of the DaprPreviewClient

Let's make sure that we use the Alpha1 suffix for the Conversation API

Let's make sure we keep everything under sdk module and we don't create a separate module for Conversation API

For the Conversation API converse let's make sure we add private methods to validate all the input parameters, before invoking the GRPC API

For Conversation API converse method let's ensure we keep number of parameters to a minimum, having to pass 5 parameters is too much. I think a better option is to have a builder for ConversationRequest which should be part of the model classes for DaprClient. This way we can have sane defaults, but allow users to override some of the values if desired.

CC: @salaboy @cicoyle

@artur-ciocanu Addressed all the comments here as well.
@salaboy Added Integration tests too.

siri-varma · 2025-03-24T17:43:59Z

@artur-ciocanu , @salaboy All the builds are passing and addressed comments as well. Would you folks be able to do another round of reviews please ?

cicoyle

Generally this looks great 🌟 - mind adding an example for conversation api to the examples directory in the repo with the mechanical markdown in the README with a sample .java file for users to know how to use the API?

We should also document the high level things that are expected when adding new APIs to the SDK to lower the barrier to entry for future developers and for consistency. Thanks for this PR 🚀 We are nearly there!

examples/src/main/java/io/dapr/examples/conversation/DemoConversationAI.java

sdk-tests/src/test/java/io/dapr/it/testcontainers/DaprConversationIT.java

…tionIT.java Co-authored-by: Cassie Coyle <[email protected]> Signed-off-by: Siri Varma Vegiraju <[email protected]>

Signed-off-by: siri-varma <[email protected]>

cicoyle · 2025-04-14T21:18:38Z

Amazing work here @siri-varma 🚀 Thanks for the contribution 🌟

Signed-off-by: artur-ciocanu <[email protected]>

artur-ciocanu

@siri-varma thanks a lot for all your hard work! I have a few general comments that are critical, others are mostly style related:

Dapr Conversation API uses a component to configure everything related to model interaction and we should make sure that this is reflected in the API like using name or componentName. I feel componentName makes more sense, but I will let @cicoyle and @salaboy share their thoughts.
scrubPII - I know this comes from Dapr Runtime, but honestly it looks and feels cryptic, so if we can agree on a better name and then propagate this back to Dapr Runtime that would be great.
ConversationRole - any LLM framework I have used, do not constraint the role in any way, since you can have different roles, depending on use case, so I think sticking to Dapr Runtime string is good enough.

Please take a look and let me know your thoughts.

artur-ciocanu · 2025-04-14T22:54:24Z

examples/src/main/java/io/dapr/examples/conversation/DemoConversationAI.java

+      throw new RuntimeException(e);
+    }
+  }
+}


Add new line

artur-ciocanu · 2025-04-14T22:55:02Z

examples/src/main/java/io/dapr/examples/conversation/DemoConversationAI.java

+          + "This is the my number 672-123-4567");
+
+      // Component name is the name provided in the metadata block of the conversation.yaml file.
+      Mono<ConversationResponse> responseMono = client.converse(new ConversationRequest("echo",


You could use a more modern approach from Java 11 List.of(...) instead of Collections.singleton(...)

artur-ciocanu · 2025-04-14T22:57:18Z

examples/src/main/java/io/dapr/examples/conversation/README.md

@@ -0,0 +1,117 @@
+## Manage Dapr Jobs via the Conversation API


Manage Dapr Jobs looks confusing ... is this related to Job API or Conversation API?

good catch, lets remove jobs from this unless you are using the jobs api.

artur-ciocanu · 2025-04-14T22:57:47Z

pom.xml

@@ -17,7 +17,7 @@
    <grpc.version>1.69.0</grpc.version>
    <protobuf.version>3.25.5</protobuf.version>
    <protocCommand>protoc</protocCommand>


This should be updated to latest

v1.15.4 is latest as of now - think this was just bc the PR has been open a while and we more recently released 1.15.3 && 1.15.4

artur-ciocanu · 2025-04-14T23:31:48Z

sdk-tests/src/test/java/io/dapr/it/testcontainers/DaprConversationIT.java

+        Assertions.assertEquals("input this <PHONE_NUMBER>",
+                response.getConversationOutpus().get(1).getResult());
+    }
+}


Add new line

artur-ciocanu · 2025-04-15T00:33:34Z

sdk/src/test/java/io/dapr/client/DaprPreviewClientGrpcTest.java

+			observer.onCompleted();
+			return null;
+		}).when(daprStub).converseAlpha1(any(DaprProtos.ConversationRequest.class), any());
+


Could we rename it to daprConversationInput

artur-ciocanu · 2025-04-15T00:33:54Z

sdk/src/test/java/io/dapr/client/DaprPreviewClientGrpcTest.java

+
+		List<ConversationInput> daprConversationInputs = new ArrayList<>();
+		daprConversationInputs.add(daprConversationInput);
+


Could we rename it to response

artur-ciocanu · 2025-04-15T00:34:27Z

sdk/src/test/java/io/dapr/client/DaprPreviewClientGrpcTest.java

+		verify(daprStub, times(1)).converseAlpha1(captor.capture(), Mockito.any());
+
+		DaprProtos.ConversationRequest conversationRequest = captor.getValue();
+


Could we use static imports so we could use just assertEquals without Assertions

artur-ciocanu · 2025-04-15T00:47:15Z

sdk/src/main/java/io/dapr/client/DaprClientImpl.java

+            .setContent(input.getContent())
+            .setScrubPII(input.isScrubPii());
+
+        if (input.getRole() != null) {


ConversationRole is an enum with TOOL, USER, ASSISTANT and toString() would return capital case "TOOL", "USER", "ASSISTANT". While I think enum is a good idea, I would keep it compatible with GRPC object and use an ordinary string. We want users to decide what role they want to use system, assistant, agent, etc

artur-ciocanu · 2025-04-15T00:49:56Z

sdk/src/main/java/io/dapr/client/domain/ConversationRole.java

+
+/**
+ * Conversation AI supported roles.
+ */


As I mentioned I am not sure we need this enum. We want user to use whatever they feel is appropriate as a role. We don't want to keep changing this enum, because someone has a different use case.

I replied on the other thread - I agree, lets align and use string. I appreciate the enum idea here though 🙏🏻

codecov · 2025-04-15T01:02:37Z

Codecov Report

Attention: Patch coverage is 95.06173% with 4 lines in your changes missing coverage. Please review.

Project coverage is 75.69%. Comparing base (d759c53) to head (720a427).
Report is 127 commits behind head on master.

Files with missing lines	Patch %	Lines
...k/src/main/java/io/dapr/client/DaprClientImpl.java	92.50%	2 Missing and 1 partial ⚠️
...java/io/dapr/client/domain/ConversationOutput.java	83.33%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1235      +/-   ##
============================================
- Coverage     76.91%   75.69%   -1.23%     
- Complexity     1592     1641      +49     
============================================
  Files           145      199      +54     
  Lines          4843     5171     +328     
  Branches        562      567       +5     
============================================
+ Hits           3725     3914     +189     
- Misses          821      936     +115     
- Partials        297      321      +24

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

cicoyle · 2025-04-15T18:25:31Z

@siri-varma thanks a lot for all your hard work! I have a few general comments that are critical, others are mostly style related:

Dapr Conversation API uses a component to configure everything related to model interaction and we should make sure that this is reflected in the API like using name or componentName. I feel componentName makes more sense, but I will let @cicoyle and @salaboy share their thoughts.

scrubPII - I know this comes from Dapr Runtime, but honestly it looks and feels cryptic, so if we can agree on a better name and then propagate this back to Dapr Runtime that would be great.

ConversationRole - any LLM framework I have used, do not constraint the role in any way, since you can have different roles, depending on use case, so I think sticking to Dapr Runtime string is good enough.

Please take a look and let me know your thoughts.

I understand where you are coming from, however we want to align with dapr runtime and other sdks. For example, the scrubPII should stay as-is, bc in runtime we have it named as such, dotnet has it named that way, so for consistency in the dapr projects and ecosystem, the java sdk should as well.

Same for component name - dotnet && go-sdk for example

For role - Im inclined to agree on string as well for the same reasons. It is how we have it in the go-sdk.

siri-varma · 2025-04-20T02:19:20Z

will update this pr in couple of days

siri-varma requested review from a team as code owners March 6, 2025 16:51

siri-varma force-pushed the users/svegiraju/conversation-api-2 branch from 68d30ee to 9a8926e Compare March 6, 2025 16:52

cicoyle added this to the v1.15 milestone Mar 6, 2025

cicoyle assigned siri-varma Mar 6, 2025

siri-varma force-pushed the users/svegiraju/conversation-api-2 branch from 9a8926e to 4cb6031 Compare March 6, 2025 19:10

Conversation first commit

75f487f

Signed-off-by: Siri Varma Vegiraju <[email protected]> Signed-off-by: sirivarma <[email protected]>

siri-varma force-pushed the users/svegiraju/conversation-api-2 branch from 4cb6031 to 75f487f Compare March 6, 2025 19:11

Add unit tests

88fe015

Signed-off-by: sirivarma <[email protected]>

siri-varma force-pushed the users/svegiraju/conversation-api-2 branch from bf70fd4 to 88fe015 Compare March 7, 2025 04:27

Merge branch 'master' into users/svegiraju/conversation-api-2

c27d3ab

siri-varma changed the title ~~WIP: Add Conversation AI to Java SDK~~ Add Conversation AI to Java SDK Mar 8, 2025

salaboy mentioned this pull request Mar 10, 2025

Add Jobs API #1101

Closed

Merge branch 'master' into users/svegiraju/conversation-api-2

ca2dd02

salaboy reviewed Mar 13, 2025

View reviewed changes

sdk-ai/pom.xml Outdated Show resolved Hide resolved

salaboy reviewed Mar 13, 2025

View reviewed changes

sdk-ai/pom.xml Outdated Show resolved Hide resolved

siri-varma added 2 commits March 13, 2025 17:30

change ai to conv

fada33f

Signed-off-by: sirivarma <[email protected]>

Merge branch 'users/svegiraju/conversation-api-2' of https://github.c…

d14ce3e

…om/siri-varma/java-sdk into users/svegiraju/conversation-api-2

artur-ciocanu reviewed Mar 17, 2025

View reviewed changes

Move to single module

842b0e7

Signed-off-by: sirivarma <[email protected]>

siri-varma force-pushed the users/svegiraju/conversation-api-2 branch from 115b5e7 to 842b0e7 Compare March 18, 2025 15:10

siri-varma added 2 commits March 18, 2025 08:14

Remove module

c18ccf5

Signed-off-by: sirivarma <[email protected]>

Add Integration tests

a169d00

Signed-off-by: siri-varma <[email protected]>

Merge branch 'master' into users/svegiraju/conversation-api-2

dd44b79

siri-varma requested review from salaboy and artur-ciocanu March 18, 2025 20:44

Merge branch 'master' into users/svegiraju/conversation-api-2

fae44b7

siri-varma added 2 commits April 7, 2025 22:29

Merge branch 'master' into users/svegiraju/conversation-api-2

7958555

Merge branch 'master' into users/svegiraju/conversation-api-2

e29e376

cicoyle requested changes Apr 10, 2025

View reviewed changes

examples/src/main/java/io/dapr/examples/conversation/DemoConversationAI.java Show resolved Hide resolved

sdk-tests/src/test/java/io/dapr/it/testcontainers/DaprConversationIT.java Outdated Show resolved Hide resolved

siri-varma and others added 5 commits April 12, 2025 15:06

Update sdk-tests/src/test/java/io/dapr/it/testcontainers/DaprConversa…

4dde2f6

…tionIT.java Co-authored-by: Cassie Coyle <[email protected]> Signed-off-by: Siri Varma Vegiraju <[email protected]>

Add example and mechanical markdown

33807c0

Signed-off-by: siri-varma <[email protected]>

Add example and mechanical markdown

738eee8

Signed-off-by: siri-varma <[email protected]>

Add example and mechanical markdown

e7fb13b

Signed-off-by: siri-varma <[email protected]>

Add example and mechanical markdown

4cfe6e7

Signed-off-by: siri-varma <[email protected]>

cicoyle previously approved these changes Apr 14, 2025

View reviewed changes

Merge branch 'master' into users/svegiraju/conversation-api-2

0b07cc7

Update conversation.yaml

6798bc2

Signed-off-by: artur-ciocanu <[email protected]>

artur-ciocanu dismissed cicoyle’s stale review via 6798bc2 April 14, 2025 22:53

artur-ciocanu requested changes Apr 15, 2025

View reviewed changes

Merge branch 'master' into users/svegiraju/conversation-api-2

720a427

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Conversation AI to Java SDK #1235

Add Conversation AI to Java SDK #1235

siri-varma commented Mar 6, 2025 •

edited

Loading

siri-varma commented Mar 6, 2025 •

edited

Loading

yaron2 commented Mar 6, 2025

salaboy commented Mar 6, 2025

siri-varma commented Mar 7, 2025 •

edited

Loading

salaboy Mar 13, 2025

salaboy Mar 13, 2025

siri-varma Mar 13, 2025 •

edited

Loading

salaboy commented Mar 13, 2025

siri-varma commented Mar 14, 2025 •

edited

Loading

salaboy commented Mar 14, 2025

siri-varma commented Mar 14, 2025

artur-ciocanu commented Mar 17, 2025

artur-ciocanu left a comment

siri-varma commented Mar 18, 2025

siri-varma commented Mar 24, 2025

cicoyle left a comment

cicoyle commented Apr 14, 2025

artur-ciocanu left a comment

artur-ciocanu Apr 14, 2025

artur-ciocanu Apr 14, 2025

artur-ciocanu Apr 14, 2025

cicoyle Apr 15, 2025

artur-ciocanu Apr 14, 2025

cicoyle Apr 15, 2025

artur-ciocanu Apr 14, 2025

artur-ciocanu Apr 15, 2025

artur-ciocanu Apr 15, 2025

artur-ciocanu Apr 15, 2025

artur-ciocanu Apr 15, 2025

artur-ciocanu Apr 15, 2025

cicoyle Apr 15, 2025

codecov bot commented Apr 15, 2025

cicoyle commented Apr 15, 2025

siri-varma commented Apr 20, 2025

		@@ -0,0 +1,117 @@
		## Manage Dapr Jobs via the Conversation API


		List<ConversationInput> daprConversationInputs = new ArrayList<>();
		daprConversationInputs.add(daprConversationInput);

		verify(daprStub, times(1)).converseAlpha1(captor.capture(), Mockito.any());

		DaprProtos.ConversationRequest conversationRequest = captor.getValue();

Add Conversation AI to Java SDK #1235

Are you sure you want to change the base?

Add Conversation AI to Java SDK #1235

Conversation

siri-varma commented Mar 6, 2025 • edited Loading

PR Overview: Conversation AI SDK Integration

Core Logic

API Contracts

Dapr Converse API

Models

Tests

Issue Reference

Checklist ✅

siri-varma commented Mar 6, 2025 • edited Loading

yaron2 commented Mar 6, 2025

salaboy commented Mar 6, 2025

siri-varma commented Mar 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

siri-varma Mar 13, 2025 • edited Loading

Choose a reason for hiding this comment

salaboy commented Mar 13, 2025

siri-varma commented Mar 14, 2025 • edited Loading

salaboy commented Mar 14, 2025

siri-varma commented Mar 14, 2025

artur-ciocanu commented Mar 17, 2025

artur-ciocanu left a comment

Choose a reason for hiding this comment

siri-varma commented Mar 18, 2025

siri-varma commented Mar 24, 2025

cicoyle left a comment

Choose a reason for hiding this comment

cicoyle commented Apr 14, 2025

artur-ciocanu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Apr 15, 2025

Codecov Report

cicoyle commented Apr 15, 2025

siri-varma commented Apr 20, 2025

siri-varma commented Mar 6, 2025 •

edited

Loading

siri-varma commented Mar 6, 2025 •

edited

Loading

siri-varma commented Mar 7, 2025 •

edited

Loading

siri-varma Mar 13, 2025 •

edited

Loading

siri-varma commented Mar 14, 2025 •

edited

Loading