category

# `score_ranker_model_common`

Shared predicates for score-ranker term construction, validation, ranking, export, and pretty-printing.

Availability:
`logtalk_load(ranking_protocols(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-04-27
Compilation flags:
`static`
Extends:
`public` score_ranker_common
Uses:
avltree
format
list
Remarks:
(none)
Inherited public predicates:
check_option/1 check_options/1 check_ranker/1 default_option/1 default_options/1 diagnostic/2 diagnostics/2 export_to_clauses/4 export_to_file/4 learn/2 learn/3 option/2 option/3 print_ranker/1 rank/3 ranker_options/2 scores/2 valid_option/1 valid_options/1 valid_ranker/1

## Public predicates

(no local declarations; see entity ancestors if any)

## Protected predicates

### `score_ranker_model/1`

Hook predicate that importing rankers must define to identify the learned score-ranker model.

Compilation flags:
`static`
Template:
`score_ranker_model(Model)`
Mode and number of proofs:
`score_ranker_model(-atom)` - `one`

### `score_ranker_label/1`

Hook predicate that importing rankers must define to provide a human-readable label used by pretty-printing helpers.

Compilation flags:
`static`
Template:
`score_ranker_label(Label)`
Mode and number of proofs:
`score_ranker_label(-atom)` - `one`

### `score_ranker_term/4`

Hook predicate that importing rankers must define to map between the ranker term representation and its items, scores, and diagnostics payloads.

Compilation flags:
`static`
Template:
`score_ranker_term(Items,Scores,Diagnostics,Ranker)`
Mode and number of proofs:
`score_ranker_term(?list,?list,?list(compound),?compound)` - `zero_or_one`

### `valid_score/1`

Hook predicate that importing rankers must define to validate individual learned score values.

Compilation flags:
`static`
Template:
`valid_score(Score)`
Mode and number of proofs:
`valid_score(+number)` - `zero_or_one`

### `build_score_ranker/5`

Builds a self-describing score-ranker term from ordered items, score pairs, effective options, and dataset summary metadata.

Compilation flags:
`static`
Template:
`build_score_ranker(Items,Scores,Options,DatasetSummary,Ranker)`
Mode and number of proofs:
`build_score_ranker(+list,+list(pair),+list(compound),+list(compound),-compound)` - `one`

### `score_ranker_data/4`

Validates and destructures a score-ranker term into its items, score pairs, and diagnostics payloads.

Compilation flags:
`static`
Template:
`score_ranker_data(Ranker,Items,Scores,Diagnostics)`
Mode and number of proofs:
`score_ranker_data(+compound,-list,-list(pair),-list(compound))` - `one`

### `valid_score_ranker_diagnostics/3`

Hook predicate that importing rankers can define to validate diagnostics beyond the common model, options, and dataset summary metadata.

Compilation flags:
`static`
Template:
`valid_score_ranker_diagnostics(Items,Scores,Diagnostics)`
Mode and number of proofs:
`valid_score_ranker_diagnostics(+list,+list(pair),+list(compound))` - `zero_or_one`

### `initialize_scores/2`

Initializes a score dictionary with zero scores for the given ordered items.

Compilation flags:
`static`
Template:
`initialize_scores(Items,Scores)`
Mode and number of proofs:
`initialize_scores(+list,-compound)` - `one`

### `accumulate_item_scores/3`

Accumulates item score deltas into a score dictionary.

Compilation flags:
`static`
Template:
`accumulate_item_scores(ItemDeltas,Scores,UpdatedScores)`
Mode and number of proofs:
`accumulate_item_scores(+list(pair),+compound,-compound)` - `one`

### `update_score/4`

Updates the score of a single item in a score dictionary by adding the given delta.

Compilation flags:
`static`
Template:
`update_score(Scores,Item,Delta,UpdatedScores)`
Mode and number of proofs:
`update_score(+compound,+term,+number,-compound)` - `one`

### `ordered_scores/3`

Materializes ordered `Item-Score` pairs from a score dictionary using the given item order.

Compilation flags:
`static`
Template:
`ordered_scores(Items,ScoresDictionary,Scores)`
Mode and number of proofs:
`ordered_scores(+list,+compound,-list(pair))` - `one`

## Private predicates

(no local declarations; see entity ancestors if any)

## Operators

(none)