flwr-nightly 1.19.0.dev20250515__py3-none-any.whl → 1.19.0.dev20250520__py3-none-any.whl

flwr/app/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Public Flower App APIs."""

flwr/app/error.py

@@ -0,0 +1,68 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Error."""
+
+
+from __future__ import annotations
+
+from typing import Optional, cast
+
+DEFAULT_TTL = 43200  # This is 12 hours
+MESSAGE_INIT_ERROR_MESSAGE = (
+    "Invalid arguments for Message. Expected one of the documented "
+    "signatures: Message(content: RecordDict, dst_node_id: int, message_type: str,"
+    " *, [ttl: float, group_id: str]) or Message(content: RecordDict | error: Error,"
+    " *, reply_to: Message, [ttl: float])."
+)
+
+
+class Error:
+    """The class storing information about an error that occurred.
+
+    Parameters
+    ----------
+    code : int
+        An identifier for the error.
+    reason : Optional[str]
+        A reason for why the error arose (e.g. an exception stack-trace)
+    """
+
+    def __init__(self, code: int, reason: str | None = None) -> None:
+        var_dict = {
+            "_code": code,
+            "_reason": reason,
+        }
+        self.__dict__.update(var_dict)
+
+    @property
+    def code(self) -> int:
+        """Error code."""
+        return cast(int, self.__dict__["_code"])
+
+    @property
+    def reason(self) -> str | None:
+        """Reason reported about the error."""
+        return cast(Optional[str], self.__dict__["_reason"])
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        view = ", ".join([f"{k.lstrip('_')}={v!r}" for k, v in self.__dict__.items()])
+        return f"{self.__class__.__qualname__}({view})"
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two instances of the class."""
+        if not isinstance(other, self.__class__):
+            raise NotImplementedError
+        return self.__dict__ == other.__dict__

flwr/app/metadata.py

@@ -0,0 +1,223 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Metadata."""
+
+
+from __future__ import annotations
+
+from typing import cast
+
+from ..common.constant import MessageType, MessageTypeLegacy
+
+
+class Metadata:  # pylint: disable=too-many-instance-attributes
+    """The class representing metadata associated with the current message.
+
+    Parameters
+    ----------
+    run_id : int
+        An identifier for the current run.
+    message_id : str
+        An identifier for the current message.
+    src_node_id : int
+        An identifier for the node sending this message.
+    dst_node_id : int
+        An identifier for the node receiving this message.
+    reply_to_message_id : str
+        An identifier for the message to which this message is a reply.
+    group_id : str
+        An identifier for grouping messages. In some settings,
+        this is used as the FL round.
+    created_at : float
+        Unix timestamp when the message was created.
+    ttl : float
+        Time-to-live for this message in seconds.
+    message_type : str
+        A string that encodes the action to be executed on
+        the receiving end.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments,too-many-positional-arguments
+        self,
+        run_id: int,
+        message_id: str,
+        src_node_id: int,
+        dst_node_id: int,
+        reply_to_message_id: str,
+        group_id: str,
+        created_at: float,
+        ttl: float,
+        message_type: str,
+    ) -> None:
+        var_dict = {
+            "_run_id": run_id,
+            "_message_id": message_id,
+            "_src_node_id": src_node_id,
+            "_dst_node_id": dst_node_id,
+            "_reply_to_message_id": reply_to_message_id,
+            "_group_id": group_id,
+            "_created_at": created_at,
+            "_ttl": ttl,
+            "_message_type": message_type,
+        }
+        self.__dict__.update(var_dict)
+        self.message_type = message_type  # Trigger validation
+
+    @property
+    def run_id(self) -> int:
+        """An identifier for the current run."""
+        return cast(int, self.__dict__["_run_id"])
+
+    @property
+    def message_id(self) -> str:
+        """An identifier for the current message."""
+        return cast(str, self.__dict__["_message_id"])
+
+    @property
+    def src_node_id(self) -> int:
+        """An identifier for the node sending this message."""
+        return cast(int, self.__dict__["_src_node_id"])
+
+    @property
+    def reply_to_message_id(self) -> str:
+        """An identifier for the message to which this message is a reply."""
+        return cast(str, self.__dict__["_reply_to_message_id"])
+
+    @property
+    def dst_node_id(self) -> int:
+        """An identifier for the node receiving this message."""
+        return cast(int, self.__dict__["_dst_node_id"])
+
+    @dst_node_id.setter
+    def dst_node_id(self, value: int) -> None:
+        """Set dst_node_id."""
+        self.__dict__["_dst_node_id"] = value
+
+    @property
+    def group_id(self) -> str:
+        """An identifier for grouping messages."""
+        return cast(str, self.__dict__["_group_id"])
+
+    @group_id.setter
+    def group_id(self, value: str) -> None:
+        """Set group_id."""
+        self.__dict__["_group_id"] = value
+
+    @property
+    def created_at(self) -> float:
+        """Unix timestamp when the message was created."""
+        return cast(float, self.__dict__["_created_at"])
+
+    @created_at.setter
+    def created_at(self, value: float) -> None:
+        """Set creation timestamp of this message."""
+        self.__dict__["_created_at"] = value
+
+    @property
+    def delivered_at(self) -> str:
+        """Unix timestamp when the message was delivered."""
+        return cast(str, self.__dict__["_delivered_at"])
+
+    @delivered_at.setter
+    def delivered_at(self, value: str) -> None:
+        """Set delivery timestamp of this message."""
+        self.__dict__["_delivered_at"] = value
+
+    @property
+    def ttl(self) -> float:
+        """Time-to-live for this message."""
+        return cast(float, self.__dict__["_ttl"])
+
+    @ttl.setter
+    def ttl(self, value: float) -> None:
+        """Set ttl."""
+        self.__dict__["_ttl"] = value
+
+    @property
+    def message_type(self) -> str:
+        """A string that encodes the action to be executed on the receiving end."""
+        return cast(str, self.__dict__["_message_type"])
+
+    @message_type.setter
+    def message_type(self, value: str) -> None:
+        """Set message_type."""
+        # Validate message type
+        if validate_legacy_message_type(value):
+            pass  # Backward compatibility for legacy message types
+        elif not validate_message_type(value):
+            raise ValueError(
+                f"Invalid message type: '{value}'. "
+                "Expected format: '<category>' or '<category>.<action>', "
+                "where <category> must be 'train', 'evaluate', or 'query', "
+                "and <action> must be a valid Python identifier."
+            )
+
+        self.__dict__["_message_type"] = value
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        view = ", ".join([f"{k.lstrip('_')}={v!r}" for k, v in self.__dict__.items()])
+        return f"{self.__class__.__qualname__}({view})"
+
+    def __eq__(self, other: object) -> bool:
+        """Compare two instances of the class."""
+        if not isinstance(other, self.__class__):
+            raise NotImplementedError
+        return self.__dict__ == other.__dict__
+
+
+def validate_message_type(message_type: str) -> bool:
+    """Validate if the message type is valid.
+
+    A valid message type format must be one of the following:
+
+    - "<category>"
+    - "<category>.<action>"
+
+    where `category` must be one of "train", "evaluate", or "query",
+    and `action` must be a valid Python identifier.
+    """
+    # Check if conforming to the format "<category>"
+    valid_types = {
+        MessageType.TRAIN,
+        MessageType.EVALUATE,
+        MessageType.QUERY,
+        MessageType.SYSTEM,
+    }
+    if message_type in valid_types:
+        return True
+
+    # Check if conforming to the format "<category>.<action>"
+    if message_type.count(".") != 1:
+        return False
+
+    category, action = message_type.split(".")
+    if category in valid_types and action.isidentifier():
+        return True
+
+    return False
+
+
+def validate_legacy_message_type(message_type: str) -> bool:
+    """Validate if the legacy message type is valid."""
+    # Backward compatibility for legacy message types
+    if message_type in (
+        MessageTypeLegacy.GET_PARAMETERS,
+        MessageTypeLegacy.GET_PROPERTIES,
+        "reconnect",
+    ):
+        return True
+
+    return False

flwr/client/app.py

@@ -30,6 +30,7 @@ import grpc
 from cryptography.hazmat.primitives.asymmetric import ec
 from grpc import RpcError
 
+from flwr.app.error import Error
 from flwr.cli.config_utils import get_fab_metadata
 from flwr.cli.install import install_from_fab
 from flwr.client.client import Client
@@ -57,7 +58,6 @@ from flwr.common.constant import (
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.grpc import generic_create_grpc_server
 from flwr.common.logger import log, warn_deprecated_feature
-from flwr.common.message import Error
 from flwr.common.retry_invoker import RetryInvoker, RetryState, exponential
 from flwr.common.typing import Fab, Run, RunNotRunningException, UserConfig
 from flwr.proto.clientappio_pb2_grpc import add_ClientAppIoServicer_to_server

flwr/client/client_app.py

@@ -20,6 +20,7 @@ from collections.abc import Iterator
 from contextlib import contextmanager
 from typing import Callable, Optional
 
+from flwr.app.metadata import validate_message_type
 from flwr.client.client import Client
 from flwr.client.message_handler.message_handler import (
     handle_legacy_message_from_msgtype,
@@ -28,7 +29,6 @@ from flwr.client.mod.utils import make_ffn
 from flwr.client.typing import ClientFnExt, Mod
 from flwr.common import Context, Message, MessageType
 from flwr.common.logger import warn_deprecated_feature
-from flwr.common.message import validate_message_type
 
 from .typing import ClientAppCallable
 

flwr/client/clientapp/app.py

@@ -23,6 +23,7 @@ from typing import Optional
 
 import grpc
 
+from flwr.app.error import Error
 from flwr.cli.install import install_from_fab
 from flwr.client.client_app import ClientApp, LoadClientAppError
 from flwr.common import Context, Message
@@ -32,7 +33,6 @@ from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS, ErrorCo
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.grpc import create_channel, on_channel_state_change
 from flwr.common.logger import log
-from flwr.common.message import Error
 from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
 from flwr.common.serde import (
     context_from_proto,

flwr/client/grpc_rere_client/connection.py

@@ -25,13 +25,14 @@ from typing import Callable, Optional, Union, cast
 import grpc
 from cryptography.hazmat.primitives.asymmetric import ec
 
+from flwr.app.metadata import Metadata
 from flwr.client.message_handler.message_handler import validate_out_message
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.constant import HEARTBEAT_CALL_TIMEOUT, HEARTBEAT_DEFAULT_INTERVAL
 from flwr.common.grpc import create_channel, on_channel_state_change
 from flwr.common.heartbeat import HeartbeatSender
 from flwr.common.logger import log
-from flwr.common.message import Message, Metadata
+from flwr.common.message import Message
 from flwr.common.retry_invoker import RetryInvoker
 from flwr.common.secure_aggregation.crypto.symmetric_encryption import (
     generate_key_pairs,

flwr/client/rest_client/connection.py

@@ -25,13 +25,14 @@ from cryptography.hazmat.primitives.asymmetric import ec
 from google.protobuf.message import Message as GrpcMessage
 from requests.exceptions import ConnectionError as RequestsConnectionError
 
+from flwr.app.metadata import Metadata
 from flwr.client.message_handler.message_handler import validate_out_message
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.constant import HEARTBEAT_DEFAULT_INTERVAL
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.heartbeat import HeartbeatSender
 from flwr.common.logger import log
-from flwr.common.message import Message, Metadata
+from flwr.common.message import Message
 from flwr.common.retry_invoker import RetryInvoker
 from flwr.common.serde import message_from_proto, message_to_proto, run_from_proto
 from flwr.common.typing import Fab, Run

flwr/clientapp/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Public Flower ClientApp APIs."""

flwr/common/__init__.py

@@ -15,6 +15,8 @@
 """Common components shared between server and client."""
 
 
+from ..app.error import Error as Error
+from ..app.metadata import Metadata as Metadata
 from .constant import MessageType as MessageType
 from .constant import MessageTypeLegacy as MessageTypeLegacy
 from .context import Context as Context
@@ -23,9 +25,7 @@ from .grpc import GRPC_MAX_MESSAGE_LENGTH
 from .logger import configure as configure
 from .logger import log as log
 from .message import DEFAULT_TTL
-from .message import Error as Error
 from .message import Message as Message
-from .message import Metadata as Metadata
 from .parameter import bytes_to_ndarray as bytes_to_ndarray
 from .parameter import ndarray_to_bytes as ndarray_to_bytes
 from .parameter import ndarrays_to_parameters as ndarrays_to_parameters

flwr/common/constant.py

@@ -130,7 +130,7 @@ GC_THRESHOLD = 200_000_000  # 200 MB
 
 # Constants for Inflatable
 HEAD_BODY_DIVIDER = b"\x00"
-TYPE_BODY_LEN_DIVIDER = " "
+HEAD_VALUE_DIVIDER = " "
 
 # Constants for serialization
 INT64_MAX_VALUE = 9223372036854775807  # (1 << 63) - 1

flwr/common/inflatable.py

@@ -20,9 +20,7 @@ from __future__ import annotations
 import hashlib
 from typing import TypeVar
 
-from .constant import HEAD_BODY_DIVIDER, TYPE_BODY_LEN_DIVIDER
-
-T = TypeVar("T", bound="InflatableObject")
+from .constant import HEAD_BODY_DIVIDER, HEAD_VALUE_DIVIDER
 
 
 class InflatableObject:
@@ -65,6 +63,9 @@ class InflatableObject:
         return None
 
 
+T = TypeVar("T", bound=InflatableObject)
+
+
 def get_object_id(object_content: bytes) -> str:
     """Return a SHA-256 hash of the (deflated) object content."""
     return hashlib.sha256(object_content).hexdigest()
@@ -84,13 +85,21 @@ def get_object_body(object_content: bytes, cls: type[T]) -> bytes:
     return _get_object_body(object_content)
 
 
-def add_header_to_object_body(object_body: bytes, cls: T) -> bytes:
+def add_header_to_object_body(object_body: bytes, obj: InflatableObject) -> bytes:
     """Add header to object content."""
     # Construct header
-    header = f"{cls.__class__.__qualname__}{TYPE_BODY_LEN_DIVIDER}{len(object_body)}"
-    enc_header = header.encode(encoding="utf-8")
+    header = f"%s{HEAD_VALUE_DIVIDER}%s{HEAD_VALUE_DIVIDER}%d" % (
+        obj.__class__.__qualname__,  # Type of object
+        ",".join((obj.children or {}).keys()),  # IDs of child objects
+        len(object_body),  # Length of object body
+    )
+
     # Concatenate header and object body
-    return enc_header + HEAD_BODY_DIVIDER + object_body
+    ret = bytearray()
+    ret.extend(header.encode(encoding="utf-8"))
+    ret.extend(HEAD_BODY_DIVIDER)
+    ret.extend(object_body)
+    return bytes(ret)
 
 
 def _get_object_head(object_content: bytes) -> bytes:
@@ -108,9 +117,14 @@ def get_object_type_from_object_content(object_content: bytes) -> str:
     return get_object_head_values_from_object_content(object_content)[0]
 
 
+def get_object_children_ids_from_object_content(object_content: bytes) -> list[str]:
+    """Return object children IDs from bytes."""
+    return get_object_head_values_from_object_content(object_content)[1]
+
+
 def get_object_body_len_from_object_content(object_content: bytes) -> int:
     """Return length of the object body."""
-    return get_object_head_values_from_object_content(object_content)[1]
+    return get_object_head_values_from_object_content(object_content)[2]
 
 
 def check_body_len_consistency(object_content: bytes) -> bool:
@@ -121,8 +135,23 @@ def check_body_len_consistency(object_content: bytes) -> bool:
 
 def get_object_head_values_from_object_content(
     object_content: bytes,
-) -> tuple[str, int]:
-    """Return object type and body length from object content."""
+) -> tuple[str, list[str], int]:
+    """Return object type and body length from object content.
+
+    Parameters
+    ----------
+    object_content : bytes
+        The deflated object content.
+
+    Returns
+    -------
+    tuple[str, list[str], int]
+        A tuple containing:
+        - The object type as a string.
+        - A list of child object IDs as strings.
+        - The length of the object body as an integer.
+    """
     head = _get_object_head(object_content).decode(encoding="utf-8")
-    obj_type, body_len = head.split(TYPE_BODY_LEN_DIVIDER, 1)
-    return obj_type, int(body_len)
+    obj_type, children_str, body_len = head.split(HEAD_VALUE_DIVIDER)
+    children_ids = children_str.split(",") if children_str else []
+    return obj_type, children_ids, int(body_len)

flwr/common/inflatable_grpc_utils.py

@@ -0,0 +1,97 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""InflatableObject utils."""
+
+
+from typing import Union
+
+from flwr.proto.fleet_pb2_grpc import FleetStub  # pylint: disable=E0611
+from flwr.proto.message_pb2 import (  # pylint: disable=E0611
+    PullObjectRequest,
+    PullObjectResponse,
+    PushObjectRequest,
+    PushObjectResponse,
+)
+from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub  # pylint: disable=E0611
+
+from .inflatable import (
+    InflatableObject,
+    get_object_head_values_from_object_content,
+    get_object_id,
+)
+from .record import Array, ArrayRecord, ConfigRecord, MetricRecord, RecordDict
+
+# Helper registry that maps names of classes to their type
+inflatable_class_registry: dict[str, type[InflatableObject]] = {
+    Array.__qualname__: Array,
+    ArrayRecord.__qualname__: ArrayRecord,
+    ConfigRecord.__qualname__: ConfigRecord,
+    MetricRecord.__qualname__: MetricRecord,
+    RecordDict.__qualname__: RecordDict,
+}
+
+
+def push_object_to_servicer(
+    obj: InflatableObject, stub: Union[FleetStub, ServerAppIoStub]
+) -> set[str]:
+    """Recursively deflate an object and push it to the servicer.
+
+    Objects with the same ID are not pushed twice. It returns the set of pushed object
+    IDs.
+    """
+    pushed_object_ids: set[str] = set()
+    # Push children if it has any
+    if children := obj.children:
+        for child in children.values():
+            pushed_object_ids |= push_object_to_servicer(child, stub)
+
+    # Deflate object and push
+    object_content = obj.deflate()
+    object_id = get_object_id(object_content)
+    _: PushObjectResponse = stub.PushObject(
+        PushObjectRequest(
+            object_id=object_id,
+            object_content=object_content,
+        )
+    )
+    pushed_object_ids.add(object_id)
+
+    return pushed_object_ids
+
+
+def pull_object_from_servicer(
+    object_id: str, stub: Union[FleetStub, ServerAppIoStub]
+) -> InflatableObject:
+    """Recursively inflate an object by pulling it from the servicer."""
+    # Pull object
+    object_proto: PullObjectResponse = stub.PullObject(
+        PullObjectRequest(object_id=object_id)
+    )
+    object_content = object_proto.object_content
+
+    # Extract object class and object_ids of children
+    obj_type, children_obj_ids, _ = get_object_head_values_from_object_content(
+        object_content=object_content
+    )
+    # Resolve object class
+    cls_type = inflatable_class_registry[obj_type]
+
+    # Pull all children objects
+    children: dict[str, InflatableObject] = {}
+    for child_object_id in children_obj_ids:
+        children[child_object_id] = pull_object_from_servicer(child_object_id, stub)
+
+    # Inflate object passing its children
+    return cls_type.inflate(object_content, children=children)