Getting started¶

Prerequisites¶

Make sure that the following applications are installed:

• JAVA (at least version 11)
• Maven (at least version 3.6)
• JAVA IDE with Maven support (e.g. IntelliJ IDEA, which is used in this manual)

You can check the versions by executing the following commands in your terminal

java --version
mvn --version

Creating a Maven Project¶

First, you need to create an empty Maven project in your IDE. To do so, click File -> New -> Project

Select Maven and a JAVA version greater 11.

Give the project an appropriate name and select the Location.

After the project is created, add the following line to the pom.xml to be able to use stepDP.

First these lines, so that the required JAVA features of the newer JAVA version can be used:

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>10</source>
                    <target>10</target>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

Then we add the stepDP repository:

<repositories>
    <repository>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>always</updatePolicy>
            <checksumPolicy>fail</checksumPolicy>
        </releases>
        <id>stepDP</id>
        <name>stepDP SB Server</name>
        <url>https://umtl.dfki.de/stepdp/repo/</url>
        <layout>default</layout>
    </repository>
</repositories>

And finally, we add stepDP as a dependency:

<dependencies>
    <dependency>
        <groupId>de.dfki.step</groupId>
        <artifactId>spring</artifactId>
        <version>[1.0.0,1.1.0)</version>
    </dependency>
</dependencies>

<dependencies>
    <dependency>
        <groupId>de.dfki.step</groupId>
        <artifactId>core</artifactId>
        <version>[1.0.0,1.1.0)</version>
    </dependency>
    <dependency>
        <groupId>de.dfki.step</groupId>
        <artifactId>spring</artifactId>
        <version>[1.0.0,1.1.0)</version>
    </dependency>
</dependencies>

Your pom.xml should look like this (since we do not update the images with every release, just ignore the version number):

Finally, we need to re-import your Maven project. To do this, click on Maven in the top right corner and select "Reload All Maven Projects".

Now stepDP can be used in your project.

First Sample Application¶

At the beginning we want to build a simple application that can greet us. For this purpose create the required files as shown in the screenshot:

In the Main class you can also check if the integration of stepDP worked correctly by testing that the namespace de.dfki.step is importable.

If this is the case, you can add the start routine to this class:

package example;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;

import java.io.IOException;

@SpringBootApplication(scanBasePackages = {"de.dfki.step.web"})
public class Main {
    private static final Logger log = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args) throws IOException {
        ConfigurableApplicationContext ctx = SpringApplication.run(Main.class, args);
    }
}

stepDP is based on the Spring Framework. Therefore it must be initialized in the start class and the web interfaces must be configured accordingly.

Then we can already create our first dialogue. Copy the following code into the Dialogue.java file:

package example;

import de.dfki.step.blackboard.Rule;
import de.dfki.step.blackboard.IToken;
import de.dfki.step.blackboard.conditions.PatternCondition;
import de.dfki.step.blackboard.patterns.Pattern;
import de.dfki.step.blackboard.patterns.PatternBuilder;
import de.dfki.step.blackboard.rules.SimpleRule;
import de.dfki.step.dialog.Dialog;
import de.dfki.step.kb.semantic.PropString;
import de.dfki.step.kb.semantic.Type;

public class Dialogue extends Dialog {
    private static final Logger log = LoggerFactory.getLogger(Dialogue.class);

    public Dialogue() throws Exception{
        // define type "GreetingIntent" in the semantic tree
        Type greetingIntent = new Type("GreetingIntent", this.getKB());
        greetingIntent.addProperty(new PropString("userName", this.getKB()));
        this.getKB().addType(greetingIntent);

        // define a rule that reacts to a greeting intent by greeting the user
        Rule greetingRule = new SimpleRule(tokens -> {
            IToken t = tokens[0];
            if (!t.isSet("userName")) {
                System.out.println("Hello! What's your name?");
            } else {
                String userName = t.getString("userName");
                System.out.println("Hello, nice to meet you, " + userName + "!");
            }
        }, "GreetingRule");
        // here, we set the condition for the rule: it should be triggered by 
        // tokens of type "GreetingIntent"
        Pattern p = new PatternBuilder("GreetingIntent", this.getKB()).build();
        greetingRule.setCondition(new PatternCondition(p));
        this.getBlackboard().addRule(greetingRule);
    }
}

This is a simple example of how to define dialog rules with StepDP. The rule reacts on a greeting intent from the user and greets back. To create such a rule, we need to perform three steps:

1. Add a type GreetingIntent to the semantic tree.
2. Create a new SimpleRule and provide a lambda expression that specifies what the rule should do.
3. Set a condition for the rule that specifies by which tokens the rule should be triggered (here: tokens of type GreetingIntent).

This example is supposed to give you a quick start into developing with StepDP. If you want to find out more about how StepDP works, refer to the section Documentation. It also includes a more detailed description of this example in the section Simple Rule.

Then we still have to configure our application. To do this we edit application.yaml as follows

logging.level.root: INFO
server.port: 50000
dialog:
  name: example.Dialogue

Here we first define the debug level and the port of the web server. Then we determine which dialogue should be loaded.

Afterwards we can already start our stepDP project. To do this, we go to the Main Class and start our project from there.

Web Interface¶

We can now open a web browser and go to the address http://127.0.0.1:50000 There you will find the WebGUI of stepDP. Under the tab "Blackboard Rules", you will see the available rules and which rules are currently active (active rules are depicted in white, inactive in grey font).

To test our dialogue, we go to "Blackboard Input", insert the following JSON object (or select "add greeting" from the drop-down menu) and press "Send Basic Token to Blackboard":

{
  "type": "GreetingIntent",
  "userName": "Alice"
}

After we have sent the intent, we can see the output of stepDP in our console.

You have now created your first successful stepDP project and successfully fired the greetingRule rule. You can find an example maven project with the code that we just saw and some other examples (e.g. for fusion rules) in the GitHub repository StepDP-Basic-Examples.