Concepts

As discussed in the Introduction, Vulcan combines the power of LLMs with concepts from traditional rule-based AI expert systems to overcome limitations in an LLM's ability to understand and act on complex logic and arithmetic.

To put theory into operation, it is important to understand Vulcan's key concepts and terminology.

Types of Logic¶

The astute reader may have noticed that the Vulcan documentation often refers to two types of logic:

Computational vs Predictive Logic

Computational Logic: Logic that is deterministic and will always evaluate to the same result given the same input. Programming "if-then" statements and CPU arithmetic instructions are examples of computational logic.
Predictive Logic: Logic that is determined by statistical probability based on trained examples. LLMs are an example of predictive logic, and given any variance to the input (even if not substantive) the result may change.

One goal of Vulcan is to replace predictive logic situations in LLM use-cases with the consistency and correctness of computational logic. Vulcan achieves this through rule expressions that are able to process complex logic and arithmetic computationally.

Despite their flaws in reasoning, LLMs' predictive nature allows them to excel in processing natural language and generalization of concepts. Vulcan leverages these strengths by seamlessly incorporating LLM usage into rule definition and evaluation.

Rules¶

Vulcan has 3 key concepts that are used to define rules:

Key Concepts

Facts: Comparable to variables in imperative programming, Facts are object-oriented representations of various data and states used to determine which rules to evaluate. They are referenced within conditional statements to define when rules should fire their actions. Internally, Facts are stored in a data structure known as "working memory".
Conditions: Conditions are the "if" statement of a rule, determining whether the rule's Action should be executed. Conditions may combine the evaluation of Facts in the Working Memory with LLM prompting and vector similarity searching.
Actions: Actions declare the changes to the Working Memory's Facts if the rule's Conditions are met.

Combined, these concepts are used to define Rules in Python¹ code. A simple example of a Rule is as follows:

Python
class SomeFact(Fact):
    some_property: int = 0
    another_property: bool

engine.rule(
    when=condition(lambda: SomeFact.some_property > 10),
    then=action(SomeFact(another_property=True)),
)

Developer Note

Internally, Vulcan uses Python metaprogramming and AST transformation to make the API more concise and usage-error resistant. Special care has been taken to ensure that IDEs and linters will provide accurate feedback and code completion in contexts they would normally fail, as well as enforce design patterns in contexts that would normally succeed. For best results, developers should think of Vulcan's API as a domain-specific language with a set of opinionated design patterns.

Whenever Facts in the Working Memory are added or updated, Vulcan evaluates rules with criteria matching the changed Facts. As Rules may also change the Working Memory, an intentional cascade of Rules firing other Rules may occur. Vulcan will continue to evaluate and fire rules until no more Facts are changed (or a recursion limit is met).

Visually this can be represented as:

flowchart TD
    subgraph rm[Rule Matcher]
    end

    subgraph rule[Rule]
        direction LR
        Facts-->|Used In|Condition-->|Fires|Action
    end

    subgraph wm[Working Memory]
        global[Facts]
    end

    wm-->|Triggers|rm
    rm-->|Evaluates|rule
    rule-->|Updates|wm

By design, Actions may only work with Facts in the Working Memory and should avoid interacting directly with other code or state. This pattern allows Vulcan to optimize and defer internal operations, improving overall performance, but also enabling guaranteed deterministic behavior and explainability.

This may seem limiting at first, but external interaction is easily achieved through the use of Fact Listeners. These listeners attach to the Working Memory and are triggered whenever a Fact is changed. This allows developers to interact with the outside world in a controlled and predictable manner.

Vulcan "Plus" Edition also supports YAML-based fact and rule definition. ↩