Initial public ModelForge release

2026-09-01 21:30:16 +02:00
commit 7082ab955a
490 changed files with 104252 additions and 0 deletions
@@ -0,0 +1,44 @@
+# 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.