Usage
=====

Installation
------------

To install ruly, call::

    pip install ruly

Quickstart
----------

Ruly's main use case can be summed up with the following code block:

.. code-block:: python

    import ruly

    knowledge_base = ruly.KnowledgeBase(
        'IF sound="croak" AND behavior="eats flies" THEN animal="frog"',
        'IF sound="chirp" AND behavior="sings" THEN animal="canary"',
        'IF animal="frog" THEN color="green"',
        'IF animal="canary" THEN color="yellow"')
    state = ruly.backward_chain(knowledge_base, 'color',
                                sound='croak',
                                behavior='eats flies')
    print(state['color'])
    # prints green
    print(state['animal'])
    # prints frog

We can see that there are two distinct separate steps taken in the usage -
knowledge base creation and backward chaining evaluation. Optionally,
additional arguments can be passed to evaluation functions, allowing caller to
further modify its behavior.

Knowledge base
--------------

The central point of the ruly's rule engine is a knowledge base. It serves as a
rule aggregator that evaluators use to derive other variable values. The
knowledge base is implemented in the following class:

.. autoclass:: ruly.KnowledgeBase
    :members:

Rule declaration
""""""""""""""""

Knowledge base requires a list of initial rules for creation and can add
additional rules after it's instantiated. Knowledge base's interface is such
that it accepts, strings, other knowledge bases or :class:`ruly.Rule` objects.
If strings are received, they are parsed into :class:`ruly.Rule` objects, more
on that in its separate section. The object that represents the rule itself has
the following signature:

.. autoclass:: ruly.Rule
    :members:

Rule's antecedent is a logical expression that, if evaluated to true, signifies
that rule should fire during evaluation. The consequent represents which value
will be added to a variable if the rule fires, represented as a standard
dictionary. The dictionary can be interpreted as the key-value pairs as the
part of the state affected by the firing rule.

Conditions
''''''''''

.. autoclass:: ruly.Condition
    :members:

.. automodule:: ruly.conditions
    :members:

Expressions
'''''''''''

.. autoclass:: ruly.Expression
    :members:

Parsing
'''''''

Rules can also be generated by parsing strings. For this, a parser function
needs to be defined. Ruly offers a default parser function at:

.. autofunction:: ruly.parse

Evaluation
----------

Ruly offers evaluation functions for individual rules and knowledge bases.

.. autofunction:: ruly.backward_chain

.. autofunction:: ruly.PostEvalCb

.. autofunction:: ruly.evaluate