Interface ScoringModel

All Known Implementing Classes:

CohereScoringModel, DecisionScoringModel, JinaScoringModel, OnnxScoringModel, VertexAiScoringModel, VoyageAiScoringModel, WatsonxScoringModel

public interface ScoringModel

Represents a model capable of scoring a text against a query.
Useful for identifying the most relevant texts when scoring multiple texts against the same query.
The scoring model can be employed for re-ranking purposes.

To support listeners, an implementation overrides doScore(ScoringRequest) and implements scoreAll(List, String) by calling score(ScoringRequest). It must never make scoreAll(List, String) call score(ScoringRequest) without overriding doScore(ScoringRequest): the default doScore(ScoringRequest) calls scoreAll(List, String), so each method would call the other.

Method Summary

Modifier and Type	Method	Description
default ScoringRequestParameters	defaultRequestParameters()	The model's default per-call parameters, applied by score(ScoringRequest) and scoreAsync(ScoringRequest) to every request and overridden by any parameters set on the request itself.
default ScoringResponse	doScore(ScoringRequest request)	The provider hook behind score(ScoringRequest).
default CompletableFuture<ScoringResponse>	doScoreAsync(ScoringRequest request)	The provider hook behind scoreAsync(ScoringRequest).
default List<ScoringModelListener>	listeners()	The listeners notified before each call of score(ScoringRequest) and scoreAsync(ScoringRequest), after each successful call and when a call fails.
default ModelProvider	provider()	The ModelProvider of this scoring model (for example ModelProvider.COHERE).
default Response<Double>	score(TextSegment segment, String query)	Scores a given TextSegment against a given query.
default ScoringResponse	score(ScoringRequest request)	Scores the documents of the given request against its query.
default Response<Double>	score(String text, String query)	Scores a given text against a given query.
Response<List<Double>>	scoreAll(List<TextSegment> segments, String query)	Scores all provided TextSegments against a given query.
default CompletableFuture<ScoringResponse>	scoreAsync(ScoringRequest request)	Scores the documents of the given request against its query without blocking the calling thread — the asynchronous/reactive counterpart of score(ScoringRequest), used by the non-blocking RAG flow (see ReRankingContentAggregator).

Method Details

score

default Response<Double> score(String text,
 String query)

Scores a given text against a given query.

Parameters:

text - The text to be scored.

query - The query against which to score the text.

Returns:

the score.

score

default Response<Double> score(TextSegment segment,
 String query)

Scores a given TextSegment against a given query.

Parameters:

segment - The TextSegment to be scored.

query - The query against which to score the segment.

Returns:

the score.

scoreAll

Response<List<Double>> scoreAll(List<TextSegment> segments,
 String query)

Scores all provided TextSegments against a given query.

Parameters:

segments - The list of TextSegments to score.

query - The query against which to score the segments.

Returns:

the list of scores. The order of scores corresponds to the order of TextSegments.

score

@Experimental
default ScoringResponse score(ScoringRequest request)

Scores the documents of the given request against its query.

This applies the model's default parameters, notifies the listeners and dispatches to doScore(ScoringRequest).

Parameters:

request - the documents to score, the query, and the per-call parameters.

Returns:

the scores, in the order of ScoringRequest.documents(), and the response metadata.

Since:

1.24.0

doScore

@Experimental
default ScoringResponse doScore(ScoringRequest request)

The provider hook behind score(ScoringRequest).

The default scores the documents with scoreAll(List, String), so a model that implements only scoreAll(List, String) also supports score(ScoringRequest). To do so, the default turns each document into a TextSegment, and a TextSegment cannot be blank: a model that implements only scoreAll(List, String) therefore cannot score blank documents through score(ScoringRequest), and such a request fails with an IllegalArgumentException.

To support listeners, override this method and implement scoreAll(List, String) by calling score(ScoringRequest), so that the listeners are also notified when scoreAll(List, String) is called. Never make scoreAll(List, String) call score(ScoringRequest) without overriding this method: each method would call the other.

Parameters:

request - the request, with the default parameters already applied.

Returns:

the scores, in the order of ScoringRequest.documents(), and the response metadata.

Since:

1.24.0

scoreAsync

@Experimental
default CompletableFuture<ScoringResponse> scoreAsync(ScoringRequest request)

Scores the documents of the given request against its query without blocking the calling thread — the asynchronous/reactive counterpart of score(ScoringRequest), used by the non-blocking RAG flow (see ReRankingContentAggregator).

This applies the model's default parameters, notifies the listeners and dispatches to doScoreAsync(ScoringRequest); a model becomes genuinely non-blocking by overriding the latter. This method never throws: any failure, including an invalid request, completes the returned future exceptionally.

When doScoreAsync(ScoringRequest) is not implemented, the returned future fails with an AsyncNotSupportedException, and the listeners are notified of it as an error (listeners that count errors may want to leave it out). A RAG component built with offloadBlocking(true) then runs the synchronous call (for example scoreAll(List, String)) on another thread, which the listeners observe as a separate call; without it, the RAG call fails with an UnsupportedFeatureException. When the returned future is cancelled, the listeners are notified of neither a response nor an error.

Parameters:

request - the documents to score, the query, and the per-call parameters.

Returns:

a CompletableFuture of the scores, in the order of ScoringRequest.documents().

Since:

1.20.0

doScoreAsync

@Experimental
default CompletableFuture<ScoringResponse> doScoreAsync(ScoringRequest request)

The provider hook behind scoreAsync(ScoringRequest). The default returns a failed future carrying AsyncNotSupportedException: a scoring model that is not genuinely asynchronous does not pretend to be. A model backed by remote HTTP I/O opts in by overriding this with a genuinely async call (no thread parked), and should abort its in-flight call when the returned future is cancelled (best-effort). A model that has not opted in fails loudly on the async path rather than silently blocking a carrier thread.

Parameters:

request - the (already defaults-applied) request to score.

Returns:

a CompletableFuture of the scores, in the order of ScoringRequest.documents().

Since:

1.20.0

defaultRequestParameters

@Experimental
default ScoringRequestParameters defaultRequestParameters()

The model's default per-call parameters, applied by score(ScoringRequest) and scoreAsync(ScoringRequest) to every request and overridden by any parameters set on the request itself. The default is ScoringRequestParameters.EMPTY.

Since:

1.20.0

listeners

@Experimental
default List<ScoringModelListener> listeners()

The listeners notified before each call of score(ScoringRequest) and scoreAsync(ScoringRequest), after each successful call and when a call fails. Listeners are configured on the builder of the scoring model. Defaults to an empty list.

Since:

1.24.0

provider

@Experimental
default ModelProvider provider()

The ModelProvider of this scoring model (for example ModelProvider.COHERE). It is made available to the listeners. Defaults to ModelProvider.OTHER.

Since:

1.24.0