segrails.utils
==============

.. py:module:: segrails.utils

.. autoapi-nested-parse::

   Utility helpers for the Segrails library.

   Builds blob paths and APIM URLs from a SegrailsConfig instance,
   and provides device resolution with safe CPU fallback.

   .. rubric:: Example

   >>> from altametris.segrails.config import SegrailsConfig
   >>> from altametris.segrails.utils import get_weight_blob_path, get_apim_weight_url
   >>> config = SegrailsConfig()
   >>> get_weight_blob_path(config, "model.pt")
   'segrails/model.pt'



Functions
---------

.. autoapisummary::

   segrails.utils.get_weight_blob_path
   segrails.utils.get_apim_weight_url
   segrails.utils.resolve_device


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

.. py:function:: get_weight_blob_path(config: altametris.segrails.config.SegrailsConfig, filename: str) -> str

   Build the blob path for a weight file.

   Prepends weights_prefix to the filename when a prefix is configured.

   :param config: Segrails configuration instance.
   :param filename: Weight file name (e.g. "model.pt").

   :returns: Full path in the container (e.g. "segrails/model.pt"),
             or just the filename when no prefix is set.

   .. rubric:: Example

   >>> config = SegrailsConfig(weights_prefix="segrails")
   >>> get_weight_blob_path(config, "model.pt")
   'segrails/model.pt'

   >>> config = SegrailsConfig(weights_prefix="")
   >>> get_weight_blob_path(config, "model.pt")
   'model.pt'


.. py:function:: get_apim_weight_url(config: altametris.segrails.config.SegrailsConfig, filename: str) -> str

   Build the full APIM URL to download a weight file.

   :param config: Segrails configuration instance.
   :param filename: Weight file name (e.g. "model.pt").

   :returns: //apim.example.com/weights/segrails/model.pt").
   :rtype: Full APIM URL (e.g. "https

   :raises ValueError: If api_base_url is not configured.

   .. rubric:: Example

   >>> config = SegrailsConfig(
   ...     api_base_url="https://am-ds-apim-dev.azure-api.net",
   ...     weights_prefix="segrails",
   ... )
   >>> get_apim_weight_url(config, "model.pt")
   'https://am-ds-apim-dev.azure-api.net/weights/segrails/model.pt'


.. py:function:: resolve_device(device: str) -> torch.device

   Resolve a device string to a ``torch.device``, with silent CPU fallback.

   Normalises ``"gpu"`` to ``"cuda"``. If CUDA is requested but unavailable,
   falls back to ``"cpu"`` and logs a warning instead of raising.

   :param device: Device string — ``"cpu"``, ``"cuda"``, ``"gpu"``, or any value
                  accepted by ``torch.device`` (e.g. ``"cuda:0"``).

   :returns: Resolved ``torch.device``.

   .. rubric:: Example

   >>> resolve_device("cpu")
   device(type='cpu')
   >>> # resolve_device("gpu") returns device(type='cuda') when CUDA is
   >>> # available, or device(type='cpu') with a warning otherwise.