.. _rules:

Specifying Rules
=================

The rules within this software are specified as Python functions (see :ref:`Example <rule example>`).
These functions play a crucial role in processing events within SimProv.
To maintain clarity and distinguish rule functions from other functions, such as auxiliary functions for file manipulation, we enforce the use of the :py:func:`@rule<simprov.rule_engine.rule>` decorator on every rule function.

Each rule function must be annotated with the :py:func:`@rule<simprov.rule_engine.rule>` decorator, ensuring clarity in function identification.
Additionally, the event type for which the rule function is intended must be passed as an argument to this decorator.

During the loading of rules, the SimProv evaluates these decorators, creating an internal mapping in the :py:class:`rule engine<simprov.rule_engine.RuleEngine>` between event types and their corresponding rule functions.
This mapping facilitates execution of the rule function associated with the type attribute of incoming events.
Events lacking a defined rule function are rejected and recorded in the error log for further analysis.

Rule functions are structured as unary functions, accepting an event dictionary as input and returning a provenance activity represented by an :py:class:`Activity<simprov.provenance.Activity>` object.
Within these functions, entities, each belonging to the :py:class:`Entity<simprov.provenance.Entity>` class, must be instantiated and configured using event information.
These entities are then designated as either used or generated by the activity.
Optionally, agents, objects of the :py:class:`Agent<simprov.provenance.Agent>` class, can also be associated with the activity for further contextualization.

.. _rule example:
.. include:: incl/rule.rst