durable_rules Documentation

The framework distinguishes between facts and events based on how they are identified:

• Facts: Identified by their property names and values. If you attempt to assert a fact that is identical to one already present, it will raise a MessageObservedError.
• Events: Identified by their posting time. Even if two events have identical properties, they are considered different because they are posted at different times. Durable.post will not raise an error for duplicate event properties.

In durable_rules, a rule is defined by two main components:

1. Antecedent: The pattern of events or facts that must match for the rule to trigger (defined using @when_all).
2. Consequent: The action to take when the antecedent is matched (the function body).

You define rulesets using a with ruleset('name'): block. To trigger a rule, you use post('name', data) to send an event or assert_fact('name', data) to add a fact to the knowledge base.

from durable.lang import *

with ruleset('test'):
        # antecedent
        @when_all(m.subject == 'World')
        def say_hello(c):
            # consequent
            print ('Hello {0}'.format(c.m.subject))

post('test', { 'subject': 'World' })

Identity allows rules to react to the existence or absence of specific attributes within the context using the $ex operator.

• $ex: Checks for the existence of a key.
• m$not: Negates the existence check (e.g., m$not with $ex checks if a key does NOT exist).

{
  "bookstore": {
    "r_0": {
      "all": [
        {
          "m": {
            "$ex": {
              "status": 1
            }
          }
        }
      ],
      "run": "log"
    },
    "r_1": {
      "all": [
        {
          "m": {
            "$ex": {
              "name": 1
            }
          }
        }
      ],
      "run": "retract"
    },
    "r_2": {
      "all": [
        {
          "m$not": {
            "$ex": {
              "name": 1
            }
          }
        }
      ],
      "run": "log"
    }
  }
}

Rules in durable_rules are defined using two main components: the antecedent (the condition) and the consequent (the action).

• all and any are used to label the antecedent definition. all requires all conditions to be met, while any requires at least one.
• run labels the consequent definition, specifying what happens when the antecedent is satisfied.

{
  "test": {
    "r_0": {
      "all": [
        {
          "m": {
            "subject": "World"
          }
        }
      ],
      "run": "approved"
    }
  }
}

Rules can evaluate changes in the context state. By convention, context state change events include the attribute "$s": 1. This allows you to trigger logic specifically when a state transition occurs.

{
  "flow": {
    "r_0": {
      "all": [
        {
          "m": {
            "$and": [
              {
                "state": "start"
              },
              {
                "$s": 1
              }
            ]
          }
        }
      ],
      "run": "next"
    }
  }
}

When defining event sequences, use these labels to control triggering logic:

• "all": A set of event or fact patterns. All of them must match to trigger the action.
• "any": A set of event or fact patterns. Any one match will trigger the action.

{
  "expense": {
    "r_0": {
      "any": [
        {
          "m_0$all": [
            { "first": { "subject": "approve" } },
            { "second": { "amount": 1000 } }
          ]
        },
        {
          "m_1$all": [
            { "third": { "subject": "jumbo" } },
            { "fourth": { "amount": 10000 } }
          ]
        }
      ],
      "run": "log"
    }
  }
}

Events are ephemeral facts that are retracted immediately before executing a consequent. This means an event can only be observed once. Events are useful for triggering logic based on transient occurrences without polluting the long-term knowledge base with facts.

Use Durable.post to dispatch an event.

require "durable"

Durable.ruleset :risk do
  when_all c.first = m.t == "purchase",
           c.second = m.location != first.location do
    puts "fraud detected -> #{first.location}, #{second.location}"
  end
end

Durable.post :risk, { :t => "purchase", :location => "US" }
Durable.post :risk, { :t => "purchase", :location => "CA" }

Facts are JSON objects asserted into the system that define the knowledge base. They are stored until they are explicitly retracted. When a fact satisfies a rule antecedent, the rule's consequent is triggered. You can use assert to add facts and retract to remove them.

In rules, you can capture data from facts using assignment within the antecedent (e.g., c.first = ...) to be used later in the consequent.

require "durable"

Durable.ruleset :animal do
  # Captures data into 'first' to be used in the consequent
  when_all c.first = (m.predicate == "eats") & (m.object == "flies") do
    assert :subject => first.subject, :predicate => "is", :object => "frog"
  end

  when_all +m.subject do
    puts "fact: #{m.subject} #{m.predicate} #{m.object}"
  end
end

Durable.assert :animal, { :subject => "Kermit", :predicate => "eats", :object => "flies" }