[](https://github.com/root-11/maslite/actions/workflows/python-app.yml)
[](https://codecov.io/gh/root-11/maslite)
[](https://pepy.tech/project/maslite)
[](https://pepy.tech/project/maslite/month)
[](https://badge.fury.io/py/maslite)
# MASlite
A multi-agent platform contrived by [Bjorn Madsen](https://uk.linkedin.com/in/bmadsen)
For a comprehensive tutorial by Max Yu, go here: [Tutorial.ipynb](https://nbviewer.org/github/root-11/maslite/blob/master/tutorial/tutorial.ipynb)
All right reserved © 2016-2023. MIT-license. All code has been written by the author in isolation and any similarity to other systems is purely coincidental.
--------------
**New in version 2022.11.4**
- update of agents now follows a strict order as inserted.
--------------
#### MASlite explained in 60 seconds:
MASlite is a simle python module for creating multi-agent simulations.
- _Simple_ API: Only 3 modules to learn: Scheduler, Agent & Agent message
- _Fast_: Handles up to 2.7M messages per second ([pypy, py310](./benchmark.py))
- _Lightweight_: 52kB.
It only has 3 components:
- The scheduler (main loop)
- handles pause and proceed with a single call.
- assures repeatability in execution, which makes agents easy to debug.
- handles up to 2.7M messages per second (pypy)
- Agent's
- are python classes that have setup(), update() and teardown() methods that can be customized.
- can exchange messages using send() and receive().
- can subscribe/unsubscribe to message classes.
- have clocks and can set alarms.
- can be tested individually.
- can have independent I/O/Database interaction.
- Messages
- that have sender and receiver enable direct communication
- that have topics and no receiver are treated as broadcasts, and sent to subscribers.
The are plenty of use-cases for MASlite:
- Prototyping MASSIVE™ type games.
- Creating data processing pipeline
- Optimisation Engine, for:
- Scheduling (using Bjorn Madsen's distributed scheduling method)
- Auctions (using Dimtry Bertsekas alternating iterative auction)
-------------------
All the user needs to worry about are the protocols of interaction,
which conveniently may be summarised as:
1. Design the messages that an agent will send or receive as regular
python objects that inherit the necessary implementation details from
a basic `AgentMessage`. The messages must have an unambiguous `topic`.
2. Write the functions that are supposed to execute once an agent
receives one of the messages.
3. Update the agents operations (`self.operations`) with a dictionary
that describes the relationship between `topic` and `function`.
4. Write the update function that maintains the inner state of the agent
using `send` to send messages, and using `receive` to get messages.
The user can thereby create an agent using just:
class HelloMessage(AgentMessage):
def __init__(self, sender, receiver)
super().__init__(sender=sender, receiver=receiver)
class myAgent(Agent):
def __init__(self):
super().__init__()
self.operations[HelloMessage.__name__] = self.hello
def update(self):
while self.messages:
msg = self.receive()
operation = self.operations.get(msg.topic))
if operation is not None:
operation(msg)
else:
self.logger.debug("%s: don't know what to do with: %s" % (self.uuid), str(msg)))
def hello(self, msg)
print(msg)
That simple!
The dictionary `self.operations` which is inherited from the `Agent`-class
is updated with `HelloMessage.__name__` pointing to the function `self.hello`.
`self.operations` thereby acts
as a pointer for when a `HelloMessage` arrives, so when the agents
update function is called, it will get the topic from the message's and
point to the function `self.hello`, where `self.hello` in this simple
example just prints the content of the message.
More nuanced behaviour, can also be embedded without the user having
to worry about any externals. For example if some messages take
precedence over others (priority messages), the inbox should be emptied
in the beginning of the update function for sorting.
Here is an example where some topics are treated with priority over
others:
class AgentWithPriorityInbox(Agent):
def __init__(self):
super().__init__()
self.operations.update({"1": self.some_priority_function,
"2": self.some_function,
"3": self.some_function, # Same function for 2 topics.!
"hello": self.hello, })
self.priority_topics = ["1","2","3"]
self.priority_messages = deque() # from collections import deque
self.normal_messages = deque() # deques append and popleft are threadsafe.
def update(self):
# 1. Empty the inbox and sort the messages using the topic:
while self.messages:
msg = self.receive()
if msg.topic in self.priority_topics:
self.priority_messages.append(msg)
else:
self.normal_messages.append(msg)
# 2. We've now sorted the incoming messages and can now extend
# the priority message deque with the normal messages:
self.priority_messages.extend(normal_messages)
# 3. Next we process them as usual:
while self.priority_messages:
msg = self.priority_messages.popleft()
operation = self.operations.get(msg.topic)
if operation is not None:
operation(msg)
else:
...
The only thing which the user needs to worry about, is that the update
function cannot depend on any externals. The agent is confined to
sending (`self.send(msg)`) and receiving (`msg = self.receive()`)
messages which must be processed within the function `self.update`.
Any responses to sent messages will not happen until the agent runs
update again.
If any state needs to be stored within the agent, such as for example
memory of messages sent or received, then the agents `__init__` should
declare the variables as class variables and store the information.
Calls to databases, files, etc. can of course happen, including the usage
of `self.setup()` and `self.teardown()` which are called when the agent
is, respectively, started or stopped. See the boiler-plate (below) for a more
detailed description.
### Boilerplate
The following boiler-plate allows the user to manage the whole lifecycle
of an agent, including:
1. add variables to `__init__` which can store information between updates.
2. react to topics by extending `self.operations`
2. extend `setup` and `teardown` for start and end of the agents lifecycle.
4. use `update` with actions before(1), during(2) and after(3) reading messages.
There are no requirements, for using all functions. The boiler-plate merely
seeks to illustrate typical usage.
There are also no requirements for the agent to be programmed in procedural,
functional or object oriented manner. Doing that is completely up to the
user of MASlite.
class Example(Agent):
def __init__(self, db_connection):
super().__init__()
# add variables here.
self._is_setup = False
self.db_connection = db_connection
# remember to register topics and their functions:
self.operations.update({"topic x": self.x,
"topic y": self.y,
"topic ...": self....})
def update(self):
assert self._is_setup
# do something before reading messages
self.action_before_processing_messages()
# read the messages
while self.messages:
msg = self.receive()
# react immediately to some messages:
operation = self.operations.get(msg.topic)
if operation is not None:
operation(msg)
# react after reading all messages:
self.action_after_processing_all_messages()
# Functions added by the user that are not inherited from the
# `Agent`-class. If the `update` function should react on these,
# the topic of the message must be in the self.operations dict.
def setup(self):
self._is_setup = True
# add own setup operations here.
self.subscribe(self.__class__.__name__)
def action_before_processing_messages(self)
# do something.
def action_after_processing_all_messages(self)
# do something. Perhaps send a message to somebody that update is done?
msg = DoneMessages(sender=self, receiver=SomeOtherAgent)
self.send(msg)
def x(msg):
# read msg and send a response
from_ = msg.sender
response = SomeMessage(sender=self, receiver=from_)
self.send(response)
def y(msg):
with db_connection as db.:
db.somefield.update(time.time())
def teardown(self):
# add own teardown operations here.
self.db_connection.close()
### Messages
Messages are objects and are required to use the base class `AgentMessage`.
When agents receive messages they should be interpreted by their topic, which
should (by convention) also be the class name of the message. Practice has shown
that there are no obvious reasons where this convention shouldn't apply, so
messages which don't have a topic declared explicitly inherit the class name.
An example is shown below:
>>> from maslite import AgentMessage
>>> class MyMsg(AgentMessage):
... def __init__(self, sender, receiver):
... super().__init__(sender=sender, receiver=receiver)
...
>>> m = MyMsg(sender=1, receiver=2)
>>> m.topic
'MyMsg'
Adding functions to messages. Below is an example of a message with it's own
function(s):
class DatabaseUpdateMessage(AgentMessage):
""" Description of the message """
def __init__(self, sender, senders_db_alias):
super().__init__(sender=sender, receiver=DatabaseAgent.__name__)
self.senders_db_alias
self._states = {1: 'new', 2: 'read'}
self._state = 1
def get_senders_alias(self):
return self.senders_db_alias
def __next__(self)
if self._state + 1 <= max(self._states.keys()):
self._state += 1
def state(self):
return self._states[self._state]
The class `DatabaseUpdateMessage` is subclassed from the `AgentMessage` so that
the basic message handling properties are available for the DatabaseUpdateMessage.
This helps the user as s/he doesn't need to know anything about how the message
handling system works.
The init function requires a sender, which normally defaults to the agent's `self`.
The `AgentMessage` knows that if it gets an agent in it's `__init__` call, it will
obtain the agents UUID and use that. Similar applies to a receiver, where the typical
operation is based on that the local agent gets a message from the sender and only
knows the sender based on msg.get_sender() which returns the sending agents UUID.
If the sender might change UUID, in the course of multiple runs, the local agent
should be instructed to use, for example, the `senders_db_alias`. For the purpose
of illustration, the message above contains the function `get_senders_alias` which
then can be persistent over multiple runs.
The message is also designed to be returned to save pythons garbage collector:
When the DatabaseAgent receives the message, the `__next__`-function allows the
agent to call `next(msg)` to progress it's `self._state` from '1' (new) to '2' (read)
before returning it to the sender using 'self.send(msg)'. In such case it is
important that the DatabaseAgent doesn't store the message in its variables, as
the message must __not__ have any open object pointers when sent. This is due to
multiprocessing which uses `multiprocessing.queue`s for exchanging messages, which
require that `Agent`s and `AgentMessage`s can be pickled.
If an `Agent` can't be pickled when added to the `Scheduler`, the scheduler will
raise an error explaining that the are open pointer references. Messages are a
bit more tolerant as the `mailman` that manages the messages will try to send
the message and hope that the shared pointer will not cause conflicts. If sharing
of object pointers is required by the user (for example during prototyping) the
scheduler must be set up with `number_of_multiprocessors=0` which forces the
scheduler to run single-process-single-threaded.
__Message Conventions__:
* Messages which have `None` as receiver are considered broadcasts. The logic is
that if you don't know who exactly you are sending it to, send it it to `None`, and
you might get a response if any other agent react on the topic of the message.
The magic behind the scenes is handled by the schedulers mail manager
which keeps track of all topics that any `Agent` subscribes to.
By convention the topic of the message should be `self.__class__.__name__`.
* Messages which have a `class.__name__` as receiver, will be received by all agents
of that class. This is configured when the agent is added to the scheduler in `s.add(agent)`
* Messages which have a particular UUID as receiver, will be received by the agent
holding that UUID. If anyone other agent is tracking that UUID, by subscribing to
it, then the tracking agent will receive a `deepcopy` of the message, and not the
original. If the message has a `copy` method, this will be used instead of deepcopy.
* To get the UUID of the sender the method `msg.sender` is available.
* To subscribe/unsubscribe during runtime the agents should use the `subscribe`
function directly.
### How to load data from a database connection
When agents are added to the scheduler `setup` is run.
When agents are removed from `teardown` is run.
if agents are added and removed iteratively, they should load their
state during `setup` and store it during `teardown` from some database.
It is not necessary to let the scheduler know where the database is.
The agents can keep track of this themselves.
Though the user might find it attractive to use `uuid` to identify, a particular
`Agent` the user should set the `uuid` in `super().__init__(uuid="this")`, as a the
`uuid` otherwise will be given be the scheduler.
### Getting started
To get started only 3 steps are required:
Step 1. setup a scheduler
>>> from maslite import Agent, Scheduler
>>> s = Scheduler()
Step 2. create agents which have an `update` method and (optionally)
a `setup` and `teardown`.
>>> class MyAgent(Agent):
... def __init__(self):
... super().__init__()
... def setup(self):
... pass
... def teardown(self):
... pass
... def update(self):
... pass
>>> m = MyAgent()
>>> s.add(m)
Step 3. run the scheduler (nothing happens here)
>>> s.run(pause_if_idle=True)
Other methods such as `s.run(seconds=None, iterations=None,
pause_if_idle=False)` can be applied as the user finds it suitable.
Step 4. to stop the scheduler there are the following options:
1. Let it run until idle (most common)
2. Run for N seconds (suitable for real-time systems),
3. Run for N iterations (suitable for interrupt checking)
Then leave the scheduler (and all the agents) in their set state, for
example to read the state of particular agents; and finally
execute the `teardown` method, on all agents in a loop:
>>> for uid, agent in s.agents.items():
... agent.teardown()
### Debugging with pdb or breakpoints (PyCharm)
Debugging is easily performed by putting breakpoint at the beginning of
the update function. In that way you can watch what happens inside the
agent during its state-update.
### Typical mistakes
The user constructs the agent correctly with:
1. the methods `update`, `send`, `receive`, `setup` and `teardown`,
2. adding the agent to the scheduler using `scheduler.add(agent)`.
3. runs the scheduler using `scheduler.run()`,
...but...
Q: The agents don't seem to update?
A: The agents are not getting any messages and are therefore not updated.
This is correct behaviour, as `update` only should run when there are
new messages!
To force agents to run `update` in every scheduling cycle, use the hidden
method: `agent.keep_awake=True`. Doing this blindly however is a poor design
choice if the agent merely is polling for data. For this purpose
`agent.set_alarm_clock(agent.now()+1)` should be used, as this allows the
agent to sleep for 1 second and the be "woken up" by the alarm message.
The reason it is recommended to use the alarm instead of setting
`keep_awake=True` is that the workload of the system remains transparent
at the level of message exchange. Remember that the internal state of
the agents should always be hidden whilst the messages should be
indicative of any activity.
...
Raw data
{
"_id": null,
"home_page": "https://github.com/root-11/maslite",
"name": "MASlite",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "multi agent system,MAS,maslite",
"author": "root-11",
"author_email": "",
"download_url": "",
"platform": "any",
"description": "[](https://github.com/root-11/maslite/actions/workflows/python-app.yml)\n[](https://codecov.io/gh/root-11/maslite)\n[](https://pepy.tech/project/maslite)\n[](https://pepy.tech/project/maslite/month)\n[](https://badge.fury.io/py/maslite)\n\n# MASlite\nA multi-agent platform contrived by [Bjorn Madsen](https://uk.linkedin.com/in/bmadsen)\n\nFor a comprehensive tutorial by Max Yu, go here: [Tutorial.ipynb](https://nbviewer.org/github/root-11/maslite/blob/master/tutorial/tutorial.ipynb)\n\nAll right reserved © 2016-2023. MIT-license. All code has been written by the author in isolation and any similarity to other systems is purely coincidental. \n\n--------------\n\n**New in version 2022.11.4** \n\n- update of agents now follows a strict order as inserted.\n\n--------------\n\n#### MASlite explained in 60 seconds:\n\nMASlite is a simle python module for creating multi-agent simulations.\n\n- _Simple_ API: Only 3 modules to learn: Scheduler, Agent & Agent message\n- _Fast_: Handles up to 2.7M messages per second ([pypy, py310](./benchmark.py))\n- _Lightweight_: 52kB.\n\nIt only has 3 components:\n\n- The scheduler (main loop)\n - handles pause and proceed with a single call.\n - assures repeatability in execution, which makes agents easy to debug.\n - handles up to 2.7M messages per second (pypy)\n\n- Agent's \n\n - are python classes that have setup(), update() and teardown() methods that can be customized. \n - can exchange messages using send() and receive().\n - can subscribe/unsubscribe to message classes.\n - have clocks and can set alarms.\n - can be tested individually.\n - can have independent I/O/Database interaction.\n \n- Messages\n - that have sender and receiver enable direct communication\n - that have topics and no receiver are treated as broadcasts, and sent to subscribers.\n \nThe are plenty of use-cases for MASlite:\n\n- Prototyping MASSIVE™ type games.\n- Creating data processing pipeline\n- Optimisation Engine, for:\n - Scheduling (using Bjorn Madsen's distributed scheduling method)\n - Auctions (using Dimtry Bertsekas alternating iterative auction)\n \n-------------------\n\nAll the user needs to worry about are the protocols of interaction, \nwhich conveniently may be summarised as:\n\n1. Design the messages that an agent will send or receive as regular \npython objects that inherit the necessary implementation details from \na basic `AgentMessage`. The messages must have an unambiguous `topic`.\n2. Write the functions that are supposed to execute once an agent \n receives one of the messages.\n3. Update the agents operations (`self.operations`) with a dictionary\nthat describes the relationship between `topic` and `function`.\n4. Write the update function that maintains the inner state of the agent\nusing `send` to send messages, and using `receive` to get messages.\n\nThe user can thereby create an agent using just:\n\n class HelloMessage(AgentMessage):\n def __init__(self, sender, receiver)\n super().__init__(sender=sender, receiver=receiver)\n \n \n class myAgent(Agent):\n def __init__(self):\n super().__init__()\n self.operations[HelloMessage.__name__] = self.hello\n \n def update(self):\n while self.messages:\n msg = self.receive()\n operation = self.operations.get(msg.topic))\n if operation is not None:\n operation(msg)\n else:\n self.logger.debug(\"%s: don't know what to do with: %s\" % (self.uuid), str(msg)))\n \n def hello(self, msg)\n print(msg)\n\n\nThat simple!\n\nThe dictionary `self.operations` which is inherited from the `Agent`-class\nis updated with `HelloMessage.__name__` pointing to the function `self.hello`. \n`self.operations` thereby acts \nas a pointer for when a `HelloMessage` arrives, so when the agents \nupdate function is called, it will get the topic from the message's and \npoint to the function `self.hello`, where `self.hello` in this simple\nexample just prints the content of the message. \n\nMore nuanced behaviour, can also be embedded without the user having\nto worry about any externals. For example if some messages take \nprecedence over others (priority messages), the inbox should be emptied \nin the beginning of the update function for sorting. \n\nHere is an example where some topics are treated with priority over \nothers:\n\n class AgentWithPriorityInbox(Agent):\n def __init__(self):\n super().__init__()\n self.operations.update({\"1\": self.some_priority_function, \n \"2\": self.some_function, \n \"3\": self.some_function, # Same function for 2 topics.! \n \"hello\": self.hello, })\n self.priority_topics = [\"1\",\"2\",\"3\"]\n self.priority_messages = deque() # from collections import deque\n self.normal_messages = deque() # deques append and popleft are threadsafe.\n \n def update(self):\n # 1. Empty the inbox and sort the messages using the topic:\n while self.messages:\n msg = self.receive()\n if msg.topic in self.priority_topics:\n self.priority_messages.append(msg)\n else:\n self.normal_messages.append(msg)\n \n # 2. We've now sorted the incoming messages and can now extend\n # the priority message deque with the normal messages:\n self.priority_messages.extend(normal_messages)\n \n # 3. Next we process them as usual:\n while self.priority_messages:\n msg = self.priority_messages.popleft()\n operation = self.operations.get(msg.topic)\n if operation is not None:\n operation(msg)\n else:\n ...\n\nThe only thing which the user needs to worry about, is that the update\nfunction cannot depend on any externals. The agent is confined to\nsending (`self.send(msg)`) and receiving (`msg = self.receive()`) \nmessages which must be processed within the function `self.update`.\nAny responses to sent messages will not happen until the agent runs\nupdate again.\n\nIf any state needs to be stored within the agent, such as for example\nmemory of messages sent or received, then the agents `__init__` should\ndeclare the variables as class variables and store the information.\nCalls to databases, files, etc. can of course happen, including the usage\nof `self.setup()` and `self.teardown()` which are called when the agent\nis, respectively, started or stopped. See the boiler-plate (below) for a more \ndetailed description. \n \n### Boilerplate\n\nThe following boiler-plate allows the user to manage the whole lifecycle\nof an agent, including:\n\n1. add variables to `__init__` which can store information between updates.\n2. react to topics by extending `self.operations`\n2. extend `setup` and `teardown` for start and end of the agents lifecycle.\n4. use `update` with actions before(1), during(2) and after(3) reading messages.\n\nThere are no requirements, for using all functions. The boiler-plate merely\nseeks to illustrate typical usage.\n\nThere are also no requirements for the agent to be programmed in procedural,\nfunctional or object oriented manner. Doing that is completely up to the \nuser of MASlite.\n\n class Example(Agent):\n def __init__(self, db_connection):\n super().__init__()\n # add variables here.\n self._is_setup = False\n self.db_connection = db_connection\n \n # remember to register topics and their functions:\n self.operations.update({\"topic x\": self.x,\n \"topic y\": self.y,\n \"topic ...\": self....})\n \n def update(self):\n assert self._is_setup\n\n # do something before reading messages\n self.action_before_processing_messages()\n \n # read the messages\n while self.messages:\n msg = self.receive()\n \n # react immediately to some messages:\n operation = self.operations.get(msg.topic)\n if operation is not None:\n operation(msg)\n \n # react after reading all messages:\n self.action_after_processing_all_messages()\n \n # Functions added by the user that are not inherited from the \n # `Agent`-class. If the `update` function should react on these,\n # the topic of the message must be in the self.operations dict.\n \n def setup(self):\n self._is_setup = True\n # add own setup operations here.\n self.subscribe(self.__class__.__name__)\n \n def action_before_processing_messages(self)\n # do something.\n \n def action_after_processing_all_messages(self)\n # do something. Perhaps send a message to somebody that update is done?\n msg = DoneMessages(sender=self, receiver=SomeOtherAgent)\n self.send(msg)\n \n def x(msg):\n # read msg and send a response\n from_ = msg.sender\n response = SomeMessage(sender=self, receiver=from_) \n self.send(response)\n \n def y(msg):\n with db_connection as db.:\n db.somefield.update(time.time())\n \n def teardown(self):\n # add own teardown operations here.\n self.db_connection.close()\n \n\n### Messages\n\nMessages are objects and are required to use the base class `AgentMessage`.\n\nWhen agents receive messages they should be interpreted by their topic, which\nshould (by convention) also be the class name of the message. Practice has shown\nthat there are no obvious reasons where this convention shouldn't apply, so \nmessages which don't have a topic declared explicitly inherit the class name. \nAn example is shown below:\n\n >>> from maslite import AgentMessage\n >>> class MyMsg(AgentMessage):\n ... def __init__(self, sender, receiver):\n ... super().__init__(sender=sender, receiver=receiver)\n ...\n \n >>> m = MyMsg(sender=1, receiver=2)\n >>> m.topic\n \n 'MyMsg'\n\nAdding functions to messages. Below is an example of a message with it's own\nfunction(s): \n\n class DatabaseUpdateMessage(AgentMessage):\n \"\"\" Description of the message \"\"\"\n def __init__(self, sender, senders_db_alias):\n super().__init__(sender=sender, receiver=DatabaseAgent.__name__)\n self.senders_db_alias\n self._states = {1: 'new', 2: 'read'} \n self._state = 1\n \n def get_senders_alias(self):\n return self.senders_db_alias\n \n def __next__(self)\n if self._state + 1 <= max(self._states.keys()):\n self._state += 1\n \n def state(self):\n return self._states[self._state]\n\nThe class `DatabaseUpdateMessage` is subclassed from the `AgentMessage` so that \nthe basic message handling properties are available for the DatabaseUpdateMessage. \nThis helps the user as s/he doesn't need to know anything about how the message \nhandling system works.\n\nThe init function requires a sender, which normally defaults to the agent's `self`.\nThe `AgentMessage` knows that if it gets an agent in it's `__init__` call, it will\nobtain the agents UUID and use that. Similar applies to a receiver, where the typical\noperation is based on that the local agent gets a message from the sender and only \nknows the sender based on msg.get_sender() which returns the sending agents UUID. \nIf the sender might change UUID, in the course of multiple runs, the local agent \nshould be instructed to use, for example, the `senders_db_alias`. For the purpose\nof illustration, the message above contains the function `get_senders_alias` which\nthen can be persistent over multiple runs.\n\nThe message is also designed to be returned to save pythons garbage collector:\nWhen the DatabaseAgent receives the message, the `__next__`-function allows the\nagent to call `next(msg)` to progress it's `self._state` from '1' (new) to '2' (read)\nbefore returning it to the sender using 'self.send(msg)'. In such case it is \nimportant that the DatabaseAgent doesn't store the message in its variables, as\nthe message must __not__ have any open object pointers when sent. This is due to\nmultiprocessing which uses `multiprocessing.queue`s for exchanging messages, which\nrequire that `Agent`s and `AgentMessage`s can be pickled.\n\nIf an `Agent` can't be pickled when added to the `Scheduler`, the scheduler will\nraise an error explaining that the are open pointer references. Messages are a \nbit more tolerant as the `mailman` that manages the messages will try to send\nthe message and hope that the shared pointer will not cause conflicts. If sharing\nof object pointers is required by the user (for example during prototyping) the \nscheduler must be set up with `number_of_multiprocessors=0` which forces the \nscheduler to run single-process-single-threaded. \n\n\n__Message Conventions__:\n\n* Messages which have `None` as receiver are considered broadcasts. The logic is \nthat if you don't know who exactly you are sending it to, send it it to `None`, and\nyou might get a response if any other agent react on the topic of the message.\nThe magic behind the scenes is handled by the schedulers mail manager \nwhich keeps track of all topics that any `Agent` subscribes to.\nBy convention the topic of the message should be `self.__class__.__name__`.\n\n* Messages which have a `class.__name__` as receiver, will be received by all agents\nof that class. This is configured when the agent is added to the scheduler in `s.add(agent)` \n\n* Messages which have a particular UUID as receiver, will be received by the agent \nholding that UUID. If anyone other agent is tracking that UUID, by subscribing to\nit, then the tracking agent will receive a `deepcopy` of the message, and not the \noriginal. If the message has a `copy` method, this will be used instead of deepcopy. \n\n* To get the UUID of the sender the method `msg.sender` is available.\n\n* To subscribe/unsubscribe during runtime the agents should use the `subscribe`\nfunction directly.\n\n\n### How to load data from a database connection \n\nWhen agents are added to the scheduler `setup` is run.\nWhen agents are removed from `teardown` is run.\n\nif agents are added and removed iteratively, they should load their \nstate during `setup` and store it during `teardown` from some database. \nIt is not necessary to let the scheduler know where the database is. \nThe agents can keep track of this themselves. \n\nThough the user might find it attractive to use `uuid` to identify, a particular \n`Agent` the user should set the `uuid` in `super().__init__(uuid=\"this\")`, as a the\n`uuid` otherwise will be given be the scheduler.\n\n### Getting started\n\nTo get started only 3 steps are required:\n\nStep 1. setup a scheduler\n\n >>> from maslite import Agent, Scheduler\n >>> s = Scheduler()\n \nStep 2. create agents which have an `update` method and (optionally)\na `setup` and `teardown`.\n\n >>> class MyAgent(Agent):\n ... def __init__(self):\n ... super().__init__()\n ... def setup(self):\n ... pass\n ... def teardown(self):\n ... pass\n ... def update(self):\n ... pass\n \n >>> m = MyAgent()\n >>> s.add(m)\n\nStep 3. run the scheduler (nothing happens here)\n\n >>> s.run(pause_if_idle=True)\n\nOther methods such as `s.run(seconds=None, iterations=None, \npause_if_idle=False)` can be applied as the user finds it suitable.\n\nStep 4. to stop the scheduler there are the following options:\n\n1. Let it run until idle (most common)\n2. Run for N seconds (suitable for real-time systems), \n3. Run for N iterations (suitable for interrupt checking)\n\nThen leave the scheduler (and all the agents) in their set state, for\nexample to read the state of particular agents; and finally \nexecute the `teardown` method, on all agents in a loop:\n\n >>> for uid, agent in s.agents.items():\n ... agent.teardown()\n\n\n### Debugging with pdb or breakpoints (PyCharm)\n\nDebugging is easily performed by putting breakpoint at the beginning of\nthe update function. In that way you can watch what happens inside the \nagent during its state-update.\n\n### Typical mistakes\n\nThe user constructs the agent correctly with:\n \n1. the methods `update`, `send`, `receive`, `setup` and `teardown`,\n2. adding the agent to the scheduler using `scheduler.add(agent)`.\n3. runs the scheduler using `scheduler.run()`, \n\n...but... \n\nQ: The agents don't seem to update?\n\nA: The agents are not getting any messages and are therefore not updated.\nThis is correct behaviour, as `update` only should run when there are\nnew messages! \nTo force agents to run `update` in every scheduling cycle, use the hidden \nmethod: `agent.keep_awake=True`. Doing this blindly however is a poor design\nchoice if the agent merely is polling for data. For this purpose \n`agent.set_alarm_clock(agent.now()+1)` should be used, as this allows the\nagent to sleep for 1 second and the be \"woken up\" by the alarm message.\n\nThe reason it is recommended to use the alarm instead of setting \n`keep_awake=True` is that the workload of the system remains transparent \nat the level of message exchange. Remember that the internal state of \nthe agents should always be hidden whilst the messages should be \nindicative of any activity. \n\n...\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A fast & lightweight multi-agent system kernel",
"version": "2023.1.1",
"project_urls": {
"Homepage": "https://github.com/root-11/maslite"
},
"split_keywords": [
"multi agent system",
"mas",
"maslite"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "23e50f6d620be78e6ae5e4f589351047479cc1dea3320cc06866d69aedf41b7e",
"md5": "f3b22fbf070d94d0e11b6d79109e9c46",
"sha256": "c0e26f84bc5d40cced45da53b1b88d74fcac7ec8b18eb704ab25a1da13bac46c"
},
"downloads": -1,
"filename": "MASlite-2023.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f3b22fbf070d94d0e11b6d79109e9c46",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23259,
"upload_time": "2024-02-12T16:30:18",
"upload_time_iso_8601": "2024-02-12T16:30:18.508858Z",
"url": "https://files.pythonhosted.org/packages/23/e5/0f6d620be78e6ae5e4f589351047479cc1dea3320cc06866d69aedf41b7e/MASlite-2023.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 16:30:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "root-11",
"github_project": "maslite",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "maslite"
}
JSON
