|
|
|
The CMU/Sycara contribution to the CoABS CoAX TIE
8 March 2002
By: Joseph Giampapa (garof+ at cs dot cmu dot edu)
Sean Owens (owens at cs dot cmu dot edu)
Martin van Velsen (vvelsen at cs dot cmu dot edu)
Katia Sycara (katia at cs dot cmu dot edu)
This message makes reference to two images:
- Patrick Beautement's PPT slide, "CoAX 2002 Demo - Agent Domains (Draft 30 Nov 2001),
affectionately known as, "Patrick's CoAX slide"; (in graphical interface format) and
- mockup.jpg, which shows the mockup of the proposed RETSINA CoAX Visualizer;
The image can be found at: http://www.softagents.ri.cmu.edu/CoAx/mockup.jpg
Some descriptions of it: http://www.softagents.ri.cmu.edu/25_jan_email.html
The CMU/Sycara contribution to the CoAX TIE will be the "RETSINA CoAX
Visualizer" and the "RETSINA CoAX Grid Logger". The RETSINA CoAX Visualizer
will permit the visualization of:
1. COALITION DOMAINS, and their nested relationship to each other, if such
relationships exist. In "Patrick's CoAX slide", some coalition domains are:
"Coalition / JTFHQ", "JFMC HQ", "Task Force COC", and "JFAC HQ". Two
example nesting relationships are:
(1.1) "Task Force COC" is part of "JFMC HQ", and "JFMC HQ" is part of
"Coalition / JTFHQ";
(1.2) "JFAC HQ" is part of "Coalition / JTFHQ"
2. AGENTS, which are situated in "coalition domains", and may belong to
multiple coalition domains. An example of an agent in "Patrick's CoAX
slide" is "CAMPS", which is located in the "US National HQ" domain.
3. NON-AGENT ENTITIES, which are also situated in coalition domains, and may
belong to multiple coalition domains. Example non-agent entities of
"Patrick's CoAX slide" are the various databases (e.g. "Dbi", "Dbii", etc.)
and the "Gao Observer".
The "RETSINA CoAX Grid Logger" will provide a log facility for:
4. Receiving log messages from both Grid and, if necessary, non-Grid agents.
5. Filtering log message content according to the restrictions of a coalition
domain-specific security level. See (6) and (7), below, for specific uses
of filtering.
6. Archiving log messages to log files according to the security level of the
message. For example, if a message belongs to security levels 3 and 4 of
two different coalitions domain, then the message will be written to the log
files that correspond to those domains and levels.
7. Forwarding log messages to users of RETSINA CoAX Visualizers according to
the security level of the message and the security level of the user. For
example, if a Visualizer user operates at security level 3, for a coalition
domain, then the RETSINA CoAX Grid Logger will forward messages from that
coalition domain with security levels 0, 1, 2, and 3 to that user's
Visualizer. A user must be granted a security level access right for each
coalition domain of which he is a member.
The RETSINA CoAX Visualizer will perform the following for the CoAX demo:
a. Visualize the relationships among different coalition domains, by
representing the coalition domains as highlighted boxed areas with titles,
optionally a flag, miscellaneous information, and by showing the boxes
nested one, within the other (see "mockup.jpg");
b. Visualize the membership of agents and non-agent entities within those
domains, by representing an agent or non-agent entity as a labeled icon that
is situated within the one or more coalition domain boxes of which it is a
member. If an agent or non-agent entity belongs to more than one domain,
then its icon and label will be copied to those multiple domain boxes and
will be given a different highlight color to show that the icons refer to
the same entity.
c. Visualize the dynamic reconfiguration of coalition domain, agent, and
non-agent entity membership. That is, if a coalition domain is disbanded,
created, or "moved" under another coalition domain, such changes of state
will be visualized. Similarly, if an agent or non-agent entity withdraws
from or joins a coalition domain, its icon will be removed from or appear
within, a coalition domain box.
d. Visualize the communications among agents and non-agent entities,
**** AS LONG AS THE AGENT OR NON-AGENT ENTITY LOGS A COMMUNICATION ****
**** MESSAGE TO THE RETSINA COAX GRID LOGGER. ****
The communications will be visually represented as a kind of dashed line
that is known as the "marching ants line", that has a limited duration of
visualization. In the event that an agent or non-agent entity belongs to
more than one domain, only one of its Visualizer representations will be
chosen to originate or receive a "marching ants line", according to a
suitable heuristic.
e. Visualize all of the above in a way that is commensurate with the access
rights and role of the viewer. The RETSINA Visualizer will require that a
user login. Associated with the username will be the coalition domains of
which they are a part, their role within the coalition domain
(e.g. commander in chief (CINC), operations officer, etc.), and a security
access level that is valid for that role within the coalition domain. For
now, we use just an integer number from 0 to 9, representing progressively
increasing powers of access. 9 represents the access level of a commander
in chief, whereas 0 represents a general level of accessibility.
The user's access rights will be communicated to the RETSINA Grid Logger
upon authentication of the user. As the RETSINA Grid Logger receives data
to visualize, it will decide which messages to send to a user's Visualizer,
based upon the user's security level. So, for example, the Gao observer may
only see top-level national coalition domain boxes but not inner coalition
domains, such as "Task Force COC", and the entities within it. A supreme
CINC, and the CoAX demo audience, however, will see all domains and
entities.
_________________________________________________________________________
How To Be Visualized
To visualize the CoAX demo via the RETSINA CoAX Grid Visualizer, there are four
steps that must be taken, in order:
1. Define the coalition domains, and their subdomain relationships with each
other.
2. Define the agent and non-agent entities, and declare the domains with which
they are associated.
3. Show agent and non-agent entity communications with each other.
4. Remove any defunct, agent, or non-agent entities that are no longer
relevant, have been reallocated, or should be redrawn elsewhere on the
Visualizer.
Due to the global nature of step (1), above, the definition of coalition
domains should be performed by only one CoAX team member, for the whole demo,
at the time of demo startup. The CMU/Sycara group will do this according to
the domain layout of "Patrick's CoAX slide." If any research group needs to
show their control over the creation and location of coalition domains, please
let Joe Giampapa know ASAP.
We presume that all CoAX demonstration participants will want their agents and
non-agent entities to appear on the CoAX Grid Visualizer. Consequently,
**** ALL COAX GROUPS MUST MANAGE STEPS: (2), (3), AND (4) ****
during the complete lifecycle of their agent or non-agent entity.
**** CRITICAL ASSUMPTION ****
The other critical assumption that we make is that there will not be other Grid
log servers running. If this will not be the case, please contact Joe Giampapa
ASAP.
**** CRITICAL ASSUMPTION ****
The next section, "The RETSINA CoAX Grid Logger Message Specs", describes the
content message specifications that the Grid Logger needs to receive. If your
agent or non-agent entity has not been built with the Grid, then it must
connect to the RETSINA CoAX Grid Logger via a TCP socket, and send messages of
that section as the content of a RETSINA-KQML message. If your agent or
non-agent entity has been built with the Grid, then the you will use Grid
methods that are described in the section, "The RETSINA CoAX Grid Logger Proxy
Methods", to send these content messages.
__________________________________________________________________________
The RETSINA CoAX Grid Logger Message Specs
Since all CoAX groups must manage steps (2) -- (4), as outlined in the previous
section, message specs (MS-6) -- (MS-9), below, will be the most important ones
to understand.
MS-1. Coalition domain names are:
a. represented as strings;
b. case sensitive;
c. cannot contain a vertical bar "|" or double quote """;
d. are globally unique
(e.g. there cannot be more than one domain named, "H.Q.");
MS-2. Agent and non-agent entity names are:
a. represented as strings;
b. case sensitive;
c. cannot contain a vertical bar "|" or double quote """;
d. are globally unique
(e.g. there cannot be more than two agent or non-agent entities named,
"DB");
MS-3. To establish the visual representation of a coalition domain in the
RETSINA CoAX Visualizer, your agent must log a RETSINA-KQML message with the
following syntax:
(DEFINEDOMAIN
:name [|]*
[ :description (description +) ]
)
[ ] - indicates grouping and an optional component
* - zero or more repetitions of the previous expression
+ - one or more repetitions of the previous expression
DEFINEDOMAIN - the case-insensitive message performative
- the coalition domain name
- a description is a KQML message that has the
performative "description" and contains arbitrary
attribute/value pairs that can be used to label
coalition domain boxes.
Example 1.
To create and label the "UK National HQ" coalition domain box, as shown in
"mockup.jpg", log the following message:
(DEFINEDOMAIN
:name "UK National HQ"
:description (description
:community "UK"
:flag "UKFlag"
:info ""
)
)
Example 2.
To create the nested coalitions domain of example (1.1), above, log the
following message:
(DEFINEDOMAIN
:name "Coalition / JTFHQ|JFMC HQ|Task Force COC"
)
This will create the nested coalition domain boxes that are shown in
"Patrick's CoAX slide".
MS-4. To remove a domain, and all subdomains, agents, and non-agent entities
that are visualized within it, log the message:
(REMOVEDOMAIN
:name [|]*
)
[ ] - indicates grouping and an optional component
* - zero or more repetitions of the previous expression
+ - one or more repetitions of the previous expression
REMOVEDOMAIN - the case-insensitive message performative
- the coalition domain name
Example 1.
To remove the "Task Force COC" coalition domain box and the entities
contained within it, log the message:
(REMOVEDOMAIN :name "Coalition / JTFHQ|JFMC HQ|Task Force COC")
Example 2.
To remove the "Coalition / JTFHQ" coalition domain box and the entities
contained within it, log the message:
(REMOVEDOMAIN :name "Coalition / JTFHQ")
MS-5. To demote a domain to a subdomain, or promote a subdomain to a higher or
top-level domain, just log a REMOVEDOMAIN message followed by a DEFINEDOMAIN
message, with the new allocations. Please note that it will be necessary to
repopulate the coalition domain that was deleted.
Example 1.
To promote the "Task Force COC" up, one level, on par with the "JFMC HQ",
log the following messages, in the following order:
(REMOVEDOMAIN :name "Coalition / JTFHQ|JFMC HQ|Task Force COC")
(DEFINEDOMAIN :name "Coalition / JTFHQ|Task Force COC")
You will need to repopulate the "Task Force COC" domain with the entities
that should be part of it.
Example 2.
To demote "JFMC HQ" to being a subdomain of "Task Force COC", log the
following messages, in the following order:
(REMOVEDOMAIN :name "Coalition / JTFHQ|JFMC HQ")
(DEFINEDOMAIN :name "Coalition / JTFHQ|Task Force COC")
(DEFINEDOMAIN :name "Coalition / JTFHQ|Task Force COC|JFMC HQ")
and repopulate both the "Task Force COC" and "JFMC HQ" coalition domains.
MS-6. To show the membership of an agent or non-agent entity in one or more
domains, log a message of the following form:
(AGENTDOMAINS
:agent
[ :domainsList ( (:domain :role )+ ) ]
[ :defaultMsgSecurityList ( (:domain
:level )* ) ]
)
[ ] - indicates grouping and an optional component
* - zero or more repetitions of the previous expression
+ - one or more repetitions of the previous expression
AGENTDOMAINS - the case-insensitive message performative
- [|]*
- the coalition domain name
- if the agent or non-agent entity has a role in its
coalition domain, then this string describes it
Domain name lists are delimited by ( and ) (parens). If no ":domainsList"
attribute/value pair is provided, then the agent will be part of the
top-level domain.
Note: You must explicitly name all coalition domains in which an agent or
non-agent entity should appear. For example, if there are nested domains
"a|b|c", and an agent should appear in all three, then the ":domainsList"
must contain three components: "a", "a|b", and "a|b|c".
Example 1.
To add agent "Air_Ops_Officer" to the top-level domain, log the following
message:
(AGENTDOMAINS :agent "Air_Ops_Officer")
Example 2.
To add agent "Sgt. Owens" to multiple U.S. Army domains, log the following
message:
(AGENTDOMAINS
:agent "Sgt. Owens"
:domainsList ( (:domain "U.S." :role "citizen")
(:domain "U.S.|Army" :role "enlisted private")
(:domain "U.S.|Army|Task Force A" :role "second in command")
(:domain "U.S.|Army|Task Force B" :role "leader")
)
)
MS-7. To reassign an agent or non-agent entity to another coalition domain, it
is enough to log another AGENTDOMAINS message:
Example 1.
To reassign Sgt. Owens from "Task Force A" to "Task Force B", log the
following messages, in the following order:
(AGENTDOMAINS :agent "Sgt. Owens"
:domainsList ( (:domain "U.S.|Army|Task Force A"
:role "second in command")))
(AGENTDOMAINS :agent "Sgt. Owens"
:domainsList ( (:domain "U.S.|Army|Task Force b"
:role "leader")))
MS-8. To interrupt the visualization of an agent or non-agent entity, such as
before it shutsdown, log the AGENTREMOVE message:
(AGENTREMOVE
:agent
)
AGENTREMOVE - the case-insensitive message performative
MS-9. To log a communication from one agent to another, log a COMM message.
A COMM message also has a security level associated with it for each domain
in which it may be logged or visualized.
(COMM
:sender
:receiver
[ :msgSecurityList ( (:domain :level )* ) ]
)
[ ] - indicates grouping and an optional component
* - zero or more repetitions of the previous expression
+ - one or more repetitions of the previous expression
COMM - the case-insensitive message performative
- [|]*
- the coalition domain name
- if the agent or entity proxies a human, this string
describes the human's role in the coalition
- an single-digit integer in double quotes, from "0" to "9"
The ":msgSecurityList" field is optional.
a. If unspecified, the domain security level(s) for the message will be
derived from the ":defaultMsgSecurityList" for the sender (cf. MS-6).
b. If specified, the values of the ":msgSecurityList" will be used.
Example 1.
To visualize a communications message from "Pvt. Bailey" to "Sgt. Snorkel",
and the security levels of the message:
(COMM
:sender "Pvt. Bailey"
:receiver "Sgt. Snorkel"
:msgSecurityList ( (:domain "U.S.|Army|Task Force A" :level "1")
(:domain "U.S.|Army|Task Force B" :level "2")
)
)
_________________________________________________________________________
The RETSINA CoAX Grid Logger Proxy Methods
In order for the CoAX coalition domains, agents and non-agent entities, and
communications to be displayed in the RETSINA CoAX Visualizer, they must use
the "LogAgentRep.addReportContent()" methods to create a log report message
containing one of the above specified messages. We provide cross references to
the corresponding message specification number in, "The RETSINA CoAX Grid
Logger Message Specs", above.
GA-1. To establish the visual representation of a coalition domain in the
RETSINA CoAX Visualizer, your agent must add the following content to the
LogAgentRep (cf. MS-3, MS-5):
LogAgentRep.addReportContent(
"DEFINEDOMAIN",
"definition of an agent domain.",
"(DEFINEDOMAIN :name \"US National HQ\" :description (description :community \"USA\" :flag \"USA Flag\" ))";
GA-2. To remove a domain, and all subdomains, agents, and non-agent entities
that are visualized within it, your agent must add the following content to
the LogAgentRep (cf. MS-4, MS-5):
LogAgentRep.addReportContent(
"REMOVEDOMAIN",
"removal of an agent domain.",
"(REMOVEDOMAIN :name \"US National HQ\")");
GA-3. To show the membership of an agent or non-agent entity in one or more
domains, your agent must add the following content to the LogAgentRep
(cf. MS-6, MS-7):
LogAgentRep.addReportContent(
"AGENTDOMAINS",
"specifying domains of a new or changed agent",
"(AGENTDOMAINS :agent AgentFred :domainsList ( (:domain \"U.S.\" :role \"citizen\")
(:domain \"U.S.|Army\" :role \"enlisted private\") (:domain \"U.S.|Army|Task Force A\" :role \"second in command\")
(:domain \"U.S.|Army|Task Force B\" :role \"leader\"))");
GA-4. To interrupt the visualization of an agent or non-agent entity, such as
before it shutsdown, your agent must add the following content to the
LogAgentRep (cf. MS-8):
LogAgentRep.addReportContent(
"AGENTREMOVE",
"Removing an agent from demo display",
"(AGENTREMOVE :agent AgentFred)");
GA-5. Grid agents already log their communications with the logger by default.
As you will recall from (MS-9), above, each message has a security level
associated with it. To minimize the impact on Grid users, the security
level for a message in a particular domain will be set to the security level
of the sending agent, in that domain. Recall that an agent's security level
is set in the AGENTDOMAINS message (cf. MS-6).
a. To log communications between Grid agents with a default security level,
the Grid agent programmer need not do anything, other than ensure that
his messages contain both a sender agent name, and the receiver agent
name, either in KQML in the RawText field of the message, or in the
AgentRep of the sender being included with the Message.
Message message = new BasicMessage(toAgentName,
myAgentRep,
"KQML",
"(tell :sender AgentFred"
+" :receiver AgentBarney"
+" :content (Hello Fred))");
b. If the Grid agent programmer would like the agent to send messages at a
security level other than its default security level, (for instance, if
the agent has several security levels and wishes to attach only one of
the security levels to a message, or perhaps a lower security level than
the maximum the agent is capable of) then the ":msgSecurityList" field
from (MS-9) must be added to the content (i.e. the rawText) of the
message that is being sent. I.e.:
Message message = new BasicMessage(toAgentName,
myAgentRep,
"KQML",
"(tell :sender AgentFred"
+" :receiver AgentBarney"
+" :msgSecurityList ("
+" (:domain \"U.S.|Army|Task Force A\" :level \"1\")"
+" (:domain \"U.S.|Army|Task Force B\" :level \"2\")"
+")"
+" :content (Hello Fred))");
|
