feat: [Orchestration] Convenience for grounding metadata params

[Jonas-Isr]

Context

AI/ai-sdk-java-backlog#269

This PR introduces convenience for specifying additional metadata parameters for grounding calls through orchestration. It also includes appropriate unit and e2e tests.

Note: The use case for this feature according to the help.sap.com documentation of it is to receive additional information, i.e., the metadata of used chunks/documents, when using grounding via orchestration.

Feature scope:

• add convenience
• add tests
  • unit test
  • extend e2e test

Definition of Done

• Functionality scope stated & covered
• Tests cover the scope above
• Error handling created / updated & covered by the tests above
• Aligned changes with the JavaScript SDK
• Documentation updated
  • [Java 1.14.0]: Add convenience for metadata params for orchestration grounding calls ai-sdk#295
• Release notes updated

[Jonas-Isr]

I added this test since the only grounding unit test I saw was only testing low-level code (not our convenience).

[rpanackal]

(minor)

This looks a bit counter intuitive. Instead of setting metadataParams first and then conditionally removing it, we should just conditionally set it.

Suggested change

	.filters(filters)
	.metadataParams(metadataParams);
	// metadata_params field is not allowed for data repository type: `help.sap.com`
	.filters(filters);
	// metadata_params field is not allowed for data repository type: `help.sap.com`
	val hasHepSapCom =
	filters.contains(
	DocumentGroundingFilter.create().dataRepositoryType(DataRepositoryType.HELP_SAP_COM));
	if (!hasHepSapCom) {
	groundingConfigConfig.setMetadataParams(metadataParams);
	}

Then, you can also set the default value of field metadataParams to null

[Jonas-Isr]

This approach unfortunately does not work since if you do not set metadata params explicitly, the generated code will use an empty list which already leads to an error form grounding service when using help.sap.com.

I changed the default value of the field to null but unfortunately do not see how to improve the code snippet you marked (I agree that it doesn't look ideal).

[rpanackal]

(Question)

Correct me if I am wrong.

So the convenience only for passing the metadata_params in request but not inferring its result out of response, right?

[Jonas-Isr]

So the convenience only for passing the metadata_params in request but not inferring its result out of response, right?

Yes, exactly. And the only way to get the metadata out of the response is by parsing the string of grounding_result. This is (as far as I understand) mainly to give the LLM access to the metadata when answering.