D2.3 - Computational models and validation by Smart Society Project

SmartSociety Hybrid and Diversity-Aware Collective Adaptive Systems When People Meet Machines to Build a Smarter Society

Grant Agreement No. 600584

Deliverable D2.3 Working Package WP2

Computational models and validation Dissemination Level 1 (Confidentiality): Delivery Date in Annex I: Actual Delivery Date Status2 Total Number of pages: Keywords:

PU 30/06/2015 Jun 30, 2015 F 57 SmartShare Application, Implementation

PU: Public; RE: Restricted to Group; PP: Restricted to Programme; CO: Consortium Confidential as specified in the Grant Agreeement 2 F: Final; D: Draft; RD: Revised Draft

c SmartSociety Consortium 2013-2017

2 of 57

Deliverable D2.3

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Disclaimer This document contains material, which is the copyright of SmartSociety Consortium parties, and no copying or distributing, in any form or by any means, is allowed without the prior written agreement of the owner of the property rights. The commercial use of any information contained in this document may require a license from the proprietor of that information. Neither the SmartSociety Consortium as a whole, nor a certain party of the SmartSocietys Consortium warrant that the information contained in this document is suitable for use, nor that the use of the information is free from risk, and accepts no liability for loss or damage su↵ered by any person using this information. This document reflects only the authors’ view. The European Community is not liable for any use that may be made of the information contained herein.

Full project title:

Project Acronym: Grant Agreement Number: Number and title of workpackage: Document title: Work-package leader: Deliverable owner: Quality Assessor: c SmartSociety Consortium 2013-2017

SmartSociety: Hybrid and Diversity-Aware Collective Adaptive Systems: When People Meet Machines to Build a Smarter Society SmartSociety 600854 WP2 Modelling Framework Computational models and validation Luc Moreau, SOTON Michael Rovatsos, UEDIN Simone Fischer-H¨ ubner, KU 3 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

List of Contributors Partner Acronym SOTON SOTON UEDIN

4 of 57

Contributor Luc Moreau Heather S. Packer Dimitris Diochnos

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

Executive Summary The role of WP2 in the SmartSociety project is to develop a computational modelling framework for HDA-CASs, mainly by delivering data and processing models that enable transparency and accountability in large-scale systems and are adequate for human use. To this end, in our work so far we have developed • methods to describe HDA-CAS entities and their interactions in a formal ontology, • end-to-end provenance tracking capabilities that enable accounting for data generated by our systems,

• techniques that allow for scaling up provenance data storage, and • summarisation and explanation methods that will facilitate human inspection of complex systems operation.

These techniques provide the sca↵olding for an overall transparency and accountability framework that will enable the trustability of future applications based on SmartSociety technology. This deliverable describes a software component built as part of this work that provides the basis for subsequent validation experiments. The construction of this software has followed the requirements of the methods described above, and provides us with a fully functional suite of services for provenance and reputation management in HDA-CASs. Moreover, it is in line with more formal modelling e↵orts that we have engaged in to develop a SmartSociety-wide data and process vocabulary, and where we have provided precise semantics for the architectural components of social orchestration systems, through which the WP2-relevant data is obtained. The core element of this deliverable is the implemented software and its integration with the SmartShare system, which we survey in this document, and for which we provide extensive documentation in the attached appendices as well as in software documentation available online. A published research paper that provides the formal semantics of the overall architecture is also included as an appendix. The document also discusses the envisioned validation methodology that will guide experiments with real data. These are expected to be performed after the release of this deliverable.

c SmartSociety Consortium 2013-2017

5 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Table of Contents 1 Introduction

2 Summary

2.1

ProvBindings Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.2

Reputation Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.3

Integration with the orchestration system . . . . . . . . . . . . . . . . . . .

3 Validation methodology

4 Conclusion

A Provenance and Reputation Documentation

A.1 ProvBindings API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 A.1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 A.1.2 Issue Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 A.1.3 API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 A.2 Reputation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 A.2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 A.2.2 Issue Tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 A.2.3 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 B Orchestration API documentation

B.1 Application Orchestration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 B.1.1 Task Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 B.1.2 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 B.1.3 Task Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 B.2 Composition Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 B.3 Negotiation Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 B.4 Deletion Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 B.5 Execution Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 B.6 Further Remarks and Functionality . . . . . . . . . . . . . . . . . . . . . . . 38 B.6.1 Administration and Monitoring . . . . . . . . . . . . . . . . . . . . . 38 6 of 57

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

C Published paper: Agent Protocols for Social Computation

c SmartSociety Consortium 2013-2017

7 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Introduction

This document describes the software component implemented to validate the models developed in WP2, where our focus is to detail the software not theory or concepts which are described in the Static social orchestration: implementation and evaluation, and Provenance, Trust, Reputation & Big Data deliverables (D6.2 and D2.2). The primary purpose of the work done on these models was twofold: On the one hand, in terms of specific technical contributions from WP2, existing methods for provenance, trust, and reputation modelling had to be adapted to the nature of HDA-CASs, in particular with regard to issues of scale and accounting for the hybridity of these systems. This has been accomplished by developing provenance templates and explanation methods as well as embedding provenance and reputation mechanisms in SmartSociety prototypes. On the other hand, the formal models developed in WP2 and presented in milestone MS4 serve as a unifying framework for grounding central notions in HDA-CASs computationally by providing a formal vocabulary and semantics for the main elements of SmartSociety applications. With this respect, the software component described in this document is inextricably linked to other parts of the SmartSociety prototype developed for validation of the transparency and accountability techniques developed in WP2. Specifically, the services provided by WP2 are fully integrated with the ridesharing prototype SmartShare developed in collaboration with WPs 4, 5, and 6. Our description of the software is mainly provided in terms of API documentation and examples provided in the appendices. In the main body of the text, we restrict ourselves to a brief overview in Section 2, followed by an outline of the validation methodology we intend to apply over the following months using the implemented components (Section 3), and a brief conclusion in Section 4.

Summary

The following software components, their interaction and data flow which are detailed in this Section are described in the SmartShare: A Smart Society Application document.

2.1

ProvBindings Service

The ProvBindings service is a proxy for storing provenance template and bindings documents in the ProvStore. Templates describe patterns in provenance, and bindings define 8 of 57

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

the values for the variables defined in the templates. The service manages the associations between templates and bindings, and expands and stores templates and their bindings in the ProvStore. The management of these associations is not supported by ProvStore. The serviceâ&#x20AC;&#x2122;s functionality is exposed via a REST API (the full documentation is in Appendix A.1), the service organises its resources by application and supports the submission of both templates and bindings, and the retrieval of templates associated with an application. It is currently being used by three ride share components, the: UI, Orchestrator and Reputation service, and will be used by all SmartSociety components that record provenance.

2.2

Reputation Service

The reputation service provides storage for and access to feedback and reputation reports, for SmartSociety applications. It is described in the Provenance, Trust, Reputation & Big Data deliverable (D2.2) and the Interim report on transparency and accountability (MS3). The reputationâ&#x20AC;&#x2122;s functionality is exposed via a REST API (the full documentation is in Appendix A.2), its resources are organised by application and it supports the submission of feedback reports about a subject or collective of subjects, from an author. It is agnostic to the HDA-CASs applications. This service is designed to be accountable for 1. which feedback report was related to which event, 2. which feedback reports were used to generate reputation and opinion reports, 3. who accessed feedback, reputation, and opinion reports, and 4. the generation of reputation by storing feedback and reputation reports it supports items 1 and 2, and by submitting provenance bindings about who accessed its resources and how it generated reputation it supports items 3 and 4. In more detail, the reputation service submits bindings to record when a resource in the API is created (feedback and reputation reports), and accessed via the API.

2.3

Integration with the orchestration system

In the Static social orchestration: implementation and evaluation (D6.2 in Sections 2.5 and 3) deliverable, we described how provenance is integrated in the design of our orchestration c SmartSociety Consortium 2013-2017

9 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

engine by including it in every workflow managed by the orchestrator. We briefly repeat the main ideas here, using the example of a workflow managed by the orchestration manager shown in figure 1. profile " process-A # prov # profile

process-B

Figure 1: Workflow example In this example, the actual workflow consists of a sequence of platform jobs process-A and process-B. By default, as shown above for process-A, completion of each of these jobs triggers a process prov to record provenance information using the ProvBindings service described above (before triggering a process profile that records profiling information, e.g. time/memory usage). The orchestrator provides basic support for any such jobs and workflows to be provenanceenabled, by maintaining unique IDs for all jobs, tracking the child-parent relationships between them and recording inputs and outputs to each job, and recording times for each individual operation when processing platform jobs. All this functionality is realised through a fully RESTful design where linked documents that contain data generated by the system are connected with each other through the workflows that create and process them. In Appendix C, we have included a published paper which completes the description of the formal framework first developed in milestone MS4. The semantics of communication presented there underpins the data-oriented design of our orchestration engine, and shows how the links between documents are created by interactions of users with the platform. These correspond to the provenance graphs created by the ProvBindings service. Importantly, the formal framework presented in this paper generalises from the current SmartShare implementation by describing how general distributed coordination protocols can be converted to a fully data-centric architecture that enables straightforward provenance tracking. In terms of concrete implementation, these principles have been applied to generate provenance information for all core workflows used in the SmartShare system: task request 10 of 57

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

submission, composition, and negotiation. Appendix B repeats documentation previously presented in deliverable D6.2, describing the core API of the orchestration system as implemented in SmartShare.

Validation methodology

Over the next few months, we intend to gather real-world data through the system using the present implementation of SmartShare in order to validate the Reputation Service and Provenance recorded in WP2. This data is expected to be produced by trial deployments in Italy that will be conducted as a project-wide activity (see D9.3 Prototype version 1, testing scenarios and initial evaluation deliverable for details). Alongside automated data collection from the system, a questionnaire-based user study will be conducted among the users of the deployed system. The research questions around the use of provenance and reputation within the system are as follows: 1. How useful are provenance-derived explanations of system behaviour to users? This will be explored using questionnaires that provide natural language explanations, which describe the context of how reputation ratings are computed. The questionnaire will be used to identify key concepts which aâ&#x2020;ľect usersâ&#x20AC;&#x2122; decision making. The identified key concepts will influence which aspects we will use from the captured provenance to automatically generate descriptions of computed reputations. 2. What sorts of reputation ratings are created by participants, when and how often are these consulted by users, and what is their impact on oâ&#x2020;ľering, requesting, and accepting certain rides? This will be investigated through a statical analysis of how reputation information is produced and consumed. 3. How well do the developed graph transformation techniques (including summarisation) scale to cope with real-world data from a live system where the provenance information generated by the system is voluminous? This will be tested by applying performance measures that evaluate the computational efficiency of producing provenance summaries while also qualitatively analysing the information content of these summaries. 4. What does the provenance data collected from the ride share scenario expose in terms of workflow patterns and personal data? We will explore how far information c SmartSociety Consortium 2013-2017

11 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

revealed from provenance summaries complies with privacy profiles anticipated for an operational system and will experiment with techniques to hide or obscure personal data. 5. How does the provenance system eâ&#x2020;ľect the architecture and computation of SmartSociety applications? This will involve technical tests to explore how our technologies function within a live system and with live data, e.g. in terms of the storage and time complexity added to the basic system when introducing provenance tracking. Taken together, these validation steps will enable us to provide solid evidence for the benefits of the technologies we have developed so far by testing their eâ&#x2020;ľect on HDA-CASs in a real-world environment.

Conclusion

This document has summarised the work done on implementing a software component to validate the the technical contributions of WP2. We reviewed the structure of the software, described how it has been integrated in the SmartShare prototype, how it relates to the formal framework to describe data-drive interaction modelling that we have developed, and outlined the methodology we will apply to validate it using real-world data over the next few months. We anticipate that deployment of this software will lead to further modifications and improvements, and will present us with opportunities to refine the proposed methods. These, together with the results of the validation will be presented in the next iteration of SmartSociety deliverables.

12 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Provenance and Reputation Documentation

A.1

ProvBindings API

The documentation for the ProvBindings’s API is hosted at https://smartshare.ecs. soton.ac.uk/provbindings/. A.1.1

Introduction

PROV Binding service’s API provides a RESTful web service for posting provenance templates and bindings. This service manages which bindings are associated to a template, and acts as a proxy to the PROV Store, which is used to store the provenance templates and bindings documents. A.1.2

Issue Tracking

All tickets for the project are being tracked on BitBucket. You can also take a look at the recent updates for the project. A.1.3

API Calls

The following API calls are relative to the service’s endpoint, and this service is hosted at https://smartshare.ecs.soton.ac.uk/provbindings/. 1. GET application/:app/template/ Retrieve all templates associated with an application. (a) Response Object The response object returns a JSON object containing the details of templates associated with the specified application. Each template return contains the following: template_id template_name version prov_store_id

the the the the

template’s id. name of the template. version number for the template. id of the template in the provenance document.

(b) SmartSociety Example with Authentication via Peer Manager This example requests the details of all template resources associated with the application with id 1. Request c SmartSociety Consortium 2013-2017

13 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

GET https://smartshare.ecs.soton.ac.uk/provbindings/application/1/template/ Authorization: Basic test_auth:test APP_KEY: app_key_example APP_SECRET: app_secret_example

Response HTTP/1.0 200 OK Date: Wed, 18 Feb 2015 13:01:54 GMT Server: WSGIServer/0.1 Python/2.7.6 Content-Type: application/json { "1": { "template_id": 3, "template_name": "negotiation", "version": 1, "prov_store_id": "https://provenance.ecs.soton.ac.uk/store/api/v0/documents/76283.ttl"}, "2": { "template_id": 2, "template_name": "negotiation", "version": 0, "prov_store_id": "https://provenance.ecs.soton.ac.uk/store/api/v0/documents/76282.ttl"}, "3" :{ "template_id": 1, "template_name": "delegation", "version": 0, "prov_store_id": "https://provenance.ecs.soton.ac.uk/store/api/v0/documents/76278.ttl"} }

2. POST application/:app/template/:template name/ Save a new provenance template. (a) Request Object The request body is a string representation of the posted provenance template, which must be in one of the following provenance representations: text/provenancenotation text/turtle Use Content-Type to specify which type you are supplying. (b) Response Object The response object content is the url of the submitted provenance document, using the MIME type text/uri-list. (c) SmartSociety Example with Authentication via Peer Manager This example posts a provenance template named delegation to the application resource with id 1. The provbindings service returns the URI of the template document in the PROVStore. Request 14 of 57

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

POST https://smartshare.ecs.soton.ac.uk/provbindings/application/1/template/delegation/ Content-Type: text/provenance-notation Authorization: Basic test_auth:test APP_KEY: app_key_example APP_SECRET: app_secret_example Data: ’document prefix cas <http://smartsociety-project.github.io/cas/#> prefix tmpl <http://openprovenance.org/tmpl#> prefix var <http://openprovenance.org/var#> prefix vargen <http://openprovenance.org/vargen#> bundle vargen:b entity(var:request, [ prov:type=’cas:Request’, prov:label="cas:Request"]) activity(var:delegating_request, -, -, [ tmpl:startTime=’var:delegating_request_start’, tmpl:endTime=’var:delegating_request_end’, prov:type=’cas:ReceivingRequest’, prov:label="cas:ReceivingRequest"]) entity(var:response, [ prov:type=’cas:Response’, prov:label="cas:Response"]) activity(var:computing_response, -, -, [ tmpl:startTime=’var:computing_response_start’, tmpl:endTime=’var:computing_response_end’, prov:type=’cas:ComputingResponse’, prov:label="cas:ComputingResponse"]) activity(var:sending_response, -, -, [ tmpl:startTime=’var:sending_response_start’, tmpl:endTime=’var:sending_response_end’, prov:type=’cas:SendingRequest’, prov:label="cas:SendingRequest"]) wasDerivedFrom(var:response, var:request, -, -, -) wasInformedBy(var:computing_response, var:delegating_request) wasInformedBy(var:sending_response, var:computing_response) endBundle endDocument’

Response HTTP/1.0 201 Created Date: Wed, 18 Feb 2015 14:24:51 GMTs Server: nginx Content-Type: text/uri-list Location: https://provenance.ecs.soton.ac.uk/store/api/v0/documents/7651 https://provenance.ecs.soton.ac.uk/store/api/v0/documents/7651

3. POST application/:app/template/:template name/:binding name/ Save a new provenance binding. c SmartSociety Consortium 2013-2017

15 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

(a) Response Object The request body is a binding expressed as a provenance document in text/turtle representation. Specify Content-Type as text/turtle. (b) Response Object The response object content is the url of the submitted provenance document, using the MIME type text/uri-list. (c) SmartSociety Example with Authentication via Peer Manager This example posts a provenance binding named submit request binding, to the template resource submit request associated the application resource with id 1. The provbindings service returns the URI of the expanded provenance document in the PROVStore, which used the submitted binding and associated template. Request POST https://smartshare.ecs.soton.ac.uk/provbindings/application/1/ template/submit_request/submit_request_bindingâ&#x20AC;&#x2122; Content-Type: text/turtle Authorization: Basic test_auth:test APP_KEY: app_key_example APP_SECRET: app_secret_example Data: â&#x20AC;&#x2122; @prefix @prefix @prefix @prefix @prefix @prefix @prefix @prefix

@prefix prov: <http://www.w3.org/ns/prov#> . rideserver: <http://rideshares.info/> . rideservice: <http://rideshares.info/OpenRideServer-RS/> . view: <http://rideshares.info/OpenRideServer-RS/view/> . orchestrator: <http://www.rideshare-orchestrator.com/> . tmpl: <http://openprovenance.org/tmpl#> . var: <http://openprovenance.org/var#> . op: <https://smartshare.ecs.soton.ac.uk/rs/application/1/reputation/> . xsd: <http://www.w3.org/2001/XMLSchema#> .

var:view a prov:Entity ; tmpl:value_0 view:activeOffers-9 . var:response a prov:Entity ; tmpl:value_0 op:response-8 . var:request a prov:Entity ; tmpl:value_0 rideserver:1 . var:ui a prov:Entity ; tmpl:value_0 rideserver:ors-1 . var:sending_request a prov:Entity ; tmpl:value_0 orchestrator:requestingOpinion-112 . var:sending_request_end_time a prov:Entity ; tmpl:2dvalue_0_0 "2014-01-01T09:21:00+02:00"^^xsd:dateTime . var:changing_view a prov:Entity ; tmpl:value_0 view:viewingReputation-125 .

16 of 57

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

var:sending_request_start_time a prov:Entity ; tmpl:2dvalue_0_0 "2014-01-01T09:21:00+02:00"^^xsd:dateTime . var:identity a prov:Entity ; tmpl:value_0 rideservice:id-11 .’

Response HTTP/1.0 201 Created Server: nginx Date: Sat, 11 Apr 2015 22:52:42 GMT Content-Type: text/uri-list Location: https://provenance.ecs.soton.ac.uk/store/api/v0/documents/7652 https://provenance.ecs.soton.ac.uk/store/api/v0/documents/7652

A.2

Reputation API

The documentation for the Reputation’s API is hosted at https://smartshare.ecs. soton.ac.uk/rs/. A.2.1

Introduction

Reputation Services’ API provides a RESTful web service for storage and access feedback and reputation reports for applications. A.2.2

Issue Tracking

All tickets for the project are being tracked on BitBucket. You can also take a look at the recent updates for the project. A.2.3

Resources

The API currently describes three resources, applications, feedback, and reputation, which are documented below. These API calls are relative to the service’s endpoint, and this service is hosted at https://smartshare.ecs.soton.ac.uk/rs/. The following actions are available on the service’s resources: 1. GET application/:app/subject/byURI/:subject uri/ Retrieve a subject’s information by its URI. The subject uri must be percentage encoded. (a) Response Object The response object and version object are described in Tables 1a and 1a. c SmartSociety Consortium 2013-2017

17 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

versionInfo

an object specifying the version of information contained about a subject. subject uri the subject’s URI feedback a list of feedback reports about the subject. currentReputationReport the current reputation report for a subject. reputation reports a list of reputation reports about a subject. associatedWithEvents a list of events a subject is associated with through feedback reports. hasRole a list roles the subject has played in feedback reports.

Table 1: Response Object hasAnchor previousVersion

the current URI of the subject’s information. the previous URI of the subject’s information.

Table 2: VersionInfo Object (b) SmartSociety Example with Authentication via Peer Manager Request GET https://smartshare.ecs.soton.ac.uk/rs/subject/byURI/https\%2F\%2F\%2E example.com\%2Fuser34\%2E Authorization: Basic test\_auth:test APP_KEY: app\_key\_example APP_SECRET: app\_secret\_example

Response HTTP/1.0 200 OK Date: Wed, 18 Feb 2015 13:01:54 GMT Server: WSGIServer/0.1 Python/2.7.5 Link: <https://smartshare.ecs.soton.ac.uk/rs/request/4>; rel="hasRequest"; anchor="https://smartshare.ecs.soton.ac.uk/rs/response/4" Content-Location: https://smartshare.ecs.soton.ac.uk/rs/application/1/subject/ byURI/https://example.com/user34//v/2/ Content-Type: application/json { "versionInfo": { "hasAnchor": /rs/application/1/subject/byURI/https%2F%2F%2E example.com%2Fuser34%2E/v/2/", "previousVersion": "/rs/application/1/subject/byURI/ https%2F%2F%2Eexample.com%2Fuser34%2E/v/1/" }, "subject_uri": "https://example.com/user34", "feedback": { "feedback4": { "id": 4, "uri": "/rs/application/1/feedback/4/" },

18 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

"feedback5": { "id": 5, "uri": "/rs/application/1/feedback/5/" }, "feedback2": { "id": 2, "uri": "/rs/application/1/feedback/2/" }, "feedback3": { "id": 3, "uri": "/rs/application/1/feedback/3/" }, "feedback1": { "id": 1, "uri": "/rs/application/1/feedback/1/" } }, "currentReputationReport": { "uri": "/rs/application/1/reputation/9/", "id": 9 }, "subject_id": 1, "reputation_reports": { "reputation10": { "id": 10, "uri": "/rs/application/1/reputation/10/" }, "reputation1": { "id": 1, "uri": "/rs/application/1/reputation/1/" }, "reputation2": { "id": 2, "uri": "/rs/application/1/reputation/2/" }, "reputation3": { "id": 3, "uri": "/rs/application/1/reputation/3/" }, "reputation4": { "id": 4, "uri": "/rs/application/1/reputation/4/" }, "reputation5": { "id": 5, "uri": "/rs/application/1/reputation/5/" }, "reputation6": { "id": 6, "uri": "/rs/application/1/reputation/6/" }, "reputation7": { "id": 7, "uri": "/rs/application/1/reputation/7/" },

c SmartSociety Consortium 2013-2017

19 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

"reputation8": { "id": 8, "uri": "/rs/application/1/reputation/8/" }, "reputation9": { "id": 9, "uri": "/rs/application/1/reputation/9/" } }, "associatedWithEvents": { "event1": { "event_id": 1, "description": "Is an event that took place in the 1 application", "uri": "http://abacus.imaginary:3000/rideRequests/101/" } }, "hasRole": { "role1": { "uri": "http://example.com/commuter/", "id": 1, "description": "The quantifier is commuter." } } }

2. GET application/:app/subject/:subject/ Retrieve information about the subject with the given ID. (a) Response Object The response object and version object are described in Tables 4a and 2a. versionInfo

an object specifying the version of information contained about a subject. subject uri the subjectâ&#x20AC;&#x2122;s URI feedback a list of feedback reports about the subject. currentReputationReport the current reputation report for a subject. reputation reports a list of reputation reports about a subject. associatedWithEvents a list of events a subject is associated with through feedback reports. hasRole a list roles the subject has played in feedback reports.

Table 3: Response Object (b) SmartSociety Example with Authentication via Peer Manager Request GET https://smartshare.ecs.soton.ac.uk/rs/application/1/subject/1/

20 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

hasAnchor previousVersion

the current URI of the subject’s information. the previous URI of the subject’s information.

Table 4: VersionInfo Object Authorization: Basic test\_auth:test APP_KEY: app\_key\_example APP_SECRET: app\_secret\_example

Response HTTP/1.0 200 OK Date: Wed, 18 Feb 2015 14:18:42 GMT Server: WSGIServer/0.1 Python/2.7.5 Link: <https://smartshare.ecs.soton.ac.uk/rs/request/5>; rel="hasRequest"; anchor="https://smartshare.ecs.soton.ac.uk/rs/response/5" Content-Location: https://smartshare.ecs.soton.ac.uk/rs/application/1/subject/1/ Content-Type: application/json { "versionInfo": { "hasAnchor": "/rs/application/1/subject/ byURI/https%2F%2F%2Eexample.com%2Fuser34%2E/v/2/", "previousVersion": "/rs/application/1/ subject/byURI/https%2F%2F%2Eexample.com%2Fuser34%2E/v/1/" }, "subject_uri": "https://example.com/user34", "feedback": { "feedback4": { "id": 4, "uri": "/rs/application/1/feedback/4/" }, "feedback5": { "id": 5, "uri": "/rs/application/1/feedback/5/" }, "feedback2": { "id": 2, "uri": "/rs/application/1/feedback/2/" }, "feedback3": { "id": 3, "uri": "/rs/application/1/feedback/3/" }, "feedback1": { "id": 1, "uri": "/rs/application/1/feedback/1/" } }, "currentReputationReport": { "uri": "/rs/application/1/reputation/9/", "id": 9

c SmartSociety Consortium 2013-2017

21 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

}, "subject_id": 1, "reputation_reports": { "reputation10": { "id": 10, "uri": "/rs/application/1/reputation/10/" }, "reputation1": { "id": 1, "uri": "/rs/application/1/reputation/1/" }, "reputation2": { "id": 2, "uri": "/rs/application/1/reputation/2/" }, "reputation3": { "id": 3, "uri": "/rs/application/1/reputation/3/" }, "reputation4": { "id": 4, "uri": "/rs/application/1/reputation/4/" }, "reputation5": { "id": 5, "uri": "/rs/application/1/reputation/5/" }, "reputation6": { "id": 6, "uri": "/rs/application/1/reputation/6/" }, "reputation7": { "id": 7, "uri": "/rs/application/1/reputation/7/" }, "reputation8": { "id": 8, "uri": "/rs/application/1/reputation/8/" }, "reputation9": { "id": 9, "uri": "/rs/application/1/reputation/9/" } }, "associatedWithEvents": { "event1": { "event_id": 1, "description": "Is an event that took place in the 1 application", "uri": "http://abacus.imaginary:3000/rideRequests/101/" } }, "hasRole": { "role1": { "uri": "http://example.com/commuter/",

22 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

"id": 1, "description": "The quantifier is commuter." } } }

3. POST application/:app/feedback/ Save a new feedback report. (a) Request Body The request body is a JSON object and it is described in Table 3a. The feedback object contains a set of categories and values which a subject is rated on. The subjects object contains sets of subjects which is described in Table 3a, and the authors object contains sets of subjects 3a. application uri

URI of the Application associated with the feedback. URI of the event associated with the feedback. A list of subjects that a feedback report is about. A list of authors that authored the feedback report. An object containing feedback categories and ratings about the subject/s.

event uri subjects authors feedback

Table 5: Request Body subject uri quantifier uri

A subject’s URI. The quantifier URI, which defines the subject’s role in the event.

Table 6: Subject Object author uri quantifier uri

An author’s URI. The quantifier URI, which defines the author’s role in the event.

Table 7: Author Object (b) Response Object (c) SmartSociety Example with Authentication via Peer Manager Request POST https://smartshare.ecs.soton.ac.uk/rs/application/1/feedback/ Authorization: Basic test_auth:test APP_KEY: app_key_example

c SmartSociety Consortium 2013-2017

23 of 57

c SmartSociety Consortium 2013-2017

feedback report reputation report opinion report

Deliverable D2.3

The uri of the feedback report submitted. Reputation reports generated by the submission of the feedback report. Opinion reports generated by the submission of the feedback report.

Table 8: Response Object APP_SECRET: app_secret_example data â&#x20AC;&#x2122;{ "application_uri": "http://smartshare.com/rs/", "event_uri": "http://abacus.imaginary:3000/rideRequests/101/", "subjects": { "subject1": { "subject_uri": "https://example.com/user34", "quantifier_uri": "https://example.com/commuter" } }, "authors": { "author1": { "author_uri": "https://example.com/user3", "quantifier_uri": "https://example.com/commuter" } }, "feedback": { "StarRating": 3, "OnTime": 2, "Friendly": 4 } }â&#x20AC;&#x2122;

Response HTTP/1.0 200 OK Date: Wed, 18 Feb 2015 14:24:51 GMT Server: WSGIServer/0.1 Python/2.7.5 Link: <https://smartshare.ecs.soton.ac.uk/rs/request/8>; rel="hasRequest"; anchor="https://smartshare.ecs.soton.ac.uk/rs/response/8" Content-Location: https://smartshare.ecs.soton.ac.uk/rs/application/1/feedback/ Content-Type: application/json { "feedback_report": "https://smartshare.ecs.soton.ac.uk/rs/application/1/feedback/1/", "reputation_report": { "0": "https://smartshare.ecs.soton.ac.uk/rs/application/1/reputation/1/", "1": "https://smartshare.ecs.soton.ac.uk/rs/application/1/reputation/2/" }, "opinion_report": {

24 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

"0": "https://smartshare.ecs.soton.ac.uk/rs/application/1/opinion/2", "1": "https://smartshare.ecs.soton.ac.uk/rs/application/1/opinion/1" } }

4. GET application/:app/reputation/:reputation/ Retrieve the raw reputation report with the given ID. (a) Response Object The response object and version object are described in Tables 3b. timestamp

The timestamp of the feedback reportâ&#x20AC;&#x2122;s submission. A list of categories and ratings which the subject/s were rated. A list of subject/s that the reputation report is about. The id of the reputation report. The URI of the reputation report.

json subjects reputation id uri

Table 9: Response Object (b) SmartSociety Example with Authentication via Peer Manager Request GET https://smartshare.ecs.soton.ac.uk/rs/application/1/reputation/1/ Authorization: Basic test_auth:test APP_KEY: app_key_example APP_SECRET: app_secret_example

Response HTTP/1.0 200 OK Date: Wed, 18 Feb 2015 15:20:28 GMT Server: WSGIServer/0.1 Python/2.7.5 Link: <https://smartshare.ecs.soton.ac.uk/rs/request/5>; rel="hasRequest"; anchor="https://smartshare.ecs.soton.ac.uk/rs/response/5" Content-Location: https://smartshare.ecs.soton.ac.uk/rs/application/1/reputation/1/ Content-Type: application/json { "timestamp": "2014-12-15 12:24:07.030000+00:00", "uri": "application/1/reputation/1/", "json": { "average_StarRating": 3, "total_StarRating": 3, "total_OnTime": 2, "average_OnTime": 2, "total_Friendly": 4, "average_Friendly": 4

c SmartSociety Consortium 2013-2017

25 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

}, "subjects": { "subject_1": 1 }, "reputation_id": 1, "quantifier": "http://example.com/all" }

5. GET application/:app/opinionOf/:author/aboutSubject/:subject/ Retrieve the raw reputation report about a subject authored by an author. (a) Response Object The response object and version object are described in Tables 1a and 1a. opinion value timestamp uri subjects authors

A value representing an opinion of the author about a subject. A timestamp taken when the opinion was generated. URI of the opinion. The subject of which the opinion is about. The author whose feedback reports pertaining to the subject were used to generate the opinion value.

Table 10: Response Object hasAnchor previousVersion

the current URI of the subjectâ&#x20AC;&#x2122;s information. the previous URI of the subjectâ&#x20AC;&#x2122;s information.

Table 11: VersionInfo Object (b) SmartSociety Example with Authentication via Peer Manager Request GET https://smartshare.ecs.soton.ac.uk/rs/application/1/opinionOf/4/aboutSubject/1/ Authorization: Basic test_auth:test APP_KEY: app_key_example APP_SECRET: app_secret_example

Response HTTP/1.0 200 OK Date: Wed, 18 Feb 2015 15:35:24 GMT Server: WSGIServer/0.1 Python/2.7.5 Link: <https://smartshare.ecs.soton.ac.uk/rs/request/7>; rel="hasRequest"; anchor="https://smartshare.ecs.soton.ac.uk/rs/response/7" Content-Location: https://smartshare.ecs.soton.ac.uk/rs/application/1/opinionOf/4/aboutSubject/1/

26 of 57

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

Content-Type: application/json { "opinion_2": { "opinion_value": 2, "timestamp": "2014-12-15 13:42:47.815441+00:00", "uri": "application/1/opinion/9/", "subjects": { "subject_1": 1 }, "authors": { "author_1": 2 }, "quantifier": "all", "opinion_id": 9 }, "opinion_1": { "opinion_value": 2, "timestamp": "2014-12-15 13:42:47.834244+00:00", "uri": "application/1/opinion/10/", "subjects": { "subject_1": 1 }, "authors": { "author_1": 2 }, "quantifier": "http://example.com/commuter", "opinion_id": 10 }, "versionInfo": { "hasAnchor": "application/1/opinionOf/2/aboutSubject/1/v/1/", "previousVersion": "none" } }

c SmartSociety Consortium 2013-2017

27 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Orchestration API documentation

For the sake of completeness, this appendix summarises the orchestration API, which was already presented in deliverable D6.2. Extensive documentation for the entire SmartShare system is available from https://bitbucket.org/rovatsos/smartsociety-internal/ wiki/browse/SmartSharing. The specific documentation for integration of the the provenance aspects of the software can be found at https://bitbucket.org/rovatsos/smartsociety-internal/wiki/SmartSharing/Provenance.

B.1

Application Orchestration

For convenience we split the API into diâ&#x2020;ľerent sections. B.1.1

Task Requests

We start with task requests. The most basic operations are listed in the following table: verb POST GET GET HEAD GET DELETE

URI /applications/:app/taskRequests /applications/:app/taskRequests/?user=:user /applications/:app/taskRequests/:taskRequestID /applications/:app/taskRequests/:taskRequestID /applications/:app/taskRequests/:taskRequestID/v/:version /applications/:app/taskRequests/:taskRequestID

Create Task Request: POST /applications/:app/taskRequests

This is the main

URI where new task requests are posted. The JSON object describing the task request is expected in the body of the request. On success a platform call to the composition manager will be made. Access Control. Success.

Any peer or user.

Returns error code 201 together with

â&#x20AC;˘ a JSON document of the form { 28 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

data: aURI } where aURI is the URI where the client can retrieve (assuming authentication and access control policies have no issues) the latest version of the task request that has been posted, and optionally • an ETag for the JSON object of the response. Failure.

Returns an error code accompanied by an optional error message explaining

the failure; e.g. 403 (forbidden), 500 (internal server error), etc. Comment.

Upon success a call is made to the composition manager that will create

the associated tasks based on the current state of the system. Get Task Requests of User: GET /applications/:app/taskRequests/?user=:user

No parameters are expected

apart from authentication purposes (in the header). Access Control. Success.

The peer user or an admin.

Returns error code 200 together with

• a JSON document of the form { data: [[userTaskRequestsURIs], [associatedETags]] } that has the list of the task requests referring to the specific user together with the associated ETags for those links, • an ETag for the JSON object of the response. Failure.

Returns error code 403 together with the error message ”Forbidden”.

c SmartSociety Consortium 2013-2017

29 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Get a Task Request: GET /applications/:app/taskRequests/:taskRequestID

No parameters are ex-

pected apart from authentication information (if needed). Access Control. Success.

The owner of the task request or an admin.

Returns error code 200 together with the JSON document of the latest

version of the task request accompanied by the ETag of the document. Failure.

Returns an error code (403, 404) together with an optional error message.

Get the Head of a Task Request: HEAD /applications/:app/taskRequests/:taskRequestID

Similar to

GET /applications/:app/taskRequests/:taskRequestID except that the body returned is empty. It just returns the ETag of the latest version of the task request to indicate if there has been a change to the document and thus we need to retrieve its latest version. The access control policy is similar as above; the owner of the task request or an admin can perform the operation. Get a Specific Version of a Task Request: GET /applications/:app/taskRequests/:taskRequestID/v/:version

No param-

eters are expected apart from authentication purposes (if needed). Access Control.

The owner of the task request or an admin.

Success.

Returns error code 200 together with the specific version of the task request.

Failure.

Returns an error code together with an optional error message.

Delete a Task Request: DELETE /applications/:app/taskRequests/:taskRequestID This is the main URI for deleting task requests. No parameters are expected apart from authentication information (in the header). A platform job is prepared and is posted to the deletion manager. Access Control. 30 of 57

The owner of the task request or an admin. http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Success.

Returns error code 204.

Failure.

Returns an error code (403, 404, or 500).

B.1.2

Tasks

Tasks are generated through composition (more on that below). The most basic operations related to them are listed in the following table: verb GET HEAD GET PUT

URI /applications/:app/tasks/:taskID /applications/:app/tasks/:taskID /applications/:app/tasks/:taskID/v/:version /applications/:app/tasks/:taskID

Get a Specific Task: GET /applications/:app/tasks/:taskID

Similar to GET

/applications/:app/taskRequests/:taskRequestID but referring to tasks. No parameters are expected apart from authentication information (if needed). Access Control. Success.

The participants of the task or an admin.

Returns error code 200 together with the JSON document of the latest

version of the task accompanied by the ETag of the document. Failure.

Returns an error code (403, 404) together with an optional error message.

Get the Head of a Task: HEAD /applications/:app/tasks/:taskID

Similar as

above but the body of the response is empty. Essentially this is an easy way for the clients to figure out if the resource has changed. Same access control policy as above. Get a Specific Version of a Task: GET /applications/:app/tasks/:taskID/v/:version

No parameters are expected

apart from authentication information (if needed). Access Control.

The participants of the task or an admin.

c SmartSociety Consortium 2013-2017

31 of 57

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Success.

Returns error code 200 together with the specific version of the task.

Failure.

Returns an error code together with an optional error message.

Negotiate on a Task: PUT /applications/:app/tasks/:taskID

The main call

for negotiation which will trigger an additional platform call to the negotiation manager. Expects the new version of the document of the task taskID. A platform job for negotiation is prepared and is posted to the negotiation manager. Access Control. Success.

The participants of the task or an admin.

Returns error code 200 together with the new version of the task as is

dictated by the negotiation manager. Failure. B.1.3

Returns an error code together with an optional error message.

Task Records

Task records are generated by the orchestrator once execution can start on a specific task. The most basic operations are listed in the following table: verb GET HEAD GET PUT

URI /applications/:app/taskRecords/:taskRecordID /applications/:app/taskRecords/:taskRecordID /applications/:app/taskRecords/:taskRecordID/v/:version /applications/:app/taskRecords/:taskRecordID

Get a Specific Task Record: GET /applications/:app/taskRecords/:taskRecordID

No parameters are expected

apart from authentication information (if needed). Access Control. Success.

The participants of the task or an admin.

Returns error code 200 together with the json document of the latest version

of the task record accompanied by the ETag of the document. 32 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

Failure.

Returns an error code (403, 404) together with an optional error message.

Get the Head of a Task Record: HEAD /applications/:app/taskRecords/:taskRecordID

No parameters are ex-

pected apart from authentication information (if needed). The body of the response is empty. This is another convenience function which allows an easy way for the clients to figure out if the resource has changed. Same access control policy and error codes as above. Get a Specific Version of a Task Record: GET /applications/:app/taskRecords/:taskRecordID/v/:version

No parameters

are expected apart from authentication purposes (if needed). Access Control.

The participants of the task or an admin.

Success.

Returns error code 200 together with the specific version of the task.

Failure.

Returns an error code together with an optional error message.

Provide Execution Feedback: PUT /applications/:app/taskRecords/:taskRecordID

The main call for execu-

tion which will trigger an additional platform call to the execution manager. Expects the new version of the task record document taskRecordID. A platform job for execution is prepared and is posted to the execution manager. Access Control. Success.

The participants of the task or an admin.

Returns error code 200 together with the new version of the task as dictated

by the execution manager. Failure.

B.2

Returns an error code together with an optional error message.

Composition Manager

The composition manager provides the following functionality: c SmartSociety Consortium 2013-2017

33 of 57

c SmartSociety Consortium 2013-2017

verb POST GET

Deliverable D2.3

URI /applications/:app/compositions /applications/:app/compositions/:compositionID

Perform Composition: POST /applications/:app/compositions

Expects the plat-

form job with the description, for which the main ingredient is the new task request that has arrived on the platform.

Access Control.

Returns.

The orchestrator for the application app can make such a call.

The call always succeeds and generates a resource describing the outcome

of composition. Upon completion it returns an error code 201 and the link to the document with the results of composition. Part of the description of the document with the results of the composition is the error code and message that is returned through the call POST /applications/:app/taskRequests to the client.

Get Composition Results: GET /applications/:app/compositions/:compositionID

No parameters are ex-

pected.

Access Control.

The orchestrator for the application app or an admin can make

such a call.

Success.

Returns error code 200, the JSON document with the description of the

results of the composition together with the associated ETag for the document.

Failure.

Returns an error code (e.g. 404 not found) together with an optional error

message.

Comment.

Normally such a call is expected to happen only once from the applica-

tion orchestrator once the latter has received the 201 error code that the composition that was requested has been performed. 34 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

B.3

Negotiation Manager

The negotiation manager provides the following functionality. verb POST GET

URI /applications/:app/negotiations /applications/:app/negotiations/:negotiationID

Perform Negotiation: POST /applications/:app/negotiations

Expects the plat-

form job with the description, for which the main ingredient is the task on which negotiation is being performed. Access Control. Returns.

The orchestrator for the application app can make such a call.

The call always succeeds and generates a resource describing the outcome

of negotiation. Upon completion it returns an error code 201 and the link to the document with the results of the negotiation. Part of the description of the document with the results of the negotiation is the error code and message that is returned through the call PUT /applications/:app/tasks/:taskID to the client. Get Negotiation Results: GET /applications/:app/negotiations/:negotiationID Access Control.

No parameters are expected.

The orchestrator for the application app or an admin can make

such a call. Success.

Returns error code 200, the JSON document with the description of the

results of the negotiation together with the associated ETag for the document. Failure.

Returns an error code (e.g. 404 not found) together with an optional error

message. Comment.

Normally such a call is expected to happen only once from the applica-

tion orchestrator once the latter has received the 201 error code that the negotiation that was requested has been performed. c SmartSociety Consortium 2013-2017

35 of 57

c SmartSociety Consortium 2013-2017

B.4

Deliverable D2.3

Deletion Manager

The deletion manager provides the following functionality: verb POST GET

URI /applications/:app/deletions /applications/:app/deletions/:deletionID

Perform Deletion: POST /applications/:app/deletions

Expects the platform job

with the description, for which the main ingredient is the task request on which deletion is being performed. Access Control. Returns.

The orchestrator for the application app can make such a call.

The call always succeeds and generates a resource describing the outcome

of deletion. Upon completion it returns an error code 201 and the link to the document with the results of the deletion. Part of the description of the document with the results of the deletion is the error code that is returned through the call DELETE /applications/:app/taskRequests/:taskRequestID to the client. Get Deletion Results: GET /applications/:app/deletions/:deletionID Access Control.

No parameters are expected.

The orchestrator for the application app or an admin can make

such a call. Success.

Returns error code 200, the JSON document with the description of the

results of the deletion together with the associated ETag for the document. Failure.

Returns an error code (e.g. 404 not found) together with an optional error

message. Comment.

Normally such a call is expected to happen only once from the applica-

tion orchestrator once the latter has received the 201 error code that the deletion that was requested has been performed. 36 of 57

http://www.smart-society-project.eu

c SmartSociety Consortium 2013-2017

Deliverable D2.3

B.5

Execution Manager

The execution manager provides the following functionality: verb POST GET

URI /applications/:app/executions /applications/:app/executions/:executionID

Perform Execution: POST /applications/:app/executions/:executionID

Expects the platform job with

the description, for which the main parameter is the task on which a particular step of the execution is being performed.

Access Control.

Returns.

The orchestrator for the application app can make such a call.

The call always succeeds and generates a resource describing the outcome

of the execution. Upon completion it returns an error code 201 and the link to the document with the results of the execution. Part of the description of the document with the results of the execution is the error code and message that is returned through the call PUT /applications/:app/taskRecord/:taskRecordID to the client.

Get Execution Results: GET /applications/:app/executions/:executionID

Access Control.

No parameters are expected.

The orchestrator for the application app or an admin can make

such a call.

Success.

Returns error code 200, the json document with the description of the

results of the execution together with the associated ETag for the document.

Failure.

Returns an error code (e.g. 404 not found) together with an optional error

message. c SmartSociety Consortium 2013-2017

37 of 57

c SmartSociety Consortium 2013-2017

Comment.

Deliverable D2.3

Normally such a call is expected to happen only once from the applica-

tion orchestrator once the latter has received the 201 error code that the execution that was requested has been performed.

B.6

Further Remarks and Functionality

The above are the basic calls for orchestration (ignoring execution). They are designed in such a way so that resources are generated and linked with each other as needed. We allow a full provenance trace in the above paradigm (for the orchestration part of a SmartSociety application). Further, access control policies allow admins to follow links and inspect the system; for example for explanation purposes that can be used for provenance reasons. In addition, and this is tightly related to privacy and security concerns, the clients may want to retrieve sets of task requests or sets of tasks. One approach to accommodate such functionality would be calls of the form: POST POST

/applications/:app/taskRequests/?action=getSet /applications/:app/tasks/?action=getSet

where the client can post a document with the di↵erent URIs of tasks or task requests and request the content for all of them instead of performing one-by-one calls for retrieving the individual tasks/task requests. However, such an approach indicates bad design from a REST perspective, so, as we refine and finalise the various details we will allow get operations on specific resources that can actually guess the functionality that is requested from the server. For example, one functionality that can be provided to the clients is to allow the retrieval of all the task requests that have not been completed yet. B.6.1

Administration and Monitoring

The orchestration paradigm that we have is asynchronous, non-blocking, and allows full profiling of the di↵erent steps of the execution of the jobs of the platform. These job profiles are stored and administrators of the application/platform can have access to them. Further, the various administrators may require access to resources for inspection purposes. Such monitoring capabilities are o↵ered under URIs of the form shown below. GET POST

/applications/:app/monitoring/?action=getSet /applications/:app/monitoring

We do provide such functionality and such function calls already 3 . 3

For example see http://168.144.202.152:3001/monitoring and references therein for versioned resources but more importantly the analytics of the platform in

38 of 57

http://www.smart-society-project.eu

Deliverable D2.3

c SmartSociety Consortium 2013-2017

Published paper: Agent Protocols for Social Computation

Presented at the Multiagent Systems for Social Computation Workshop held at the International Conference on Autonomous Agents and Multiagent Systems (AAMAS 2015) (Istanbul, 4th May 2015).

http://168.144.202.152:3001/monitoring/analytics.

c SmartSociety Consortium 2013-2017

39 of 57

Agent Protocols for Social Computation Michael Rovatsos, Dimitrios Diochnos, and Matei Craciun School of Informatics The University of Edinburgh Edinburgh EH8 9AB, United Kingdom {mrovatso,ddiochno,s1374265}@inf.ed.ac.uk

Abstract. Despite the fact that social computation systems involve interaction mechanisms that closely resemble well-known models of agent coordination, current applications in this area make little or no use of the techniques the agent-based systems literature has to oâ&#x2020;ľer. In order to bridge this gap, this paper proposes a data-driven method for defining and deploying agent interaction protocols that is entirely based on using the standard architecture of the World Wide Web. This obviates the need of bespoke message passing mechanisms and agent platforms, thereby facilitating the use of agent coordination principles in standard Web-based applications. We describe a prototypical implementation of the architecture and experimental results that prove it can deliver the scalability and robustness required of modern social computation applications while maintaining the expressiveness and versatility of agent interaction protocols.

Keywords: Agent Communication, Social Computation, Web Agents

Introduction

Most real-world social computation applications that involve large-scale human and machine collaboration (e.g. collective intelligence [10] or human computation [8]), are currently implemented using either ad hoc methods or programming frameworks [1, 9] that make no use of agent technology. Within the agents community, on the other hand, agent communication languages and interaction protocols [3] have been widely used to design and deploy a wide range of agent coordination mechanisms, many of which bear close similarity to those needed in social computation systems. This is at least in part due to the fact that the architectural proposals for developing real-world agent-based systems mostly rely on bespoke platforms with custom message passing mechanisms and control structures. Since the inception of those agent platforms, the architecture of the Web [5] has given rise to a plethora of massive-scale distributed applications, almost in complete ignorance of agent-based techniques [13]. The work presented in this paper aims to bridge the gap between agent coordination techniques and social computation by providing a method for mapping the principles of agent protocol design to the architecture of the Web. We

describe a data-driven method for defining and deploying agent interaction protocols that complies with the architecture of the Web, and does away with a need for point-to-point messaging infrastructures. Also, contrary to many existing agent platforms, it does not assume ideal conditions regarding liveness of agent processes and availability of perfect communication channels. The basic principles of this architecture are simple: It conceives of messages as entries in persistent data stores accessible via normal HTTP operations, and models dependencies between these messages through an explicit graph structure, where causal and temporal links between messages in a protocol are exposed to agents via Web APIs. This enables avoiding redundant messaging in broadcast situations, failure recovery and management of â&#x20AC;&#x153;staleâ&#x20AC;? interactions, lightweight ex post modification of previous interactions, as well as global monitoring and analysis of coordination processes. Also, it leverages the architecture of the Web to enable lightweight communication and is oblivious to the degree of centralisation applied in systems design. We describe a prototypical implementation of our architecture in a typical application scenario that allows us to demonstrate its benefits. Our experiments with a deployed prototype show that our approach oâ&#x2020;ľers significant advantages in terms of scalability and robustness. The remainder of the paper is structured as follows: We start by introducing an example scenario in section 2 that serves to illustrate our framework, and is also later used in our experiments. Section 3 introduces our formal framework for modelling conventional agent interaction protocols and their semantics. Our data-driven architecture is presented in section 4 together with a discussion of its properties. Experiments are presented in section 5, and after reviewing related work in section 6, section 7 concludes.

Example

A typical social computation scenario that involves large-scale agent collectives, and which we will use for illustration purposes throughout the paper, is ridesharing (see, for example, blablacar.com and liftshare.com), where travellers (drivers and passengers) request rides posting location, price, and possibly other constraints. Ridesharing is a representative example both due to the range of functions it requires (matchmaking, negotiation, teamwork) and because it exhibits many characteristics of real-world collective collaboration systems (many users, asynchronous communication, heterogeneity of user platforms). The team task protocol shown in figure 1 describes a possible coordination mechanism that could be used in such a system, following a traditional agentbased model which involves an orchestrator o and task peers p in an 1:n relationship. In the top section of the diagram, peers ADVERTISE their capability to play role r in action a, e.g. driving a car, occupying a passenger seat, or paying a driver in the case of ridesharing. This advertisement is acknowledged simply to terminate this stage with a definite response. In the subequent matchmaking stage, peers may REQUEST a task, i.e. a plan that will achieve getting from initial state I to goal state G, subject to certain constraints C (e.g. a price limit).

p ADVERTISE(r, a) ACK ADVERTISE(r, a) REQUEST(I, G, C)

NO SOLUTIONS(I, G, C)

INFORM TASK(t)

REJECT(t)

AGREE(t)

INFORM INVALID(t)

START(t) UPDATE(t, r, ai , st) ACK UPDATE(t, r, ai , st) RATE(t, F ) ACK RATE(t, F )

Fig. 1. The team task protocol

Based on requests from various agents and by using the capabilities they have advertised, o proposes a possible task t that would involve a specific plan ⇡ to be executed, and a role assignment for the participants clarifying which agent has to perform which actions, or tells p that NO SOLUTIONS can be found. In the case of ridesharing, the plan would be the ride specification, quoting a price, time, and possibly other constraints (e.g. whether smoking is allowed). If a peer AGREEs to a task, this might have become invalid in the meantime because others have REJECTed it. If the task is still valid, and once all participants agree, the orchestrator invites participants to START executing the plan, after which p can UPDATE the execution status st of individual steps ai in the plan (e.g. “we reached the destination”) or provide feedback reports F regarding the task (e.g. “the driver was driving too fast”). These steps can be repeated depending on how many steps there are in t in the case of UPDATE, or without limitation in the case of RATE. If p rejects a task, more tasks might be suggested until no more solutions exist. Note that the protocol deliberately contains a few “imperfections”: First

of all, once a peer agrees, she will not be notified if other participants reject the task she agreed too. Secondly, there is no timeout for the negotiation. Hence, a peer will never be told that the negotiation failed because some participants did not respond. Below, we will explain how our proposed architecture results helps address such issues without complete protocol re-design.

Formal framework

Before proposing our own approach, we introduce a formal framework that allows us to capture action and communication semantics in a decentralised agent-based system. Our formalism is based on a plan-based semantics of communication and action, i.e. we consider a state transition system where messages and actions (we use this term to denote non-communicative actions that change the environment state) modify the values of state variables. While this follows traditional Stripsstyle planning formalisms [6], note we are not assuming the use of actual planning algorithms in the system. The notation just gives us a simple, generic way of describing a discrete, distributed state transition system. Let V = {v1 , v2 , . . . , vk } variables that range over a domain of discourse D1 , and constraints c = {(v1 , D1 ), . . . , (vm , Dm )} denoting that vi 2 Di ✓ D, where all vi are distinct, and {v1 , . . . , vm } ✓ V is called the domain dom(c) of constraint c. We call a constraint failed if any for any vi 2 dom(c) we have Di = ;, and write c = ? in this case. A substitution ✓ is a constraint {(v1 , E1 ), . . . , (vl , El )} that can 0 be applied to c to result in a new constraint c✓ = {(v1 , D10 ), . . . , (vm , Dm )} such 0 that for all vi = vj with vi 2 dom(c) and vj 2 dom(✓) we have Di = Di \ Ej . A 0 substitution is called a grounding if |D10 | = |D20 | = . . . = |Dm | = 1. A grounding is admissible if c✓ 6= ?, and we write bcc for the set of all possible groundings or instances of c. Entailment among two constraints is defined as c |= c0 if bcc ✓ bc0 c, i.e. c is a stricter constraint satisfied by some groundings of c0 . Next, we introduce agents and their actions. Assume agents A = {a1 , a2 , . . . an }, and, in slight abuse of notation, let their names also be valid variable values, i.e. A ✓ D. We consider a timed system with execution steps T = {t1 , t2 , . . .} using a global clock shared by all agents. For any variable v 2 V , ai may have a local copy whose value can change over time. We write vij for the value of v for agent i at time step j (Vi denotes agent i’s local variables, and Vij their values at time j). We may drop the subscript and write “v = d” for some variables whenever all agents’ local copies agree on the variable value, i.e. v = d , 8i .vi = d. Fluents F = {f1 , . . . , fk } ✓ V are variables that describe system states, and exclude any auxiliary variables not used to reflect system state, e.g. the roles denoting senders and receivers of messages in message schemata (see below). A state specification S is a constraint with dom(S) ✓ F , and is used to represent the set of all states s 2 S with s |= S. A state s can be viewed as a constraint that is a full variable assignment {(f1 , {d1 }), . . . , (fk , {dk })} for all 1

Di↵erent types Dj can be used here to accommodate di↵erent types of variables. These are omitted for simplicity.

domain fluents in F . When referring to states, we will write sji to denote a full assignment to concrete values for agent i at time j. An action ac = h{a1 , . . . , ak }, pre, e↵ i is performed by agents {a1 , . . . , ak } ✓ A and is associated with two constraints, its preconditions pre and e↵ects e↵ with dom(pre) [ dom(e↵ ) ✓ F . For any s 2 S with s |= pre(ac) (ac is applicable in s), execution of ac results in a successor state succ(s, ac) = s0 where s0 = s\{(v, D)|v 2 dom(e↵ (ac))} [ e↵ (ac). In other words, if ac is applicable in s, then the successor state results from removing the values of all a↵ected variables in dom(e↵ (ac)) from s and adding their new values as per e↵ (ac). Note that these actions need not be “ground” in the sense that the fluents they involve need to have specific single values before or after the action. A plan ⇡ = hac 1 , . . . , ac n i is a sequence of actions such that ac 1 is applicable in the states represented by the initial state specification I, i.e. I |= pre(ac 1 ), and each ac i is applicable in succ(s, hac 1 , ac 2 , . . . , ac i 1 i) (where succ is canonically extended to sequences of actions), for all 2  i  n and s |= I. Plans provide the definition for any well-defined sequence of actions that is feasible given the specifications of these actions and the current system state. A plan ⇡ is a solution for a planning problem hI, G, Aci with initial state specification I and goal state specification G if succ(s, ⇡) |= G for all s |= I, i.e. if its execution from any state that satisfies I results in a state that satisfies G. Given this general framework, we can proceed to defining the structure and semantics of agent protocols. Definition 1 A message schema µ =MSG(se, re, c, pre, e↵ ) is a structure with label MSG, where se and re are variables for the sender(s) and receiver(s) of the message, constraint c denotes the message content, and precondition/e↵ect constraints pre and e↵ with dom(pre) ✓ V and dom(e↵ ) ✓ V .

In figure 1, such schemata label the edges connecting the individual boxes on the swimlanes of the diagram (which represent sender p and receiver o), e.g. REQUEST(p, o, {(ip , {I}), (gp , {G}), (cp , {C})}). For readability, we omit preconditions and e↵ects and the constraint notation assigning concrete values to p’s local variables for I, G, and C is not used in the diagram (the request implies, for example, that p’s local variable ip has value I at the time of sending). To define the structure of a protocol, we introduce a graph that is “dual” to that in the diagram, in that is has message schemata for nodes and edges for decision points: Definition 2 A protocol graph is a directed graph P = h , i whose node set includes a set of message schemata uniquely identified by message labels, with additional root and sink nodes start and end (e↵ (start) = pre(end ) = ;). Its edges are given by a mapping : ! 2 . Every edge (µ, µ0 ) with µ0 2 (µ) is labelled with e↵ (µ) and pre(µ0 ).2 We present the protocol graph for part of the team task protocol (preconditions end e↵ects are only shown for REQUEST): 2

Throughout the paper, we adopt the convention of referring to elements in a structure x = hy, y 0 , . . .i as y(x), y 0 (x) etc.

AGREE(p, o, t)

INFORM TASK(o, p, t)

INFORM INVALID(o, p, t)

{(I , {I \ I}), (G , {G \ G})} REQUEST(p, o, I, G, C)

REJECT(p, o, t)

{(wants p , {G}), (sp , {I})} NO SOLUTIONS(o, p, I, G, C)

The example assumes that the precondition for REQUEST is {(wants p , G), (sp , I)} for p. The e↵ect for o, who is gathering planning problems from peers to propose a joint plan that solves all of them, is {(I⇤ , I⇤ \I), (G⇤ , G⇤ \G)} where “⇤ ” denotes the view o has of all peers. In other words, o’s strategy involves conjunctively narrowing down initial and goal states before suggesting a plan that satisfies all of them. To make the plan-based semantics of protocols concrete, we need to introduce messages as instances of schemata: Definition 3 A message is a structure m = hµ, Se, Re, ✓, ti where µ is a message schema, Se ✓ A and Re ✓ A are the (non-empty) sets of senders3 /receivers of the message, ✓ is a substitution for c(µ), and t the time the message was sent. The following definition defines when a message is admissible, i.e. it is a legal continuation of an observed interaction: Definition 4 For any protocol graph P , state st 2 S, and initial message sequence ⇡ = hstart, m1 , . . . , mt 1 i, define: h⇡, st i |=P mt

mt = end ^ end 2

(µ(mt

✓ =✓(m1 )✓(m2 ) · · · ✓(mt ) 6= ? ^ µ(mt ) 2 8i

2 Se(mt ). sti |= 2 Re(mt ). st+1 j

1 ))

(µ(mt

1 ))^

pre(µ(mt )✓) ^

|= succ(stj , µ(mt )✓)

This defines a message mt as admissible in the context of a current message sequence and state h⇡, st i, which we call a model for m, if either mt = end and its immediate predecessor was connected to the end node in P , or if (i) its schema µ(mt ) is a successor to that of the most recent message, (ii) the preconditions (e↵ects) of that schema are satisfied by all senders (receivers) of the message in timestep t (t + 1), and (iii) this is subject to the combined substitution ✓ that accumulates all the substitutions applied in previous messages (and which must itself be consistent).4 3

Allowing many senders in messages may seem counter-intuitive at first, but is useful for situations where a physical sender acts on behalf of a whole group, or to summarise identical messages received from various peers as one message in the data-driven model we introduce in section 4. Note that di↵erent semantics are possible here, which may assume that senders also have a modified state regarding their perception of receivers’ local variables after

In other words, an admissible message is interpreted as a planning action hSe [ Re, pre(µ(m)✓), e↵ (µ(m)✓)i, with the additional requirement that it extends the observed message sequence following P , and respects the substitions applied to earlier messages on the path that led to it. To extend this definition to message sequences, we can write h⇡, si |=P ⇡ 0 for any finite ⇡ 0 = hmt+1 , . . . , mt+k i i↵ ⌦ ↵ ⇡hmt+1 , . . . , mt+j i, succ(s, hmt+1 , . . . , mt+j i) |=P mt+j+1 for all 0  j  k 1. We write s |=P ⇡) i↵ hhi, si |=P ⇡. With this, we can proceed to define the semantics of a protocol through the set of admissible continuations it gives rise to in a specific state given an observed execution history: Definition 5 Let s 2 S and ⇡ a message sequence. If s |=P ⇡, the continuations J⇡Ks of ⇡ are defined as the (potentially infinite) set of sequences messages ⇡ 0 for which h⇡, si |= ⇡ 0 holds. We let J⇡Ks := ? if s 6|=P ⇡.

This completes our account of a simple and fairly generic plan-based semantics for agent interaction protocols. Our semantics does not make any specific commitment as to the actual semantic language (e.g. mentalistic, commitment-based, or deontic) used to specify constraints governing the exchange of messages. Instead, it specifies what message sequences are admissible under a shared protocol definition, and how message passing results in a synchronisation among agents’ local variables. For simplicity, we have assumed that no additional agent actions or exogenous events occur during protocol execution. Note, however, that such actions or events could be easily accommodated in the protocol graph as additional choices between successive messages without requiring additional formal machinery.

Data-centric Architecture

4.1

Framework

While conventional specifications of agent interaction protocols such as the ones considered above provide a very flexible framework for coordinating multiple agents, the point-to-point message passing they assume can be problematic in large-scale multiagent systems using potentially unreliable communication infrastructures, and operating over long periods of time, so that the contributions of agents occur at unpredictable points in time. Consider a real-world deployment of the protocol shown in figure 1 in a webbased ridesharing application with many users. If we use conventional message passing, this protocol would require n conversations for n task peers going on sending a message, or receivers inferring facts about senders’ previous states upon receipt of a message. Which of these variants is chosen is not essential for the material provided below.

REJECT(p, o, t) REJECT(a3 , o, t2 ) INFORM TASK(o, p, t) INFORM INVALID(o, p, t) REQUEST(p, o, I, G, C) REQUEST(a1 , o, I, G, C1)

INFORM TASK(o, {a1 , a2 }, t1 )

INFORM INVALID(o, a2 , t2 )

INFORM TASK(o, {a2 , a3 }, t2 )

REQUEST(a2 , o, I, G, C2)

AGREE(p, o, t)

REQUEST(a3 , o, I, G, C3)

AGREE(a2 , o, t2 )

REQUEST(a4 , o, I 0, G0 , C4 ) NO SOLUTIONS(o, p, I, G, C) NO SOLUTIONS(o, a4 , I 0 , G0 , C4 ) NO SOLUTIONS(o, a3 , I, G, C3)

AGREE(a2 , o, t1 ) AGREE(a1 , o, t1 )

Fig. 2. Data-centric model of part of the ridesharing protocol

in parallel, and o would need to maintain separate internal data structures to track which agents have already agreed to the task, which of them may provide execution updates, etc. Also, these conversations would have to remain “open” indefinitely, unless strict time limits were imposed on these parts of the protocol. Another drawback is that many data objects such as identical requests, suggested tasks, or information about invalid/agreed tasks and initiation of task execution would have to be sent repeatedly from/to di↵erent peers. Finally, if we wanted to de-couple di↵erent parts of the protocol that are not causally linked to each other in order to allow for a more flexible execution of the di↵erent stages of the protocol (e.g. advertising capabilities is unrelated to negotiation), this would involve creating separate protocols, and managing synchronisation among variables that are not local to a single protocol. Before introducing our data-driven architecture to address some of these issues, we present its instantiation for the negotiation part of our team task protocol as an example in figure 2. The diagram combines the original protocol graph (message schemata in rounded boxes, connected with bold grey arrows) with message stores attached to every schema. These message stores contain messages exchanged by the participants so far, and links (black arrows) between messages that were generated in response to each other. As before, we omit preconditions and e↵ects as well as timestep labels and the details of content constraints for readability. Using linked message stores enables us to replace message passing among agents by inspecting and modifying the contents of persistent message repositories, which is the key idea behind our approach. We start by introducing protocol execution graphs (PEGs), which provide the link structure arising from observed message sequences: Definition 6 Let ⇧ = {⇡1 , . . . , ⇡k } a set of protocol executions where ⇡i = hm1 , . . . , mj , . . . , mti i and ⇡ij = mj , and M (⇧) = {⇡ij |⇡i 2 ⇧} the set of all messages in ⇧. The PEG is a directed graph P (⇧) = hM (⇧), (⇧)i with edges (⇧) = {(m, m0 )|9⇡i 2 ⇧.m = ⇡ij ^ m0 = ⇡ij +1 }.

For any set of messages, we define a mapping ' : M ! (P ) to the nodes in P , where '(m) = µ if 9µ 2 (P ).µ = µ(m) and ? else. Given this, ⇡i 2 ⇧ is associated with a generating path '(⇡i ) := h'(m1 ), . . . , '(mti )i in P . A PEG has every two messages connected that correspond to message schemata connected in the protocol graph the executions followed. Note that whenever the protocol graph contains cycles, a PEG may contain unfoldings of these cycles (and thus message schemata may appear repeatedly in a generating path '(⇡i )). Furthermore, even though the distinct message schema labels guarantee that every message has a unique node in the protocol graph assigned to it, identical messages (sent to or from di↵erent agents) appear only once in the graph. On the other hand, if two messages have identical senders, receivers, and conent, they would count as di↵erent nodes in the PEG if they were part of di↵erent conversations (as they are annotated with di↵erent timestamps). In figure 2, the nodes of the PEG are the entries of the boxes under each message schema, and its edges are depicted as black arrows connecting these nodes. As concerns continuations, we can extend our previous definitions canonically to sets by letting h⇧, si |=P m i↵ 9⇡ 2 ⇧.h⇡, si |=P m and J⇧Ks := [⇡2⇧ J⇡Ks . The final step in our construction is to identify message stores, one for each message schema µ appearing in the protocol graph (shown as square boxes in figure 2). These provide a somewhat orthogonal view of the PEG, focusing on specific message schemata: Definition 7 A message store is a set of messages Mµ := {m 2 M (⇧)|µ(m) = µ} containing all message instances for a message schema µ. It supports the following operations given m = hµ, Se, Re, ✓, ti: – – – –

get(a, Mµ ) = {m 2 Mµ |a 2 Re(m)} add (a, Mµ , m) = Mµ , a 2 Se(m) ^ Mµ0 = Mµ [ {m} del (a, Mµ , m) = Mµ0 , a 2 Se(m) ^ Mµ0 = Mµ \{m} mod (a, Mµ , m, m0 ) = add (a, del (a, Mµ , m), m0 )

The operations add , del (and mod ) leave Mµ unchanged if their arguments do not satisfy the above constraints. The main reason we define message stores as first-order citizens in our architecture is that they permit the definition of operations which can be used to emulate sending and receiving messages. These operations, which are realised as physical messages over the network (but we distinguish from protocol messages) allow an agent to create a new message if it is a sender of that message (a↵ ), and to inspect those messages in a store that have her as receiver (get). We also permit deletion of previous messages through del for reasons that will become clear below, and modification of an existing message through mod (a combination of del and add ). Using these methods, a message such as REQUEST(a1 , o, I, G, C2 ) in figure 2 would be realised as a sequence of calls add (a1 , Mµ , REQUEST(a1 , o, I, G, C2 )) ! get(o, Mµ ) where Mµ is the message store for REQUEST. This enables a di↵erent way of processing the protocol specification, which is based on an ability to

generate responses to any message contained in a message store without requiring a control flow that manages every conversation sequence individually: Proposition 1 Let st 2 S and m = hµ, Se, Re, ✓, ti a message with h⇧, st i |=P m. We define op = get(Re, add (a, M (µ), m))) where a 2 Se and get(Re, . . .) is shorthand notation for all receivers executing the get operation in any ordering. We assume that each get/add operation takes one timestep. Further, we assume that the add operation is only performed if sti |= pre(µ✓) for all ai 2 Se, and all aj 2 Re update their local state stj to st+1 = succ(stj , µ✓) instantly when they observe any new message m. j Then, if |Re| = k, and no other actions or message store operations are executed between t and t + k, it holds that Mµ0 = op(M ) = M [ {m} in st+k and succ (k) (st , op) = succ(st , m).5 Proof. The proof for this proposition requires only straightforward application of the respective definitions. The operation op on Mµ involves one sender add ing m to the message store (which implies Mµ0 = op(M ) = M [ {m}), and k receivers Re getting the result. Since the message is admissible, we would have sti |= pre(µ✓) for all i 2 Se and st+1 |= succ(st , µ✓) if this message was sent. j We assume that the get message is only sent if the sender can locally satisfy the preconditions of m, and that receivers incorporate the e↵ects of any new message observed on a message store locally (though for a given agent this will only happen at st+l for some 1  l < k depending on when the receiver performs the get operation). Given this, and under the assumption that no other action occurs while op is being executed, we have succ (k) (st , op) = succ(st , m). ⌅ The importance of this proposition is twofold: Firstly, it shows how message store operations can correctly replace any protocol message exchange. Secondly, it reveals that an additional |Re| get operations are necessary to produce the same outcome, and that the receivers monitor the contents of each relevant message store continually. On the other hand, it is sufficient if the time k required for these updates is less than the time that passes until further messages being sent to or from the recipients, or other actions are executed that a↵ect their local state. Our model also allows for more unusual operations on message stores, for example deletions of past messages. While this might seem counterintuitive, we discuss in section 4.2 how it can be very useful in real applications. Deletions require a more complex “rollback”, which obviously cannot undo the global state of the system, but for which we can establish a weaker result: Proposition 2 For any message m, let next(m, ⇧) = {m0 |(m, m0 ) 2 (⇧)} with next ⇤ (m, ⇧) as its reflexive and transitive closure. Removing next ⇤ (m, ⇧) results in a PEG ⇧ 0 = h 0 , 0 i where 0 = ⇧\next ⇤ (m, ⇧) and 0 = (⇧) \{(m0 , m00 )|{m0 , m00 } \ next ⇤ (m, ⇧) 6= ;}. It holds that: 5

The superscript (k) is added to the succ function here to indicate that op requires this number of timesteps.

⇤ 0 0 1. If 8m0 2 next ⇤ (m, ⇧). Mµ(m 0 ) = del (a, Mµ(m0 ) , mi ) and 8m 62 next (m, ⇧). 0 0 0 0 Mµ(m0 ) = Mµ (m ), then Mµ = Mµ (⇧ ) for all µ and some a 2 A. 2. For any m 2 ⇧ 0 we have h⇧ t(m) , st(m) i |=P mj where ⇧ t(m) and st(m) are the contents of the original PEG and state at time t(m) when the message was created.

Proof. Statement 1. claims that deleting all successors of m from the respective message stores, and leaving all other message stores unchanged will restore the property that any message store Mµ in the system contains all messages instantiating a schema µ in ⇧ 0 . This is trivially the case, as ⇧ 0 is identical to ⇧ with the exception of having m and all its successors and their adjacent edges removed. To see that stement 2. holds, it suffices to observe that all remaining messages in ⇧ 0 are either a predecessor of m, or occur on paths that do not contain m or any of its successors. It follows that their validity at the time of their creation is maintained if we remove m and all subsequent messages. ⌅ The main implication of this result is that when a message is deleted from a store, then all its successors need to be deleted with it to maintain some level of consistency (this also assumes that no other messages or modifications on message stores take place in the meantime). Even with these provisions, the level of consistency achieved is obviously much weaker than what can be guaranteed for add operations, as deletions remove paths that were previously available, and only paths una↵ected by the removal of m have identical continuations as before the removal. Also, the system state may have changed compared to when the original messages were sent, so that we may not be able to track what interactions brought it about. Finally, we should note that the two properties we have just established apply to mod operations as a consequence of those operations being abbreviations for a composition of del and add calls. 4.2

Discussion

To illustrate the use of our model, let us revisit the example from figure 2 in more detail: We have six initial REQUEST messages from agents a1 , . . . a4 , which result in possible tasks t1 for {a1 , a2 }, t2 for {a2 , a3 } and no solution for a4 (maybe because his requirements don’t match those of any other peers). One immediately obvious advantage of our approach here is that only INFORM TASK messages need to be “sent” to two agents each (sets {a1 , a2 } and {a2 , a3 }). Next, we have the situation that a2 AGREEs to t2 and a3 REJECTs this task. We assume that a2 is the driver and needs to agree first (no ride can be taken without a car), but there is no such restriction regarding rejection, which any participant of the task can issue at any point. Now if a3 issues the rejection first, a2 will receive an INFORM INVALID response, as shown in the diagram, and no agreement on t2 will be possible anymore. If a2 has already agreed, however, this agent will never be notified of a3 ’s rejection, a problem we already mentioned in section 2. One solution to this problem would be to add an edge from INFORM INVALID to AGREE, which was not included in the original protocol of figure 1. Since previous INFORM TASK messages also gave a2 the option t1 , she

can now agree to this task, and after a1 agrees, too, the next message would be START to initiate task execution. This is generally how protocol flexibility has to be accommodated in normal agent protocols – every possible agent behaviour has to be accounted for by providing additional paths that enable other agents to respond appropriately. In fact, the INFORM INVALID!AGREE edge would not work here, as no alternative possible task t1 would be known to a2 (unless a list of all possible tasks was sent with INFORM TASK from the outset, which would doubtlessly complicate the workflow further). So, we would have to backtrack at least to the level of INFORM TASK (in a “task no longer available, here’s another alternative” fashion) to allow a2 to make alternative choices. Or we would leave a2 ’s AGREE message without response, whereupon we would rely on the decision logic of the agent to resolve the problem (e.g. by having her assume failure after some time). Our data-centric view a↵ords us with additional ways of dealing with such problems. Firstly, because of our protocol semantics, the INFORM INVALID option is easy to accommodate, as a2 can still AGREE to any task contained in the INFORM TASK message store. Secondly, the orchestrator could remove INFORM TASK (o, {a2 , a3 }, t2 ) (as owner of this message) after receiving a REJECT from a3 , and a2 would be able to anticipate that its previous AGREE message has become invalid (it could even be del eted by o if we used this type of call and gave the orchestrator appropriate permissions for this operation on messages not created by herself). Under these circumstances, not even the INFORM INVALID message itself would be necessary, thus making the protocol even simpler. Finally, we could give a3 permission to add INFORM TASK messages (for example with possible alternative tasks that were not generated by o) or post mod ifications to t2 in order to make the task acceptable for her, thus increasing the chances that successful agreement would be reached. Thus, even though in principle the possible computations that can be jointly performed by agents are of course no di↵erent from the agent-centric view, our data-centric view allows much more flexibility in organising the interactions that lead to those computations, without requiring that the overall protocol needs to be significantly re-designed to accommodate additional functionality. For example, we could have orchestrators post arbitrary new tasks in an asynchronous way (for the same requests, or incrementally, as more potentially matching agents join), we could easily allow drivers to agree to several tasks in parallel, or let peers remove their previous requests if they are no longer interested in them.

Experimental Results

To establish whether the scalability and robustness we expect can actually be observed in a real-world implementation, we have developed a prototypical webbased system that runs the protocol depicted in figure 1, and evaluated it experimentally in the ridesharing domain. Our experiments below focus on the matchmaking and negotiation part of the protocol (from REQUEST to START), as this involves most dependencies among individual behaviours, and requires

involves solving a complex combinatorial problem for the orchestrator agent o that involves calculating exponential numbers of possible rides presented to every driver and passenger. Instead of trying to get agreement or rejection to a single potential ride from every peer involved, our architecture enables us to constantly update all rides available to every peer in the system. We also use two further “non-standard” protocol operations: One is to automatically generate INFORM INVALID messages for other participants when an agent REJECTS a ride, and the other is to delete all INFORM TASK messages linked to a peer’s request once a di↵erent ride for that peer has been agreed. Since in practice there is no global clock for synchronisation, all agents periodically poll the stores they are interested in (INFORM TASK to check what the currently available rides are, and START/INFORM INVALID to determine whether a ride has been agreed/can no longer be agreed). In terms of the execution engine, our implementation involves a single server which contains all message stores, and exposes operations on them through a simple RESTful Web API. The server runs Node.js, a non-blocking event-driven JavaScript library, and has separate processing queues associated with di↵erent message stores, which asynchronously process individual “platform jobs” for di↵erent client calls. Note that running the platform on a single server is not a requirement – in principle every message store could be located on a di↵erent server, including agent nodes that implement an HTTP interface. Our first experiment examines the overall scalability of the platform. We create artificial “groups” of size k in a population of n agents such that all the requests inside a group match, and we can artificially control how many rides will be created. Our first experiment involves up to 10 groups of 6, 9, and 12 agents, i.e. a total of 60, 90, 120 agents, where the ratio of drivers d to passengers p is 1/2 (i.e. p/d 2 {2/4, 3/6, 4/8} for each group size). Note that the respective number of possible rides generated in each group is (2p 1) ⇤ d as there is a di↵erent proposal for every subset of passengers, and the rides di↵erent drivers may o↵er to a group overlap. This means that 30/189/1020 rides have to be created for each group, i.e. the system has to deal with up to 10200 rides overall as we keep adding groups. Note also that, since all ride requests and agreements to rides occur in very close succession, the load of this system is similar to a real-world system that would experience this level of usage every few minutes (in reality, of course, users take much much longer to check updates and respond), so it is in fact representative of a very large scale real-world application. Finally, to maximise the amount of messages exchanged and the duration of negotiation, drivers accept only the maximally sized ride, and passengers accept all rides. The top two plots in figure 3 show the average time taken in seconds (across all agents, and for 20 repetitions for each experiment, with error bars to indicate standard deviations) for matchmaking (REQUEST and INFORM TASK) and negotiation (all further messages up to and including START), respectively. As can be seen from these plots, even though every agent has a built-in delay of 2 seconds between any two steps, even when when there are 120 agents in the system, the average time it takes an agent to get information about all rides acceptable to her/complete the negotiation of a ride is around 50s/80s even in the largest configurations.

Fig. 3. Experimental results

In the second experiment, we investigate the cumulative e↵ect of adding delays and message failures on the total execution time of an entire negotiation for a ride, in order to assess how robust the system is. For this, we artificially increase the delay between any update an agent receives and its successive operation from 2s to 5s, 10s, and 20s. We use these artificial delays also to emulate failure, e.g. when network resources are temporarily unavailable. The bottom plot in figure 3 shows the results for this experiment, for a group size of 9 and 5 groups (45 agents in total), showing measurements for matchmaking, negotiation, and the total lifespan of an agent (from creation to agreement). As can be seen, the overall lifespan of an agent increases by a factor of 3 to 4 here when the delay increases by a factor of 10, which is a good indication that the system degrades gracefully under increasing perturbation. Moreover, what is interesting is that the time taken for negotiation, which involves the highest number of messages to the orchestrator (as all passengers accept all rides) only increases by a factor between 1.5 and 2. This is because the larger delays require less e↵ort for matchmaking and computing rides, and the orchestrator has more time to process negotiation-related messages during these gaps. This nicely illustrates how separating the processing of di↵erent message stores leads to e↵ective load balancing for any agent that has to engage in di↵erent interactions concurrently.

Related Work

The idea of coordinating distributed processes through a shared coordination medium is not new. It can be traced back at least to the blackboard systems [4] used in early distributed knowledge-based systems. In distributed computing, similar ideas led to coordination languages like LINDA [7]. While these systems initially involved either fixed sets of coordination primitives or built-in, application-dependent coordination strategies, they were later used in platforms like TuCSoN [11] to develop programmable behaviours for the coordination data structures. Our approach di↵ers from this line of work in that we do not attempt to replace the protocol-based interaction models used in mainstream agents research. Instead, we maintain their advantages in terms of supporting complex specifications of sequential interactions and agent communication language semantics. Mapping these onto a data-driven architecture gives us the “best of both worlds”, as it allows us to capture complex agent interactions while separating coordination from computation. An architecture that takes a similar protocol-centric approach to the regulation of agent behaviours is OpenKnowledge [12], which allows declarative specifications of interaction protocols to be directly executed in an open, peer-to-peer platform. While its automation of executing protocols from their specification is more advanced here than in our approach, it involves agents e↵ectively handing over control to coordinators that “run” the agent processes (the agent can still make autonomous decisions regarding di↵erent choices available in the protocol, but the platform executes the protocol by invoking these local decision methods from outside). The di↵erence to our approach is that we do not provide an execu-

tion platform that includes the agent processes themselves, but prefer to restrict the computational coordination process only to what is absolutely necessary. Previous work most closely related to ours, however, is at the intersection of agents and service-oriented computing research. The authors of [2] present a method for mapping complex agent conversations to web services, without providing, however, a formal framework or a concrete implementation. Only very recently Singh [14, 15] addressed the service-based view of agent protocols by proposing a formal language and a computational architecture that supports it. His approach bears close resemblance to our work: It considers protocols in terms of information schemas without any additional control flow constructs, defines semantics in terms of histories of past message exchanges, and proposes an architecture that enables agents to asynchronously and atomically process individual messages, supporting distributed interactions that have multiple loci of enactment. The main diâ&#x2020;ľerence to our approach is that the semantics provided in this model does not take account of non-message actions and local state transitions, instead focusing more on protocol verification. Also, no quantitative performance results for an implementation of this system are presented. It is worth mentioning, that, with the exception of [14], all of the above approaches involve some kind of middleware that relies on a bespoke communication architecture and platform that the agents must comply with. Moreover, while these platforms could be exposed, at least in principle, over normal Web APIs, agent designers would still have to be familiar with the specific languages used by them. In our framework, we do not only do away with such specific middleware. We also reduce the language specification for messages and constraints to a very general form, through constraints that are general variable restrictions, and messages with simple pre- and postconditions. As long as ontological agreement can be assumed regarding the semantics of individual variables and their domains (which is also a prerequisite for all of the above approaches), our APIs should be straightforward to use. In these respects, our work is heavily influenced by the REST paradigm [5], in that it uses ordinary Web resources as the means of exposing state to peers in order to coordinate the workflow between them. To our knowledge, there have been no attempts to formalise the semantics of this paradigm, and while our work does not aim to provide such semantics for the general case, it can be seen as a contribution toward a better overall understanding of REST itself.

Conclusions

In this paper, we have presented a data-driven architecture for coordinating agent collectives on the Web that is aimed at bridging the gap between work on agent interaction protocols and modern Web-based applications used commonly in areas such as social and collective computation. We presented a formal framework that allows us to specify the semantics of our architecture, and which allowed us to introduce functionality that is not available in normal agent-based systems platforms. Our experimental results with a prototypical implementation

show that it can handle complex interactions in a lightweight way, producing minimal overhead while providing good scalability and robustness properties. We summarise the main benefits of our approach: Firstly, there are no sequential distributed processes that need to rely on a standing line of communication, since all data operations are atomic, and can be easily repeated in case of failure. As our experiments show, the overhead of the additional link structure that has to be stored and the frequent “pull” operations from agents do not seem to a↵ect performance significantly. Secondly, in a real Web deployment, we could directly benefit from the standard caching facilities of Web servers that can store frequently reused resources. Thirdly, coordination platforms can cross-check parallel interactions and apply global constraints to the overall interactions flexibly. Fourthly, since all operations are atomic, the decision logic can be devolved to components processing data in parallel whenever di↵erent steps are independent. This also provides guidance for designing agents’ internal reasoning mechanisms, or for “splitting” functionality into several agents. Finally, message stores and the linkage between them provide a direct “data” view to the ongoing interactions at a global level, thus facilitating analysis, prediction, and ease of mapping to other structures such as provenance information. In fact, all operations in our architecture can easily be captured using standard formats like PROV6 , and our implementation supports this through full integration with a live PROV server. As regards future work, on the practical side, we plan to focus on developing an automated procedure for generating implementations of our architecture directly from a given protocol specification. On the more theoretical side, we would like to develop formal procedures to detect and decouple di↵erent parts of a coordination protocol where these are not causally linked.

Acknowledgments

The research presented in this paper has been funded by the European Community’s Seventh Framework Programme (FP7/2007-2013) under grant agreement n. 600854 “SmartSociety – Hybrid and Diversity-Aware Collective Adaptive Systems: Where people meet machines to build smarter societies” (http://www.smartsociety-project.eu/).

References 1. S. Ahmad, A. Battle, Z. Malkani, and S. D. Kamvar. The Jabberwocky Programming Environment for Structured Social Computing. In Proceedings of the 24th Annual ACM Symposium on User Interface Software and Technology (UIST 2011), pages 53–64, Santa Barbara, CA, 2011. 2. L. Ardissono, A. Goy, and G. Petrone. Enabling conversations with web services. In J. S. Rosenschein, T. Sandholm, M. Wooldridge, and M. Yokoo, editors, Proceedings of the Second International Joint Conference on Autonomous Agents and Multiagent Systems (AAMAS 2003), pages 819–826, 2003. 6

See http://www.w3.org/TR/prov-overview/

3. A. K. Chopra, A. Artikis, J. Bentahar, M. Colombetti, F. Dignum, N. Fornara, A. J. I. Jones, M. P. Singh, and P. Yolum. Research Directions in Agent Communication. ACM Transactions on Intelligent Systems and Technology, 4(2):1–23, 2013. 4. R. Englemore and T. Morgan, editors. Blackboard Systems. Addison-Wesley, Reading, MA, 1988. 5. R. T. Fielding and R. N. Taylor. Principled Design of the Modern Web Architecture. ACM Transactions on Internet Technology, 2(2):115–150, 2002. 6. R.E. Fikes and N.J. Nilsson. STRIPS: A new approach to the application of theorem proving to problem solving. Artificial Intelligence, 2(3-4):189–208, 1971. 7. D. Gelernter and N. Carriero. Coordination languages and their significance. Communications of the ACM, 35(2):97–107, 1992. 8. E. Law and L. von Ahn. Human Computation. Synthesis Lectures on Artificial Intelligence and Machine Learning. Morgan & Claypool Publishers, 2011. 9. G. Little, L. B. Chilton, M. Goldman, and R. C. Miller. TurKit: Human Computation Algorithms on Mechanical Turk. In Proceedings of the 23nd Annual ACM Symposium on User Interface Software and Technology (UIST 2010), pages 57–66, 2010. 10. T. W. Malone, R. Laubacher, and C. Dellarocas. The collective intelligence genome. Sloan Management Review, 51(3):21–31, 2010. 11. A. Omicini and F. Zambonelli. Tuple centres for the coordination of internet agents. In Proceedings of the 4th ACM Symposium on Applied Computing, San Antonio, TX, February 1999. 12. D. Robertson, A. Barker, P. Besana, A. Bundy, Y.-H. Chen-Burger, D. Dupplaw, F. Giunchiglia, F. van Harmelen, F. Hassan, S. Kotoulas, D. Lambert, G. Li, J. McGinnis, F. McNeill, N. Osman, A. Perreau De Pinninck, R. Siebes, C. Sierra, and C. Walton. Models of interaction as a grounding for peer to peer knowledge sharing. In T. S. Dillon, E. J. Chang, R. Meersman, and K. Sycara, editors, Advances in Web Semantics I, volume 4891 of Lecture Notes in Computer Science, Berlin, Heidelberg, 2007. Springer-Verlag. 13. M. Rovatsos. Multiagent systems for social computation. In A. Lomuscio, P. Scerri, A. Bazzan, and M. Huhns, editors, Proceedings of the 13th International Joint Conference on Autonomous Agents and Multiagent Systems (AAMAS 2014), Paris, France, 5th-9th May, 2014. Second prize for best challenge paper. 14. M. P. Singh. LoST: Local State Transfer - An Architectural Style for the Distributed Enactment of Business Protocols. In Proceedings of the 9th International Conference on Web Services (ICWS), pages 57–64, Washington, DC, 2011. 15. M. P. Singh. Semantics and Verification of Information-Based Protocols. In V. Conitzer, M. Winiko↵, L. Padgham, and V. van der Hoek, editors, Proceedings of the Eleventh International Conference on Autonomous Agents Multiagent Systems (AAMAS 2012), pages 1149–1156, Valencia, Spain, June 4-8, 2012.