unaiverse 0.1.0__py3-none-any.whl

unaiverse/networking/node/node.py

@@ -0,0 +1,2203 @@
+"""
+       █████  █████ ██████   █████           █████ █████   █████ ██████████ ███████████    █████████  ██████████
+      ░░███  ░░███ ░░██████ ░░███           ░░███ ░░███   ░░███ ░░███░░░░░█░░███░░░░░███  ███░░░░░███░░███░░░░░█
+       ░███   ░███  ░███░███ ░███   ██████   ░███  ░███    ░███  ░███  █ ░  ░███    ░███ ░███    ░░░  ░███  █ ░ 
+       ░███   ░███  ░███░░███░███  ░░░░░███  ░███  ░███    ░███  ░██████    ░██████████  ░░█████████  ░██████   
+       ░███   ░███  ░███ ░░██████   ███████  ░███  ░░███   ███   ░███░░█    ░███░░░░░███  ░░░░░░░░███ ░███░░█   
+       ░███   ░███  ░███  ░░█████  ███░░███  ░███   ░░░█████░    ░███ ░   █ ░███    ░███  ███    ░███ ░███ ░   █
+       ░░████████   █████  ░░█████░░████████ █████    ░░███      ██████████ █████   █████░░█████████  ██████████
+        ░░░░░░░░   ░░░░░    ░░░░░  ░░░░░░░░ ░░░░░      ░░░      ░░░░░░░░░░ ░░░░░   ░░░░░  ░░░░░░░░░  ░░░░░░░░░░ 
+                 A Collectionless AI Project (https://collectionless.ai)
+                 Registration/Login: https://unaiverse.io
+                 Code Repositories:  https://github.com/collectionlessai/
+                 Main Developers:    Stefano Melacci (Project Leader), Christian Di Maio, Tommaso Guidi
+"""
+import os
+import sys
+import ast
+import cv2
+import copy
+import json
+import math
+import time
+import html
+import queue
+import types
+import requests
+import threading
+import traceback
+from PIL import Image
+from typing import Optional
+from collections import deque
+from unaiverse.clock import Clock
+from unaiverse.world import World
+from unaiverse.agent import Agent
+from unaiverse.networking.p2p import P2P
+from unaiverse.networking.p2p.messages import Msg
+from datetime import datetime, timezone, timedelta
+from unaiverse.networking.node.connpool import NodeConn
+from unaiverse.networking.node.profile import NodeProfile
+from unaiverse.streams import DataProps, BufferedDataStream
+from unaiverse.utils.misc import GenException, get_key_considering_multiple_sources, save_node_addresses_to_file
+
+
+class Node:
+
+    # Each node can host an agent or a world
+    AGENT = "agent"
+    WORLD = "world"
+
+    # Each node outputs console text with a different color
+    TEXT_COLORS = ('\033[91m', '\033[94m', '\033[92m', '\033[93m')
+    TEXT_LAST_USED_COLOR = 0
+    TEXT_LOCK = threading.Lock()
+
+    def __init__(self,
+                 hosted: Agent | World,
+                 unaiverse_key: str | None = None,
+                 node_name: str | None = None,
+                 node_id: str | None = None,
+                 hidden: bool = False,
+                 clock_delta: float = 1. / 25.,
+                 only_certified_agents: bool = False,
+                 allowed_node_ids: list[str] | set[str] = None,  # Optional: it is loaded from the online profile
+                 world_masters_node_ids: list[str] | set[str] = None,  # Optional: it is loaded from the online profile
+                 world_masters_node_names: list[str] | set[str] = None,  # Optional: it will be converted to node IDs
+                 allow_connection_through_relay: bool = True,
+                 talk_to_relay_based_nodes: bool = True):
+        """Initializes a new instance of the Node class.
+
+        Args:
+            hosted: The Agent or World entity hosted by this node.
+            unaiverse_key: The UNaIVERSE key for authentication (if None, it will be loaded from env var or cache file,
+                or you will be asked for it).
+            node_name: A human-readable name for the node (using node ID is preferable; use this or node ID, not both).
+            node_id: A unique identifier for the node (use this or the node name, not both).
+            hidden: A flag to determine if the node is hidden (i.e., only the owner of the account can see it).
+            clock_delta: The minimum time delta for the node's clock.
+            only_certified_agents: A flag to allow only certified agents to connect.
+            allowed_node_ids: A list or set of allowed node IDs to connect (t is loaded from the online profile).
+            world_masters_node_ids: A list or set of world masters' node IDs (it is also loaded from online profile).
+            world_masters_node_names: A list or set of world masters' node names (using IDs is preferable).
+            allow_connection_through_relay: A flag to allow connections through a relay.
+            talk_to_relay_based_nodes: A flag to allow talking to relay-based nodes.
+        """
+
+        # Checking main arguments
+        if not (isinstance(hosted, Agent) or isinstance(hosted, World)):
+            raise GenException("Invalid hosted entity, must be Agent or World")
+        if not (node_id is None or isinstance(node_id, str)):
+            raise GenException("Invalid node ID")
+        if not (node_name is None or isinstance(node_name, str)):
+            raise GenException("Invalid node name")
+        if not (node_name is None or node_id is None):
+            raise GenException("Cannot specify both node ID and node name")
+        if not (node_name is not None or node_id is not None):
+            raise GenException("You must specify either node ID or node name: both are missing")
+        if not (unaiverse_key is None or isinstance(unaiverse_key, str)):
+            raise GenException("Invalid UNaIVERSE key")
+
+        # Main attributes
+        self.node_id = node_id
+        self.unaiverse_key = unaiverse_key
+        self.hosted = hosted
+        self.node_type = Node.AGENT if (isinstance(hosted, Agent) and not isinstance(hosted, World)) else Node.WORLD
+        self.agent = hosted if self.node_type is Node.AGENT else None
+        self.world = hosted if self.node_type is Node.WORLD else None
+        self.clock = Clock(min_delta=clock_delta)  # Node clock
+        self.conn = None  # Manages the network operations in the P2P network
+        self.talk_to_relay_based_nodes = talk_to_relay_based_nodes
+
+        # Expected properties of the nodes that will try to connect to this one
+        self.only_certified_agents = only_certified_agents
+        self.allowed_node_ids = set(allowed_node_ids) if allowed_node_ids is not None else None
+        self.world_masters_node_ids = set(world_masters_node_ids) if world_masters_node_ids is not None else None
+
+        # Profile
+        self.profile = None
+        self.send_dynamic_profile_every = 10. if self.node_type is Node.WORLD else 10.  # Seconds
+        self.get_new_token_every = 23 * 60. * 60. + 30 * 60.  # Seconds (23 hours and 30 minutes, safer)
+
+        # Rendezvous
+        self.publish_rendezvous_every = 10.
+        self.last_rendezvous_time = 0.
+
+        # Automatic address update and relay refresh (if needed)
+        self.relay_reservation_expiry: Optional[datetime] = None
+        self.address_check_every = 5 * 60.  # Check every 5 minutes
+
+        # Interview of newly connected nodes
+        self.interview_timeout = 45.  # Seconds
+        self.connect_without_ack_timeout = 45.  # Seconds
+        
+        # Alive messaging
+        self.send_alive_every = 2.5 * 60.  # Seconds
+        self.last_alive_time = 0.
+        self.skip_was_alive_check = os.getenv("NODE_IGNORE_ALIVE", "0") == "1"
+
+        # Root server-related
+        self.root_endpoint = 'https://unaiverse.io/api'  # WARNING: EDITING THIS ADDRESS VIOLATES THE LICENSE
+        self.node_token = ""
+        self.public_key = ""
+
+        # Output console text
+        print_level = int(os.getenv("NODE_PRINT", "0"))  # 0, 1, 2
+        self.print_enabled = print_level > 0
+        self.cursor_hidden = False
+        NodeSynchronizer.DEBUG = print_level > 1
+        NodeConn.DEBUG = print_level > 1
+        if print_level == 0:
+            self.cursor_hidden = True
+        with Node.TEXT_LOCK:
+            self.text_color = Node.TEXT_COLORS[Node.TEXT_LAST_USED_COLOR]
+            Node.TEXT_LAST_USED_COLOR = (Node.TEXT_LAST_USED_COLOR + 1) % len(Node.TEXT_COLORS)
+
+        # Print-related logging (for inspector only)
+        self._output_messages = [""] * 20
+        self._output_messages_ids = [-1] * 20
+        self._output_messages_count = 0
+        self._output_messages_last_pos = -1
+
+        # Attributes: handshake-related
+        self.agents_to_interview: dict[str, [float, NodeProfile | None]] = {}  # Peer_id -> [time, profile | None]
+        self.agents_expected_to_send_ack = {}
+        self.last_rejected_agents = deque(maxlen=self.conn)
+        self.joining_world_info = None
+        self.first = True
+
+        # Inspector related
+        self.inspector_activated = False
+        self.inspector_peer_id = None
+        self.debug_server_running = False
+        self.__inspector_cache = {"behav": None, "known_streams_count": 0, "all_agents_count": 0}
+        self.__inspector_told_to_pause = False
+
+        # Get key
+        self.unaiverse_key = get_key_considering_multiple_sources(self.unaiverse_key)
+
+        # Getting node ID (retrieving by name), if it was not provided (the node is created if not existing)
+        if self.node_id is None:
+            node_ids, were_alive = self.get_node_id_by_name([node_name],
+                                                            create_if_missing=True)
+            self.node_id = node_ids[0]
+            if were_alive[0]:
+                raise GenException(f"Cannot access node {node_name}, it is already running! "
+                                   f"(set env variable NODE_IGNORE_ALIVE=1 to ignore this control)")
+
+        # Getting node ID of world masters, if needed
+        if world_masters_node_names is not None and len(world_masters_node_names) > 0:
+            master_node_ids, were_alive = self.get_node_id_by_name(world_masters_node_names,
+                                                                   create_if_missing=True, node_type=Node.AGENT)
+            for master_node_name, master_node_id in zip(world_masters_node_names, master_node_ids):
+                if master_node_id is None:
+                    raise GenException(f"Cannot find world master node ID given its name: {master_node_name}")
+                else:
+                    if self.world_masters_node_ids is None:
+                        self.world_masters_node_ids = set()
+                    self.world_masters_node_ids.add(master_node_id)
+
+        # Here you can setup max_instances, max_channels, enable_logging at libp2p level etc.
+        P2P.setup_library(enable_logging=os.getenv("NODE_LIBP2PLOG", "0") == "1")
+
+        offer_relay_facilities = self.node_type is Node.WORLD  # Only world nodes offer relay facilities
+
+        # Create P2P node in the whole universe (it has fields 'addresses', and 'peer_id', and 'libp2p')
+        p2p_u = P2P(max_connections=1000,
+                    ips=None,
+                    enable_relay_service=offer_relay_facilities,
+                    enable_relay_client=allow_connection_through_relay,
+                    wait_public_reachability=os.getenv("NODE_WAIT_PUBLIC", "1") == "1",
+                    port=int(os.getenv("NODE_STARTING_PORT", "0")))
+
+        # Create another P2P node for the private world (it has fields 'addresses', and 'peer_id', and 'libp2p')
+        p2p_w = P2P(max_connections=1000,
+                    ips=None,
+                    enable_relay_service=offer_relay_facilities,
+                    enable_relay_client=allow_connection_through_relay,
+                    wait_public_reachability=os.getenv("NODE_WAIT_PUBLIC", "1") == "1",
+                    port=(int(os.getenv("NODE_STARTING_PORT", "0")) + 3)
+                    if int(os.getenv("NODE_STARTING_PORT", "0")) > 0 else 0)
+
+        # Get first node token
+        self.get_node_token(peer_ids=[p2p_u.peer_id, p2p_w.peer_id])  # Passing both the peer IDs
+
+        # Get first badge token
+        if self.node_type is Node.WORLD:
+            self.badge_token = self.__root(api="account/node/cv/badge/token/get", payload={"node_id": self.node_id})
+        else:
+            self.badge_token = None
+
+        # Get profile (static)
+        profile_static = self.__root(api="/account/node/profile/static/get", payload={"node_id": self.node_id})
+
+        # Getting list of allowed nodes from the static profile,
+        # if we did not already specify it when creating the node in the code (the code has higher priority)
+        if (self.allowed_node_ids is None and 'allowed_node_ids' in profile_static and
+                profile_static['allowed_node_ids'] is not None and len(profile_static['allowed_node_ids']) > 0):
+            self.allowed_node_ids = set(profile_static['allowed_node_ids'])
+
+        # Getting list of world master nodes from the static profile,
+        # if we did not already specify it when creating the node in the code (the code has higher priority)
+        if self.node_type is Node.WORLD:
+            if (self.world_masters_node_ids is None and 'world_masters_node_ids' in profile_static and
+                    profile_static['world_masters_node_ids'] is not None
+                    and len(profile_static['world_masters_node_ids']) > 0):
+                self.world_masters_node_ids = set(profile_static['world_masters_node_ids'])
+        else:
+            self.world_masters_node_ids = None  # Clearing this in case the user specified it for a non-world node
+
+        # Creating the connection manager
+        # guessing max number of connections (max number of valid
+        # the connection manager will ensure that this limit is fulfilled)
+        # however, the actual number of connection attempts handled by libp2p must be higher that
+        self.conn = NodeConn(max_connections=profile_static['max_nr_connections'],
+                             p2p_u=p2p_u,
+                             p2p_w=p2p_w,
+                             is_world_node=self.node_type is Node.WORLD,
+                             public_key=self.public_key,
+                             token=self.node_token)
+
+        # Get CV
+        cv = self.get_cv()
+
+        # Creating full node profile putting together static info, dynamic profile, adding P2P node info, CV
+        self.profile = NodeProfile(static=profile_static,
+                                   dynamic={'peer_id': p2p_u.peer_id,
+                                            'peer_addresses': p2p_u.addresses,
+                                            'private_peer_id': p2p_w.peer_id,
+                                            'private_peer_addresses': p2p_w.addresses,
+                                            'connections': {
+                                                'role': self.hosted.ROLE_BITS_TO_STR[self.hosted.ROLE_PUBLIC]
+                                            },
+                                            'world_summary': {
+                                                'world_name':
+                                                    profile_static['node_name']
+                                                    if self.node_type is Node.WORLD else None
+                                            },
+                                            "world_roles_fsm": None,  # This will be filled later if this is a world
+                                            "hidden": hidden  # Marking the node as hidden (or not)
+                                            },
+                                   cv=cv)  # Adding CV here
+
+        # Sharing node-level info with the hosted entity
+        self.hosted.set_node_info(self.clock, self.conn, self.profile, self.out, self.ask_to_get_in_touch,
+                                  self.__purge, self.agents_expected_to_send_ack, print_level)
+
+        # Finally, sending dynamic profile to the root server
+        # (send AFTER set_node_info, not before, since set_node_info updates the profile,
+        # adding world roles and state machines)
+        self.send_dynamic_profile()
+
+        # Save public addresses
+        path_to_append_addresses = os.getenv("NODE_SAVE_RUNNING_ADDRESSES")
+        if path_to_append_addresses is not None and os.path.exists(path_to_append_addresses):
+            save_node_addresses_to_file(self, public=True, dir_path=path_to_append_addresses,
+                                        filename="running.csv", append=True)
+
+        # Update lone-wolf machines to replace default wildcards (like <agent>) - the private one will be handled when
+        # joining a world
+        if self.node_type is Node.AGENT:
+            self.agent.behav_lone_wolf.update_wildcard("<agent>", f"{self.get_public_peer_id()}")
+
+    def out(self, msg: str):
+        """Prints a formatted message to the console if printing is enabled.
+
+        Args:
+            msg: The message to be printed.
+        """
+        if self.print_enabled:
+            s = (f"{self.node_type[0:2]}: " +
+                 ((self.hosted.get_name())[0:6] + ",").ljust(7) +
+                 f" cy: {self.clock.get_cycle()}")
+            s = f"[{s}] {msg}"
+            print(f"{self.text_color}{s}\033[0m")
+
+        if self.inspector_activated or self.debug_server_running:
+            last_id = self._output_messages_ids[self._output_messages_last_pos]
+            self._output_messages_last_pos = (self._output_messages_last_pos + 1) % len(self._output_messages)
+            self._output_messages_count = min(self._output_messages_count + 1, len(self._output_messages))
+            self._output_messages_ids[self._output_messages_last_pos] = last_id + 1
+            self._output_messages[self._output_messages_last_pos] = html.escape(str(msg), quote=True)
+
+    def err(self, msg: str):
+        """Prints a formatted error message to the console.
+
+        Args:
+            msg: The error message to be printed.
+        """
+        if self.print_enabled:
+            self.out("<ERROR> " + msg)
+        else:
+            print("<ERROR> " + msg)
+
+    def get_node_id_by_name(self, node_names: list[str], create_if_missing: bool = False,
+                            node_type: str | None = None) -> tuple[list[str], list[bool]]:
+        """Retrieves the node ID by its name from the root server, creating a new node if it's missing and specified.
+
+        Args:
+            node_names: The list with the names of the nodes to retrieve.
+            create_if_missing: A flag to create the node if it doesn't exist (only valid for your own nodes).
+            node_type: The type of the node to create if missing (when create_if_missing is True) - default: the type of
+                the current node.
+
+        Returns:
+            The list of node IDs and the list of boolean flags telling if a node was already alive,
+            or an exception if an error occurs.
+        """
+        try:
+            response = self.__root("/account/node/get/id",
+                                   payload={"node_name": node_names,
+                                            "account_token": self.unaiverse_key})
+            node_ids = []
+            were_alive = []
+            missing = []
+            for i in range(0, len(response["nodes"])):
+                if response["nodes"][i] is not None:
+                    node_ids.append(response["nodes"][i]["node_id"])
+                    were_alive.append(response["nodes"][i]["was_alive"])
+                else:
+                    node_ids.append(None)
+                    were_alive.append(None)
+                missing.append(i)
+        except Exception as e:
+            raise GenException(f"Error while retrieving nodes named {node_names} from server! [{e}]")
+
+        if create_if_missing:
+            for i in missing:
+                node_name = node_names[i]
+                if "/" in node_name or "@" in node_name:  # Cannot create nodes belonging to others
+                    continue
+                try:
+                    response = self.__root("/account/node/fast_register",
+                                           payload={"node_name": node_name,
+                                                    "node_type": self.node_type if node_type is None else node_type,
+                                                    "account_token": self.unaiverse_key})
+                    node_ids[i] = response["node_id"]
+                    were_alive[i] = False
+                except Exception as e:
+                    raise GenException(f"Error while registering node named {node_name} in server! [{e}]")
+        return node_ids, were_alive
+
+    def send_alive(self) -> bool:
+        """Send an alive message to the root server.
+
+        Returns:
+            A boolean flag indicating whether the node was already live before sending this.
+        """
+        try:
+            response = self.__root("/account/node/alive",
+                                   payload={"node_id": self.node_id,
+                                            "account_token": self.unaiverse_key})
+            return response["was_alive"]
+        except Exception as e:
+            self.err(f"Error while sending alive message to server! [{e}]")
+
+    def get_node_token(self, peer_ids):
+        """Generates and retrieves a node token from the root server.
+
+        Args:
+            peer_ids: A list of public and private peer IDs.
+        """
+        response = None
+
+        for i in range(0, 3):  # It will try 3 times before raising the exception...
+            try:
+                response = self.__root("/account/node/token/generate",
+                                       payload={"node_id": self.node_id,
+                                                "account_token": self.unaiverse_key
+                                                if self.node_token is None or len(self.node_token) == 0 else None,
+                                                "node_token": self.node_token, "peer_ids": json.dumps(peer_ids)})
+                break
+            except Exception as e:
+                if i < 2:
+                    self.err(f"Error while getting token from server, retrying...")
+                    time.sleep(1)  # Wait a little bit
+                else:
+                    raise GenException(f"Error while getting token from server [{e}]")  # Raise the exception
+
+        self.node_token = response["token"]
+        self.public_key = response["public_key"]
+
+        # Sharing the token with the connection manager
+        if self.conn is not None:
+            self.conn.set_token(self.node_token)
+
+    def get_cv(self):
+        """Retrieves the node's CV (Curriculum Vitae) from the root server
+
+        Returns:
+            The node's CV as a dictionary.
+        """
+        for i in range(0, 3):  # It will try 3 times before raising the exception...
+            try:
+                return self.__root(api="/account/node/cv/get", payload={"node_id": self.node_id})
+            except Exception as e:
+                self.err(f"Error while getting CV from server [{e}]")
+                if i < 2:
+                    self.out("Retrying...")
+                    time.sleep(1)  # Wait a little bit
+                else:
+                    raise GenException(f"Error while getting CV from server [{e}]")
+
+    def send_dynamic_profile(self):
+        """Sends the node's dynamic profile to the root server."""
+        try:
+            self.__root(api="/account/node/profile/dynamic/post", payload={"node_id": self.node_id,
+                                                                           "profile":
+                                                                               self.profile.get_dynamic_profile()})
+        except Exception as e:
+            self.err(f"Error while sending dynamic profile to from server [{e}]")
+            raise GenException(f"Error while sending dynamic profile to from server [{e}]")
+
+    def send_badges(self):
+        """Sends new badges assigned by a world node to the root server and notifies the agents."""
+        if self.node_type is Node.WORLD:
+            peer_id_to_badges = self.world.get_all_badges()
+            if len(peer_id_to_badges) > 0:
+                self.out(f"Sending {len(peer_id_to_badges)} badges to root server")
+                for i in range(0, 3):  # It will try 3 times before raising the exception...
+                    try:
+                        badges = [badge for _badges in peer_id_to_badges.values() for badge in _badges]
+                        peer_ids = [peer_id for peer_id, _badges in peer_id_to_badges.items() for _ in _badges]
+
+                        response = self.__root(api="/account/node/cv/badge/assign",
+                                               payload={"badges": badges,
+                                                        "world_node_id": self.node_id,
+                                                        "world_badge_token": self.badge_token})
+
+                        # Getting the next badge token
+                        self.badge_token = response["badge_token"]
+                        badges_states = response["badges_states"]  # List of booleans
+
+                        # Check if posting went well and saving the set of peer IDs to contact
+                        peer_ids_to_notify = set()
+                        for z in range(0, len(badges_states)):
+                            ret = badges_states[z]
+                            if 'state' not in ret or 'code' not in ret['state'] or 'message' not in ret['state']:
+                                self.err(f"Error while posting a badge assigned to {peer_ids[z]}. Badge: {badges[z]}. "
+                                         f"Error message: invalid response format")
+                            else:
+                                if ret['state']['code'] != "ok":
+                                    self.err(f"Error while posting a badge assigned to {peer_ids[z]}. "
+                                             f"Badge: {badges[z]}. "
+                                             f"Error message: {ret['state']['message']}")
+                                else:
+                                    peer_ids_to_notify.add(peer_ids[z])
+
+                        # Notify agents
+                        for peer_id in peer_ids_to_notify:
+                            if not self.conn.send(peer_id, channel_trail=None, content=None,
+                                                  content_type=Msg.GET_CV_FROM_ROOT):
+                                self.err(f"Error while sending the request to re-download CV to peer {peer_id}")
+
+                        # Clearing
+                        self.world.clear_badges()
+                        break
+                    except Exception as e:
+                        self.err(f"Error while sending badges to server or when notifying peers [{e}]")
+                        if i < 2:
+                            self.out("Retrying...")
+                            time.sleep(1)  # Wait a little bit
+                        else:
+                            self.err(f"Couldn't complete badge sending or notification procedure (stop trying)")
+
+    def get_public_addresses(self) -> list[str]:
+        """Returns the public addresses of the P2P node
+
+        Returns:
+            The list of public addresses.
+        """
+        return self.conn[NodeConn.P2P_PUBLIC].addresses
+
+    def get_world_addresses(self) -> list[str]:
+        """Returns the world addresses of the P2P node
+
+        Returns:
+            The list of world addresses.
+        """
+        return self.conn[NodeConn.P2P_WORLD].addresses
+
+    def get_public_peer_id(self) -> str:
+        """Returns the public peer ID of the P2P node
+
+        Returns:
+            The public peer ID.
+        """
+        return self.conn[NodeConn.P2P_PUBLIC].peer_id
+
+    def get_world_peer_id(self) -> str:
+        """Returns the world peer ID of the P2P node
+
+        Returns:
+            The world peer ID.
+        """
+        return self.conn[NodeConn.P2P_WORLD].peer_id
+
+    def ask_to_get_in_touch(self, node_name: str | None = None, addresses: list[str] | None = None, public: bool = True,
+                            before_updating_pools_fcn=None, run_count: int = 0):
+        """Tries to connect to another agent or world node.
+
+        Args:
+            node_name: Name of the node to join (alternative to addresses below)
+            addresses: A list of network addresses to connect to (alternative to node_name).
+            public: A boolean flag indicating whether to use the public or world P2P network.
+            before_updating_pools_fcn: A function to call before updating the connection pools.
+            run_count: The number of connection attempts made.
+
+        Returns:
+            The peer ID of the connected node if successful, otherwise None.
+        """
+
+        # Checking arguments
+        if (node_name is None and addresses is None) or (node_name is not None and addresses is not None):
+            raise GenException("Cannot specify both node_name and addresses or none of them, check your code!")
+
+        # Getting addresses, if needed
+        if addresses is None:
+            addresses = self.__root(api="account/node/get/addresses",
+                                    payload={"node_name": node_name, "account_token": self.unaiverse_key})["addresses"]
+
+        # Connecting
+        self.out("Connecting to another agent/world...")
+        peer_id, through_relay = self.conn.connect(addresses,
+                                                   p2p_name=NodeConn.P2P_PUBLIC if public else NodeConn.P2P_WORLD)
+
+        if through_relay:
+            print("Warning: this connection goes through a relay-based circuit, "
+                  "so a third-party node is involved in the communication")
+
+        if peer_id is not None and (not through_relay or self.talk_to_relay_based_nodes):
+
+            # Ping to test the readiness of the established connection
+            self.out(f"Connected, ping-pong...")
+            if not self.conn.send(peer_id, channel_trail=None, content_type=Msg.MISC, content={"ping": "pong"},
+                                  p2p=self.conn.p2p_name_to_p2p[NodeConn.P2P_PUBLIC if public else NodeConn.P2P_WORLD]):
+                if run_count < 2:
+                    return self.ask_to_get_in_touch(addresses=addresses, public=public,
+                                                    before_updating_pools_fcn=before_updating_pools_fcn,
+                                                    run_count=run_count+1)
+                else:
+                    self.err("Connection failed! (ping-pong max trials exceeded)")
+                    return None
+
+            self.out("Connected, updating pools...")
+            if before_updating_pools_fcn is not None:
+                before_updating_pools_fcn(peer_id)
+            self.conn.update()
+
+            self.agents_expected_to_send_ack[peer_id] = self.clock.get_time()
+            self.out(f"Current set of {len(self.agents_expected_to_send_ack)} connected peer IDs that will get our "
+                     f"profile and are expected to send a confirmation: "
+                     f"{self.agents_expected_to_send_ack.keys()}")
+            return peer_id
+        else:
+            self.err("Connection failed!")
+            return None
+
+    def ask_to_join_world(self, node_name: str | None = None, addresses: list[str] | None = None, **kwargs):
+        """Initiates a request to join a world.
+
+        Args:
+            node_name: The name of the node hosting the world to join (alternative to addresses below).
+            addresses: A list of network addresses of the world node (alternative to world_name).
+            **kwargs: Additional options for joining the world.
+
+        Returns:
+            The public peer ID of the world node if the connection request is successful, otherwise None.
+        """
+        print("Asking to join world...")
+
+        # Leave an already entered world (if any)
+        world_peer_id = self.profile.get_dynamic_profile()['connections']['world_peer_id']
+        if world_peer_id is not None:
+            self.leave(world_peer_id)
+
+        # Connecting to the world (public)
+        peer_id = self.ask_to_get_in_touch(node_name=node_name, addresses=addresses, public=True)
+
+        # Saving info
+        if peer_id is not None:
+            print("Connected on the public network, waiting for handshake...")
+            self.joining_world_info = {"world_public_peer_id": peer_id, "options": kwargs}
+        else:
+            print("Failed to join world!")
+        return peer_id
+
+    def leave(self, peer_id: str):
+        """Disconnects the node from a specific peer, typically a world.
+
+        Args:
+            peer_id: The peer ID of the node to leave.
+        """
+
+        if not isinstance(peer_id, str):
+            self.err(f"Invalid argument provided to leave(...): {peer_id}")
+            return
+
+        print(f"Leaving {peer_id}...")
+
+        dynamic_profile = self.profile.get_dynamic_profile()
+
+        if peer_id == dynamic_profile['connections']['world_peer_id']:
+            print("Leaving world...")
+
+            # Clearing world-related lists in the connection manager (to avoid world agent to connect again)
+            self.conn.set_world(None)
+            self.conn.set_world_agents_list(None)
+            self.conn.set_world_masters_list(None)
+
+            # Disconnecting all connected world-related agents, including world node (it clears roles too)
+            self.conn.remove_all_world_agents()
+
+            # Better clear this as well
+            if peer_id in self.agents_expected_to_send_ack:
+                del self.agents_expected_to_send_ack[peer_id]
+
+            # Clear profile
+            dynamic_profile['connections']['world_peer_id'] = None
+            dynamic_profile['connections']['world_agents'] = None
+            dynamic_profile['connections']['world_masters'] = None
+            self.profile.mark_change_in_connections()
+
+            # Clearing agent-level info
+            self.agent.clear_world_related_data()
+
+            # Clearing all joining options
+            self.joining_world_info = None
+        else:
+            if peer_id in self.hosted.all_agents:
+                self.hosted.remove_agent(peer_id)
+            self.conn.remove(peer_id)
+
+    def leave_world(self):
+        """Initiates the process of leaving a world.
+
+        Returns:
+            None.
+        """
+        if self.profile.get_dynamic_profile()['connections']['world_peer_id'] is not None:
+            self.agent.accept_new_role(self.agent.ROLE_PUBLIC)
+            self.agent.world_profile = None
+            self.leave(self.profile.get_dynamic_profile()['connections']['world_peer_id'])
+
+    def run(self, cycles: int | None = None, max_time: float | None = None, interact_mode_opts: dict | None = None):
+        """Starts the main execution loop for the node.
+
+        Args:
+            cycles: The number of clock cycles to run the loop for. If None, runs indefinitely.
+            max_time: The maximum time in seconds to run the loop. If None, runs indefinitely.
+            interact_mode_opts: A dictionary of options to enable interactive mode.
+        """
+        try:
+            if self.cursor_hidden:
+                sys.stdout.write("\033[?25l")  # Hide cursor
+
+            last_dynamic_profile_time = self.clock.get_time()
+            last_get_token_time = self.clock.get_time()
+            last_address_check_time = self.clock.get_time()
+            if not (cycles is None or cycles > 0):
+                raise GenException("Invalid number of cycles")
+
+            # Interactive mode (useful when chatting with lone wolves)
+            keyboard_queue = None
+            keyboard_listener = None
+            processor_net_hash = None
+            processor_img_stream = None
+            processor_text_stream = None
+            cap = None
+            ready_to_interact = False
+
+            if interact_mode_opts is not None:
+                if self.agent is None:
+                    raise GenException("Interactive mode is only valid for agents")
+
+                processor_text_net_hash = None
+                processor_img_net_hash = None
+                looking_for_public_streams = "lone_wolf_peer_id" in interact_mode_opts
+                for net_hash, stream_dict in self.agent.proc_streams.items():
+                    for stream in stream_dict.values():
+                        if (processor_text_stream is None and stream.props.is_public() == looking_for_public_streams
+                                and stream.props.is_text()):
+                            processor_text_stream = stream
+                            processor_text_net_hash = net_hash
+                        if (processor_img_stream is None and stream.props.is_public() == looking_for_public_streams
+                                and stream.props.is_img()):
+                            processor_img_stream = stream
+                            processor_img_net_hash = net_hash
+
+                if processor_text_net_hash is None:
+                    raise GenException("Interactive mode requires a processor that generates a text stream")
+                if not (processor_img_net_hash is None or (processor_text_net_hash == processor_img_net_hash)):
+                    raise GenException("Interactive mode requires the same processor to generate text and img streams")
+                processor_net_hash = processor_text_net_hash
+
+                def keyboard_listener(k_queue):
+                    while True:
+                        webcam_shot = None
+                        keyboard_msg = input()  # Get from keyboards
+                        if cap is not None:
+                            ret, got_shot = cap.read()  # Get from webcam
+                            if ret:
+                                target_area = 224 * 224
+                                webcam_shot = Image.fromarray(cv2.cvtColor(got_shot, cv2.COLOR_BGR2RGB))
+                                width, height = webcam_shot.size
+                                current_area = width * height
+
+                                if current_area > target_area:
+                                    scale_factor = math.sqrt(target_area / current_area)
+                                    new_width = int(round(width * scale_factor))
+                                    new_height = int(round(height * scale_factor))
+                                    webcam_shot = webcam_shot.resize((new_width, new_height),
+                                                                     Image.Resampling.LANCZOS)
+
+                        if keyboard_msg is not None and len(keyboard_msg) > 0:
+                            k_queue.put((keyboard_msg, webcam_shot))  # Store in the asynch queue
+
+                        if keyboard_msg.strip() == "exit" or keyboard_msg.strip() == "quit":
+                            break
+
+                        if not self.agent.in_world():  # If the world disconnected
+                            break
+
+                keyboard_queue = queue.Queue()  # Create a thread-safe queue for communication
+                keyboard_listener = threading.Thread(target=keyboard_listener, args=(keyboard_queue,), daemon=True)
+
+            if self.clock.get_cycle() == -1:
+                print("Running " + ("agent node" if self.agent else "world node") + " " +
+                      f"(public: {self.get_public_peer_id()}, private: {self.get_world_peer_id()})...")
+
+            # Main loop
+            must_quit = False
+            while not must_quit:
+
+                # Check inspector
+                if self.inspector_activated:
+                    if self.__inspector_told_to_pause:
+                        print("Paused by the inspector, waiting...")
+
+                        while self.__inspector_told_to_pause:
+                            if not self.inspector_activated:  # Disconnected
+                                self.__inspector_told_to_pause = False
+                                print("Inspector is not active/connected anymore, resuming...")
+                                break
+
+                            public_messages = self.conn.get_messages(p2p_name=NodeConn.P2P_PUBLIC)
+                            for msg in public_messages:
+                                if msg.content_type == Msg.INSPECT_CMD:
+
+                                    # Unpacking piggyback
+                                    sender_node_id, sender_inspector_mode_on = (msg.piggyback[0:-1],
+                                                                                msg.piggyback[-1] == "1")
+
+                                    # Is message from inspector?
+                                    sender_is_inspector = (sender_node_id == self.profile.get_static_profile()[
+                                        'inspector_node_id'] and
+                                                           sender_inspector_mode_on)
+
+                                    if sender_is_inspector:
+                                        self.__handle_inspector_command(msg.content['cmd'], msg.content['arg'])
+                                    else:
+                                        self.err("Inspector command was not sent by the expected inspector node ID "
+                                                 "or no inspector connected")
+                                        self.__purge(msg.sender)
+                            time.sleep(0.1)
+
+                # Move to the next cycle
+                while not self.clock.next_cycle():
+                    time.sleep(0.001)  # Seconds (lowest possible granularity level)
+
+                self.out(f">>> Starting clock cycle {self.clock.get_cycle()} <<<")
+
+                # Handle new connections or lost connections
+                self.__handle_network_connections()
+
+                # Handle (read, execute) received network data/commands
+                self.__handle_network_messages(interact_mode_opts=interact_mode_opts)
+
+                # Stream live data (generated and environmental)
+                if len(self.hosted.all_agents) > 0:
+                    if self.node_type is Node.WORLD:
+                        if self.first is True:
+                            self.first = False
+                            for net_hash, stream_dict in self.hosted.known_streams.items():
+                                for stream_obj in stream_dict.values():
+                                    if isinstance(stream_obj, BufferedDataStream):
+                                        stream_obj.restart()
+                self.hosted.send_stream_samples()
+
+                # Trigger HSM of the agent
+                if self.node_type is Node.AGENT:
+                    if interact_mode_opts is not None:
+                        try:
+
+                            # Waiting until we meet a state named "ready"
+                            if not ready_to_interact:
+                                behav = self.agent.behav_lone_wolf \
+                                    if "lone_wolf_peer_id" in interact_mode_opts else self.agent.behav
+                                if behav.state == "ready":
+                                    ready_to_interact = True
+                                    keyboard_listener.start()
+                                    cap = cv2.VideoCapture(0) if processor_img_stream is not None else None
+                                    print(f"\n*** Entering interactive text mode ***\n\n👉 ", end="")
+
+                                    original_stdout = sys.stdout  # Valid screen-related stream
+                                    sys.stdout = open('interact_stdout.txt',
+                                                      'w')  # Open(os.devnull, 'w')  # null stream
+                                    interact_mode_opts["stdout"] = [original_stdout, sys.stdout]
+
+                            # Getting message from keyboard
+                            msg, image_pil = keyboard_queue.get_nowait()
+
+                            # Quit?
+                            msg = msg.strip()
+                            if msg == "exit" or msg == "quit":
+                                must_quit = True
+                                interact_mode_opts["stdout"][1].close()
+                                if cap is not None:
+                                    cap.release()
+                            else:
+
+                                # Asking the to generate (the request will be immediately sent)
+                                if "lone_wolf_peer_id" in interact_mode_opts:
+                                    behav = self.agent.behav_lone_wolf
+                                    other_behav = self.agent.behav
+
+                                    other_behav.enable(False)
+                                    behav.enable(True)
+                                    self.agent.ask_gen(agent=interact_mode_opts["lone_wolf_peer_id"],
+                                                       u_hashes=[processor_net_hash],
+                                                       samples=1)
+                                    behav.enable(False)
+                                else:
+                                    self.agent.behav.request_action(action_name="ask_gen",
+                                                                    args={},
+                                                                    signature=self.get_world_peer_id(),
+                                                                    timestamp=self.clock.get_time(),
+                                                                    uuid=None)
+                                    behav = self.agent.behav
+                                    other_behav = self.agent.behav_lone_wolf
+                                    self.agent.behave()
+
+                                # Loading the message and image to the processor's output streams
+                                # they will be sent at the next clock cycle
+                                other_behav.enable(False)
+                                behav.enable(True)
+                                if processor_img_stream is not None:
+                                    [msg, image_pil], _ = self.agent.generate(input_net_hashes=None,
+                                                                              inputs=[msg, image_pil])
+                                    processor_text_stream.set(msg)
+                                    processor_img_stream.set(image_pil)
+                                else:
+                                    [msg], _ = self.agent.generate(input_net_hashes=None,
+                                                                   inputs=[msg])
+                                    processor_text_stream.set(msg)
+                                behav.enable(False)
+                        except queue.Empty:
+                            self.agent.behave()  # If nothing has been typed (+ enter)
+                    else:
+
+                        # Ordinary behaviour
+                        self.agent.behave()
+
+                # Send dynamic profile every "N" seconds
+                if (self.clock.get_time() - last_dynamic_profile_time >= self.send_dynamic_profile_every
+                        and self.profile.connections_changed()):
+                    try:
+                        last_dynamic_profile_time = self.clock.get_time()
+                        self.profile.unmark_change_in_connections()
+                        self.send_badges()  # Sending and clearing badges
+                        self.send_dynamic_profile()  # Sending
+                    except Exception as e:
+                        self.err(f"Error while sending the update dynamic profile (or badges) to the server "
+                                 f"(trying to go ahead...) [{e}]")
+
+                # Getting a new token every "N" seconds
+                if self.clock.get_time() - last_get_token_time >= self.get_new_token_every:
+                    self.get_node_token(peer_ids=[self.get_public_peer_id(), self.get_world_peer_id()])
+                    last_get_token_time = self.clock.get_time()
+
+                # Sending alive message every "K" seconds
+                if self.clock.get_time() - self.last_alive_time >= self.send_alive_every:
+                    was_alive = self.send_alive()
+
+                    # Checking only at the first run
+                    if self.last_alive_time == 0 and was_alive and not self.skip_was_alive_check:
+                        print(f"The node is already alive, maybe running in a different machine? "
+                              f"(set env variable NODE_IGNORE_ALIVE=1 to ignore this control)")
+                        break  # Stopping the running cycle
+                    self.last_alive_time = self.clock.get_time()
+
+                # Check for address changes every "N" seconds
+                if self.clock.get_time() - last_address_check_time >= self.address_check_every:
+                    self.out("Performing periodic check for address changes...")
+                    last_address_check_time = self.clock.get_time()
+                    try:
+                        current_public_addrs = self.conn.p2p_public.get_node_addresses()
+                        current_private_addrs = self.conn.p2p_world.get_node_addresses()
+                        profile_public_addrs = self.profile.get_dynamic_profile().get('peer_addresses', [])
+                        profile_private_addrs = self.profile.get_dynamic_profile().get('private_peer_addresses', [])
+
+                        # TODO: if public addresses changed... (if this makes any sense)
+                        if set(current_public_addrs) != set(profile_public_addrs):
+                            self.out(f"Address change detected for the public instance! "
+                                     f"New addresses: {current_public_addrs}")
+
+                            # Update profile in-place
+                            # address_list = self.profile.get_dynamic_profile()['peer_addresses']
+                            # address_list.clear()
+                            # address_list.extend(current_public_addrs)
+                            # self.profile.mark_change_in_connections()
+
+                        # If private addresses changed, update the profile and notify the world
+                        elif set(current_private_addrs) != set(profile_private_addrs):
+                            self.out(f"Address change detected for the private instance! "
+                                     f"New addresses: {current_public_addrs}")
+
+                            # Update profile in-place
+                            address_list = self.profile.get_dynamic_profile()['private_peer_addresses']
+                            address_list.clear()
+                            address_list.extend(current_private_addrs)
+                            # self.profile.mark_change_in_connections()
+
+                            world_peer_id = (
+                                self.profile.get_dynamic_profile().get('connections', {}).get('world_peer_id'))
+                            if self.node_type is Node.AGENT and world_peer_id:
+                                self.out("Notifying world of address change...")
+                                self.conn.send(
+                                    world_peer_id, content_type=Msg.ADDRESS_UPDATE, channel_trail=None,
+                                    content={'addresses': self.profile.get_dynamic_profile()['private_peer_addresses']}
+                                )
+                        else:
+                            self.out("No address changes detected.")
+                    except Exception as e:
+                        self.err(f"Failed to check for address updates: {e}")
+
+                # Refresh relay reservation if nearing expiration
+                if self.relay_reservation_expiry is not None:
+                    time_to_expiry = self.relay_reservation_expiry - datetime.now(timezone.utc)
+                    if time_to_expiry < timedelta(minutes=15):
+                        self.out("Relay reservation nearing expiration. Attempting to renew...")
+                        try:
+                            world_private_peer_id = self.profile.get_dynamic_profile()['connections']['world_peer_id']
+                            new_expiry_utc = self.conn.p2p_world.reserve_on_relay(world_private_peer_id)
+                            self.relay_reservation_expiry = datetime.fromisoformat(
+                                new_expiry_utc.replace('Z', '+00:00'))
+                            self.out(f"Relay reservation renewed. New expiration: "
+                                     f"{self.relay_reservation_expiry.strftime('%Y-%m-%d %H:%M:%S')} UTC")
+                        except Exception as e:
+                            self.err(f"Failed to renew relay reservation: {e}. Node may become unreachable.")
+                            self.relay_reservation_expiry = None  # Stop trying if it fails
+
+                # Taking to the inspector
+                if self.inspector_activated:
+                    self.__send_to_inspector()
+
+                # Stop conditions
+                if cycles is not None and ((self.clock.get_cycle() + 1) >= cycles):
+                    break
+                if max_time is not None and self.clock.get_time(passed=True) >= max_time:
+                    break
+
+        except KeyboardInterrupt:
+            if self.cursor_hidden:
+                sys.stdout.write("\033[?25h")  # Re-enabling cursor
+            if cycles == 1:
+                raise KeyboardInterrupt  # Node synch will catch this
+            else:
+                print("\nDetected Ctrl+C! Exiting gracefully...")
+
+        except Exception as e:
+            if self.cursor_hidden:
+                sys.stdout.write("\033[?25h")  # Re-enabling cursor
+            print(f"An error occurred: {e}")
+            traceback.print_exc()
+
+    def __handle_network_connections(self):
+        """Manages new and lost network connections."""
+        
+        # Getting fresh lists of existing world agents and world masters (from the rendezvous)
+        if self.node_type is Node.AGENT:
+            self.out("Updating list of world agents and world masters by using data from the rendezvous")
+            self.conn.set_world_agents_and_world_masters_lists_from_rendezvous()
+
+        # Updating connection pools, getting back the lists (well, dictionaries) of new agents and lost agents
+        new_peer_ids_by_pool, removed_peer_ids_by_pool = self.conn.update()
+        if len(new_peer_ids_by_pool) > 0 or len(removed_peer_ids_by_pool) > 0:
+            self.out("Current status of the pools, right after the update:\n" + str(self.conn))
+
+        # Checking if some peers were removed
+        an_agent_left_the_world = False
+        removed_peers = False
+        for pool_name, removed_peer_ids in removed_peer_ids_by_pool.items():
+            for peer_id in removed_peer_ids:
+                removed_peers = True
+                self.out("Removing a not-connected-anymore peer, "
+                         "pool_name: " + pool_name + ", peer_id: " + peer_id + "...")
+                self.__purge(peer_id)
+
+                # Checking if we removed an agent from this world
+                if self.node_type is Node.WORLD and pool_name in self.conn.WORLD:
+                    an_agent_left_the_world = True
+
+                # Check if the world disconnected: in that case, disconnect all the other agents in the world and leave
+                if self.node_type is Node.AGENT and pool_name in self.conn.WORLD_NODE:
+                    self.leave_world()
+
+                # Checking if the inspector disconnected
+                if peer_id == self.inspector_peer_id:
+                    self.inspector_activated = False
+                    self.inspector_peer_id = None
+                    self.__inspector_cache = {"behav": None, "known_streams_count": 0, "all_agents_count": 0}
+                    print("Inspector disconnected")
+
+        # Handling newly connected peers
+        an_agent_joined_the_world = False
+        added_peers = False
+        for pool_name, new_peer_ids in new_peer_ids_by_pool.items():
+            for peer_id in new_peer_ids:
+                added_peers = True
+                self.out("Processing a newly connected peers, "
+                         "pool_name: " + pool_name + ", peer_id: " + peer_id + "...")
+
+                # If this is a world node, it is time to tell the world object that a new agent is there
+                if self.node_type is Node.WORLD and pool_name in self.conn.WORLD:
+                    self.out("Not considering interviewing since this is a world and the considered peer is in the"
+                             " world pools")
+
+                    if peer_id in self.agents_to_interview:
+
+                        # Getting the new agent profile
+                        profile = self.agents_to_interview[peer_id][1]  # [time, profile]
+
+                        # Adding the new agent to the world object
+                        if not self.world.add_agent(peer_id=peer_id, profile=profile):
+                            self.__purge(peer_id)
+                            continue
+
+                        # Clearing the profile from the interviews
+                        del self.agents_to_interview[peer_id]  # Removing from the queue (private peer id)
+                        an_agent_joined_the_world = True
+
+                        # Replacing multi-address with what comes from the profile (there are more addresses there!)
+                        self.conn.set_addresses_in_peer_info(peer_id,
+                                                             profile.get_dynamic_profile()['private_peer_addresses'])
+                    else:
+
+                        # This agent tried to connect to a world "directly", without passing through the
+                        # public handshake
+                        self.__purge(peer_id)
+                        continue
+
+                    continue  # Nothing else to do
+
+                # Both if this is an agent or a world, checks if the newly connected agent can be added or not to the
+                # queue of agents to interview
+                if pool_name not in self.conn.OUTGOING:
+
+                    # Trying to add to the queue
+                    enqueued_for_interview = self.__interview_enqueue(peer_id)
+
+                    # If the agent is rejected at this stage, we disconnect from its peer
+                    if not enqueued_for_interview:
+                        self.out(f"Not enqueued for interview, removing peer (disconnecting {peer_id})")
+                        self.__purge(peer_id)
+                    else:
+                        self.out("Enqueued for interview")
+
+        # Updating list of world agents & friends, if needed
+        # (it happens only if the node hosts a world, otherwise 'an_agent_joined_the_world' and
+        # 'an_agent_left_the_world' are certainly False)
+        world_agents_peer_infos = None
+        world_masters_peer_infos = None
+        if self.node_type is Node.WORLD:
+            enter_left = an_agent_joined_the_world or an_agent_left_the_world
+            timeout = (self.clock.get_time() - self.last_rendezvous_time) >= self.publish_rendezvous_every
+
+            if enter_left or timeout or self.world.role_changed_by_world or self.world.received_address_update:
+                if enter_left or self.world.role_changed_by_world:
+
+                    # Updating world-node profile with the summary of currently connected agents in the world
+                    world_agents_peer_infos = self.conn.get_all_connected_peer_infos(NodeConn.WORLD_AGENTS)
+                    world_masters_peer_infos = self.conn.get_all_connected_peer_infos(NodeConn.WORLD_MASTERS)
+
+                    dynamic_profile = self.profile.get_dynamic_profile()
+                    dynamic_profile['world_summary']['world_agents'] = world_agents_peer_infos
+                    dynamic_profile['world_summary']['world_masters'] = world_masters_peer_infos
+                    dynamic_profile['world_summary']["world_agents_count"] = len(world_agents_peer_infos)
+                    dynamic_profile['world_summary']["world_masters_count"] = len(world_masters_peer_infos)
+                    dynamic_profile['world_summary']["total_agents"] = (len(world_agents_peer_infos) +
+                                                                        len(world_masters_peer_infos))
+                    self.profile.mark_change_in_connections()
+
+                # Publish updated list of (all) world agents (i.e., both agents and masters)
+                world_all_peer_infos = self.conn.get_all_connected_peer_infos(NodeConn.WORLD)
+                if not self.conn.publish(self.conn.p2p_world.peer_id, f"{self.conn.p2p_world.peer_id}::ps:rv",
+                                         content_type=Msg.WORLD_AGENTS_LIST,
+                                         content={"peers": world_all_peer_infos,
+                                                  "update_count": self.clock.get_cycle()}):
+                    self.err("Failed to publish the updated list of (all) world agents (ignoring)")
+                else:
+                    self.last_rendezvous_time = self.clock.get_time()
+                    self.out(f"Rendezvous messages just published "
+                             f"(tag: {self.clock.get_cycle()}, peers: {len(world_all_peer_infos)})")
+
+                    # Clearing
+                    self.world.role_changed_by_world = False
+                    self.world.received_address_update = False
+
+        # Updating list of node connections (being this a world or a plain agent)
+        if added_peers or removed_peers:
+
+            # The following could have been already computed in the code above, let's reuse
+            if world_agents_peer_infos is None:
+                world_agents_peer_infos = self.conn.get_all_connected_peer_infos(NodeConn.WORLD_AGENTS)
+            if world_masters_peer_infos is None:
+                world_masters_peer_infos = self.conn.get_all_connected_peer_infos(NodeConn.WORLD_MASTERS)
+            world_private_peer_id = self.conn.get_all_connected_peer_infos(NodeConn.WORLD_NODE)
+            world_private_peer_id = world_private_peer_id[0]['id'] if len(world_private_peer_id) > 0 else None
+
+            # This is only computed here
+            public_agents_peer_infos = self.conn.get_all_connected_peer_infos(NodeConn.PUBLIC)
+
+            # Updating node profile with the summary of currently connected peers
+            dynamic_profile = self.profile.get_dynamic_profile()
+            dynamic_profile['connections']['public_agents'] = public_agents_peer_infos
+            dynamic_profile['connections']['world_agents'] = world_agents_peer_infos
+            dynamic_profile['connections']['world_masters'] = world_masters_peer_infos
+            dynamic_profile['connections']['world_peer_id'] = world_private_peer_id
+            self.profile.mark_change_in_connections()
+
+    def __handle_network_messages(self, interact_mode_opts=None):
+        """Handles and processes all incoming network messages.
+
+        Args:
+            interact_mode_opts: A dictionary of options for interactive mode.
+        """
+        # Fetching all messages,
+        public_messages = self.conn.get_messages(p2p_name=NodeConn.P2P_PUBLIC)
+        world_messages = self.conn.get_messages(p2p_name=NodeConn.P2P_WORLD)
+
+        self.out("Got " + str(len(public_messages)) + " messages from the public net")
+        self.out("Got " + str(len(world_messages)) + " messages from the world/private net")
+
+        # Process all messages
+        all_messages = public_messages + world_messages
+        if len(all_messages) > 0:
+            self.out("Processing all messages...")
+
+        for i, msg in enumerate(all_messages):
+            if i < len(public_messages):
+                self.out("Processing public message " + str(i + 1) + "/"
+                         + str(len(public_messages)) + ": " + str(msg))
+            else:
+                self.out("Processing world/private message " + str(i - len(public_messages) + 1)
+                         + "/" + str(len(world_messages)) + ": " + str(msg))
+
+            # Checking
+            if not isinstance(msg, Msg):
+                self.err("Expected message of type Msg, got {} (skipping)".format(type(msg)))
+                continue
+
+            # Unpacking piggyback
+            sender_node_id, sender_inspector_mode_on = (msg.piggyback[0:-1],
+                                                        msg.piggyback[-1] == "1")
+
+            # Is message from inspector?
+            sender_is_inspector = (sender_node_id == self.profile.get_static_profile()['inspector_node_id'] and
+                                   sender_inspector_mode_on)
+
+            # (A) received a profile
+            if msg.content_type == Msg.PROFILE:
+                self.out("Received a profile...")
+
+                # Checking the received profile
+                # (recall that a profile sent through the world connection to the world node will be considered
+                # not acceptable)
+                profile = NodeProfile.from_dict(msg.content)
+                is_an_already_known_agent = msg.sender in self.hosted.all_agents
+
+                if is_an_already_known_agent:
+                    self.out("Editing information of an already added agent " + msg.sender)
+
+                    if not self.hosted.add_agent(peer_id=msg.sender, profile=profile):
+                        self.__purge(msg.sender)
+                else:
+                    is_expected_and_acceptable_profile = self.__interview_check_profile(peer_id=msg.sender,
+                                                                                        node_id=sender_node_id,
+                                                                                        profile=profile)
+
+                    if not is_expected_and_acceptable_profile:
+                        self.err("Unexpected or unacceptable profile, removing (disconnecting) " + msg.sender)
+                        self.__purge(msg.sender)
+                    else:
+
+                        # If the node hosts a world and gets an expected and acceptable profile from the public network,
+                        # assigns a role and sends the world profile (which includes private peer ID) and role to the
+                        # requester
+                        if (self.node_type is Node.WORLD and self.conn.is_public(peer_id=msg.sender) and
+                                not sender_is_inspector):
+                            self.out("Sending world approval message, profile, and assigned role to " + msg.sender +
+                                     " (and switching peer ID in the interview queue)...")
+                            is_world_master = (self.world_masters_node_ids is not None and
+                                               sender_node_id in self.world_masters_node_ids)
+
+                            # Assigning a role
+                            role_str = self.world.assign_role(profile=profile, is_world_master=is_world_master)
+                            if role_str is None:
+                                self.err("Unable to determine what role to assign, removing (disconnecting) "
+                                         + msg.sender)
+                                self.__purge(msg.sender)
+                            else:
+                                role = self.world.ROLE_STR_TO_BITS[role_str]  # The role is a bit-wise-interpretable int
+                                role = role | (Agent.ROLE_WORLD_MASTER if is_world_master else Agent.ROLE_WORLD_AGENT)
+
+                                # Clearing temporary options (if any)
+                                dynamic_profile = profile.get_dynamic_profile()
+                                keys_to_delete = [key for key in dynamic_profile if key.startswith('tmp_')]
+                                for key in keys_to_delete:
+                                    del dynamic_profile[key]
+
+                                if not self.conn.send(msg.sender, channel_trail=None,
+                                                      content={
+                                                          'world_profile': self.profile.get_all_profile(),
+                                                          'rendezvous_tag': self.clock.get_cycle(),
+                                                          'your_role': role,
+                                                          'agent_actions': self.world.agent_actions
+                                                      },
+                                                      content_type=Msg.WORLD_APPROVAL):
+                                    self.err("Failed to send world approval, removing (disconnecting) " + msg.sender)
+                                    self.__purge(msg.sender)
+                                else:
+                                    private_peer_id = profile.get_dynamic_profile()['private_peer_id']
+                                    private_addr = profile.get_dynamic_profile()['private_peer_addresses']
+                                    if is_world_master:
+                                        role = role | Agent.ROLE_WORLD_MASTER
+                                        self.conn.add_to_world_masters_list(private_peer_id, private_addr, role)
+                                    else:
+                                        role = role | Agent.ROLE_WORLD_AGENT
+                                        self.conn.add_to_world_agents_list(private_peer_id, private_addr, role)
+
+                                    # Removing from the queue of public interviews
+                                    # and adding to the private ones (refreshing timer)
+                                    del self.agents_to_interview[msg.sender]  # Removing from public queue
+                                    self.agents_to_interview[private_peer_id] = [self.clock.get_time(), profile]  # Add
+
+                        # If the node is an agent, it is time to tell the agent object that a new agent is now known,
+                        # and send our profile to the agent that asked for out contact
+                        elif self.node_type is Node.AGENT or sender_is_inspector:
+                            self.out("Sending agent approval message and profile...")
+
+                            if not self.conn.send(msg.sender, channel_trail=None,
+                                                  content={
+                                                      'my_profile': self.profile.get_all_profile()
+                                                  },
+                                                  content_type=Msg.AGENT_APPROVAL):
+                                self.err("Failed to send agent approval, removing (disconnecting) " + msg.sender)
+                                self.__purge(msg.sender)
+                            else:
+                                self.out("Adding known agent and removing it from the interview queue " + msg.sender)
+                                if not self.hosted.add_agent(peer_id=msg.sender, profile=profile):  # keep "hosted" here
+                                    self.__purge(msg.sender)
+                                else:
+
+                                    # Removing from the queues
+                                    del self.agents_to_interview[msg.sender]  # Removing from queue
+
+            # (B) received a world-join-approval
+            elif msg.content_type == Msg.WORLD_APPROVAL:
+                self.out("Received a world-join-approval message...")
+
+                # Checking if it is the world we asked for
+                # moreover, it must be on the public network, and this must not be a world-node (of course)
+                # and you must not be already in another world
+                if (not self.conn.is_public(peer_id=msg.sender) or self.node_type is Node.WORLD
+                        or msg.sender not in self.agents_expected_to_send_ack or
+                        self.profile.get_dynamic_profile()['connections']['world_peer_id'] is not None):
+                    self.err("Unexpected world approval, removing (disconnecting) " + msg.sender)
+                    self.__purge(msg.sender)
+                else:
+                    if msg.sender != self.joining_world_info["world_public_peer_id"]:
+                        self.err(f"Unexpected world approval: asked to join "
+                                 f"{self.joining_world_info['world_public_peer_id']} got approval from {msg.sender} "
+                                 f"(disconnecting)")
+                        self.__purge(msg.sender)
+                    else:
+
+                        # Getting world profile (includes private addresses) and connecting to the world (privately)
+                        self.__join_world(profile=NodeProfile.from_dict(msg.content['world_profile']),
+                                          role=msg.content['your_role'],
+                                          agent_actions=msg.content['agent_actions'],
+                                          rendezvous_tag=msg.content['rendezvous_tag'])
+
+            # (C) received an agent-connect-approval
+            elif msg.content_type == Msg.AGENT_APPROVAL:
+                self.out("Received an agent-connect-approval message...")
+
+                # Checking if it is the agent we asked for
+                if msg.sender not in self.agents_expected_to_send_ack:
+                    self.err("Unexpected agent-connect approval, removing (disconnecting) " + msg.sender)
+                    self.__purge(msg.sender)
+                else:
+
+                    # Adding the agent
+                    self.__join_agent(profile=NodeProfile.from_dict(msg.content['my_profile']),
+                                      peer_id=msg.sender)
+
+            # (D) requested for a profile
+            elif msg.content_type == Msg.PROFILE_REQUEST:
+                self.out("Received a profile request...")
+
+                # If this is a world-node, it expects profile requests only on the public network
+                # if this is not a world or not, we only send profile to agents who are involved in the handshake
+                if ((self.node_type is Node.WORLD and not self.conn.is_public(peer_id=msg.sender)) or
+                        (msg.sender not in self.agents_expected_to_send_ack)):
+                    self.err("Unexpected profile request, removing (disconnecting) " + msg.sender)
+                    self.__purge(msg.sender)
+                else:
+
+                    # If a preference was defined, we temporarily add it to the profile
+                    if (self.joining_world_info is not None and
+                            msg.sender == self.joining_world_info["world_public_peer_id"] and
+                            self.joining_world_info["options"] is not None and
+                            len(self.joining_world_info["options"]) > 0):
+                        my_profile = copy.deepcopy(self.profile)
+                        for k, v in self.joining_world_info["options"].items():
+                            my_profile.get_dynamic_profile()['tmp_' + str(k)] = v
+                        my_profile = my_profile.get_all_profile()
+                    else:
+                        my_profile = self.profile.get_all_profile()
+
+                    # Sending the profile
+                    self.out("Sending profile")
+                    if not self.conn.send(msg.sender, channel_trail=None,
+                                          content=my_profile,
+                                          content_type=Msg.PROFILE):
+                        self.err("Failed to send profile, removing (disconnecting) " + msg.sender)
+                        self.__purge(msg.sender)
+
+            # (E) the world node received an ADDRESS_UPDATE from an agent
+            elif msg.content_type == Msg.ADDRESS_UPDATE:
+                self.out("Received an address update from " + msg.sender)
+
+                if self.node_type is Node.WORLD and msg.sender in self.world.all_agents:
+                    all_addresses = msg.content.get('addresses')
+                    if all_addresses and isinstance(all_addresses, list):
+
+                        # Update the address both in the connection and in the profile
+                        self.conn.set_addresses_in_peer_info(msg.sender, all_addresses)
+                        self.world.set_addresses_in_profile(msg.sender, all_addresses)
+                        self.out(f"Waiting rendezvous publish after address update from {msg.sender}")
+
+            # (F) got stream data
+            elif msg.content_type == Msg.STREAM_SAMPLE:
+                self.out("Received a stream sample...")
+
+                if self.node_type is Node.AGENT:  # Handling the received samples
+                    self.agent.get_stream_sample(net_hash=msg.channel, sample_dict=msg.content)
+
+                    # Printing messages to screen, if needed (useful when chatting with lone wolves)
+                    if interact_mode_opts is not None and "stdout" in interact_mode_opts:
+                        net_hash = DataProps.normalize_net_hash(msg.channel)
+                        if net_hash in self.agent.known_streams:
+                            stream_dict = self.agent.known_streams[net_hash]
+                            sys.stdout = interact_mode_opts["stdout"][0]  # Output on
+                            for name, stream_obj in stream_dict.items():
+                                if stream_obj.props.is_text():
+                                    msg = stream_obj.get(requested_by="print")  # Getting message
+                                    print(f"\n『 {msg} 』")  # Printing to screen
+                                if stream_obj.props.is_img():
+                                    img = stream_obj.get(requested_by="print")  # Getting image
+                                    filename = "wolf_img.png"
+                                    img.save(filename)
+                                    msg = f"(saved image to {filename})"
+                                    print(f"\n『 {msg} 』")  # Printing to screen
+                            print("\n👉 ", end="")
+                            sys.stdout = interact_mode_opts["stdout"][1]  # Output off
+
+                elif self.node_type is Node.WORLD:
+                    self.err("Unexpected stream samples received by this world node, sent by: " + msg.sender)
+                    self.__purge(msg.sender)
+
+            # (G) got action request
+            elif msg.content_type == Msg.ACTION_REQUEST:
+                self.out("Received an action request...")
+
+                if self.node_type is Node.AGENT:
+                    if msg.sender not in self.agent.all_agents:
+                        self.err("Unexpected action request received by a unknown node: " + msg.sender)
+                    else:
+                        behav = self.agent.behav_lone_wolf \
+                            if msg.sender in self.agent.public_agents else self.agent.behav
+                        behav.request_action(action_name=msg.content['action_name'],
+                                             args=msg.content['args'],
+                                             signature=msg.sender,
+                                             timestamp=self.clock.get_time(),
+                                             uuid=msg.content['uuid'])
+
+                elif self.node_type is Node.WORLD:
+                    self.err("Unexpected action request received by this world node, sent by: " + msg.sender)
+                    self.__purge(msg.sender)
+
+            # (H) got role suggestion
+            elif msg.content_type == Msg.ROLE_SUGGESTION:
+                self.out("Received a role suggestion/new role...")
+
+                if self.node_type is Node.AGENT:
+                    if msg.sender == self.conn.get_world_peer_id():
+                        new_role_indication = msg.content
+                        if new_role_indication['peer_id'] == self.get_world_peer_id():
+                            self.agent.accept_new_role(new_role_indication['role'])
+
+                            self.agent.behav.update_wildcard("<agent>", f"{self.get_world_peer_id()}")
+                            self.agent.behav.update_wildcard("<world>", f"{msg.sender}")
+
+                elif self.node_type is Node.WORLD:
+                    if msg.sender in self.world.world_masters:
+                        for role_suggestion in msg.content:
+                            self.world.set_role(peer_id=role_suggestion['peer_id'], role=role_suggestion['role'])
+
+            # (I) got request to alter the HSM
+            elif msg.content_type == Msg.HSM:
+                self.out("Received a request to alter the HSM...")
+
+                if self.node_type is Node.AGENT:
+                    if msg.sender in self.agent.world_masters:  # This must be coherent with what we do in set_role
+                        ret = getattr(self.agent.behav, msg.content['method'])(*msg.content['args'])
+                        if not ret:
+                            self.err(f"Cannot run HSM action named {msg.content['method']} with args "
+                                     f"{msg.content['args']}")
+                    else:
+                        self.err("Only world-master can alter HSMs of other agents: " + msg.sender)  # No need to purge
+
+                elif self.node_type is Node.WORLD:
+                    self.err("Unexpected request to alter the HSM received by this world node, sent by: " + msg.sender)
+                    self.__purge(msg.sender)
+
+            # (J) misc
+            elif msg.content_type == Msg.MISC:
+                self.out("Received a misc message...")
+                self.out(msg.content)
+
+            # (K) got a request to re-download the CV from the root server
+            elif msg.content_type == Msg.GET_CV_FROM_ROOT:
+                self.out("Received a notification to re-download the CV...")
+
+                # Downloading CV
+                self.profile.update_cv(self.get_cv())
+
+                # Re-downloading token (it will include the new CV hash)
+                self.get_node_token(peer_ids=[self.get_public_peer_id(), self.get_world_peer_id()])
+
+            # (L) got one or more badge suggestions
+            elif msg.content_type == Msg.BADGE_SUGGESTIONS:
+                self.out("Received badge suggestions...")
+
+                if self.node_type is Node.WORLD:
+                    for badge_dict in msg.content:
+
+                        # Right now, we accept all the suggestions
+                        self.world.add_badge(**badge_dict)  # Adding to the list of badges
+                elif self.node_type is Node.AGENT:
+                    self.err("Receiving badge suggestions is not expected for an agent node")
+
+            # (M) got a special connection/presence message for an inspector
+            elif msg.content_type == Msg.INSPECT_ON:
+                self.out("Received an inspector-activation message...")
+
+                if sender_is_inspector:
+                    self.inspector_activated = True
+                    self.inspector_peer_id = msg.sender
+                    print("Inspector activated")
+                else:
+                    self.err("Inspector-activation message was not sent by the expected inspector node ID")
+                    self.__purge(msg.sender)
+
+            # (N) got a command from an inspector
+            elif msg.content_type == Msg.INSPECT_CMD:
+                self.out("Received a command from the inspector...")
+
+                if sender_is_inspector and self.inspector_activated:
+                    self.__handle_inspector_command(msg.content['cmd'], msg.content['arg'])
+                else:
+                    self.err("Inspector command was not sent by the expected inspector node ID "
+                             "or the inspector was not yet activated (Msg.INSPECT_ON not received yet)")
+                    self.__purge(msg.sender)
+
+        self.__interview_clean()
+        self.__connected_without_ack_clean()
+
+    def __join_world(self, profile: NodeProfile, role: int,
+                     agent_actions: str | None, rendezvous_tag: int):
+        """Performs the actual operation of joining a world after receiving confirmation.
+
+        Args:
+            profile: The profile of the world to join.
+            role: The role assigned to the agent in the world (int).
+            agent_actions: A string of code defining the agent's actions.
+            rendezvous_tag: The rendezvous tag from the world's profile.
+
+        Returns:
+            True if the join operation is successful, otherwise False.
+        """
+        addresses = profile.get_dynamic_profile()['private_peer_addresses']
+        world_public_peer_id = profile.get_dynamic_profile()['peer_id']
+        self.out(f"Actually joining world, role will be {role}")
+
+        # Connecting to the world (private)
+        # notice that we also communicate the world node private peer ID to the connection manager,
+        # to avoid filtering it out when updating pools
+        peer_id = self.ask_to_get_in_touch(addresses=addresses, public=False,
+                                           before_updating_pools_fcn=self.conn.set_world)
+
+        if peer_id is not None:
+
+            # Relay reservation logic for non-public peers
+            if not self.conn.p2p_world.is_public and self.conn.p2p_world.relay_is_enabled:
+                self.out("Node is not publicly reachable. Attempting to reserve a slot on the world's private network.")
+                try:
+                    expiry_utc = self.conn.p2p_world.reserve_on_relay(peer_id)
+                    self.relay_reservation_expiry = (
+                        datetime.fromisoformat(expiry_utc.replace('Z', '+00:00')))
+                    self.out(f"Reserved relay slot. Expires at "
+                             f"{self.relay_reservation_expiry.strftime('%Y-%m-%d %H:%M:%S')} UTC")
+
+                    self.out("Fetching updated address list from transport layer...")
+                    complete_private_addrs = self.conn.p2p_world.get_node_addresses()
+
+                    # Update the profile with this definitive list (IN-PLACE)
+                    address_list = self.profile.get_dynamic_profile()['private_peer_addresses']
+                    address_list.clear()
+                    address_list.extend(complete_private_addrs)
+
+                    self.out("Notifying world of the complete updated address list...")
+                    self.conn.send(peer_id, channel_trail=None,
+                                   content_type=Msg.ADDRESS_UPDATE,
+                                   content={'addresses': complete_private_addrs})
+                except Exception as e:
+                    self.err(f"An error occurred during relay reservation: {e}.")
+
+            # Subscribing to the world rendezvous topic, from which we will get fresh information
+            # about the world agents and masters
+            self.out("Subscribing to the world-members topic...")
+            if not self.conn.subscribe(peer_id, channel=f"{peer_id}::ps:rv"):  # Special rendezvous (ps:rv)
+                self.leave(peer_id)  # If subscribing fails, we quit everything (safer)
+                return False
+
+            # Killing the public connection to the world node
+            self.out("Disconnecting from the public world network (since we joined the private one)")
+            self.__purge(world_public_peer_id)
+
+            # Removing the private world peer id from the list of connected-but-not-managed peer
+            del self.agents_expected_to_send_ack[peer_id]
+
+            # Subscribing to all the other world topics, from which we will get fresh information
+            # about the streams
+            self.out("Subscribing to the world-streams topics...")
+            dynamic_profile = profile.get_dynamic_profile()
+            list_of_props = []
+            list_of_props += dynamic_profile['streams'] if dynamic_profile['streams'] is not None else []
+            list_of_props += dynamic_profile['proc_outputs'] if dynamic_profile['proc_outputs'] is not None else []
+
+            if not self.agent.add_compatible_streams(peer_id, list_of_props, buffered=False, public=False):
+                self.leave(peer_id)
+                return False
+
+            # Setting actions
+            if agent_actions is not None and len(agent_actions) > 0:
+
+                # Checking code
+                if not Node.__analyze_code(agent_actions):
+                    self.err("Invalid agent actions code (syntax errors or unsafe code) was provided by the world, "
+                             "blocking the join operation")
+                    return False
+
+                # Creating a new agent with the received actions
+                mod = types.ModuleType("dynamic_module")
+                exec(agent_actions, mod.__dict__)
+                sys.modules["dynamic_module"] = mod
+                new_agent = mod.WAgent(proc=None)
+
+                # Cloning attributes of the existing agent
+                for key, value in self.agent.__dict__.items():
+                    if hasattr(new_agent, key):  # This will skip ROLE_BITS_TO_STR, CUSTOM_ROLES, etc...
+                        setattr(new_agent, key, value)
+
+                # Telling the FSM that actions are related to this new agent
+                new_agent.behav.set_actionable(new_agent)
+                new_agent.behav_lone_wolf.set_actionable(new_agent)
+
+                # Setting up roles
+                roles = profile.get_dynamic_profile()['world_roles_fsm'].keys()
+                new_agent.CUSTOM_ROLES = roles
+                new_agent.augment_roles()
+
+                # Updating node-level references
+                old_agent = self.agent
+                self.agent = new_agent
+                self.hosted = new_agent
+            else:
+                old_agent = self.agent
+
+            # Saving the world profile
+            self.agent.world_profile = profile
+
+            # Setting the assigned role and default behavior (do it after having recreated the new agent object)
+            self.agent.accept_new_role(role)  # Do this after having done 'self.agent.world_profile = profile'
+
+            # Updating wildcards
+            self.agent.behav.update_wildcard("<agent>", f"{self.get_world_peer_id()}")
+            self.agent.behav.update_wildcard("<world>", f"{peer_id}")
+            self.agent.behav.add_wildcards(old_agent.behav_wildcards)
+
+            # Telling the connection manager the info needed to discriminate peers (getting them from the world profile)
+            # notice that the world node private ID was already told to the connection manager (see a few lines above)
+            self.out(f"Rendezvous tag received with profile: {rendezvous_tag} "
+                     f"(in conn pool: {self.conn.rendezvous_tag})")
+            if self.conn.rendezvous_tag < rendezvous_tag:
+                self.conn.rendezvous_tag = rendezvous_tag
+                num_world_masters = len(dynamic_profile['world_summary']['world_masters']) \
+                    if dynamic_profile['world_summary']['world_masters'] is not None else 'none'
+                num_world_agents = len(dynamic_profile['world_summary']['world_agents']) \
+                    if dynamic_profile['world_summary']['world_agents'] is not None else 'none'
+                self.out(f"Rendezvous from profile (tag: {rendezvous_tag}), world masters: {num_world_masters}")
+                self.out(f"Rendezvous from profile (tag: {rendezvous_tag}), world agents: {num_world_agents}")
+                self.conn.set_world_masters_list(dynamic_profile['world_summary']['world_masters'])
+                self.conn.set_world_agents_list(dynamic_profile['world_summary']['world_agents'])
+
+            # Updating our profile to set the world we are in
+            self.profile.get_dynamic_profile()['connections']['world_peer_id'] = peer_id
+            self.profile.mark_change_in_connections()
+
+            print("Handshake completed, world joined!")
+            return True
+        else:
+            return False
+
+    def __join_agent(self, profile: NodeProfile, peer_id: str):
+        """Adds a new known agent after receiving an approval message.
+
+        Args:
+            profile: The profile of the agent to join.
+            peer_id: The peer ID of the agent.
+
+        Returns:
+            True if the agent is successfully added, otherwise False.
+        """
+        self.out("Adding known agent " + peer_id)
+        if not self.agent.add_agent(peer_id=peer_id, profile=profile):
+            self.__purge(peer_id)
+            return False
+
+        del self.agents_expected_to_send_ack[peer_id]
+        return True
+
+    def __interview_enqueue(self, peer_id: str):
+        """Adds a newly connected peer to the queue of agents to be interviewed.
+
+        Args:
+            peer_id: The peer ID of the agent to interview.
+
+        Returns:
+            True if the agent is successfully enqueued, otherwise False.
+        """
+
+        # If the peer_id is not in the same world were we are, we early stop the interview process
+        if (not self.conn.is_public(peer_id) and peer_id not in self.conn.world_agents_list and
+                peer_id not in self.conn.world_masters_list and peer_id != self.conn.world_node_peer_id):
+            self.out(f"Interview failed: "
+                     f"peer ID {peer_id} is not in the world agents/masters list, and it is not the world node")
+            return False
+
+        # Ask for the profile
+        ret = self.conn.send(peer_id, channel_trail=None,
+                             content_type=Msg.PROFILE_REQUEST, content=None)
+        if not ret:
+            self.out(f"Interview failed: "
+                     f"unable to send a profile request to peer ID {peer_id}")
+            return False
+
+        # Put the agent in the list of agents to interview
+        self.agents_to_interview[peer_id] = [self.clock.get_time(), None]  # Peer ID -> [time, profile]; no profile yet
+        return True
+
+    def __interview_check_profile(self, peer_id: str, node_id: str, profile: NodeProfile):
+        """Checks if a received profile is acceptable and valid.
+
+        Args:
+            peer_id: The peer ID of the node that sent the profile.
+            node_id: The node ID of the node that sent the profile.
+            profile: The NodeProfile object to be checked.
+
+        Returns:
+            True if the profile is acceptable, otherwise False.
+        """
+
+        # If the node ID was not on the list of allowed ones (if the list exists), then stop it
+        # notice that we do not get the node ID from the profile, but from outside (it comes from the token, so safe)
+        if ((self.allowed_node_ids is not None and node_id not in self.allowed_node_ids) or
+                (peer_id not in self.agents_to_interview)):
+            self.out(f"Profile of f{peer_id} not in the list of agents to interview or its node ID is not allowed")
+            return False
+        else:
+
+            # Getting the parts of profile needed
+            eval_static_profile = profile.get_static_profile()
+            eval_dynamic_profile = profile.get_dynamic_profile()
+            my_dynamic_profile = self.profile.get_dynamic_profile()
+
+            # Checking if CV was altered
+            cv_hash = self.conn.get_cv_hash_from_last_token(peer_id)
+            sanity_ok, pairs_of_hashes = profile.verify_cv_hash(cv_hash)
+            if not sanity_ok:
+                self.out(f"The CV in the profile of f{peer_id} failed the sanity check {pairs_of_hashes},"
+                         f" {profile.get_cv()}")
+                return False
+
+            # Determining type of agent, checking the connection pools
+            role = self.conn.get_role(peer_id)
+
+            if role & 1 == 0:
+
+                # Ensuring that the interviewed agent is out of every world
+                # (if it were in the same world in which we are, it would connect in a private manner) and
+                # possibly fulfilling the optional constraint of accepting only certified agent,
+                # then asking the hosted entity for additional custom evaluation
+                if (eval_dynamic_profile['connections']['world_peer_id'] is None and
+                        (not self.only_certified_agents or eval_static_profile['certified'] is True)):
+                    return self.hosted.evaluate_profile(role, profile)
+                else:
+                    self.out(f"Peer f{peer_id} is already living in a world, of it is not certified "
+                             f"and maybe I expect certified only")
+                    return False
+            else:
+
+                if self.node_type is Node.AGENT:
+
+                    # Ensuring that the interviewed agent is in the same world where we are and
+                    # possibly fulfilling the optional constraint of accepting only certified agent
+                    if (eval_dynamic_profile['connections']['world_peer_id'] is not None and
+                            eval_dynamic_profile['connections']['world_peer_id'] ==
+                            my_dynamic_profile['connections']['world_peer_id'] and
+                            (not self.only_certified_agents or 'certified' in eval_static_profile and
+                             eval_static_profile['certified'] is True)):
+                        return self.hosted.evaluate_profile(role, profile)
+                    else:
+                        self.out(f"Peer f{peer_id} is living in a different world, of it is not certified "
+                                 f"and maybe I expect certified only")
+                        return False
+
+                elif self.node_type is Node.WORLD:
+
+                    # If this node hosts a world, we do not expect to interview agents in the private world connection,
+                    # so something went wrong here, let's reject it
+                    self.out(f"Peer f{peer_id} sent a profile in the private network, unexpected")
+                    return False
+
+    def __interview_clean(self):
+        """Removes outdated or timed-out interview requests from the queue."""
+        cur_time = self.clock.get_time()
+        agents_to_remove = []
+        for peer_id, (profile_time, profile) in self.agents_to_interview.items():
+
+            # Checking timeout
+            if (cur_time - profile_time) > self.interview_timeout:
+                self.out("Removing (disconnecting) due to timeout in interview queue: " + peer_id)
+                agents_to_remove.append(peer_id)
+
+        # Updating
+        for peer_id in agents_to_remove:
+            self.__purge(peer_id)  # This will also remove the peer from the queue of peers to interview
+
+    def __connected_without_ack_clean(self):
+        """Removes connected peers from the queue if they haven't sent an acknowledgment within the timeout period."""
+        cur_time = self.clock.get_time()
+        agents_to_remove = []
+        for peer_id, connection_time in self.agents_expected_to_send_ack.items():
+
+            # Checking timeout
+            if (cur_time - connection_time) > self.connect_without_ack_timeout:
+                self.out("Removing (disconnecting) due to timeout in the connected-without-ack queue: " + peer_id)
+                agents_to_remove.append(peer_id)
+
+        # Updating
+        for peer_id in agents_to_remove:
+            self.__purge(peer_id)  # This will also remove the peer from the queue of in the connected-without-ack queue
+
+    def __purge(self, peer_id: str):
+        """Removes a peer from all relevant connection lists and queues.
+
+        Args:
+            peer_id: The peer ID of the node to purge.
+        """
+        self.hosted.remove_agent(peer_id)
+        self.conn.remove(peer_id)
+
+        # Clearing also the contents of the list of interviews
+        if peer_id in self.agents_to_interview:
+            del self.agents_to_interview[peer_id]
+
+        # Clearing the temporary list of connected agents
+        if peer_id in self.agents_expected_to_send_ack:
+            del self.agents_expected_to_send_ack[peer_id]
+
+    def __root(self, api: str, payload: dict):
+        """Sends a POST request to the root server's API endpoint.
+
+        Args:
+            api: The API endpoint to send the request to.
+            payload: The data to be sent in the request body.
+
+        Returns:
+            The 'data' field from the server's JSON response.
+        """
+        response_fields = ["state", "flags", "data"]
+
+        try:
+            api = self.root_endpoint + ("/" if self.root_endpoint[-1] != "/" and api[0] != "/" else "") + api
+            payload["node_token"] = self.node_token  # Adding token to let the server verify
+            response = requests.post(api,
+                                     json=payload,
+                                     headers={"Content-Type": "application/json"})
+
+            if response.status_code == 200:
+                ret = response.json()
+                if response_fields is not None:
+                    for field in response_fields:
+                        if field not in ret:
+                            raise GenException(f"Missing key '{field}' in the response to {api}: {ret}")
+            else:
+                raise GenException(f"Request {api} failed with status code {response.status_code}")
+        except Exception as e:
+            self.err(f"An error occurred while making the POST request: {e}")
+            raise GenException(f"An error occurred while making the POST request: {e}")
+
+        if ret['state']['code'] != "ok":
+            raise GenException("[" + api + "] " + ret['state']['message'])
+
+        return ret['data']
+
+    @staticmethod
+    def __analyze_code(file_in_memory):
+        """Analyzes a string of Python code for dangerous or unsafe functions and modules.
+
+        Args:
+            file_in_memory: The string of Python code to analyze.
+
+        Returns:
+            True if the code is considered safe, otherwise False.
+        """
+        dangerous_functions = {"eval", "exec", "compile", "system", "__import__", "input"}
+        dangerous_modules = {"subprocess"}
+
+        def is_suspicious(ast_node):
+
+            # Detect function calls
+            if isinstance(ast_node, ast.Call):
+                if isinstance(ast_node.func, ast.Name):
+                    return ast_node.func.id in dangerous_functions
+                elif isinstance(ast_node.func, ast.Attribute):
+                    return ast_node.func.attr in dangerous_functions
+
+            # Detect imports
+            if isinstance(ast_node, (ast.Import, ast.ImportFrom)):
+                for alias in ast_node.names:
+                    if alias.name.split('.')[0] in dangerous_modules:
+                        return True
+
+            return False
+
+        try:
+            tree = ast.parse(file_in_memory)
+        except SyntaxError:
+            return False
+
+        for _ast_node in ast.walk(tree):
+            if is_suspicious(_ast_node):
+                return False
+
+        return True
+
+    def __handle_inspector_command(self, cmd: str, arg):
+        """Handles commands received from an inspector node.
+
+        Args:
+            cmd: The command string.
+            arg: The argument for the command.
+        """
+        self.out(f"Handling inspector message {cmd}, with arg {arg}")
+        print(f"Handling inspector message {cmd}, with arg {arg}")
+
+        if arg is not None and not isinstance(arg, str):
+            self.err(f"Expecting a string argument from the inspector!")
+        else:
+            if cmd == "ask_to_join_world":
+                print(f"Inspector asked to join world: {arg}")
+                self.ask_to_join_world(node_name=arg)
+            elif cmd == "ask_to_get_in_touch":
+                print(f"Inspector asked to get in touch with an agent: {arg}")
+                self.ask_to_get_in_touch(node_name=arg, public=True)
+            elif cmd == "leave":
+                print(f"Inspector asked to leave an agent: {arg}")
+                self.leave(arg)
+            elif cmd == "leave_world":
+                print(f"Inspector asked to leave the current world")
+                self.leave_world()
+            elif cmd == "pause":
+                print("Inspector asked to pause")
+                self.__inspector_told_to_pause = True
+            elif cmd == "play":
+                print("Inspector asked to play")
+                self.__inspector_told_to_pause = False
+            elif cmd == "save":
+                print("Inspector asked to save")
+                self.hosted.save(arg)
+            else:
+                self.err("Unknown inspector command")
+
+    def __send_to_inspector(self):
+        """Sends status updates and data to the connected inspector node."""
+
+        # Collecting console
+        f = self._output_messages_last_pos - self._output_messages_count + 1  # Included
+        t = self._output_messages_last_pos  # Included
+        ff = -1
+        tt = -1
+        if t >= 0 > f:  # If there is something, and we incurred in the circular organization (t: valid; f: negative)
+            ff = len(self._output_messages) + f  # Included
+            tt = len(self._output_messages) - 1  # Included
+            f = 0
+        elif t < 0:  # If there are no messages at all (t: -1; f: 0 - due to the way we initialized class attributes)
+            f = -1
+            t = -1
+        console = {'output_messages': self._output_messages[ff:tt+1] + self._output_messages[f:t+1]}
+
+        # Collecting the HSM
+        if self.__inspector_cache['behav'] != self.hosted.behav:
+            self.__inspector_cache['behav'] = self.hosted.behav
+            behav = str(self.hosted.behav)
+        else:
+            behav = None
+
+        # Collecting status of the HSM
+        if self.hosted.behav is not None:
+            _behav = self.hosted.behav
+            state = _behav.get_state().id if _behav.get_state() is not None else None
+            action = _behav.get_action().id if _behav.get_action() is not None else None
+            behav_status = {'state': state, 'action': action,
+                            'state_with_action': _behav.get_state().has_action()
+                            if (state is not None) else False}
+        else:
+            behav_status = None
+
+        # Collecting known agents
+        if self.__inspector_cache['all_agents_count'] != len(self.hosted.all_agents):
+            self.__inspector_cache['all_agents_count'] = len(self.hosted.all_agents)
+            all_agents_profiles = {k: v.get_all_profile() for k, v in self.hosted.all_agents.items()}
+
+            # Inspector expects also to have access to the profile of the world,
+            # so we patch this thing by adding it here
+            if self.hosted.in_world() and self.conn.world_node_peer_id is not None:
+                all_agents_profiles[self.conn.world_node_peer_id] = self.hosted.world_profile.get_all_profile()
+        else:
+            all_agents_profiles = None
+
+        # Collecting known streams info
+        if self.__inspector_cache['known_streams_count'] != len(self.hosted.known_streams):
+            self.__inspector_cache['known_streams_count'] = len(self.hosted.known_streams)
+            known_streams_props = {(k + "-" + name): v.get_props().to_dict() for k, stream_dict in
+                                   self.hosted.known_streams.items() for name, v in stream_dict.items()}
+        else:
+            known_streams_props = None
+
+        # Packing console, HSM status, and possibly HSM
+        console_behav_status_and_behav = {'console': console,
+                                          'behav': behav,
+                                          'behav_status': behav_status,
+                                          'all_agents_profiles': all_agents_profiles,
+                                          'known_streams_props': known_streams_props}
+
+        # Sending console, HSM status, and possibly HSM to the inspector
+        if not self.conn.send(self.inspector_peer_id, channel_trail=None,
+                              content_type=Msg.CONSOLE_AND_BEHAV_STATUS,
+                              content=console_behav_status_and_behav):
+            self.err("Failed to send data to the inspector")
+
+        # Sending stream data (not pubsub) to the inspector
+        my_peer_ids = (self.get_public_peer_id(), self.get_world_peer_id())
+        for net_hash, streams_dict in self.hosted.known_streams.items():
+            peer_id = DataProps.peer_id_from_net_hash(net_hash)
+
+            # Preparing sample dict
+            something_to_send = False
+            content = {name: {} for name in streams_dict.keys()}
+            for name, stream in streams_dict.items():
+                data = stream.get(requested_by="__send_to_inspector")
+
+                if data is not None:
+                    something_to_send = True
+
+                self.hosted.deb(f"[__send_to_inspector] Preparing to send stream samples from {net_hash}, {name}")
+                content[(peer_id + "|" + name) if peer_id not in my_peer_ids else name] = \
+                    {'data': data, 'data_tag': stream.get_tag(), 'data_uuid': stream.get_uuid()}
+
+            # Checking if there is something valid in this group of streams to send to inspector
+            if not something_to_send:
+                self.hosted.deb(f"[__send_to_inspector] No stream samples to send to inspector for {net_hash}, "
+                                f"all internal streams returned None")
+                continue
+
+            self.hosted.deb(f"[__send_to_inspector] Sending samples of {net_hash} by direct message, to inspector")
+            name_or_group = DataProps.name_or_group_from_net_hash(net_hash)
+            if not self.conn.send(self.inspector_peer_id, channel_trail=name_or_group,
+                                  content_type=Msg.STREAM_SAMPLE, content=content):
+                self.err(f"Failed to send stream sample data to the inspector (hash: {net_hash})")
+
+
+class NodeSynchronizer:
+    DEBUG = True
+
+    def __init__(self):
+        """Initializes a new instance of the NodeSynchronizer class."""
+        self.nodes = []
+        self.agent_nodes = {}
+        self.world_node = None  # Added to allow get_console() to access the world node from server.py (synch only)
+        self.streams = {}
+        self.world = None
+        self.world_masters = set()
+        self.world_masters_node_ids = None
+        self.agent_name_to_profile = {}
+        self.clock = Clock()
+        self.synch_cycle = -1
+        self.synch_cycles = -1
+
+        # Visualization-related attributes
+        self.using_server = False
+        self.server_checkpoints = None
+        self.skip_clear_for = 0
+        self.step_event = None  # Event that triggers a new step (manipulated by the server)
+        self.wait_event = None  # Event that triggers a new "wait-for-step-event" case (manipulated by the server)
+        self.next_checkpoint = 0
+        self.server_checkpoints = None
+        self.gap = 0.  # Seconds
+
+    def add_node(self, node: Node):
+        """Adds a new node to the synchronizer.
+
+        Args:
+            node: The node to add.
+        """
+        self.nodes.append(node)
+
+        if node.node_type == Node.AGENT:
+            self.agent_nodes[node.agent.get_name()] = node
+            if self.world_masters_node_ids is not None:
+                if node.node_id in self.world_masters_node_ids:
+                    self.world_masters.add(node.agent.get_name())
+            self.agent_name_to_profile[node.agent.get_name()] = node.agent.get_profile()
+        elif node.node_type == Node.WORLD:
+            self.world_node = node
+            self.world = node.world
+            self.world_masters_node_ids = node.world_masters_node_ids
+            if self.world_masters_node_ids is None:
+                self.world_masters_node_ids = set()
+            for node in self.nodes:
+                if node.node_id in self.world_masters_node_ids:
+                    self.world_masters.add(node.agent.get_name())
+        node.debug_server_running = True
+
+    def run(self, synch_cycles: int | None = None):
+        """Starts the main execution loop for the node.
+
+        Args:
+            synch_cycles: The number of clock cycles to run the loop for. If None, runs indefinitely.
+        """
+        if self.world is None:
+            raise GenException("Missing world node")
+
+        # External events
+        if self.using_server:
+            self.step_event = threading.Event()
+            self.wait_event = threading.Event()
+
+        # Main loop
+        self.synch_cycles = synch_cycles
+        self.synch_cycle = 0
+
+        try:
+            while True:
+
+                # In server mode, we wait for an external event to go ahead (step_event.set())
+                if self.using_server:
+                    self.wait_event.set()
+                    self.step_event.wait()
+                    self.wait_event.clear()
+
+                state_changed = False
+                world_node = None
+                for node in self.nodes:
+                    if node.node_type == Node.AGENT:
+                        node.run(cycles=1)
+                        if self.gap > 0.:
+                            time.sleep(self.gap)
+                        state_changed = state_changed or node.agent.behav.get_state_changed()
+                    else:
+                        world_node = node
+                if world_node is not None:
+                    world_node.run(cycles=1)
+                    if self.gap > 0.:
+                        time.sleep(self.gap)
+
+                if NodeSynchronizer.DEBUG and state_changed:
+                    for node in self.nodes:
+                        if node.node_type == Node.AGENT:
+                            print(f"[DEBUG NODE SYNCHRONIZER] {node.agent.get_name()} "
+                                  f"state: {node.agent.behav.get_state_name()}")
+
+                # Matching checkpoints
+                if self.server_checkpoints is not None and self.server_checkpoints["current"] >= 0:
+                    self.server_checkpoints["matched"] = -1
+                    checkpoint = self.server_checkpoints["checkpoints"][self.server_checkpoints["current"]]
+                    agent = checkpoint["agent"]
+                    state = checkpoint["state"] if "state" in checkpoint else None
+
+                    if agent not in self.nodes:
+                        raise GenException(f"Unknown agent in the checkpoint list: {agent}")
+                    behav = self.nodes[agent].agent.behav
+                    if not (state is None or state in behav.states):
+                        raise GenException(f"Unknown state in the checkpoint list: {state}")
+
+                    if state is None or behav.state == state:
+                        if "skip" not in checkpoint:
+                            self.server_checkpoints["matched"] = self.server_checkpoints["current"]
+                            self.server_checkpoints["current"] += 1
+                            if self.server_checkpoints["current"] >= len(self.server_checkpoints["checkpoints"]):
+                                self.server_checkpoints["current"] = -1  # This means: no more checkpoints
+                        else:
+                            checkpoint["skip"] -= 1
+                            if checkpoint["skip"] <= 0:
+                                self.server_checkpoints["current"] += 1
+                                if self.server_checkpoints["current"] >= len(self.server_checkpoints["checkpoints"]):
+                                    self.server_checkpoints["current"] = -1  # This means: no more checkpoints
+
+                # In step mode, we clear the external event to be able to wait for a new one
+                if self.using_server:
+                    if self.skip_clear_for == 0:
+                        self.step_event.clear()
+                    elif self.skip_clear_for == -2:  # Infinite play
+                        pass
+                    elif self.skip_clear_for == -1:  # Play until next state
+                        if state_changed:
+                            self.step_event.clear()
+                    elif self.skip_clear_for == -3:  # Play until next checkpoint:
+                        if self.server_checkpoints["matched"] >= 0:
+                            self.step_event.clear()
+                    else:
+                        self.skip_clear_for -= 1
+
+                self.synch_cycle += 1
+
+                # Stop condition on the number of cycles
+                if self.synch_cycles is not None and self.synch_cycle == self.synch_cycles:
+                    break
+        except KeyboardInterrupt:
+            print("\nDetected Ctrl+C! Exiting gracefully...")