See personis Package for API documentation.
Models can be accessed either locally in the filesystem, or via a server.
Local access is via the base module.
Basic accretion operation - tell some evidence
The following example shows the use of base to tell a piece of evidence containing a name string to a component in the model. The source of the evidence is “contactapp” which will have been given access to the model by the owner.
import base
# access the model in the filesystem
# model name is "alice", model is stored in directory "Models"
um = base.Access(model="alice", modeldir='Models', user='contactapp')
# create a piece of evidence with Alice as value
ev = Personis_base.Evidence(evidence_type="explicit", value="Alice")
# tell this as user alice's first name into component "firstname", context "Personal"
um.tell(context=["Personal"], componentid="firstname", evidence=ev)
Basic resolution operation - ask for a value
This example *ask*s for the value of a component using the default resolver that uses the most recent piece of evidence.
import base
um = base.Access(model="alice", modeldir='Models', user='contactapp')
# now ask for the value of the component using the default resolver and the last piece of evidence
reslist = um.ask(context=["Personal"], view=["firstname"], resolver=dict(evidence_filter="last1"))
A view is just a list of components. The list can be explicit in the ask request or we can give a view a name and store it in the model.
For example:
# now ask for the value of two components using a view
reslist = um.ask(context=["Personal"], view=["firstname", "lastname"], resolver=dict(evidence_filter="last1"))
We can make a view using a view object and the mkview method. For example:
import base
um = base.Access(model="alice", modeldir='Models', user='contactapp')
vobj = Personis_base.View(Identifier="fullname", component_list=["firstname", "lastname"])
um.mkview(context=["Personal"], viewobj=vobj)
reslist= um.ask(context=["Personal"], view = 'fullname', resolver={'evidence_filter':"all"})
The values are returned by an ask request in a list of component objects, one for eachc component value requested. The component objects have the attributes described in the documentation above but this includes a value attribute which is the resolved value for the component. Eg:
reslist = um.ask(context=["Personal"], view=["firstname"], resolver=dict(evidence_filter="last1"))
print "Firstname:", reslist[0].value
Creating new contexts and components
The mkcontext and mkcomponent methods, along with the Component and Context objects, are used to build new elements in the model. Here is an example of creating and then deleting a context:
# assume we have accessed the model
print "creating context 'Deltest' in context 'Personal'"
cobj = base.Context(Identifier="Deltest", Description="testing context deletion")
# now make the new context
um.mkcontext(context=["Personal"], contextobj=cobj)
print "now delete it"
um.delcontext(context=["Personal", "Deltest"]):
and here is an example of creating and then deleting a component:
cobj = base.Component(Identifier="age", component_type="attribute", Description="age", goals=[['Personal', 'Health', 'weight']], value_type="number")
um.mkcomponent(context=["Personal"], componentobj=cobj)
# tell some evidence to the new component
ev = Personis_base.Evidence(evidence_type="explicit", value=17)
um.tell(context=["Personal"], componentid='age', evidence=ev)
reslist = um.ask(context=["Personal"], view=['age'], resolver={'evidence_filter':"all"})
print "Age:", reslist[0].value
# delete the component
resd = um.delcomponent(context=["Personal"], componentid = "age")
Navigating the Model
If you want to discover what contexts are present in the model there is a variant on the ask method that allows you to get a list of all the contexts, components, views and subscriptions that are contained in a given context. Just add the parameter “showcontexts=True” to the ask call. Using this call you can start at the root context and walk the tree of contexts discovering the full contents of the model. Eg:
print "Show the root context"
info = um.ask(context=[""], showcontexts=True)
The return value is a tuple containing (componentlist, contextlist, viewlist, sublist), where each part of the tuple is a list of objects.
Subscriptions: rules for action
A feature of Personis is the ability to add a rule to a component that is examined when ever a tell operation is performed on the component. The rule typically examines a resolved value of the component, matching against a pattern. If the pattern is matched an action is initiated. The action can be a tell operation to tell some evidence to a component, or a notify operation that will construct a URL and fetch it, thus initiating some action at an external web site. Rules can be deleted using the delete_sub method.
Note that you need to use active instead of base as that is where the subscription methods are found.
For example:
import base
import active
um = Personis_a.Access(model="alice", modeldir='Models', user='contactapp')
# subscription rule that will match firstname against a wildcard pattern (regular expression):
sub = """
<default!./Personal/firstname> ~ '.*' :
NOTIFY 'http://www.myweb.me/~alice/action.cgi?' 'firstname=' <./Personal/firstname>
"""
# a token identifying the rule is returned
subtoken = um.subscribe(context=["Personal"], view=['firstname'], subscription={'user':'alice', 'password':'secret', 'statement':sub})
ev = Personis_base.Evidence(evidence_type="explicit", value="Alice")
# do a tell. This should cause the action.cgi script to be invoked with the firstame
um.tell(context=["Personal"], componentid='firstname', evidence=ev)
# delete the rule
um.delete_sub(context=["Personal"], componentid='lastname', subname=subtoken)
Import and Export of Models
Models can be imported and exported in JSON (JavaScript Object Notation) form using the export_model and import_model methods:
import base
import active
um = active.Access(model="alice", modeldir='Models', user='contactapp')
# export a model sub tree to JSON
# note that all evidence will also be exported.
modeljson = um.export_model(["Personal"], evidence_filter="all")
print modeljson
# import the same model tree but into a different context.
um.import_model(context=["Temp"], partial_model=modeljson)