feersum_nlu 2.0.22.dev0

FeersumNLU API

FeersumNLU API Wrappers
***********************

.. image:: https://badge.fury.io/py/feersum_nlu.svg
:target: https://badge.fury.io/py/feersum_nlu

This git repo hosts Python and other language wrappers for the FeersumNLU RESTful HTTP API. FeersumNLU is the natural
language understanding component of Feersum Engine `<https://www.feersum.io>`_ .

The HTTP API is designed such that a user may apply multi-lingual Natural Language Understanding (NLU) to their application
domain without requiring a deep understanding of NLU theory. The examples in this repo demonstrate commonly required NLU
functions and how to access them. There are also some cURL examples of direct HTTP access in the examples_curl folder.

These language wrappers and examples are for version 2.0.22 of the HTTP API. The language wrappers are auto-generated
from a Swagger spec of the API available at `<https://nlu.playground.feersum.io:443/nlu/v2/swagger.json>`_


(Note: This repo is currently being updated with more examples)

Overview
********

FeersumNLU provides natural language understanding solutions for chat-based interactions, where messages from
the end-user may be long or very short. Our product is also designed to be language-agnostic, which
means it can be scaled to work with any language, even in markets where large bodies of labelled
data do not exist. Our Natural Language Understanding models are developed locally, and can be
modified to provide solutions for specialised industries like finance or health.


Features
********

FeersumNLU makes use of open-source building blocks like NLTK, sklearn, PyTorch and Duckling, as
well as algorithms we've developed in-house. We build on all elements to support a growing list
of local and international languages.

Current features include Natural Language FAQ's, detection of the user's intent and sentiment,
information extraction, entity extraction, and text-based language identification.


Installing
**********

Please have a look at the examples in the repo. It is also recommended that you create a Python virtual environment
and then follow one of the install options below to run the examples. The examples were tested with Python 3.5 and 3.6.

Creating a Python Virtual Environment
=====================================

To get started with the Python wrappers install Python 3.5 (or 3.6) and pip. Then do:

.. code-block:: sh

$ virtualenv -p /usr/local/bin/python3.5 .pyenv
$ source .pyenv/bin/activate
$ pip install pip-tools
$ pip install appdirs

If you don't have virtualenv installed first run:

.. code-block:: sh

$ pip install virtualenv
$ sudo /usr/bin/easy_install virtualenv


Install Option 1 - Using make
=============================
Clone the repo and then to install the dependencies required to run the module's examples run:

.. code-block:: sh

$ make requirements
$ make deps


Install Option 2 - Using setuptools
===================================

Alternatively clone the repo and then install the feersum_nlu wrapper module into your Python environment using setuptools:

.. code-block:: sh

$ make requirements
$ make deps
$ python setup.py install

The benefit of installing the feersum_nlu module into you Python environment is that you can more easily use it in your own projects.


Install Option 3 - Using pip
============================

The feersum_nlu wrapper module is also available from the Python Package Index `<https://pypi.python.org/pypi/feersum_nlu>`_. To install it using pip run:

.. code-block:: sh

$ pip install feersum_nlu

The benefit of installing the feersum_nlu module into you Python environment is that you can more easily use it in your own projects.


Running the Examples
====================
If you use an IDE like PyCharm you can simply open the folder you cloned the source to (e.g. feersum-nlu-api-wrappers) with the IDE.

Or to start executing example notebooks install Jupyter with

.. code-block:: sh

$ pip install jupyter

and then run:

.. code-block:: sh

$ jupyter notebook

The notebooks are all in the example_notebooks folder.

Alternatively run the example python scripts in the examples folder from the terminal e.g.:

.. code-block:: sh

$ PYTHONPATH=. python examples/faq_matcher.py

Remember to set your API token in the example scripts and notebooks.


The FeersumNLU Playground Server
********************************

A FeersumNLU playground instance of the RESTful web service is hosted at nlu.playground.feersum.io:443/nlu/v2
You may use this URL to run the examples given in this repo.

You'll need an authentication token to access the service, so email us at [e-mail] and
we'll send you a token to use. Some autogenerated API documentation is available at
`<https://nlu.playground.feersum.io:443/nlu/v2/ui/>`_

Note that this is just a playground instance. Please contact us at [e-mail] for a variety of hosting options including
containerised solutions.


Making your Own API Wrapper
***************************

This Python language wrapper was generated using the swagger-codegen toolchain. The full process is in the makefile target
called `update_spec`. To update the Python wrapper run:

.. code-block:: sh

$ make update_spec

To generate an API wrapper for another language modify the command to use a different generator. See
`<https://github.com/swagger-api/swagger-codegen#to-generate-a-sample-client-library>`_ for some more details.

To generate a PHP wrapper, for example, change the generate command to something like:

.. code-block:: sh

$ swagger-codegen generate -i swagger/swagger.yaml -l php -c swagger/swagger_codegen-python_config.json -o swagger/build_php
Changelog
*********

Version 2.0.22
==============
Name changes to make the Python API more consistent and friendlier towards code generation:
- text_clsfr_create_details renamed to text_classifier_create_details
- text_clsfr_instance_detail renamed to text_classifier_instance_detail
- wm_create_details renamed to word_manifold_create_details
- wm_instance_detail renamed to word_manifold_instance_detail
- create_details renamed to intent_classifier_create_details for intent classifier
- instance_detail renamed to intent_classifier_instance_detail for intent classifier
- create_details renamed to faq_matcher_create_details for faq matcher
- instance_detail renamed to faq_matcher_instance_detail for faq matcher
- regex_ent_create_details renamed to regex_entity_extractor_create_details
- regex_instance_detail renamed to regex_entity_extractor_instance_detail
- person_name_ent_create_details renamed to person_name_entity_extractor_create_details
- person_name_instance_detail renamed to person_name_entity_extractor_instance_detail
- duckling_ent_create_details renamed to duckling_entity_extractor_create_details
- duckling_instance_detail renamed to duckling_entity_extractor_instance_detail
- sim_word_ent_create_details renamed to sim_word_entity_extractor_create_details
- sim_word_instance_detail renamed to sim_word_entity_extractor_instance_detail
- lr4_language_recogniser renamed to language_recogniser
- lr4_create_details renamed to language_recogniser_create_details
- lr4_instance_detail renamed to language_recogniser_instance_detail

Version 2.0.21
==============
- Examples of async training.

- Examples of online training.

Version 2.0.20
==============
- Changed name of similar_entity_extractor to sim_word_entity_extractor.

- Removed the api hit counts from the dashboard.

- Added a trashed flag to each model in the dashboard.

- Removed the immediate_mode arguments in the train operations.

- The spec and Python API wrapper have been updated to rather return lists of python objects as opposed to lists of json objects.

- Changes to LR4 to have a load from store that works like all of the other names.


Version 2.0.18
==============
- Added a 'long_name' attribute to all models. May be used as a 'pretty' formatted model name while the existing model
name is really a slug used in urls, etc.

- Addition of params end point to all models. Used to update and get model attributes like desc, long_name and threshold.

- Updated LID LR4 to load from store.


Version 2.0.16
==============

- Added model delete endpoints.

- Expose experimental person name entity extractor on the http API.

- Exposed the reference_time attribute to the Duckling entity extractor.

- Moved the examples' and tests' auth token and host config to a central location in the __init.py__

- Added this changelog.