Module System

Core

XPM Configxpm_torch.module.Module

Base class for all modules containing parameters

XPM Configxpm_torch.module.ModuleList(*, sub_modules)

Groups different models together, to be used within the Learner

sub_modules: List[xpm_torch.module.Module]

XPM Configxpm_torch.module.ModuleLoader(*, value, settings)

Base class for loading a model from a checkpoint.

Subclasses define their own DataPath fields to specify where model files are stored (e.g. a single path or separate encoder_path and query_encoder_path).

The optional settings field carries opaque metadata (e.g. validation key, checkpoint epoch) that distinguishes loaders with the same model and path.

Override write_hub_extras() and hub_readme_sections() to customize what gets written when the model is exported to HuggingFace Hub.

The model config is accessible via model (alias for value).

value: experimaestro.core.objects.config.Config

The configuration that will be serialized

settings: experimaestro.core.objects.config.Config

Optional metadata (validation info, checkpoint epoch, etc.)

XPM Configxpm_torch.module.SimpleModuleLoader(*, value, settings, path)

Default ModuleLoader with a single path DataPath.

Loads model weights from a checkpoint directory containing either a model/ subdirectory (safetensors) or a model.pth file.

value: experimaestro.core.objects.config.Config

The configuration that will be serialized

settings: experimaestro.core.objects.config.Config

Optional metadata (validation info, checkpoint epoch, etc.)

path: path

Path to the checkpoint directory

class xpm_torch.module.ModuleContainer

A container for Modules, exposing only nn.Module attributes that actually contain state (parameters or buffers).

Example:

class MyRetriever(ModuleContainer):
    def __init__(self):
        super().__init__()
        self.encoder = nn.Linear(128, 64)  # Has params -> wrapped
        self.activ = nn.ReLU()              # No params -> ignored

retriever = MyRetriever()
retriever.setup_with_fabric(fabric)

get_manageable_modules() → Dict[str, Module]

Returns a mapping of attributes that are nn.Modules AND have actual data (params/buffers) to manage.

setup_with_fabric(fabric) → None

Self-identifies which children need Fabric wrapping.

Base Classes

XPM Configxpm_torch.base.Random(*, seed)

Random configuration

seed: int = 0

The seed to use so the random process is deterministic

XPM Configxpm_torch.base.Sampler

Abstract data sampler

XPM Configxpm_torch.base.SampleIterator

Generic class to iterate over items or batch of items

Hooks

XPM Configxpm_torch.context.Hook

Base class for all hooks

XPM Configxpm_torch.context.InitializationHook

Base class for hooks before/after initialization

Parameters

XPM Configxpm_torch.parameters.ParametersIterator

Iterator over module parameters

This can be useful to freeze some layers, or perform any other parameter-wise operation

XPM Configxpm_torch.parameters.RegexParametersIterator(*, negative_regex, regex, model)

Itertor over all the parameters which match the given regex

negative_regex: str

The negative regex expression (should not match)

regex: str

The regex expression

model: xpm_torch.module.Module

The model we want to select the parameters from

XPM Configxpm_torch.parameters.InverseParametersIterator(*, iterator)

Inverse the selection of a parameter iterator

iterator: xpm_torch.parameters.ParametersIterator

XPM Configxpm_torch.parameters.SubParametersIterator(*, model, iterator, default)

Wraps a parameter iterator over a global model and a selector over a subpart of the model

model: xpm_torch.module.Module

The model from which the parameters should be gathered

iterator: xpm_torch.parameters.ParametersIterator

The sub-model iterator

default: bool

Default value for parameters not within the sub-model

XPM Configxpm_torch.parameters.NameMapper

Changes name of parameters

XPM Configxpm_torch.parameters.PrefixRenamer(*, model, data)

Changes name of parameters

model: str

Prefix in model

data: str

Prefix in data

XPM Configxpm_torch.parameters.PartialModuleLoader(*, value, path, selector, mapper)

Allows to load only a part of the parameters

value: experimaestro.core.objects.config.Config

The configuration that will be serialized

path: path

Path containing the data

selector: xpm_torch.parameters.ParametersIterator

The selectors gives the list of parameters for which some

mapper: xpm_torch.parameters.NameMapper

Maps parameter names so it matches so the saved ones

XPM Configxpm_torch.parameters.SubModuleLoader(*, value, path, selector, saved_value)

Allows to load only a part of the parameters (with automatic renaming)

value: experimaestro.core.objects.config.Config

The configuration that will be serialized

path: path

Path containing the data

selector: xpm_torch.parameters.ParametersIterator

The selectors gives the list of parameters for which loaded parameters should be used

saved_value: xpm_torch.module.Module

The original module that is being loaded (optional, allows to map names)

Hub Export Helpers

class xpm_torch.module.ReadmeSection(key: str, content: str, before: str | None = None, after: str | None = None)

A named section for the HF Hub README.

Sections are assembled in order, with optional before/after constraints for positioning relative to other sections.

after: str | None = None

Insert this section after the section with this key.

before: str | None = None

Insert this section before the section with this key.

content: str

Markdown content of this section.

key: str

Unique identifier for this section.

xpm_torch.module.assemble_readme_sections(base: List[ReadmeSection], extra: List[ReadmeSection]) → str

Merge extra sections into base using before/after constraints, then concatenate all contents.

XPM Configxpm_torch.actions.ExportAction(*, loader, default_name)

Export a trained model to HuggingFace Hub or a local directory.

Uses get_hub() to obtain the HF Hub wrapper. Subclass and override get_hub() to use a library-specific hub class (e.g. XPMIRHFHub for xpmir models).

loader: xpm_torch.module.ModuleLoader

The model loader to export

default_name: str

Default HF Hub model name (for pre-fill)

Results

XPM Configxpm_torch.results.TrainingResults(*, models, tb_logs)

Base class for experiment results that can be serialized.

Subclass this in domain-specific libraries (e.g., xpmir’s PaperResults) to add evaluation results and other metadata.

Models should be ModuleLoader instances (not wrappers like ValidationModuleLoader).

models: Dict[str, xpm_torch.module.ModuleLoader]

ModuleLoaders keyed by identifier

tb_logs: Dict[str, path]

Tensorboard log dirs per model (metadata, not part of identity)