---
active_crumb: Docs
layout: documentation
id: getting_started
---

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<div class="col-md-8 second-column">
    <section id="getting-started">
        <h2 class="section-title">Getting Started</h2>
        <p>
            In this section we'll take a quick 10 minutes look at running and
            testing <a href="https://github.com/apache/incubator-nlpcraft/tree/master/src/main/scala/org/apache/nlpcraft/examples" target="github">examples</a>
            shipped with NLPCraft along with
            running the main components of NLPCraft - data probe and REST server. We assume the following:
        </p>
        <ul>
            <li>You <a href="/download.html">downloaded</a> NLPCraft {{site.latest_version}} as a ZIP archive.</li>
            <li>You followed <a href="/installation.html">installation</a> instructions.</li>
            <li>You are using Mac OS/Linux environment.</li>
        </ul>
    </section>
    <section id="probe-server">
        <h2 class="section-title">Data Probe <span class="amp">&amp;</span> REST Server</h2>
        <p>
            Data probes are used to deploy and host data model, while REST server (or a
            cluster of servers) is used to accept client REST calls and route them to the data model deployed on data probes.
        </p>
        <p>
            Both data probe and the REST server start the same way. NLPCraft ships with all-inclusive
            single executable JAR file. We'll use command line to start the both.
            Open two console windows and start server first and then data probe by typing these commands:
        </p>
        <nav>
            <div class="nav nav-tabs" role="tablist">
                <a class="nav-item nav-link active" data-toggle="tab" href="#nav-srv-start" role="tab" aria-controls="nav-home" aria-selected="true">REST Server</a>
                <a class="nav-item nav-link" data-toggle="tab" href="#nav-probe-start" role="tab" aria-controls="nav-home" aria-selected="true">Data Probe</a>
            </div>
        </nav>
        <div class="tab-content">
            <div class="tab-pane fade show active" id="nav-srv-start" role="tabpanel">
                <pre class="brush: plain">
                    $ cd build
                    $ java -jar apache-nlpcraft-{{site.latest_version}}-all-deps.jar -server
                </pre>
                <p>
                    You can can also start it via Docker:
                </p>
                <pre class="brush: plain">
                    $ docker run -m 8G -p 8081:8081 -p 8201:8201 -p 8202:8202 nlpcraftserver/server:{{site.latest_version}}
                </pre>
                <p>
                    REST server starts with default configuration (<code>nlpcraft.conf</code> and
                    <code>ignite.xml</code> files located in the same folder as <code>apache-nlpcraft-{{site.latest_version}}-all-deps.jar</code>
                    file). You should see the output similar to this:
                </p>
                <pre class="brush: plain">
                        _   ____      ______           ______
                       / | / / /___  / ____/________ _/ __/ /_
                      /  |/ / / __ \/ /   / ___/ __ `/ /_/ __/
                     / /|  / / /_/ / /___/ /  / /_/ / __/ /_
                    /_/ |_/_/ .___/\____/_/   \__,_/_/  \__/
                           /_/

                    Server
                    Version: {{site.latest_version}}
                    Copyright (C) 2020 Apache Software Foundation.

                    ...

                    +-------------------------+
                    | Server started [19.35s] |
                    +-------------------------+


                    Mar-11 23:21:04 [INFO ] REST server is listening on 'localhost:8081'.
                </pre>
            </div>
            <div class="tab-pane fade show" id="nav-probe-start" role="tabpanel">
                <pre class="brush: plain">
                    $ cd build
                    $ java -jar apache-nlpcraft-{{site.latest_version}}-all-deps.jar -probe
                </pre>
                <p>
                    Data probe starts with default configuration (file <code>nlpcraft.conf</code> located in the same folder
                    as <code>apache-nlpcraft-{{site.latest_version}}-all-deps.jar</code> file) that deploys
                    all example models shipped with NLPCraft. You should see the output similar to this:
                </p>
                <pre class="brush: plain">
                    _   ____      ______           ______
                   / | / / /___  / ____/________ _/ __/ /_
                  /  |/ / / __ \/ /   / ___/ __ `/ /_/ __/
                 / /|  / / /_/ / /___/ /  / /_/ / __/ /_
                /_/ |_/_/ .___/\____/_/   \__,_/_/  \__/
                       /_/

                Data Probe
                Version: {{site.latest_version}}
                Copyright (C) 2020 Apache Software Foundation.

                Mar-11 23:25:52 [INFO ] Probe Configuration:
                +----------------------------------------------------------------------+
                | Probe ID        | all.examples                                       |
                | Probe Token     | 3141592653589793                                   |
                | API Version     | {{site.latest_version}}, 2019-04-16                                  |
                | Down-Link       | localhost:8202                                     |
                | Up-Link         | localhost:8201                                     |
                +-----------------+----------------------------------------------------+
                | Model providers | org.apache.nlpcraft.examples.alarm.AlarmModel             |
                |                 | org.apache.nlpcraft.examples.echo.EchoModel               |
                |                 | org.apache.nlpcraft.examples.helloworld.HelloWorldModel   |
                |                 | org.apache.nlpcraft.examples.time.TimeModel               |
                |                 | org.apache.nlpcraft.examples.weather.WeatherModel         |
                |                 | org.apache.nlpcraft.examples.lightswitch.LightSwitchModel |
                +-----------------+----------------------------------------------------+
                | JARs Folder     |                                                    |
                +----------------------------------------------------------------------+

                ...

                Mar-11 23:25:56 [INFO ] Models deployed: 6

                +===================================================================================+
                |        Model ID         |            Name            | Ver. | Elements | Synonyms |
                +===================================================================================+
                | nlpcraft.alarm.ex       | Alarm Example Model        | 1.0  | 1        | 419      |
                | nlpcraft.weather.ex     | Weather Example Model      | 1.0  | 3        | 9045     |
                | nlpcraft.lightswitch.ex | Light Switch Example Model | 1.0  | 3        | 643      |
                | nlpcraft.helloworld.ex  | HelloWorld Example Model   | 1.0  | 0        | 0        |
                | nlpcraft.time.ex        | Time Example Model         | 1.0  | 1        | 432      |
                | nlpcraft.echo.ex        | Echo Example Model         | 1.0  | 0        | 0        |
                +-----------------------------------------------------------------------------------+

                ...

                +--------------------------+
                | Probe started [5.12 sec] |
                +--------------------------+

                ...

                Mar-11 23:25:58 [INFO ] Server connection established.
                </pre>
            </div>
        </div>
        <p>
            At this point you have both the data probe and the REST server started and connected to each other.
            We are ready to start calling REST API to use natural language to query our example models.
        </p>
    </section>
    <section id="querying">
        <h2 class="section-title">Weather Forecast</h2>
        <p>
            We'll be testing <a target="github" href="https://github.com/apache/incubator-nlpcraft/tree/master/src/main/scala/org/apache/nlpcraft/examples/weather">Weather Example</a>
            to ask questions about weather forecast using REST APIs. This example returns a comprehensive JSON weather
            data for variety of different inquiries about the past, present or future weather conditions.
        </p>
        <p>
            There are <a target=_ href="https://medium.com/@alicealdaine/top-10-api-testing-tools-rest-soap-services-5395cb03cfa9">many ways</a> to issue
            and test REST calls - for our examples we'll use standard
            <a target="wiki" href="https://en.wikipedia.org/wiki/CURL">cURL</a> utility which you can simply use from the
            command line in any OS.
            NLPCraft comes with a convenient wrapper script <code>bin/nccurl.sh</code> that shortens
            command line of the standard <code>cURL</code>. Note also that we'll be using Python to pretty format
            cURL JSON responses.
        </p>
        <h3 class="section-title">Sign In</h3>
        <p>
            First, we need to sign in and obtain <b>access token</b>. We'll use <code>/signin</code>
            REST call for that. When REST server starts
            for the first time it creates a default user with email <code>admin@admin.com</code> and
            <code>admin</code> password. Open new command line terminal and let's use these default credentials for sing in:
        </p>
        <pre class="brush: js; highlight: [3]">
            $ nccurl.sh signin '{"email": "admin@admin.com", "passwd": "admin"}' | python -m json.tool
            {
                "acsTok": "KMGWMQJ44",
                "status": "API_OK"
            }
        </pre>
        <p>
            Note the returned access token <code>KMGWMQJ44</code> which we'll use in subsequent operations. Keep in mind that you
            will get different access tokens and IDs when you are performing these steps by yourself.
        </p>
        <h3 class="section-title"><b>Query</b></h3>
        <p>
            Now that we have signed in (access token <code>KMGWMQJ44</code>) we can go ahead and start asking natural language
            questions against our data model (<code>nlpcraft.weather.ex</code>). For this example we'll use
            <a target=apiary href="https://nlpcraft.docs.apiary.io/#reference/asking"><code>/ask/sync</code></a> REST call - a
            call that submit the request and waits for its completion before returning the result.
        </p>
        <p>
            <b>Q: What is the current forecast for Chicago?</b>
        </p>
        <pre class="brush: js highlight: [2, 3, 4, 5]">
            $ nccurl.sh ask/sync '{"acsTok": "KMGWMQJ44", "txt": "What is the current forecast for Chicago?", "mdlId": "nlpcraft.weather.ex"}' | python -m json.tool
        </pre>
        <p>
            And we get a full 5-day forecast for Chicago:
        </p>
        <pre class="brush: js">
        {
            "state": [
                {
                    "createTstamp": 1552527883277,
                    "mdlId": "nlpcraft.weather.ex",
                    "resBody": {
                        "intentId": "fcast|date?|city?",
                        "result": {
                            "forecast": {
                                "forecastday": [
                                    {
                                        "astro": {
                                            "moonrise": "11:05 AM",
                                            "moonset": "01:01 AM",
                                            "sunrise": "07:06 AM",
                                            "sunset": "06:55 PM"
                                        },
                                    }
                                ]
                            },
                            ...
                            "location": {
                                "lat": "41.85",
                                "localtime": "2019-03-13 20:44",
                                "localtime_epoch": "1552527885",
                                "lon": "-87.65",
                                "name": "Chicago",
                                "region": "Illinois",
                                "tz_id": "America/Chicago"
                            }
                        }
                    },
                    "resType": "json",
                    "srvReqId": "gJ0OJ0qXp",
                    "status": "QRY_READY",
                    "updateTstamp": 1552527885155,
                    "usrId": 7001
                }
            ],
            "status": "API_OK"
        }
        </pre>
        <p>
            <b>Q: Any chance of snow today in Moscow?</b>
        </p>
        <pre class="brush: js highlight: [2, 3, 4, 5]">
            $ nccurl.sh ask/sync '{"acsTok": "KMGWMQJ44", "txt": "Any chance of snow today in Moscow?", "mdlId": "nlpcraft.weather.ex"}' | python -m json.tool
        </pre>
        <p>
            And we get today's Moscow weather report:
        </p>
        <pre class="brush: js">
            {
                "states": [
                    {
                        "createTstamp": 1552529034568,
                        "mdlId": "nlpcraft.weather.ex",
                        "resBody": {
                            "intentId": "curr|date?|city?",
                            "result": {
                                "forecast": {
                                    "forecastday": [
                                        {
                                            "astro": {
                                                "moonrise": "10:16 AM",
                                                "moonset": "02:16 AM",
                                                "sunrise": "06:49 AM",
                                                "sunset": "06:30 PM"
                                            },
                                            "date": "2019-03-14",
                                            "date_epoch": "1552521600",
                                            "day": {
                                                "avghumidity": 89.0,
                                                "avgtemp_c": -3.9,
                                                "avgtemp_f": 25.1,
                                                "avgvis_km": 19.6,
                                                "avgvis_miles": 12.0,
                                                "condition": {
                                                    "code": 1198.0,
                                                    "icon": "//cdn.apixu.com/weather/64x64/day/311.png",
                                                    "text": "Light freezing rain"
                                                },
                                                "maxtemp_c": -0.2,
                                                "maxtemp_f": 31.6,
                                                "maxwind_kph": 15.8,
                                                "maxwind_mph": 9.8,
                                                "mintemp_c": -7.3,
                                                "mintemp_f": 18.9,
                                                "totalprecip_in": 0.0,
                                                "totalprecip_mm": 0.1,
                                                "uv": 1.7
                                            }
                                        }
                                    ]
                                },
                                "location": {
                                    "lat": "55.75",
                                    "localtime": "2019-03-14 5:03",
                                    "localtime_epoch": "1552529035",
                                    "lon": "37.62",
                                    "name": "Moscow",
                                    "region": "Moscow City",
                                    "tz_id": "Europe/Moscow"
                                }
                            }
                        },
                        "resType": "json",
                        "srvReqId": "bgp299kX0",
                        "status": "QRY_READY",
                        "updateTstamp": 1552529035186,
                        "usrId": 7001
                    }
                ],
                "status": "API_OK"
            }
        </pre>
        <h3 class="section-title">Sign Out</h3>
        <p>
            Once we enjoyed our conversation about the weather we sign out:
        </p>
        <pre class="brush: js highlight: [3]">
            $ nccurl.sh signout '{"acsTok": "KMGWMQJ44"}' | python -m json.tool
            {
                "status": "API_OK"
            }
        </pre>
    </section>
</div>
<div class="col-md-2 third-column">
    <ul class="side-nav">
        <li class="side-nav-title">On This Page</li>
        <li><a href="#getting-started">Getting Started</a></li>
        <li><a href="#probe-server">Data Probe <span class="amp">&amp;</span> Server</a></li>
        <li><a href="#querying">Using REST API</a></li>
        {% include quick-links.html %}
    </ul>
</div>