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_downloadso per-file progress flows to the plugin’sreport_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 typedPluginResourceErrorfor 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.