Merge pull request #670 from snipsco/release/0.17.0

Release 0.17.0

.appveyor.yml

@@ -23,19 +23,9 @@ install:
 build: false
 
 test_script:
-  - "%PYTHON%\\python.exe -m snips_nlu download snips_nlu_de-0.2.0 --direct"
-  - "%PYTHON%\\python.exe -m snips_nlu download snips_nlu_en-0.2.0 --direct"
-  - "%PYTHON%\\python.exe -m snips_nlu download snips_nlu_es-0.2.0 --direct"
-  - "%PYTHON%\\python.exe -m snips_nlu download snips_nlu_fr-0.2.0 --direct"
-  - "%PYTHON%\\python.exe -m snips_nlu download snips_nlu_ja-0.2.0 --direct"
-  - "%PYTHON%\\python.exe -m snips_nlu download snips_nlu_ko-0.2.0 --direct"
-  - "%PYTHON%\\python.exe -m snips_nlu download snips_nlu_zh-0.2.0 --direct"
-  - "%PYTHON%\\python.exe -m snips_nlu link snips_nlu_de de"
-  - "%PYTHON%\\python.exe -m snips_nlu link snips_nlu_en en"
-  - "%PYTHON%\\python.exe -m snips_nlu link snips_nlu_es es"
-  - "%PYTHON%\\python.exe -m snips_nlu link snips_nlu_fr fr"
-  - "%PYTHON%\\python.exe -m snips_nlu link snips_nlu_ja ja"
-  - "%PYTHON%\\python.exe -m snips_nlu link snips_nlu_ko ko"
-  - "%PYTHON%\\python.exe -m snips_nlu link snips_nlu_zh zh"
+  - "%PYTHON%\\python.exe -m snips_nlu download-all-languages"
+  - "%PYTHON%\\python.exe -m snips_nlu download-entity snips/musicAlbum fr"
+  - "%PYTHON%\\python.exe -m snips_nlu download-entity snips/musicArtist fr"
+  - "%PYTHON%\\python.exe -m snips_nlu download-entity snips/musicTrack fr"
   - "%PYTHON%\\python.exe -m unittest discover"
   - "%PYTHON%\\python.exe snips_nlu_samples/sample.py"

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+**Description**:
+- ...
+
+**Checklist**:
+- [ ] My PR is ready for code review
+- [ ] I have added some tests, if applicable, and run the whole test suite, including [linting tests](../linting_test.py)
+- [ ] I have updated the documentation, if applicable

.travis.yml

@@ -23,4 +23,4 @@ after_success:
   - tox -e coverage-report
   - codecov
 
-cache: pip
+cache: pip

CHANGELOG.md

@@ -1,8 +1,18 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [0.17.0] - 2018-10-05
+### Added
+- Support for 3 new builtin entities in French: `snips/musicAlbum`, `snips/musicArtist` and `snips/musicTrack`
+- Minimal support for Italian
+
+### Changed
+- model version `0.16.0` => `0.17.0`
+
+### Fixed
+- Bug with entity feature name in intent classification
 
-## [0.16.5] - 2018-0906
+## [0.16.5] - 2018-09-06
 ### Fixed
 - Segfault in CRFSuite when the `CRFSlotFiller` is fitted only on empty utterances 
 
@@ -140,6 +150,7 @@ several commands.
 - Fix compiling issue with `bindgen` dependency when installing from source
 - Fix issue in `CRFSlotFiller` when handling builtin entities
 
+[0.17.0]: https://github.com/snipsco/snips-nlu/compare/0.16.5...0.17.0
 [0.16.5]: https://github.com/snipsco/snips-nlu/compare/0.16.4...0.16.5
 [0.16.4]: https://github.com/snipsco/snips-nlu/compare/0.16.3...0.16.4
 [0.16.3]: https://github.com/snipsco/snips-nlu/compare/0.16.2...0.16.3

README.rst

@@ -22,15 +22,84 @@ Snips NLU
 
 `Snips NLU <https://snips-nlu.readthedocs.io>`_ (Natural Language Understanding) is a Python library that allows to parse sentences written in natural language and extracts structured information.
 
-Check out our `blog post`_ to get more details about why we built Snips NLU and how it works under the hood.
+Summary
+-------
+
+- `What is Snips NLU about ?`_
+- `Getting Started`_
+
+  - `System requirements`_
+  - `Installation`_
+  - `Language Resources`_
+- `API Usage`_
+
+  - `Sample code`_
+  - `Command Line Interface`_
+- `Sample datasets`_
+- `Benchmarks`_
+- `Documentation`_
+- `FAQ`_
+- `Related content`_
+- `How do I contribute ?`_
+- `Licence`_
+
+What is Snips NLU about ?
+-------------------------
+
+Behind every chatbot and voice assistant lies a common piece of technology: Natural Language Understanding (NLU). Anytime a user interacts with an AI using natural language, their words need to be translated into a machine-readable description of what they meant.
+
+The NLU engine first detects what the intention of the user is (a.k.a. `intent`_), then extracts the parameters (called `slots`_) of the query. The developer can then use this to determine the appropriate action or response.
+
+
+Let’s take an example to illustrate this, and consider the following sentence:
+
+.. code-block:: text
+
+    "What will be the weather in paris at 9pm?"
+
+Properly trained, the Snips NLU engine will be able to extract structured data such as:
+
+.. code-block:: json
+
+    {
+       "intent": {
+          "intentName": "searchWeatherForecast",
+          "probability": 0.95
+       },
+       "slots": [
+          {
+             "value": "paris",
+             "entity": "locality",
+             "slotName": "forecast_locality"
+          },
+          {
+             "value": {
+                "kind": "InstantTime",
+                "value": "2018-02-08 20:00:00 +00:00"
+             },
+             "entity": "snips/datetime",
+             "slotName": "forecast_start_datetime"
+          }
+       ]
+    }
+
+In this case, the identified intent is ``searchWeatherForecast`` and two slots were extracted, a locality and a datetime. As you can see, Snips NLU does an extra step on top of extracting entities: it resolves them. The extracted datetime value has indeed been converted into a handy ISO format.
+
+Check out our `blog post`_ to get more details about why we built Snips NLU and how it works under the hood. We also published a `paper on arxiv`_, presenting the machine learning architecture of the Snips Voice Platform.
+
+
+Getting Started
+---------------
 
+-------------------
 System requirements
 -------------------
-- 64-bit Linux, MacOS >= 10.11, 64-bit Windows
-- Python 2.7 or Python >= 3.4
+
+- Python 2.7 or Python >= 3.4, < 3.7
 - RAM: Snips NLU will typically use between 100MB and 200MB of RAM, depending on the language and the size of the dataset.
 
 
+------------
 Installation
 ------------
 
@@ -46,10 +115,11 @@ distribution. To do so, `Rust <https://www.rust-lang.org/en-US/install.html>`_
 and `setuptools_rust <https://github.com/PyO3/setuptools-rust>`_ must be
 installed before running the ``pip install snips-nlu`` command.
 
+------------------
 Language resources
 ------------------
 
-Snips NLU relies on `language resources`_ that must be downloaded before the
+Snips NLU relies on `external language resources`_ that must be downloaded before the
 library can be used. You can fetch resources for a specific language by
 running the following command:
 
@@ -71,51 +141,41 @@ Once the resources have been fetched, they can be loaded in Python using:
 
     load_resources("en")
 
-The list of supported languages is available
-`here <https://snips-nlu.readthedocs.io/en/latest/languages.html>`_.
+The list of supported languages is available at 
+`this address <https://snips-nlu.readthedocs.io/en/latest/languages.html>`_.
 
-A simple example
-----------------
+API Usage
+---------
 
-Let’s take an example to illustrate the main purpose of this lib, and consider the following sentence:
+----------------------
+Command Line Interface
+----------------------
 
-.. code-block:: text
+The easiest way to test the abilities of this library is through the command line interface.
 
-    "What will be the weather in paris at 9pm?"
+First, start by training the NLU with one of the `sample datasets`_:
 
-Properly trained, the Snips NLU engine will be able to extract structured data such as:
+.. code-block:: sh
+    
+    snips-nlu train path/to/dataset.json path/to/output_trained_engine
 
-.. code-block:: json
+Where ``path/to/dataset.json`` is the path to the dataset which will be used during training, and ``path/to/output_trained_engine`` is the location where the trained engine should be persisted once the training is done.
 
-    {
-       "intent": {
-          "intentName": "searchWeatherForecast",
-          "probability": 0.95
-       },
-       "slots": [
-          {
-             "value": "paris",
-             "entity": "locality",
-             "slotName": "forecast_locality"
-          },
-          {
-             "value": {
-                "kind": "InstantTime",
-                "value": "2018-02-08 20:00:00 +00:00"
-             },
-             "entity": "snips/datetime",
-             "slotName": "forecast_start_datetime"
-          }
-       ]
-    }
+After that, you can start parsing sentences interactively by running:
+
+.. code-block:: sh
+    
+    snips-nlu parse path/to/trained_engine
 
+Where ``path/to/trained_engine`` corresponds to the location where you have stored the trained engine during the previous step.
 
+
+-----------
 Sample code
 -----------
 
 Here is a sample code that you can run on your machine after having
-installed `snips-nlu`, fetched the english resources and downloaded this
-`sample dataset`_:
+installed `snips-nlu`, fetched the english resources and downloaded one of the `sample datasets`_:
 
 .. code-block:: python
 
@@ -141,19 +201,39 @@ installed `snips-nlu`, fetched the english resources and downloaded this
 What it does is training an NLU engine on a sample weather dataset and parsing
 a weather query.
 
+Sample datasets
+---------------
+
+Here is a list of some datasets that can be used to train a Snips NLU engine:
+
+- `Lights dataset <sample_datasets/lights_dataset.json>`_: "Turn on the lights in the kitchen", "Set the light to red in the bedroom"
+- `Beverage dataset <sample_datasets/beverage_dataset.json>`_: "Prepare two cups of cappucino", "Make me a cup of tea"
+- `Flights dataset <sample_datasets/flights_dataset.json>`_: "Book me a flight to go to boston this weekend", "book me some tickets from istanbul to moscow in three days"
+
+Benchmarks
+----------
+
+In January 2018, we reproduced an `academic benchmark`_ which was published during the summer 2017. In this article, authors assessed the performance of API.ai (now Dialogflow, Google), Luis.ai (Microsoft), IBM Watson, and `Rasa NLU`_. For fairness, we used an updated version of Rasa NLU and compared it to the latest version of Snips NLU (both in dark blue).
+
+.. image:: .img/benchmarks.png
+
+In the figure above, `F1 scores`_ of both intent classification and slot filling were computed for several NLU providers, and averaged accross the three datasets used in the academic benchmark mentionned before. All the underlying results can be found `here <https://github.com/snipsco/nlu-benchmark/tree/master/2018-01-Braum-et-al-extension>`_.
+
+
 Documentation
 -------------
 
-To find out how to use Snips NLU please refer to our `documentation <https://snips-nlu.readthedocs.io>`_, it will provide you with a step-by-step guide on how to use and setup our library.
+To find out how to use Snips NLU please refer to the `package documentation <https://snips-nlu.readthedocs.io>`_, it will provide you with a step-by-step guide on how to setup and use this library.
 
 FAQ
 ---
-Please join our `Discord channel`_ to ask your questions and get feedback from the community.
+Please join Snips `Discord channel`_ to ask your questions and get feedback from the community.
 
-Links
------
+Related content
+---------------
 * `What is Snips about ? <https://snips.ai/>`_
 * Snips NLU Open sourcing `blog post`_
+* `Snips Voice Platform paper (arxiv) <https://arxiv.org/abs/1805.10190>`_
 * `Snips NLU Language Resources <https://github.com/snipsco/snips-nlu-language-resources>`_
 * `Bug tracker <https://github.com/snipsco/snips-nlu/issues>`_
 * `Snips NLU Rust <https://github.com/snipsco/snips-nlu-rs>`_: Rust inference pipeline implementation and bindings (C, Swift, Kotlin, Python)
@@ -170,7 +250,12 @@ Licence
 
 This library is provided by `Snips <https://www.snips.ai>`_ as Open Source software. See `LICENSE <LICENSE>`_ for more information.
 
-.. _language resources: https://github.com/snipsco/snips-nlu-language-resources
-.. _sample dataset: snips_nlu_samples/sample_dataset.json
+.. _external language resources: https://github.com/snipsco/snips-nlu-language-resources
 .. _Discord channel: https://discordapp.com/invite/3939Kqx
-.. _blog post: https://medium.com/snips-ai/an-introduction-to-snips-nlu-the-open-source-library-behind-snips-embedded-voice-platform-b12b1a60a41a
+.. _blog post: https://medium.com/snips-ai/an-introduction-to-snips-nlu-the-open-source-library-behind-snips-embedded-voice-platform-b12b1a60a41a
+.. _paper on arxiv: https://arxiv.org/abs/1805.10190
+.. _academic benchmark: http://workshop.colips.org/wochat/@sigdial2017/documents/SIGDIAL22.pdf
+.. _Rasa NLU: https://nlu.rasa.ai/
+.. _F1 scores: https://en.wikipedia.org/wiki/F1_score
+.. _intent: https://snips-nlu.readthedocs.io/en/latest/data_model.html#intent
+.. _slots: https://snips-nlu.readthedocs.io/en/latest/data_model.html#slot

debug/debug.py

@@ -16,9 +16,8 @@ def debug_training(dataset_path, config_path=None):
 
     load_resources(dataset["language"])
 
-    if config_path is None:
-        config = NLUEngineConfig()
-    else:
+    config = None
+    if config_path is not None:
         with Path(config_path).open("r", encoding="utf8") as f:
             config = NLUEngineConfig.from_dict(json.load(f))
 

docs/source/api.rst

@@ -99,4 +99,5 @@ Configurations
 Result and output format
 ------------------------
 
-.. automodule:: snips_nlu.result
+.. automodule:: snips_nlu.result
+   :members:

docs/source/conf.py

@@ -39,7 +39,7 @@
 # Autodoc settings
 autoclass_content = 'both'
 autodoc_member_order = 'bysource'
-autodoc_default_flags = ['members', 'no-show-inheritance']
+autodoc_default_options = {'members': None, 'no-show-inheritance': None}
 
 # Napoleon settings
 napoleon_google_docstring = True

docs/source/data_model.rst

@@ -265,7 +265,8 @@ entity in your dataset as follows:
             "value": "blue",
             "synonyms": []
           }
-        ]
+        ],
+        "parser_threshold": 1.0
       }
     }
 
@@ -361,6 +362,7 @@ not your custom entity is automatically extensible:
       "my_custom_entity": {
         "automatically_extensible": true,
         "use_synonyms": true,
-        "data": []
+        "data": [],
+        "parser_threshold": 1.0
       }
     }

docs/source/installation.rst

@@ -6,15 +6,12 @@ Installation
 System requirements
 -------------------
 - 64-bit Linux, MacOS >= 10.11, 64-bit Windows
-- Python 2.7 or Python >= 3.4
+- Python 2.7 or Python >= 3.4, <3.7
 - RAM: Snips NLU will typically use between 100MB and 200MB of RAM, depending on the language and the size of the dataset.
 
+.. warning::
 
-Python Version
---------------
-
-We recommend using the latest version of Python 3. Snips NLU supports Python
-3.4 and newer as well as Python 2.7.
+    Snips NLU does not support Python3.7 yet.
 
 
 Install Snips NLU

docs/source/languages.rst

@@ -18,6 +18,8 @@ their isocode:
 +------------+------------+
 | French     | fr         |
 +------------+------------+
+| Italian    | it         |
++------------+------------+
 | Japanese   | ja         |
 +------------+------------+
 | Korean     | ko         |

docs/source/tutorial.rst

@@ -150,6 +150,7 @@ Now, the ``"entities"`` part of the generated json looks like that:
               "value": "garden"
             }
           ],
+          "parser_threshold": 1.0,
           "use_synonyms": true
         },
         "snips/temperature": {}
@@ -199,6 +200,7 @@ and that we want our assistant to cover. Additionally, we add some
               "value": "garden"
             }
           ],
+          "parser_threshold": 1.0,
           "use_synonyms": true
         },
         "snips/temperature": {}