Assertions
An assertion is a key piece of configuration within CogTL, as it is the main way of implementing business logic and discover possible scenarios.
Like most CogTL configuration elements, an assertion is identified by its name and can have an informative description.
Basically, an assertion is composed of three parts:
- A set of criteria to identify subjects, which are elements (entities or relations) that can be found in the knowledge graph.
- An optional condition to refine the subjects that must be considerated.
- A set of consequences, which are actions that must be taken whenever a set of subjects matching the condition are found.
Optionally also, a set of adapter pipelines can be defined to adapt the data belonging to the subjects and use them in consequences.
The execution of an assertion can be automatic, or scheduled, depending if you select Evaluate automatically on pertinent model changes.
Subjects
A subject is a set of criteria that define specific entities or relations in the knowledge graph. They are identified by a variable name, and can be of one of the following types:
- A simple entity identified by a set of criteria (combined in a AND expression):
| Criterion | Description |
|---|---|
| Whose type is... | A specific entity type or one of its descendents |
| With a data of type... | A specified data type is defined (has a value) |
| With a data value... | A data value is equal to, greater or less than, or contains a specific value, or the result of an expression. The specific data type is optional, meaning that it could search for a value in any data type also. |
| With a tag... | The entity is flagged with a specific tag (or NOT flagged with this tag, if you check negative) |
| Whose probability is... | Higher or lower than a specific probability |
- A simple relation identified by a set of criteria (combined in a AND expression):
| Criterion | Description |
|---|---|
| Whose type is... | A specific relation type or one of its descendents |
| With a tag... | The relation is flagged with a specific tag |
| Whose probability is... | Higher or lower than a specific probability |
- A navigation, starting from a previous subject.
Subjects are ordered and can refer to previous ones, meaning that a navigation or prepared query subject can refer to a subject defined before as starting points. This is also true for entity subjects, who can refer to values of previous subjects in an expression. Matching assertions make use of this, and CogTL is specifically optimized for that kind of assertions. See the example below.
Aggregators
When using more than one subject, you can add aggregators to aggregate the entities found by one subject relatively to others. Those aggregators allow to count entities, or compute the sum, maximum value or average value of a datatype.
You can then refer to those aggregators in expressions, with the function aggregator(name). Note that aggregators are applied after the condition, therefore you cannot use aggregators in the condition. But you can use them on every action where expressions are used, like Set entity data, or Create an entity.
Condition
The condition is optional. If set, the condition will be applied to every combination of subjects found, and if the resulting probability is below the defined threshold OR if the condition cannot be evaluated (because the set of subjects don't contain the necessary data values), the set of subjects is discarded.
More informations about conditions can be found here.
Consequences
Consequences describe what CogTL has to do with all set of subjects identified, that match the optional condition if defined. Consequences can modify/alter the knowledge graph, flag elements with a tag, add some values to an entity, store possible scenarios or invoke optional external modules.
The following actions are available:
- Create an entity : Create a new entity of any type, with entities data that you can fill using the subjects data values.
- Set an entity data : Add or modify the data of one of the subjects.
- Delete an entity : Delete an entity (one of the subjects), independently from its knowledge sources.
- Delete a rleation : Delete a relation between two subjects, independently from its knowledge sources.
- Create a relation : Create a relation of any type between two subjects identified.
- Tag an object : Flag one of the subjects (being an entity or a relation) with a specific tag.
- Tag a path : Flag all the path (i.e. all the relations) between two subjects (if any), with a specific tag.
- Instantiate a template : Create a whole subgraph, that can be linked with the subjects by using "Variable" entities.
- Invoke a module : Invoke a CogTL module on any agent, with parameters that can include the subjects data values. The output of the module can be then transformed as a template that will be merged with the knowledge graph.
- Store a possible scenario is the key action that will be used to modelize the possibilities of any scenario that may happen. The scenario will be attached to the subjects identified by mapping the actors of the scenario to subjects of the assertion, and for every actor, you can specify the impact on all factors, with an expression that can take into account any subject data value.
For every action, you can optionally write a last conditional (expression)[expression.md] that will be evaluated just before the action is executed. It may allow you to modulate the actions executed for the same set of subjects, depending on the situation.
Examples
Matching assertions
Matching assertions are a specific, optimized kind of assertion, that aims at creating relations between objects that are not originally connected by knowledge sources. Imagine that you have a list of Actor of interest coming from a source, and another source is bound to a news feed, and issues Article. A matching assertion could be written to detect the occurrence of any Actor name within the summary of every Article.
Such a matching assertion would be written as follows:
Subject A : Type Entity, whose type is Actor.
Subject B : Type Entity, with a data value defined as an expression A.name and the checkbox Exact not set.
Consequence : Create a relation between B and A, of type mentions.