caikit.core.model_management
============================

.. py:module:: caikit.core.model_management

.. autoapi-nested-parse::

   The model management abstractions manage the key lifecycle phases of a concrete
   model instance and are used by the ModelManager to handle each phase of the
   model lifecycle.

   For architectural details, see docs/adrs/020-model-management-abstractions.md



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/caikit/core/model_management/factories/index
   /autoapi/caikit/core/model_management/job_base/index
   /autoapi/caikit/core/model_management/job_predictor_base/index
   /autoapi/caikit/core/model_management/local_job_base/index
   /autoapi/caikit/core/model_management/local_job_predictor/index
   /autoapi/caikit/core/model_management/local_model_finder/index
   /autoapi/caikit/core/model_management/local_model_initializer/index
   /autoapi/caikit/core/model_management/local_model_trainer/index
   /autoapi/caikit/core/model_management/model_finder_base/index
   /autoapi/caikit/core/model_management/model_initializer_base/index
   /autoapi/caikit/core/model_management/model_trainer_base/index
   /autoapi/caikit/core/model_management/multi_model_finder/index
   /autoapi/caikit/core/model_management/multi_model_initializer/index


Attributes
----------

.. autoapisummary::

   caikit.core.model_management.job_predictor_factory
   caikit.core.model_management.model_finder_factory
   caikit.core.model_management.model_initializer_factory
   caikit.core.model_management.model_trainer_factory


Classes
-------

.. autoapisummary::

   caikit.core.model_management.JobBase
   caikit.core.model_management.JobFutureBase
   caikit.core.model_management.JobPredictorBase
   caikit.core.model_management.JobPredictorFutureBase
   caikit.core.model_management.JobPredictorInfo
   caikit.core.model_management.ModelFinderBase
   caikit.core.model_management.ModelInitializerBase
   caikit.core.model_management.ModelTrainerBase
   caikit.core.model_management.ModelTrainerFutureBase
   caikit.core.model_management.TrainingInfo


Package Contents
----------------

.. py:data:: job_predictor_factory

.. py:data:: model_finder_factory

.. py:data:: model_initializer_factory

.. py:data:: model_trainer_factory

.. py:class:: JobBase(config: aconfig.Config, instance_name: str)

   Bases: :py:obj:`caikit.core.toolkit.factory.FactoryConstructible`


   A class can be constructed by a factory if its constructor takes exactly
   one argument that is an aconfig.Config object and it has a name to identify
   itself with the factory.


   .. py:method:: get_future(job_id: str) -> JobFutureBase
      :abstractmethod:


      Look up the model future for the given id



   .. py:method:: get_job_name(job_id: str) -> str
      :classmethod:


      Un-hash the background's instance name from the given job id



.. py:class:: JobFutureBase(future_name: str, future_id: str, use_reversible_hash: bool = True, **kwargs)

   Bases: :py:obj:`abc.ABC`


   Every JobBase implementation must have a JobFutureBase class that can access the
   job information in the infrastructure managed by the task.


   .. py:attribute:: ID_DELIMITER
      :value: ':'



   .. py:attribute:: _id
      :value: ''



   .. py:property:: id
      :type: str


      Every job future must have a unique ID that can be used to look
      up the in-flight background task



   .. py:method:: get_info() -> JobInfo
      :abstractmethod:


      Every model future must be able to poll the status of the
      background job



   .. py:method:: cancel()
      :abstractmethod:


      Terminate the given job



   .. py:method:: wait()
      :abstractmethod:


      Block until the job reaches a terminal state



   .. py:method:: result() -> Any
      :abstractmethod:


      Support result() to match concurrent.futures.Future



.. py:class:: JobPredictorBase(config: aconfig.Config, instance_name: str)

   Bases: :py:obj:`caikit.core.model_management.job_base.JobBase`


   A class can be constructed by a factory if its constructor takes exactly
   one argument that is an aconfig.Config object and it has a name to identify
   itself with the factory.


   .. py:attribute:: __doc__
      :value: Multiline-String

      .. raw:: html

         <details><summary>Show Value</summary>

      .. code-block:: python

         """
         A Job Predictor is responsible for managing execution of a prediction jobs running
         in the background for a given task method
         
         Configuration for Job Predictors lives under the config as follows:
         
         model_management:
             job_predictors:
                 <predictor name>:
                     type: <predictor type name>
                     config:
                         <config option>: <value>
         """

      .. raw:: html

         </details>




   .. py:method:: predict(model_instance: caikit.core.modules.ModuleBase, prediction_func_name: str, *args, external_inference_id: Optional[str] = None, **kwargs) -> JobPredictorFutureBase
      :abstractmethod:


      Start a prediction with the given model instance and function and return a
      future to the prediction result



   .. py:method:: get_prediction_future(future_id: str) -> JobPredictorFutureBase
      :abstractmethod:


      Look up the jobs future for the given id



   .. py:method:: get_future(prediction_id: str) -> caikit.core.model_management.job_base.JobFutureBase

      Look up the job future for the given id



   .. py:method:: get_predictor_name(predict_id: str) -> str
      :classmethod:


      Un-hash the predictors's instance name from the given prediction id



.. py:class:: JobPredictorFutureBase(future_name: str, future_id: str, use_reversible_hash: bool = True, **kwargs)

   Bases: :py:obj:`caikit.core.model_management.job_base.JobFutureBase`


   Subclass of JobFutureBase for Job Predictions


   .. py:method:: result() -> caikit.core.data_model.DataObjectBase
      :abstractmethod:


      The result of a JobPredictorFutureBase is the result object



.. py:class:: JobPredictorInfo

   Bases: :py:obj:`caikit.core.model_management.job_base.JobInfo`


   JobPredictorInfo is a remap of JobInfo but for predictors


.. py:class:: ModelFinderBase(config: aconfig.Config, instance_name: str)

   Bases: :py:obj:`caikit.core.toolkit.factory.FactoryConstructible`


   A class can be constructed by a factory if its constructor takes exactly
   one argument that is an aconfig.Config object and it has a name to identify
   itself with the factory.


   .. py:attribute:: __doc__
      :value: Multiline-String

      .. raw:: html

         <details><summary>Show Value</summary>

      .. code-block:: python

         """
         A ModelFinder is responsible for finding models based on a unique input string
         which may be a path, id, or other identifier.
         
         Configuration for ModelFinders lives under the config as follows:
         
         model_management:
             finders:
                 <finder name>:
                     type: <finder type name>
                     config:
                         <config option>: <value>
         """

      .. raw:: html

         </details>




   .. py:method:: find_model(model_path: str, **kwargs) -> Optional[caikit.core.modules.ModuleConfig]
      :abstractmethod:


      Find any model that can be uniquely identified by the given (logical)
      path. If found, return the in-memory ModuleConfig.

      Args:
          model_path (str): The logical path to the model (name, id, file
              path, etc...)
          **kwargs: All finders must allow additional kwargs through so that
              specific finders and loaders can support additional optional
              arguments.

      Returns:
          result (Optional[ModuleConfig]): If found, the in-memory config
              object for the model. If the model cannot be found, an exception
              may be raised or None returned.



.. py:class:: ModelInitializerBase(config: aconfig.Config, instance_name: str)

   Bases: :py:obj:`caikit.core.toolkit.factory.FactoryConstructible`


   A class can be constructed by a factory if its constructor takes exactly
   one argument that is an aconfig.Config object and it has a name to identify
   itself with the factory.


   .. py:attribute:: __doc__
      :value: Multiline-String

      .. raw:: html

         <details><summary>Show Value</summary>

      .. code-block:: python

         """
         A ModelInitializer is responsible for taking an in-memory ModuleConfig and
         producing a usable Module instance.
         
         Configuration for ModelInitializers lives under the config as follows:
         
         model_management:
             initializers:
                 <initializer name>:
                     type: <initializer type name>
                     config:
                         <config option>: <value>
         """

      .. raw:: html

         </details>




   .. py:method:: init(model_config: caikit.core.modules.ModuleConfig, **kwargs) -> Optional[caikit.core.modules.ModuleBase]
      :abstractmethod:


      Given a ModelConfig, attempt to initialize it for running

      Args:
          model_config (ModuleConfig): The in-memory model config object for
              the model to be loaded
          **kwargs: All loaders must allow additional kwargs through so that
              specific finders and loaders can support additional optional
              arguments.

      Returns:
          model (Optional[ModuleBase]): The in-memory ModuleBase instance that
              is ready to run if successful. If unable to load, an exception
              may be raised, or None may be returned.



.. py:class:: ModelTrainerBase(config: aconfig.Config, instance_name: str)

   Bases: :py:obj:`caikit.core.model_management.job_base.JobBase`


   A class can be constructed by a factory if its constructor takes exactly
   one argument that is an aconfig.Config object and it has a name to identify
   itself with the factory.


   .. py:attribute:: __doc__
      :value: Multiline-String

      .. raw:: html

         <details><summary>Show Value</summary>

      .. code-block:: python

         """
         A Trainer is responsible for managing execution of a training job for a given
         module class
         
         Configuration for ModelTrainers lives under the config as follows:
         
         model_management:
             trainers:
                 <trainer name>:
                     type: <trainer type name>
                     config:
                         <config option>: <value>
         """

      .. raw:: html

         </details>




   .. py:attribute:: ModelFutureBase


   .. py:method:: train(module_class: Type[caikit.core.modules.ModuleBase], *args, save_path: Optional[Union[str, caikit.interfaces.common.data_model.stream_sources.S3Path]] = None, save_with_id: bool = False, model_name: Optional[str] = None, **kwargs) -> ModelFutureBase
      :abstractmethod:


      Start training the given module and return a future to the trained
      model instance



   .. py:method:: get_model_future(training_id: str) -> ModelFutureBase
      :abstractmethod:


      Look up the model future for the given id



   .. py:method:: get_future(job_id: str) -> caikit.core.model_management.job_base.JobFutureBase

      Look up the model future for the given id



   .. py:method:: get_trainer_name(training_id: str) -> str
      :classmethod:


      Un-hash the trainer's instance name from the given training id



.. py:class:: ModelTrainerFutureBase(*args, **kwargs)

   Bases: :py:obj:`caikit.core.model_management.job_base.JobFutureBase`


   Every JobBase implementation must have a JobFutureBase class that can access the
   job information in the infrastructure managed by the task.


   .. py:attribute:: _save_path


   .. py:property:: save_path
      :type: Optional[str]


      If created with a save path, the future must expose it, including
      any injected background id



   .. py:method:: load() -> caikit.core.modules.ModuleBase
      :abstractmethod:


      A model future must be loadable with no additional arguments. Mainly
      useful in train results



   .. py:method:: result() -> caikit.core.modules.ModuleBase

      The result of a model train future is the loaded model



.. py:class:: TrainingInfo

   Bases: :py:obj:`caikit.core.model_management.job_base.JobInfo`