Multi-agent negociation for event scheduling with NARVAL

Bruno VAN FRACHEM


Table of Contents

Install and setup
Install
Configuration
Define preferences
Execution

Abstract

This HOW-TO explains how to use negociation procedure from the PIA package to schedule common rendez-vous among NARVAL agents in function of theirs calendars.

Install and setup

Install

Install the PIA package with the npm program npm (in the "tools" directory of NARVAL):

	  npm.py install pia.tgz
	
Else you can prefer using HORN to do it, by clicking the 'Install package' item from the 'File' menu of the main window.

To use PIA's scheduling negociation you'll need NARVAL's negociation package too. Install it in the same way.

Finally, if you want to use the negociation recipes, you must have the vcalsax tool. You can download it here.

Configuration

Next insert a <xml-repository type='vcal'> element in your memory.xml file, as a child of

<memory>
, containing the pointer to your own calendar file (generated by a scheduling software like KOrganizer or Evolution). It should look like that:
	  <memory>
          ...
          <xml-repository type='vcal'>file:///home/me/calendar.vcs</xml-repository>
	  </memory>
	

You must then allow your agent to contact other personal assistants. The first thing to do is then to consult the LDAP directory in order to find all the connected agents. To get things run well, you have to add in your memory file different elements.

  • The first thing you must specify is how to contact the LDAP server. This is done by addind a "ldap-server" element in your memory file :

    		<ldap-server host='myserver.mydomain.org' port='389'>
    	      
    The port number is only necessary if you want to specify a special port. If this attribute is omitted, the default Ldap one will be used.

  • The second thing to do is to give your agent's name. Agent Names are supposed to be unique since they're used as a RDN in the LDAP directory. This element allows your assistant to recognize himself. You should have something like :

    		<agent-name>my-agent-name</agent-name>
    	      

  • The last thing to do is to update your agent's entries in the LDAP database, this means update your assistant's status (on/off) and update the port and machine's definitions. The right way to do this is to add this element in memory :

    		
        	          <start-plan recipe='ldap.turn_assistant_on'/>
    		
    	      
    You should do like this since the port and the machine's name will be set to their appropriate values at NARVAL's start. The only thing which is needed for this recipe is the name of your agent which must be declared as told just before.

The last entries to add in memory.xml are <start-plan> elements, to start all the recipes. For this, you can either add this line :

	  
	    <memory>
	     ...
             <start-plan recipe='pia.start'/>
            </memory>
          
	
or you can prefer add these ones if you encounter any problems with the above line.
	  
	    <memory>
             ...
              <!-- These four are facultative on non initiator agents -->
              <start-plan recipe='pia.initiator_negociate'/>
              <start-plan recipe='negociation.record_evaluation'/>
              <start-plan recipe='pia.initiator_evaluate'/>
              <start-plan recipe='negociation.initiator_terminate'/>

              <!-- These others are absolutly necessary -->
              <start-plan recipe='pia.find_agents'/>
              <start-plan recipe='pia.attendee_evaluate'/>
              <start-plan recipe='pia.attendee_act'/>
            </memory>
	  
	
These two ways should be equivalent. The first way is just a 'short cut' to start all the plans.

Of course all the agents involved in negociations must have the path to their user's calendar in a <xml-repository type='vcal'> element. <agent-def> are not necessary in agents which do not launch new negociations, neither are the four first <start-plan> elements.

The event scheduling negociation needs user preferences too. So create the file schedulingrules.xml in the data subdirectory of .narval, which must contain at least this:

	  
	   <?xml version='1.0' encoding='iso-8859-1'?>
	   <schedulingrules/>
	  
	

Define preferences

You can set up some personal preferences in schedulingrules.xml. They are written as if-then rules involving values of different parameters of the events: "category", "day", "hour", "duration", "location" and "attendee". These rules must appear as childs of the <schedulingrules> element.

Rules are used during negociation either to make the first proposal or to evaluate a proposal made by another participant. The then part of a rule is a little bit more complex than the if one as you can define whether a consequence is sure, positive, negative or impossible.

For example, the following element indicates to the agent that user appreciates, when category is "WSM", meetings with a 15 minutes duration and which are scheduled at 3 PM.

	  
	    <prefrule>
	      <if>
	        <meetingattr name='category'>WSM</meetingattr>
              </if>
              <then>
                 <meetingattr name='hour' type='positive'>1500</meetingattr>
                 <meetingattr nmae='duration' type='positive'>15</meetingattr>
	      </then>
            </prefrule>
	  
        

These rules should be a merge between your rules and the rules learnt by NARVAL. Once the rules have been processed in the learning procedure, some attributes may appear in the prefrule like test-relevance or training-relevance. Their values are meaningful and removing them could decrease the negociation accuracy.

Execution

First start all the assistants you want them to take part in the negociation, on the hosts and ports notified in the memory.xml files (use option --listen-on on Engine.py).

Then insert a new event in your agenda, and mark it by inserting the 'XXX ' (note the space after the triple X) string at the start of its summary, followed by the real event summary. So the assistant will recognize it as an event whose date must be negociated. Set the attendees for this event with their e-mail address, which you had written in memory.xml, you remember? (I don't)

Now to launch the negociation process just start the 'pia.initiator_get_event_requests' and the 'notify-all' recipe on your assistant. You may do that with the following command:

echo "# négocier rdv
connect_to $NARVAL_ADR
start_plan pia.initiator_get_event_requests
start_plan negociation.notify-all
disconnect" | $PYTHON narval/Horn.py --exec -