cellmap_flow.models.geometry_cache
==================================

.. py:module:: cellmap_flow.models.geometry_cache

.. autoapi-nested-parse::

   Get a model's geometry without building the model, when possible.

   Sizing an annotation volume needs five numbers: ``read_shape``,
   ``write_shape``, the two voxel sizes, and the output channel count. Reading
   them from ``ModelConfig.config`` costs a full model load -- for a script model
   that executes the config file, which downloads weights, loads adapters, and
   runs a validation forward pass. One measured session spent 43s of a 47s
   "create annotation volume" there, on the dashboard's CPU, for numbers the
   inference server already had.

   Three sources, cheapest first:

   1. a running inference server, which already holds the model;
   2. this cache, keyed so that it invalidates itself when the model changes;
   3. building the model, which then populates the cache. Not for a model
      that runs in its own environment (``models.envs``): its packages are
      there, not here (``build_here``).

   Reading the declarations statically is deliberately *not* among them. The
   script contract allows geometry to depend on the model -- a DaCapo script
   can say ``output_voxel_size = Coordinate(model.scale(voxel_size))`` -- so
   parsing literals would silently produce wrong numbers for those scripts
   rather than failing.



Attributes
----------

.. autoapisummary::

   cellmap_flow.models.geometry_cache.logger
   cellmap_flow.models.geometry_cache.CACHE_PATH
   cellmap_flow.models.geometry_cache.MAX_ENTRIES


Functions
---------

.. autoapisummary::

   cellmap_flow.models.geometry_cache.cache_key
   cellmap_flow.models.geometry_cache.load_cached_geometry
   cellmap_flow.models.geometry_cache.store_geometry
   cellmap_flow.models.geometry_cache.build_here
   cellmap_flow.models.geometry_cache.resolve_model_geometry


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

.. py:data:: logger

.. py:data:: CACHE_PATH

.. py:data:: MAX_ENTRIES
   :value: 200


.. py:function:: cache_key(model_config)

   A key that changes when the model does, or None if we cannot make one.

   Only keys that invalidate themselves are allowed. A script is keyed by
   path and mtime, so editing it misses the cache. A HuggingFace repo is
   keyed by an explicit revision, which is immutable; without one the
   revision is whatever ``main`` points at today, so those are not cached
   rather than risk serving geometry for a model that has since moved.


.. py:function:: load_cached_geometry(model_config)

   Geometry remembered for this exact model, as a geometry_stand_in, or None.


.. py:function:: store_geometry(model_config, config)

   Remember the geometry of a model we just paid to build.

   ``config`` is its ModelConfig.config, or anything with the same
   geometry attributes, a ModelGeometry included.


.. py:function:: build_here(model_config)

   ``model_config.config``, built in this process.

   Refused for a model that runs in another environment (its ``env``, or
   its type's ``default_env``): this process lacks its packages, or has
   other versions of them (the default environment's cellpose 3 for a
   Cellpose-SAM model), so building it here fails or, worse, half-works.
   Its geometry comes from its running server.

   :raises ModelEnvError: the model runs in its own environment.


.. py:function:: resolve_model_geometry(model_name, model_config)

   The five geometry fields, by the cheapest route that can supply them.

   Returns an object exposing ``read_shape``, ``write_shape``,
   ``input_voxel_size``, ``output_voxel_size`` and ``output_channels`` --
   either a stand-in or, on the build path, the real ``ModelConfig.config``.
   Raises ModelEnvError for a model that runs in its own environment when
   neither its server nor the cache knows its geometry.