.. -*- mode: rst -*-

=================
Overview of Jason
=================

Jason is an interpreter for AgentSpeak programs, and a framework to create
environments for the development and testing of multi agent systems. You will not
need to be familiar with the full power of Jason however. The website for Jason is
http://jason.sourceforge.net and it is the best place to start for finding
documentation and example code. In particular the documentation section of the site
contains links to the manual and a `getting started
<http://jason.sourceforge.net/mini-tutorial/getting-started/>`_ tutorial, both of
which are essential reference documents.

Setting up Jason
----------------

An IDE is provided for the easy editing of AgentSpeak, running of the
environment and debugging. To set it up simply follow the instructions
below, taken from the `getting started
<http://jason.sourceforge.net/mini-tutorial/getting-started/>`_ tutorial
(which has more info, and pictures).

1. Download Jason from `<http://jason.sourceforge.net>`_.

2. Extract the archive to a folder in your userspace. Something like
   | ``tar xzf Jason-1.2.tgz``
   should do the trick.

3. Execute Jason by running ``./jason.sh`` from the bin directory.

4. You will probably need to set up the location of your Java JDK. Go
   to the menu ``Plugins -> Plugins Options -> Jason``. On a DICE
   machine, "Java Home" should be set to ``/usr/lib/jvm/java/``

At this stage I would encourage loading some of the examples and
running them, to get an idea of how things work. The guides online
may be of some assistance here.

Setting up the Environment
---------------------------

The steps below will take you through loading and running the assignment code:

#. Download the :download:`Assignment 2 code <../assignment2/masws-assign2.zip>`, and
   decompress it, e.g. with::

      unzip masws-assign2.zip.

#. Start Jason, and load up ``hotels.mas2j``. You will then be able to load the
   ``.asl`` files for ``travel_agent``, ``hotel_agent`` and ``bnb_agent``.

#. The ``iactions`` directory contains the Java code for the ``checkDB`` internal
   action. 

#. Edit your code as appropriate, and run or debug with the buttons in the bottom
   right area of the IDE.  The Jason IDE will handle compiling the Java code for you,
   and any files in ``lib`` will be in the classpath. If you wish to add other
   directories to your classpath, rename ``bin/build.xml`` to ``bin/c-build.xml`` and
   edit as appropriate. For example, on a DICE machine to add the Jena libraries to
   the classpath you would add the lines::

      <fileset dir="/usr/share/java/jena/lib/"> 
        <include name="*.jar" />
      </fileset>

   to the ``project.classpath`` section of your ``bin/cbuild.xml`` file.

A Brief Overview of an AgentSpeak Agent
---------------------------------------

This is a very brief overview, for further information it is strongly
recommended that you read the Jason documentation and see the
examples.

The main components of an agent are **beliefs**, **intentions** and
**plans**. Beliefs either come from percepts, and are updated
automatically each reasoning cycle, or are added from plans. They are
expressed as predicates, which may be of arity-0. An example of a
position belief might be ``pos(2,3)``.

Plans are of the following form::

	triggering-event : guard
		<- 	plan_step;
			plan_step.

triggering-event: 
  The triggering-event defines which events may initiate a plan. It could be internal, from
  plans, or external, from percepts. It can be addition, denoted by ``+``
  or removal denoted by ``-``. It may be either a goal or a belief. So
  for example ``+!start`` would trigger on the addition of a start
  achievement goal.

guard:
  A guard is a conjunction or disjunction of beliefs, logical formulae and
  certain built-in special predicates, such as ``.random(N)``. An
  example of a guard depending on the position would be ``pos(X,Y) &
  (X == 10)``. Note that variables must begin with an
  uppercase letter, while lowercase or numbers are constant. The ``_``
  is a "don't care" variable which unifies
  with anything. 

plan step: 
  Plan steps may be 0 or more steps, seperated by ``;`` and terminated
  with a full-stop.  These can be actions, in the form ``do(action)``, or
  goals to achieve, in the form of ``+!goal``.

This is an incomplete description of AgentSpeak; please see the
documentation for more information.

Some sample AgentSpeak(L)
--------------------------

To get you started, here are some simple AgentSpeak(L) plans::
	
	+!send(Message, Agent) : true
		<- .send(Agent, tell, Message)
		
	+!broadcast(Message) : true	
		<- .broadcast(tell, Message).

The first sends ``Message`` to agent ``Agent``. This will result in
the belief ``Message`` being added to ``Agent``\ 's belief base.
The second plan is to broadcast a message.

A simple example of code for two agents to communicate could be as follows:

Agent1
++++++

``Agent1`` sends a hello to all agents, and prints "yay!" with every
response it gets::


	!go. //this is an initial goal
	
	+!go : true
		<- .broadcast(tell,hello).
	
	+hello_from(Agent) : true
		<- .println("Yay! Heard from: ", Agent).

Agent2
++++++

``Agent1`` waits for a hello, and when it receives one, it responds to
whoever sent it::

	+hello[source(A)] : .my_name(Me)
		<- .send(A, tell, hello_from(Me)).

And finally some simple code to wait for 4 replies::


	/* Example recursive code to wait for 4 replies
	of the form "reply(X,Round)" */

	// A counting rule to make this easier
	// Has everyone replied this round?
	done_round(R) :-
		.count(reply(X, R), 4). 

	+!check(R) :  done_round(R)
		<- .println("Got 4 replies!").
	
	//still waiting on replies case (we've proposed but not got all replies yet)
	+!check(R) : true
		<- 	.wait(250);	//wait 250ms before checking again.
			!check(R).