diff --git a/docs/src/Memory Storage.md b/docs/src/Memory Storage.md index 07e407e..972e907 100644 --- a/docs/src/Memory Storage.md +++ b/docs/src/Memory Storage.md @@ -8,7 +8,7 @@ When using Memory Storage, each local CST instance is called a node. Memories wi The collection of synchonized nodes is a mind, and a single Redis instance can support multiple minds with unique names. -To use it, you just need to add a :class:`Memory Storage Codelet` to each mind participating in the network. +To use it, you just need to add a :class:`Memory Storage Codelet` to each mind participating in the network. Check the [Memory Storage Example](https://h-iaac.github.io/CST-Python/_build/html/_examples/Memory%20Storage.html) for how to use it. ## Protocol diff --git a/examples/Memory Storage.ipynb b/examples/Memory Storage.ipynb new file mode 100644 index 0000000..c63698c --- /dev/null +++ b/examples/Memory Storage.ipynb @@ -0,0 +1,310 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Memory Storage\n", + "\n", + "[![Open in Colab](https://img.shields.io/badge/Open%20in%20Colab-F9AB00?style=for-the-badge&logo=googlecolab&color=525252)](https://colab.research.google.com/github/H-IAAC/CST-Python/blob/main/examples/Memory%20Storage.ipynb) [![Open in Github](https://img.shields.io/badge/Open%20in%20Github-100000?style=for-the-badge&logo=github&logoColor=white)](https://github.com/H-IAAC/CST-Python/blob/main/examples/Memory%20Storage.ipynb)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In this example, we gonna use the Memory Storage to synchonize memories across two CST instances." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "First, we need to ensure that `cst_python` and `redis` is installed:" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " import cst_python as cst\n", + " import redis\n", + "except:\n", + " !python3 -m pip install cst_python[memory_storage] " + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We also need to have a running Redis server. If you're running this notebook in Google Colab, the following cell will install and start Redis:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [], + "source": [ + "try:\n", + " import google.colab\n", + " IN_COLAB = True\n", + "except:\n", + " IN_COLAB = False\n", + "\n", + "if IN_COLAB:\n", + " # Install Redis\n", + " !curl -fsSL https://packages.redis.io/redis-stack/redis-stack-server-6.2.6-v7.focal.x86_64.tar.gz -o redis-stack-server.tar.gz \n", + " !tar -xvf redis-stack-server.tar.gz\n", + "\n", + " # Start Redis server\n", + " !./redis-stack-server-6.2.6-v7/bin/redis-stack-server --daemonize yes" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can then import the modules and get started." + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [], + "source": [ + "import time\n", + "\n", + "import cst_python as cst\n", + "from cst_python.memory_storage import MemoryStorageCodelet" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Our example will involve two CST instances, two nodes, with a memory called \"MyMemory\" being synchronized between them. Let's start by creating the instance's mind and its memory:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "firstnode_mind = cst.Mind()\n", + "firstnode_memory = firstnode_mind.create_memory_object(\"MyMemory\", \"\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "To use memory storage, each node needs to have a MemoryStorageCodelet running in its mind. Let's create the codelet, add the mind and start the mind:" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [], + "source": [ + "firstnode_mscodelet = MemoryStorageCodelet(firstnode_mind)\n", + "firstnode_mscodelet.time_step = 100\n", + "firstnode_mind.insert_codelet(firstnode_mscodelet)\n", + "\n", + "firstnode_mind.start()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Let's initialize the memory with an info:" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'First node info'" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "firstnode_memory.set_info(\"First node info\")\n", + "firstnode_memory.get_info()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "And create the mind and memory of the second node. Notice that its memory is not initialized:" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "''" + ] + }, + "execution_count": 7, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "secondnode_mind = cst.Mind()\n", + "secondnode_memory = secondnode_mind.create_memory_object(\"MyMemory\", \"\")\n", + "\n", + "secondnode_memory.get_info()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We then create the MemoryStorage of the second instance and start it:" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [], + "source": [ + "secondnode_mscodelet = MemoryStorageCodelet(secondnode_mind)\n", + "secondnode_mscodelet.time_step = 100\n", + "secondnode_mind.insert_codelet(secondnode_mscodelet)\n", + "\n", + "secondnode_mind.start()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We wait a while to ensure that the codelet will be executed, and we check the data in the second instance:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "time.sleep(1)\n", + "\n", + "secondnode_memory.get_info()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "We can see that the data has been synchronized!\n", + "\n", + "The process works both ways:" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'Second node info'" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "secondnode_memory.set_info(\"Second node info\")\n", + "time.sleep(1)\n", + "firstnode_memory.get_info()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "And it can contain data of a few different types:" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "[1, 2, 3]" + ] + }, + "execution_count": 12, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "firstnode_memory.set_info([1, 2, 3])\n", + "time.sleep(1)\n", + "secondnode_memory.get_info()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "In this example, we used two CST-Python instances in the same machine. But, it could be a CST-Python with a CST-Java instance, or instances in different machines, or even more than two instances.\n", + "\n", + "The [Memory Storage Documentation](https://h-iaac.github.io/CST-Python/_build/html/src/Memory%20Storage.html) contains more information about how the Memory Storage works." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.9" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/examples/README.md b/examples/README.md index 621060e..2da43a4 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,4 +6,5 @@ Here we have some examples of how to use the CST-Python: - [Implementing a Architecture](https://h-iaac.github.io/CST-Python/_build/html/_examples/Implementing%20a%20Architecture.html): how to implement a cognitive architecture using CST-Python. - [Publisher-Subscriber](https://h-iaac.github.io/CST-Python/_build/html/_examples/Publisher-Subscriber.html): using the publisher-subscriber mechanism for synchronous codelets. - [Activation and Monitoring](https://h-iaac.github.io/CST-Python/_build/html/_examples/Activation%20and%20Monitoring.html): using codelet's activation value and monitoring the agent. +- [Memory Storage](https://h-iaac.github.io/CST-Python/_build/html/_examples/Memory%20Storage.html): how to use the CST synchronization mechanism to use multiple instances on the same agent. - [Gymnasium Integration](https://h-iaac.github.io/CST-Python/_build/html/_examples/Gymnasium%20Integration.html): using gymnasium environments with CST. \ No newline at end of file