Merge pull request #136 from HyperAgents/scenario-manufacturing-disco…

…ver-behavior-specs

[Closes #119] Add manufacturing scenario for discovery of behavior specifications

domains/manufacturing-environments/README.md

@@ -28,6 +28,7 @@ Containment relations between workspaces and the entities they contain allow age
 Agents, artifacts, documents, and other entities in a Hypermedia MAS are hosted on one or multiple platforms that provide various services to support the MAS. Hosting relations allow agents to discover hosting platforms together with any services they may provide. For example, a Hypermedia MAS for manufacturing may be implemented using a FIPA-compliant platform such as JADE. An agent in such a system is then hosted on an instance of a JADE platform, which provides an HTTP-based message transport service for interacting with the agents it hosts. A hosting relation can be used to advertise the hosting platform in the Resource Profile of an agent. Dereferencing the URI of the hosting platform would then retrieve a Resource profile of the platform, including any services the platform may provide. 
 
 
+
 ## Interaction Vocabulary
 The following features aim to enable autonomous agents to discover and interpret how to exploit affordances for interacting with artifacts and other agents in hypermedia environments. 
 

domains/manufacturing-environments/discover-behavior-specifications/README.md

@@ -0,0 +1,51 @@
+# Discover Behavior Specifications
+
+Feature: Discovery of Behavior Specifications
+
+
+## Description
+An agent is situated in a manufacturing workspace that contains a robotic arm artifact. In the same workspace, a signifier signifies information about how to exploit a behavior possibility offered by the robotic arm artifact, specifically, information about how to move the gripper of the robotic arm. This information specifies a set of contraints on how to execute the action of moving the gripper:
+- the action execution should have an [`onto:GripperJoint`](https://ci.mines-stetienne.fr/kg/ontology#GripperJoint) as input;
+- the action execution should use on of the following hypermedia controls: 
+  - a form describing an HTTP request,
+  - a form describing a request based on the Constrained Application Protocol (CoAP).
+
+The agent discovers the signifier, that is exposed in the profile of the robotic arm artifact.
+Based on the signified information, that agent knows that interacting with the robotic arm artifact requires providing 
+an [`onto:GripperJoint`](https://ci.mines-stetienne.fr/kg/ontology#GripperJoint) as input, and sending either an HTTP or 
+a CoAP request based on the forms.
+
+## Competency Questions
+
+| ID | Question in Natural Language                                                                                              | Example                                                                                                                   |
+|----|---------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
+| q1 | What is the action execution specification that a given signifier signifies?                                              | Specification that signifier `ex:gripperMovable` signifies: `ex:moveGripperShape`                                         |
+| q2 | What is the specification of the input based on a given action execution specification?                      | Specification of the input for the execution of moving the gripper based on `ex:moveGripperShape`: `ex:gripperJointShape` |
+| q3 | What is the type of the input that an action execution should have based on a given action execution specification?       | Type of the input that the execution of moving the gripper should have based on `ex:moveGripperShape`: `onto:GripperJoint` |
+| q4 | What are the properties that the input of an action execution should have based on a given action execution specification? | Properties of the input that the execution of moving the gripper should have based on `ex:moveGripperShape`: `ex:hasGripperValue` |
+| q5 | What are forms that an action execution should use based on a given action execution specification?                       | Forms that the execution of moving the gripper should use based on `ex:moveGripperShape`: `ex:httpForm`, `ex:coapForm`    |
+
+
+
+## Glossary
+- **Behavior Execution**: A course of action performed by an agent upon exploiting a behavior possibility.
+- **Action Execution**: A behavior execution that is the execution of exactly one context-free action, e.g. of a context-free HTTP request.
+- **Input**: An input of an action, for example, in the representation of an action execution.
+- **Form**: A hypermedia control that describes how to execute an action as defined here, for example, an [`hctl:Form`](https://www.w3.org/2019/wot/hypermedia#Form).
+- **Signification of Behavior**: The act of revealing information about how to exploit a behavior possibility.
+- **Signifier**: see [Discovery of Signifiers](../discover-signifiers/README.md).
+- **Signifier Exposure**: see [Discovery of Signifiers](../discover-signifiers/README.md).
+- **Situatedness**: see [Discovery of Signifiers](../discover-signifiers/README.md).
+- **Workspace**: see [Discovery of Workspaces, Agents, and Artifacts in Hypermedia Environments](../discover-core/README.md).
+- **Resource Containment**: see [Discovery of Workspaces, Agents, and Artifacts in Hypermedia Environments](../discover-core/README.md).
+- **Artifact**: see [Discovery of Workspaces, Agents, and Artifacts in Hypermedia Environments](../discover-core/README.md).
+- **Agent**: see [Discovery of Workspaces, Agents, and Artifacts in Hypermedia Environments](../discover-core/README.md).
+- **Resource Profile**: see [Discovery of Workspaces, Agents, and Artifacts in Hypermedia Environments](../discover-core/README.md).
+
+
+## Recommendations
+- A signifier can signify a behavior specification for revealing information about how to exploit the relevant behavior possibility.
+- This scenario focuses on signifying a specification of a behavior execution that is the execution of exactly one action. However, a signifier may concern a behavior execution that is more generic than a single action execution, for example, in the case of a behavior that is executed through the execution of multiple actions. In the latter case, implementation details (e.g. an [`hctl:Form`](https://www.w3.org/2019/wot/hypermedia#Form)) will be directly associated to the specifications of the individual action executions rather than the overall behavior execution specification. This differentiation between behavior execution and action execution serves the following purposes:
+  -	Enabling the action-oriented design of hypermedia by keeping the implementation details attached to a specified action execution, considering that this is a simple design style, and a style easily relatable to how signifiers are used on the Web.
+  - Preserving the freedom of designers to create signifiers that concern the executution of behaviors with higher-level semantics on top of actions. 
+  - Providing extension points for defining behaviors based on how human agents reason about action and execute behaviors when exploiting behavior possibilities. 

domains/manufacturing-environments/discover-behavior-specifications/dataset.ttl

@@ -0,0 +1,56 @@
+@prefix hmas: <https://purl.org/hmas/> .
+@prefix onto: <https://ci.mines-stetienne.fr/kg/ontology#> .
+@prefix hctl: <https://www.w3.org/2019/wot/hypermedia#> .
+@prefix pto:   <http://www.productontology.org/id/> .
+@prefix htv: <http://www.w3.org/2011/http#> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix prov: <http://www.w3.org/ns/prov#> .
+@prefix xs: <https://www.w3.org/2001/XMLSchema#> .
+@prefix ex: <http://example.org/> .
+
+ex:ur5Profile a hmas:ResourceProfile;
+    hmas:isProfileOf ex:ur5;
+    hmas:exposesSignifier ex:gripperMovable .
+
+ex:ur5 a hmas:Artifact, pto:Robotic_arm ;
+    hmas:isContainedIn ex:manufacturingWksp .
+
+ex:manufacturingWksp a hmas:Workspace .
+
+ex:gripperMovable a hmas:Signifier ;
+    hmas:signifies ex:moveGripperShape .
+
+ex:moveGripperShape a sh:NodeShape;
+	sh:class hmas:ActionExecution ;
+ 	sh:property [
+		sh:path prov:used ;
+        sh:minCount 1;
+        sh:maxCount 1 ;
+    	sh:or (
+			[ sh:hasValue ex:httpForm ]
+			[ sh:hasValue ex:coapForm ]
+	    ) ;
+  	] ;
+	sh:property [
+		sh:path hmas:hasInput;
+    	sh:qualifiedValueShape ex:gripperJointShape ;
+    	sh:qualifiedMinCount 1 ;
+    	sh:qualifiedMaxCount 1
+  	] .
+
+ex:gripperJointShape a sh:NodeShape ;
+	sh:class onto:GripperJoint ;
+	sh:property [
+		sh:path ex:hasGripperValue ;
+        sh:minCount 1;
+        sh:maxCount 1 ;
+        sh:datatype xs:integer
+    ] .
+
+ex:httpForm a hctl:Form;
+    htv:methodName "PUT";
+    hctl:hasTarget <https://api.interactions.ics.unisg.ch/leubot1/v1.3.4/gripper>.
+
+ex:coapForm a hctl:Form;
+    htv:methodName "PUT";
+    hctl:hasTarget <coaps://api.interactions.ics.unisg.ch/leubot1/v1.3.4/gripper>.

domains/manufacturing-environments/discover-behavior-specifications/onto.ttl

@@ -0,0 +1,43 @@
+@base <https://purl.org/hmas/> .
+@prefix : <> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+
+#################################################################
+#    Classes
+#################################################################
+
+:ActionExecution a owl:Class ;
+                 rdfs:isDefinedBy :interaction ;
+                 rdfs:subClassOf :BehaviorExecution ;
+                 rdfs:comment "A behavior execution that is the execution of exactly one context-free action, e.g. of a context-free HTTP request."@en ;
+                 rdfs:label "action execution"@en,  "exécution de l'action"@fr .
+
+:BehaviorExecution a owl:Class ;
+                   rdfs:isDefinedBy :interaction ;
+                   rdfs:comment "A course of action performed by an agent upon exploiting a behavior possibility."@en ;
+                   rdfs:label "behavior execution"@en, "exécution du comportement"@fr .
+
+:Input a owl:Class ;
+       rdfs:isDefinedBy :interaction ;
+       rdfs:comment "An input of an action, for example, in the representation of an action execution."@en ;
+       rdfs:label "input"@en, "entrée"@fr .
+
+#################################################################
+#    Object Properties
+#################################################################
+
+:hasInput a owl:ObjectProperty ;
+              rdfs:isDefinedBy :interaction ;
+              rdfs:domain :ActionExecution ;
+              rdfs:range :Input ;
+              rdfs:comment "A relation between an action execution and the input that it has."@en ;
+              rdfs:label "has input"@en, "a une entrée"@fr .
+
+:signifies a owl:ObjectProperty ;
+           rdfs:isDefinedBy :interaction ;
+           rdfs:domain :Signifier ;
+           rdfs:range sh:NodeShape ;
+           rdfs:comment "A relation between a signifier and a node shape specifying a description of the expected behavior execution."@en ;
+           rdfs:label "signifies"@en, "signifie"@fr .

domains/manufacturing-environments/discover-behavior-specifications/q1.csv

@@ -0,0 +1,2 @@
+actionExecutionSpec
+http://example.org/moveGripperShape

domains/manufacturing-environments/discover-behavior-specifications/q1.rq

@@ -0,0 +1,12 @@
+prefix hmas: <https://purl.org/hmas/>
+prefix ex: <http://example.org/>
+prefix sh: <http://www.w3.org/ns/shacl#> 
+
+select ?actionExecutionSpec
+where {
+    ex:gripperMovable a hmas:Signifier ;
+        hmas:signifies ?actionExecutionSpec .
+    ?actionExecutionSpec a sh:NodeShape ;
+        sh:class hmas:ActionExecution .
+}
+order by ?actionExecutionSpec

domains/manufacturing-environments/discover-behavior-specifications/q2.csv

@@ -0,0 +1,2 @@
+inputSpec
+http://example.org/gripperJointShape

domains/manufacturing-environments/discover-behavior-specifications/q2.rq

@@ -0,0 +1,11 @@
+prefix hmas: <https://purl.org/hmas/>
+prefix ex: <http://example.org/>
+prefix sh: <http://www.w3.org/ns/shacl#> 
+
+select ?inputSpec
+where {
+    ex:moveGripperShape sh:property ?propertySpec .
+    ?propertySpec sh:path hmas:hasInput ;
+                  sh:qualifiedValueShape ?inputSpec .
+}
+order by ?inputSpec

domains/manufacturing-environments/discover-behavior-specifications/q3.csv

@@ -0,0 +1,2 @@
+inputType
+https://ci.mines-stetienne.fr/kg/ontology#GripperJoint

domains/manufacturing-environments/discover-behavior-specifications/q3.rq

@@ -0,0 +1,12 @@
+prefix hmas: <https://purl.org/hmas/>
+prefix ex: <http://example.org/>
+prefix sh: <http://www.w3.org/ns/shacl#> 
+
+select ?inputType
+where {
+    ex:moveGripperShape sh:property ?propertySpec .
+    ?propertySpec sh:path hmas:hasInput ;
+                  sh:qualifiedValueShape ?inputSpec .
+    ?inputSpec sh:class ?inputType .
+}
+order by ?inputType

domains/manufacturing-environments/discover-behavior-specifications/q4.csv

@@ -0,0 +1,2 @@
+inputProperty
+http://example.org/hasGripperValue

domains/manufacturing-environments/discover-behavior-specifications/q4.rq

@@ -0,0 +1,13 @@
+prefix hmas: <https://purl.org/hmas/>
+prefix ex: <http://example.org/>
+prefix sh: <http://www.w3.org/ns/shacl#> 
+
+select ?inputProperty
+where {
+    ex:moveGripperShape sh:property ?propertySpec .
+    ?propertySpec sh:path hmas:hasInput ;
+                  sh:qualifiedValueShape ?inputSpec .
+    ?inputSpec sh:property ?inputPropertySpec .
+    ?inputPropertySpec sh:path ?inputProperty .
+}
+order by ?inputProperty

domains/manufacturing-environments/discover-behavior-specifications/q5.csv

@@ -0,0 +1,3 @@
+form
+http://example.org/coapForm
+http://example.org/httpForm

domains/manufacturing-environments/discover-behavior-specifications/q5.rq

@@ -0,0 +1,21 @@
+prefix hmas: <https://purl.org/hmas/>
+prefix ex: <http://example.org/>
+prefix sh: <http://www.w3.org/ns/shacl#> 
+prefix prov: <http://www.w3.org/ns/prov#>
+prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+
+select ?form
+where {
+	ex:moveGripperShape sh:property ?propertySpec .
+	?propertySpec sh:path prov:used .
+	{ 
+		?propertySpec sh:hasValue ?form . 
+	}  
+	union
+	{ 
+		?propertySpec sh:or ?formShapeList . 
+		?formShapeList rdf:rest*/rdf:first ?formShape . 
+		?formShape sh:hasValue ?form .
+	}  
+}
+order by ?form

src/interaction.ttl

@@ -1,46 +1,66 @@
 @base <https://purl.org/hmas/> .
 @prefix : <> .
 @prefix owl: <http://www.w3.org/2002/07/owl#> .
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
-@prefix xml: <http://www.w3.org/XML/1998/namespace> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix cc: <http://creativecommons.org/ns#> .
 @prefix vann: <http://purl.org/vocab/vann/> .
-@prefix voaf: <http://purl.org/vocommons/voaf#> .
-@prefix foaf: <http://xmlns.com/foaf/0.1/>.
-@prefix schema: <http://schema.org/>.
 @prefix dct: <http://purl.org/dc/terms/>.
-@prefix skos: <http://www.w3.org/2004/02/skos/core#>.
+@prefix sh: <http://www.w3.org/ns/shacl#> .
 
 #################################################################
 #    Ontology Description
 #################################################################
 
-:interaction rdf:type owl:Ontology ;
+:interaction a owl:Ontology ;
+    owl:imports :core ;
     dct:title "Hypermedia MAS Interaction Ontology"@en, "Ontologie d'Interaction des SMA Hypermédias"@fr ;
-    dct:description "An ontology to describe interaction in Hypermedia Multi-Agent Systems."@en,
-    "L'ontologie pour décrire l'interaction dans les systèmes multi-agents hypermédias."@fr ;
+    dct:description "An ontology to describe interaction in Hypermedia Multi-Agent Systems."@en, 
+                  "L'ontologie pour décrire l'interaction dans les systèmes multi-agents hypermédias."@fr ;
     dct:issued "2023-01-13"^^xsd:date ;
     cc:license <https://creativecommons.org/licenses/by/4.0/> ;
     dct:creator <https://danaivach.inrupt.net/profile/card#me> ;
     dct:contributor <https://pod.inrupt.com/andreiciortea/profile/card#me> ;
     dct:contributor <https://pod.inrupt.com/smnmyr/profile/card#me> ;
     dct:contributor <http://ns.inria.fr/fabien.gandon#me> ; 
     cc:license <https://creativecommons.org/licenses/by/4.0/> ;
-    owl:imports :core ;
     vann:preferredNamespacePrefix "hmas" ;
     vann:preferredNamespaceUri <> .
 
-
 #################################################################
 #    Classes
 #################################################################
 
-:TestInteraction a owl:Class ;
-  rdfs:comment "testing the redirections"@en ;
-  rdfs:isDefinedBy :interaction .
+:ActionExecution a owl:Class ;
+                 rdfs:isDefinedBy :interaction ;
+                 rdfs:subClassOf :BehaviorExecution ;
+                 rdfs:comment "A behavior execution that is the execution of exactly one context-free action, e.g. of a context-free HTTP request."@en ;
+                 rdfs:label "action execution"@en,  "exécution de l'action"@fr .
+
+:BehaviorExecution a owl:Class ;
+                   rdfs:isDefinedBy :interaction ;
+                   rdfs:comment "A course of action performed by an agent upon exploiting a behavior possibility."@en ;
+                   rdfs:label "behavior execution"@en, "exécution du comportement"@fr .
+
+:Input a owl:Class ;
+       rdfs:isDefinedBy :interaction ;
+       rdfs:comment "An input of an action, for example, in the representation of an action execution."@en ;
+       rdfs:label "input"@en, "entrée"@fr .
 
 #################################################################
 #    Object Properties
 #################################################################
+
+:hasInput a owl:ObjectProperty ;
+              rdfs:isDefinedBy :interaction ;
+              rdfs:domain :ActionExecution ;
+              rdfs:range :Input ;
+              rdfs:comment "A relation between an action execution and the input that it has."@en ;
+              rdfs:label "has input"@en, "a une entrée"@fr .
+
+:signifies a owl:ObjectProperty ;
+           rdfs:isDefinedBy :interaction ;
+           rdfs:domain :Signifier ;
+           rdfs:range sh:NodeShape ;
+           rdfs:comment "A relation between a signifier and a node shape specifying a description of the expected behavior execution."@en ;
+           rdfs:label "signifies"@en, "signifie"@fr .