query facts from the knowledge base#

This section describes how to add/remove/query the robot’s knowledge base.

Note

You might want to check first 💡 Knowledge and reasoning to know more about your robot’s knowledge base.

You have two main options to access the knowledge base:

use the Python wrapper, that uses an idiomatic python syntax to add/remove/query facts. If you are programming with Python, we recommend this approach. See section Python API.
use the ROS interface directly: the knowledge base exposes standard topics and services to manipulate knowledge. See section ROS API.

Using the knowledge base from Python#

The Python wrapper makes it easy to update or query the knowledge base from a Python script or mission controller.

Our Python wrapper follows closely the API of the pykb library: pykb. pykb examples and documentation are largely applicable here as well.

If not already running, start the knowledge base:

ros2 launch knowledge_core knowledge_core.launch.py

Then, create a new Python script and import the Python wrapper as follows:

# first, create a ROS 2
import rclpy
from rclpy.node import Node

rclpy.init()
node = Node("test_kb_client")

# then import the knowledge base API and create a KB instance
from knowledge_core.api import KB
kb = KB(node)

You can then add/remove statements with kb += "s p o", kb += ["s1 p1 o1", "s2 p2 o2"], kb -="s p o", etc.

Then let’s assume that we want to add the following facts to the kb: “ari is-a Robot”, “tiago is-a Robot”, and “stockbot is-a Robot”.

We can do it as it follows:

kb += ["ari rdf:type Robot",
       "tiago rdf:type Robot",
       "stockbot rdf:type Robot"]

We can then query the knowledge base and to retrieve this information:

for known_robot in kb["?robot rdf:type Robot"]:
    print(known_robot)

If the facts have been correctly added, you should get ari, tiago, and stockbot as output.

Let’s now remove some facts from the knowledge base. Suppose we want to remove the following facts: tiago rdf:type Robot, and stockbot rdf:type Robot:

kb -= "tiago rdf:type Robot"
kb -= "stockbot rdf:type Robot"
# or equivalently
# kb -= ["tiago rdf:type Robot", "stockbot rdf:type Robot"]

for known_robot in kb["?robot rdf:type Robot"]:
    print(known_robot)

If the facts have been correctly removed, you should only get ari as output.

Refer to the Python API for more advanced examples, including subscribing to semantic events (i.e., get notifications when e.g. a specific fact becomes true).

Using the knowledge base with the ROS API#

First, start the knowledge base:

ros2 launch knowledge_core knowledge_core.launch.py

You should see the following output on your terminal:

KnowledgeCore
=============

Knowledge base started.

Available topics:
- /kb/add_fact [std_msgs/String]
- /kb/remove_fact [std_msgs/String]
- /kb/active_concepts [kb_msgs/ActiveConcepts]
- /kb/events/<id> [std_msgs/String] for each subscribed event

Available services:
- /kb/manage [kb_msgs/Manage]
- /kb/revise [kb_msgs/Revise]
- /kb/query [kb_msgs/Query]
- /kb/about [kb_msgs/About]
- /kb/label [kb_msgs/About]
- /kb/details [kb_msgs/About]
- /kb/lookup [kb_msgs/Lookup]
- /kb/sparql [kb_msgs/Sparql]
- /kb/events [kb_msgs/Event]

KnowledgeCore exposes two main topics, /kb/add_fact and /kb/remove_fact, to add/remove triples to the knowledge base. Both topics expect a simple string with 3 tokens separated by spaces (if the object is a literal string, use double quotes to escape it).

Note

The topic, /kb/events/<id>, is used for events: you can subscribe to specific ‘semantic’ events (eg, a given fact becomes true), and get notified.

See the KnowledgeCore API documentation for details.

It also exposes several services, including:

/kb/revise to add/remove facts using a synchronous interface
/kb/query to perform simple queries
/kb/manage to manage the knowledge base (including for instance the wipe-off of all the facts)

For more details about the API please refer to the ROS API.

We are now ready to see how we can add, remove and query the knowledge base.

To add facts to the knowledge base, we can do it using the topics or the services. For instance, suppose we want to add the following facts: [ari rdf:type Robot, tiago rdf:type Robot, stockbot rdf:type Robot].

import rclpy
from rclpy.node import Node
from std_msgs.msg import String
from kb_msgs.srv import Revise

rclpy.init()
node = Node("test_kb_client")

# add a fact by publishing to the /kb/add_fact topic
facts_pub = node.create_publisher(String, "/kb/add_fact", 1)
facts_pub.publish(String(data="ari rdf:type Robot"))

# or using the Revise service
revise = node.create_client(Revise, "/kb/revise")
revise.wait_for_service(timeout_sec=1.0)

future = revise.call_async(
        Revise.Request(
            statements=["tiago rdf:type Robot",
                        "stockbot rdf:type Robot"],
            method=Revise.Request.ADD
        ))

# wait for the service to complete
rclpy.spin_until_future_complete(node, future)

We can then query the knowledge base and check if we can retrieve this information.

import json
from kb_msgs.srv import Query

query = node.create_client(Query, "/kb/query")
query.wait_for_service(timeout_sec=1.0)

future = query.call_async(
        Query.Request(
            patterns=["?robot rdf:type Robot"],
            vars=[],
            models=[]
        ))


# wait for the service to complete
rclpy.spin_until_future_complete(node, future)

results = future.result()

print(json.loads(results.json))

If the facts have been correctly added, you should get the following output:

[{'robot': 'stockbot'}, {'robot': 'tiago'}, {'robot': 'ari'}]

Let’s now remove some facts from the knowledge base. Suppose we want to remove the following facts: [tiago rdf:type Robot, stockbot rdf:type Robot].

# either via topics...
facts_pub = node.create_publisher(String, "/kb/remove_fact", 1)
facts_pub.publish(String(data="tiago rdf:type Robot"))

# ...or with a service call
future = revise.call_async(
        Revise.Request(
            statements=["stockbot rdf:type Robot"],
            method=Revise.Request.DELETE
        ))

rclpy.spin_until_future_complete(node, future)

We can then query the knowledge base again:

future = query.call_async(
        Query.Request(
            patterns=["?robot rdf:type Robot"],
            vars=[],
            models=[]
        ))

rclpy.spin_until_future_complete(node, future)

results = future.result()
print(json.loads(results.json))

If the facts have been correctly removed, you should get the following output:

[{'robot': 'ari'}]

Next steps#

Check the KnowledgeCore API for more details about the KnowledgeCore capabilities;
Check the Tutorial: Getting started with the knowledge base for a tutorial involving reasoning.