unaiverse 0.1.6__cp313-cp313-macosx_10_13_x86_64.whl

unaiverse/networking/p2p/lib.go.sha256

@@ -0,0 +1 @@
+9715da07770e39746f5889cc25ef308badd9a48e82cd5b15cb98cad24213da89

unaiverse/networking/p2p/lib_types.py

@@ -0,0 +1,312 @@
+"""
+       █████  █████ ██████   █████           █████ █████   █████ ██████████ ███████████    █████████  ██████████
+      ░░███  ░░███ ░░██████ ░░███           ░░███ ░░███   ░░███ ░░███░░░░░█░░███░░░░░███  ███░░░░░███░░███░░░░░█
+       ░███   ░███  ░███░███ ░███   ██████   ░███  ░███    ░███  ░███  █ ░  ░███    ░███ ░███    ░░░  ░███  █ ░ 
+       ░███   ░███  ░███░░███░███  ░░░░░███  ░███  ░███    ░███  ░██████    ░██████████  ░░█████████  ░██████   
+       ░███   ░███  ░███ ░░██████   ███████  ░███  ░░███   ███   ░███░░█    ░███░░░░░███  ░░░░░░░░███ ░███░░█   
+       ░███   ░███  ░███  ░░█████  ███░░███  ░███   ░░░█████░    ░███ ░   █ ░███    ░███  ███    ░███ ░███ ░   █
+       ░░████████   █████  ░░█████░░████████ █████    ░░███      ██████████ █████   █████░░█████████  ██████████
+        ░░░░░░░░   ░░░░░    ░░░░░  ░░░░░░░░ ░░░░░      ░░░      ░░░░░░░░░░ ░░░░░   ░░░░░  ░░░░░░░░░  ░░░░░░░░░░ 
+                 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 json
+import ctypes
+import logging
+from threading import Lock
+from typing import Optional, List, Any, TYPE_CHECKING
+
+from .golibp2p import GoLibP2P  # Assuming this class loads the library
+
+logger = logging.getLogger('LIB-TYPES')
+
+
+class TypeInterface:
+    """
+    Helper class for converting between Python types and Go types using ctypes.
+    """
+    def __init__(self, libp2p_instance: GoLibP2P):
+        self.__freed_pointers: set[int] = set()  # Track freed pointers to prevent double-free errors
+        self.__freed_pointers_lock: Any = Lock()  # A threading lock
+        self.libp2p: GoLibP2P = libp2p_instance  # Store the shared library object instance
+
+    def to_go_string(self, s: str) -> bytes:
+        """
+        Converts a Python string to a UTF-8 encoded Python 'bytes' object.
+
+        This 'bytes' object is suitable for direct use with ctypes when passing
+        to a C function expecting a 'char*' (ctypes.c_char_p), as ctypes
+        will automatically pass a pointer to the byte string's data.
+
+        Args:
+            s: The Python string.
+
+        Returns:
+            A Python 'bytes' object containing the UTF-8 encoded string.
+        """
+        if s is None:
+            s = ""
+        return s.encode("utf-8")
+
+    def from_go_string(self, cstr: bytes) -> str:
+        """
+        Converts a C char pointer (Go string) to a Python string.
+
+        Args:
+            cstr: The C char pointer.
+
+        Returns:
+            The decoded Python string.
+        """
+        if not cstr:
+            return ""
+        return cstr.decode("utf-8")
+
+    def to_go_int(self, i: int) -> ctypes.c_int:
+        """
+        Converts a Python integer to a Go-compatible ctypes integer.
+
+        Args:
+            i: The Python integer.
+
+        Returns:
+            A ctypes.c_int equivalent.
+        """
+        return ctypes.c_int(i)
+
+    def from_go_int(self, val: ctypes.c_int) -> int:
+        """
+        Converts a ctypes.c_int from Go to a Python integer.
+
+        Args:
+            val: The ctypes.c_int value.
+
+        Returns:
+            The corresponding Python integer.
+        """
+        return int(val)
+
+    def to_go_float(self, f: float) -> ctypes.c_float:
+        """
+        Converts a Python float to a Go-compatible ctypes float.
+
+        Args:
+            f: The Python float.
+
+        Returns:
+            A ctypes.c_float equivalent.
+        """
+        return ctypes.c_float(f)
+
+    def from_go_float(self, val: ctypes.c_float) -> float:
+        """
+        Converts a ctypes.c_float from Go to a Python float.
+
+        Args:
+            val: The ctypes.c_float value.
+
+        Returns:
+            The corresponding Python float.
+        """
+        return float(val)
+
+    def to_go_bool(self, b: bool) -> ctypes.c_int:
+        """
+        Converts a Python boolean to a Go-compatible integer (1 if True, 0 if False).
+
+        Args:
+            b: The Python boolean.
+
+        Returns:
+            A ctypes.c_int (1 or 0).
+        """
+        return ctypes.c_int(1 if b else 0)
+
+    def from_go_bool(self, val: ctypes.c_int) -> bool:
+        """
+        Converts a Go-compatible integer (ctypes.c_int) to a Python boolean.
+
+        Args:
+            val: The ctypes.c_int value.
+
+        Returns:
+            True if the value equals 1, False otherwise.
+        """
+        return val == 1
+
+    def to_go_bytes(self, b: bytes) -> ctypes.c_char_p:
+        """
+        Converts a Python bytes object to a Go-compatible C char pointer.
+
+        Args:
+            b: The Python bytes.
+
+        Returns:
+            A ctypes.c_char_p pointing to the byte data.
+        """
+        if b is None:
+            b = b""
+        buf = ctypes.create_string_buffer(b, len(b))
+        return ctypes.cast(buf, ctypes.c_char_p)
+
+    def from_go_bytes(self, cptr: ctypes.c_char_p, length: int) -> bytes:
+        """
+        Converts a Go pointer representing a byte array to a Python bytes object.
+
+        Args:
+            cptr: The C pointer to the byte array.
+            length: The number of bytes to read.
+
+        Returns:
+            A Python bytes object containing the read data.
+        """
+        if not cptr or length <= 0:
+            return bytes()
+        return ctypes.string_at(cptr, length)
+
+    def from_go_ptr_to_json(self, c_void_ptr_val: int) -> Any:
+        """
+        Converts a C void* pointer (returned by Go as int) pointing to a
+        null-terminated C string containing JSON into a Python object.
+
+        It reads the string, parses it as JSON, and crucially frees the C memory
+        using the provided FreeString function from the Go library.
+
+        Args:
+            c_void_ptr_val: The integer value representing the C pointer address.
+
+        Returns:
+            The parsed Python object from the JSON string.
+
+        Raises:
+            GoLibError: If the pointer is NULL, reading/decoding fails, or
+                        JSON parsing fails.
+            TypeError: When go_lib is not a valid ctypes library object.
+        """
+
+        json_string: Optional[str] = None  # To store the string for error reporting
+
+        if not c_void_ptr_val:  # Check if the address is NULL (0)
+            raise print("Received a NULL pointer from Go function")
+
+        try:
+
+            # --- Double-Free Check (Before Reading/Casting) ---
+            self.__freed_pointers_lock.acquire()  # Acquire lock if using threading
+            if c_void_ptr_val in self.__freed_pointers:
+
+                # This indicates a serious logic error elsewhere - the pointer
+                # was already freed but somehow passed here again.
+                logger.warning(f"🔥🔥🔥 ATTEMPT TO PROCESS ALREADY FREED POINTER {hex(c_void_ptr_val)}! 🔥🔥🔥")
+
+                # Raising an error is safer than trying to read potentially invalid memory.
+                logger.error(f"Attempt to process pointer {hex(c_void_ptr_val)} which was already freed",
+                             pointer_val=c_void_ptr_val)
+                raise Exception(f"Attempt to process pointer {hex(c_void_ptr_val)} which was already freed",
+                                pointer_val=c_void_ptr_val)
+            self.__freed_pointers_lock.release()  # Release lock if using threading
+
+            # --- Cast void* to c_char_p and Read String ---
+            try:
+
+                # Perform the cast only when needed for reading
+                c_char_ptr_for_read = ctypes.cast(c_void_ptr_val, ctypes.c_char_p)
+                raw_bytes = ctypes.string_at(c_char_ptr_for_read)
+                json_string = raw_bytes.decode('utf-8')
+
+                # Logger.debug(f"Read string (len={len(json_string)}) from pointer {hex(c_void_ptr_val)}: %.100s...", json_string)
+            except (ctypes.ArgumentError, ValueError, UnicodeDecodeError) as read_err:
+                logger.error(f"Failed to read/decode string from pointer {hex(c_void_ptr_val)}: {read_err}", exc_info=False)
+
+                # Even if reading fails, the pointer itself *might* still be valid C memory
+                # that Go expects us to free. We will proceed to free it in finally.
+                raise Exception(f"Failed to read string from pointer {hex(c_void_ptr_val)}: {read_err}",
+                                pointer_val=c_void_ptr_val) from read_err
+            except Exception as unexpected_read_err:  # Catch other potential ctypes issues
+                logger.error(f"Unexpected error reading C string from pointer {hex(c_void_ptr_val)}: {unexpected_read_err}", exc_info=True)
+                raise Exception(f"Unexpected error reading C string from pointer {hex(c_void_ptr_val)}: {unexpected_read_err}",
+                                pointer_val=c_void_ptr_val) from unexpected_read_err
+
+            # --- Check for Empty String ---
+
+            # --- Parse JSON ---
+            try:
+
+                # Now that we have the string, parse it
+                logger.debug(f"Parsing JSON from string: {json_string}")
+                parsed_data = json.loads(json_string)
+                logger.debug(f"Parsed JSON data: {parsed_data}")
+
+                # Logger.debug(f"Successfully parsed JSON from pointer {hex(c_void_ptr_val)}")
+                return parsed_data  # Return the parsed Python object
+
+            except json.JSONDecodeError as json_err:
+                logger.error(f"Failed to decode JSON from pointer {hex(c_void_ptr_val)}: {json_err}", exc_info=False)
+
+                # Again, the pointer is likely valid C memory, but the content is bad.
+                # Let the block handle freeing.
+                raise Exception(f"Failed to decode JSON from pointer {hex(c_void_ptr_val)}: {json_err}",
+                                pointer_val=c_void_ptr_val) from json_err
+
+        finally:
+
+            # --- CRITICAL: Free C Memory ---
+            # This block executes even if errors occurred during read/parse,
+            # ensuring we attempt to free any non-NULL pointer received from Go.
+            with self.__freed_pointers_lock:
+                if c_void_ptr_val:
+                    logger.info(f"🐍 FINALLY: Freeing pointer {hex(c_void_ptr_val)}...")
+                    if c_void_ptr_val in self.__freed_pointers:
+
+                        # This check is technically redundant if the initial check worked,
+                        # but provides an extra safety layer in case of concurrency issues
+                        # (if freed_pointers is shared without locks - which it shouldn't be).
+                        logger.warning(f"🔥🔥🔥 DOUBLE FREE DETECTED in finally block for {hex(c_void_ptr_val)}! Skipping FreeString call again. 🔥🔥🔥")
+                    else:
+
+                        # Add before calling free
+                        try:
+                            self.libp2p.FreeString(c_void_ptr_val)  # Pass the original void* value
+                            logger.info(f"✅ FINALLY: FreeString successful for {hex(c_void_ptr_val)}.")
+                        except Exception as free_err:
+
+                            # Log if FreeString fails, but don't raise from finally
+                            # as it might hide the original error.
+                            logger.critical(f"🚨 FAILED TO FREE C MEMORY for pointer {hex(c_void_ptr_val)} via FreeString: {free_err}", exc_info=True)
+
+                            # Consider removing from freed_pointers if free failed?
+                            # freed_pointers.discard(c_void_ptr_val) # Maybe, to allow retry? Risky.
+                            # But if FreeString fails, the pointer is likely invalid anyway.
+
+    def to_go_json(self, data: Any) -> bytes:
+        """
+    Encodes a Python object to a JSON string, returning a UTF-8 encoded
+    Python 'bytes' object.
+
+    This 'bytes' object is suitable for direct use with ctypes when passing
+    to a C function expecting a 'char*' (ctypes.c_char_p).
+
+    Args:
+        data: The Python object (e.g., dict, list) to encode.
+
+    Returns:
+        A Python 'bytes' object containing the JSON string, UTF-8 encoded.
+    """
+        json_str = json.dumps(data)
+        return self.to_go_string(json_str)
+
+    def from_go_string_to_list(self, cstr: ctypes.c_char_p) -> List[Any]:
+        """
+        Decodes a JSON-encoded list from a Go C char pointer into a Python list.
+
+        Args:
+            cstr: The Go string (C char pointer) containing a JSON list.
+
+        Returns:
+            A Python list representing the JSON data.
+        """
+        s = self.from_go_string(cstr)
+
+        return json.loads(s)

unaiverse/networking/p2p/message_pb2.py

@@ -0,0 +1,63 @@
+"""
+       █████  █████ ██████   █████           █████ █████   █████ ██████████ ███████████    █████████  ██████████
+      ░░███  ░░███ ░░██████ ░░███           ░░███ ░░███   ░░███ ░░███░░░░░█░░███░░░░░███  ███░░░░░███░░███░░░░░█
+       ░███   ░███  ░███░███ ░███   ██████   ░███  ░███    ░███  ░███  █ ░  ░███    ░███ ░███    ░░░  ░███  █ ░ 
+       ░███   ░███  ░███░░███░███  ░░░░░███  ░███  ░███    ░███  ░██████    ░██████████  ░░█████████  ░██████   
+       ░███   ░███  ░███ ░░██████   ███████  ░███  ░░███   ███   ░███░░█    ░███░░░░░███  ░░░░░░░░███ ░███░░█   
+       ░███   ░███  ░███  ░░█████  ███░░███  ░███   ░░░█████░    ░███ ░   █ ░███    ░███  ███    ░███ ░███ ░   █
+       ░░████████   █████  ░░█████░░████████ █████    ░░███      ██████████ █████   █████░░█████████  ██████████
+        ░░░░░░░░   ░░░░░    ░░░░░  ░░░░░░░░ ░░░░░      ░░░      ░░░░░░░░░░ ░░░░░   ░░░░░  ░░░░░░░░░  ░░░░░░░░░░ 
+                 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 google.protobuf import descriptor as _descriptor
+from google.protobuf.internal import builder as _builder
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'message.proto'
+)
+
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\rmessage.proto\x12\x03p2p\"\xc0\x01\n\x07Message\x12\x0e\n\x06sender\x18\x01 \x01(\t\x12\x14\n\x0c\x63ontent_type\x18\x02 \x01(\t\x12\x0f\n\x07\x63hannel\x18\x03 \x01(\t\x12\x11\n\tpiggyback\x18\x04 \x01(\t\x12\x15\n\rtimestamp_net\x18\x05 \x01(\t\x12\x31\n\rstream_sample\x18\x06 \x01(\x0b\x32\x18.p2p.StreamSampleContentH\x00\x12\x16\n\x0cjson_content\x18\x07 \x01(\tH\x00\x42\t\n\x07\x63ontent\"\x90\x01\n\x13StreamSampleContent\x12\x36\n\x07samples\x18\x01 \x03(\x0b\x32%.p2p.StreamSampleContent.SamplesEntry\x1a\x41\n\x0cSamplesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12 \n\x05value\x18\x02 \x01(\x0b\x32\x11.p2p.StreamSample:\x02\x38\x01\"e\n\x0cStreamSample\x12\x1d\n\x04\x64\x61ta\x18\x01 \x01(\x0b\x32\x0f.p2p.SampleData\x12\x10\n\x08\x64\x61ta_tag\x18\x02 \x01(\x05\x12\x16\n\tdata_uuid\x18\x03 \x01(\tH\x00\x88\x01\x01\x42\x0c\n\n_data_uuid\"\x8e\x01\n\nSampleData\x12&\n\x0btensor_data\x18\x01 \x01(\x0b\x32\x0f.p2p.TensorDataH\x00\x12$\n\nimage_data\x18\x02 \x01(\x0b\x32\x0e.p2p.ImageDataH\x00\x12\"\n\ttext_data\x18\x03 \x01(\x0b\x32\r.p2p.TextDataH\x00\x42\x0e\n\x0c\x64\x61ta_payload\"8\n\nTensorData\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\x12\r\n\x05\x64type\x18\x02 \x01(\t\x12\r\n\x05shape\x18\x03 \x03(\x05\"\x19\n\tImageData\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\"\x18\n\x08TextData\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\tB\x0cZ\n./proto-gob\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'message_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z\n./proto-go'
+  _globals['_STREAMSAMPLECONTENT_SAMPLESENTRY']._loaded_options = None
+  _globals['_STREAMSAMPLECONTENT_SAMPLESENTRY']._serialized_options = b'8\001'
+  _globals['_MESSAGE']._serialized_start=23
+  _globals['_MESSAGE']._serialized_end=215
+  _globals['_STREAMSAMPLECONTENT']._serialized_start=218
+  _globals['_STREAMSAMPLECONTENT']._serialized_end=362
+  _globals['_STREAMSAMPLECONTENT_SAMPLESENTRY']._serialized_start=297
+  _globals['_STREAMSAMPLECONTENT_SAMPLESENTRY']._serialized_end=362
+  _globals['_STREAMSAMPLE']._serialized_start=364
+  _globals['_STREAMSAMPLE']._serialized_end=465
+  _globals['_SAMPLEDATA']._serialized_start=468
+  _globals['_SAMPLEDATA']._serialized_end=610
+  _globals['_TENSORDATA']._serialized_start=612
+  _globals['_TENSORDATA']._serialized_end=668
+  _globals['_IMAGEDATA']._serialized_start=670
+  _globals['_IMAGEDATA']._serialized_end=695
+  _globals['_TEXTDATA']._serialized_start=697
+  _globals['_TEXTDATA']._serialized_end=721
+
+# @@protoc_insertion_point(module_scope)

unaiverse/networking/p2p/messages.py

@@ -0,0 +1,265 @@
+"""
+       █████  █████ ██████   █████           █████ █████   █████ ██████████ ███████████    █████████  ██████████
+      ░░███  ░░███ ░░██████ ░░███           ░░███ ░░███   ░░███ ░░███░░░░░█░░███░░░░░███  ███░░░░░███░░███░░░░░█
+       ░███   ░███  ░███░███ ░███   ██████   ░███  ░███    ░███  ░███  █ ░  ░███    ░███ ░███    ░░░  ░███  █ ░ 
+       ░███   ░███  ░███░░███░███  ░░░░░███  ░███  ░███    ░███  ░██████    ░██████████  ░░█████████  ░██████   
+       ░███   ░███  ░███ ░░██████   ███████  ░███  ░░███   ███   ░███░░█    ░███░░░░░███  ░░░░░░░░███ ░███░░█   
+       ░███   ░███  ░███  ░░█████  ███░░███  ░███   ░░░█████░    ░███ ░   █ ░███    ░███  ███    ░███ ░███ ░   █
+       ░░████████   █████  ░░█████░░████████ █████    ░░███      ██████████ █████   █████░░█████████  ██████████
+        ░░░░░░░░   ░░░░░    ░░░░░  ░░░░░░░░ ░░░░░      ░░░      ░░░░░░░░░░ ░░░░░   ░░░░░  ░░░░░░░░░  ░░░░░░░░░░ 
+                 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 io
+import gzip
+import json
+import torch
+from PIL import Image
+from datetime import datetime, timezone
+
+# Import the Protobuf-generated module
+try:
+    from . import message_pb2 as pb
+except ImportError:
+    print("Error: message_pb2.py not found. Please compile the .proto file first.")
+    raise
+
+
+class Msg:
+
+    # Message content types
+    PROFILE = "profile"
+    WORLD_APPROVAL = "world_approval"
+    AGENT_APPROVAL = "agent_approval"
+    PROFILE_REQUEST = "profile_request"
+    ADDRESS_UPDATE = "address_update"
+    STREAM_SAMPLE = "stream_sample"
+    ACTION_REQUEST = "action_request"
+    ROLE_SUGGESTION = "role_suggestion"
+    HSM = "hsm"
+    MISC = "misc"
+    GET_CV_FROM_ROOT = "get_cv_from_root"
+    BADGE_SUGGESTIONS = "badge_suggestions"
+    INSPECT_ON = "inspect_on"
+    INSPECT_CMD = "inspect_cmd"
+    WORLD_AGENTS_LIST = "world_agents_list"
+    CONSOLE_AND_BEHAV_STATUS = "console_and_behav_status"
+
+    # Collections
+    CONTENT_TYPES = {PROFILE, WORLD_APPROVAL, AGENT_APPROVAL, PROFILE_REQUEST, ADDRESS_UPDATE,
+                     STREAM_SAMPLE, ACTION_REQUEST, ROLE_SUGGESTION, HSM, MISC, GET_CV_FROM_ROOT,
+                     BADGE_SUGGESTIONS, INSPECT_ON, INSPECT_CMD, WORLD_AGENTS_LIST, CONSOLE_AND_BEHAV_STATUS}
+
+    def __init__(self,
+                 sender: str | None = None,
+                 content: any = None,
+                 timestamp_net: str | None = None,
+                 channel: str | None = None,
+                 content_type: str = MISC,
+                 piggyback: str | None = None,
+                 _proto_msg: pb.Message = None):
+        """The constructor should be used either to create a new message filling the fields,
+        or to parse an existing Protobuf message (passing _proto_msg). In the latter case,
+        the other fields are ignored and the Protobuf message is used as-is. The message is
+        simply stored in the internal `_proto_msg` field and other fields can be accessed
+        through properties."""
+
+        self._decoded_content: any = None  # Cache for decompressed content
+
+        if _proto_msg is not None:
+
+            # Check if any other arguments were simultaneously provided
+            other_args = [sender, content, timestamp_net, channel, piggyback]
+            if any(arg is not None for arg in other_args):
+                raise ValueError("Cannot specify other arguments when creating a Msg from a _proto_msg.")
+
+            # This path is used by from_bytes, message is already built
+            self._proto_msg = _proto_msg
+            return
+
+        # Sanity checks
+        assert sender is not None, "Sender must be specified for a new message."
+        assert isinstance(sender, str), "Sender must be a string"
+        assert timestamp_net is None or isinstance(timestamp_net, str), "Invalid timestamp_net"
+        assert channel is None or isinstance(channel, str), "Invalid channel"
+        assert content_type in Msg.CONTENT_TYPES, "Invalid content type"
+
+        # --- SMART CONSTRUCTOR: Populates the correct 'oneof' field ---
+        self._proto_msg = pb.Message()
+        self._proto_msg.sender = sender if sender is not None else ""
+        self._proto_msg.timestamp_net = timestamp_net if timestamp_net is not None else \
+            datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S.%f")
+        self._proto_msg.content_type = content_type if content_type is not None else self.MISC
+        self._proto_msg.channel = channel if channel is not None else "<unknown>"
+        self._proto_msg.piggyback = piggyback if piggyback is not None else ""
+
+        if content is None or content == "<empty>":
+            return  # Nothing to set in the 'oneof'
+
+        # Route the content to the correct builder
+        if content_type == Msg.STREAM_SAMPLE:
+            self._build_stream_sample_content(content)
+        else:
+
+            # All other structured types use the generic json_content field
+            self._build_json_content(content)
+
+    def __str__(self):
+        return (f"Msg(sender={self.sender[:12]}..., content_type={self.content_type}, "
+                f"channel='{self.channel}', content_len={len(self.to_bytes())} bytes)")
+
+    # --- Properties for lazy-loading and easy access ---
+    @property
+    def sender(self):
+        return self._proto_msg.sender
+
+    @sender.setter
+    def sender(self, value: str):
+        self._proto_msg.sender = value if value is not None else ""
+
+    @property
+    def content_type(self):
+        return self._proto_msg.content_type
+
+    @content_type.setter
+    def content_type(self, value: str):
+        self._proto_msg.content_type = value if value is not None else self.MISC
+
+    @property
+    def channel(self):
+        return self._proto_msg.channel
+
+    @channel.setter
+    def channel(self, value: str):
+        self._proto_msg.channel = value if value is not None else "<unknown>"
+
+    @property
+    def piggyback(self):
+        return self._proto_msg.piggyback
+
+    @piggyback.setter
+    def piggyback(self, value: str):
+        self._proto_msg.piggyback = value if value is not None else ""
+
+    @property
+    def timestamp_net(self):
+        return self._proto_msg.timestamp_net
+
+    @timestamp_net.setter
+    def timestamp_net(self, value: str):
+        self._proto_msg.timestamp_net = value if value is not None else ""
+
+
+    @property
+    def content(self) -> any:
+        """The main content of the message, decoded on-the-fly with caching."""
+        if self._decoded_content is not None:
+            return self._decoded_content
+
+        payload_type = self._proto_msg.WhichOneof("content")
+        if payload_type == "stream_sample":
+            self._decoded_content = self._parse_stream_sample_content()
+        elif payload_type == "json_content":
+            self._decoded_content = self._parse_json_content()
+        else:
+            self._decoded_content = "<empty>"
+
+        return self._decoded_content
+
+    # --- Serialization / Deserialization ---
+    def to_bytes(self) -> bytes:
+        """Serializes the internal Protobuf message to bytes."""
+        return self._proto_msg.SerializeToString()
+
+    @classmethod
+    def from_bytes(cls, msg_bytes: bytes) -> 'Msg':
+        """Deserializes a byte array into a new Msg instance."""
+        pb_msg = pb.Message()
+        pb_msg.ParseFromString(msg_bytes)
+
+        # Pass the parsed protobuf message to the constructor
+        return cls(_proto_msg=pb_msg)
+
+    # --- Internal Helper Methods ---
+    def _build_json_content(self, content: dict):
+        """Populates the generic json_content field."""
+        self._proto_msg.json_content = json.dumps(content)
+
+    def _parse_json_content(self) -> dict:
+        """Parses the generic json_content field back to a dict."""
+        return json.loads(self._proto_msg.json_content)
+
+    def _build_stream_sample_content(self, samples_dict: dict):
+        """Builds the complex StreamSampleContent message from a dict."""
+        content_pb = self._proto_msg.stream_sample
+        for name, sample_info in samples_dict.items():
+            data = sample_info.get('data')
+            if data is None:
+                continue
+
+            stream_sample_pb = content_pb.samples[name]
+            stream_sample_pb.data_tag = sample_info.get('data_tag', -1)
+            uuid = sample_info.get('data_uuid')
+
+            # Only set the field if the uuid is not None
+            if uuid is not None:
+                stream_sample_pb.data_uuid = uuid
+
+            if isinstance(data, torch.Tensor):
+                raw_bytes = data.detach().cpu().numpy().tobytes()
+                with io.BytesIO() as buffer:
+                    with gzip.GzipFile(fileobj=buffer, mode='wb') as f:
+                        f.write(raw_bytes)
+                    stream_sample_pb.data.tensor_data.data = buffer.getvalue()
+                stream_sample_pb.data.tensor_data.dtype = str(data.dtype).split('.')[-1]
+                stream_sample_pb.data.tensor_data.shape.extend(list(data.shape))
+
+            elif isinstance(data, Image.Image):
+                with io.BytesIO() as buffer:
+                    data.save(buffer, format="PNG", optimize=True, compress_level=9)
+                    stream_sample_pb.data.image_data.data = buffer.getvalue()
+
+            elif isinstance(data, str):
+                stream_sample_pb.data.text_data.data = data
+
+    def _parse_stream_sample_content(self) -> dict:
+        """
+        Parses the internal StreamSampleContent message back into a Python
+        dictionary of tensors and images.
+        """
+        py_dict = {}
+
+        # Iterate through the Protobuf map ('samples')
+        for name, sample_pb in self._proto_msg.stream_sample.samples.items():
+            data_payload = sample_pb.data
+            data = None
+
+            # Check which field in the 'oneof' is set
+            payload_type = data_payload.WhichOneof("data_payload")
+
+            if payload_type == "tensor_data":
+                tensor_data = data_payload.tensor_data
+
+                # Decompress and reconstruct the tensor
+                with gzip.GzipFile(fileobj=io.BytesIO(tensor_data.data), mode='rb') as f:
+                    raw_bytes = f.read()
+                data = torch.frombuffer(
+                    bytearray(raw_bytes),
+                    dtype=getattr(torch, tensor_data.dtype)
+                ).reshape(list(tensor_data.shape))
+
+            elif payload_type == "image_data":
+                data = Image.open(io.BytesIO(data_payload.image_data.data))
+
+            elif payload_type == "text_data":
+                data = data_payload.text_data.data
+
+            # Build the final Python dictionary for this sample
+            py_dict[name] = {
+                'data': data,
+                'data_tag': sample_pb.data_tag,
+                'data_uuid': sample_pb.data_uuid if sample_pb.HasField("data_uuid") else None
+            }
+        return py_dict