altametris.sara.core.base_detector
==================================

.. py:module:: altametris.sara.core.base_detector

.. autoapi-nested-parse::

   Base detector class for inference.

   Provides a common interface for running inference on ML models
   with support for:
   - Model loading
   - Batch and single image prediction
   - Device management
   - Warmup for performance optimization

   .. rubric:: Example

   >>> class MyDetector(BaseDetector):
   ...     def _load_model(self, model_path):
   ...         self.model = torch.load(model_path)
   ...     def predict(self, source, **kwargs):
   ...         return self.model(source)



Attributes
----------

.. autoapisummary::

   altametris.sara.core.base_detector.logger


Classes
-------

.. autoapisummary::

   altametris.sara.core.base_detector.BaseDetector


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

.. py:data:: logger

.. py:class:: BaseDetector(model_path: Union[str, pathlib.Path], device: str = 'auto', warmup: bool = False, **kwargs: Any)

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


   Abstract base class for model inference/detection.

   Provides common inference infrastructure:
   - Model loading and initialization
   - Device management
   - Warmup capability
   - Prediction interface

   :param model_path: Path to model weights
   :param device: Device for inference ("cpu", "cuda", "mps", "auto")
   :param warmup: Whether to run warmup inference on initialization

   .. rubric:: Example

   >>> detector = MyDetector(model_path="weights/best.pt", device="cuda")
   >>> results = detector.predict(source="image.jpg")


   .. py:attribute:: model_path


   .. py:attribute:: _device


   .. py:attribute:: model
      :value: None



   .. py:attribute:: _is_initialized
      :value: False



   .. py:method:: _resolve_device(device: str) -> torch.device

      Resolve device string to torch.device.

      :param device: Device string

      :returns: Resolved torch.device



   .. py:property:: device
      :type: torch.device


      Get current device.


   .. py:property:: is_initialized
      :type: bool


      Check if detector is initialized.


   .. py:method:: _load_model(model_path: pathlib.Path, **kwargs: Any) -> None
      :abstractmethod:


      Load model from path.

      :param model_path: Path to model file
      :param \*\*kwargs: Additional loading arguments

      :raises ModelError: If model cannot be loaded

      .. note:: Must be implemented by subclasses. Should set self.model.



   .. py:method:: predict(source: Any, **kwargs: Any) -> Any
      :abstractmethod:


      Run inference on source.

      :param source: Input source (image path, array, video, etc.)
      :param \*\*kwargs: Inference parameters (conf, iou, etc.)

      :returns: Prediction results (format depends on detector type)

      :raises InferenceError: If prediction fails

      .. note:: Must be implemented by subclasses



   .. py:method:: warmup(iterations: int = 3) -> None

      Warmup the model with dummy inference.

      Useful for GPU models to pre-allocate memory and compile kernels.

      :param iterations: Number of warmup iterations

      .. rubric:: Example

      >>> detector.warmup(iterations=5)



   .. py:method:: validate_source(source: Any) -> None

      Validate input source.

      :param source: Input source to validate

      :raises InferenceError: If source is invalid



   .. py:method:: __call__(source: Any, **kwargs: Any) -> Any

      Callable interface for prediction.

      :param source: Input source
      :param \*\*kwargs: Inference parameters

      :returns: Prediction results

      .. rubric:: Example

      >>> detector = MyDetector(model_path="weights/best.pt")
      >>> results = detector("image.jpg", conf=0.5)



   .. py:method:: __repr__() -> str

      String representation of detector.