unaiverse 0.1.12__py3-none-any.whl

unaiverse/utils/sandbox.py

@@ -0,0 +1,292 @@
+"""
+       █████  █████ ██████   █████           █████ █████   █████ ██████████ ███████████    █████████  ██████████
+      ░░███  ░░███ ░░██████ ░░███           ░░███ ░░███   ░░███ ░░███░░░░░█░░███░░░░░███  ███░░░░░███░░███░░░░░█
+       ░███   ░███  ░███░███ ░███   ██████   ░███  ░███    ░███  ░███  █ ░  ░███    ░███ ░███    ░░░  ░███  █ ░ 
+       ░███   ░███  ░███░░███░███  ░░░░░███  ░███  ░███    ░███  ░██████    ░██████████  ░░█████████  ░██████   
+       ░███   ░███  ░███ ░░██████   ███████  ░███  ░░███   ███   ░███░░█    ░███░░░░░███  ░░░░░░░░███ ░███░░█   
+       ░███   ░███  ░███  ░░█████  ███░░███  ░███   ░░░█████░    ░███ ░   █ ░███    ░███  ███    ░███ ░███ ░   █
+       ░░████████   █████  ░░█████░░████████ █████    ░░███      ██████████ █████   █████░░█████████  ██████████
+        ░░░░░░░░   ░░░░░    ░░░░░  ░░░░░░░░ ░░░░░      ░░░      ░░░░░░░░░░ ░░░░░   ░░░░░  ░░░░░░░░░  ░░░░░░░░░░ 
+                 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 uuid
+import argparse
+import subprocess
+from pathlib import Path
+
+# Configuration
+DOCKER_IMAGE_NAME = "unaiverse-sandbox"
+CONTAINER_NAME_BASE = "unaiverse-sandbox-container"
+CONTAINER_NAME = f"{CONTAINER_NAME_BASE}-{uuid.uuid4().hex[:8]}"  # Append a short unique ID
+DOCKERFILE_CONTENT = """
+
+# Debian image, automatically guessed architecture
+FROM python:3.12-slim-bookworm
+
+# Installing Go compiler
+RUN apt-get update && apt-get install -y --no-install-recommends build-essential curl git
+RUN rm -rf /var/lib/apt/lists/*
+RUN ARCH=$(dpkg --print-architecture) && curl -LO https://go.dev/dl/go1.24.5.linux-${ARCH}.tar.gz
+RUN ARCH=$(dpkg --print-architecture) && tar -C /usr/local -xzf go1.24.5.linux-${ARCH}.tar.gz
+RUN ARCH=$(dpkg --print-architecture) && rm go1.24.5.linux-${ARCH}.tar.gz
+
+# Set Go environment variables
+ENV PATH="/usr/local/go/bin:${PATH}"
+ENV GOPATH="/go"
+RUN mkdir -p /go/bin /go/src /go/pkg
+
+# Setting the working directory inside the container
+WORKDIR /unaiverse
+
+# Dependencies
+RUN <create_requirements.txt>
+RUN pip install --no-cache-dir -r requirements.txt --break-system-packages
+"""
+
+
+def sandbox(file_to_run: str,
+            read_only_paths: tuple[str] | list[str] | None = None,
+            writable_paths: tuple[str] | list[str] | None = None) -> None:
+
+    # Path of this file
+    absolute_path_of_this_file = os.path.abspath(__file__)
+
+    # Folders composing the path (and file name at the end)
+    path_components = list(Path(absolute_path_of_this_file).parts)
+
+    # Ensuring the folder/file structure was not manipulated
+    assert path_components[-1] == 'sandbox.py', "Major security issue, stopping."
+    assert path_components[-2] == 'utils', "Major security issue, stopping."
+    assert path_components[-3] == 'unaiverse', "Major security issue, stopping."
+
+    # Main folder of UNaIVERSE
+    abspath_of_unaiverse_code = str(Path(*path_components[0:-3]))
+
+    # Clean up any remnants from previous runs first (safety)
+    cleanup_docker_artifacts(where=abspath_of_unaiverse_code)
+
+    # Requirements
+    echoed_contents_of_requirements = 'printf "'
+    with open(os.path.join(abspath_of_unaiverse_code, "requirements.txt"), 'r') as req_file:
+        req_lines = req_file.readlines()
+    for i, req_line in enumerate(req_lines):
+        if i != (len(req_lines) - 1) and len(req_line.strip()) > 0:
+            echoed_contents_of_requirements += req_line.strip() + "\\n"
+        else:
+            echoed_contents_of_requirements += req_line.strip() + "\\n\" > requirements.txt"
+
+    # Create Dockerfile
+    print("Creating Dockerfile...")
+    with open(os.path.join(abspath_of_unaiverse_code, "Dockerfile"), "w") as f:
+        f.write(DOCKERFILE_CONTENT.replace('<create_requirements.txt>', echoed_contents_of_requirements))
+
+    # Building Docker image
+    if not build_docker_image(where=abspath_of_unaiverse_code):
+        print("Exiting due to Docker image build failure")
+        cleanup_docker_artifacts(where=abspath_of_unaiverse_code)  # Try to clean up what was created (if any)
+        sys.exit(1)
+
+    # Read only folders from the host machine
+    read_only_mount_paths = ([abspath_of_unaiverse_code] +
+                             (list(read_only_paths) if read_only_paths is not None else []))
+
+    # Writable folders in host machine
+    writable_mount_paths = ([os.path.join(abspath_of_unaiverse_code, 'runners'),
+                             os.path.join(abspath_of_unaiverse_code, 'unaiverse', 'library'),
+                             os.path.join(abspath_of_unaiverse_code, 'unaiverse', 'networking', 'p2p')] +
+                            (list(writable_paths) if writable_paths is not None else []))
+
+    # Running
+    if not run_in_docker(file_to_run=os.path.abspath(file_to_run),
+                         read_only_host_paths=read_only_mount_paths,
+                         writable_host_paths=writable_mount_paths):
+        print("Exiting due to Docker container run failure")
+        sys.exit(1)
+
+    # Final cleanup
+    cleanup_docker_artifacts(where=abspath_of_unaiverse_code)
+
+
+def build_docker_image(where: str):
+    """Builds the Docker image."""
+    print(f"Building Docker image '{DOCKER_IMAGE_NAME}'...")
+
+    try:
+
+        # The '.' at the end means build from the current directory
+        subprocess.run(["docker", "build", "-t", DOCKER_IMAGE_NAME, where], check=True)
+        print(f"Docker image '{DOCKER_IMAGE_NAME}' built successfully.")
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"Error building Docker image: {e}")
+        return False
+
+
+def cleanup_docker_artifacts(where: str):
+    """Cleans up the generated files and Docker image."""
+    print("Cleaning...")
+
+    # Stop and remove container if it's still running (e.g., if previous run failed)
+    try:
+        print(f"Attempting to stop and remove container '{CONTAINER_NAME}' (if running)...")
+        subprocess.run(["docker", "stop", CONTAINER_NAME],
+                       check=False, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        subprocess.run(["docker", "rm", CONTAINER_NAME],
+                       check=False, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    except Exception as e:
+        print(f"Error during preliminary container cleanup: {e}")
+
+    # Remove the Docker image
+    try:
+        print(f"Removing Docker image '{DOCKER_IMAGE_NAME}'...")
+        subprocess.run(["docker", "rmi", DOCKER_IMAGE_NAME], check=True)
+        print("Docker image removed.")
+    except subprocess.CalledProcessError as e:
+        print(f"Error removing Docker image '{DOCKER_IMAGE_NAME}': {e}")
+
+    # Remove the generated Dockerfile
+    if os.path.exists(os.path.join(where, "Dockerfile")):
+        os.remove(os.path.join(where, "Dockerfile"))
+        print("Removed Dockerfile.")
+
+
+def run_in_docker(file_to_run: str, read_only_host_paths: list[str] = None, writable_host_paths: list[str] = None):
+    """Runs the code in a Docker container with optional mounts."""
+    print(f"\nRunning code in Docker container '{CONTAINER_NAME}'...")
+
+    # Building command (it will continue below...)
+    command = ["docker", "run",
+               "--rm",  # Automatically remove the container when it exits
+               "-e", "PYTHONUNBUFFERED=1",  # Ensure Python output is unbuffered
+               "-e", "NODE_STARTING_PORT",
+               "--name", CONTAINER_NAME]
+
+    if sys.platform.startswith('linux'):
+
+        # Linux
+        command.extend(["--net", "host"]),  # Expose the host network (in macOS and Windows it is still a virtual host)
+    else:
+
+        # Not-linux: check ports (adding -p port:port)
+        port_int = int(os.getenv("NODE_STARTING_PORT", "0"))
+        if port_int > 0:
+            command.extend(["-p", str(port_int + 0) + ":" + str(port_int + 0)])
+            command.extend(["-p", str(port_int + 1) + ":" + str(port_int + 1) + "/udp"])
+            command.extend(["-p", str(port_int + 2) + ":" + str(port_int + 2)])
+            command.extend(["-p", str(port_int + 3) + ":" + str(port_int + 3) + "/udp"])
+
+    # Add read-only mount if path is provided
+    if read_only_host_paths is not None and len(read_only_host_paths) > 0:
+        for path in read_only_host_paths:
+
+            # Ensure the host path exists and is a directory
+            if not os.path.isdir(path):
+                print(
+                    f"Error: Read-only host path '{path}' does not exist or is not a directory. Cannot mount.")
+                return False
+            else:
+
+                # Augmenting command
+                path = os.path.abspath(path)
+                command.extend(["-v", f"{path}:{path}:ro"])
+                print(f"Mounted host '{path}' as read-only to container")
+
+    # Add writable mount if path is provided
+    if writable_host_paths is not None and len(writable_host_paths) > 0:
+        for path in writable_host_paths:
+
+            # Ensure the host path exists and is a directory
+            if not os.path.isdir(path):
+                print(
+                    f"Error: Writable host path '{path}' does not exist or is not a directory. Cannot mount.")
+                return False
+            else:
+
+                # Augmenting command
+                path = os.path.abspath(path)
+                command.extend(["-v", f"{path}:{path}"])
+                print(f"Mounted host '{path}' as writable to container")
+
+    # Completing command
+    command.append(DOCKER_IMAGE_NAME)
+
+    try:
+
+        # Running the prepared command... (using Popen to stream output in real-time)
+        try:
+            command.extend(["python3", file_to_run])
+            process = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+            for line in iter(process.stdout.readline, ''):
+                sys.stdout.write(line)
+            process.wait()  # Wait for the process to finish
+            if process.returncode != 0:
+                print(f"Container exited with non-zero status code: {process.returncode}")
+        except KeyboardInterrupt:
+            pass
+
+        print(f"\nContainer '{CONTAINER_NAME}' finished execution.")
+        return True
+    except FileNotFoundError:
+        print("Error: Docker command not found. Is Docker installed and in your PATH?")
+        print("Please ensure Docker is installed and running.")
+        return False
+    except subprocess.CalledProcessError as e:
+        print(f"Error running Docker container: {e}")
+        return False
+
+
+# Entry point
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Run a Python script adding customizable read-only and writable paths.",
+        formatter_class=argparse.RawTextHelpFormatter,
+        epilog="""
+    Examples:
+      python utils/sandbox.py my_script.py -r /home/user/data:/opt/app/data -p 1234
+      python utils/sandbox.py another_script.py -w /tmp/output:/mnt/results
+      python utils/sandbox.py script_with_both.py -r /input:/app/in -w /output:/app/out -p 8082
+    """)
+    parser.add_argument(help="Path to the Python script to execute.", dest="script_to_run",
+                        type=str)
+    parser.add_argument("-p", "--port", dest="port",
+                        help="The starting port of the node(s) (each node uses 4 ports, consecutive port numbers)",
+                        type=str, required=True)
+    parser.add_argument("-r", "--read-only", dest="read_only_folders",
+                        help="One or multiple paths to mount as read-only. "
+                             "Use a colon to separate multiple paths (e.g., /path/a:/path/b).",
+                        type=str, default=None)
+    parser.add_argument("-w", "--writable", dest="writable_folders",
+                        help="One or multiple paths to mount as writable. "
+                             "Use a colon to separate multiple paths (e.g., /path/c:/path/d).",
+                        type=str, default=None)
+    args = parser.parse_args()
+
+    if not args.script_to_run.endswith(".py"):
+        parser.error(f"The script '{args.script_to_run}' must be a Python file (e.g., ending with .py)")
+    script_to_run = args.script_to_run
+    if not int(args.port) > 0:
+        parser.error(f"Invalid port")
+
+    read_only_folders = None
+    if args.read_only_folders:
+        read_only_folders = args.read_only_folders.split(':')
+    writable_folders = None
+    if args.writable_folders:
+        writable_folders = args.writable_folders.split(':')
+
+    print("\n Running in sandbox...")
+    print(f"- Script to run: {script_to_run}")
+    print(f"- Starting port (+0, +1, +2, +3): {args.port}")
+    print(f"- Read only paths to mount (the UNaIVERSE code folder will be automatically mounted): {read_only_folders}")
+    print(f"- Writable paths to mount: {writable_folders}\n")
+
+    # Marking
+    os.environ["NODE_STARTING_PORT"] = args.port
+
+    # Running the sandbox and the script
+    sandbox(script_to_run, read_only_paths=read_only_folders, writable_paths=writable_folders)

unaiverse/world.py

@@ -0,0 +1,384 @@
+"""
+       █████  █████ ██████   █████           █████ █████   █████ ██████████ ███████████    █████████  ██████████
+      ░░███  ░░███ ░░██████ ░░███           ░░███ ░░███   ░░███ ░░███░░░░░█░░███░░░░░███  ███░░░░░███░░███░░░░░█
+       ░███   ░███  ░███░███ ░███   ██████   ░███  ░███    ░███  ░███  █ ░  ░███    ░███ ░███    ░░░  ░███  █ ░ 
+       ░███   ░███  ░███░░███░███  ░░░░░███  ░███  ░███    ░███  ░██████    ░██████████  ░░█████████  ░██████   
+       ░███   ░███  ░███ ░░██████   ███████  ░███  ░░███   ███   ░███░░█    ░███░░░░░███  ░░░░░░░░███ ░███░░█   
+       ░███   ░███  ░███  ░░█████  ███░░███  ░███   ░░░█████░    ░███ ░   █ ░███    ░███  ███    ░███ ░███ ░   █
+       ░░████████   █████  ░░█████░░████████ █████    ░░███      ██████████ █████   █████░░█████████  ██████████
+        ░░░░░░░░   ░░░░░    ░░░░░  ░░░░░░░░ ░░░░░      ░░░      ░░░░░░░░░░ ░░░░░   ░░░░░  ░░░░░░░░░  ░░░░░░░░░░ 
+                 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
+"""
+from unaiverse.stats import Stats
+from typing import List, Dict, Any
+from unaiverse.agent import AgentBasics
+from unaiverse.hsm import HybridStateMachine
+from unaiverse.networking.p2p.messages import Msg
+from unaiverse.networking.node.profile import NodeProfile
+
+
+class World(AgentBasics):
+
+    def __init__(self, world_folder: str, merge_flat_stream_labels: bool = False, stats: Stats | None = None):
+        """Initializes a World object, which acts as a special agent without a processor or behavior.
+
+        Args:
+            world_folder: The path of the world folder, with JSON files of the behaviors (per role) and agent.py.
+        """
+
+        # Creating a "special" agent with no processor and no behavior, but with a "world_folder", which is our world
+        super().__init__(proc=None, proc_inputs=None, proc_outputs=None, proc_opts=None, behav=None,
+                         world_folder=world_folder, merge_flat_stream_labels=merge_flat_stream_labels)
+
+        # Clearing processor (world must have no processor, and, maybe, a dummy processor was allocated when building
+        # the agent in the init call above)
+        self.proc = None
+        self.proc_inputs = []  # Do not set it to None
+        self.proc_outputs = []  # Do not set it to None
+        self.compat_in_streams = None
+        self.compat_out_streams = None
+
+        # Map from public peer IDs to private peer IDs
+        self.private_peer_of = {}
+        
+        # Stats
+        if stats is not None:
+            self.stats = stats
+        else:
+            # fallback to default Stats class
+            self.stats = Stats(is_world=True, db_path=f"{self.world_folder}/stats/world_stats.db",
+                               cache_window_hours=2.0)
+
+    def assign_role(self, profile: NodeProfile, is_world_master: bool) -> str:
+        """Assigns an initial role to a newly connected agent.
+
+        In this basic implementation, the role is determined based on whether the agent is a world master or a regular
+        world agent, ensuring there's only one master.
+
+        Args:
+            profile: The NodeProfile of the new agent.
+            is_world_master: A boolean indicating if the new agent is attempting to be a master.
+
+        Returns:
+            A string representing the assigned role.
+        """
+        assert self.is_world, "Assigning a role is expected to be done by the world"
+
+        if profile.get_dynamic_profile()['guessed_location'] == 'Some Dummy Location, Just An Example Here':
+            pass
+
+        # Currently, roles are only world masters and world agents
+        if is_world_master:
+            if len(self.world_masters) <= 1:
+                return AgentBasics.ROLE_BITS_TO_STR[AgentBasics.ROLE_WORLD_MASTER]
+            else:
+                return AgentBasics.ROLE_BITS_TO_STR[AgentBasics.ROLE_WORLD_AGENT]
+        else:
+            return AgentBasics.ROLE_BITS_TO_STR[AgentBasics.ROLE_WORLD_AGENT]
+
+    async def set_role(self, peer_id: str, role: int):
+        """Sets a new role for a specific agent and broadcasts this change to the agent (async).
+
+        It computes the new role and sends a message containing the new role and the corresponding default behavior
+        for that role.
+
+        Args:
+            peer_id: The ID of the agent whose role is to be set.
+            role: The new role to be assigned (as an integer).
+        """
+        assert self.is_world, "Setting the role is expected to be done by the world, which will broadcast such info"
+
+        # Computing new role (keeping the first two bits as before)
+        cur_role = self._node_conn.get_role(peer_id)
+        new_role_without_base_int = (role >> 2) << 2
+        new_role = (cur_role & 3) | new_role_without_base_int
+
+        if new_role != role:
+            self._node_conn.set_role(peer_id, new_role)
+            self.out("Telling an agent that his role changed")
+            if not (await self._node_conn.send(peer_id, channel_trail=None,
+                                               content={'peer_id': peer_id, 'role': new_role,
+                                                        'default_behav':
+                                                            self.role_to_behav[
+                                                                self.ROLE_BITS_TO_STR[new_role_without_base_int]]
+                                                            if self.role_to_behav is not None else
+                                                            str(HybridStateMachine(None))},
+                                               content_type=Msg.ROLE_SUGGESTION)):
+                self.err("Failed to send role change, removing (disconnecting) " + peer_id)
+                await self._node_purge_fcn(peer_id)
+            else:
+                self.role_changed_by_world = True
+
+    def set_addresses_in_profile(self, peer_id, addresses):
+        """Updates the network addresses in an agent's profile.
+
+        Args:
+            peer_id: The ID of the agent whose profile is being updated.
+            addresses: A list of new addresses to set.
+        """
+        if peer_id in self.all_agents:
+            profile = self.all_agents[peer_id]
+            addrs = profile.get_dynamic_profile()['private_peer_addresses']
+            addrs.clear()  # Warning: do not allocate a new list, keep the current one (it is referenced by others)
+            for _addrs in addresses:
+                addrs.append(_addrs)
+            self.received_address_update = True
+        else:
+            self.err(f"Cannot set addresses in profile, unknown peer_id {peer_id}")
+
+    def add_badge(self, peer_id: str, score: float, badge_type: str, agent_token: str,
+                  badge_description: str | None = None):
+        """Requests a badge for a specific agent, which can be used to track and reward agent performance.
+        It validates the score and badge type and stores the badge information in an internal dictionary.
+
+        Args:
+            peer_id: The ID of the agent for whom the badge is requested.
+            score: The score associated with the badge (must be in [0, 1]).
+            badge_type: The type of badge to be awarded.
+            agent_token: The token of the agent receiving the badge.
+            badge_description: An optional text description for the badge.
+        """
+
+        # Validate score
+        if score < 0. or score > 1.:
+            raise ValueError(f"Score must be in [0.0, 1.0], got {score}")
+
+        # Validate badge_type
+        if badge_type not in AgentBasics.BADGE_TYPES:
+            raise ValueError(f"Invalid badge_type '{badge_type}'. Must be one of {AgentBasics.BADGE_TYPES}.")
+
+        if badge_description is None:
+            badge_description = ""
+
+        # The world not necessarily knows the token of the agents, since they usually do not send messages to the world
+        badge = {
+            'agent_node_id': self.all_agents[peer_id].get_static_profile()['node_id'],
+            'agent_token': agent_token,
+            'badge_type': badge_type,
+            'score': score,
+            'badge_description': badge_description,
+            'last_edit_utc': self._node_clock.get_time_as_string(),
+        }
+
+        if peer_id not in self.agent_badges:
+            self.agent_badges[peer_id] = [badge]
+        else:
+            self.agent_badges[peer_id].append(badge)
+
+        # This will force the sending of the dynamic profile at the defined time instants
+        self._node_profile.mark_change_in_connections()
+
+    # Get all the badges requested by the world
+    def get_all_badges(self):
+        """Retrieves all badges that have been added to the world's record for all agents.
+        This provides a central log of achievements or performance metrics.
+
+        Returns:
+            A dictionary where keys are agent peer IDs and values are lists of badge dictionaries.
+        """
+        return self.agent_badges
+
+    def clear_badges(self):
+        """Clears all badge records from the world's memory.
+        This can be used to reset competition results or clean up state after a specific event.
+        """
+        self.agent_badges = {}
+
+    async def add_agent(self, peer_id: str, profile: NodeProfile) -> bool:
+        if await super().add_agent(peer_id, profile):
+            public_peer_id = profile.get_dynamic_profile()["peer_id"]
+            self.private_peer_of[public_peer_id] = peer_id
+            return True
+        else:
+            return False
+
+    async def remove_agent(self, peer_id: str):
+        profile = None
+        if peer_id in self.all_agents:
+            profile = self.all_agents[peer_id]
+        if await super().remove_agent(peer_id):
+            public_peer_id = profile.get_dynamic_profile()["peer_id"]
+            if public_peer_id in self.private_peer_of:
+                del self.private_peer_of[public_peer_id]
+            return True
+        else:
+            return False
+
+    def collect_and_store_own_stats(self):
+        """Collects this world's own stats and pushes them to the stats recorder."""
+        if self.stats is None:
+            return
+        
+        t = self._node_clock.get_time_ms()
+        _, own_private_pid = self.get_peer_ids()
+        
+        # Helper to add if value changed
+        def store_if_changed(stat_name, new_value):
+            last_value = self.stats.get_last_value(stat_name)
+            if last_value != new_value:
+                # Note: We pass the world's *own* peer_id for its *own* stats
+                self.stats.store_stat(stat_name, new_value, peer_id=own_private_pid, timestamp=t)
+        
+        try:
+            store_if_changed("world_masters", len(self.world_masters))
+            store_if_changed("world_agents", len(self.world_agents))
+            store_if_changed("human_agents", len(self.human_agents))
+            store_if_changed("artificial_agents", len(self.artificial_agents))
+        except Exception as e:
+            self.err(f"[Stats] Error updating own world stats: {e}")
+    
+    def _process_custom_stat(self, stat_name, value, peer_id, timestamp) -> bool:
+        """Hook for subclasses to intercept a stat. Return True if handled."""
+        return False
+    
+    def _extract_graph_node_info(self, peer_id: str) -> Dict[str, Any]:
+        """Helper to extract lightweight visualization data from NodeProfile."""
+
+        if peer_id == self.get_peer_ids()[1]:
+            # this is the world itself
+            profile = self._node_profile
+        else:
+            profile = self.all_agents.get(peer_id)
+        if profile is None:
+            return {}
+        
+        # Accessing the inner private dict of NodeProfile based on your class structure
+        static_profile = profile.get_static_profile()
+        dynamic_profile = profile.get_dynamic_profile()
+        
+        return {
+            'Name': static_profile.get('node_name', '~'),
+            'Owner': static_profile.get('email', '~'),
+            'Role': dynamic_profile.get('connections', {}).get('role', 'unknown').split('~')[-1],
+            'Type': static_profile.get('node_type', '~'),
+            'Number of Badges': len(dynamic_profile.get('cv', [])),
+            'Current Action': self.stats.get_last_value('action', peer_id=peer_id) or '~',
+            'Current State': self.stats.get_last_value('state', peer_id=peer_id) or '~',
+        }
+    
+    def _update_graph(self, peer_id: str, connected_peers_list: List[str], timestamp: int):
+        """Updates both graph connectivity (edges) and node metadata."""
+        
+        # 1. initialize structure if missing (e.g. first run or after DB load)
+        graph_stat = self.stats.get_stats().setdefault("graph", {'nodes': {}, 'edges': {}})
+            
+        nodes = graph_stat.setdefault('nodes', {})
+        edges = graph_stat.setdefault('edges', {})
+        
+        # 2. Update Node Metadata
+        # We update the sender's info
+        node_data = self._extract_graph_node_info(peer_id)
+        node_data['last_seen'] = timestamp
+        nodes[peer_id] = node_data
+
+        # We also ensure connected peers exist in 'nodes', even if we don't have their full profile yet
+        connected_peers = set(connected_peers_list)
+        for target_id in connected_peers:
+            if target_id not in nodes:
+                # Try to fetch profile if we have it, otherwise placeholder
+                nodes[target_id] = self._extract_graph_node_info(target_id)
+
+        # 3. Update Edges (Logic adapted from your previous code)
+        prev_connected_peers = edges.setdefault(peer_id, set())
+
+        # Add reverse connections (Undirected/Bidirectional logic)
+        for _peer_id in connected_peers:
+            edges.setdefault(_peer_id, set()).add(peer_id)
+        
+        # Remove dropped reverse connections
+        to_remove = prev_connected_peers - connected_peers
+        for _peer_id in to_remove:
+            if _peer_id in edges and peer_id in edges[_peer_id]:
+                edges[_peer_id].remove(peer_id)
+        
+        # Update peer's own forward connections
+        edges[peer_id] = connected_peers
+        
+        # 4. Store
+        world_peer_id = self.get_peer_ids()[1]
+        self.stats.store_stat('graph', graph_stat, peer_id=world_peer_id, timestamp=timestamp)
+    
+    def _prune_graph(self):
+        """Removes nodes that are no longer connected to the World."""
+        graph_stat = self.stats.get_stats().get("graph")
+        if not graph_stat:
+            return
+
+        nodes = graph_stat.get('nodes', {})
+        edges = graph_stat.get('edges', {})
+
+        # Get the active/inactive peers
+        active_peers = set(self.all_agents.keys())
+        # active_peers_in_world = set(self.world_agents.keys()) | set(self.world_masters.keys())
+        active_peers.add(self.get_peer_ids()[1])
+        current_graph_nodes = set(nodes.keys())
+        dead_peers = current_graph_nodes - active_peers
+
+        if not dead_peers:
+            return
+
+        # 2. Kill Zombies
+        for pid in dead_peers:
+            nodes.pop(pid, None)  # Nodes
+            edges.pop(pid, None)  # Outgoing edges
+
+            # Remove incoming edges
+            for other_pid in edges:
+                edges[other_pid].discard(pid)
+    
+    def add_peer_stats(self, peer_stats_batch: List[Dict[str, Any]], sender_peer_id: str | None = None):
+        """(World-only) Processes a batch of stats received from a peer."""
+        
+        # 1. Update own stats (this logic is now in the World)
+        self.collect_and_store_own_stats()
+
+        # 2. Process peer stats
+        connected_peers = []
+        for update in peer_stats_batch:
+            try:
+                p_id = update['peer_id']
+                if p_id != sender_peer_id:
+                    # TODO: decide if we want to filter the stats
+                    pass
+                stat_name = update['stat_name']
+                t = int(update['timestamp'])
+                v = update['value']
+                
+                # Call the hook (which also lives in the World now)
+                if self._process_custom_stat(stat_name, v, p_id, t):
+                    continue  # The custom processor handled it
+                
+                # Generate the graph and handle the connected_peers stat
+                if stat_name == 'connected_peers':
+                    # We need to wait for all the info to arrive before updating the graph.
+                    # Otherwise, _extract_graph_node_info may not find data yet.
+                    connected_peers.append((p_id, v, t))
+                    continue
+
+                # 3. Push to the "dumb" Stats recorder
+                if stat_name in self.stats.all_keys:
+                    self.stats.store_stat(stat_name, v, peer_id=p_id, timestamp=t)
+                else:
+                    self.err(f"[World] Unknown stat received: {stat_name}")
+
+            except Exception as e:
+                self.err(f"[World] Error processing stats update {update}: {e}")
+        
+        # Now update the graph for all collected connected_peers stats
+        for p_id, v, t in connected_peers:
+            self._update_graph(p_id, v, t)
+        
+        # Clean the graph from potentially stale peers
+        self._prune_graph()
+    
+    def debug_stats_dashboard(self):
+        """Helper to verify the dashboard looks correct during development."""
+        import plotly.io as pio
+        
+        print("[DEBUG] Rendering Dashboard...")
+        json_str = self.stats.plot()
+        if json_str:
+            pio.from_json(json_str).show()