flwr-nightly 1.13.0.dev20241114__py3-none-any.whl → 1.13.0.dev20241116__py3-none-any.whl

flwr/server/superlink/linkstate/sqlite_linkstate.py

@@ -57,6 +57,8 @@ from .utils import (
     generate_rand_int_from_bytes,
     has_valid_sub_status,
     is_valid_transition,
+    verify_found_taskres,
+    verify_taskins_ids,
 )
 
 SQL_CREATE_TABLE_NODE = """
@@ -510,136 +512,67 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
 
     # pylint: disable-next=R0912,R0915,R0914
     def get_task_res(self, task_ids: set[UUID]) -> list[TaskRes]:
-        """Get TaskRes for task_ids.
+        """Get TaskRes for the given TaskIns IDs."""
+        ret: dict[UUID, TaskRes] = {}
 
-        Usually, the ServerAppIo API calls this method to get results for instructions
-        it has previously scheduled.
-
-        Retrieves all TaskRes for the given `task_ids` and returns and empty list if
-        none could be found.
-
-        Constraints
-        -----------
-        If `limit` is not `None`, return, at most, `limit` number of TaskRes. The limit
-        will only take effect if enough task_ids are in the set AND are currently
-        available. If `limit` is set, it has to be greater than zero.
-        """
-        # Check if corresponding TaskIns exists and is not expired
-        task_ids_placeholders = ",".join([f":id_{i}" for i in range(len(task_ids))])
+        # Verify TaskIns IDs
+        current = time.time()
         query = f"""
             SELECT *
             FROM task_ins
-            WHERE task_id IN ({task_ids_placeholders})
-            AND (created_at + ttl) > CAST(strftime('%s', 'now') AS REAL)
+            WHERE task_id IN ({",".join(["?"] * len(task_ids))});
         """
-        query += ";"
-
-        task_ins_data = {}
-        for index, task_id in enumerate(task_ids):
-            task_ins_data[f"id_{index}"] = str(task_id)
-
-        task_ins_rows = self.query(query, task_ins_data)
-
-        if not task_ins_rows:
-            return []
-
-        for row in task_ins_rows:
-            # Convert values from sint64 to uint64
+        rows = self.query(query, tuple(str(task_id) for task_id in task_ids))
+        found_task_ins_dict: dict[UUID, TaskIns] = {}
+        for row in rows:
             convert_sint64_values_in_dict_to_uint64(
                 row, ["run_id", "producer_node_id", "consumer_node_id"]
             )
-            task_ins = dict_to_task_ins(row)
-            if task_ins.task.created_at + task_ins.task.ttl <= time.time():
-                log(WARNING, "TaskIns with task_id %s is expired.", task_ins.task_id)
-                task_ids.remove(UUID(task_ins.task_id))
+            found_task_ins_dict[UUID(row["task_id"])] = dict_to_task_ins(row)
 
-        # Retrieve all anonymous Tasks
-        if len(task_ids) == 0:
-            return []
+        ret = verify_taskins_ids(
+            inquired_taskins_ids=task_ids,
+            found_taskins_dict=found_task_ins_dict,
+            current_time=current,
+        )
 
-        placeholders = ",".join([f":id_{i}" for i in range(len(task_ids))])
+        # Find all TaskRes
         query = f"""
             SELECT *
             FROM task_res
-            WHERE ancestry IN ({placeholders})
-            AND delivered_at = ""
+            WHERE ancestry IN ({",".join(["?"] * len(task_ids))})
+            AND delivered_at = "";
         """
+        rows = self.query(query, tuple(str(task_id) for task_id in task_ids))
+        for row in rows:
+            convert_sint64_values_in_dict_to_uint64(
+                row, ["run_id", "producer_node_id", "consumer_node_id"]
+            )
+        tmp_ret_dict = verify_found_taskres(
+            inquired_taskins_ids=task_ids,
+            found_taskins_dict=found_task_ins_dict,
+            found_taskres_list=[dict_to_task_res(row) for row in rows],
+            current_time=current,
+        )
+        ret.update(tmp_ret_dict)
 
-        data: dict[str, Union[str, float, int]] = {}
-
-        query += ";"
-
-        for index, task_id in enumerate(task_ids):
-            data[f"id_{index}"] = str(task_id)
-
-        rows = self.query(query, data)
-
-        if rows:
-            # Prepare query
-            found_task_ids = [row["task_id"] for row in rows]
-            placeholders = ",".join([f":id_{i}" for i in range(len(found_task_ids))])
-            query = f"""
-                UPDATE task_res
-                SET delivered_at = :delivered_at
-                WHERE task_id IN ({placeholders})
-                RETURNING *;
-            """
-
-            # Prepare data for query
-            delivered_at = now().isoformat()
-            data = {"delivered_at": delivered_at}
-            for index, task_id in enumerate(found_task_ids):
-                data[f"id_{index}"] = str(task_id)
-
-            # Run query
-            rows = self.query(query, data)
-
-            for row in rows:
-                # Convert values from sint64 to uint64
-                convert_sint64_values_in_dict_to_uint64(
-                    row, ["run_id", "producer_node_id", "consumer_node_id"]
-                )
-
-        result = [dict_to_task_res(row) for row in rows]
-
-        # 1. Query: Fetch consumer_node_id of remaining task_ids
-        # Assume the ancestry field only contains one element
-        data.clear()
-        replied_task_ids: set[UUID] = {UUID(str(row["ancestry"])) for row in rows}
-        remaining_task_ids = task_ids - replied_task_ids
-        placeholders = ",".join([f":id_{i}" for i in range(len(remaining_task_ids))])
-        query = f"""
-            SELECT consumer_node_id
-            FROM task_ins
-            WHERE task_id IN ({placeholders});
-        """
-        for index, task_id in enumerate(remaining_task_ids):
-            data[f"id_{index}"] = str(task_id)
-        node_ids = [int(row["consumer_node_id"]) for row in self.query(query, data)]
-
-        # 2. Query: Select offline nodes
-        placeholders = ",".join([f":id_{i}" for i in range(len(node_ids))])
+        # Mark existing TaskRes to be returned as delivered
+        delivered_at = now().isoformat()
+        for task_res in ret.values():
+            task_res.task.delivered_at = delivered_at
+        task_res_ids = [task_res.task_id for task_res in ret.values()]
         query = f"""
-            SELECT node_id
-            FROM node
-            WHERE node_id IN ({placeholders})
-            AND online_until < :time;
+            UPDATE task_res
+            SET delivered_at = ?
+            WHERE task_id IN ({",".join(["?"] * len(task_res_ids))});
         """
-        data = {f"id_{i}": str(node_id) for i, node_id in enumerate(node_ids)}
-        data["time"] = time.time()
-        offline_node_ids = [int(row["node_id"]) for row in self.query(query, data)]
+        data: list[Any] = [delivered_at] + task_res_ids
+        self.query(query, data)
 
-        # 3. Query: Select TaskIns for offline nodes
-        placeholders = ",".join([f":id_{i}" for i in range(len(offline_node_ids))])
-        query = f"""
-            SELECT *
-            FROM task_ins
-            WHERE consumer_node_id IN ({placeholders});
-        """
-        data = {f"id_{i}": str(node_id) for i, node_id in enumerate(offline_node_ids)}
-        task_ins_rows = self.query(query, data)
+        # Cleanup
+        self._force_delete_tasks_by_ids(set(ret.keys()))
 
-        return result
+        return list(ret.values())
 
     def num_task_ins(self) -> int:
         """Calculate the number of task_ins in store.
@@ -699,6 +632,32 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
 
         return None
 
+    def _force_delete_tasks_by_ids(self, task_ids: set[UUID]) -> None:
+        """Delete tasks based on a set of TaskIns IDs."""
+        if not task_ids:
+            return
+        if self.conn is None:
+            raise AttributeError("LinkState not initialized")
+
+        placeholders = ",".join([f":id_{index}" for index in range(len(task_ids))])
+        data = {f"id_{index}": str(task_id) for index, task_id in enumerate(task_ids)}
+
+        # Delete task_ins
+        query_1 = f"""
+            DELETE FROM task_ins
+            WHERE task_id IN ({placeholders});
+        """
+
+        # Delete task_res
+        query_2 = f"""
+            DELETE FROM task_res
+            WHERE ancestry IN ({placeholders});
+        """
+
+        with self.conn:
+            self.conn.execute(query_1, data)
+            self.conn.execute(query_2, data)
+
     def create_node(
         self, ping_interval: float, public_key: Optional[bytes] = None
     ) -> int:

flwr/server/superlink/linkstate/utils.py

@@ -15,15 +15,23 @@
 """Utility functions for State."""
 
 
+from logging import ERROR
 from os import urandom
+from typing import Optional, Union
+from uuid import UUID, uuid4
 
-from flwr.common import ConfigsRecord, Context, serde
-from flwr.common.constant import Status, SubStatus
+from flwr.common import ConfigsRecord, Context, log, now, serde
+from flwr.common.constant import ErrorCode, Status, SubStatus
 from flwr.common.typing import RunStatus
-from flwr.proto.message_pb2 import Context as ProtoContext  # pylint: disable=E0611
 
 # pylint: disable=E0611
+from flwr.proto.error_pb2 import Error
+from flwr.proto.message_pb2 import Context as ProtoContext
+from flwr.proto.node_pb2 import Node
 from flwr.proto.recordset_pb2 import ConfigsRecord as ProtoConfigsRecord
+from flwr.proto.task_pb2 import Task, TaskIns, TaskRes
+
+# pylint: enable=E0611
 
 NODE_UNAVAILABLE_ERROR_REASON = (
     "Error: Node Unavailable - The destination node is currently unavailable. "
@@ -43,6 +51,13 @@ VALID_RUN_SUB_STATUSES = {
     SubStatus.FAILED,
     SubStatus.STOPPED,
 }
+MESSAGE_UNAVAILABLE_ERROR_REASON = (
+    "Error: Message Unavailable - The requested message could not be found in the "
+    "database. It may have expired due to its TTL or never existed."
+)
+REPLY_MESSAGE_UNAVAILABLE_ERROR_REASON = (
+    "Error: Reply Message Unavailable - The reply message has expired."
+)
 
 
 def generate_rand_int_from_bytes(num_bytes: int) -> int:
@@ -208,3 +223,167 @@ def has_valid_sub_status(status: RunStatus) -> bool:
     if status.status == Status.FINISHED:
         return status.sub_status in VALID_RUN_SUB_STATUSES
     return status.sub_status == ""
+
+
+def create_taskres_for_unavailable_taskins(taskins_id: Union[str, UUID]) -> TaskRes:
+    """Generate a TaskRes with a TaskIns unavailable error.
+
+    Parameters
+    ----------
+    taskins_id : Union[str, UUID]
+        The ID of the unavailable TaskIns.
+
+    Returns
+    -------
+    TaskRes
+        A TaskRes with an error code MESSAGE_UNAVAILABLE to indicate that the
+        inquired TaskIns ID cannot be found (due to non-existence or expiration).
+    """
+    current_time = now().timestamp()
+    return TaskRes(
+        task_id=str(uuid4()),
+        group_id="",  # Unknown group ID
+        run_id=0,  # Unknown run ID
+        task=Task(
+            # This function is only called by SuperLink, and thus it's the producer.
+            producer=Node(node_id=0, anonymous=False),
+            consumer=Node(node_id=0, anonymous=False),
+            created_at=current_time,
+            ttl=0,
+            ancestry=[str(taskins_id)],
+            task_type="",  # Unknown message type
+            error=Error(
+                code=ErrorCode.MESSAGE_UNAVAILABLE,
+                reason=MESSAGE_UNAVAILABLE_ERROR_REASON,
+            ),
+        ),
+    )
+
+
+def create_taskres_for_unavailable_taskres(ref_taskins: TaskIns) -> TaskRes:
+    """Generate a TaskRes with a reply message unavailable error from a TaskIns.
+
+    Parameters
+    ----------
+    ref_taskins : TaskIns
+        The reference TaskIns object.
+
+    Returns
+    -------
+    TaskRes
+        The generated TaskRes with an error code REPLY_MESSAGE_UNAVAILABLE_ERROR_REASON,
+        indicating that the original TaskRes has expired.
+    """
+    current_time = now().timestamp()
+    ttl = ref_taskins.task.ttl - (current_time - ref_taskins.task.created_at)
+    if ttl < 0:
+        log(ERROR, "Creating TaskRes for TaskIns that exceeds its TTL.")
+        ttl = 0
+    return TaskRes(
+        task_id=str(uuid4()),
+        group_id=ref_taskins.group_id,
+        run_id=ref_taskins.run_id,
+        task=Task(
+            # This function is only called by SuperLink, and thus it's the producer.
+            producer=Node(node_id=0, anonymous=False),
+            consumer=Node(node_id=0, anonymous=False),
+            created_at=current_time,
+            ttl=ttl,
+            ancestry=[ref_taskins.task_id],
+            task_type=ref_taskins.task.task_type,
+            error=Error(
+                code=ErrorCode.REPLY_MESSAGE_UNAVAILABLE,
+                reason=REPLY_MESSAGE_UNAVAILABLE_ERROR_REASON,
+            ),
+        ),
+    )
+
+
+def has_expired(task_ins_or_res: Union[TaskIns, TaskRes], current_time: float) -> bool:
+    """Check if the TaskIns/TaskRes has expired."""
+    return task_ins_or_res.task.ttl + task_ins_or_res.task.created_at < current_time
+
+
+def verify_taskins_ids(
+    inquired_taskins_ids: set[UUID],
+    found_taskins_dict: dict[UUID, TaskIns],
+    current_time: Optional[float] = None,
+    update_set: bool = True,
+) -> dict[UUID, TaskRes]:
+    """Verify found TaskIns and generate error TaskRes for invalid ones.
+
+    Parameters
+    ----------
+    inquired_taskins_ids : set[UUID]
+        Set of TaskIns IDs for which to generate error TaskRes if invalid.
+    found_taskins_dict : dict[UUID, TaskIns]
+        Dictionary containing all found TaskIns indexed by their IDs.
+    current_time : Optional[float] (default: None)
+        The current time to check for expiration. If set to `None`, the current time
+        will automatically be set to the current timestamp using `now().timestamp()`.
+    update_set : bool (default: True)
+        If True, the `inquired_taskins_ids` will be updated to remove invalid ones,
+        by default True.
+
+    Returns
+    -------
+    dict[UUID, TaskRes]
+        A dictionary of error TaskRes indexed by the corresponding TaskIns ID.
+    """
+    ret_dict = {}
+    current = current_time if current_time else now().timestamp()
+    for taskins_id in list(inquired_taskins_ids):
+        # Generate error TaskRes if the task_ins doesn't exist or has expired
+        taskins = found_taskins_dict.get(taskins_id)
+        if taskins is None or has_expired(taskins, current):
+            if update_set:
+                inquired_taskins_ids.remove(taskins_id)
+            taskres = create_taskres_for_unavailable_taskins(taskins_id)
+            ret_dict[taskins_id] = taskres
+    return ret_dict
+
+
+def verify_found_taskres(
+    inquired_taskins_ids: set[UUID],
+    found_taskins_dict: dict[UUID, TaskIns],
+    found_taskres_list: list[TaskRes],
+    current_time: Optional[float] = None,
+    update_set: bool = True,
+) -> dict[UUID, TaskRes]:
+    """Verify found TaskRes and generate error TaskRes for invalid ones.
+
+    Parameters
+    ----------
+    inquired_taskins_ids : set[UUID]
+        Set of TaskIns IDs for which to generate error TaskRes if invalid.
+    found_taskins_dict : dict[UUID, TaskIns]
+        Dictionary containing all found TaskIns indexed by their IDs.
+    found_taskres_list : dict[TaskIns, TaskRes]
+        List of found TaskRes to be verified.
+    current_time : Optional[float] (default: None)
+        The current time to check for expiration. If set to `None`, the current time
+        will automatically be set to the current timestamp using `now().timestamp()`.
+    update_set : bool (default: True)
+        If True, the `inquired_taskins_ids` will be updated to remove ones
+        that have a TaskRes, by default True.
+
+    Returns
+    -------
+    dict[UUID, TaskRes]
+        A dictionary of TaskRes indexed by the corresponding TaskIns ID.
+    """
+    ret_dict: dict[UUID, TaskRes] = {}
+    current = current_time if current_time else now().timestamp()
+    for taskres in found_taskres_list:
+        taskins_id = UUID(taskres.task.ancestry[0])
+        if update_set:
+            inquired_taskins_ids.remove(taskins_id)
+        # Check if the TaskRes has expired
+        if has_expired(taskres, current):
+            # No need to insert the error TaskRes
+            taskres = create_taskres_for_unavailable_taskres(
+                found_taskins_dict[taskins_id]
+            )
+            taskres.task.delivered_at = now().isoformat()
+        ret_dict[taskins_id] = taskres
+    return ret_dict

flwr/simulation/app.py

@@ -119,7 +119,7 @@ def flwr_simulation() -> None:
         args.superlink,
     )
     run_simulation_process(
-        superlink=args.superlink,
+        simulationio_api_address=args.superlink,
         log_queue=log_queue,
         run_once=args.run_once,
         flwr_dir_=args.flwr_dir,
@@ -131,7 +131,7 @@ def flwr_simulation() -> None:
 
 
 def run_simulation_process(  # pylint: disable=R0914, disable=W0212, disable=R0915
-    superlink: str,
+    simulationio_api_address: str,
     log_queue: Queue[Optional[str]],
     run_once: bool,
     flwr_dir_: Optional[str] = None,
@@ -139,7 +139,7 @@ def run_simulation_process(  # pylint: disable=R0914, disable=W0212, disable=R09
 ) -> None:
     """Run Flower Simulation process."""
     conn = SimulationIoConnection(
-        simulationio_service_address=superlink,
+        simulationio_service_address=simulationio_api_address,
         root_certificates=certificates,
     )
 

flwr/simulation/legacy_app.py

@@ -30,7 +30,12 @@ from ray.util.scheduling_strategies import NodeAffinitySchedulingStrategy
 from flwr.client import ClientFnExt
 from flwr.common import EventType, event
 from flwr.common.constant import NODE_ID_NUM_BYTES
-from flwr.common.logger import log, set_logger_propagation, warn_unsupported_feature
+from flwr.common.logger import (
+    log,
+    set_logger_propagation,
+    warn_deprecated_feature,
+    warn_unsupported_feature,
+)
 from flwr.server.client_manager import ClientManager
 from flwr.server.history import History
 from flwr.server.server import Server, init_defaults, run_fl
@@ -108,6 +113,11 @@ def start_simulation(
 ) -> History:
     """Start a Ray-based Flower simulation server.
 
+    Warning
+    -------
+    This function is deprecated since 1.13.0. Use :code: `flwr run` to start a Flower
+    simulation.
+
     Parameters
     ----------
     client_fn : ClientFnExt
@@ -183,6 +193,16 @@ def start_simulation(
         Object containing metrics from training.
     """  # noqa: E501
     # pylint: disable-msg=too-many-locals
+    msg = (
+        "flwr.simulation.start_simulation() is deprecated."
+        "\n\tInstead, use the `flwr run` CLI command to start a local simulation "
+        "in your Flower app, as shown for example below:"
+        "\n\n\t\t$ flwr new  # Create a new Flower app from a template"
+        "\n\n\t\t$ flwr run  # Run the Flower app in Simulation Mode"
+        "\n\n\tUsing `start_simulation()` is deprecated."
+    )
+    warn_deprecated_feature(name=msg)
+
     event(
         EventType.START_SIMULATION_ENTER,
         {"num_clients": len(clients_ids) if clients_ids is not None else num_clients},

flwr/simulation/simulationio_connection.py

@@ -20,7 +20,7 @@ from typing import Optional, cast
 
 import grpc
 
-from flwr.common.constant import SIMULATIONIO_API_DEFAULT_ADDRESS
+from flwr.common.constant import SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
 from flwr.proto.simulationio_pb2_grpc import SimulationIoStub  # pylint: disable=E0611
@@ -41,7 +41,7 @@ class SimulationIoConnection:
 
     def __init__(  # pylint: disable=too-many-arguments
         self,
-        simulationio_service_address: str = SIMULATIONIO_API_DEFAULT_ADDRESS,
+        simulationio_service_address: str = SIMULATIONIO_API_DEFAULT_CLIENT_ADDRESS,
         root_certificates: Optional[bytes] = None,
     ) -> None:
         self._addr = simulationio_service_address

flwr/superexec/deployment.py

@@ -23,7 +23,11 @@ from typing_extensions import override
 
 from flwr.cli.config_utils import get_fab_metadata
 from flwr.common import ConfigsRecord, Context, RecordSet
-from flwr.common.constant import SERVERAPPIO_API_DEFAULT_ADDRESS, Status, SubStatus
+from flwr.common.constant import (
+    SERVERAPPIO_API_DEFAULT_CLIENT_ADDRESS,
+    Status,
+    SubStatus,
+)
 from flwr.common.logger import log
 from flwr.common.typing import Fab, RunStatus, UserConfig
 from flwr.server.superlink.ffs import Ffs
@@ -38,7 +42,7 @@ class DeploymentEngine(Executor):
 
     Parameters
     ----------
-    superlink: str (default: "0.0.0.0:9091")
+    serverappio_api_address: str (default: "127.0.0.1:9091")
         Address of the SuperLink to connect to.
     root_certificates: Optional[str] (default: None)
         Specifies the path to the PEM-encoded root certificate file for
@@ -49,11 +53,11 @@ class DeploymentEngine(Executor):
 
     def __init__(
         self,
-        superlink: str = SERVERAPPIO_API_DEFAULT_ADDRESS,
+        serverappio_api_address: str = SERVERAPPIO_API_DEFAULT_CLIENT_ADDRESS,
         root_certificates: Optional[str] = None,
         flwr_dir: Optional[str] = None,
     ) -> None:
-        self.superlink = superlink
+        self.serverappio_api_address = serverappio_api_address
         if root_certificates is None:
             self.root_certificates = None
             self.root_certificates_bytes = None
@@ -110,7 +114,7 @@ class DeploymentEngine(Executor):
         if superlink_address := config.get("superlink"):
             if not isinstance(superlink_address, str):
                 raise ValueError("The `superlink` value should be of type `str`.")
-            self.superlink = superlink_address
+            self.serverappio_api_address = superlink_address
         if root_certificates := config.get("root-certificates"):
             if not isinstance(root_certificates, str):
                 raise ValueError(

{flwr_nightly-1.13.0.dev20241114.dist-info → flwr_nightly-1.13.0.dev20241116.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: flwr-nightly
-Version: 1.13.0.dev20241114
-Summary: Flower: A Friendly Federated Learning Framework
+Version: 1.13.0.dev20241116
+Summary: Flower: A Friendly Federated AI Framework
 Home-page: https://flower.ai
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning
@@ -42,6 +42,7 @@ Requires-Dist: protobuf (>=4.25.2,<5.0.0)
 Requires-Dist: pycryptodome (>=3.18.0,<4.0.0)
 Requires-Dist: ray (==2.10.0) ; (python_version >= "3.9" and python_version < "3.12") and (extra == "simulation")
 Requires-Dist: requests (>=2.31.0,<3.0.0) ; extra == "rest"
+Requires-Dist: rich (>=13.5.0,<14.0.0)
 Requires-Dist: starlette (>=0.31.0,<0.32.0) ; extra == "rest"
 Requires-Dist: tomli (>=2.0.1,<3.0.0)
 Requires-Dist: tomli-w (>=1.0.0,<2.0.0)
@@ -51,7 +52,7 @@ Project-URL: Documentation, https://flower.ai
 Project-URL: Repository, https://github.com/adap/flower
 Description-Content-Type: text/markdown
 
-# Flower: A Friendly Federated Learning Framework
+# Flower: A Friendly Federated AI Framework
 
 <p align="center">
   <a href="https://flower.ai/">
@@ -74,7 +75,7 @@ Description-Content-Type: text/markdown
 [![Docker Hub](https://img.shields.io/badge/Docker%20Hub-flwr-blue)](https://hub.docker.com/u/flwr)
 [![Slack](https://img.shields.io/badge/Chat-Slack-red)](https://flower.ai/join-slack)
 
-Flower (`flwr`) is a framework for building federated learning systems. The
+Flower (`flwr`) is a framework for building federated AI systems. The
 design of Flower is based on a few guiding principles:
 
 - **Customizable**: Federated learning systems vary wildly from one use case to