Skip to content

hf

lanfactory.hf

HuggingFace Hub integration for LANfactory.

This module provides utilities for uploading trained models to and downloading models from HuggingFace Hub.

Modules:

  • download –

    Download utilities for HuggingFace Hub.

  • model_card –

    Model card utilities for HuggingFace Hub.

  • upload –

    Upload utilities for HuggingFace Hub.

Classes:

Functions:

lanfactory.hf.ModelCardConfig dataclass 

ModelCardConfig(
    tags: list[str] = (lambda: ["lan", "ssm", "hssm"])(),
    library_name: str = "onnx",
    license: str = DEFAULT_LICENSE,
    title: str = "LAN Model",
    description: str = "Likelihood Approximation Network trained with LANfactory.",
    architecture: dict | None = None,
    training: dict | None = None,
    usage_example: str | None = None,
)

Configuration for model card generation.

lanfactory.hf.download_model 

download_model(
    network_type: str,
    model_name: str,
    output_folder: Path,
    repo_id: str = DEFAULT_REPO_ID,
    revision: str | None = None,
    include_patterns: list[str] | None = None,
    exclude_patterns: list[str] | None = None,
    token: str | None = None,
    force: bool = False,
) -> Path

Download a model from HuggingFace Hub.

Parameters:

  • network_type (str) –

    Network type (e.g., "lan", "cpn", "opn").

  • model_name (str) –

    Model name (e.g., "ddm", "angle").

  • output_folder (Path) –

    Local destination folder.

  • repo_id (str, default: DEFAULT_REPO_ID ) –

    HuggingFace repository ID (default: "franklab/HSSM").

  • revision (str | None, default: None ) –

    Specific branch/tag/commit to download (default: main).

  • include_patterns (list[str] | None, default: None ) –

    Glob patterns for files to include.

  • exclude_patterns (list[str] | None, default: None ) –

    Glob patterns for files to exclude.

  • token (str | None, default: None ) –

    HuggingFace API token for private repos.

  • force (bool, default: False ) –

    Whether to overwrite existing files.

Returns:

  • Path –

    Path to the downloaded model folder.

Raises:

lanfactory.hf.generate_readme 

generate_readme(config: ModelCardConfig, model_name: str | None = None) -> str

Generate HuggingFace-compatible README.md content.

Parameters:

  • config (ModelCardConfig) –

    Model card configuration.

  • model_name (str | None, default: None ) –

    Model name to include in usage example.

Returns:

  • str –

    README.md content with YAML frontmatter.

lanfactory.hf.load_model_card_yaml 

load_model_card_yaml(model_folder: Path) -> ModelCardConfig

Load model card configuration from YAML file.

Parameters:

  • model_folder (Path) –

    Path to the model folder containing model_card.yaml.

Returns:

Raises:

lanfactory.hf.upload_model 

upload_model(
    model_folder: Path,
    network_type: str,
    model_name: str,
    repo_id: str = DEFAULT_REPO_ID,
    commit_message: str = "Upload model",
    private: bool = False,
    create_repo: bool = False,
    include_patterns: list[str] | None = None,
    exclude_patterns: list[str] | None = None,
    revision: str | None = None,
    token: str | None = None,
    dry_run: bool = False,
    publish_root_alias: bool = True,
    update_manifest: bool = True,
    require_model_card: bool = False,
    canonical_onnx: Path | None = None,
    overwrite_root: bool = False,
) -> str | None

Upload a trained model to HuggingFace Hub.

Parameters:

  • model_folder (Path) –

    Path to the folder containing trained model artifacts.

  • network_type (str) –

    Network type (e.g., "lan", "cpn", "opn").

  • model_name (str) –

    Model name (e.g., "ddm", "angle").

  • repo_id (str, default: DEFAULT_REPO_ID ) –

    HuggingFace repository ID (default: "franklab/HSSM").

  • commit_message (str, default: 'Upload model' ) –

    Git commit message for the upload.

  • private (bool, default: False ) –

    Whether to create a private repository.

  • create_repo (bool, default: False ) –

    Whether to create the repository if it doesn't exist.

  • include_patterns (list[str] | None, default: None ) –

    Glob patterns for files to include.

  • exclude_patterns (list[str] | None, default: None ) –

    Glob patterns for files to exclude.

  • revision (str | None, default: None ) –

    Branch or tag name for versioning.

  • token (str | None, default: None ) –

    HuggingFace API token.

  • dry_run (bool, default: False ) –

    If True, show what would be uploaded without uploading.

  • publish_root_alias (bool, default: True ) –

    Also publish the canonical ONNX at the repository root under the filename HSSM resolves ({model}{suffix}.onnx). On by default: an upload without it is not consumable by any released HSSM version.

  • update_manifest (bool, default: True ) –

    Read-modify-write manifest.json at the repository root to record this network.

  • require_model_card (bool, default: False ) –

    Fail when model_card.yaml is absent instead of generating one from the artifact pickles.

  • canonical_onnx (Path | None, default: None ) –

    Explicit choice of the ONNX artifact to publish at the root; inferred from the folder when its name corroborates model_name.

  • overwrite_root (bool, default: False ) –

    Allow replacing a root network that is already published. Off by default: every released HSSM downloads root filenames from main without pinning a revision, so replacing one changes the likelihood for all existing users.

Returns:

  • str | None –

    URL of the uploaded model, or None if dry_run is True.

Raises: