flip.nvflare.components.flip_server_event_handler
=================================================

.. py:module:: flip.nvflare.components.flip_server_event_handler


Classes
-------

.. autoapisummary::

   flip.nvflare.components.flip_server_event_handler.ServerEventHandler


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

.. py:class:: ServerEventHandler(model_id: str = '', validation_json_generator_id: str = 'json_generator', persist_and_cleanup_id: str = 'persist_and_cleanup', flip: flip.FLIP = FLIP())

   Bases: :py:obj:`nvflare.apis.fl_component.FLComponent`


   ServerEventHandler is a generic component that handles system events triggered by nvflare
   or custom flip events. It executes logic inside its own event handler but may also call
   other component's event handlers directly to overcome the non-deterministic order
   in which nvflare handles events i.e handling ValidationJsonGenerator component events.

   :param model_id: ID of the model. When empty, the model ID is resolved lazily
                    from job metadata via ``get_flip_model_id`` on first status update.
   :type model_id: str, optional
   :param validation_json_generator_id: Component ID for the validation JSON generator.
   :type validation_json_generator_id: str, optional
   :param persist_and_cleanup_id: Component ID for the persist-and-cleanup component.
   :type persist_and_cleanup_id: str, optional
   :param flip: FLIP client instance.
   :type flip: FLIP, optional


   .. py:attribute:: _model_id_fallback
      :value: ''



   .. py:attribute:: _model_id
      :type:  str | None
      :value: None



   .. py:attribute:: validation_json_generator_id
      :value: 'json_generator'



   .. py:attribute:: validation_json_generator
      :value: None



   .. py:attribute:: persist_and_cleanup_id
      :value: 'persist_and_cleanup'



   .. py:attribute:: persist_and_cleanup
      :value: None



   .. py:attribute:: flip


   .. py:attribute:: fatal_error
      :value: False



   .. py:attribute:: final_status
      :type:  flip.constants.ModelStatus | None
      :value: None



   .. py:method:: _resolve_model_id(fl_ctx: nvflare.apis.fl_context.FLContext) -> str

      Resolve model ID lazily from job metadata, falling back to the constructor arg.

      :param fl_ctx: The FL context for the current job.
      :type fl_ctx: FLContext

      :returns: The resolved model ID.
      :rtype: str



   .. py:method:: _update_status(fl_ctx: nvflare.apis.fl_context.FLContext, status: flip.constants.ModelStatus | None) -> None

      Resolve model ID lazily and update training status.

      :param fl_ctx: The FL context for the current job.
      :type fl_ctx: FLContext
      :param status: The new model status to set.
      :type status: ModelStatus | None



   .. py:method:: _relay_round_event(fl_ctx: nvflare.apis.fl_context.FLContext, event: flip.schemas.FLLogEvent) -> None

      Relay a stock round boundary to the hub as a typed fact.

      Facts only — display text is composed hub-side. NVFLARE's
      ``CURRENT_ROUND`` prop is 0-based; the wire contract is 1-based.
      ``ROUND_AGGREGATED`` counts come from the sticky props seeded here at
      round start ("0 of m") and overwritten by the FLIP ScatterAndGather
      controller as it accepts client results.

      :param fl_ctx: The FL context carrying the round props.
      :type fl_ctx: FLContext
      :param event: ROUND_STARTED or ROUND_AGGREGATED.
      :type event: FLLogEvent



   .. py:method:: _expected_client_count(fl_ctx: nvflare.apis.fl_context.FLContext) -> int | None

      Best-effort count of the clients targeted this round; ``None`` when unavailable.

      :param fl_ctx: The FL context to read the engine from.
      :type fl_ctx: FLContext

      :returns: ``len(engine.get_clients())``, or ``None`` when the engine
                cannot be read (the round then closes with the uncounted wording).
      :rtype: int | None



   .. py:method:: _evaluation_wholly_failed() -> bool

      Whether this is an evaluation job in which every validate task failed.

      Training jobs wire the base ``ValidationJsonGenerator``, which tracks no failures, so the
      isinstance check also serves as the "is this an evaluation job" test.

      :returns: True when the evaluation produced failures and no results at all.
      :rtype: bool



   .. py:method:: _terminal_status(default: flip.constants.ModelStatus) -> flip.constants.ModelStatus

      Resolve the run's terminal status, most salient cause first.

      A recorded fatal system error is the root cause and outranks everything. A user-requested
      abort outranks the evaluation failures it necessarily caused (aborting a run cancels its
      in-flight validate tasks, which must not be reported as ERROR). An evaluation in which every
      validate task failed outranks ``default`` — otherwise a wholly failed run reports success on
      an empty results file (FLIP#754), or reports a trailing upload failure as its cause.

      :param default: The status to use when no failure cause is recorded — the outcome
                      of the upload itself.
      :type default: ModelStatus

      :returns: The status to report to the hub.
      :rtype: ModelStatus



   .. py:method:: handle_event(event_type: str, fl_ctx: nvflare.apis.fl_context.FLContext) -> None


   .. py:method:: __set_dependencies(fl_ctx: nvflare.apis.fl_context.FLContext) -> None