0.9.0 release version.
1 file changed
tree: 3f94faf6eec351f2d6f470d983834485966b8ef5
  1. .asf.yaml
  2. .github/
  3. .gitignore
  7. README.md
  8. assembly.xml
  9. bin/
  10. bindist/
  11. docker/
  12. external/
  13. idea/
  14. javadoc/
  15. nlpcraft-examples/
  16. nlpcraft-stanford/
  17. nlpcraft/
  18. openapi/
  19. pom.xml
  20. sql/

License Build Documentation Status Gitter

What is Apache NLPCraft?

Apache NLPCraft is an open source library for adding a natural language interface for modern applications. It enables people to interact with your products using voice or text:

Why Natural Language?

Natural Language Interface enables users to interact with any type of products using natural language augmenting existing UI/UX with fidelity and simplicity of a familiar spoken language. Natural Language has no learning curve, no special rules or UI to master, no cumbersome syntax or terms to remember - it's just a natural interface that your users already know.

Key Features

Intent Definition Language

Advanced Intent Definition Language (IDL) coupled with deterministic intent matching provide ease of use and unprecedented expressiveness for designing real-life, non-trivial intents.

Composable Named Entities

Easily compose, mix and match new named entities out of built-in or external ones, creating new reusable named entity recognizers on the fly.


Advanced out-of-the-box support for maintaining and managing conversational context that is fully integrated with intent matching.


Everything you do with NLPCraft is part of your source code. No more awkward web UIs splitting your logic across different incompatible places. Model-as-a-code is built by engineers, and it reflects how engineers work.

By Devs - For Devs

Built with a singular focus - provide state-of-the-art developers with unprecedented productivity and efficiency when building modern natural language applications.


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

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.8.0 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)~{has(tok_groups(), 'act')} term(loc)~{tok_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"
                locToks.map(_.meta[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) 2021 Apache Software Foundation