This quick setup guide will help you get going with the IIPC software on your own system. Alternatively, you can also try using Docker (required for final submission). Make sure you read the Stack Guide for more details about each component.
In order to set up the competition software for local use you will need a JDK to compile and run the source code.
In the download section there are links to clone or download the Simulation Server, BDI Interface and Test Agent software. The Simulation Server and BDI Interface are required to run the competition locally. The Test Agent is not strictly necessary but can be used to validate the software stack and as an example / starter code.
Gradle wrappers are provided for building the code and expedite setup. To avoid Gradle conflicts, it is recommended that each repository/zip file is cloned/unzipped in its own directory. The Simulation Server and BDI Interface can then be built using the following command in their respective top-level directories:
./gradlew fatJar
To build the Test Agent use the command:
./gradlew jar
in the appropriate directory.
To run the Simulation Server and BDI Interface use the following commands in the appropriate directory:
java -jar build\libs\simulator-server-all-1.0.jar
java -jar build\libs\bdi-interface-all-1.0.jar
To run the Test Agent use the following command in the appropriate directory:
java -jar build\libs\test-agent.jar -t
The -t performs a test of the software stack and should produce the following ouptput:
TEST MODE ENABLED
Connection to BDI established on port 40000
The stack appear to be configured correctly and the test domain completed with success.When running locally, the BDI Interface defaults to using localhost.
To ensure that we are able to run your code, your final submission must be contained within a Docker container.
Please read our Docker instructions and follow the steps there to create your container.
Additional instructions on where to send your submission and the deadline will be added here when they are finalised.
There are 3 ways of running the International Intention Progression Competition:
Step-by-step tutorials on how to run the IIPC Docker container are available here
You will be running the server and the BDI interface in a Docker container. Your solution will run separately outside of the container. After you have started the server and the BDI interface from within the container, simply compile and execute your solution as you would normally (in your local installation) and it should automatically connect to the BDI interface in the container.
This is recommended if you want to ensure your solution works in the containerised server, but you are still developing your solution and prefer to run it locally.
Assuming you are familiar with Docker (if not, follow the link above to the step-by-step tutorials), this is the command you need to run the container:
docker run -it --rm -p 40000:40000 -p 30000:30000 ipc-simulator bash
Create a docker container with your solution in such a way that allows it to connect and communicate with the server and BDI interface container.
You will need to do this for your final submission to ensure that we can easily run your code.
An example of a containerised solution of the TestAgent is available here.
Assuming you are familiar with Docker (if not, follow the link above to the step-by-step tutorials), first you need to create a Docker network:
docker network create ipc_network
Run the container with the server and BDI interface:
docker run -it --rm --network=ipc_network --name ipc_server ipc-simulator bash
Run the container with the solution (replace "ipc-submission-testagent" with your submission):
docker run -it --rm --network=ipc_network ipc-submission-testagent
The International Intention Progression Competition software stack consists of three parts. Two are provided: the Simulation Server representing the agent's environment, and the BDI Interface which represents a BDI agent that receives goals and percepts from the environment and performs actions to achieve the goals. Together, these two components form the competition framework. The third component is the competition entry itself in the form of a solver for intention progression problems, that decides which action should be returned by the agent.
The Simulator Server represents the agent's environment. It is responsible for initialising the agent with forest of goal-plan trees to be used for the current intention progression problem instance, the initial state of the environment, and the initial set of goals to be achieved. Following initialisation, the Simulator Server is responsible for updating the environment state in response to actions performed by the agent and spontaneous changes to the environment, and for generating additional goals to be achieved during the run.
The server communicates with the BDI Interface representing the agent via messages sent in JSON format. (By default, the server listens on port 30000.)
The BDI Interface represents a BDI agent that receives goals and percepts from the environment and performs actions to achieve the goals.
The BDI Interface handles communication between the Simulator Server and IPP Solver. At each cycle, the interface sends the solver:
Following initialisation, the solver sends the interface:
Messages between the interface and solver are in XML format and are documented at: interface to solver and solver to interface . (By default, the interface listens on port 40000.)
The role of the BDI Interface is mostly to simplify development of solvers and the running of the competition. It translates XML commands to and responses from the simulator into and from JSON (with some basic syntax checking on the input side) so the solver doesn’t have to do this. It also logs the time of each command from the solver and response from the simulator, so that the elapsed time taken by a solver can be computed. (Currently, this is only for information, but future competitions may wish to include elapsed time in scoring.)
The IPP Solver constitutes the competition entry.
A solver for the IIPC is a stand-alone program that interacts with the BDI Interface via a socket. During the competition, the solver will be restarted for each IPP problem instance. The path to the XML file containing the IPP instance will be passed to the solver on the command line. The solver must initialise the session by sending an <initiate> command to the BDI Interface. It then must read the local XML file containing the IPP instance returned by the Simulator Server containing the specification of the forest of goal-plan trees to be used for this problem instance. Note that initiation must occur before the XML file containing the goal-plan forest is read. For the competition, the problem instance files are stored on the host running the Simulator Server, and are only sent to the BDI Interface following receipt of an <initiate> command.
Following initiation, the solver enters a cycle of reading the current environment state and requested goals, and choosing an action to perform. The response to the <initiate> command also contains the initial state of the environment and the set of goals the agent has been asked to achieve. The solver must return the next basic action in a plan for one of the top-level goals (if execution has reached a subgoal in a plan, this involves choosing an appropriate plan for the subgoal and returning the first action of that plan). The solver then returns the selected action to the BDI Interface which forwards it to the Simulator Sever for execution. If the preconditions of the action hold in the current environment state, the environment is updated with the action's postconditions. The cycle repeats until all the top-level goals in the problem instance have been achieved, none of the agent's intentions can be progressed or a timeout is reached.
In summary, the solver must be able to:
Implementing the decision making of the solver is the key challenge of the IIPC.
The Simulation Server and BDI Interface can be downloaded here. Also available in the dowloads area is a simple test client, which can be used to check that the software stack is correctly configured, and some example IPP instances of differing complexity.
During the development of your entry, the three components may be run on the same or different machines, by appropriate configuration of the Simulation Server and BDI Client. However, your submitted entry must run in a Docker container. Submission instructions are available here.
<command clientid="" >...
This is the root tag of the entire XML command. The attribute
clientidspecifies the competition ID of the IPP Solver issuing the command as a string. is your (unique)
The actual command is specified in a child <initiate>, <action>, or <quit/> tag as described below.
<initiate>...
This tag wraps up the requirements for starting a session.
When initiating a session, the IPP Solver should specify the (relative) path to the file containting the forest of goal-plan trees to be used for the current intention progression problem instance in a <gptfile> tag. The solver may also optinally specify the random seed to be used by the Simulation Server to ensure repeatability of, e.g., spontaneous environmental changes in a <seed> tag.
<gptfile>gpts/gpt.2.xml</gptfile>
This tag contains a string specifying the relative path (on the Simulation Server host) to the gpt file.
<seed>1000</seed>
This tag contains an int specifying the random seed to be used by the Simulation Server.
<action>T1-A0</action>
This tag constains a string specifying the action to be performed by the agent at this cycle.
<quit/>
This tag instructs the Simulator Server to cleanly close the current session.
Note that the following has been prettified for readability, and in practice is sent without whitespace.
<msgroot>...
This is the root tag of the message. It contains <environment>, <gptfile> and <status> tags. The final message of the session also contains a <logfile> tag.
<environment>...
This tag wraps the percepts and current goals of the agent. The environment is specified in a <literals> tag, and the goals in a <goals> tag.
<literals>...
This tag contains the literals perceived by the agent at this cycle. Each literal is of the form:
<literal-name>boolean-state</literal-name>
where literal-name is a string and boolean-state is either true (for positive literals) or false (for negated literals).
<goals>...
This tag contains the goals the agent has been asked to achieve (so far). Each goal is of the form:
<goal-name>boolean</goal-name>
where goal-name is a string and boolean is true if the goal has been achieved, and false if the goal has not been achieved.
<gptfile>gpts/gpt.2.xml</gptfile>
This tag contains a string specifying the path to the file containing the forest of goal-plan trees for the current IPP instance, relative to the BDI Interface directory.
<logfile>logfiles/45C48C-1565267126447</logfile>
This tag contains a string specifying path to the log file associated with the current session, relative to the BDI Interface directory. Note that the <logfile> tag is included only in the last message from the Simulator Server, i.e., when the current session has ended.
<status>...
This tag wraps up all of the metadata for the current IPP instance session. It contains <contest> <timeremaining>, <command> and <message> tags.
<contest>ACTIVE</contest>
This tag contains a string specifying the state of the current IPP instance session:
ACTIVECOMPLETETIMEOUT<timeremaining>600000</timeremaining>
This tag contains an int specifying the time remaining in the current session in milliseconds.
<command>VALID_COMMAND</command>
This contains a string specifying the response to the last message sent to the Simulator Server:
VALID_COMMANDACTION_FAILEDMISSING_CLIENT_IDINVALID_GPT_FILECOMMAND_NOT_RECOGNISEDINVALID_COMMANDTERMINATE<message>Initialisation started</message>
This tag contains a string expanding on the command response, e.g., an error message.
Note that the following has been prettified for readability, and in practice is sent without whitespace.
The current releases of all the required software can be found on the Downloads page and via Docker containers.
<Forest>...
This is the root tag of the goal-plan tree forest. It contains an <Environment> tag, and one or more <Goal> tags. Each <Goal> tag forms the root of a goal-plan tree in the forest.
<Environment>...
This tag wraps the literals that form the agent's environment. Each literal is specified in a <Literal> tag.
<Literal name="EV-0" stochastic="true" initVal="true" />
This tag contains an environment variable. The characteristics of the variable are specified by the following attributes:
namestochastictrue indicates the variable can change at random, false that the variable will only change in response to agent actions.initValtrue, false or random (for a literal whose value is set randomly during initialisation).<Goal name="T0-G0" goal-condition="(G-0,true);">...
This tag specifies a goal. When it occurs as a direct child of the <Forest> tag it indicates a top-level goal that the agent may be asked to achieve. The characteristics of the goal are specified by the following attributes:
namegoal-conditiongoal-condition holds in the current environment.A <Goal> contains one or more <Plan> tags containing plans to achieve the goal.
<Plan name="T0-P0" precondition="(EV-9,true);">...
This tag specifies a plan. The characteristics of the plan are specified by the following attributes:
namepreconditionA <Plan> contains one or more <Action> and <Goal> forming the body of the plan. The actions and goals should be executed/achieved in the order specified (typically, the postcondition of an action or a goal condition establishes the precondition of an action or the plans for a subgoal occurring later in the plan).
<Action name="T0-A0" precondition="(EV-9,true);" postcondition="(EV-0,false), (G-0,true);"/>
This tag specifies an action. The characteristics of the action are specified by the following attributes:
namepreconditionVALID_COMMAND response is returned to the BDI Interface; otherwise the action fails, and an ACTION_FAILED response is returned.postcondition(EV-0,false), (G-0,true);
Pre- post- and goal conditions are specified as pairs of the form:.
(<literal-name>,<boolean-state>),...(<literal-name>,<boolean-state>);
Where literal-name is the name of a <Literal> forming part of the <Environment> and boolean-state specifies the value the literal must have for the condition to hold.
Note that the following example is simply to illustrate the syntax; the problem instances used in the competition will typically be much more complex.
Entries will be evaluated on instances of intention progression problems in both a "synthetic" domain and in a number of "real world" domains.
The goal-plan trees for the synthetic domain are derived from abstract BDI programs that have similar structure to "real world" BDI programs, however the goal, plan and action names are arbitrary, and the literals defining the environment are not a model of any particular environment.
Each forest of synthetic trees are defined by six parameters: the depth of each goal-plan tree, the number of subgoals in each non-leaf plan (leaf plans contain only action nodes), the number of plans to achieve a goal, the number of actions in each plan, the number of environment variables that may appear in the tree as pre- and postconditions, and the number of goal-plan trees in the forest. The trees are generated such that: (a) each plan is well formed (the plan can be successfully executed in some environment), and (b) taken individually, each goal-plan tree is executable (there is at least one way to achieve the top-level goal in all (static) environments).
By varying the number of environment variables, we can vary the likelihood of actions and plans in different goal-plan trees having the same pre- and postconditions, and hence the probability of both positive and negative interactions between goal-plan trees. This, together with variations in the dynamism of the environment, allows the performance of each solver to be evaluated under different conditions.
A variety of synthetic problem instances of differing complexity and difficulty are provided as part of the competition resources in the download section.
In addition to the "synthetic domain", entries will be evaluated on instances of intention progression problems in the following "real world" domains. The goal-plan trees for these domains are derived from simple BDI programs loosely based on common examples from the BDI literature, including elevator control, and logistics. Note that, in the interests of readability, goal, plan and action names are given in a simplified form; however the relationship between goals and plans is as in the XML GPTs.
Each domain is defined by a set of parameters, and a variety of problem instances of differing complexity and difficulty are provided for each domain as part of the competition resources in the download section.
The Miconic-N Domain defines a set of simple 'elevator world' problems, in which the goals of the agent involve moving people from one floor of a building to another. Unlike traditional elevators, the Miconic-N elevator allows passengers to enter their destination floor when calling the elevator using a N-digit keypad installed in each elevator lobby (where N is the number of floors in the building). In the scenario, a single Miconic-N elevator is controlled by the agent. For simplicity, there are no restrictions on the number of people the elevator can carry. The specification is based on the description of the Miconic-10 domain in (Yao & Logan 2016), which in turn is based on the HTN formulation in (Koehler & Schuster 2000).
The agent has plans to achieve goals of the form: "Move (passenger) n to (floor) x", "(be) At (floor) y", "Collect (passenger) n (from the current floor)", and "Deliver (passenger) n (to the current floor)". The plans for "Collect n" and "Deliver n" consist of a single action (to embark and disembark the passenger respectively). In addition, there is a plan to achieve the "At y" goal from each floor z in the building, consisting of a single action to move the elevator from floor z to floor y. The top-level goals are of the form "Move n to x".
The environment is deterministic, i.e., it changes only when the agent performs an action (passengers are assumed to enter and exit the elevator when requested by "embark" and "disembark" actions), and actions are guaranteed to succeed if their preconditions are true.
The environment is parameterized by the number of floors and the number of possible passengers. As the simulator only supports problem definitions in propositional form, goal-plan trees are generated for a number of randomly selected top-level goals of the form "Move n to x", and an environment is generated such that passenger n is initially at a floor different from x. (For simplicity, each passenger is moved at most once by a top-level goal.) A randomly selected subset of these goals is used to evaluate the agent (the same goal-plan forest, environment and evaluation goal set is used for each agent). A subset of the goals in the evaluation set are given to the agent initially and the remaining goals are given over the course of the run. The additional goals are given at the same point in the run to each agent.
The environment state is specified by propositions for each possible position (floor) of the elevator and of each passenger, as well as propositions for each passenger being in the elevator. Actions have the 'obvious' pre- and postconditions; for example, the action of embarking a passenger has as precondition that the elevator is at the floor the passenger is currently on, and postcondition that the passenger is in the elevator and no longer at the floor.
The Logistics Domain defines a set of simplified logistics problems, in which the goals of the agent involve delivering packages from one location to another. The agent controls a vehicle which can carry a limited number of packages at any given time. (This prohibits the O(2n+2m) step solution to a problem with n stops and m potential packages, of simply moving around the ring, picking up every package and then delivering them.) Locations are arranged in a ‘ring' with each location directly connected to two adjacent locations by ‘roads'. In addition, there are a number of randomly generated ‘chordal roads' connecting non-adjacent locations. The chordal routes effectively provide a set of ‘shortcuts' that may or may not be available at a particular point in a run.
The agent has plans to achieve goals of the form "Transport (package) n to (location) x", GoTo (location) y", "Load (at location) y", and "Unload (at location) x". The goal "Load y" is achieved by a set of plans, one for each number of packages the agent is currently carrying. Each plan consists of a single "load" action that loads the package at the current location and updates the number of packages the vehicle is carrying. The goal "Unload x" is similar. In addition, for each "GoTo y" goal, there is a plan for each possible starting location of the vehicle by each route that is no longer than the path from the starting location to y around the ring. That is, the agent can choose any traversable shortcut of length less than or equal to the shortest path around the ring. The plans for "GoTo y" goals consist of sequences of "move x y" actions, where x and y are either adjacent locations on the ring, or x and y are locations connected by a chordal road. The top-level goals are of the form "Transport n to x".
The environment is non-deterministic. To reflect traffic jams, road closures etc., the chordal roads may or may not be traversable at any given point in a run (controlled by the environment agent), while the ring is always traversable (so packages can always be delivered). Actions are guaranteed to succeed if their preconditions are true. For example, a load action can be performed if the vehicle is at a location with a package. A move action can be performed, if the road to the destination location is traversable.
The environment is parameterised by the number of locations and the number of possible packages. As the simulator only supports problem definitions in propositional form, goal-plan trees are generated for a number of randomly selected top-level goals of the form "Transport n to x", and an environment is generated such that package n is initially at a location different from x. (For simplicity, each package is moved at most once by a top-level goal.) A randomly selected subset of these goals is used to evaluate the agent (the same goal-plan forest, environment and evaluation goal set is used for each agent). A subset of the goals in the evaluation set are given to the agent initially and the remaining goals are given over the course of the run. The additional goals are given at the same point in the run to each agent. This, together with changes in the availability of shortcuts by the environment agent, changes both the applicability and utility of plans at run time, for example, by allowing the use of a shortcut, or combining pickups and drop-offs at adjacent locations.
The environment state is specified by propositions for each possible location of the vehicle and of each package, as well as propositions for each package being in the vehicle and the number of packages currently carried. Actions have the ‘obvious' pre- and postconditions; for example, the action of loading a package has as precondition that the vehicle is at the pickup location of the package and the vehicle is currently carrying less than the maximum number of packages, and postcondition that the package is in the vehicle and no longer at its pickup location. The action of moving from a location x to an adjacent location on the ring y has precondition that the vehicle is at x, and postcondition that the vehicle is at y (and no longer at x). The action of moving from a location x to a location y via a chordal road has an additional precondition that the road from x to y is currently traversable.