getting-started.html

---
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 <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            Lets review how to run NLPCraft <a href="https://github.com/apache/incubator-nlpcraft/tree/master/nlpcraft-examples" target="github">examples</a>.
            We will use an example shipped with NLPCraft along with demonstrating the main components of NLPCraft -
            <a href="/server-and-probe.html#probe">data probe</a>,
            <a href="/server-and-probe.html#server">REST server</a>, and
            <a href="/tools/script.html"><code>nlpcraft.{sh|cmd}</code></a> script.
        </p>
        <p>
            We assume the following:
        </p>
        <ul>
            <li>
                You <a href="/download.html#zip">downloaded</a> NLPCraft {{site.latest_version}} as <b>binary release</b>.
                <ul>
                    <li>
                        If you downloaded the source release - run <code class="script">mvn clean package -P examples</code> to build binaries before proceeding.
                    </li>
                </ul>
            </li>
            <li>You followed <a href="/installation.html">installation</a> instructions.</li>
            <li>You are using MacOS/Linux environment.</li>
        </ul>
    </section>
    <section>
        <h2 class="section-title">Weather Forecast <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            We'll be testing <a href="/examples/weather_bot.html">Weather Example</a>
            to ask questions about weather forecast using REST APIs. This example returns a JSON weather
            data for variety of different inquiries about the past, present or future weather conditions.
        </p>
        <h2 id="probe-server" class="section-sub-title">Data Probe <span class="amp">&amp;</span> REST Server <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            <a href="/server-and-probe.html">Data probes</a> are used to deploy and host data model, while <a href="/server-and-probe.html">REST server</a> (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>
            Data probe and REST server are both Java applications.
            In this tutorial, we'll use <a href="/tools/script.html"><code>nlpcraft.{sh|cmd}</code></a> script that comes with NLPCraft
            to manage them. To start REST server and data probe - run the following two commands:
        </p>
        <pre class="brush: bash">
            $ bin/nlpcraft.sh start-server
            $ bin/nlpcraft.sh start-probe --cp=./build/nlpcraft-examples/weather/nlpcraft-example-weather-{{site.latest_version}}.jar --mdls=org.apache.nlpcraft.examples.weather.NCWeatherModel
        </pre>
        <p>
            At this point data probe and the REST server are started and connected.
        </p>
        <h2 id="querying" class="section-sub-title">Using REST API <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            We will be using NLPCraft CLI script to issue REST calls. Let's start NLPCraft CLI in interactive REPL mode
            by running <a href="/tools/script.html"><code>nlpcraft.{sh|cmd}</code></a> script with no argument:
        </p>
        <pre class="brush: bash">
            $ bin/nlpcraft.sh
        </pre>
        <p>
            <b>NOTES:</b>
        </p>
        <ul>
            <li>
                NLPCraft CLI automatically detects the REST server and data probe we have started in
                the previous step. You can see the status of the REST server and data probe in the REPL prompt or you can
                use <code>info</code> command to see a status information.
            </li>
            <li>
                When NLPCraft CLI detects running REST server it automatically signs in with the <a href="/using-rest.html#users">default user account</a>
                to obtain access token that is required for all REST calls. It will automatically use this access token
                while in REPL mode whenever required.
            </li>
            <li>
                Use <span class="keyboard">Tab</span> key anytime for auto-completion for commands, parameters,
                file systems paths, and model class names.
                Use <span class="keyboard">↑</span> and <span class="keyboard">↓</span> keys to scroll
                through command history.
            </li>
        </ul>
        <p>
            While in REPL mode lets use <code>ask</code> command to issue REST requests to our data model.
        </p>
        <div class="accordion" id="questions">
            <div class="card">
                <div class="card-header" id="q1">
                    <h2 class="mb-0">
                        <button class="btn btn-link btn-block text-left" type="button" data-toggle="collapse" data-target="#a1">
                            <b>Q:</b> What is the current forecast for Chicago?
                        </button>
                    </h2>
                </div>
                <div id="a1" class="collapse" data-parent="#questions">
                    <div class="card-body">
                        <p>
                            <img class="img-fluid" src="/images/getting_started_fig4.png" alt="">
                        </p>
                        <p>
                            <b>A:</b> we get a full 5-day forecast for Chicago.
                        </p>
                    </div>
                </div>
            </div>
            <div class="card">
                <div class="card-header" id="q2">
                    <h2 class="mb-0">
                        <button class="btn btn-link btn-block text-left collapsed" type="button" data-toggle="collapse" data-target="#a2">
                            <b>Q:</b> Any chance of snow today in Moscow?
                        </button>
                    </h2>
                </div>
                <div id="a2" class="collapse" data-parent="#questions">
                    <div class="card-body">
                        <p>
                            <img class="img-fluid" src="/images/getting_started_fig5.png" alt="">
                        </p>
                        <p>
                            <b>A:</b> we get today's Moscow weather report.
                        </p>
                    </div>
                </div>
            </div>
        </div>
    </section>
    <section>
        <h2 class="section-title">Done! 👌 <a href="#"><i class="top-link fas fa-fw fa-angle-double-up"></i></a></h2>
        <p>
            Use <code>stop</code> command to stop REST server and the data probe and <code>quit</code>
            command to quit from REPL mode:
        </p>
        <p>
            <img class="img-fluid" src="/images/getting_started_fig6.png" alt="">
        </p>
    </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>