# PEAK: Python-based framework for heterogenous agent communities
[](http://dx.doi.org/10.1016/j.softx.2025.102190)
[](https://pypi.org/project/peak-mas/)
[](https://pypi.org/project/peak-mas/)
[](https://github.com/gecad-group/peak-mas)
[](https://www.gecad.isep.ipp.pt/GECAD/Pages/Presentation/Home.aspx)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
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 <a href="https://spade-mas.readthedocs.io/en/latest/" target="_blank">SPADE</a>.
## Prerequisites
- Python == 3.9.6
- XMPP Server ([see docs](https://www.gecad.isep.ipp.pt/peak))
## Installing PEAK
### Conda
To install using conda, download the environment.yml file from the repository and then use the following command:
```bash
$ conda env create --file environment.yml
```
This will create a conda environment called _peak_.
### Pip
To install using pip, just type the following command:
```bash
$ 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 <a href="https://spade-mas.readthedocs.io/en/latest/" target="_blank">SPADE</a> 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 <a href="http://www.gecad.isep.ipp.pt/peak" target="_blank">documentation</a>.
#### 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:
```bash
$ 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`.
```python
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:
```bash
$ peak run path/to/agent.py -j agent@localhost
```
Change the `localhost` to the domain of the XMPP server you want to connect.
<details><summary>Note</summary>
<p>
If you want to know more about each command we recommend reading the [documentation](http://www.gecad.isep.ipp.pt/peak) or using the `-h` option to see the help message.
</p>
</details>
For more advanced functionalities and examples we recommend you to head forward to the <a href="http://www.gecad.isep.ipp.pt/peak" target="_blank">documentation website</a>.
## Support
Use the <a href="https://github.com/gecad-group/peak-mas/discussions" target="_blank">Discussion</a> 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 <a href="https://github.com/gecad-group/peak-mas/issues" target="_blank">Issues</a> 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 <a href="https://pypi.org/project/black/" target="_blank">black</a> and <a href="https://pypi.org/project/isort/" target="_blank">isort</a> packages.
For the commits please follow the <a href="www.conventionalcommits.org" target="_blank">Conventional Commits Guideline</a>.
## License
`PEAK` is free and open-source software licensed under the <a href="https://github.com/gecad-group/peak-mas/blob/develop/LICENSE" target="_blank">GNU General Public License v3.0</a>.
Raw data
{
"_id": null,
"home_page": null,
"name": "peak-mas",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.9.6",
"maintainer_email": null,
"keywords": "framework, multiagent, agent-based, ecosystem, spade, xmpp",
"author": null,
"author_email": "Bruno Ribeiro <brgri@isep.ipp.pt>, Luis Gomes <log@isep.ipp.pt>",
"download_url": "https://files.pythonhosted.org/packages/ae/76/4f0b7325ab1d18b3c4840a11f99f536dca851d10b198bcfce69f93c61cfb/peak_mas-1.2.0.tar.gz",
"platform": null,
"description": "# PEAK: Python-based framework for heterogenous agent communities\n\n[](http://dx.doi.org/10.1016/j.softx.2025.102190)\n[](https://pypi.org/project/peak-mas/)\n[](https://pypi.org/project/peak-mas/)\n[](https://github.com/gecad-group/peak-mas)\n[](https://www.gecad.isep.ipp.pt/GECAD/Pages/Presentation/Home.aspx)\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n\nPEAK 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. \nThis framework is based on <a href=\"https://spade-mas.readthedocs.io/en/latest/\" target=\"_blank\">SPADE</a>.\n\n\n## Prerequisites\n\n- Python == 3.9.6\n- XMPP Server ([see docs](https://www.gecad.isep.ipp.pt/peak))\n\n\n## Installing PEAK\n\n### Conda\n\nTo install using conda, download the environment.yml file from the repository and then use the following command:\n```bash\n$ conda env create --file environment.yml\t\n```\nThis will create a conda environment called _peak_.\n\n### Pip\n\nTo install using pip, just type the following command:\n```bash\n$ pip install peak-mas\n```\n\n\n## Using PEAK\n\n### Notes on SPADE\n\nAs 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 <a href=\"https://spade-mas.readthedocs.io/en/latest/\" target=\"_blank\">SPADE</a> examples and documentation before starting using PEAK. Once you are familiarized with SPADE's mechanics you can start using PEAK.\nFor now PEAK is not compatible with version above 3.2.2 of SPADE.\n\n### Notes on XMPP\n\nTo 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 <a href=\"http://www.gecad.isep.ipp.pt/peak\" target=\"_blank\">documentation</a>.\n\n#### Using docker\n\nTo 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:\n\n```bash\n$ docker-compose up -d\n```\n\n### Hello World Agent Example\n\nOne 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.\nIn this example we will show you how to execute a single agent. Save the following code in a file called `agent.py`.\n\n```python \nfrom peak import Agent, OneShotBehaviour\n\nclass agent(Agent):\n\u00a0 \u00a0 class HelloWorld(OneShotBehaviour):\n\u00a0 \u00a0 \u00a0 \u00a0 async def run(self):\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 print(\"Hello World\")\n\u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 await self.agent.stop()\n\n\u00a0 \u00a0 async def setup(self):\n\u00a0 \u00a0 \u00a0 \u00a0 self.add_behaviour(self.HelloWorld())\n```\nIt 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:\n```bash \n$ peak run path/to/agent.py -j agent@localhost\n```\nChange the `localhost` to the domain of the XMPP server you want to connect.\n\n<details><summary>Note</summary>\n<p>\n\nIf you want to know more about each command we recommend reading the [documentation](http://www.gecad.isep.ipp.pt/peak) or using the `-h` option to see the help message.\n\n</p>\n</details>\n\nFor more advanced functionalities and examples we recommend you to head forward to the <a href=\"http://www.gecad.isep.ipp.pt/peak\" target=\"_blank\">documentation website</a>.\n\n\n## Support\n\nUse the <a href=\"https://github.com/gecad-group/peak-mas/discussions\" target=\"_blank\">Discussion</a> page if you have any questions or ideas you would like so see implemented.\nTo alert an issue or a bug please post in the <a href=\"https://github.com/gecad-group/peak-mas/issues\" target=\"_blank\">Issues</a> page.\n\n## Roadmap\n\nThis are some functionalities that are being developed and will be released in a near future:\n- [ ] Integrate FIPA ACL messages in PEAK.\n- [ ] Add dynamic speed option to PEAK's internal clock.\n- [ ] Add multi-threading option to the Command Line Interface.\n- [ ] Implement Yellow Page Service in the Directory Facilitator agent.\n- [ ] Implement physical mobility in the agents.\n\n## Scientific Publications\n\n- 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\n- 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\n- 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\n- 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\n\n\n## Contributing to PEAK\n\nPull requests are welcome. For major changes, please open a discussion first to discuss what you would like to change.\n\nThe examples are used as a form of testing the framework. So please make sure to update the examples as appropriate or make new ones. \n\nTo format the code please use the <a href=\"https://pypi.org/project/black/\" target=\"_blank\">black</a> and <a href=\"https://pypi.org/project/isort/\" target=\"_blank\">isort</a> packages. \n\nFor the commits please follow the <a href=\"www.conventionalcommits.org\" target=\"_blank\">Conventional Commits Guideline</a>.\n\n## License\n\n`PEAK`\u00a0is free and open-source software licensed under the <a href=\"https://github.com/gecad-group/peak-mas/blob/develop/LICENSE\" target=\"_blank\">GNU General Public License v3.0</a>.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python-based framework for heterogeneous agent communities",
"version": "1.2.0",
"project_urls": {
"Github": "https://github.com/gecad-group/peak-mas",
"Homepage": "https://www.gecad.isep.ipp.pt/peak"
},
"split_keywords": [
"framework",
" multiagent",
" agent-based",
" ecosystem",
" spade",
" xmpp"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "62ea5852967eb67188fefaa09d2cb0e11587613214f88f87402a0a78624b020e",
"md5": "b4b3fb9d661b3fa6dba22c58677edea4",
"sha256": "87ca873d1652839ee6163a9772d12a0cf89783267286e8c81f595e8c368423e6"
},
"downloads": -1,
"filename": "peak_mas-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4b3fb9d661b3fa6dba22c58677edea4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.9.6",
"size": 38194,
"upload_time": "2025-07-28T12:32:01",
"upload_time_iso_8601": "2025-07-28T12:32:01.827681Z",
"url": "https://files.pythonhosted.org/packages/62/ea/5852967eb67188fefaa09d2cb0e11587613214f88f87402a0a78624b020e/peak_mas-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ae764f0b7325ab1d18b3c4840a11f99f536dca851d10b198bcfce69f93c61cfb",
"md5": "9991bc8b9f16d5970a785ef468fd374d",
"sha256": "cdbc4757948aed255cb3bd7556a85b08cb0c4333415e8cc193b6f2701a1f7fe8"
},
"downloads": -1,
"filename": "peak_mas-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "9991bc8b9f16d5970a785ef468fd374d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.9.6",
"size": 33837,
"upload_time": "2025-07-28T12:32:03",
"upload_time_iso_8601": "2025-07-28T12:32:03.435526Z",
"url": "https://files.pythonhosted.org/packages/ae/76/4f0b7325ab1d18b3c4840a11f99f536dca851d10b198bcfce69f93c61cfb/peak_mas-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 12:32:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gecad-group",
"github_project": "peak-mas",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp_cors",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "aioxmpp",
"specs": [
[
"==",
"0.13.2"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"1.4.2"
]
]
},
{
"name": "pyModbusTCP",
"specs": [
[
"==",
"0.2.0"
]
]
},
{
"name": "PyYAML",
"specs": [
[
"==",
"6.0"
]
]
},
{
"name": "spade",
"specs": [
[
"==",
"3.2.2"
]
]
}
],
"lcname": "peak-mas"
}
JSON
