flwr-nightly 1.26.0.dev20260112__tar.gz → 1.26.0.dev20260113__tar.gz

{flwr_nightly-1.26.0.dev20260112 → flwr_nightly-1.26.0.dev20260113}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.26.0.dev20260112
+Version: 1.26.0.dev20260113
 Summary: Flower: A Friendly Federated AI Framework
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning
@@ -30,6 +30,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Provides-Extra: rest
 Provides-Extra: simulation
+Requires-Dist: SQLAlchemy (>=2.0.45,<3.0.0)
 Requires-Dist: click (<8.2.0)
 Requires-Dist: cryptography (>=44.0.1,<45.0.0)
 Requires-Dist: grpcio (>=1.70.0,<2.0.0)

{flwr_nightly-1.26.0.dev20260112 → flwr_nightly-1.26.0.dev20260113}/py/flwr/cli/app.py

@@ -23,7 +23,6 @@ from .app_cmd import publish as app_publish
 from .app_cmd import review as app_review
 from .build import build
 from .federation import ls as federation_list
-from .federation import show as federation_show
 from .install import install
 from .log import log
 from .login import login
@@ -35,6 +34,7 @@ from .stop import stop
 from .supernode import ls as supernode_list
 from .supernode import register as supernode_register
 from .supernode import unregister as supernode_unregister
+from .utils import init_flwr_config
 
 app = typer.Typer(
     help=typer.style(
@@ -80,14 +80,13 @@ federation_app.command("list")(federation_list)
 # Hide "ls" command (left as alias)
 federation_app.command(hidden=True)(federation_list)
 app.add_typer(federation_app, name="federation")
-federation_app.command()(federation_show)
 
 typer_click_object = get_command(app)
 
 
 @app.callback(invoke_without_command=True)
-def version_callback(
-    ver: bool = typer.Option(
+def main(
+    version: bool = typer.Option(
         None,
         "-V",
         "--version",
@@ -95,8 +94,9 @@ def version_callback(
         help="Show the version and exit.",
     ),
 ) -> None:
-    """Print version."""
-    if ver:
+    """Flower CLI."""
+    init_flwr_config()
+    if version:
         typer.secho(f"Flower version: {package_version}", fg="blue")
         raise typer.Exit()
 

{flwr_nightly-1.26.0.dev20260112 → flwr_nightly-1.26.0.dev20260113}/py/flwr/cli/federation/__init__.py

@@ -16,9 +16,7 @@
 
 
 from .ls import ls as ls
-from .show import show as show
 
 __all__ = [
     "ls",
-    "show",
 ]

flwr_nightly-1.26.0.dev20260112/py/flwr/cli/federation/show.py → flwr_nightly-1.26.0.dev20260113/py/flwr/cli/federation/ls.py

@@ -12,12 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower command line interface `federation show` command."""
+"""Flower command line interface `federation list` command."""
 
 
 import io
 from pathlib import Path
-from typing import Annotated, Any
+from typing import Annotated, Any, cast
 
 import typer
 from rich.console import Console
@@ -35,24 +35,27 @@ from flwr.common.constant import FAB_CONFIG_FILE, NOOP_ACCOUNT_NAME, CliOutputFo
 from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import run_from_proto
 from flwr.proto.control_pb2 import (  # pylint: disable=E0611
+    ListFederationsRequest,
+    ListFederationsResponse,
     ShowFederationRequest,
     ShowFederationResponse,
 )
 from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.proto.federation_pb2 import Federation  # pylint: disable=E0611
 from flwr.proto.node_pb2 import NodeInfo  # pylint: disable=E0611
-from flwr.supercore.constant import NOOP_FEDERATION
 from flwr.supercore.utils import humanize_duration
 
 from ..run_utils import RunRow, format_runs
 from ..utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
 
 
-def show(  # pylint: disable=R0914, R0913, R0917
+def ls(  # pylint: disable=R0914, R0913, R0917, R0912
+    ctx: typer.Context,
     app: Annotated[
         Path,
         typer.Argument(help="Path of the Flower project"),
     ] = Path("."),
-    federation: Annotated[
+    toml_federation: Annotated[
         str | None,
         typer.Argument(help="Name of the federation"),
     ] = None,
@@ -64,12 +67,19 @@ def show(  # pylint: disable=R0914, R0913, R0917
             help="Format output using 'default' view or 'json'",
         ),
     ] = CliOutputFormat.DEFAULT,
+    federation: Annotated[
+        str | None,
+        typer.Option(
+            "--federation",
+            case_sensitive=False,
+            help="Name of the federation to display",
+        ),
+    ] = None,
 ) -> None:
-    """Show details of a federation.
+    """List available federations."""
+    # Resolve command used (list or ls)
+    command_name = cast(str, ctx.command.name) if ctx.command else "ls"
 
-    Display comprehensive information about a federation including its members,
-    registered SuperNodes, and runs.
-    """
     suppress_output = output_format == CliOutputFormat.JSON
     captured_output = io.StringIO()
     try:
@@ -80,25 +90,41 @@ def show(  # pylint: disable=R0914, R0913, R0917
         pyproject_path = app / FAB_CONFIG_FILE if app else None
         config, errors, warnings = load_and_validate(pyproject_path, check_module=False)
         config = process_loaded_project_config(config, errors, warnings)
-        federation, federation_config = validate_federation_in_project_config(
-            federation, config
+        toml_federation_name, federation_config = validate_federation_in_project_config(
+            toml_federation, config
         )
-        exit_if_no_address(federation_config, "federation show")
-        real_federation: str = federation_config.get("federation", NOOP_FEDERATION)
+        exit_if_no_address(federation_config, f"federation {command_name}")
         channel = None
         try:
-            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
+            auth_plugin = load_cli_auth_plugin(
+                app, toml_federation_name, federation_config
+            )
             channel = init_channel(app, federation_config, auth_plugin)
             stub = ControlStub(channel)
-            typer.echo(f"📄 Showing '{real_federation}' federation ...")
-            members, nodes, runs = _show_federation(stub, real_federation)
-            restore_output()
-            if output_format == CliOutputFormat.JSON:
-                Console().print_json(data=_to_json(members, nodes, runs))
+
+            if federation:
+                # Show specific federation details
+                typer.echo(f"📄 Showing '{federation}' federation ...")
+                members, nodes, runs = _show_federation(stub, federation)
+
+                restore_output()
+                if output_format == CliOutputFormat.JSON:
+                    Console().print_json(
+                        data=_to_json(members=members, nodes=nodes, runs=runs)
+                    )
+                else:
+                    Console().print(_to_members_table(members))
+                    Console().print(_to_nodes_table(nodes))
+                    Console().print(_to_runs_table(runs))
             else:
-                Console().print(_to_members_table(members))
-                Console().print(_to_nodes_table(nodes))
-                Console().print(_to_runs_table(runs))
+                # List federations
+                typer.echo("📄 Listing federations...")
+                federations = _list_federations(stub)
+                restore_output()
+                if output_format == CliOutputFormat.JSON:
+                    Console().print_json(data=_to_json(federations=federations))
+                else:
+                    Console().print(_to_table(federations))
         finally:
             if channel:
                 channel.close()
@@ -120,6 +146,71 @@ def show(  # pylint: disable=R0914, R0913, R0917
         captured_output.close()
 
 
+def _list_federations(stub: ControlStub) -> list[Federation]:
+    """List all federations."""
+    with flwr_cli_grpc_exc_handler():
+        res: ListFederationsResponse = stub.ListFederations(ListFederationsRequest())
+
+    return list(res.federations)
+
+
+def _to_table(federations: list[Federation]) -> Table:
+    """Format the provided federations list to a rich Table."""
+    table = Table(header_style="bold cyan", show_lines=True)
+
+    # Add columns
+    table.add_column(
+        Text("Federation", justify="center"), style="bright_black", no_wrap=True
+    )
+
+    for federation in federations:
+        table.add_row(federation.name)
+
+    return table
+
+
+def _to_json(
+    federations: list[Federation] | None = None,
+    members: list[str] | None = None,
+    nodes: list[NodeInfo] | None = None,
+    runs: list[RunRow] | None = None,
+) -> list[dict[str, str]] | list[list[dict[str, Any]]]:
+    """Format the provided federations list to JSON serializable format."""
+    if federations is not None:
+        return [{"name": federation.name} for federation in federations]
+
+    if members is None or nodes is None or runs is None:
+        return []
+
+    members_list: list[dict[str, Any]] = []
+    nodes_list: list[dict[str, Any]] = []
+    runs_list: list[dict[str, Any]] = []
+
+    for member in members:
+        members_list.append({"member_id": member, "role": "Member"})
+
+    for node in nodes:
+        nodes_list.append(
+            {
+                "node_id": f"{node.node_id}",
+                "owner": node.owner_name,
+                "status": node.status,
+            }
+        )
+
+    for run in runs:
+        runs_list.append(
+            {
+                "run_id": f"{run.run_id}",
+                "app": f"@{run.fab_id}=={run.fab_version}",
+                "status": run.status_text,
+                "elapsed": run.elapsed,
+            }
+        )
+
+    return [members_list, nodes_list, runs_list]
+
+
 def _show_federation(
     stub: ControlStub, federation: str
 ) -> tuple[list[str], list[NodeInfo], list[RunRow]]:
@@ -268,51 +359,3 @@ def _to_runs_table(run_list: list[RunRow]) -> Table:
         table.add_row(*formatted_row)
 
     return table
-
-
-def _to_json(
-    members: list[str], nodes: list[NodeInfo], runs: list[RunRow]
-) -> list[list[dict[str, str]]]:
-    """Format the provided federation information to JSON serializable format.
-
-    Parameters
-    ----------
-    members : list[str]
-        List of member account identifiers.
-    nodes : list[NodeInfo]
-        List of NodeInfo objects.
-    runs : list[RunRow]
-        List of RunRow objects.
-
-    Returns
-    -------
-    list[list[dict[str, str]]]
-        Nested list containing dictionaries for members, nodes, and runs.
-    """
-    members_list: list[dict[str, Any]] = []
-    nodes_list: list[dict[str, Any]] = []
-    runs_list: list[dict[str, Any]] = []
-
-    for member in members:
-        members_list.append({"member_id": member, "role": "Member"})
-
-    for node in nodes:
-        nodes_list.append(
-            {
-                "node_id": f"{node.node_id}",
-                "owner": node.owner_name,
-                "status": node.status,
-            }
-        )
-
-    for run in runs:
-        runs_list.append(
-            {
-                "run_id": f"{run.run_id}",
-                "app": f"@{run.fab_id}=={run.fab_version}",
-                "status": run.status_text,
-                "elapsed": run.elapsed,
-            }
-        )
-
-    return [members_list, nodes_list, runs_list]

{flwr_nightly-1.26.0.dev20260112 → flwr_nightly-1.26.0.dev20260113}/py/flwr/cli/utils.py

@@ -48,8 +48,23 @@ from flwr.common.grpc import (
     create_channel,
     on_channel_state_change,
 )
-from flwr.supercore.constant import FLOWER_CONFIG_FILE, SuperLinkConnectionTomlKey
-from flwr.supercore.typing import SuperLinkConnection
+from flwr.supercore.constant import (
+    DEFAULT_FLOWER_CONFIG_TOML,
+    DEFAULT_SIMULATION_BACKEND_NAME,
+    FLOWER_CONFIG_FILE,
+    SimulationBackendConfigTomlKey,
+    SimulationClientResourcesTomlKey,
+    SimulationInitArgsTomlKey,
+    SuperLinkConnectionTomlKey,
+    SuperLinkSimulationOptionsTomlKey,
+)
+from flwr.supercore.typing import (
+    SimulationBackendConfig,
+    SimulationClientResources,
+    SimulationInitArgs,
+    SuperLinkConnection,
+    SuperLinkSimulationOptions,
+)
 from flwr.supercore.utils import get_flwr_home
 
 from .auth_plugin import CliAuthPlugin, get_cli_plugin_class
@@ -626,6 +641,74 @@ def validate_credentials_content(creds_path: Path) -> str:
     return creds[ACCESS_TOKEN_KEY]
 
 
+def _parse_simulation_options(options: dict[str, Any]) -> SuperLinkSimulationOptions:
+    """Parse simulation options from a dictionary in a SuperLink connection."""
+    num_supernodes = options.get(SuperLinkSimulationOptionsTomlKey.NUM_SUPERNODES)
+    # Validation handled in SuperLinkSimulationOptions.__post_init__
+
+    backend_dict = options.get(SuperLinkSimulationOptionsTomlKey.BACKEND)
+    simulation_backend: SimulationBackendConfig | None = None
+
+    if isinstance(backend_dict, dict):
+        # Parse client resources
+        client_resources_dict = backend_dict.get(
+            SimulationBackendConfigTomlKey.CLIENT_RESOURCES
+        )
+        client_resources: SimulationClientResources | None = None
+        if isinstance(client_resources_dict, dict):
+            client_resources = SimulationClientResources(
+                num_cpus=client_resources_dict.get(
+                    SimulationClientResourcesTomlKey.NUM_CPUS
+                ),
+                num_gpus=client_resources_dict.get(
+                    SimulationClientResourcesTomlKey.NUM_GPUS
+                ),
+            )
+
+        # Parse init args
+        init_args_dict = backend_dict.get(SimulationBackendConfigTomlKey.INIT_ARGS)
+        init_args: SimulationInitArgs | None = None
+        if isinstance(init_args_dict, dict):
+            init_args = SimulationInitArgs(
+                num_cpus=init_args_dict.get(SimulationInitArgsTomlKey.NUM_CPUS),
+                num_gpus=init_args_dict.get(SimulationInitArgsTomlKey.NUM_GPUS),
+                logging_level=init_args_dict.get(
+                    SimulationInitArgsTomlKey.LOGGING_LEVEL
+                ),
+                log_to_drive=init_args_dict.get(SimulationInitArgsTomlKey.LOG_TO_DRIVE),
+            )
+
+        simulation_backend = SimulationBackendConfig(
+            name=backend_dict.get(
+                SimulationBackendConfigTomlKey.NAME, DEFAULT_SIMULATION_BACKEND_NAME
+            ),
+            client_resources=client_resources,
+            init_args=init_args,
+        )
+
+    # Note: validation happens in SuperLinkSimulationOptions.__post_init__
+    return SuperLinkSimulationOptions(
+        num_supernodes=cast(int, num_supernodes),
+        backend=simulation_backend,
+    )
+
+
+def init_flwr_config() -> None:
+    """Initialize the Flower configuration file."""
+    config_path = get_flwr_home() / FLOWER_CONFIG_FILE
+
+    if not config_path.exists():
+        # Create parent directory if it doesn't exist
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        # Write Flower config file
+        config_path.write_text(DEFAULT_FLOWER_CONFIG_TOML, encoding="utf-8")
+
+        typer.secho(
+            f"\nFlower configuration not found. Created default configuration"
+            f" at {config_path}\n",
+        )
+
+
 def parse_superlink_connection(
     conn_dict: dict[str, Any], name: str
 ) -> SuperLinkConnection:
@@ -643,20 +726,31 @@ def parse_superlink_connection(
     SuperLinkConnection
         The parsed SuperLink connection configuration.
     """
-    # Check required fields
+    # Check fields
     address = conn_dict.get(SuperLinkConnectionTomlKey.ADDRESS)
     root_certificates = conn_dict.get(SuperLinkConnectionTomlKey.ROOT_CERTIFICATES)
     insecure = conn_dict.get(SuperLinkConnectionTomlKey.INSECURE)
     enable_account_auth = conn_dict.get(SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH)
-    if not (
+    options = conn_dict.get("options")
+
+    is_address_setup = (
         isinstance(address, str)
         # root-certificates is optional in TOML (can be missing)
         and isinstance(root_certificates, (str, type(None)))
         and isinstance(insecure, bool)
         and isinstance(enable_account_auth, bool)
-    ):
+    )
+
+    is_simulation_setup = isinstance(options, dict)
+
+    if not (is_address_setup or is_simulation_setup):
         raise ValueError("Invalid SuperLink connection format.")
 
+    simulation_options: SuperLinkSimulationOptions | None = None
+    if is_simulation_setup:
+        options = cast(dict[str, Any], options)
+        simulation_options = _parse_simulation_options(options)
+
     # Build and return SuperLinkConnection
     return SuperLinkConnection(
         name=name,
@@ -664,6 +758,7 @@ def parse_superlink_connection(
         root_certificates=root_certificates,
         insecure=insecure,
         enable_account_auth=enable_account_auth,
+        options=simulation_options,
     )
 
 

{flwr_nightly-1.26.0.dev20260112 → flwr_nightly-1.26.0.dev20260113}/py/flwr/supercore/constant.py

@@ -60,6 +60,9 @@ FORCE_EXIT_TIMEOUT_SECONDS = 5  # Used in `flwr_exit` function
 # Constants for message processing timing
 MESSAGE_TIME_ENTRY_MAX_AGE_SECONDS = 3600
 
+# Constants for simulations
+DEFAULT_SIMULATION_BACKEND_NAME = "ray"
+
 # System message type
 SYSTEM_MESSAGE_TYPE = "system"
 
@@ -77,10 +80,6 @@ class NodeStatus:
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
 
 
-# CLI connection configuration file name
-FLOWER_CONFIG_FILE = "config.toml"
-
-
 class SuperLinkConnectionTomlKey:
     """TOML keys for SuperLink connection configuration."""
 
@@ -90,3 +89,52 @@ class SuperLinkConnectionTomlKey:
     ROOT_CERTIFICATES = "root-certificates"
     INSECURE = "insecure"
     ENABLE_ACCOUNT_AUTH = "enable-account-auth"
+
+
+class SimulationClientResourcesTomlKey:
+    """TOML keys for SimulationClientResources."""
+
+    NUM_CPUS = "num-cpus"
+    NUM_GPUS = "num-gpus"
+
+
+class SimulationInitArgsTomlKey:
+    """TOML keys for SimulationInitArgs."""
+
+    NUM_CPUS = "num-cpus"
+    NUM_GPUS = "num-gpus"
+    LOGGING_LEVEL = "logging-level"
+    LOG_TO_DRIVE = "log-to-drive"
+
+
+class SimulationBackendConfigTomlKey:
+    """TOML keys for SimulationBackendConfig."""
+
+    CLIENT_RESOURCES = "client-resources"
+    INIT_ARGS = "init-args"
+    NAME = "name"
+
+
+class SuperLinkSimulationOptionsTomlKey:
+    """TOML keys for SuperLinkSimulationOptions."""
+
+    NUM_SUPERNODES = "num-supernodes"
+    BACKEND = "backend"
+
+
+# CLI connection configuration file name
+FLOWER_CONFIG_FILE = "config.toml"
+
+# The default configuration for the Flower config file
+DEFAULT_FLOWER_CONFIG_TOML = f"""[{SuperLinkConnectionTomlKey.SUPERLINK}]
+{SuperLinkConnectionTomlKey.DEFAULT} = "local-simulation"
+
+[{SuperLinkConnectionTomlKey.SUPERLINK}.supergrid]
+{SuperLinkConnectionTomlKey.ADDRESS} = "supergrid.flower.ai"
+{SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH} = true
+
+[{SuperLinkConnectionTomlKey.SUPERLINK}.local-simulation]
+options.num-supernodes = 10
+options.backend.client-resources.num-cpus = 1
+options.backend.client-resources.num-gpus = 0
+"""

flwr_nightly-1.26.0.dev20260113/py/flwr/supercore/typing.py

@@ -0,0 +1,97 @@
+# Copyright 2026 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.
+# ==============================================================================
+"""Flower type definitions for infrastructure."""
+
+
+from dataclasses import dataclass
+
+from flwr.supercore.constant import DEFAULT_SIMULATION_BACKEND_NAME
+
+
+@dataclass
+class SimulationClientResources:
+    """Resource configuration for the ClientApp."""
+
+    num_cpus: float | None = None
+    num_gpus: float | None = None
+
+    def __post_init__(self) -> None:
+        """Validate client resources configuration."""
+        if self.num_cpus is not None and not isinstance(self.num_cpus, (int, float)):
+            raise ValueError("client-resources.num-cpus must be a number (int/float).")
+        if self.num_gpus is not None and not isinstance(self.num_gpus, (int, float)):
+            raise ValueError("client-resources.num-gpus must be a number (int/float).")
+
+
+@dataclass
+class SimulationInitArgs:
+    """Initialization arguments for the simulation."""
+
+    num_cpus: int | None = None
+    num_gpus: int | None = None
+    logging_level: str | None = None
+    log_to_drive: bool | None = None
+
+    def __post_init__(self) -> None:
+        """Validate initialization arguments."""
+        if self.num_cpus is not None and not isinstance(self.num_cpus, int):
+            raise ValueError("init-args.num-cpus must be an integer.")
+        if self.num_gpus is not None and not isinstance(self.num_gpus, int):
+            raise ValueError("init-args.num-gpus must be an integer.")
+        if self.logging_level is not None and not isinstance(self.logging_level, str):
+            raise ValueError("init-args.logging-level must be a string.")
+        if self.log_to_drive is not None and not isinstance(self.log_to_drive, bool):
+            raise ValueError("init-args.log-to-drive must be a boolean.")
+
+
+@dataclass
+class SimulationBackendConfig:
+    """Backend configuration for the simulation."""
+
+    client_resources: SimulationClientResources | None = None
+    init_args: SimulationInitArgs | None = None
+    name: str = DEFAULT_SIMULATION_BACKEND_NAME
+
+    def __post_init__(self) -> None:
+        """Validate backend configuration."""
+        if not isinstance(self.name, str):
+            raise ValueError("backend.name must be a string.")
+
+
+@dataclass
+class SuperLinkSimulationOptions:
+    """Options for local simulation."""
+
+    num_supernodes: int
+    backend: SimulationBackendConfig | None = None
+
+    def __post_init__(self) -> None:
+        """Validate simulation options."""
+        if not isinstance(self.num_supernodes, int):
+            raise ValueError(
+                "Invalid simulation options: num-supernodes must be an integer."
+            )
+
+
+@dataclass
+class SuperLinkConnection:
+    """SuperLink connection configuration for CLI commands."""
+
+    name: str
+    address: str | None = None
+    root_certificates: str | None = None
+    insecure: bool | None = None
+    enable_account_auth: bool | None = None
+    options: SuperLinkSimulationOptions | None = None

{flwr_nightly-1.26.0.dev20260112 → flwr_nightly-1.26.0.dev20260113}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "flwr-nightly"
-version = "1.26.0.dev20260112"
+version = "1.26.0.dev20260113"
 description = "Flower: A Friendly Federated AI Framework"
 license = "Apache-2.0"
 authors = ["The Flower Authors <hello@flower.ai>"]
@@ -78,6 +78,7 @@ rich = "^13.5.0"
 pyyaml = "^6.0.2"
 requests = "^2.31.0"
 click = "<8.2.0"
+SQLAlchemy = "^2.0.45"
 # Optional dependencies (Simulation Engine)
 ray = [
     { version = "==2.51.1", optional = true, python = ">=3.10,<3.13" },