| Name | mango-agents-assume JSON |
| Version |
1.2.0.post1
JSON |
| download |
| home_page | None |
| Summary | Modular Python Agent Framework - Temporary Fork of mango for development purpose |
| upload_time | 2024-10-13 23:34:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License Copyright (c) 2020 OFFIS e.V. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
agent based simulation
simulation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mango
[PyPi](https://pypi.org/project/mango-agents/) | [Read the Docs](https://mango-agents.readthedocs.io)
| [Github](https://github.com/OFFIS-DAI/mango) | [mail](mailto:mango@offis.de)
**Note:** _This project is still in an early development stage.
We appreciate constructive feedback and suggestions for improvement._
mango (**m**odul**a**r pytho**n** a**g**ent framew**o**rk) is a python library for multi-agent systems (MAS).
It is written on top of asyncio and is released under the MIT license.
mango allows the user to create simple agents with little effort and in the same time offers options
to structure agents with complex behaviour.
The main features of mango are:
- Container mechanism to speedup local message exchange
- Message definition based on the FIPA ACL standard
- Structuring complex agents with loose coupling and agent roles
- Built-in codecs: JSON and protobuf
- Supports communication between agents directly via TCP or via an external MQTT broker
A detailed documentation for this project can be found at [mango-agents.readthedocs.io](https://mango-agents.readthedocs.io)
## Installation
*mango* requires Python >= 3.8 and runs on Linux, OSX and Windows.
For installation of mango you should use
[virtualenv](https://virtualenv.pypa.io/en/latest/#) which can create isolated Python environments for different projects.
It is also recommended to install
[virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/index.html)
which makes it easier to manage different virtual environments.
Once you have created a virtual environment you can just run [pip](https://pip.pypa.io/en/stable/) to install it:
$ pip install mango-agents
## Getting started
####Creating an agent
In our first example, we'll create a very simple agent that simply prints the content of
all messages it receives:
```python
from mango import Agent
class RepeatingAgent(Agent):
def __init__(self, container):
# We must pass a ref of the container to "mango.Agent":
super().__init__(container)
print(f"Hello world! My id is {self.aid}.")
def handle_message(self, content, meta):
# This method defines what the agent will do with incoming messages.
print(f"Received a message with the following content: {content}")
```
Agents must be a subclass of `Agent`. This base class needs
a reference to the container the agents live in, so you must forward
a *container* argument to it if you override `__init__()`.
####Creating a container
Agents live in a container, so we need to know how to create a mango container.
The container is responsible for message exchange between agents.
```python3
# Containers need to be started via a factory function.
# This method is a coroutine so it needs to be called using the
# await statement
first_container = await create_container(addr=('localhost', 5555))
```
This is how a container is created. Since the method `create_container()` is a
[coroutine](https://docs.python.org/3.9/library/asyncio-task.html) we need to await its result.
#### Running your first agent within a container
To put it all together we will wrap the creation of a container and the agent into a coroutine
and execute it using `asyncio.run()`.
The following script will create a RepeatingAgent
and let it run within a container for three seconds and
then shutdown the container:
```python
import asyncio
from mango import Agent, create_container
class RepeatingAgent(Agent):
def __init__(self, container):
# We must pass a ref. to the container to "mango.Agent":
super().__init__(container)
print(f"Hello world! My id is {self.aid}.")
def handle_message(self, content, meta):
# This method defines what the agent will do with incoming messages.
print(f"Received a message with the following content: {content}")
async def run_container_and_agent(addr, duration):
first_container = await create_container(addr=addr)
first_agent = RepeatingAgent(first_container)
await asyncio.sleep(duration)
await first_agent.shutdown()
await first_container.shutdown()
asyncio.run(run_container_and_agent(addr=('localhost', 5555), duration=3))
```
The only output you should see is `Hello world! My id is agent0.`, because
the agent does yet not receive any messages.
#### Creating a proactive Agent
Let's implement another agent that is able to send a hello world message
to another agent:
```python3
from mango import Agent
from mango.util.scheduling import InstantScheduledTask
class HelloWorldAgent(Agent):
def __init__(self, container, other_addr, other_id):
super().__init__(container)
self.schedule_instant_acl_message(
receiver_addr=other_addr,
receiver_id=other_id,
content="Hello world!")
)
def handle_message(self, content, meta):
print(f"Received a message with the following content: {content}")
```
#### Connecting two agents
We can now connect an instance of a HelloWorldAgent with an instance of a RepeatingAgent and run them.
```python
import asyncio
from mango import Agent, create_container
from mango.util.scheduling import InstantScheduledTask
class RepeatingAgent(Agent):
def __init__(self, container):
# We must pass a ref. to the container to "mango.Agent":
super().__init__(container)
print(f"Hello world! My id is {self.aid}.")
def handle_message(self, content, meta):
# This method defines what the agent will do with incoming messages.
print(f"Received a message with the following content: {content}")
class HelloWorldAgent(Agent):
def __init__(self, container, other_addr, other_id):
super().__init__(container)
self.schedule_instant_acl_message(
receiver_addr=other_addr,
receiver_id=other_id,
content="Hello world!")
)
def handle_message(self, content, meta):
print(f"Received a message with the following content: {content}")
async def run_container_and_two_agents(first_addr, second_addr):
first_container = await create_container(addr=first_addr)
second_container = await create_container(addr=second_addr)
first_agent = RepeatingAgent(first_container)
second_agent = HelloWorldAgent(second_container, first_container.addr, first_agent.aid)
await asyncio.sleep(1)
await first_agent.shutdown()
await second_agent.shutdown()
await first_container.shutdown()
await second_container.shutdown()
def test_second_example():
asyncio.run(run_container_and_two_agents(
first_addr=('localhost', 5555), second_addr=('localhost', 5556))
)
```
You should now see the following output:
`Hello world! My id is agent0.`
`Received a message with the following content: Hello world!`
You have now successfully created two agents and connected them.
## Support
- Documentation: [mango-agents.readthedocs.io](https://mango-agents.readthedocs.io)
- E-mail: [mango@offis.de](mailto:mango@offis.de)
## License
Distributed under the MIT license.
[comment]: <> (##TODO Release History * 0.0.1 First TCPContainer with json)
[comment]: <> (* 0.0.2 * Added MQTTContainer and protobuf support )
Raw data
{
"_id": null,
"home_page": null,
"name": "mango-agents-assume",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "agent based simulation, simulation",
"author": null,
"author_email": "Mango Developers <mango@offis.de>, Florian Maurer <fmaurer@disroot.org>",
"download_url": "https://files.pythonhosted.org/packages/e1/f2/998ef136855d76b9c64f64db49dedebc52236f5ef5bf6bccffeca0143c53/mango_agents_assume-1.2.0.post1.tar.gz",
"platform": null,
"description": "# mango\n\n[PyPi](https://pypi.org/project/mango-agents/) | [Read the Docs](https://mango-agents.readthedocs.io)\n| [Github](https://github.com/OFFIS-DAI/mango) | [mail](mailto:mango@offis.de)\n\n**Note:** _This project is still in an early development stage.\nWe appreciate constructive feedback and suggestions for improvement._\n\nmango (**m**odul**a**r pytho**n** a**g**ent framew**o**rk) is a python library for multi-agent systems (MAS).\nIt is written on top of asyncio and is released under the MIT license.\n\nmango allows the user to create simple agents with little effort and in the same time offers options\nto structure agents with complex behaviour.\n\nThe main features of mango are:\n - Container mechanism to speedup local message exchange\n - Message definition based on the FIPA ACL standard\n - Structuring complex agents with loose coupling and agent roles\n - Built-in codecs: JSON and protobuf\n - Supports communication between agents directly via TCP or via an external MQTT broker\n\nA detailed documentation for this project can be found at [mango-agents.readthedocs.io](https://mango-agents.readthedocs.io)\n\n## Installation\n\n*mango* requires Python >= 3.8 and runs on Linux, OSX and Windows.\n\nFor installation of mango you should use\n[virtualenv](https://virtualenv.pypa.io/en/latest/#) which can create isolated Python environments for different projects.\n\nIt is also recommended to install\n[virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/index.html)\nwhich makes it easier to manage different virtual environments.\n\nOnce you have created a virtual environment you can just run [pip](https://pip.pypa.io/en/stable/) to install it:\n\n $ pip install mango-agents\n\n## Getting started\n\n####Creating an agent\n\nIn our first example, we'll create a very simple agent that simply prints the content of\nall messages it receives:\n\n```python\n\n from mango import Agent\n\n class RepeatingAgent(Agent):\n def __init__(self, container):\n # We must pass a ref of the container to \"mango.Agent\":\n super().__init__(container)\n print(f\"Hello world! My id is {self.aid}.\")\n\n def handle_message(self, content, meta):\n # This method defines what the agent will do with incoming messages.\n print(f\"Received a message with the following content: {content}\")\n```\nAgents must be a subclass of `Agent`. This base class needs\na reference to the container the agents live in, so you must forward\na *container* argument to it if you override `__init__()`.\n\n####Creating a container\n\nAgents live in a container, so we need to know how to create a mango container.\nThe container is responsible for message exchange between agents.\n\n```python3\n\n # Containers need to be started via a factory function.\n # This method is a coroutine so it needs to be called using the\n # await statement\n first_container = await create_container(addr=('localhost', 5555))\n```\n\nThis is how a container is created. Since the method `create_container()` is a\n[coroutine](https://docs.python.org/3.9/library/asyncio-task.html) we need to await its result.\n\n#### Running your first agent within a container\n\nTo put it all together we will wrap the creation of a container and the agent into a coroutine\nand execute it using `asyncio.run()`.\nThe following script will create a RepeatingAgent\nand let it run within a container for three seconds and\nthen shutdown the container:\n\n```python\n\n import asyncio\n from mango import Agent, create_container\n\n class RepeatingAgent(Agent):\n def __init__(self, container):\n # We must pass a ref. to the container to \"mango.Agent\":\n super().__init__(container)\n print(f\"Hello world! My id is {self.aid}.\")\n\n def handle_message(self, content, meta):\n # This method defines what the agent will do with incoming messages.\n print(f\"Received a message with the following content: {content}\")\n\n async def run_container_and_agent(addr, duration):\n first_container = await create_container(addr=addr)\n first_agent = RepeatingAgent(first_container)\n await asyncio.sleep(duration)\n await first_agent.shutdown()\n await first_container.shutdown()\n\n asyncio.run(run_container_and_agent(addr=('localhost', 5555), duration=3))\n```\nThe only output you should see is `Hello world! My id is agent0.`, because\nthe agent does yet not receive any messages.\n\n#### Creating a proactive Agent\n\nLet's implement another agent that is able to send a hello world message\nto another agent:\n\n```python3\n\n from mango import Agent\n from mango.util.scheduling import InstantScheduledTask\n\n class HelloWorldAgent(Agent):\n def __init__(self, container, other_addr, other_id):\n super().__init__(container)\n self.schedule_instant_acl_message(\n receiver_addr=other_addr,\n receiver_id=other_id,\n content=\"Hello world!\")\n )\n\n def handle_message(self, content, meta):\n print(f\"Received a message with the following content: {content}\")\n```\n#### Connecting two agents\nWe can now connect an instance of a HelloWorldAgent with an instance of a RepeatingAgent and run them.\n```python\nimport asyncio\nfrom mango import Agent, create_container\nfrom mango.util.scheduling import InstantScheduledTask\n\n\nclass RepeatingAgent(Agent):\n def __init__(self, container):\n # We must pass a ref. to the container to \"mango.Agent\":\n super().__init__(container)\n print(f\"Hello world! My id is {self.aid}.\")\n\n def handle_message(self, content, meta):\n # This method defines what the agent will do with incoming messages.\n print(f\"Received a message with the following content: {content}\")\n\nclass HelloWorldAgent(Agent):\n def __init__(self, container, other_addr, other_id):\n super().__init__(container)\n self.schedule_instant_acl_message(\n receiver_addr=other_addr,\n receiver_id=other_id,\n content=\"Hello world!\")\n )\n\n def handle_message(self, content, meta):\n print(f\"Received a message with the following content: {content}\")\n\n\nasync def run_container_and_two_agents(first_addr, second_addr):\n first_container = await create_container(addr=first_addr)\n second_container = await create_container(addr=second_addr)\n first_agent = RepeatingAgent(first_container)\n second_agent = HelloWorldAgent(second_container, first_container.addr, first_agent.aid)\n await asyncio.sleep(1)\n await first_agent.shutdown()\n await second_agent.shutdown()\n await first_container.shutdown()\n await second_container.shutdown()\n\n\ndef test_second_example():\n asyncio.run(run_container_and_two_agents(\n first_addr=('localhost', 5555), second_addr=('localhost', 5556))\n )\n\n```\n\nYou should now see the following output:\n\n`Hello world! My id is agent0.`\n\n`Received a message with the following content: Hello world!`\n\nYou have now successfully created two agents and connected them.\n\n## Support\n- Documentation: [mango-agents.readthedocs.io](https://mango-agents.readthedocs.io)\n- E-mail: [mango@offis.de](mailto:mango@offis.de)\n\n## License\n\nDistributed under the MIT license.\n\n[comment]: <> (##TODO Release History * 0.0.1 First TCPContainer with json)\n[comment]: <> (* 0.0.2 * Added MQTTContainer and protobuf support )\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2020 OFFIS e.V. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Modular Python Agent Framework - Temporary Fork of mango for development purpose",
"version": "1.2.0.post1",
"project_urls": {
"Homepage": "https://mango-agents.readthedocs.io/",
"Repository": "https://github.com/maurerle/mango"
},
"split_keywords": [
"agent based simulation",
" simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1eaf5cab8ad749a85d3acaaae84cbd73fc9ce315bef20bbbfe7af1cf2806b98c",
"md5": "3a90fc7c4ffd9fd9fd33f4dae5ca59eb",
"sha256": "d1a4322ef7413db2e3c8a4410b36d599a2170e35aca8111b134b0d41b6d9c831"
},
"downloads": -1,
"filename": "mango_agents_assume-1.2.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3a90fc7c4ffd9fd9fd33f4dae5ca59eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 62348,
"upload_time": "2024-10-13T23:34:06",
"upload_time_iso_8601": "2024-10-13T23:34:06.141676Z",
"url": "https://files.pythonhosted.org/packages/1e/af/5cab8ad749a85d3acaaae84cbd73fc9ce315bef20bbbfe7af1cf2806b98c/mango_agents_assume-1.2.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e1f2998ef136855d76b9c64f64db49dedebc52236f5ef5bf6bccffeca0143c53",
"md5": "4db1e1a2eebd3691b7c8cc9e86c6c883",
"sha256": "9b5b53c68510bdf0a65c8c183f3f56a426d9ddf880000e3f3bbada10457827ed"
},
"downloads": -1,
"filename": "mango_agents_assume-1.2.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "4db1e1a2eebd3691b7c8cc9e86c6c883",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 159560,
"upload_time": "2024-10-13T23:34:07",
"upload_time_iso_8601": "2024-10-13T23:34:07.841576Z",
"url": "https://files.pythonhosted.org/packages/e1/f2/998ef136855d76b9c64f64db49dedebc52236f5ef5bf6bccffeca0143c53/mango_agents_assume-1.2.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-13 23:34:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maurerle",
"github_project": "mango",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "mango-agents-assume"
}
