Knowledge Base¶

Semantic Tree¶

To begin with, you should build a semantic tree that contains all the types you need. From stepDP there is only the predefined type Object, from which all derive. In the following example, there is first a general type UserIntent, which is extended by a more specific type GreetingIntent. Similarly, the Bottle type is specified more precisely by two types.

Lifecycle

In code, this Semantic Tree would look like this:

Type UserIntent = new Type("UserIntent", this.getKB());
this.getKB().addType(UserIntent);

Type GreetingIntent = new Type("GreetingIntent", this.getKB());
GreetingIntent.addInheritance(UserIntent);
this.getKB().addType(GreetingIntent);

Type Bottle = new Type("Bottle", this.getKB());
Bottle.addProperty(new PropString("material", this.getKB()));
this.getKB().addType(Bottle);

Type GlasBottle = new Type("GlasBottle", this.getKB());
GlasBottle.addInheritance(Bottle);
this.getKB().addType(GlasBottle);

Type PlasticBottle = new Type("PlasticBottle", this.getKB());
PlasticBottle.addInheritance(Bottle);
this.getKB().addType(PlasticBottle);

Instances¶

As soon as the semantic tree with its types has been defined, these types can be mapped into concrete instances. These instances are permanently stored in the knowledge base (unlike the tokens on the Blackboard, which are archived after a certain time and later deleted).

Instance

In code, this instance would look like this:

IKBObjectWriteable Bottle42 = this.getKB().createInstance("Bottle42", GlasBottle);
Bottle42.setString("material", "glas");
Bottle42.setInteger("size", 500);
Bottle42.setString("color", "green");
Bottle42.setString("mfn", "Mfn1");
Bottle42.setString("location", "Storage3");

How to add KB instances to the blackboard¶

In many applications, it is useful to add knowledge base instances to the blackboard, such that they can be processed by the rules and conditions. As an example, let's imagine a user pointing to an object, e.g. a TV. An external sensor that recognizes the pointing gesture and identifies the target object could then add the corresponding knowledge base instance to the blackboard, such that it can, for example, be fused with a speech input like "How much does this cost?". There are two options to add a knowledge base instance to the blackboard:

Add KB Instance directly as token
You can use the API endpoint /blackboard/addKBToken to add a KB instance as a token to the blackboard by providing its UUID or name in the following format:
```
{
  "uuid": "7d5a8c64-aec2-451b-87a4-5e833e8540f2"
}
```
```
{
  "name": "tv1"
}
```
Add a token with a KB reference
The KB instance can also be only a part of a token that contains additional information, as shown below. It is again referenced by its UUID or name. In this case, you can simply add the token via the standard endpoint /blackboard/addToken.
```
{
  "type": "OrderIntent",
  "product": "7d5a8c64-aec2-451b-87a4-5e833e8540f2",
  "paymentMethod": "credit card"
}
```
```
{
  "type": "OrderIntent",
  "product": "tv1",
  "paymentMethod": "credit card"
}
```

In both cases, the references to the KB instance will be resolved automatically, so that the tokens can be used in the same way as tokens without KB instances.

Reference by UUID vs. reference by name

In general, it is preferable to reference a knowledge base instance by its UUID since it uniquely identifies the object. In some cases, the reference by name might be more convenient, but be aware that the knowledge base does not enforce name uniqueness, so you have to ensure yourself that each name is only associated with one knowledge base instance. You can get a mapping from UUID to name from the stepDP API.

Dialog Example¶

A code example of a dialog system using knowledge base objects can be found in the repository StepDP-Basic-Examples under the name KBExample.