ML module

Optional machine-learning helpers for HyperCoast.

ModelInfo dataclass

Describe an optional HyperCoast model family.

Parameters:

Name	Type	Description	Default
name	str	Model family name.	required
task	str	Supported inference task.	required
required_extra	str	Package extra needed to use the model.	required
module	str	Import path that provides the implementation.	required

Source code in hypercoast/ml.py

@dataclass(frozen=True)
class ModelInfo:
    """Describe an optional HyperCoast model family.

    Args:
        name: Model family name.
        task: Supported inference task.
        required_extra: Package extra needed to use the model.
        module: Import path that provides the implementation.
    """

    name: str
    task: str
    required_extra: str
    module: str

    def as_dict(self) -> dict[str, Any]:
        """Return serializable model metadata.

        Returns:
            dict: Model metadata.
        """
        return asdict(self)

as_dict(self)

Return serializable model metadata.

Returns:

Type	Description
dict	Model metadata.

Source code in hypercoast/ml.py

def as_dict(self) -> dict[str, Any]:
    """Return serializable model metadata.

    Returns:
        dict: Model metadata.
    """
    return asdict(self)

list_models()

Return optional model metadata.

Returns:

Type	Description
dict	Mapping of model names to metadata.

Source code in hypercoast/ml.py

def list_models() -> dict[str, dict[str, Any]]:
    """Return optional model metadata.

    Returns:
        dict: Mapping of model names to metadata.
    """
    return {name: info.as_dict() for name, info in MODEL_REGISTRY.items()}

load_moe_vae_modules()

Import and return the optional MoE/VAE package namespace.

Returns:

Type	Description
module	hypercoast.moe_vae package.

Source code in hypercoast/ml.py

def load_moe_vae_modules():
    """Import and return the optional MoE/VAE package namespace.

    Returns:
        module: ``hypercoast.moe_vae`` package.
    """
    require_ml_dependencies()
    from . import moe_vae

    return moe_vae

require_ml_dependencies()

Raise a clear error when optional ML dependencies are unavailable.

Exceptions:

Type	Description
ImportError	If PyTorch is not installed.

Source code in hypercoast/ml.py

def require_ml_dependencies() -> None:
    """Raise a clear error when optional ML dependencies are unavailable.

    Raises:
        ImportError: If PyTorch is not installed.
    """
    missing = [name for name in ("torch",) if find_spec(name) is None]
    if missing:
        packages = ", ".join(missing)
        raise ImportError(
            f"HyperCoast ML features require optional dependencies: {packages}. "
            "Install HyperCoast with the 'ml' extra."
        )