Understanding Facts¶

Facts are the basis of logic within Vulcan. Facts represent the domain model for which Vulcan performs its reasoning via Rules. Collectively, they serve as input, output, and the state of intermediate reasoning steps. A collection of Fact definitions may be referred to as a "knowledge schema" or "Facts schema."

A simple Fact definition and instantiation:

1
2
3
4
5
6
7
8

from vulcan_core import Fact


class Inventory(Fact):
    apples: int


i = Inventory(apples=15)

Working Memory¶

The Vulcan Working Memory is a collection of Fact instances that represent the state of your domain model. For example, the working memory for a grocery story may contain Facts representing inventory, item types and prices, equipment temperatures, store operating hours, and so on. The working memory simultaneously serves as the input, output, and intermediate state of the rules engine.

In simple terms, the Working Memory can be thought of as a Python dictionary. However, a simple dictionary of key-value strings is insufficient to express non-trivial reasoning tasks. Therefore, Vulcan's Working Memory operates only on Fact objects, enabling complex expression of semantics and reasoning within Rules.

Fact Constraints¶

Vulcan's syntax is designed to be simple, yet flexible enough to express complex reasoning tasks. By leveraging Python's typing and metaprogramming features, Vulcan encourages a declarative style of programming that enhances the developer experience when used with modern IDE static analysis and autocompletion. As a result, boilerplate code and the possibility of errors are minimized.

To ensure a consistent and error-resistant interface for Vulcan rules, Vulcan imposes some requirements on how Facts may be defined and used.

Facts Must Extend the Fact Class¶

1
2
3
4

from vulcan_core import Fact


class Inventory(Fact): ...

Vulcan Facts must extend the base class vulcan_core.Fact. The Fact base class provides development conveniences, such as:

• Automatically apply Python dataclass functionality.
• Ensures that all Facts are immutable.
• Enforces that Facts may only be instantiated with keyword arguments.
• Adds operators for working with immutability, such as the union operator: |
• Provide dictionary-like access to the Fact's attributes.

Omitting the Fact base class will cause Facts to fail static and runtime checks:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from dataclasses import dataclass

from vulcan_core import RuleEngine


@dataclass
class Inventory:
    apples: int = 0


engine = RuleEngine()
engine.fact(Inventory(apples=5))  # (1)!

1

NotAFactError: 'Inventory' is not a Fact subclass

Type Hints are Required¶

1
2

class Inventory(Fact):
    apples: int = 0  # (1)!

Vulcan requires type information for all fields defined in a Fact. This helps to catch errors early in the development process and improve the overall reliability of the rules.

Facts missing type hints will result in static and runtime errors:

1
2
3
4
5

class Inventory(Fact):
    apples = 0


i = Inventory(apples=15)  # (1)!

1

TypeError: Inventory.__init__() got an unexpected keyword argument 'apples'

Keyword Instantiation is Required¶

1
2
3
4
5

class Inventory(Fact):
    apples: int = 0


i = Inventory(apples=15)  # (1)!

To facilitate readability and reduce the risk of errors, Vulcan enforces that all Facts must be instantiated with keyword arguments. This means that when creating an instance of a Fact, you must specify the names of the fields along with their values.

Positional arguments are not allowed when instantiating Facts and will result in static and runtime errors:

1
2
3
4
5

class Inventory(Fact):
    apples: int = 0


i = Inventory(15)  # (1)!

1

TypeError: Inventory.__init__() takes 1 positional argument but 2 were given

Facts are Immutable¶

Vulcan requires all Facts to be immutable. This means that once a Fact is created, its attributes cannot be modified. This immutability is crucial for ensuring the integrity of reasoning and preventing unintended side effects.

To simplify Fact manipulation with immutability, Vulcan provides a union operator similar to the dictionary union operator: |. Vulcan also allows partial creation of Facts using the functools.partial function. We will explore both of these features more in the Working With Facts section below.

Attempting to modify a Fact instance fields directly will result in static and runtime errors:

1
2
3
4
5
6
7

class Inventory(Fact):
    apples: int
    oranges: int = 0


i = Inventory(apples=15)
i.oranges = 20  # (1)!

1

FrozenInstanceError: cannot assign to field 'oranges'

Working With Facts¶

Facts are immutable to ensure the integrity of reasoning and prevent unintended side effects from actors external to the reasoning engine. Generally speaking, immutability can be difficult to work with, especially if applying design patterns that rely on mutability. In most use-cases Vulcan's Fact immutability should be of little inconvenience for developers - as long as Vulcan's interface contracts and best practices are followed.

Vulcan offers features to help make working with facts relatively easy. The first is that Vulcan supports the concept of a partial Facts using Python's functools.partial function. This allows partial instantiation and limited mutability, prior to the final instantiation of a Fact.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

from functools import partial

from vulcan_core import Fact


class Inventory(Fact):
    apples: int
    oranges: int


# Partial Fact representation, no `oranges` value:
i = partial(Inventory, apples=15)

# Modifying a partial Fact attribute before instantiation:
i = partial(i, apples=10)  # (1)!
print(f"Partial Object: {i}")

# Full Fact instantiation, also supplying an `oranges` value:
i = i(oranges=20)  # (2)!
print(f"Complete Object: {i}")

1. As long as a Fact is a partial Fact, any defined field may be modified.
2. Once the partial Fact has been fully instantiated, it may no longer be modified.

1
2

Partial Object: functools.partial(<class '__main__.Inventory'>, apples=10)
Complete Object: Inventory(apples=10, oranges=20)

Partial facts are most often found in a Rule's Action. For example a developer may intend to update only a portion of a Fact, without wanting to replace or repeat the values of the entire Fact.

Default Fact Values¶

You may have noticed in prior examples, that Fact fields may be defined with default values:

1
2
3
4

class Inventory(Fact):
    apples: int = 10  # (1)!
    oranges: int  # (2)!
    last_updated: str | None = None  # (3)!

1. A default value of 10
2. Fields without defaults will require a value at instantiation, or resolvable at runtime if the fact is a partial Fact.
3. A field with an optional and default value of None

Default values are optional. But if defaults are not defined, values will be required when the Fact is instantiated. This includes when a value is missing from a partial Fact. Static and runtime errors will be raised if default values are not provided at instantiation.

Fact Union Operator¶

Information represented by Facts is expected to change over time, but Fact immutability means that existing facts must be replaced by new Facts in order to update the overall state (working memory) of the rules engine. Vulcan Rules abstract the concerns of immutability away from developers, but there are times when a developer may want to create altered Facts outside of a Rule definition.

To make derivative Fact creation easier, Vulcan provides a union operator to combine a Fact instance with a partial Fact.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

class Inventory(Fact):
    apples: int
    oranges: int


# Initial Fact
i = Inventory(apples=15, oranges=20)
print(f"i: {i}, id: {id(i)}")

# A New Derived Fact object, with a different value for `apples`:
i = i | partial(Inventory, apples=100)
print(f"i: {i}, id: {id(i)}")

1
2

i: Inventory(apples=15, oranges=20), id: 128993665940464
i: Inventory(apples=100, oranges=20), id: 128993865646000

1
2
3
4
5
6
7
8
9

class Inventory(Fact):
    apples: int = 0
    oranges: int = 0
    bananas: int = 0


i1 = Inventory(apples=10, oranges=20, bananas=30)
i3 = i1 | Inventory(apples=100)  # (1)!
print(i3)

1

Inventory(apples=100, oranges=0, bananas=0)

Dictionary Key Access¶

Unlike typical Python dataclasses, Vulcan Facts also support dictionary-like access to their attributes. This allows greater interoperability with other Python libraries and tools, such as JSON serialization.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class Inventory(Fact):
    apples: int
    oranges: int


inv = Inventory(apples=15, oranges=20)
print(f"Value of 'apples' key: {inv['apples']}")

for k, v in inv.items():
    print(f"{k}: {v}")

1
2
3

Value of 'apples' key: 15
apples: 15
oranges: 20

Using Facts With Conditions and Actions¶

Facts are often used within Vulcan's condition and action Rule expressions. Vulcan uses a modified form of Python's lambda expression, to both allow linters and type checkers to validate the expression, while providing developers with a declarative syntax.

Conditions are used to determine if a Rule should be executed. Below is an example of using a Fact within a standalone condition:

1
2
3
4
5
6
7
8

from vulcan_core import condition


class Inventory(Fact):
    apples: int


apples_less_than_ten = condition(lambda: Inventory.apples <= 10)  # (1)!

1. Vulcan lambdas will only accept a <classname>.<fieldname> syntax for accessing Fact fields.

During Rule evaluation, Conditions and Actions are provided values from the Facts residing in Vulcan's working memory. In order for Vulcan to manage dynamic rule evaluation, access to specific Fact instance is not allowed in lambda expressions. If attempted, Conditions and Actions will raise a runtime error:

1
2
3

inv = Inventory(apples=15)

apples_less_than_ten = condition(lambda: inv.apples <= 10)

1

ScopeAccessError: Accessing undefined class 'inv'

Facts may also be used within Actions. When a Rule's Condition criteria is met, it will apply the Action to the working memory. Actions may apply Facts, partial Facts, and use lambda expressions to reference other Facts within the working memory.

Below are some ways in which Facts may be used within Actions:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

from vulcan_core import action


class Inventory(Fact):
    apples: int
    oranges: int


act1 = action(Inventory(apples=10, oranges=20))  # (1)!

act2 = action(partial(Inventory, apples=10))  # (2)!

act3 = action(lambda: partial(Inventory, apples=Inventory.apples + 10))  # (3)!

1. Replaces or creates a new Fact ignoring any existing values.
2. Replaces an existing Fact by merging the the specified values with the previous Fact. If the Fact is not present in the working memory, default values will be used for any missing fields.
3. Performs calculations prior to replacing or creating a new Fact.