| --- |
| 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 NLPCraft <a href="https://github.com/apache/incubator-nlpcraft/tree/master/nlpcraft/src/main/scala/org/apache/nlpcraft/examples" target="github">examples</a>. |
| Instead of building our own model we will use an example model 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">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 MacOS/Linux environment.</li> |
| </ul> |
| </section> |
| <section id="probe-server"> |
| <h2 class="section-title">Data Probe <span class="amp">&</span> REST Server</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 and therefore can be started in many different ways. |
| In this tutorial, we'll use <a href="/tools/script.html"><code>nlpcraft.{sh|cmd}</code></a> script that comes with NLPCraft and acts as a central management |
| utility responsible for executing most of the routine tasks in NLPCraft in a simple and productive way. |
| </p> |
| <p> |
| To start REST server and data probe with default configurations - run the following two commands: |
| </p> |
| <nav> |
| <div class="nav nav-tabs" role="tablist"> |
| <a class="nav-item nav-link active" data-toggle="tab" href="#nav-start-cmd" role="tab" aria-controls="nav-home" aria-selected="true">Command</a> |
| <a class="nav-item nav-link" data-toggle="tab" href="#nav-srv-start" role="tab" aria-controls="nav-home" aria-selected="true">REST Server Output</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 Output</a> |
| </div> |
| </nav> |
| <div class="tab-content"> |
| <div class="tab-pane fade show active" id="nav-start-cmd" role="tabpanel"> |
| <pre class="brush: bash"> |
| $ bin/nlpcraft.sh start-server |
| $ bin/nlpcraft.sh start-probe |
| </pre> |
| </div> |
| <div class="tab-pane fade show" id="nav-srv-start" role="tabpanel"> |
| <p></p> |
| <p> |
| <img class="img-fluid" src="/images/getting_started_fig1.png" alt=""> |
| </p> |
| </div> |
| <div class="tab-pane fade show" id="nav-probe-start" role="tabpanel"> |
| <p></p> |
| <p> |
| <img class="img-fluid" src="/images/getting_started_fig2.png" alt=""> |
| </p> |
| </div> |
| </div> |
| <p> |
| At this point you have both the data probe and the REST server started and connected to each other. |
| </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/nlpcraft/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> |
| We will be using NLPCraft CLI script to issue REST calls. Let's start NLPCraft CLI in interactive REPL mode |
| by running <code>nlpcraft.{sh|cmd}</code> script with no argument: |
| </p> |
| <nav> |
| <div class="nav nav-tabs" role="tablist"> |
| <a class="nav-item nav-link active" data-toggle="tab" href="#nav-repl-cmd" role="tab" aria-controls="nav-home" aria-selected="true">Command</a> |
| <a class="nav-item nav-link" data-toggle="tab" href="#nav-repl-out" role="tab" aria-controls="nav-home" aria-selected="true">Output <i class="fa fa-desktop output"></i></a> |
| </div> |
| </nav> |
| <div class="tab-content"> |
| <div class="tab-pane fade show active" id="nav-repl-cmd" role="tabpanel"> |
| <pre class="brush: bash"> |
| $ bin/nlpcraft.sh |
| </pre> |
| </div> |
| <div class="tab-pane fade show" id="nav-repl-out" role="tabpanel"> |
| <p></p> |
| <p> |
| <img class="img-fluid" src="/images/getting_started_fig3.png" alt=""> |
| </p> |
| </div> |
| </div> |
| <p> |
| <b>NOTES:</b> |
| </p> |
| <ul> |
| <li> |
| Note that when you start NLPCraft CLI it automatically detects the REST server and data probe we have started in |
| the previous step. |
| </li> |
| <li> |
| You can see the status of the REST server and data probe in the prompt and you can always |
| use <code>info</code> command to see a full information. |
| </li> |
| <li> |
| When NLPCraft CLI detects running REST server it automatically signs in with the default user account |
| to obtain access token that is required for all REST calls. It will automatically use this access token |
| while in REPL mode whenever required so that you don't have to specify it manually. |
| </li> |
| <li> |
| Use <span class="keyboard">Tab</span> key anytime for command auto-suggestion and auto-completion. |
| </li> |
| <li> |
| You can also use <span class="keyboard">↑</span> and <span class="keyboard">↓</span> keys to scroll through command history. |
| </li> |
| </ul> |
| <h2 class="section-sub-title">Asking</h2> |
| <p> |
| Now that we are in NLPCraft CLI REPL mode and have both REST server and the data probe connected, we can |
| use <code>ask</code> command to issue REST requests to our data model. |
| </p> |
| <p> |
| <b>Q: What is the current forecast for Chicago?</b> |
| </p> |
| <p> |
| <img class="img-fluid" src="/images/getting_started_fig4.png" alt=""> |
| </p> |
| <p> |
| ...we get a full 5-day forecast for Chicago: |
| </p> |
| <p> |
| <b>Q: Any chance of snow today in Moscow?</b> |
| </p> |
| <p> |
| <img class="img-fluid" src="/images/getting_started_fig5.png" alt=""> |
| </p> |
| <p> |
| ...we get today's Moscow weather report: |
| </p> |
| </section> |
| <section> |
| <h2 class="section-title">Done! 👌</h2> |
| <p> |
| We've seen how to start REST server and data probe, and ask our weather bot several natural language questions. All we |
| have to do now is to 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">&</span> Server</a></li> |
| <li><a href="#querying">Using REST API</a></li> |
| {% include quick-links.html %} |
| </ul> |
| </div> |
| |
| |
| |
