xlm.external_models

ExternalModelConflictError

Bases: Exception

Raised when there are conflicts between external models or with core XLM.

discover_external_models()

Discover external model directories.

Each model must be packaged with its configs in the following structure: |-- model.py |-- loss.py |-- predictor.py |-- datamodule.py |-- metrics.py |-- .. |-- setup.py (optional) |-- README.md (optional) |-- configs/ | |-- datamodule/ | |-- experiment/ | |-- .. | |-- ..

The model can be installed as a python package (recommended for sharing) or simply kept as a directory (during development). When installed as a python package, make sure to package the configs as well like so in the setup.py: package_dir={ "": "", }, package_data={ "": ["configs//*.yaml", "configs//*.yml"], }

Discovery:

1. search_dirs: We look for directories that may contain . By default these are the "." (current directory), "xlm-models" (standard xlm-models directory), and the directory specified in the XLM_MODELS_PATH environment variable.
2. Each search_dir may contain multiple directories, hence multiple models. Therefore, we look for a xlm_models.json file in each search_dir that has the following structure:

   {
       "<model_name_1>": "<model_root_dir_1>",
       "<model_name_2>": "<model_root_dir_2>",
       ...
   }
   

   The model root dir path is relative to the search_dir.
3. installed python packages: We also allow discovering models from installed python packages. The package names must be specified in the XLM_MODELS_PACKAGES environment variable as a colon-separated list (e.g., arlm:mlm:ilm:mdlm). The installed package much follow the same structure as the and package the configs as shown above. For the case of python packages, we expect only one model per package.

Parameters:

Name	Type	Description	Default
validate		Whether to run validation on discovered models.	required
strict_validation		If True, raise errors for validation failures. If False, just warn.	required

Returns:

Type	Description
Tuple[Dict[str, Path], Dict[str, Path]]	dict of model_name -> model_root_dir

Raises:

Type	Description
ExternalModelConflictError	If validation fails and strict_validation=True

setup_external_models()

Auto-discover and register external models.

Parameters:

Name	Type	Description	Default
validate		Whether to run validation on discovered models.	required
strict_validation		If True, raise errors for validation failures. If False, just warn.	required

Returns:

Type	Description
List[Path]	List of discovered external model directories.

Raises:

Type	Description
ExternalModelConflictError	If validation fails and strict_validation=True