protocol

# `ranker_protocol`

Protocol for machine learning rankers.

Availability:
`logtalk_load(ranking_protocols(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-05-06
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `learn/3`

Learns a ranker from the given dataset object using the specified options.

Compilation flags:
`static`
Template:
`learn(Dataset,Ranker,Options)`
Mode and number of proofs:
`learn(+object_identifier,-compound,+list(compound))` - `one`

### `learn/2`

Learns a ranker from the given dataset object using default options.

Compilation flags:
`static`
Template:
`learn(Dataset,Ranker)`
Mode and number of proofs:
`learn(+object_identifier,-compound)` - `one`

### `rank/3`

Ranks a list of candidate items using the learned ranker and returns the candidates ordered from most preferred to least preferred.

Compilation flags:
`static`
Template:
`rank(Ranker,Candidates,Ranking)`
Mode and number of proofs:
`rank(+compound,+list,-list)` - `one`

### `scores/2`

Returns the learned item-score pairs on the ranker native numeric scale. Depending on the ranker, these values may also be interpreted more specifically as strengths or ratings.

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

### `diagnostics/2`

Returns diagnostics and metadata associated with a learned ranker in a representation-independent way.

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

### `diagnostic/2`

Tests or enumerates individual diagnostics metadata terms for a learned ranker.

Compilation flags:
`static`
Template:
`diagnostic(Ranker,Diagnostic)`
Mode and number of proofs:
`diagnostic(+compound,?compound)` - `zero_or_more`

### `ranker_options/2`

Returns the effective training options recorded in a learned ranker diagnostics list.

Compilation flags:
`static`
Template:
`ranker_options(Ranker,Options)`
Mode and number of proofs:
`ranker_options(+compound,-list(compound))` - `zero_or_one`

### `check_ranker/1`

Checks that the argument is a structurally valid learned ranker term for the receiving ranker implementation, throwing an exception on invalid input when applicable.

Compilation flags:
`static`
Template:
`check_ranker(Ranker)`
Mode and number of proofs:
`check_ranker(@compound)` - `one_or_error`
Exceptions:
`Ranker` is a variable:
`instantiation_error`
`Ranker` is neither a variable nor a valid ranker:
`domain_error(ranker,Ranker)`

### `valid_ranker/1`

True when check_ranker/1 succeeds for the argument without throwing an exception.

Compilation flags:
`static`
Template:
`valid_ranker(Ranker)`
Mode and number of proofs:
`valid_ranker(@compound)` - `zero_or_one`

### `export_to_clauses/4`

Converts a ranker into a list of predicate clauses. `Functor` is the functor for the generated predicate clauses. When exporting a serialized ranker term, a noun such as `ranker` or `model` is usually clearer than a verb or result label.

Compilation flags:
`static`
Template:
`export_to_clauses(Dataset,Ranker,Functor,Clauses)`
Mode and number of proofs:
`export_to_clauses(+object_identifier,+compound,+callable,-list(clause))` - `one`

### `export_to_file/4`

Exports a ranker to a file. `Functor` is the functor for the generated predicate clauses. When exporting a serialized ranker term, a noun such as `ranker` or `model` is usually clearer than a verb or result label.

Compilation flags:
`static`
Template:
`export_to_file(Dataset,Ranker,Functor,File)`
Mode and number of proofs:
`export_to_file(+object_identifier,+compound,+callable,+atom)` - `one`

### `print_ranker/1`

Prints a ranker to the current output stream in a human-readable format.

Compilation flags:
`static`
Template:
`print_ranker(Ranker)`
Mode and number of proofs:
`print_ranker(+compound)` - `one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

bradley_terry_ranker, ranking_dataset_protocol, pairwise_ranking_dataset_protocol