ModelForge/docs/architecture/HUGGING_FACE_INTEGRATION.md

Hugging Face Integration

Boundary

M3 integrates the Hub through HuggingFaceProvider. Domain services do not call huggingface_hub directly and ModelForge exposes no arbitrary Hub proxy. The official HfApi client provides search and model_info(..., files_metadata=True, securityStatus=True) metadata. HTML scraping is not used.

The control plane retrieves metadata only. Artifact bytes are fetched by the authenticated, node-scoped artifact worker on the selected compute node. MODELFORGE_HF_TOKEN is optional secret configuration, is never persisted or returned by the API, and is passed only to the API and node agent—not to future runtimes.

Facts and interpretation

Search results and snapshots keep reported repository ID, author, task, library, tags, popularity, access state, card data, scanner data, file tree and source timestamps as upstream facts. Local candidate matching, approval, hardware compatibility and intended capability remain ModelForge interpretation. Missing values stay absent/unknown.

Scanner results are stored as upstream evidence with evidence_only=true; they are never converted into a ModelForge approval. License declarations are captured as unreviewed evidence and no legal conclusion is inferred.

Revision and access semantics

A requested ref such as main is resolved to the exact Hub commit SHA before a ModelRevision or artifact set is created. A later movement of main creates a new immutable revision. Existing revisions and approved plans retain their original SHA.

Access is classified as public, gated, private, inaccessible/not-found, or provider unavailable. Metadata errors are normalized without exposing credentials. Planning a gated/private snapshot without configured credentials fails closed as access-required behavior.

API

• POST /api/v1/discovery/search
• POST /api/v1/models/{id}/refresh-upstream
• GET /api/v1/models/{id}/upstream
• GET /api/v1/revisions/{id}/artifact-sets

The adapter is covered by offline fakes/mocks; the M3 acceptance also refreshed all 15 real candidates against the live Hub.