Karana.KUtils.kdpy_model_io
===========================

.. py:module:: Karana.KUtils.kdpy_model_io

.. autoapi-nested-parse::

   Load and identify serialized kdFlex models for the kdpy launcher.

   The launcher accepts one ``--from-model`` path without requiring the user to
   name its serialized root type. This module owns that probing policy and
   normalizes every successful load into :class:`LoadedModel`, allowing the rest
   of kdpy to work with one small interface.



Attributes
----------

.. autoapisummary::

   Karana.KUtils.kdpy_model_io.MODEL_LOADERS


Classes
-------

.. autoapisummary::

   Karana.KUtils.kdpy_model_io.LoadedModel


Functions
---------

.. autoapisummary::

   Karana.KUtils.kdpy_model_io.loadModel


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

.. py:class:: LoadedModel

   Normalize a successfully loaded root model for launcher orchestration.

   ``state_target`` is the object reset from ``--from-state``. It may be a
   subtree even when ``sim.mb`` is the complete multibody. ``model_target`` is
   retained until output serialization so kdpy writes the same kind of model
   that it read. The caller owns ``sim`` and therefore controls the lifetime of
   every native object reachable through the other fields.


   .. py:attribute:: sim
      :type:  Karana.KUtils.Sim.Sim


   .. py:attribute:: model_type
      :type:  str


   .. py:attribute:: state_target
      :type:  Karana.Dynamics.SubTree


   .. py:attribute:: model_target
      :type:  Any


.. py:data:: MODEL_LOADERS
   :type:  tuple[tuple[str, Callable[[pathlib.Path], tuple[Karana.KUtils.Sim.Sim, Karana.Dynamics.SubTree, Any]]], Ellipsis]

.. py:function:: loadModel(model_file: pathlib.Path) -> LoadedModel

   Load the first supported kdFlex model type that accepts the file.

   Each kdFlex ``fromFile`` call performs schema validation. A schema mismatch
   is therefore the dispatch signal rather than a fatal error. Failed probes
   can allocate native objects and register cleanup callbacks, so each attempt
   is treated as a small transaction: remember the callback boundary, try the
   loader, and unwind only callbacks introduced by that attempt on failure.