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:

• ModelCardConfig –

  Configuration for model card generation.

Functions:

• download_model –

  Download a model from HuggingFace Hub.

• generate_readme –

  Generate HuggingFace-compatible README.md content.

• load_model_card_yaml –

  Load model card configuration from YAML file.

• upload_model –

  Upload a trained model to HuggingFace Hub.

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:

• ImportError –

  If huggingface_hub is not installed.

• ValueError –

  If network_type is not valid.

• FileExistsError –

  If output_folder exists and force is False.

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:

• ModelCardConfig –

  Parsed model card configuration.

Raises:

• FileNotFoundError –

  If model_card.yaml is not found in the model folder.

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:

• ImportError –

  If huggingface_hub is not installed.

• FileNotFoundError –

  If model_folder doesn't exist or is missing required files.

• ValueError –

  If network_type is not valid.

Public constants

Export	Value	Contract
DEFAULT_REPO_ID	franklab/HSSM	Default artifact repository used by Hub helpers
DEFAULT_LICENSE	bsd-2-clause	License metadata used for generated model cards
VALID_NETWORK_TYPES	lan, cpn, opn, gonogo	Network types accepted by Hub publication helpers

Public helpers

• load_model_card_yaml reads model-card metadata.
• generate_readme renders a model card from metadata.
• ModelCardConfig stores model-card metadata and defaults.
• upload_model publishes a trained artifact and its metadata.
• download_model retrieves a published network artifact.

The installed upload-hf and download-hf entry points, including every flag and safety default, are documented in the command-line reference.

For the task-oriented publication sequence, see Share trained networks on Hugging Face Hub.