Skip to main content

cjm-hf-plugin-utils

Install

pip install cjm_hf_plugin_utils

Project Structure

nbs/
├── cache_config.ipynb # A dataclass mixin adding HuggingFace Hub cache / revision / air-gap / security fields to a plugin's config, with `RELOAD_TRIGGER` + JSON-schema metadata pre-set.
├── download.ipynb     # Wrap `huggingface_hub.snapshot_download` so per-file progress flows to the plugin's `report_progress`, defeating the substrate's stall detector during downloads.
└── loading.ipynb      # Call `model_class.from_pretrained(...)` and convert CUDA OOM into the substrate's typed `PluginResourceError` for CR-7 reactive retry.

Total: 3 notebooks

Module Dependencies

graph LR
    cache_config["cache_config<br/>HF cache config mixin"]
    download["download<br/>Snapshot download with progress"]
    loading["loading<br/>Pretrained loading with typed OOM"]

No cross-module dependencies detected.

CLI Reference

No CLI commands found in this project.

Module Overview

Detailed documentation for each module in the project:

HF cache config mixin (cache_config.ipynb)

A dataclass mixin adding HuggingFace Hub cache / revision / air-gap / security fields to a plugin’s config, with RELOAD_TRIGGER + JSON-schema metadata pre-set.

Import

from cjm_hf_plugin_utils.cache_config import (
    HFCacheConfig
)

Classes

@dataclass
class HFCacheConfig:
    """
    Mixin adding HuggingFace Hub cache/revision/air-gap/security fields to a plugin config.
    
    Compose by inheritance:
    
        @dataclass
        class MyPluginConfig(HFCacheConfig):
            model_id: str = field(default="org/model", metadata={RELOAD_TRIGGER: "model"})
            # ... plugin-specific fields (all defaulted) ...
    
    Each field is `RELOAD_TRIGGER`-tagged `"model"` (a change invalidates a loaded
    model) and carries `SCHEMA_TITLE`/`SCHEMA_DESC` so the plugin-config UI renders
    it. `trust_remote_code` defaults to False and is flagged DANGER in its help text.
    """
    
    cache_dir: Optional[str] = field(...)
    revision: Optional[str] = field(...)
    local_files_only: bool = field(...)
    trust_remote_code: bool = field(...)

Snapshot download with progress (download.ipynb)

Wrap huggingface_hub.snapshot_download so per-file progress flows to the plugin’s report_progress, defeating the substrate’s stall detector during downloads.

Import

from cjm_hf_plugin_utils.download import (
    snapshot_download_with_progress
)

Functions

def snapshot_download_with_progress(
    """
    Download an HF Hub snapshot, streaming per-file progress to `report_progress`.
    
    When `report_progress` is given, a `tqdm_class` subclass forwards each update
    as `report_progress(downloaded / total, "downloading <file>")`. When it is
    None, the default HF Hub progress bars are used unchanged.
    
    Returns the local snapshot directory; subsequent `from_pretrained` calls with
    the same `cache_dir` + `local_files_only=True` hit the populated cache.
    """

Pretrained loading with typed OOM (loading.ipynb)

Call model_class.from_pretrained(...) and convert CUDA OOM into the substrate’s typed PluginResourceError for CR-7 reactive retry.

Import

from cjm_hf_plugin_utils.loading import (
    load_pretrained_with_oom
)

Functions

def load_pretrained_with_oom(
    model_class: Type,            # A class exposing `.from_pretrained(repo_id, **kwargs)`
    repo_id: str,                 # Model repo id or local path passed to from_pretrained
    *,
    label: Optional[str] = None,  # OOM-message context (default: f"loading {repo_id!r}")
    **kwargs,                     # Forwarded verbatim to model_class.from_pretrained
) -> Any:                         # The loaded model
    """
    Call `model_class.from_pretrained(repo_id, **kwargs)`, converting CUDA OOM to a typed error.
    
    On `torch.cuda.OutOfMemoryError`, re-raises as `PluginResourceError` (via
    `cuda_oom_to_plugin_resource_error`) so the substrate's CR-7 reactive-retry
    path can evict + reload + retry. All other exceptions propagate unchanged.
    
    Wrap the call in `self.heartbeat(...)` at the plugin site to cover the silent
    construction phase; pre-download with `snapshot_download_with_progress` for
    real download progress.
    """

Metadata

Release files for cjm-hf-plugin-utils 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cjm-hf-plugin-utils 0.0.1
File Size Uploaded Provenance Actions
cjm_hf_plugin_utils-0.0.1.tar.gz 9.3 kB Without provenance Details for cjm_hf_plugin_utils-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cjm-hf-plugin-utils 0.0.1
File Interpreter ABI Platform Actions
cjm_hf_plugin_utils-0.0.1-py3-none-any.whl Python 3 none any Details for cjm_hf_plugin_utils-0.0.1-py3-none-any.whl

Total release size: 20.9 kB

Release files / cjm_hf_plugin_utils-0.0.1.tar.gz

Download URL cjm_hf_plugin_utils-0.0.1.tar.gz
Size 9.3 kB
Tags Source
SHA-256 checksum
How to use checksums
22b1e66a7150c0fa730c75297b4685dfd7f538a335299a7e9312ddeb6f330e53
BLAKE2b-256 checksum
How to use checksums
58328345feb354406b5a928d9b45b8456224e8806adce321d3789369628fae45
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / cjm_hf_plugin_utils-0.0.1-py3-none-any.whl

Download URL cjm_hf_plugin_utils-0.0.1-py3-none-any.whl
Size 11.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f9bd4a463927a8935d207902113b6467a85e926a16f81f7fe2162ac0082b79e7
BLAKE2b-256 checksum
How to use checksums
9c92cb46cead32bda6c0ed6a488c28bffc00cc0244ac154c41a0c15504ca6e5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for cjm-hf-plugin-utils 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page