clara.tools.inspect

Tooling to inspect a rule session. The two major methods here are:

  • inspect, which returns a data structure describing the session that can be used by tooling.
  • explain-activations, which uses inspect and prints a human-readable description covering why each rule activation or query match occurred.

->Explanation

(->Explanation matches bindings)

Positional factory function for class clara.tools.inspect.Explanation.

ConditionMatch

A structure associating a condition with the facts that matched them. The fields are: :fact - A fact propagated from this condition in a rule or query. For non-accumulator conditions, this will be the fact matched by the condition. For accumulator conditions, it will be the result of the accumulation. So, for example, if we have a condition like

    [?cold <- Cold]

    a ConditionMatch for this condition will have a Cold fact in its :fact field.  If we have a condition like

    [?min-cold <- (acc/min :temperature) :from [Cold]]

    the value of :fact will be the minimum temperature returned by the accumulator.

:condition - A structure representing this condition. This is the same structure used inside the structures defining rules and queries.

:facts-accumulated (nullable) : When the condition is an accumulator condition, this will contain the individual facts over which the accumulator ran. For example, in the case above with the condition

                             [?min-cold <- (acc/min :temperature) :from [Cold]]

                             this will contain the individual Cold facts over which we accumulated, while the :fact field
                             will contain the result of the accumulation.

explain-activations

(explain-activations session & {:keys [rule-filter-fn], :as options})

Prints a human-friend explanation of why rules and queries matched in the given session. A caller my optionally pass a :rule-filter-fn, which is a predicate

(clara.tools.inspect/explain-activations session :rule-filter-fn (fn [rule] (re-find my-rule-regex (:name rule))))

inspect

(inspect session)

Inputs: [session]

Returns a representation of the given rule session useful to understand the state of the underlying rules.

The returned structure includes the following keys:

  • :rule-matches – a map of rule structures to their matching explanations.
  • :query-matches – a map of query structures to their matching explanations.
  • :condition-matches – a map of conditions pulled from each rule to facts they match.
  • :insertions – a map of rules to a sequence of {:explanation E, :fact F} records to allow inspection of why a given fact was inserted.
  • :fact->explanations – a map of facts inserted to a sequence of maps of the form {:rule rule-structure :explanation explanation}, where each such map justifies a single insertion of the fact.

Users may inspect the entire structure for troubleshooting or explore it for specific cases. For instance, the following code snippet could look at all matches for some example rule:

(defrule example-rule … )

(get-in (inspect example-session) [:rule-matches example-rule])

The above segment will return matches for the rule in question.

InspectionSchema

map->Explanation

(map->Explanation m11926)

Factory function for class Explanation, taking a map of keywords to field values, but not much slower than ->x like the clojure.core version. (performance is fixed in Clojure 1.7, so this should eventually be removed.)

strict-map->Explanation

(strict-map->Explanation m11927 & [drop-extra-keys?__2290__auto__])

Factory function for class Explanation, taking a map of keywords to field values. All keys are required, and no extra keys are allowed. Even faster than map->