docs: model files build locally — hub-referenced models not supported (#1495)

[LukasWodka]

Documents the #1495 contract on the Customize Models page (join-use-case/model-optimization.mdx):

• New "Models build locally (no external hubs)" section: a model file must build its architecture from local code; tracebloc does not fetch models/weights/tokenizers/configs from a hub (HuggingFace) at training time. No from_pretrained("<hub-id>"), no model_id/tokenizer_id/hf_token. Start from pretrained by downloading weights once and uploading them; ship a tokenizer.json for NLP.
• Removes the retired model_id / hf_token additional variables (they now fail upload) and points to the new section.
• Adds the strict weight-load note (uploaded weights load into the architecture your file builds, matching names/shapes).

⚠️ DRAFT — do not merge until the block ships to prod. docs develop auto-deploys to production, and this describes behavior that isn't live until backend#1505 + tracebloc-py-package#380 reach prod. Un-draft + merge once they're deployed.

Refs #1151 · Documents #1495.

🤖 Generated with Claude Code

[saqlainsyed007]

Content LGTM — accurate, and cleanly scoped. Verified:

• Both internal anchors resolve: #use-pre-trained-weights → the existing Use Pre-trained Weights heading, and the self-reference #models-build-locally-no-external-hubs → this new section's heading.
• The retired variables are fully removed — no dangling model_id / hf_token / tokenizer_id references remain anywhere in the doc; the only mentions left are the two that deliberately name them as no-longer-supported.
• The new section documents the #1495 contract at the right place (the canonical Customize Models page), and the strict weight-load Note matches the "build the same architecture" requirement.

Holding the formal approval (commenting, not approving) purely on your own prod-timing gate: docs develop auto-deploys to production, and this describes behavior that isn't live until backend#1505 + tracebloc-py-package#380 reach prod. The content is ready — approve/merge once those are deployed and you un-draft, per your note.

[LukasWodka]

Checked the draft-blocker and it is discharged — but I am leaving this in draft, because verifying the blocker surfaced a claim in the diff that prod does not support.

The stated blocker is gone

Both dependencies are on their prod branches (containment, not just "merged"):

dependency	merge sha	prod branch	result
backend#1505	2c31be9	main	compare/sha...main → ahead by 442 (sha is an ancestor)
tracebloc-py-package#380	d9367a7	master	compare/sha...master → ahead by 99 (sha is an ancestor)

So "un-draft once they're deployed" is satisfied.

Why I did not un-draft it

The diff makes two claims. One is enforced on prod; the other is contradicted by it.

✅ "Models build locally (no external hubs)" — accurate and machine-enforced. There is a real gate: bandit_tracebloc_model_validation/bandit_plugins/tracebloc_model_validation.py rejects *.from_pretrained(...), torch.hub.load, and even getattr(X, 'from_pretrained'), with the message "tracebloc no longer allows hub-referenced models" (:352). This section is correct and worth publishing.

❌ "Removes the retired model_id / hf_token additional variables (they now fail upload)" — not supported. They are still accepted end-to-end on both prod branches:

• SDK, master — tracebloc/link_model_dataset.py:83,102-104 lists model_id, model_id_llm, hf_token, tokenizer_id in the validate_kwargs accepted set, and :116,127-129 assign all four.
• Backend, main — metaApi/models/Experiment.py:467 hf_token = models.CharField(default=settings.TEMP_HF_TOKEN, …) and :339 tokenizer_id; metaApi/serializers/ExperimentSerializer.py:114,143 accept both (hf_token as write_only); common/utils/bus_client_util.py:182 passes hf_token through to the training parameters.

A field with a live serializer entry, a model column, and a pass-through into training parameters is not one that "fails upload". Note model_id is separately the tracebloc model id and always required (the SDK comment at :126 says so explicitly), so removing it from the docs as "retired" would be wrong on a second count.

What I think this means

Either #1495's contract was only half-implemented — the hub-fetch gate landed, the additional-variable rejection did not — or the doc overstated it from the start. I have not diagnosed which, and I would rather say so than guess: the hub gate is clearly real, so this is not a case of nothing shipping.

Suggested split: publish the hub-fetching section (it is accurate and enforced), and drop or reword the additional-variables removal until someone confirms which side is wrong. Happy to make that edit if you agree with the reading — I stopped short of rewriting the diff because which half is authoritative is a product call, not mine.

This does deploy to production docs on merge, which is why I checked rather than trusting the three-week-old body.

[LukasWodka]

Corrected the false half in cb81211 — still a draft, because publishing to production docs is your call, not mine.

I said last pass that I'd stopped short since "which half is authoritative is a product call." On re-reading, that was the wrong place to stop: the claim is measurably false against both prod branches regardless of which half you'd want to be authoritative, so removing a false statement doesn't preempt your decision. Only restoring it would.

What was wrong, in two places

Both said the variables are rejected. They are not:

• SDK master — tracebloc/link_model_dataset.py:83,102-104 lists model_id, model_id_llm, hf_token, tokenizer_id in the accepted validate_kwargs set; :116,127-129 assign all four.
• backend main — Experiment.py:467 hf_token column (default TEMP_HF_TOKEN), :339 tokenizer_id; ExperimentSerializer.py:114,143 accept both; and bus_client_util.py:182 passes hf_token through to the training parameters.

What is actually enforced

The hub fetch, and it's a real gate: bandit_tracebloc_model_validation rejects *.from_pretrained(...), torch.hub.load(...) and the getattr(X, "from_pretrained") route (:21-31, message at :352). Those variable names appear nowhere in that plugin, so nothing refuses a declaration — which is why "must not declare a model_id variable" was overstated too, not just the "no longer supported" note.

The edit

The hub-fetching section is unchanged and now lists the calls that really are refused. The Additional-variables note says the variables are still accepted and simply cannot achieve a hub fetch — which is the actionable fact for someone who has one in a working config and is wondering whether their upload will break. It won't; it just won't do anything.

Anchor #additional-variables verified present; JSX tags balanced (5/5 <Note>, 1/1 <Warning>).

The original draft-blocker is separately discharged: backend#1505 and tracebloc-py-package#380 are both ancestors of their prod branches. So this is accurate and publishable whenever you want it — un-draft and it goes live.

One thing worth a ticket either way: if #1495's intent was to reject those variables at upload, that half never shipped, and the docs describing it as done is how it stays unnoticed. Happy to file that in backend if you want it tracked rather than just corrected here.