.. index:: single: ranker_protocol
.. _ranker_protocol/0:

.. rst-class:: right

**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)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: learn/3
.. _ranker_protocol/0::learn/3:

``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``


------------

.. index:: learn/2
.. _ranker_protocol/0::learn/2:

``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``


------------

.. index:: rank/3
.. _ranker_protocol/0::rank/3:

``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``


------------

.. index:: scores/2
.. _ranker_protocol/0::scores/2:

``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``


------------

.. index:: diagnostics/2
.. _ranker_protocol/0::diagnostics/2:

``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``


------------

.. index:: diagnostic/2
.. _ranker_protocol/0::diagnostic/2:

``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``


------------

.. index:: ranker_options/2
.. _ranker_protocol/0::ranker_options/2:

``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``


------------

.. index:: check_ranker/1
.. _ranker_protocol/0::check_ranker/1:

``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)``


------------

.. index:: valid_ranker/1
.. _ranker_protocol/0::valid_ranker/1:

``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``


------------

.. index:: export_to_clauses/4
.. _ranker_protocol/0::export_to_clauses/4:

``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``


------------

.. index:: export_to_file/4
.. _ranker_protocol/0::export_to_file/4:

``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``


------------

.. index:: print_ranker/1
.. _ranker_protocol/0::print_ranker/1:

``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)

.. seealso::

   :ref:`bradley_terry_ranker <bradley_terry_ranker/0>`, :ref:`ranking_dataset_protocol <ranking_dataset_protocol/0>`, :ref:`pairwise_ranking_dataset_protocol <pairwise_ranking_dataset_protocol/0>`