personalitylinmult.inference.predictor
======================================

.. py:module:: personalitylinmult.inference.predictor

.. autoapi-nested-parse::

   Load a trained FI checkpoint and predict Big Five scores from features.

   A checkpoint is self-describing: :meth:`FiLightningModule.load_from_checkpoint`
   rebuilds the exact model from the ``feature_names`` / ``input_feature_dim`` /
   configs stored in its hyperparameters, so :class:`FiPredictor` needs no external
   metadata — the path alone is enough.

   The predictor is deliberately model-agnostic (the checkpoint decides which
   features it consumes and which traits it emits), so the same class serves the
   audio-only (A) and full multimodal (AVT) models without a code change.



Attributes
----------

.. autoapisummary::

   personalitylinmult.inference.predictor.logger


Exceptions
----------

.. autoapisummary::

   personalitylinmult.inference.predictor.InferenceError


Classes
-------

.. autoapisummary::

   personalitylinmult.inference.predictor.FiPredictor


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

.. py:data:: logger

   Module-level logger.

.. py:exception:: InferenceError

   Bases: :py:obj:`Exception`


   Raised when features do not match what the checkpoint expects.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: FiPredictor(module: personalitylinmult.train.module.FiLightningModule)

   Predicts Big Five trait scores from per-modality features.

   :param module: A loaded, eval-mode Lightning module.
   :type module: FiLightningModule

   .. attribute:: feature_names

      Features this model consumes, in input order.

      :type: list[str]

   .. attribute:: traits

      Trait names, in output-column order.

      :type: list[str]


   .. py:method:: from_checkpoint(path: str | pathlib.Path, map_location: str = 'cpu') -> FiPredictor
      :classmethod:


      Load a predictor from a training checkpoint.

      :param path: Path to a ``.ckpt`` written by training.
      :type path: str | Path
      :param map_location: Device to map tensors onto. ``"cpu"`` keeps
                           inference portable (a demo host rarely has the training GPU).
      :type map_location: str

      :returns: Ready to predict.
      :rtype: FiPredictor

      :raises FileNotFoundError: If the checkpoint does not exist.



   .. py:method:: predict(features: dict[str, numpy.ndarray]) -> dict[str, float]

      Predict Big Five scores for one sample.

      :param features: One ``(T, F)`` array per feature the
                       model expects (see :attr:`feature_names`).
      :type features: dict[str, np.ndarray]

      :returns: ``{trait: score}`` with scores clamped to ``[0, 1]``,
                in the model's trait order.
      :rtype: dict[str, float]

      :raises InferenceError: If the features do not match the model.