Chunks and Rules

This specification defines a cognitive graph database model featuring chunks as collections of properties, and rules that operate on them in conjunction with highly scalable graph algorithms, together with a simple notation for serializing graphs as a convenient abstraction above RDF. The model reflects functional characteristics of human memory and cognition, including stochastic recall and the forgetting curve. Chunks & Rules provide an attractive framework for low-code real-time control of digital twins for the Internet of Things, decoupled from the details of communication technologies and standards, using asynchronous messaging that enables distributed implementations and integration with robot systems based upon ROS (the robot operating system), see [[CHUNKS-LOWCODE]]

Chunks and graphs

A chunk is a named typed collection of [=properties=]. A [=chunk=] is used to model both declarative knowledge and procedural knowledge as a collection of basic familiar units that have been grouped together and stored in memory.

A [=chunk=] has a [=type=] and an optional [=identifier=].

dog dog1 {
  name "Fido"
  age 4
}

or using the compact syntax:

dog dog1 {name "Fido"; age 4}

This [=chunk=] describes a dog named "Fido" that is 4 years old. The chunk [=type=] is dog. Its [=identifier=] is dog1 and uniquely identifies this chunk within the graph it is defined in. The chunk has two [=properties=]:

name whose value is the [=string literal=] "Fido"
age whose value is the [=number=] 4

The interpretation of age as being stated in years is application dependent. Applications could choose to declare the units with an associated [=property=], e.g. age-units as an application dependent solution. A more general approach is proposed in the section [[[#data-models]]].

Chunk type

A chunk type is a [=name=] that documents the nature of a chunk. The [=type=] is used to group and index chunks. [=Rules=] typically apply to chunks of a given [=type=].

person Dave {
  knows Francois
}

As a special case, the [=type=] may be formed by a single asterisk (*), which is used to describe a [=condition=] or [=action=] that matches any chunk [=type=].

Chunk identifier

The chunk identifier is a [=name=] that uniquely identifies a chunk within the graph it is defined in.

The chunk [=identifier=] is optional. If missing, it will be automatically assigned when the chunk is added to a chunk module.

Chunk properties

A chunk property is a [=name=]/[=value=] pair that describes a chunk across the particular dimension identified by the property name.

A value is either an [=atomic value=] or an ordered list of [=atomic values=] (values are comma-separated in serialized form).

An atomic value is either:

a [=name=], which can for instance be used to reference other chunks
a [=number=]
a [=boolean=] (true or false)
a [=date=]
a [=string literal=]

A property [=value=] |a| equals property [=value=] |b| when the following algorithm returns true:

If |a| is the [=wild card operator=] *, return true.
If |b| is the [=wild card operator=] *, return true.
If |a| is the [=negation operator=] !, return false.
If |b| is the [=negation operator=] !, return false.
If |a| is a [=name=] that starts with the [=negation operator=] !, return false if !|a| [=equals=] |b|, true otherwise.
If |b| is a [=name=] that starts with the [=negation operator=] !, return false if |a| [=equals=] !|b|, true otherwise.
If |a| is a [=variable=] that is not yet [=bound=] to a value, return true.
If |b| is a [=variable=] that is not yet [=bound=] to a value, return true.
If |a| is a [=variable=] [=bound=] to a value |v|, return true if |v| [=equals=] |b|, false otherwise.
If |b| is a [=variable=] [=bound=] to a value |v|, return true if |a| [=equals=] |v|, false otherwise.
If |a| and |b| are identical [=atomic values=], return true.
If |a] and |b| are lists of [=atomic values=], both lists have the same length, and [=atomic values=] at the same position in |a| and |b| are [=equal=], return true.
Otherwise, return false.

Chunk context

A [=chunk=] may be scoped to a context, which identifies the specific situation under which the [=chunk=] should be considered to be true. This mechanism allows [=chunks=] to describe things that are only true in hypothetical situations.

[=Contexts=] can be used to express situations that involve the use of statements about statements, including beliefs, stories, reported speech, examples in lessons, abductive reasoning and even search query patterns. They are also useful for episodic memory when one wants to describe facts that are true in a given situation, for instance an episode when a person visited a restaurant for lunch, sat by the window, and had soup for starters followed by mushroom risotto for the main course. A sequence of episodes can then be modelled as relationships between contexts.

A [=chunk=] is associated with a specific [=context=] through an [=@context=] [=property=].

A [=chunk=] that is not explicitly associated with a [=context=] (i.e. in the absence of an [=@context=] property) belongs to the default context.

Here is an example from John Sowa's Architectures for Intelligent Systems:

Tom believes that Mary wants to marry a sailor.

This example involves talking about a statement Mary wants to marry a sailor that is only known to be true according to Tom's belief. When represented as [=chunks=], the statement needs to be associated with a [=context=] that identifies Tom's belief, so that we cannot directly assert that the statement is true in general.

Similarly, the statement to marry a sailor is only known to be true according to Mary's desire. When represented as [=chunks=], the statement also needs to be associated with a [=context=] that identifies Mary's desire.

Here is one possible way to represent the overall statement with [=chunks=]:

believes {
  @subject tom
  proposition tom-belief-1
}
wants {
  @context tom-belief-1
  @subject mary
  situation mary-desire-1
}
married-to {
  @context mary-desire-1
  @subject mary
  @object s1
}
a s1 {
  @context mary-desire-1
  profession sailor
}

As illustrated in the previous example, [=contexts=] can be chained, e.g. to describe the beliefs of someone in a fictional story or movie, and to indicate when a context is part of several other contexts, thus creating a tree of [=contexts=].

Practically speaking, [=contexts=] make it possible to filter out non relevant [=chunks=] in [=conditions=] and [=actions=]. Two [=chunks=] may only [=match=] when they belong to the same context. For instance, a [=chunk=] that belongs to the context tom-belief-1 can only [=match=] [=chunks=] that also belong to that context, and de facto cannot match [=chunks=] that belong to the [=default context=]. In particular, a [=chunk=] that belongs to the [=default context=] can only [=match=] [=chunks=] that also belong to the [=default context=].

Is there a need for a limited form of automatic inheritance, e.g. when matching chunks in a context for a fictional account, should this also match chunks in the parent context? This would allow general knowledge to apply by default within fictional accounts.

Links between chunks

In this document, a link is a directed and labeled connection between two [=chunks=]. A [=link=] is automatically created whenever a chunk property [=value=] is a [=name=] that references an existing chunk [=identifier=].

The subject of the [=link=] identifies the [=chunk=] at the origin of the connection. The object of the [=link=] identifies the [=chunk=] targeted by the connection. The label of the [=link=] is the property [=name=].

friend f34 {
  name Joan
}
friend f35 {
  name Jenny
  likes f34
}

The above definition creates a link between f35 and f34 with the relationship likes.

When a [=chunk=] links to another [=chunk=], this implicitly creates a third [=chunk=] whose [=type=] is the name of the [=property=] that creates the [=link=], and that has two [=properties=]:

@subject: references the [=subject=] of a [=link=]
@object: references the [=object=] of a [=link=]

animal dog {
  kindof mammal
}

The previous definition implicitly creates the following [=chunk=]:

kindof {
  @subject dog
  @object mammal
}

The grammar allows to express [=links=] in a compact format in a [=chunks document=], e.g.:

dog kindof mammal
cat kindof mammal

This is equivalent to:

kindof {
  @subject dog
  @object mammal
}
kindof {
  @subject cat
  @object mammal
}

Graph of chunks

A graph of chunks is simply a collection of [=chunks=]. The vertices of the graph are the [=chunks=]. The edges of the graph are the [=links=] between the chunks.

Since [=links=] are directed, a [=graph of chunks=] is a directed graph.

Rules and modules

Rules

A rule is a [=chunk=] whose [=type=] is rule and that has:

an @condition [=property=], whose value is a chunk [=identifier=] or a list thereof, and which is used to reference the rule's [=conditions=].
an @action [=property=], whose value is a chunk [=identifier=] or a list thereof, and which is used to reference the rule's [=actions=].

A [=rule=] represents a unit of procedural knowledge. Rules consist of [=conditions=] and [=actions=].

The following [=rule=] has one [=condition=] (that holds true when the goal [=module buffer=] contains a [=chunk=] whose [=type=] is remember), and two [=actions=] that clears the goal [=module buffer=] and that loads a [=chunk=] whose type is memory in the facts [=module=]:

rule r1 {
  @condition c1
  @action a1, a2
}

remember c1 {}
next a1 { @do clear }
memory a2 { @module facts }

The grammar allows to express [=rules=] in a compact format in a [=chunks document=]. For instance, the previous example may be written as:

remember {} => next { @do clear },  memory { @module facts }

This compact format makes the link between [=conditions=] and [=actions=] more explicit and avoids the need to provide chunk [=identifiers=].

Conditions

A condition is a [=chunk=] that describes the premises that must hold true for a [=rule=] to apply. A [=condition=] identifies which [=module=] it relates to through an [=@module=] property, defaulting to the goal module. A [=condition=] holds true when the [=chunk=] in the related [=module buffer=] is a [=matching chunk=] for the [=condition=].

Actions

An action is a [=chunk=] that can directly update [=module buffers=], or can do so indirectly, e.g. by sending messages to the [=module=] to invoke graph algorithms, such as graph queries and updates, or to carry out operations, e.g. instructing a robot to move its arm. When the algorithm or operation is complete, a response can be sent back to update the module's buffer. This in turn can trigger further rules as needed. An [=action=] identifies which [=module=] it relates to through an [=@module=] property, defaulting to the goal module.

In many cases, the actual operation that an [=action=] will carry out will appear as an [=@do=] property. Built-in operations are always supported (see ). Other actions may be supported. See section [[[#scripting-api]]] for a means for applications to define additional actions, e.g. as a way to invoke external actions for operating a robot arm or camera.

Matching chunks

A [=chunk=] |A| matches [=chunk=] |B| if the conditions below are all met:

Context. One of the following conditions holds true:
- Neither |A| nor |B| have [=@context=] properties.
- Both |A| and |B| have [=@context=] properties and |A|'s [=@context=] property [=value=] [=equals=] |B|'s [=@context=] property [=value=].
Identifier. One of the following conditions holds true:
- |A| has an [=@id=] property whose [=value=] is an [=atomic value=] that [=equals=] |B|'s [=identifier=].
- |A| does not have an [=@id=] property.
Inheritance. One of the following conditions holds true:
- |A| has an [=@kindof=] property whose [=value=] |V| is an [=atomic value=], and |B|'s [=type=] is a subclass of |V|, meaning that |B|'s [=type=] is |V| or there exists a chain of kindof links between |V| and |B|'s [=type=].
- |A| does not have an [=@kindof=] property.
Properties. For each [=property=] |p| in |A| whose [=name=] does not start with @, either of the following holds true:
- |p|'s [=value=] is ! and there is no [=property=] in |B| with |p|'s [=name=].
- |p|'s [=value=] is not ! and there exits a [=property=] in |B| with the same [=name=] and [=equal=] [=value=] as |p|.
Type. One of the following conditions holds true:
- |A| has an [=@type=] property whose [=value=] is an [=atomic value=] that [=equals=] |B|'s [=type=].
- |A| does not have an [=@type=] property, and |A|'s [=type=] is *.
- |A| does not have an [=@type=] property, and |A|'s [=type=] and |B|'s [=type=] are identical.

@-properties for conditions and actions

The [=reserved names=] defined in this section may be used as [=property=] names in [=conditions=] and [=actions=] to control their behavior.

The `@compile` property

This used in a rule action to compile a set of chunks in declarative memory into a set of rules in procedural memory. The process starts with the chunk that cites the chunks used for the conditions and actions, and then applies to those chunks. Note that @compile may cite a list of IDs for chunks to be compiled.

put {@compile rule1; @map map1}

The above [=action=] looks for a chunk with ID rule1 in the default module and compiles it using the mappings specified in the chunk with ID map1 as specified with @map. The chunk type and ID are copied as is.

The `@context` property

When used in a regular [=chunk=], identifies a chunk's [=context=]. When used in a [=condition=] or in an [=action=], [=matches=] a [=chunk=]'s [=context=].

recall { lunch ?restaurant }
     => lookup { @module facts; @do get; @type lunch; @context ?restaurant }

The above [=rule=] defines an [=action=] that looks for a [=chunk=] in the facts [=module=] whose [=type=] is lunch and whose [=context=] is the identifier of the lunch matched by the recall [=condition=].

The `@do` property

Specifies the graph algorithm or operation to execute. See for a list of common operations that are supported across modules.

The `@for` property

Iterates over a set of items in a comma separated list. The [=@from=] and [=@to=] properties may be used to restrict the iteration range.

The `@from` property

Specifies the zero-based starting index of an [=@for=] iteration. Value must be an integer.

# a chunk in the facts module
person {name Wendy; friends Michael, Suzy, Janet, John}

# after having recalled the person chunk, the
# following rule iterates over the friends
person {@module facts; friends ?friends}
   => item {@module goal; @for ?friends; @from 1; @to 2}

which will iterate over Suzy and Janet, updating the module buffer by setting properties for the item's value and its index, e.g.

item {value Suzy; @index 1; @more true}

The action's properties are copied over apart from those starting with an @. The item index in the list is copied into the chunk as [=@index=]. You can then use [=@do next=] in an action to load the next item into the buffer. The [=@more=] property is set to true in the buffer if there is more to come, and false for the last property in the iteration. Action chunks should use either [=@do=] or [=@for=], but not both. Neither implies @do update.

The `@id` property

This is used in rule actions together with a value specify the chunk ID, e.g. to get a chunk with a given ID, or to add, update or replace an existing chunk with that ID.

The `@index` property

Used as part of an iteration over the values in a comma separated list with [=@for=].

The `@kindof` property

[=Matches=] a [=chunk=]'s [=type=] when that [=type=] is linked to the value of the [=@kindof=] property through a chain of kindof links. The property should be used in conjunction with a * type to match subclasses of a given class in a taxonomy.

Given the following facts in a facts [=module=]:

penguin kindof bird
eagle kindof bird
penguin p6 { name Pingou }

The following [=condition=] would match the [=chunk=] p6 if it was in the [=module buffer=] of the facts [=module=]:

* cond1 {
  @module facts
  @kindof bird
}

The `@map` property and chunk type

This is used with [=@compile=] and [=@uncompile=] to reference a chunk of type [=@map=] that defines a map for property names and their meanings. See also the [=@unmap=] property.

@map map1 {do @do; condition @condition; action @action; module @module}

The above [=chunk=] signifies that do is to be interpreted as [=@do=], condition is to be interpreted as [=@condition=], action is to be interpreted as [=@action=], and so forth. By mapping property names in this way, rules can be used to operate on chunks in declarative memory free of the difficulties posed by properties with the @ prefix. The above example would be appropriate for a [=chunk=] such as the following:

rule r1 {condition g1; action a1, a2, a3}

which is mapped to:

rule r1 {@condition g1; @action a1, a2, a3}

The `@module` property

References the [=module=] a [=condition=] or [=action=] relates to. Value must be the [=module name=] of the targeted [=module=]. In the absence of an [=@module=] property, [=conditions=] and [=actions=] apply to the goal module.

The `@more` property

Queries the [=boolean=] flag set to true by the [=rule engine=] on the current [=chunk=] in [=@for=] and [=@do properties=] iterations when there are remaining [=chunks=] to iterate over.

The `@pop` property

An [=action=] property that removes the last [=atomic value=] from a [=value=]. If the [=value=] to process is already an [=atomic value=], the underlying property is removed.

If a [=@to=] property is also present, the removed [=atomic value=] is assigned to the [=property=] identified by the [=@to=] property. In the absence of a [=@to=] property, the removed [=atomic value=] is discarded.

Given the following [=chunk=] and [=action=]:

digits { list 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }
digits { @pop list, @to item }

The [=action=] will update the [=chunk=] to:

digits {
  list 0, 1, 2, 3, 4, 5, 6, 7, 8
  item 9
}

The `@priority` property

The @priority property lets actions set the [=priority=] of a [=chunk=] when they add it to the queue for a module buffer (see [=module buffer=]).

The `@push` property

An [=action=] property that pushes an [=atomic value=] to the end of the [=value=] of the property identified by a companion [=@to=] property. If the targeted property does not exist yet, it is created.

In the absence of a [=@to=] property, this operation has no effect.

Given the following [=chunk=] and [=action=]:

digits { list 0, 1, 2, 3, 4, 5, 6, 7, 8 }
digits { @push 9, @to list }

The [=action=] will update the [=chunk=] to:

digits { list 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }

The `@shift` property

An [=action=] property that removes the first [=atomic value=] from a [=value=]. If the [=value=] to process is already an [=atomic value=], the underlying property is removed.

Given the following [=chunk=] and [=action=]:

digits { list 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }
digits { @shift list, @to item }

The [=action=] will update the [=chunk=] to:

digits {
  list 1, 2, 3, 4, 5, 6, 7, 8, 9
  item 0
}

The `@status` property

Queries the [=module buffer/status=] of a [=module buffer=]. The [=rule engine=] sets the status of a [=module buffer=] with the outcome of the [=rule=]'s execution. Most operations are asynchronous, except [=@do clear=], [=@do update=] and [=@do queue=].

The `@tag` property

This property provides a means for rule conditions to test a module buffer for the result from a preceding action. Use @tag in the action to pass an identifier to the subsequent asynchronous response where it can be accessed via @tag in a rule condition.

The `@to` property

Companion [=action=] property used in [=@do properties=], [=@for=], [=@pop=], [=@push=], [=@shift=], [=@unshift=] operations.

Meaning and value constraints depend on the operation. See individual operations for details. For instance, when used in a [=@for=] operation, the property specifies the zero-based ending index of the iteration. Value must be an integer. When used in a [=@do properties=] operation, the property specifies the name of the [=module buffer=] onto which to write the current [=chunk=].

The `@type` property

[=Matches=] a [=chunk=]'s [=type=], or binds a variable to the [=chunk=]'s [=type=].

The `@unmap` property

This MUST reference a chunk of type [=@map=] that defines a map for property names and their meanings, performing the inverse of the mapping specified by the [=@map=] property.

The `@unshift` property

An [=action=] property that pushes an [=atomic value=] to the beginning of the [=value=] of the property identified by a companion [=@to=] property. If the targeted property does not exist yet, it is created.

In the absence of a [=@to=] property, this operation has no effect.

Given the following [=chunk=] and [=action=]:

digits { list 1, 2, 3, 4, 5, 6, 7, 8 }
digits { @shift 0, @to list }

The [=action=] will update the [=chunk=] to:

digits { list 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }

The `@uncompile` property

This used in a rule action to copy a set of rules in procedural memory to a set of chunks in declarative memory into a set of rules in procedural memory. The process starts with the chunk that cites the chunks used for the conditions and actions, and then applies to those chunks. Note that @uncompile may cite a list of IDs for chunks to be uncompiled.

get {@uncompile rule1; @map map1}

The above [=action=] looks for a rule chunk with ID rule1 in the rule module and copies the associated chunks to the default module using the mappings specified in the chunk with ID map1 as specified with [=@map=]. The chunk type and ID are copied as is.

Is there a need for a means to map chunk IDs for use with [=@compile=] and [=@uncompile=]? A potential solution would be to introduce @map-id by analogy to [=@map=].

Modules

A module is a [=graph of chunks=] associated with one and only one [=module buffer=]. A [=module=] has a module name that follows the [=name=] data type, and that is typically used to target the [=module=] in [=@module=] properties.

A [=module=] supports [=built-in operations=], and may support additional operations defined by the application when the [=module=] is initialized.

A [=module=] represents a cognitive database on which the [=rule engine=] may operate. It may be viewed as a region in the cerebral cortex, where the [=module buffer=] corresponds to the bundle of nerve fibres connecting to that region.

The [=rule engine=] automatically creates a module named goal, which will therefore always exist in a rule execution context.

The [=@module=] property allows [=conditions=] and [=actions=] to reference the [=module name=] of the [=module=] they relate to. In the absence of an [=@module=] property, [=conditions=] and [=actions=] apply to the goal module.

Module buffers

A module buffer is a container for at most one [=chunk=]. The mammalian brain is richly connected locally, and weakly remotely. A [=module buffer=] mimics the constrained communication capacity of the mammalian brains for such long range communication.

The [=rule engine=] operates on a module's [=graph of chunks=] through its [=module buffer=].

A [=module buffer=] has a status, (accessible via [=@status=]), whose value is initially [=status/okay=], and which reflects the outcome of the last [=action=] held and performed by the [=module buffer=]. Values can be:

pending: The operation is still pending.
okay: The operation completed successfully.; Switch to ok? This seems more common in technologies (e.g. HTTP) than okay.
forbidden: The operation was not allowed.
nomatch: The operation [=failed=] because there was no [=matching chunk=] for the [=action=] in the targeted [=module=].
failed: The operation failed.

This is analogous to the hypertext transfer protocol (HTTP) and allows rule engines to work with remote cognitive databases. To relate particular request and response pairs, use [=@tag=] in the action to pass an identifier to the subsequent asynchronous response where it can be accessed via [=@tag=] in a rule condition.

A [=module buffer=] has a queue, which is a set of [=chunks=], initially empty. Each chunk in the [=queue=] has a priority, represented by an integer from 1 to 10, with 10 the highest priority. The default [=priority=] is 5. [=Chunks=] are ordered by descending [=priority=] in a [=queue=]. When [=priorities=] match, [=chunks=] are ordered by insertion order (first in, first out).

The [=@priority=] property lets [=actions=] set the [=priority=] of a [=chunk=] when they add it to a [=queue=].

A [=module buffer=] is automatically cleared when the [=actions=] associated with the [=rule=] it contained did not update the contents of targeted [=module buffers=]. This pops the [=queue=] if it is not already empty.

Built-in operations

The [=@do=] property lets an [=action=] specify the graph algorithm or operation to execute. The default operation is to update the [=module buffer=], similar to calling [=@do update=].

All [=modules=] support the built-in operations defined in this section.

All [=modules=] also support the [=@for=] property to iterate over a set of items in a comma separated list. This has the effect of loading the [=module buffer=] with the first item in the list. The index range can optionally be specified with [=@from=] and [=@to=], where the first item in the list has index 0.

The `@do clear` operation

Clears the [=module buffer=] and pops the [=queue=].

The `@do delete` operation

Removes [=matching chunks=] from the [=graph of chunks=].

The `@do get` operation

Looks for a [=matching chunk=] in the module's [=graph of chunks=] and puts a copy of it in the [=module buffer=] if found. Modifying the [=properties=] of a [=chunk=] copied from a [=graph of chunks=] (e.g. through a [=@do update=] operation) will not alter the underlying [=graph of chunks=]. To save an updated [=chunk=], a [=@do put=] or [=@do patch=] command needs to be issued.

The `@do next` operation

Loads the next [=matching chunk=] to the targeted [=module buffer=] in an implementation dependent order.

The `@do patch` operation

If the [=chunk=] in the targeted [=module buffer=] has the same [=identifier=] as a [=chunk=] in the underlying [=graph of chunks=], patches the [=chunk=] in the [=graph of chunks=] with the [=properties=] that appear in the [=module buffer=], excluding [=properties=] prefixed with an @ character.

What is the expected behavior when the action has an @id property? It would seem reasonable for the action to synchronously update the [=identifier=] for the chunk in the module buffer prior to applying that chunk to patch the module's [=graph of chunks=].

The `@do properties` operation

Initiates an iteration over the [=properties=] of the [=matching chunk=] that do not begin with @. Each [=property=] is mapped to a new [=chunk=] with the same [=type=] as the [=action=]. The action's properties are copied over, and name and value properties are used to pass the [=property=] name and value respectively. The [=@more=] property is given the value true unless this is the final [=chunk=] in the iteration, in which case [=@more=] is given the value false. By default, the iteration is written to the same [=module buffer=] as designated by the [=action=] that initiated it. However, you can designate a different [=module buffer=] with the [=@to=] property. By setting additional properties in the initiating action, you can ensure that the rules used to process the property name and value are distinct from other such iterations.

The following example first sets the facts [=module buffer=] to a [=chunk=] of [=type=] foo, and then initiates an iteration over all of the [=chunk=]'s properties:

run {}
  =>
    foo {@module facts; a 1; c 2}, # set facts buffer to foo {a 1; c 2}
    bar {@module facts; @do properties; loop prop18; @to goal} # launch iteration

# this rule is invoked with the name and value for each property
# note that 'loop prop18' is copied over from the initiating chunk
# (also note that "@do log" is an hypothetical operation to log a message)
bar {loop prop18; name ?name; value ?value}
  =>
    console {@do log; message ?name, is, ?value},
    bar {@do next}  # to load the next instance from the iteration

The `@do put` operation

Saves the contents of the [=module buffer=] as a [=chunk=] to the module's [=graph of chunks=]. If the [=action=] has an [=@id=] property, this operation will overwrite the [=chunk=] with the same [=identifier=] or will create a new [=chunk=] with the given [=identifier=] if it does not exist already. This operation will also create a new [=chunk=] in the absence of an [=@id=] property.

If a chunk was loaded with @do get, then updated with @do update, would a call to @do patch create a new chunk if @id is not set? Or would it rather update the chunk in the graph?

The `@do queue` operation

Pushes a [=chunk=] to the [=queue=] for the [=module buffer=]. If a [=@priority=] property is set to an integer value between 1 and 10, the [=priority=] of the [=chunk=] in the [=queue=] is set to that value.

The `@do update` operation

Directly updates the [=module buffer=] if the chunk [=type=] for the [=action=] is the same as the [=chunk=] currently held in the [=module buffer=]. The operation updates the properties given in the [=action=], leaving aside properties prefixed with an @ character, and leaving other existing properties unchanged. If the chunk [=type=] for the action is not the same as the [=chunk=] currently held in the [=module buffer=], a new [=chunk=] is created with the properties given in the [=action=], excluding properties prefixed with an @ character. This is the default action when an [=action=] has neither an [=@do=] property nor an [=@for=] property.

How can one update the properties prefixed with an @ character in a [=chunk=] such as [=@context=], [=@subject=] or [=@object=]? A potential solution is to support the [=@map=] property as already supported for [=@compile=] and [=@uncompile=], along with an [=@unmap=] property. This would involve an asynchronous operation.

Name operators

Operators defined in this section may be used on their own as [=names=] or in front of [=names=] to alter their meaning.

The variable operator `?`

The variable operator ? may be prepended to a [=name=] when used as a [=property=] value to turn the [=name=] into a variable which represents a symbolic name to a [=value=]. A [=variable=] gets bound to a [=value=] in a [=condition=]. The [=value=] can then be referenced in [=actions=] using the [=variable=]'s name. Effectively, [=variables=] allow applications to copy information from rule [=conditions=] to rule [=actions=].

[=Variables=] are scoped to the [=rule=] where they appear.

count { state start; from ?num1; to ?num2 }
=> increment { @module facts; @do get; number ?num1 }

The above [=rule=] defines a [=condition=] that [=matches=] a [=chunk=] in the goal [=module buffer=] whose [=type=] is count, that has a state [=property=] whose value is start, and that has from and to [=properties=]. The [=condition=] binds the value of the [=variable=] ?num1 to the [=value=] of the from [=property=] in the matching chunk, and the value of the [=variable=] ?num2 to the [=value=] of the to [=property=].

The [=rule=] defines an [=action=] that looks for a [=chunk=] in the facts [=module=] whose [=type=] is increment and that has a [=property=] named number and whose [=value=] equals the value of the ?num1 [=variable=].

[=Variables=] are [=bound=] to a [=value=] the first time they appear in a [=condition=]. Subsequent occurrences of the same [=variable=] in a [=condition=] reference their [=value=].

count { state start; from ?num1; to ?num1 }
=> console { @do log; message ?num1 }

The above [=rule=] defines a [=condition=] that [=matches=] a [=chunk=] in the goal [=module buffer=] whose [=type=] is count, that has a state [=property=] whose value is start, and that has from and to [=properties=] that have identical values. The [=condition=] binds the value of the [=variable=] ?num1 to the [=value=] of the from [=property=] in the matching chunk.

[=Variables=] may represent any type of [=value=]. In particular, a [=variable=] that [=matches=] a property whose value is a list of [=atomic values=] gets bound to the list of [=atomic values=].

basket { fruit ?f }
=> console { @do log; message ?f }

The above [=rule=] defines a [=condition=] that [=matches=] a [=chunk=] in the goal [=module buffer=] whose [=type=] is basket and that has a fruit [=property=]. Given the following [=chunk=] in the goal [=module buffer=], the [=condition=] binds variable ?f to apple, banana, orange:

basket { fruit apple, banana, orange }

A [=condition=] that contains a [=property=] with a list of [=variables=] [=matches=] a list of [=atomic values=] that has the same length. The [=condition=] does not [=match=] when the lengths of the lists differ.

basket { fruit ?a, ?b, ?o }
=> console { @do log; message ?a, ?b, ?o }

The above [=rule=] defines a [=condition=] that [=matches=] a [=chunk=] in the goal [=module buffer=] whose [=type=] is basket and that has a fruit [=property=] whose value is a list of three atomic values. Given the following [=chunk=] in the goal [=module buffer=], the [=condition=] binds variable ?a to apple, ?b to banana, and ?o to orange:

basket { fruit apple, banana, orange }

The wild card operator `*`

The wild card operator * may be used on its own in lieu of a [=name=] in one of the following cases:

As the [=type=] of a [=condition=] or [=action=] to denote that [=condition=] or [=action=] matches a [=chunk=] regardless of its [=type=].
```
* {} => ...
```
The * {} [=condition=] [=matches=] a [=chunk=] regardless of its [=type=] and [=properties=].
In a [=condition=] as the [=value=] of a [=property=] |p| to have the [=condition=] [=match=] a [=chunk=] that has a [=property=] whose [=name=] equals |p|'s [=name=], regardless of its [=value=].
```
basket { fruit * } => ...
```
The [=condition=] [=matches=] a [=chunk=] whose [=type=] is basket and which has a fruit [=property=] .
A [=variable=] may also be used to [=match=] on any [=value=]. The [=wild card operator=] avoids the need to provide a name for the [=variable=] when the actual [=value=] does not need to be captured.
In a [=condition=] as an [=atomic value=] in a list to [=match=] any [=atomic value=] at the same position in a [=chunk=].
```
basket { fruit apple, *, * } => ...
```
The [=condition=] [=matches=] a [=chunk=] whose [=type=] is basket and which has a fruit [=property=] whose [=value=] is a list of three [=atomic values=] starting with apple.

The negation operator `!`

The negation operator ! may be prepended to [=names=] to negate the outcome of their evaluation. The [=negation operator=] may be used in one of the following cases:

In a [=rule=] in front of a [=condition=] to negate it. A rule with a negated [=condition=] !|cond| applies if and only if |cond| does not hold true.
```
# Rule with a negated condition
rule {
@condition !c1
@action a1
}
person c1 { @id John }
console a1 { @do log; message "Type is not person or id is not John" }

# Same rule defined using the compact format
!person { @id John }
=> console { @do log; message "Type is not person or id is not John" }
```
The above example illustrates two equivalent ways to define a rule with a negated condition. In this example, the condition |c1| [=matches=] a [=chunk=] whose [=type=] is person and whose [=identifier=] is John. As such, the negated condition [=matches=] a [=chunk=] whose [=type=] is not person or whose [=identifier=] is not John.
In a [=condition=] in front of a [=property=] value to negate the result of a [=match=]. A negated [=property=] value !|val1| [=equals=] another [=property=] value |val2| if and only if |val1| does not [=equal=] |val2|.
```
person { @id !John }
=> console { @do log; message "Type is person but id is not John" }
```
The above [=condition=] [=matches=] a [=chunk=] whose [=type=] is person and whose [=identifier=] is not John.
```
basket { fruit ?a, !banana, ?o }
=> console { @do log; message "No banana in second position" }
```
The above [=condition=] [=matches=] a [=chunk=] whose [=type=] is basket and which has a fruit [=property=] whose [=value=] is a list of three [=atomic values=]. First and third [=atomic values=] in that list can be anything. Second [=atomic value=] must not be banana.
On its own as a [=property=] value in a [=condition=] to test that a [=property=] is undefined. A [=condition=] with a [=property=] |p| whose value is ! [=matches=] a [=chunk=] if and only if the [=chunk=] does not have a [=property=] whose [=name=] is |p|'s [=name=].
```
basket { fruit ! }
=> console { @do log; message "Basket without fruits" }
```
The above [=condition=] [=matches=] a [=chunk=] whose [=type=] is basket and which does not have a fruit [=property=].

On its own as a [=property=] value in a [=@do patch=], [=@do update=] or similar [=action=] that updates a [=chunk=] to unset a [=property=].

# Given the following chunk in the module buffer
basket { fruit apple, banana, orange }

# ... the following rule drops the fruit property
* {} => basket { @do update; fruit ! }

# Resulting chunk
basket {}

The [=negation operator=] cannot be prepended to a [=variable=] that has not yet been [=bound=]. Similarly, the [=negation operator=] cannot be used on its own as an [=atomic value=] in a list. More generally, the [=negation operator=] cannot be used elsewhere than in the cases detailed above.

# Invalid: variable ?num1 is unbound
count { state counting; start !?num1 } => ...

# Invalid: on its own in a list
basket { fruit ?a, !, ?o } => ...

# Invalid: in an update action but not on its own
* {} => basket { @do update; fruit !apple }

A second [=negation operator=] prepended to a [=name=] that starts with a [=negation operator=] cancels the effect of the first [=negation operator=].

# The following condition
person { @id !!John }

# ... is the same as this one:
person { @id John }

The reserved name operator `@`

The reserved name operator @ may be prepended to a [=name=] to denote a reserved name with specific meaning. Most [=reserved names=] are to be used as [=property=] names, typically in [=conditions=] and [=actions=] to control their behavior (see [[[#properties-for-conditions-and-actions]]]). Some of them may be used as chunk [=types=] to denote a chunk with specific meaning (see [[[#mapping-to-rdf]]]).

Mapping to RDF

Linked Data [[LINKED-DATA]], at the basis of RDF [[RDF11-CONCEPTS]], is a way to create a network of standards-based machine interpretable data across different documents and Web sites. It allows an application to start at one piece of Linked Data, and follow embedded links to other pieces of Linked Data that are hosted on different sites across the Web.

[=Names=] used in [=chunks=] are local to the [=graph of chunks=] in which they appear. For [=names=] to be usable as linked data, there needs to be a way to associate them to global identifiers. [=Reserved names=] defined in this section may be used to create such a mapping.

In turn, this mechanism can be used to map a [=graph of chunks=] to an RDF graph and vice versa.

Algorithms to serialize/deserialize a [=graph of chunks=] to an RDF graph and vice versa are out of scope of this document but may be specified in future revisions of it.

Given the following [=graph of chunks=]:

@rdfmap {
  dog http://example.com/ns/dog
  cat http://example.com/ns/cat
  age http://example.com/ns/age
  name http://example.com/ns/name
}

dog { name "Youki"; age 5 }
cat { name "Isidore"; age 3 }

The [=@rdfmap=] [=chunk=] creates a mapping between local names and a URL. This [=graph of chunks=] is equivalent to the following RDF graph expressed in Turtle [[TURTLE]]:

<http://example.org/ns/dog>
  <http://example.org/ns/name> "Youki";
  <http://example.org/ns/age> 5.

<http://example.org/ns/cat>
  <http://example.org/ns/name> "Isidore";
  <http://example.org/ns/age> 3.

The `@rdfmap` type

The [=@rdfmap=] chunk [=type=] identifies a chunk that defines a mapping between [=names=] and IRIs [[IRI]]. Each [=property=] it defines whose [=name=] does not start with one of the name operators (see [[[#name-operators]]]) creates a mapping between this [=name=] and the property [=value=], interpreted as an IRI.

# Maps the name "thing" to the "Thing" item type in schema.org
@rdfmap {
  thing http://schema.org/Thing
}

The [=@rdfmap=] keyword plays the same role in [=chunks=] as the @context keyword in JSON-LD. See the notion of Context in JSON-LD for details [[JSON-LD]]. The term [=context=] and the [=@context=] keyword have a different meaning in [=chunks=] where they identify the specific situation under which a [=chunk=] should be considered to be true. A distinct [=@rdfmap=] keyword is used here to avoid any confusion.

If multiple [=@rdfmap=] chunks create a mapping for the same [=name=], the last definition in overrides previous ones.

# Creates a mapping from image to the example.org namespace
@rdfmap { image http://example.org/ns/image }

# "image" gets mapped to http://schema.org/image
# due to the second mapping definition below that
# overrides the initial mapping defined above.
thing { image img1 }

# New mapping definition for image, overrides former one
@rdfmap { image http://schema.org/image }

An [=@rdfmap=] chunk may also contain a [=@base=] property to create a default IRI namespace for [=names=] and [=@prefix=] properties to define prefixes for compact IRIs.

The `@base` property

The [=@base=] [=property=] defines a default IRI namespace for [=names=] that are not explicitly declared in an [=@rdfmap=].

@rdfmap {
  @base http://schema.org/
  dog http://example.org/ns/dog
}

dog { name "Youki"; birthDate 2021-07-09 }

In this example, the [=@rdfmap=] chunk maps:

dog to http://example.org/ns/dog
name to http://schema.org/name
birthDate to http://schema.org/birthDate

There can be only one default IRI namespace for a given [=graph of chunks=]. If [=@base=] is used in multiple [=@rdfmap=] chunks, the last definition overrides previous ones.

# Sets example.org as default namespace
@rdfmap {
  @base http://example.org/ns/
}

# Names actually get mapped to schema.org namespace
# due to override below
Thing { name "Desktop" }

# Re-defines default namespace to use schema.org
@rdfmap {
  @base http://schema.org/
}

The `@prefix` property

The [=@prefix=] [=property=] can be used in an [=@rdfmap=] chunk to reference a [=chunk=] that defines IRI prefixes, which in turn allow the use of compact IRIs in the [=@rdfmap=] chunk.

The actual [=chunk=] that defines prefixes can have any [=type=]. Each [=property=] it defines whose [=name=] does not start with one of the name operators (see [[[#name-operators]]]) creates a prefix between the property [=name=] and the property [=value=], interpreted as an IRI.

prefix p1 {
  dcterms http://purl.org/dc/terms/
  foaf http://xmlns.com/foaf/0.1/
}

@rdfmap {
  @prefix p1
  title dcterms:title
  topic foaf:topic
}

book {
  title "Chunks of life"
  topic "Mammalian rules"
}

The [=@rdfmap=] chunk in this example maps:

title to the compact IRI dcterms:title, which gets expanded to http://purl.org/dc/terms/title through the [=@prefix=] property
topic to the compact IRI foaf:topic, which gets expanded to http://xmlns.com/foaf/0.1/topic through the [=@prefix=] property

As with [=@base=], in case of conflicts, the definition that gets referenced last overrides former definitions.

prefix last { foaf http://xmlns.com/foaf/0.1/ }
prefix first { foaf http://example.org/ns/ }

@rdfmap { @prefix first; nick foaf:nick }
@rdfmap { @prefix last }

The last [=@rdfmap=] definition makes the foaf prefix map to http://xmlns.com/foaf/0.1/, overriding the previous mapping to http://example.org/ns/. The nick [=name=] gets mapped to http://xmlns.com/foaf/0.1/nick as a consequence.

Scripting API

This section describes the scripting API exposed by the original JavaScript library for chunks and rules, see [[CHUNKS-DEMOS]]. The starting point is to create a graph from a text string containing the source of the chunks that make up the graph. The following code creates two graphs: one for facts from "facts.chk", and another for rules from "rules.chk".

	let facts, rules;
	fetch("facts.chk")
	.then((response) => response.text())
	.then(function (source) {
		facts = new ChunkGraph(source);
		fetch("rules.chk")
		.then((response) => response.text())
		.then(function (source) {
			rules = new ChunkGraph(source);
		});
	});

Here are some operations you perform on a graph:

new ChunkGraph(source): Create a new graph from a text string containing the chunks and links.
graph.chunks[id]: Find a chunk given its id.
graph.types[type]: Find the list of chunks with a given type.
graph.forall(kind, handler, context): Apply a function to all chunks whose type has the kindof relationship to the given kind. This applies recursively to chains of kindof relationships. The handler is a function that is passed the chunk and the context.
graph.get(type, values): Recall a chunk with a given type, and matching values as denoted by a JavaScript object with a set of named properties. Note that this is stochastic and returns the 'best' chunk when there are multiple matches.

graph.put(type, values, id)

Remember (i.e. create and store) a chunk with a given type, and matching values as denoted by a JavaScript object with a set of named properties. The chunk id will be assigned automatically if not supplied.

graph.delete(type, values, id)

Remove the chunk with a given ID if provided, otherwise forget the set of chunks with the given type and matching values.

graph.parse(source)

Parse source as chunks and add to this graph.

graph.add(chunk)

Adds a chunk or link to the graph, see below for ways to create chunks and links. If the chunk is currently part of another graph, it will be removed from that graph before being added to this one.

graph.remove(chunk)

Remove a chunk or link from the graph.

Here are some operations you perform on a chunk:

new Chunk(type, id): Create a new chunk for a given type and id. The id is optional and will be assigned automatically when the chunk is added to a graph if not supplied.
new Link(subject, predicate, object): Create a new Link as a subclass of chunk where the chunk type is given by the predicate. The chunk id will be assigned automatically when the Link is added to a graph.
chunk.id: Access the chunk's id.
chunk.type: Access the chunk's type.
chunk.properties[name]: Access a chunk property value given the property's name.
chunk.setValue(name, value): Overwrite the value of a named property
chunk.addValue(name, value): Add a value for named property. An array is used only if the property value has multiple values.
chunk.removeValue(name): Remove a value from the named property - this is the inverse of addValue.
chunk.hasValue(name, value): Returns true or false according to whether the named property contains the given value, i.e. the property is either that value or it is a list, one of whose items is that value. If the property is undefined for this chunk, then the return value is false.
chunk.toString(): Returns a pretty printed version of the chunk.

The following describes the API for rule engines:

new RuleEngine()

Create a new rule engine.

engine.addModule(name, graph[, backend])

Registers a new local module with its name, graph and an optional backend for graph algorithms.

The backend is declared as an object whose property values are functions that implement the algorithm identified by the property's name. The algorithm's name can then used with @do in rule actions for this module. The action is passed a single argument that is an object whose property values are the bindings for the variables identified by the object's property names.

The backend functions can be used to override the default actions for recall, remember and update. Note that "rules" and "goals" are required modules. The rules module is used to hold procedural knowledge as a set of rules. By default, the "goals" module is initialised to an empty graph. A separate method is envisaged for adding remote modules.

engine.getModule(name)

Return the module created by calling engine.addModule.

engine.start(rules, facts[, initial_goal])

A convenience function to set the rules and facts modules, along with an optional initial chunk, that is provided as a chunk, i.e. as source text. Note: rules is a graph containing the rules that define procedural knowledge, and facts is a graph containing a set of chunks that define declarative knowledge. The goal is not used until you call engine.next().

engine.next()

Find and execute the next matching rule.

engine.setGoal(source)

Parse the source for a chunk and load it into the goal module's buffer.

engine.setBuffer(name, source)

Parse the source for a chunk and add it to the named module's graph, then load it into the module's buffer.

engine.setBuffer(name, chunk)

Load the chunk into the named module's buffer.

engine.getBuffer(name)

Return the chunk in the named module's buffer.

engine.addListener(listener)

Register a listener function that will be called when any of the module buffers are updated. The listener is passed a single argument identifying the module by name.

Introduction

Conformance classes

Data types

Chunks and graphs

Chunk type

Chunk identifier

Chunk properties

Chunk context

Links between chunks

Graph of chunks

Rules and modules

Rules

Conditions

Actions

Matching chunks

@-properties for conditions and actions

The @compile property

The @context property

The @do property

The @for property

The @from property

The @id property

The @index property

The @kindof property

The @map property and chunk type

The @module property

The @more property

The @pop property

The @priority property

The @push property

The @shift property

The @status property

The @tag property

The @to property

The @type property

The @unmap property

The @unshift property

The @uncompile property

Modules

Module buffers

Built-in operations

The @do clear operation

The @do delete operation

The @do get operation

The @do next operation

The @do patch operation

The @do properties operation

The @do put operation

The @do queue operation

The @do update operation

Name operators

The variable operator ?

The wild card operator *

The negation operator !

The reserved name operator @

Rule engine execution

Chunks documents

Parsing a chunks document

Chunks grammar

Railroad diagrams

Mapping to RDF

The @rdfmap type

The @base property

The @prefix property

Data Models

Validation and Richer Queries

Mimicking Human Memory

Scripting API

The `@compile` property

The `@context` property

The `@do` property

The `@for` property

The `@from` property

The `@id` property

The `@index` property

The `@kindof` property

The `@map` property and chunk type

The `@module` property

The `@more` property

The `@pop` property

The `@priority` property

The `@push` property

The `@shift` property

The `@status` property

The `@tag` property

The `@to` property

The `@type` property

The `@unmap` property

The `@unshift` property

The `@uncompile` property

The `@do clear` operation

The `@do delete` operation

The `@do get` operation

The `@do next` operation

The `@do patch` operation

The `@do properties` operation

The `@do put` operation

The `@do queue` operation

The `@do update` operation

The variable operator `?`

The wild card operator `*`

The negation operator `!`

The reserved name operator `@`

The `@rdfmap` type

The `@base` property

The `@prefix` property