flwr-nightly 1.26.0.dev20260115__tar.gz → 1.26.0.dev20260116__tar.gz

{flwr_nightly-1.26.0.dev20260115 → flwr_nightly-1.26.0.dev20260116}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.26.0.dev20260115
+Version: 1.26.0.dev20260116
 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

flwr_nightly-1.26.0.dev20260116/py/flwr/cli/config_migration.py

@@ -0,0 +1,225 @@
+# 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.
+# ==============================================================================
+"""Utilities for migrating old TOML configurations to Flower config."""
+
+
+import re
+from pathlib import Path
+from typing import Any
+
+import click
+import typer
+
+from .config_utils import load_and_validate, validate_federation_in_project_config
+from .flower_config import (
+    init_flwr_config,
+    parse_superlink_connection,
+    set_default_superlink_connection,
+    write_superlink_connection,
+)
+
+CONFIG_MIGRATION_NOTICE = """
+##################################################################
+# CONFIGURATION MIGRATION NOTICE:
+#
+# What was previously called "federation config" for SuperLink
+# connections in pyproject.toml has been renamed and moved.
+#
+# These settings are now **SuperLink connection configuration**
+# and are defined in the Flower configuration file.
+#
+# The entries below are commented out intentionally and are kept
+# only as a migration reference.
+#
+# Docs: <link to Flower config docs>
+##################################################################
+
+"""
+
+CLI_NOTICE = (
+    typer.style("\n🌸 Heads up from Flower!\n\n", fg=typer.colors.MAGENTA, bold=True)
+    + "We detected legacy usage of this command that relies on connection\n"
+    + "settings from your pyproject.toml.\n\n"
+    + "Flower will migrate any relevant settings to the new Flower config.\n\n"
+    + "Learn more: https://flower.ai/docs\n"
+)
+
+
+def _is_legacy_usage(superlink: str, args: list[str]) -> bool:
+    """Check if legacy usage is detected in the given arguments."""
+    # If one and only one extra argument is given, assume legacy usage
+    if len(args) == 1:
+        return True
+
+    # If the `superlink` looks like a path, assume legacy usage
+    pth = Path(superlink)
+    if pth.is_absolute() or len(pth.parts) > 1 or superlink in (".", ".."):
+        return True
+
+    # Lastly, check if a pyproject.toml file exists at the given superlink
+    if (pth / "pyproject.toml").exists():
+        return True
+
+    return False
+
+
+def _check_is_migratable(app: Path) -> None:
+    """Check if the given app path contains legacy TOML configuration."""
+    toml_path = app / "pyproject.toml"
+    if not toml_path.exists():
+        raise FileNotFoundError(f"No pyproject.toml found in '{app}'")
+    config, errors, _ = load_and_validate(toml_path, check_module=False)
+    if config is None:
+        raise ValueError(f"Failed to load TOML configuration: {toml_path}")
+    if errors:
+        raise ValueError(
+            f"Invalid TOML configuration found in '{toml_path}':\n"
+            + "\n".join(f"- {err}" for err in errors)
+        )
+    try:
+        _ = config["tool"]["flwr"]["federations"]
+        return
+    except KeyError:
+        raise ValueError(
+            f"No '[tool.flwr.federations]' section found in '{toml_path}'"
+        ) from None
+
+
+def _migrate_pyproject_toml_to_flower_config(
+    app: Path, toml_federation: str | None
+) -> tuple[list[str], str | None]:
+    """Migrate old TOML configuration to Flower config."""
+    # Load and validate the old TOML configuration
+    toml_path = app / "pyproject.toml"
+    config, _, _ = load_and_validate(toml_path, check_module=False)
+    if config is None:
+        raise ValueError(f"Failed to load TOML configuration: {toml_path}")
+    validate_federation_in_project_config(toml_federation, config)
+
+    # Construct SuperLinkConnection
+    toml_federations: dict[str, Any] = config["tool"]["flwr"]["federations"]
+    migrated_conn_names: list[str] = []
+    for name, toml_fed_config in toml_federations.items():
+        if isinstance(toml_fed_config, dict):
+            # Resolve relative root-certificates path
+            if cert_path := toml_fed_config.get("root-certificates"):
+                if not Path(cert_path).is_absolute():
+                    toml_fed_config["root-certificates"] = str(
+                        (app / cert_path).resolve()
+                    )
+            # Parse and write SuperLink connection
+            conn = parse_superlink_connection(toml_fed_config, name)
+            write_superlink_connection(conn)
+            migrated_conn_names.append(name)
+
+    # Set default federation if applicable
+    default_toml_federation: str | None = toml_federations.get("default")
+    if default_toml_federation in toml_federations:
+        set_default_superlink_connection(default_toml_federation)
+
+    return migrated_conn_names, default_toml_federation
+
+
+def _comment_out_legacy_toml_config(app: Path) -> None:
+    """Comment out legacy TOML configuration in pyproject.toml."""
+    # Read pyproject.toml lines
+    toml_path = app / "pyproject.toml"
+    lines = toml_path.read_text(encoding="utf-8").splitlines(keepends=True)
+    section_pattern = re.compile(r"\s*\[(.*)\]")
+
+    # Comment out the [tool.flwr.federations] section
+    notice_added = False
+    in_federation_section = False
+    with toml_path.open("w", encoding="utf-8") as f:
+        for line in lines:
+            # Detect section headers
+            if match := section_pattern.match(line):
+                section = match.group(1)
+                in_federation_section = section.startswith("tool.flwr.federations")
+
+            # Comment out lines in the federation section
+            if in_federation_section:
+                if not notice_added:
+                    f.write(CONFIG_MIGRATION_NOTICE)
+                    notice_added = True
+                # Preserve empty lines and comment out others
+                f.write(f"# {line}" if line.strip() != "" else line)
+            else:
+                f.write(line)
+
+
+def migrate(
+    app: Path,
+    toml_federation: str | None,
+) -> None:
+    """Migrate legacy TOML configuration to Flower config."""
+    # Initialize Flower config
+    init_flwr_config()
+
+    # Print migration notice
+    typer.echo(CLI_NOTICE)
+
+    # Check if migration is applicable
+    app = app.resolve()
+    try:
+        _check_is_migratable(app)
+    except (FileNotFoundError, ValueError) as e:
+        raise click.ClickException(f"Cannot migrate configuration:\n{e}") from e
+
+    try:
+        migrated_conns, default_conn = _migrate_pyproject_toml_to_flower_config(
+            app, toml_federation
+        )
+    except Exception as e:
+        raise click.ClickException(
+            f"Failed to migrate legacy TOML configuration to Flower config:\n{e!r}"
+        ) from e
+
+    typer.secho("✅ Migration completed successfully!\n", fg=typer.colors.GREEN)
+
+    # Print migrated connections
+    typer.secho("Migrated SuperLink connections:", fg=typer.colors.BLUE)
+    for conn_name in migrated_conns:
+        typer.secho(f"  {conn_name}", fg=typer.colors.GREEN, nl=False)
+        if conn_name == default_conn:
+            typer.secho(" (default)", fg=typer.colors.WHITE, nl=False)
+        typer.echo()
+
+    # print usage
+    typer.secho("\nYou should now use the Flower CLI as follows:")
+    ctx = click.get_current_context()
+    typer.secho(ctx.get_usage() + "\n", bold=True)
+
+    _comment_out_legacy_toml_config(app)
+
+
+def migrate_if_legacy_usage(
+    superlink: str,
+    args: list[str],
+) -> None:
+    """Migrate legacy TOML configuration to Flower config if legacy usage is
+    detected."""
+    # Trigger the same typer error when detecting unexpected extra args
+    if len(args) > 1:
+        raise click.UsageError(f"Got unexpected extra arguments ({' '.join(args[1:])})")
+
+    # Skip migration if no legacy usage is detected
+    if not _is_legacy_usage(superlink, args):
+        return
+
+    migrate(
+        app=Path(superlink),
+        toml_federation=args[0] if len(args) == 1 else None,
+    )

{flwr_nightly-1.26.0.dev20260115 → flwr_nightly-1.26.0.dev20260116}/py/flwr/cli/config_utils.py

@@ -21,6 +21,7 @@ from typing import Any
 import tomli
 import typer
 
+from flwr.cli.typing import SuperLinkConnection
 from flwr.common.config import (
     fuse_dicts,
     get_fab_config,
@@ -283,6 +284,65 @@ def validate_certificate_in_federation_config(
     return insecure, root_certificates_bytes
 
 
+def load_certificate_in_connection(
+    connection: SuperLinkConnection,
+) -> bytes | None:
+    """Validate TLS-related settings and load root certificates if provided.
+
+    Parameters
+    ----------
+    connection : SuperLinkConnection
+        The SuperLink connection configuration.
+
+    Returns
+    -------
+    bytes | None
+        The loaded root certificate bytes if a custom certificate is configured.
+        None if TLS is disabled or if gRPC should use its default trust store.
+
+    Raises
+    ------
+    ValueError
+        If required TLS settings are missing.
+    typer.Exit
+        If the configuration is invalid or the certificate file cannot be read.
+    """
+    if connection.insecure is None:
+        raise ValueError(
+            f"SuperLink connection '{connection.name}' is missing insecure setting."
+        )
+
+    insecure = connection.insecure
+
+    # Process root certificates
+    if root_certificates := connection.root_certificates:
+        if insecure:
+            typer.secho(
+                "❌ `root-certificates` were provided but the `insecure` parameter "
+                "is set to `True`.",
+                fg=typer.colors.RED,
+                bold=True,
+                err=True,
+            )
+            raise typer.Exit(code=1)
+
+        # TLS is enabled with self-signed certificates: attempt to read the file
+        try:
+            root_certificates_bytes = Path(root_certificates).read_bytes()
+        except Exception as e:
+            typer.secho(
+                f"❌ Failed to read certificate file `{root_certificates}`: {e}",
+                fg=typer.colors.RED,
+                bold=True,
+                err=True,
+            )
+            raise typer.Exit(code=1) from e
+    else:
+        root_certificates_bytes = None
+
+    return root_certificates_bytes
+
+
 def exit_if_no_address(federation_config: dict[str, Any], cmd: str) -> None:
     """Exit if the provided federation_config has no "address" key.
 

{flwr_nightly-1.26.0.dev20260115 → flwr_nightly-1.26.0.dev20260116}/py/flwr/cli/flower_config.py

@@ -234,7 +234,7 @@ def serialize_superlink_connection(connection: SuperLinkConnection) -> dict[str,
 
 def read_superlink_connection(
     connection_name: str | None = None,
-) -> SuperLinkConnection | None:
+) -> SuperLinkConnection:
     """Read a SuperLink connection from the Flower configuration file.
 
     Parameters
@@ -245,9 +245,8 @@ def read_superlink_connection(
 
     Returns
     -------
-    SuperLinkConnection | None
-        The SuperLink connection, or None if the config file is missing or the
-        requested connection (or default) cannot be found.
+    SuperLinkConnection
+        The SuperLink connection.
 
     Raises
     ------
@@ -345,10 +344,29 @@ def write_superlink_connection(connection: SuperLinkConnection) -> None:
     # Add/update the connection
     superlink_config[connection.name] = conn_dict
 
-    # Flatten SuperLink connections
-    for name in list(superlink_config.keys()):
-        if isinstance(superlink_config[name], dict):
-            superlink_config[name] = flatten_dict(superlink_config[name])
+    # Write back to file
+    write_flower_config(toml_dict)
+
+
+def set_default_superlink_connection(connection_name: str) -> None:
+    """Set the default SuperLink connection."""
+    toml_dict, _ = read_flower_config()
+
+    # Get superlink section
+    superlink_config = toml_dict[SuperLinkConnectionTomlKey.SUPERLINK]
+
+    # Check if the connection exists
+    if connection_name not in superlink_config:
+        typer.secho(
+            f"❌ SuperLink connection '{connection_name}' not found in the Flower "
+            "configuration file. Cannot set as default.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Set default connection
+    superlink_config[SuperLinkConnectionTomlKey.DEFAULT] = connection_name
 
     # Write back to file
     write_flower_config(toml_dict)
@@ -402,6 +420,12 @@ def write_flower_config(toml_dict: dict[str, Any]) -> Path:
     """
     config_path = get_flwr_home() / FLOWER_CONFIG_FILE
 
+    # Flatten SuperLink connections
+    superlink_config: dict[str, Any] = toml_dict[SuperLinkConnectionTomlKey.SUPERLINK]
+    for name in list(superlink_config.keys()):
+        if isinstance(superlink_config[name], dict):
+            superlink_config[name] = flatten_dict(superlink_config[name])
+
     # Get the standard TOML text
     toml_content = tomli_w.dumps(toml_dict)
 

{flwr_nightly-1.26.0.dev20260115 → flwr_nightly-1.26.0.dev20260116}/py/flwr/cli/typing.py

@@ -16,6 +16,7 @@
 
 
 from dataclasses import dataclass
+from pathlib import Path
 
 from flwr.cli.constant import (
     DEFAULT_SIMULATION_BACKEND_NAME,
@@ -102,38 +103,46 @@ class SuperLinkConnection:
 
     def __post_init__(self) -> None:
         """Validate SuperLink connection configuration."""
+        err_prefix = f"Invalid value for key '%s' in connection '{self.name}': "
         if self.address is not None and not isinstance(self.address, str):
             raise ValueError(
-                f"Invalid value for key '{SuperLinkConnectionTomlKey.ADDRESS}': "
-                f"expected str, but got {type(self.address).__name__}."
+                err_prefix % SuperLinkConnectionTomlKey.ADDRESS
+                + f"expected str, but got {type(self.address).__name__}."
             )
         if self.root_certificates is not None and not isinstance(
             self.root_certificates, str
         ):
             raise ValueError(
-                "Invalid value for key "
-                f"'{SuperLinkConnectionTomlKey.ROOT_CERTIFICATES}': "
-                f"expected str, but got {type(self.root_certificates).__name__}."
+                err_prefix % SuperLinkConnectionTomlKey.ROOT_CERTIFICATES
+                + f"expected str, but got {type(self.root_certificates).__name__}."
             )
+
+        # Ensure root certificates path is absolute
+        if self.root_certificates is not None:
+            if not Path(self.root_certificates).is_absolute():
+                raise ValueError(
+                    err_prefix % SuperLinkConnectionTomlKey.ROOT_CERTIFICATES
+                    + "expected absolute path, but got relative path "
+                    f"'{self.root_certificates}'."
+                )
+
         if self.insecure is not None and not isinstance(self.insecure, bool):
             raise ValueError(
-                f"Invalid value for key '{SuperLinkConnectionTomlKey.INSECURE}': "
-                f"but got {type(self.insecure).__name__}."
+                err_prefix % SuperLinkConnectionTomlKey.INSECURE
+                + f"expected bool, but got {type(self.insecure).__name__}."
             )
         if self.enable_account_auth is not None and not isinstance(
             self.enable_account_auth, bool
         ):
             raise ValueError(
-                "Invalid value for key "
-                f"'{SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH}': "
-                f"expected bool, but got {type(self.enable_account_auth).__name__}."
+                err_prefix % SuperLinkConnectionTomlKey.ENABLE_ACCOUNT_AUTH
+                + f"expected bool, but got {type(self.enable_account_auth).__name__}."
             )
 
         if self.federation is not None and not isinstance(self.federation, str):
             raise ValueError(
-                "Invalid value for key "
-                f"'{SuperLinkConnectionTomlKey.FEDERATION}': "
-                f"expected str, but got {type(self.federation).__name__}."
+                err_prefix % SuperLinkConnectionTomlKey.FEDERATION
+                + f"expected str, but got {type(self.federation).__name__}."
             )
 
         # The connection needs to have either an address or options (or both).

{flwr_nightly-1.26.0.dev20260115 → flwr_nightly-1.26.0.dev20260116}/py/flwr/cli/utils.py

@@ -27,6 +27,7 @@ import grpc
 import pathspec
 import typer
 
+from flwr.cli.typing import SuperLinkConnection
 from flwr.common.constant import (
     ACCESS_TOKEN_KEY,
     AUTHN_TYPE_JSON_KEY,
@@ -47,10 +48,14 @@ from flwr.common.grpc import (
     create_channel,
     on_channel_state_change,
 )
+from flwr.supercore.utils import get_flwr_home
 
 from .auth_plugin import CliAuthPlugin, get_cli_plugin_class
 from .cli_account_auth_interceptor import CliAccountAuthInterceptor
-from .config_utils import validate_certificate_in_federation_config
+from .config_utils import (
+    load_certificate_in_connection,
+    validate_certificate_in_federation_config,
+)
 
 
 def prompt_text(
@@ -369,6 +374,52 @@ def load_cli_auth_plugin(
         raise typer.Exit(code=1) from None
 
 
+def load_cli_auth_plugin_from_connection(
+    connection: SuperLinkConnection,
+    authn_type: str | None = None,
+) -> CliAuthPlugin:
+    """Load the CLI-side account auth plugin for the given connection.
+
+    Parameters
+    ----------
+    connection : SuperLinkConnection
+        The SuperLink connection configuration.
+    authn_type : str | None
+        Authentication type. If None, will be determined from config.
+
+    Returns
+    -------
+    CliAuthPlugin
+        The loaded authentication plugin instance.
+
+    Raises
+    ------
+    typer.Exit
+        If the authentication type is unknown.
+    """
+    # Locate the credentials directory
+    flwr_dir = get_flwr_home()
+    credentials_dir = flwr_dir / CREDENTIALS_DIR
+    credentials_dir.mkdir(parents=True, exist_ok=True)
+
+    # Find the path to the account auth config file
+    config_path = get_account_auth_config_path(flwr_dir, connection.name)
+
+    # Determine the auth type if not provided
+    if authn_type is None:
+        authn_type = AuthnType.NOOP
+        if connection.enable_account_auth:
+            authn_type = retrieve_authn_type(config_path)
+
+    # Retrieve auth plugin class and instantiate it
+    try:
+        auth_plugin_class = get_cli_plugin_class(authn_type)
+        return auth_plugin_class(config_path)
+    except ValueError:
+        typer.echo(f"❌ Unknown account authentication type: {authn_type}")
+        raise typer.Exit(code=1) from None
+
+
 def init_channel(
     app: Path, federation_config: dict[str, Any], auth_plugin: CliAuthPlugin
 ) -> grpc.Channel:
@@ -407,6 +458,46 @@ def init_channel(
     return channel
 
 
+def init_channel_from_connection(connection: SuperLinkConnection) -> grpc.Channel:
+    """Initialize gRPC channel to the Control API.
+
+    Parameters
+    ----------
+    connection : SuperLinkConnection
+        SuperLink connection configuration.
+
+    Returns
+    -------
+    grpc.Channel
+        Configured gRPC channel with authentication interceptors.
+    """
+    root_certificates_bytes = load_certificate_in_connection(connection)
+
+    # Load authentication plugin
+    auth_plugin = load_cli_auth_plugin_from_connection(connection)
+
+    # Load tokens
+    auth_plugin.load_tokens()
+
+    # Ensure address and insecure are set
+    if connection.address is None or connection.insecure is None:
+        raise ValueError(
+            f"Couldn't create channel. SuperLink connection '{connection.name}'"
+            " is missing address or insecure setting."
+        )
+
+    # Create the gRPC channel
+    channel = create_channel(
+        server_address=connection.address,
+        insecure=connection.insecure,
+        root_certificates=root_certificates_bytes,
+        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
+        interceptors=[CliAccountAuthInterceptor(auth_plugin)],
+    )
+    channel.subscribe(on_channel_state_change)
+    return channel
+
+
 @contextmanager
 def flwr_cli_grpc_exc_handler() -> Iterator[None]:  # pylint: disable=too-many-branches
     """Context manager to handle specific gRPC errors.

flwr_nightly-1.26.0.dev20260116/py/flwr/supercore/state/__init__.py

@@ -0,0 +1,15 @@
+# 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 SuperCore state components."""

flwr_nightly-1.26.0.dev20260116/py/flwr/supercore/state/schema/README.md

@@ -0,0 +1,39 @@
+# State Entity Relationship Diagram
+
+## Schema
+
+```mermaid
+
+---
+    config:
+        layout: elk
+---
+erDiagram
+  object_children {
+    VARCHAR child_id PK,FK
+    VARCHAR parent_id PK,FK
+  }
+
+  objects {
+    VARCHAR object_id PK "nullable"
+    BLOB content "nullable"
+    INTEGER is_available
+    INTEGER ref_count
+  }
+
+  run_objects {
+    VARCHAR object_id PK,FK
+    INTEGER run_id PK
+  }
+
+  token_store {
+    INTEGER run_id PK "nullable"
+    FLOAT active_until "nullable"
+    VARCHAR token UK
+  }
+
+  objects ||--o| object_children : parent_id
+  objects ||--o| object_children : child_id
+  objects ||--o| run_objects : object_id
+
+```

flwr_nightly-1.26.0.dev20260116/py/flwr/supercore/state/schema/__init__.py

@@ -0,0 +1,15 @@
+# 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 SQLAlchemy database schema."""

flwr_nightly-1.26.0.dev20260116/py/flwr/supercore/state/schema/corestate_tables.py

@@ -0,0 +1,30 @@
+# 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.
+# ==============================================================================
+"""SQLAlchemy Core Table definitions for CoreState."""
+
+from sqlalchemy import Column, Float, Integer, MetaData, String, Table
+
+corestate_metadata = MetaData()
+
+# ------------------------------------------------------------------------------
+#  Table: token_store
+# ------------------------------------------------------------------------------
+token_store = Table(
+    "token_store",
+    corestate_metadata,
+    Column("run_id", Integer, primary_key=True, nullable=True),
+    Column("token", String, unique=True, nullable=False),
+    Column("active_until", Float),
+)