PEAK: Python-based framework for heterogenous agent communities

PEAK is a multi-agent system framework which helps the users develop, monitor, analyze and maintain ecosystem of heterogeneous agent communities. This ecosystem is where various multi-agent systems can coexist, interact and share resources between them. This framework is based on SPADE.

Prerequisites

• Python == 3.9.6
• XMPP Server (see docs)

Installing PEAK

Conda

To install using conda, download the environment.yml file from the repository and then use the following command:

$ conda env create --file environment.yml	

This will create a conda environment called peak.

Pip

To install using pip, just type the following command:

$ pip install peak-mas

Using PEAK

Notes on SPADE

As already said PEAK is based on SPADE. This means that every functionality of SPADE is available to the user. We highly recommend you to see SPADE examples and documentation before starting using PEAK. Once you are familiarized with SPADE's mechanics you can start using PEAK. For now PEAK is not compatible with version above 3.2.2 of SPADE.

Notes on XMPP

To run any PEAK's agent you will need a XMPP server. You can either configure one on your machine, remotely or use a public server. The only issue with the public servers is that they don't usually have all the configurations required to run some PEAK's functionalities. To configure the server you can read the "Configure XMPP server" section in the documentation.

Using docker

To make it easier to configure the XMPP server we have created a docker image with the server already configured. To use it just type the following command in the /docker folder:

$ docker-compose up -d

Hello World Agent Example

One thing that was added in PEAK was the way the user executes the agents. PEAK added a CLI, inspired in JADE, to help the user execute end configure each agent in a easy and intuitive manner. In this example we will show you how to execute a single agent. Save the following code in a file called agent.py.

from peak import Agent, OneShotBehaviour

class agent(Agent):
    class HelloWorld(OneShotBehaviour):
        async def run(self):
            print("Hello World")
            await self.agent.stop()

    async def setup(self):
        self.add_behaviour(self.HelloWorld())

It is necessary that the name of the file is the same as the name of the agent's class so PEAK can do the proper parsing. This agent only has a behavior that prints to the terminal the "Hello World" message. To execute the agent just type the following command:

$ peak run path/to/agent.py -j agent@localhost

Change the localhost to the domain of the XMPP server you want to connect.

For more advanced functionalities and examples we recommend you to head forward to the documentation website.

Support

Use the Discussion page if you have any questions or ideas you would like so see implemented. To alert an issue or a bug please post in the Issues page.

Roadmap

This are some functionalities that are being developed and will be released in a near future:

• Integrate FIPA ACL messages in PEAK.
• Add dynamic speed option to PEAK's internal clock.
• Add multi-threading option to the Command Line Interface.
• Implement Yellow Page Service in the Directory Facilitator agent.
• Implement physical mobility in the agents.

Scientific Publications

• Ribeiro, B., Dias, D., Gomes, L., & Vale, Z. (2025). PEAK: Python-based framework for heterogeneous agent communities. SoftwareX, 30, 102190. https://doi.org/10.1016/j.softx.2025.102190
• Ribeiro, B., Pereira, H., Gomes, L., Vale, Z. (2023). Python-Based Ecosystem for Agent Communities Simulation. In: , et al. 17th International Conference on Soft Computing Models in Industrial and Environmental Applications (SOCO 2022). SOCO 2022. Lecture Notes in Networks and Systems, vol 531. Springer, Cham. https://doi.org/10.1007/978-3-031-18050-7_7
• Pereira H, Ribeiro B, Gomes L, Vale Z. Smart Grid Ecosystem Modeling Using a Novel Framework for Heterogenous Agent Communities. Sustainability. 2022; 14(23):15983. https://doi.org/10.3390/su142315983
• Silva C, Faria P, Ribeiro B, Gomes L, Vale Z. Demand Response Contextual Remuneration of Prosumers with Distributed Storage. Sensors. 2022; 22(22):8877. https://doi.org/10.3390/s22228877

Contributing to PEAK

Pull requests are welcome. For major changes, please open a discussion first to discuss what you would like to change.

The examples are used as a form of testing the framework. So please make sure to update the examples as appropriate or make new ones.

To format the code please use the black and isort packages.

For the commits please follow the Conventional Commits Guideline.

License

PEAK is free and open-source software licensed under the GNU General Public License v3.0.