Changes between Initial Version and Version 1 of Paose/Documentation/HowTo-Roles-and-Dependencies

Timestamp:

Sep 6, 2010, 10:31:04 AM (14 years ago)

Author:

wester

Comment:

--

Paose/Documentation/HowTo-Roles-and-Dependencies

@@ +1 @@
+= HowTo: Roles and Dependencies with KBE =
+
+This document explains the purpose and handling of the ''Knowledge Base Editor (KBE)'' tool (Mulan plugin ''KBE'').
+
+== (1) Description ==
+
+The KBE fulfils several purposes for the development of an MAA (which should actually better be addressed separately instead of by one monolithic tool):
+
+  1. The user can define roles for the MAA along with role dependencies in terms of inheritance and service dependencies.
+  2. For each role, further information can be added: state descriptions, expected patterns for incoming messages, mapping between incoming messages and interaction protocols to be activated in response.
+  3. Several roles can be clustered into what can be considered particular agent types (or agent positions) for the MAS to be.
+  4. Ultimately, all the former specifications are compiled into knowledge base files (.kb files). These embody initial bodies of knowledge that agents can be lauched with.
+
+== (2) Embedment in the PAOSE Development Process ==
+
+The following figure illustrates the embedment of the models and software artefacts created with / generated by the KBE into the PAOSE development process.
+
+[[Image(PAOSE_embedment_KBE.png)]]
+
+== (3) Tool Usage ==
+
+As already said, all efforts of using the KBE ultimately result in the generation of knowledge base files to launch agents with initially. Thus, before describing the usage of the KBE step by step, we have a look at what kind of information the knowlege base of a Mulan/Capa agent contains. Afterwards, we address the modelling of roles and role dependencies, the adding of role-specific information, and the definition of agent types in turn.
+
+=== (3.1) Contents of the knowledge base of a Mulan/Capa agent ===
+
+The knowledge base of a Mulan/Capa agent is a unified Renew net (''WissensbasisKBE.rnw'') that offers an interface for accessing and modifying the knowledge of an agent. The knowledge body itself however is stored on a particular place within this net as a Java ''Hashtable''. Thus, knowledge is stored in the form of key-value-tuples, where a key typically is a ''String''. Basically, the developer is free in choosing a key for association with a particular knowledge element. But there exist some reserved keys.
+
+  * '''{{{"Name"}}}''': {{{The AgentIdentifier}}} that denotes the agent itself.
+  * '''{{{"serviceDesc"}}}''': A list ({{{Vector}}}) that denotes the services ({{{ServiceDescription}}}) offerd by the agent.
+  * '''{{{"requiredServices"}}}''': A list ({{{Vector}}}) that denotes the services ({{{ServiceDescription}}}) required by the agent.
+  * Each of the required services ({{{ServiceDescription}}}) results in a key of its own that is the name of the service (via {{{getName()}}}) and that is associated with a list ({{{VTSet}}}) of agents ({{{AgentIdentifier}}}) that offer this service. Service providers and service users are made known to each other by directory facilitators.
+  * '''{{{"proaktiv"}}}''' (yeah, still some german involved): A list ({{{Vector}}}) of net names ({{{String}}} without the {{{.rnw}}} suffix) that denote the protocol nets that are to be started proactively on agent startup.
+  * '''{{{"protocols"}}}''' (quite unintuitive key name): A list ({{{VTIndex}}}) of messages ({{{AclMessage}}}) upon whose reception the agent reacts with the instantiation of a protocol net (as long as the messages do not carry conversation IDs).
+  * Each of the messages from the '''{{{"protocols"}}}''' list results in a key of its own and is associated with the net name ({{{String}}} without the {{{.rnw}}} suffix) that denotes the protocol net to be instantiated upon reception of the message.
+  * '''{{{"decisionComponents"}}}''': A list ({{{Vector}}}) of net names ({{{String}}} without the {{{.rnw}}} suffix)  that denote the decision component (DC) nets of the agent.
+
+In addition to these reserved and oligatory key-value-tuples, the knowledge {{{Hashtable}}} typically contains further entries that add to the state description of the agent.
+
+=== (3.2) Modelling roles and role dependencies ===
+
+In order to demonstrate the usage of the KBE we refer to a simple MAA as a running example. The MAA features agents that can act as ''producers'', ''consumers'', and ''storages''. Producer agents can send produced items to storage agents from which they can be retrieved by consumer agents.
+
+After starting up KBE as via the Renew menu bar ({{{Plugins}}} >> {{{KBE}}} >> {{{Start KBE}}}) we need to create a new project (right click in the ''projects'' frame of the KBE window >> {{{New Project}}}). First of all we want to model the roles and role dependencies for this new project. In order to do so, we create a new diagram (right click on the project entry that was just created >> {{{Create}}} >> {{{New MA-Diagram}}}).
+
+In our MAA example, we identify the roles {{{Producer}}}, {{{Consumer}}}, and {{{Storage}}}. In addition, we want to model an abstract/super role {{{CapaAgent}}} from which all other roles inherit.
+
+[[Image(KBE_roles.png)]]
+
+In addition to inheritance, role dependencies can take on the form of service dependencies. In our running example, the role {{{Storage}}} offers the services {{{store}}} and {{{deliver}}} which are used by the roles {{{Producer}}} and {{{Consumer}}} respectively. For this purpose, the KBE offers service interfaces as modelling elements where each service interface is provided by exactly one role und may be used by multiple roles. A service interface carries one or more service descriptions. Each of these services is provided by the role that provides the interface as a whole. Roles that use a service interface use a subset of the corresponding services. Service descriptions may be added to a service interface via right-clicking the interface element and following the menu options. Descriptions of required services for roles may be added analogously. When a role is declared as using a service interface, the KBE automatically checks (via comparing keys) for matches between the required services of the role and the services of the service interface.
+
+[[Image(KBE_services.png)]]
+
+=== (3.3) Adding role-specific information ===
+
+Roles and role dependencies embody a global view onto the MAA under development. In addition, we can add (local) role-specific information. We distinguish between arbitrary ''state descriptions'' and a ''mapping between patterns of expected incoming messages and protocol nets'' that are to be launched in response. Turning to state descriptions in our running example, we add (again, via right-clicking the role and following the menu options):
+  * Entries for an ''agent name/identifier'' (see Sect. 3.1) and a ''proactive protocols section'' (see Sect. 3.1) for the super role  {{{CapaAgent}}}. They are inherited by all inheriting roles (however, inheritance is severely bugged, see Sect. 4).
+  * Entries for ''decision components'' (see Sect. 3.1) for {{{Producer}}}, {{{Storage}}}, and {{{Consumer}}} respectively.
+  * An entry for a ''product list'' on behalf of the {{{Storage}}}.
+  * An entry for a ''product names list'' on behalf of the {{{Consumer}}}.
+Note that there are quite different value types associated with each of these entries (in particular a {{{Vector}}} for the decision components and two ontology classes {{{ProductList}}} and {{{ProductNamesList}}}).
+
+Decision components are the source for proactive conversation initializations (starting protocol nets proactively). In our running example, this concerns the {{{Producer}}} who can start a conversation with the {{{Storage}}} in order to store products and the {{{Consumer}}} who can start a conversation with the {{{Storage}}} in order to get a list of available products or to retrieve one specific product. The aspect of handling proactive conversation initializations is not addressed in the KBE. However, what is addressed in the KBE is reactive conversation participation. In our running example this concerns the {{{Storage}}} who has to react to incoming messages from the {{{Producer}}} and from the {{{Consumer}}} by starting protocol nets reactively. So we define a mapping between incoming message patterns and protocol nets. Again, this is done via right-clicking the role element and following the menu options. Define patterns of incoming messages first and choose a unique key for each. Afterwards, define names of protocol nets and assign one or more keys of message patterns to them.
+
+[[Image(KBE_state.png)]]
+
+=== (3.4) Defining agent types and generating knowlege base files ===
+
+So far, we have modelled roles and role dependencies. However, they are still just abstract specifications. Our MAA will consist of agents who occupy these roles and thus fill them "with life". We define an agent type by assining to it one or more roles and thus define the agent's initial body of knowledge with which it is "born". In order to do so, we have to switch the KBE perspective. But beforehand, we have to save our role diagram (via the small disc button in the upper left corner) and generate XML descriptions of all roles and service interfaces defined in it (via right-clicking the name that was chosen for our role diagram >> {{{Generate}}} >> {{{Generate ARDs/AIDs (intermediate KBs) from MAD ...}}}).
+
+Afterwards, we switch KBE perspective from the role diagram to the MAS perspective where agent types may be defined. Either this perspective is already available in the ''projects'' frame of the KBE or you have to create it via right-clicking the name of the role diagram >> {{{Create}}} >> {{{New MAS}}}.
+
+In the MAS perspective you may define agent types by assigning roles to it. The final step is to save all agent type definitions as ''knowledge base files'' ({{{.kb}}} files) to the directoy from they are to be read when the MAA is launched (via {{{Save Agent KB}}} or {{{Save All Agent KBs}}}).
+
+[[Image(KBE_agentTypes.png)]]
+
+== (4) Pitfalls ==
+
+soon
+
+== (5) Conventions ==
+
+soon ...