Add Conversation AI to Java SDK

[siri-varma]

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]

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

[yaron2]

Great contribution, thanks @siri-varma

[salaboy]

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

[siri-varma]

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]

@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]

@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

[salaboy]

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

[siri-varma]

@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]

@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.

[siri-varma]

@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]

@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!

[siri-varma]

@artur-ciocanu , @cicoyle let me know if you folks have any more feedback on this. Thank you.

[artur-ciocanu]

@siri-varma thanks for your contribution, I have no more comments, great job!

[artur-ciocanu]

@cicoyle and @salaboy could you please do a final pass. I have checked and everything looks good to me.

[siri-varma]

@cicoyle I think this PR is ready to merge unless you or @salaboy have any additional feedback. Thank you

[codecov]

Codecov Report

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

Project coverage is 77.42%. Comparing base (d759c53) to head (af02465).
Report is 136 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%   77.42%   +0.50%     
- Complexity     1592     1764     +172     
============================================
  Files           145      204      +59     
  Lines          4843     5368     +525     
  Branches        562      587      +25     
============================================
+ Hits           3725     4156     +431     
- Misses          821      899      +78     
- Partials        297      313      +16     

☔ 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.