Python bindings for the Luminoso client API

This package contains Python code for interacting with a Luminoso text processing server through its REST API.

Important note: API version and client version

This page covers the client that connects to the v4 API; this client is the object named luminoso_api.LuminosoClient, which is an alias for luminoso_api.v4_client.LuminosoClient.

However, the v5 API is now available, as is a client for using it. That client can be accessed as luminoso_api.V5LuminosoClient (or directly at luminoso_api.v5_client.LuminosoClient). Documentation for the new client can be found here. When the sunset period for the v4 API ends on January 3, 2019, we will remove the v4 version of the client, and luminoso_api.LuminosoClient will become an alias for the v5 client.

Using this client

In this code, instead of having to authenticate each request separately, you make a "session" object that keeps track of your login information, and call methods on it that will be properly authenticated.

Installation

This client API is designed to be used with Python 2.6, 2.7, 3.3, or 3.4.

You can download and install it using a Python package manager:

pip install luminoso-api

or

easy_install luminoso-api

Or you can download this repository and install it the usual way:

python setup.py install

If you are installing into the main Python environment on a Mac or Unix system, you will probably need to prefix those commands with sudo and enter your password, as in sudo python setup.py install.

Getting started

You interact with the API using a LuminosoClient object, which sends HTTP requests to URLs starting with a given path, and keeps track of your authentication information.

You can connect using a username and password:

>>> from luminoso_api import LuminosoClient
>>> proj = LuminosoClient.connect('/projects/account_id/my_project_id',
                                  username='my_username')
Password for my_username: [here you enter your password]
>>> proj.get('terms')
[lots of terms and vectors here]

Or you can connect using an existing API token:

from luminoso_api import LuminosoClient
proj = LuminosoClient.connect('/projects/account_id/my_project_id',
                              token='my-api-token-here')

You can even save your API token to a file on your computer and load it automatically, so that you don't have to specify any credentials:

from luminoso_api import LuminosoClient
client = LuminosoClient.connect(token='my-api-token-here')
# This will save a non-expiring token, regardless of whether you are currently
# using that token or some other token.
client.save_token()
# Now you can exit Python, restart your computer, etc., and your token will
# still be saved when you come back.
proj = LuminosoClient.connect('/projects/account_id/my_project_id')

When you connect without specifying a URL, the URL will be set to your default account_id under /projects:

>>> from luminoso_api import LuminosoClient
>>> projects = LuminosoClient.connect(username='testuser')
Password: ...
>>> print(projects)
<LuminosoClient for https://analytics.luminoso.com/api/v4/projects/lumi-test/>

HTTP methods

The URLs you can communicate with are documented at https://analytics.luminoso.com/api/v4. That documentation is the authoritative source for what you can do with the API, and this Python code is just here to help you do it.

A LuminosoClient object has methods such as .get, .post, and .put, which correspond to the corresponding HTTP methods that the API uses. For example, .get is used for retrieving information without changing anything, .post is generally used for creating new things or taking actions, and .put is generally used for updating information.

Examples

Most of the time, you'll want your LuminosoClient to refer to a particular project (also known as a database), but one case where you don't is to get a list of projects in the first place:

from luminoso_api import LuminosoClient
client = LuminosoClient.connect(username='jane', password=MY_SECRET_PASSWORD)
# this points to the /projects/janeaccount/ endpoint by default,
# where janeaccount is the account_id of jane's default account
project_info_list = client.get()
print(project_info_list)

An example of working with a project, including the upload method that we provide to make it convenient to upload documents in the right format:

from luminoso_api import LuminosoClient

projects = LuminosoClient.connect(username='jane')

# Create a new project by POSTing its name
project_id = projects.post(name='testproject')['project_id']

# use that project from here on
project = projects.change_path(project_id)

docs = [{'title': 'First example', 'text': 'This is an example document.'},
        {'title': 'Second example', 'text': 'Examples are a great source of inspiration.'},
        {'title': 'Third example', 'text': 'Great things come in threes.'}]
project.upload('docs', docs)
job_id = project.post('docs/recalculate')

This starts an asynchronous job, returning us its ID number. We can use wait_for to block until it's ready:

project.wait_for(job_id)

When the project is ready:

response = project.get('terms')
terms = [(term['text'], term['score']) for term in response]
print(terms)

Vectors

The semantics of terms are represented by "vector" objects, which this API will return as inscrutable base64-encoded strings like this:

'WAB6AJG6kL_6D_6yAHE__R9kSAE8BlgKMo_80y8cCOCCSN-9oAQcABP_TMAFhAmMCUA'

If you want to look inside these vectors and compare them to each other, download our library called pack64, available as pip install pack64. It will turn these into NumPy vectors, so it requires NumPy.

>>> from pack64 import unpack64
>>> unpack64('WAB6AJG6kL_6D_6y')
array([ 0.00046539,  0.00222015, -0.08491898, -0.0014534 , -0.00127411], dtype=float32)

Uploading from the command line

Instead of sending your documents as a list of Python dictionaries, you can upload a file containing documents in JSON format.

The file should contain one JSON object per line (we suggest using the extension .jsons to indicate that the entire file is not a single JSON object). It will look like this:

{"title": "First example", "text": "This is an example document."}
{"title": "Second example", "text": "Examples are a great source of inspiration."}
{"title": "Third example", "text": "Great things come in threes."}

It can also be a CSV file (which can be created by Excel, for example) with columns named title and text:

title   text
First example   This is an example document.
Second example  Examples are a great source of inspiration.
Third example   Great things come in threes.

This library installs a script called lumi-upload for uploading files in one of these formats. For example, you would type at the command line:

lumi-upload example.jsons ACCOUNT_NAME example_project_name