feat: Orchestration Grounding convenience

[CharlesDuboisSAP]

Context

AI/ai-sdk-java-backlog#167.

TheGrounding configuration is full of boilerplate code. I added a layer of convenience.

Feature scope:

• Created Grounding convenience

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
• Release notes updated

[newtork]

(Major)

Please make this a required argument. I doubt we can use someID globally.

[CharlesDuboisSAP]

It should be useless, I set it to empty string

[newtork]

(Minor/Comment)

According to spec this identifier shall be unique per request.
Multiple filters are possible per requset.

See spec

GroundingModuleConfig:
  type: object
  required:
    - type
    - config
  additionalProperties: false
  properties:
    type:
      ...
    config:
      type: object
      required:
        - input_params
        - output_param
      additionalProperties: false
      properties:
        filters:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/DocumentGroundingFilter"
          description: Document grounding service filters to be used
        ...

DocumentGroundingFilter:
  type: object
  required:
    - id
    - data_repository_type
  additionalProperties: false
  properties:
    id:
      $ref: "#/components/schemas/GroundingFilterId"

...

GroundingFilterId:
  title: Id
  description: Identifier of this SearchFilter - unique per request.

GroundingFilterSearchConfiguration:
  ...

With the proposed convenience API we are

• limiting users to define exactly one filter - this is why "id" seems unnecessary.
• sending a filter no matter what - is this a requirement, that at least one filter must be present?
• not blocking future changes to cardinality - which is good. Looks like we could easily extend the logic.

[newtork]

Therefore:
Would allow for setting multiple filter on Grounding then for 1..*?
Or will you keep the cardinality 1?
Is 0 filters an option we have to consider?

[CharlesDuboisSAP]

I modified the API to allow 1+ filters.
0 filters is not allowed because we have to specify the repository type

[newtork]

(Comment)

I was looking into other API options where we could increment a number for id implicitly, but they weren't really promising:

Using handler

Suggested change

	// optional filter for document chunks
	val databaseFilter =
	DocumentGroundingFilter.create()
	.id("")
	.dataRepositoryType(DataRepositoryType.VECTOR)
	.searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(1))
	.documentMetadata(List.of(documentMetadata));
	val groundingConfig = Grounding.create().filter(databaseFilter);
	// optional filter for document chunks
	val groundingConfig =
	Grounding.create()
	.filterForType(DataRepositoryType.VECTOR)
	.apply(filter -> filter
	.searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(1))
	.documentMetadata(List.of(documentMetadata)));

Using return state

Suggested change

	// optional filter for document chunks
	val databaseFilter =
	DocumentGroundingFilter.create()
	.id("")
	.dataRepositoryType(DataRepositoryType.VECTOR)
	.searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(1))
	.documentMetadata(List.of(documentMetadata));
	val groundingConfig = Grounding.create().filter(databaseFilter);
	// optional filter for document chunks
	val groundingConfig = Grounding.create();
	groundingConfig
	.filterForType(DataRepositoryType.VECTOR)
	.searchConfig(GroundingFilterSearchConfiguration.create().maxChunkCount(1))
	.documentMetadata(List.of(documentMetadata));

[CharlesDuboisSAP]

This is a filter for 1 request, the id can be empty