flip.nvflare.runtime
====================

.. py:module:: flip.nvflare.runtime

.. autoapi-nested-parse::

   Runtime resolution of FLIP-specific job parameters from NVFLARE's job metadata.

   The FLIP-API hands job-scoped values (``model_id``, optionally ``participating_clients``)
   to NVFLARE via ``meta.json``'s ``custom_props`` dict. FLIP components fetch these at first
   use via :func:`get_flip_model_id` rather than requiring them as ``__init__`` arguments —
   this lets the Python ``FlipFedAvgRecipe`` build a real ``FedJob`` (no UUID known yet) that
   runs identically in SimEnv, PocEnv, ProdEnv, or under the FLIP-API.

   Resolution order, given a component that also accepts a legacy ``model_id`` constructor arg:

   1. If the constructor arg is a real UUID (e.g. the FLIP-API substituted ``{model_id}`` into
      the JSON config before NVFLARE loaded it), use it.
   2. Otherwise read ``fl_ctx.get_prop(FLContextKey.JOB_META)["custom_props"]["model_id"]``.
   3. Otherwise raise ``ValueError`` — neither path produced a UUID.



Attributes
----------

.. autoapisummary::

   flip.nvflare.runtime.FLIP_CUSTOM_PROPS_KEY
   flip.nvflare.runtime.FLIP_MODEL_ID_KEY
   flip.nvflare.runtime.FLIP_PARTICIPATING_CLIENTS_KEY


Functions
---------

.. autoapisummary::

   flip.nvflare.runtime.get_job_custom_props
   flip.nvflare.runtime._load_meta_from_workspace
   flip.nvflare.runtime.get_flip_model_id


Module Contents
---------------

.. py:data:: FLIP_CUSTOM_PROPS_KEY
   :value: 'custom_props'


.. py:data:: FLIP_MODEL_ID_KEY
   :value: 'model_id'


.. py:data:: FLIP_PARTICIPATING_CLIENTS_KEY
   :value: 'participating_clients'


.. py:function:: get_job_custom_props(fl_ctx: nvflare.apis.fl_context.FLContext) -> dict[str, Any]

   Return the ``custom_props`` dict from the job's ``meta.json``, or ``{}`` if absent.

   NVFLARE sets ``FLContextKey.JOB_META`` with ``sticky=False``, so it's only on the
   fl_ctx during the component-build phase — gone by the time controllers fire events.
   Fall back to reading ``meta.json`` straight from the workspace's run dir.


.. py:function:: _load_meta_from_workspace(fl_ctx: nvflare.apis.fl_context.FLContext) -> dict[str, Any] | None

   Read ``meta.json`` from the run dir if the FLContext doesn't carry it.


.. py:function:: get_flip_model_id(fl_ctx: nvflare.apis.fl_context.FLContext, fallback: str | None = None) -> str

   Resolve the FLIP ``model_id`` for the current job.

   :param fl_ctx: The NVFLARE FLContext.
   :param fallback: Value passed to the component's ``__init__`` (legacy path). If this is a
                    valid UUID it is returned as-is; otherwise it's ignored.

   :returns: A UUID string.

   :raises ValueError: If neither ``fallback`` nor ``meta.json``'s ``custom_props.model_id``
       holds a valid UUID.