Fix for NLPCRAFT-168.
3 files changed
tree: b4ac2e97d3ebc57a4a2a9c005407f137acff5b60
  1. .asf.yaml
  2. .github/
  3. .gitignore
  8. assembly.xml
  9. bin/
  10. bindist/
  11. docker/
  12. external/
  13. idea/
  14. javadoc/
  15. nlpcraft-stanford/
  16. nlpcraft/
  17. openapi/
  18. pom.xml
  19. sql/

License build Documentation Status Gitter

What is Apache NLPCraft?

Apache NLPCraft is an open source library for adding a natural language interface to any applications. Based on semantic modelling it allows rapid implementation and requires no model training or pre-existing text corpora:

Why Natural Language?

Natural Language Interface (NLI) enables users to explore any type of data sources using natural language augmenting existing UI/UX with fidelity and simplicity of a familiar spoken language. There is no learning curve, no special rules or UI to master, no cumbersome syntax or terms to remember - just a natural language that your users already speak.

Key Features

Semantic Modeling

Advanced semantic modelling and intent-based matching enables deterministic natural language understanding without requiring deep learning training or pre-existing text corpora.

Any Data Source

Any data source, device, or service - public or private. From databases and SaaS systems, to smart home devices, voice assistants and chatbots.

English Focused

NLPCraft focuses on processing English language delivering the ease of use and unparalleled comprehension for the language spoken by more than a billion people.

By Devs - For Devs

Built with a singular focus - provide developers with unprecedented productivity and efficiency when building modern NLI applications.

Advanced NLP Toolset

Combines ease-of-use and development productivity with state-of-the-art NLP capabilities like short-term-memory (STM) support, advanced intent DSL with deterministic matching, and composable NEs.


REST API and Java-based implementation natively supports the world's largest ecosystem of development tools, multiple programming languages, frameworks and services.


Model-as-a-code convention natively supports any system development life cycle tools and frameworks in the Java ecosystem.

Out-Of-The-Box Integration

NLPCraft natively integrates with 3rd party libraries for base NLP processing and named entity recognition:

Learn more >

How It Works

When using NLPCraft you will be dealing with three main components:

Data model specifies how to interpret user input, how to query a data source, and how to format the result back. Developers use model-as-a-code approach to build models using any JVM language like Java, Scala, Groovy or Kotlin.

Data probe is a DMZ-deployed application designed to securely deploy and manage data models. Each probe can manage multiple models, and you can have many probes.

REST server provides REST endpoint for user applications to securely query data sources using NLI via data models deployed in data probes.

Learn more >


As a quick example let's consider a very simple implementation for NLI-powered light switch. Our app should understand something like Turn the lights off in the entire house or Switch on the illumination in the master bedroom closet. You can easily modify intent callbacks in the model implementation below to perform the actual light switching using HomeKit or Arduino-based controllers.

Add NLPCraft

Add NLPCraft dependency to your project:


NOTE: 0.7.1 should be the latest NLPCraft version.

Define Data Model

Declare the static part of the data model using YAML which we will later load in our model implementation. You can declare entire model in the code - but doing it with JSON or YAML is more productive:

id: "nlpcraft.lightswitch.ex"
name: "Light Switch Example Model"
version: "1.0"
description: "NLI-powered light switch example model."
  - name: "<ACTION>"
    macro: "{turn|switch|dial|control|let|set|get|put}"
  - name: "<ENTIRE_OPT>"
    macro: "{entire|full|whole|total|*}"
  - name: "<LIGHT>"
    macro: "{all|*} {it|them|light|illumination|lamp|lamplight}"
enabledBuiltInTokens: [] # This example doesn't use any built-in tokens.
  - id: "ls:loc"
    description: "Location of lights."
      - "<ENTIRE_OPT> {upstairs|downstairs|*} {kitchen|library|closet|garage|office|playroom|{dinning|laundry|play} room}"
      - "<ENTIRE_OPT> {upstairs|downstairs|*} {master|kid|children|child|guest|*} {bedroom|bathroom|washroom|storage} {closet|*}"
      - "<ENTIRE_OPT> {house|home|building|{1st|first} floor|{2nd|second} floor}"
  - id: "ls:on"
      - "act"
    description: "Light switch ON action."
      - "<ACTION> <LIGHT>"
      - "<ACTION> on <LIGHT>"
  - id: "ls:off"
      - "act"
    description: "Light switch OFF action."
      - "<ACTION> <LIGHT> {off|out}"
      - "{<ACTION>|shut|kill|stop|eliminate} {off|out} <LIGHT>"
      - "no <LIGHT>"
  - "intent=ls term(act)~{groups @@ 'act'} term(loc)~{id == 'ls:loc'}*"

Model Implementation

Once we have model declaration we can provide implementation for intent callbacks. We'll use Scala to implement the data model, but you can use any JVM-based language like Java, Groovy, or Kotlin:

package org.apache.nlpcraft.examples.lightswitch
import org.apache.nlpcraft.model.{NCIntentTerm, _}
class LightSwitchModel extends NCModelFileAdapter("org/apache/nlpcraft/examples/lightswitch/lightswitch_model.yaml") {
        "Turn the lights off in the entire house.",
        "Switch on the illumination in the master bedroom closet.",
        "Get the lights on.",
        "Please, put the light out in the upstairs bedroom.",
        "Set the lights on in the entire house.",
        "Turn the lights off in the guest bedroom.",
        "Could you please switch off all the lights?",
        "Dial off illumination on the 2nd floor.",
        "Please, no lights!",
        "Kill off all the lights now!",
        "No lights in the bedroom, please."
    def onMatch(
        @NCIntentTerm("act") actTok: NCToken,
        @NCIntentTerm("loc") locToks: List[NCToken]
    ): NCResult = {
        val status = if (actTok.getId == "ls:on") "on" else "off"
        val locations =
            if (locToks.isEmpty)
                "entire house"
      [String]("nlpcraft:nlp:origtext")).mkString(", ")
        // Add HomeKit, Arduino or other integration here.
        // By default - just return a descriptive action string.
        NCResult.text(s"Lights '$status' in '${locations.toLowerCase}'.")


  • We are loading our static model declaration that we've defined above using NCModelFileAdapter base class.
  • Annotation @NCIntentRef references the intent defined in our YAML model definition.
  • We use @NCIntentSample to provide sample sentences that should satisfy this intent. These samples are used for model auto-testing and synonyms analysis.

Done! 👌

Learn more about this example >


Copyright (C) 2020 Apache Software Foundation