Client/Server Protocol

This document describes the Personis access, ask and tell calls in terms of the Python method calls.

access:

personis.client.Access(uri = personis_uri, credentials = cred, http=http)

The POST URL is then /access and the body is (for example):

{"password": "", "modelname": "bob", "user": "bob", "version": "11.2"}

The password and user are now vestigal. These are taken care of at the http level. A user may still have multiple models in a server, so modelname can be used. The default is the main user model.

the return data is:

{"result": "ok", "val": true}     -- on success
{"result": "fail", "val": false}     -- on failure
I might change this to include a diagnostic string as the value of val.

tell:

def tell(modelname=string, version="11.2",
        context=list-of-strings, componentid=string, evidence=dict)

The URL is /tell

Body example:

{"modelname": "bob",
"user": "bob",
"password": "",
"version": "11.2",
"evidence": {"comment": null, "evidence_type": "explicit", "value": "Bob",
                "objectType": "Evidence", "source": "demoex2", "flags": [],
                "time": null, "exp_time": 0},
"context": ["Personal"],
"componentid": "firstname"}

Note that the evidence dictionary should be extensible, ie not just the fields shown. Keys are strings, values can be strings/None/integer/list-of-strings

The return data is:

{"result": "ok", "val": true}     -- on success
{"result": "fail", "val": false}     -- on failure
I might change this to include a diagnostic string as the value of val.[a]

ask:

def ask(modelname=string, version="11.2",
        context=list-of-strings,
        resolve=dict,
        showcontexts=true-or-false,[b]
        view=list-of-(string-or-list-of-string) )

The resolver dictionary is extensible, keys and values are strings, view is a list of strings or (list of strings)

The URL is /ask

Body example:

{"modelname": "bob",
"user": "bob",
"password": "",
"version": "11.2",
"context": ["Preferences", "Music", "Jazz", "Artists"],
"showcontexts": null,
"resolver": {"evidence_filter": "all"},
"view": ["Miles_Davis", ["Personal", "firstname"]]}

The return data is a dictionary containing a result and val entries like the Access function. The value for “val” is a list of dictionaries, one per component value being returned.

example:

{"result": "ok", "val":
 [        {"Description": "First name",
        "component_type": "attribute",
        "evidencelist": null,
        "value_list": null,
        "value": "Bob",
        "value_type": "string",
        "goals": [],
        "resolver": null,
        "Identifier": "firstname",
        "objectType": "Component"},
        {"Description": "Last name",
        "component_type": "attribute",
        "evidencelist": null,
        "value_list": null,
        "value": "Kummerfeld",
        "value_type": "string",
        "goals": [],
        "resolver": null,
        "Identifier": "lastname",
        "objectType": "Component"}
 ]
}

The POST requests should be over HTTPS. Also, a future stage of development will involve more crypto with signed, encrypted JSON.