Agents
======

Introduction
------------

The client assumes that the agent would be present in a separate python package.
Thus, we rely on `Entry Points`_ to register the agent. The entrypoint specification
can be used by a python package to register an algorithm by specifying a key value
pair in setup.py/pyproject.toml for the package where the key would be the name of
the algorithm and the value is the path to the algorithm class relative to the
package root. Refer to :ref:`the registration section<Sample Detector and Registration>`
for an example.

Functions Used By the Protocol
------------------------------

The protocols assumes that the algorithm have the following functions during evaluation

1. :code:`FeatureExtraction`: Primarily used for extracting features from the input
   modality so that it can be used by other stages of the algorithm.
2. :code:`WorldDetection`: Encapsulates the functionality that is used by detecting
   change in distribution during an experiment. The logic in this function is used
   to determine the introduction of novelty in an experiment.
3. :code:`NoveltyClassification`: Used for providing the probability of a sample being
   novel or known. The probability of known class is subdivided into a distribution over
   all the known classes. This results in a prediction of k+1 values for every sample,
   where k is the number of known classes and 1 value is reserved predicting that the sample
   is novel.
4. :code:`NoveltyCharacterization`: Similar to :code:`NoveltyClassification` function with
   one major difference in the output. The probability of unknown class is subdivided
   into a distribution over the unknown classes. This results in a prediction of k+d+1 values
   for every sample, where k is the number of known classes, d is the number of discovered
   classes and 1 value is reserved for the probability that the sample is novel.
5. :code:`NoveltyAdaption`: Used by the algorithm to update its internal state after
   it had provided results for :code:`WorldDetection` and :code:`NoveltyClassification`/
   :code:`NoveltyCharacterization` depending on the protocol.

Adapters
--------

Rather than enforcing a strict API for the functions required by the algorithms,
sail on client provides adapters to fulfill input-output requirements of an algorithm.
The adapters are provided a dictionary with the parameters obtained from the harness.

Sample Adapter
^^^^^^^^^^^^^^

.. literalinclude:: ../../../sail_on_client/agent/mock_ond_agents.py
   :language: python
   :lines: 162-197

Sample Detector and Registration
--------------------------------

Sample Detector
^^^^^^^^^^^^^^^

.. literalinclude:: ../../../sail_on_client/agent/mock_ond_agents.py
   :language: python
   :lines: 19-129

Registering the Detector
^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
    The registration is highlighted below.

.. literalinclude:: ../../../pyproject.toml
   :language: toml
   :lines: 57-69
   :emphasize-lines: 6

.. Appendix 1: Links

.. _Entry Points: https://packaging.python.org/specifications/entry-points/