Surface¶

class mangrove_surface.SurfaceClient(url=None, token=None, username=None, password=None)¶

Instanciate Mangrove.ai python SDK with instance url and identity access

Parameters:

url – (optional) url of the Mangrove.ai instance (by default environment variable SURFACE_URL is used)
token – (optional) access token used to secure connection (by default, if username/password are given then those are used to generate an access token; otherwise environment variable SURFACE_TOKEN is used)
username – (optional) username used (with password) to sign in (by default, a token is expected)
password – (optional) password used to (with username) sign in (by default, a token is expected)

Note

Surface URL or access token can be explicitly provided as parameters or implicitly using environment variables (SURFACE_URL and SURFACE_TOKEN)

Raises:	IOError – if the endpoint doesn’t answer correctly AttributeError – if url, username-password or token are not provided

Load Surface python SDK:

>>> from mangrove_surface import SurfaceClient

Instanciate with url and token are environment variables:

>>> client = SurfaceClient()

Or with url as environment variable and an explicit token:

>>> client = SurfaceClient(token='eyJ0eXAiOiJKV1QiLCJhbGciOiJ...')

Or with explicit url and token:

>>> client = SurfaceClient(
...     url='http://my.surface/api',
...     token='eyJ0eXAiOiJKV1QiLCJhbGciOiJ...'
... )

create_project(name, schema, description='', schema_test=None, tags=[], default_classifier=True, force=False)¶

Create a new project

Parameters:

name – project name
description – (optional) project description

schema –

(optional) a data schema which contains train data sets and relations, like:

{
    "tags": ["dataset", "tag"],
    "datasets": [
        {
            "name": "Dataset Name",
            "filepath": "/path/to/dataset.csv",
            "tags": ["optional", "tags"],
            "central": True | False,
            "keys: ["index"], # optional if there is only
                              # one dataset
            "separator": ",", # could be `|`, `,`, `;` or `     `
        }, ...
    ],
    "outcome": "FIELD TARGETED",
    "outcome_modality": "main value targeted"
}

filepath is an absolute filepath or it could be a S3 uri, like:

{
    "type": "s3",
    "bucket": "mang-model-producer-samples",
    "key": "CAR_INSURANCE/CHAT_SESSION_CONTENT_TRAIN.csv"
}

tags – (optional) list of project tags
schema_test – (optional) a data schema which contains test data sets and relations, like schema
default_classifier – (default: True) indicates if a default classifier it provided at the project creation
force – (default: False) indicates if a project with the same name exists then it is replaced or not

project(name)¶

Return project named name

Parameters:	name – the name of the wished project

projects()¶: List all projects

Surface admin¶

class SurfaceClient._Admin¶

Administration methods:

create_token(token_name, expiration_date)¶

Create a new token

Parameters:	token_name – date (expiration) – should be a datetime.datetime object

>>> from datetime import datetime
>>> expire = datetime(2020, 1, 1)
>>> mang.admin.create_token('token_jbp', expire)
{
    'created_at': '2018-03-29T09:45:06.067Z',
    'expires_at': 1577833200,
    'id': '40a6a8b6-65b1-465e-b6c7-6c3021c30952',
    'name': 'token_jbp',
    'token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI4MjI0OTg4NC05M2UwLTQwN2MtYmQ3OS02NTllMWE4MzQ2NTUiLCJzY3AiOiJ1c2VyIiwiaWF0IjoxNTAzOTk5OTA2LCJleHAiOjE1Nzc4MzMyMDAsImp0aSI6IjhlN2I5YmM1LTAxODItNGRmYi1hMzM0LTAxYzQ4ODc5OTk1NCIsInR5cGUiOiJhcHBsaWNhdGlvbiJ9.looosUk2TuXOVXREmAvPoVnOx0kLaSLOT4TlOMK_yTA',
    'updated_at': '2018-03-29T09:45:06.067Z'
}

create_user(username, password)¶

Create a user

Parameters:	username – new username password – it password

delete_users(*usernames)¶

Delete users

Parameters:	*usernames – arbitrary number of usernames

>>> mang.admin.delete_users("Alice", "Bob", "Oscar")

license_information(request_code=False)¶

Retrieve license information

Parameters:	request_code – (default False) if True it adds the request code to obtain a new license (only for byol)

>>> mang.admin.license_information()
[{
    'expires_at': '2018-08-29 00:00:00 UTC',
    'service_level': 'full',
    'system_information': None,
    'updated_at': '2018-03-29 09:49:34 UTC'
}]

>>> mang.admin.license_information(request_code=True)
[{
    'expires_at': '2018-08-29 00:00:00 UTC',
    'service_level': 'full',
    'system_information': {
        'request_code': 'kzho-isiA-8dwy-gZyq-gFNb-EC5l-od7s-JBai-RcaF-2hMb-cirj-52rS-P4M3-2sRg-fuZa-/S5W-FkRn-RDSo-srVa-0xlX-q7KO-NkMY-380Y-dmW4-JfHG-Q01x-so3N-NhdO-MoMj-Xw+B-bUdb-Q7VI-K+Hy-gSMF-kVpD-kCkO-v3Ay-a2/f-To9v-Lnxw-3EdE-FEPa-yVMI-x/U4-EsUV-T1eq-LQsM-C88E-yPOS-RtVp-vDtD-zwEn-PAS7-/pSl-MGJ+-jnUq-JllG-uxO+-seDZ-6X+v-rXBI-zHUx-go3p-K2ZO'
    },
    'updated_at': '2018-03-29 09:49:34 UTC'
}]

Raises:	MangroveError – if the license has expired

{
    "status": 402,
    "status_text": "Payment Required",
    "errors": [
        {
            "code": "LICENSE-402-002",
            "type": "license",
            "metadata": {
                "reason": "License not found",
                "request_code": "P6jC-ns9H-X5ph-KZVg-finF-ttgv-2Jtl-ygPn-Ie/z-VUBc-hYYz-GeLT-yTb4-UrkS-tr/s-w3uf-lzlG-Av34-3fnx-0gl2-8SnL-jaQt-0BJ+-bhKU-zgWl-tu6j-kM4r-i84u-s2Qo-SR4P-JyEH-AIRh-psnw-d0zd-R+Nf-zrl+-8hWy-l3Db-HeD9-6DY7-gwlO-1Zjp-Opvu-pp5I-mxWQ-qDtS-WWTo-xjlK-hE9q-sukL-YEeK-OPWz-aaJl-0ZzB-0sN2-6Gqz-soPd-lEXR-USDl-vDzJ-JltE-RWX+-HfZs-2Njd",
                "type": "private",
                "autofetch": False
            }
        }
    ]
}

new_license(license_code)¶

Update the licence

Parameters:	license_code – string provided by the Mangrove team

>>> mang.admin.new_license('fxbE-D9pK-h0t7-x+5r-B3G7-bY+x-AG6x-dzYW-tccq-HAtl-Bkzb-JPVw-jsFd-zcvN-Nr15-vkIZ-ZK4J-yafW-niK9-RbaV-FGS9-oks5-zsLJ-yweZ-fg3K-SAeT-jDWP-pDnj-bJ8P-ZjKh-Tskp-I/1A-Ymow-fV6s-fvXK-dliu-cHCY-1Orf-pBY0-VDgm-IBaP-3Dz3-CiYS-4MVR-hQsO-KNfu-WK7d-7/6w-CTNW-A0HA-9rnB-im62-evcd-j7HS-KnnL-K/aD-UNlU-5vO5-K9g=')
{
    'expires_at': '2018-03-30 00:00:00 UTC',
    'service_level': 'full',
    'system_information': None,
    'updated_at': '2018-03-31 11:47:54 UTC'
}

Raises:	HTTPError – if you provide a wrong license

(Please use GUI)

tokens()¶

List all tokens

>>> mang.admin.tokens()
[{
    'created_at': '2018-03-29T09:45:06.067Z',
    'expires_at': 1577833200,
    'id': '40a6a8b6-65b1-465e-b6c7-6c3021c30952',
    'name': 'token_jbp',
    'token': 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI4MjI0OTg4NC05M2UwLTQwN2MtYmQ3OS02NTllMWE4MzQ2NTUiLCJzY3AiOiJ1c2VyIiwiaWF0IjoxNTAzOTk5OTA2LCJleHAiOjE1Nzc4MzMyMDAsImp0aSI6IjhlN2I5YmM1LTAxODItNGRmYi1hMzM0LTAxYzQ4ODc5OTk1NCIsInR5cGUiOiJhcHBsaWNhdGlvbiJ9.looosUk2TuXOVXREmAvPoVnOx0kLaSLOT4TlOMK_yTA',
    'updated_at': '2018-03-29T09:45:06.067Z'
}]

users()¶

Retrieve all users

>>> mang.admin.users()
[admin(admin), Toto, Gillou]

versions()¶

Version information

>>> mang.admin.versions()
[
    {
        'name': 'atlas',
        'version': '0.0.1-alpha.1'
    }, {
        'name': 'license_authority',
        'version': u'1.3.2-rc1'
    }, {
        'name': 'dmgr',
        'version': '0.0.1'
    }, {
        'name': 'modeler',
        'version': '0.0.1-alpha.1'
    }, {
        'name': 'exporter',
        'version': '0.0.1'
    }, {
        'name': 'mang_sdk',
        'version': '1.2.1-30-ge792bea-dirty'
    }
]