Merge pull request #554 from TNO/restructure-faq

WIP: Improve documentation

docs/docs/get-started/_category_.json

@@ -1,8 +1,8 @@
 {
-  "label": "Tutorial",
+  "label": "Guides",
   "position": 6,
   "link": {
     "type": "generated-index",
-    "description": "In-depth details about how to use the various elements of the Knowledge Engine"
+    "description": "In-depth details about how to use the various elements of the Knowledge Engine."
   }
 }

docs/docs/get-started/knowledge-base.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 99
+---
+# Implementing a Knowledge Base
+This page describes how to implement your own Knowledge Base given a data source.
+
+There are three approaches to implement your own Knowledge Base:
+1. Java
+2. REST Developer API
+3. Knowledge Mapper (based on a Python client)
+4. JavaScript client
+
+The Knowledge Mapper is a tool we have built to easily connect to several common data sources (SQL, RDF, APIs).
+If you're interested in using the Knowledge Mapper or JavaScript client, please reach out to us as they are not yet open source.
+
+## Implementing your own Knowledge Interaction
+When you receive a request for data via an ANSWER or REACT Knowledge Interaction, you should return the expected results, e.g. by retrieving data from an API.
+
+If you do not have a response, then you should send an empty binding set.
+Also, when your REACT Knowledge Interaction has no result graph pattern, you should always return an empty binding set to the Knowledge Engine.
+
+If an error occurs while responding, you can either return an empty BindingSet (although this does not give any information about the error occurring) or call the (in case you are using the asynchronous handler methods of the Java Developer API) `future.completeExceptionally(...)` method.

docs/docs/get-started/knowledge-directory.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 4
+---
+# Starting a Knowledge Directory
+This page describes how to setup a Knowledge Directory.
+
+You can start the Knowledge Directory on ports 8080 with the available JAR:
+```bash
+cd knowledge-directory/target/
+
+java -Dorg.slf4j.simpleLogger.logFile=kd.log -cp "knowledge-directory-1.2.5.jar:dependency/*" eu.knowledge.engine.knowledgedirectory.Main 8080
+```
+You can of course run the Knowledge Directory on another port by replacing 8080 by your preferred port number.

docs/docs/get-started/knowledge-interactions.md

@@ -1,32 +1,82 @@
 ---
+sidebar_position: 7
 ---
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Knowledge Interactions
+# Using Knowledge Interactions
+This page describes how to register and execute Knowledge Interactions.
 
 ## How to instantiate a Knowledge Interaction?
+> You only need to register your Knowledge Interactions once. 
+> They are, however, dynamic and can be added and removed if needed.
+
 <Tabs groupId="tke-usage">
 <TabItem value="java" label="Java">
 
 ```java
 // ASK:
-AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(graphPattern);
+AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(communicativeAct, graphPattern);
 smartConnector.register(askInteraction);
 
 // ANSWER:
-AnswerKnowledgeInteraction answerInteraction = new AnswerKnowledgeInteraction(graphPattern);
+AnswerKnowledgeInteraction answerInteraction = new AnswerKnowledgeInteraction(communicativeAct, graphPattern);
 smartConnector.register(answerInteraction);
 
 // POST:
-PostKnowledgeInteraction postInteraction = new PostKnowledgeInteraction(graphPattern);
+PostKnowledgeInteraction postInteraction = new PostKnowledgeInteraction(communicativeAct, argumentGraphPattern, resultGraphPattern);
 smartConnector.register(postInteraction);
 
 // REACT:
-ReactKnowledgeInteraction reactInteraction = new ReactKnowledgeInteraction(graphPattern);
+ReactKnowledgeInteraction reactInteraction = new ReactKnowledgeInteraction(communicativeAct, argumentGraphPattern, resultGraphPattern);
 smartConnector.register(reactInteraction);
 ```
 
+You can also provide a name for your interaction, for example:
+```java
+AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(communicativeAct, graphPattern, name); 
+```
+
+If you want to use prefixes in your graph pattern, these can be defined in the `graphPattern`:
+```java
+GraphPattern graphPattern = new GraphPattern(prefixes, pattern);
+```
+
+</TabItem>
+<TabItem value="JSON" label="Rest API">
+To instantiate a Knowledge Interaction, you need to send a POST to `/sc/ki` with a body that contains the type of knowledge interaction that you want to make, and any required graph patterns.
+ASK and ANSWER require one graph pattern, like so:
+
+```json
+{
+  "knowledgeInteractionType": "AskKnowledgeInteraction",
+  "graphPattern": "?s ?p ?o"
+}
+```
+
+POST and REACT require an `argumentGraphPattern`, and optionally use a `resultGraphPattern`. For example:
+
+```json
+{
+  "knowledgeInteractionType": "PostKnowledgeInteraction",
+  "argumentGraphPattern": "?s ?p ?o",
+  "resultGraphPattern": "?x ?y ?z"
+}
+```
+
+You can also provide a name for your interaction and define prefixes for your graph patterns:
+
+```json
+{
+  "knowledgeInteractionType": "AskKnowledgeInteraction",
+  "knowledgeInteractionName": "my-ask",
+  "graphPattern": "?a rdf:type ex:Book",
+  "prefixes": {
+    "rdf": "https://www.w3.org/1999/02/22-rdf-syntax-ns/"
+  }
+}
+```
+
 </TabItem>
 </Tabs>
 
@@ -50,6 +100,30 @@ AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(graphPatter
 AskResult interactionResult = sc.ask(askInteraction, queryBindings).get();
 ```
 
+</TabItem>
+<TabItem value="JSON" label="Rest API">
+Send a POST to `/sc/ask` to execute an Ask Knowledge Interaction.
+To execute a Post Knowledge Interaction, send a POST to `/sc/post`.
+
+Triggering an interaction requires you to provide two parameters:
+* `Knowledge-Base-Id`: specifies the Knowledge Base Id for which to execute the ask
+* `Knowledge-Interaction-Id`: specifies the Ask Knowledge Interaction that should be executed
+
+In the body you can also specify a binding set, or a recipient selector *and* binding set.
+The recipient selector can be used to select a single Knowledge Base Id which should be contacted.
+The binding set specifies values that you are interested in. These must correspond to the variables in the graph pattern of the knowledge interaction.
+```json
+{
+  "recipientSelector": {
+    "knowledgeBases": []
+  },
+  "bindingSet": [
+    {}
+  ]
+}
+```
+If you leave the array for `knowledgeBases` empty, then it will simply ask all relevant KBs.
+
 </TabItem>
 </Tabs>
 

docs/docs/get-started/smart-connector.md

@@ -5,12 +5,49 @@ sidebar_position: 6
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Smart Connectors
+# Connecting to a Knowledge Network
+This page describes how to connect to an (existing) Knowledge Network using a Smart Connector.
+
+To connect to a Knowledge Network, you need a Knowledge Engine Runtime (KER).
+Every KER in distributed mode consists of two APIs: [Knowledge Engine Developer REST API](https://github.com/TNO/knowledge-engine/blob/1.2.5/smart-connector-rest-server/src/main/resources/openapi-sc.yaml) and the [Inter-Knowledge Engine Runtime API](https://github.com/TNO/knowledge-engine/blob/1.2.5/smart-connector/src/main/resources/openapi-inter-ker.yaml).
+The former is started on port `8280` by default, and you use this API to register your Knowledge Base and Knowledge Interactions.
+The latter API is meant for internal communication between KERs and you do not need to use it yourself.
+However, you do need to make sure this API is reachable for other KERs in the Knowledge Network.
+By default, this API is available on port 8081, but sometimes you need to change this port using the `KE_RUNTIME_PORT` environment variable.
+Make sure the latter API of your KER is accessible from the internet and configure its URL when starting the KER with the `KE_RUNTIME_EXPOSED_URL` environment variable.
+To set this up correctly, you typically install a reverse proxy like NGINX and open the correct ports in the firewall of the server.
+For this you need to contact the administrator of the server you are using.
+A KER starts in distributed mode when it detects the `KD_URL` environment variable.
+This variable points to the Knowledge Directory of the Knowledge Network.
+You can configure it using environment variables `KD_URL=<knowledge-direcotry-url>`.
+If the Knowledge Directory is protected using Basic Authentication, you can add the credentials to the KD_URL as described [here](https://stackoverflow.com/a/50528734).
+
+
+
+To connect to a network, the following steps are required:
+* Get access to the Knowledge Engine Runtime (KER) you want to connect to
+* Start a Knowledge Engine Runtime (KER) on your computer
+* Register your Knowledge Base via the REST Developer API
+* [Register your Knowledge Interactions via the REST Developer API](./knowledge-interactions.md)
+
+## Getting access to the Knowledge Engine Runtime
+To get access to the Knowledge Engine Runtime you want to connect to, you will need its URL.
+You can test whether you have access to its REST Developer API by activating its `GET /sc` operation via the browser with a URL like: `<ker-url>/sc`
+If the KER is protected with Basic Authentication, your browser might ask you for credentials. 
+This operation returns JSON with all the Knowledge Bases that are registered with that Knowledge Engine Runtime.
+An empty list indicates that no Knowledge Bases are registered with this Knowledge Engine Runtime.
+If you run a Knowledge Engine Runtime on your own computer, then the URL is typically `http://localhost:8280`.
+
+## How to start a Smart Connector?
+> *Before starting a Smart Connector, please ensure that there is a Knowledge Directory available to connect to.*
+
+> Typically, you start a single Smart Connector which should be available as long as your system (Knowledge Base) is available.
 
-## How to instantiate a Smart Connector?
 <Tabs groupId="tke-usage">
 <TabItem value="java" label="Java">
 
+Assuming `this` is your knowledge base, you can make a `SmartConnector` as follows:
+
 ```java
 SmartConnector sc = SmartConnectorBuilder.newSmartConnector(this).create();
 ```
@@ -31,9 +68,12 @@ java -Dorg.slf4j.simpleLogger.logFile=ke.log -cp "smart-connector-rest-dist-1.2.
 </TabItem>
 </Tabs>
 
-
-## How to add a Smart Connector?
-
 ## How to remove a Smart Connector?
 
-## How to renew the lease of a Smart Connector?
+## How to renew the lease of a Smart Connector?
+
+## How to deal with the long polling connection of a Smart Connector?
+Each Smart Connector uses a single long polling connection to receive all interactions from the Knowledge Engine.
+The Knowledge Engine REST Developer API uses long-polling to notify you when your KB needs to react.
+This long-polling connection will automatically return every *29 seconds* with status code 202 to prevent certain proxies from blocking it.
+You will need to reestablish this long polling connection when you receive a 202 and after you receive data via it.