Bring your model

You don’t have to rewrite a model to train it on tracebloc. From your own notebook, pass the model you already have to user.upload_model(): the SDK recognises it, converts it into the model file the platform trains, checks that the converted model is still yours, and uploads it. A model file that already passes the upload checks is uploaded unchanged. For protein, DNA, molecule, pathology and omics models, see Models for bioinformatics.

What you can bring

Your model	What to pass to `upload_model`
A Hugging Face folder	The folder `save_pretrained` writes, or a model repository you downloaded: `config.json` and its weights. A text model also needs its tokenizer files, such as `tokenizer.json` or `vocab.txt`.
A checkpoint of a torchvision or timm model	The checkpoint file: `.pt`, `.pth`, `.ckpt`, `.bin` or `.safetensors`. timm models convert for Image classification only.
Your own code	A folder, `.zip` or repository with the Python files that define your PyTorch model, and its checkpoint if you have one.
A model object in your notebook	The object itself, when its class is defined in your code or notebook. For a Hugging Face model, save it with `save_pretrained` and pass the folder.
A fitted scikit-learn, XGBoost, LightGBM or CatBoost model	The pickled model, for the tabular tasks.

The use case decides the task. A pretrained model always fine-tunes for the use case’s task: its backbone keeps its weights and, for a task with classes, a new head is built for the use case’s classes.

Install the training versions

Conversion runs on your machine, with the same library versions training uses. Install the SDK with the training extra, on Python 3.11, 3.12 or 3.13:

python -m pip install --upgrade pip
pip install "tracebloc[training]>=1.2.82"

The training extra installs exactly the versions of torch, transformers, timm, scikit-learn and the other training libraries that the training images run. When yours differ, conversion stops, names each library with both versions, and tells you to install the training versions. Use a fresh virtual environment, so the extra doesn’t change the libraries your other projects use.

Upload your model

Sign in, then upload your model with the use case’s dataset key as dataset_id. The dataset key is on the use case’s Overview, under Start training. It tells the SDK the use case’s task and its number of classes:

from tracebloc import User

user = User()  # prompts for your email and password

user.upload_model("esm2_t6_8M", dataset_id="<dataset key>")

Here esm2_t6_8M is a Hugging Face folder. The SDK:

Recognises the model, reads its licence and asks you to confirm it.
Writes the converted model next to yours, in esm2_t6_8M_tracebloc/: the model file, its weights as SafeTensors, the tokenizer for a text model, and the conversion report tracebloc_conversion.json.
Runs the acceptance check on the converted model.
Uploads the converted model, and prints Licence: MIT (from README.md license); confirmed by … and that the upload was successful.

Your own model is never changed. Upload the same model again and the SDK converts it again into the same folder.

Confirm the licence

The SDK reads the model’s licence from its model card or licence file and, in a notebook, asks:

I may use these weights, under MIT, in a data owner's secure environment. Confirm? [y/N]

When no licence is found, the sentence is I own these weights, or may use them in a data owner's secure environment. Your confirmation is recorded in the conversion report with your name and the time. Outside a notebook, nothing is asked. Confirm in the call instead:

user.upload_model("esm2_t6_8M", dataset_id="<dataset key>", licence_confirmed=True)

Without a confirmation, the converted model is not uploaded, and the SDK says to pass licence_confirmed=True. Weights whose licence forbids redistributing them, such as CC-BY-ND or CC-BY-NC-ND, are stopped before anything uploads:

UNI is licensed CC-BY-NC-ND-4.0 (README.md license), which forbids redistributing the weights; tracebloc's rule for weights under such terms is under review, and until it is decided they are not uploaded

Non-commercial (NC) and share-alike (SA) licences upload once you confirm.

Your own code

Point upload_model at the folder with your model’s Python files, and its checkpoint if it has one:

protein_cnn/
├── net.py      # defines your torch.nn.Module
└── best.pth    # its trained weights (optional)

user.upload_model("protein_cnn", dataset_id="<dataset key>")

The SDK finds your model class, reads its constructor’s values from the checkpoint, your config files, your training script’s arguments or the constructor’s defaults, and generates a model file that builds it. Your files are not changed: the converted model carries a copy of the code your model needs. When your model takes the number of classes as a constructor argument, such as num_classes, the converted model sets it to the use case’s. A text model needs its tokenizer. When your folder doesn’t carry one, pass the model’s tokenizer.json:

user.upload_model("protein_cnn", tokenizer="tokenizer.json", dataset_id="<dataset key>")

Your code may import only the allowed imports of the use case’s task. Imports your model doesn’t use are left out of the copy.

The acceptance check

The converted model is uploaded only when it passes the acceptance check. The check:

confirms the training libraries on your machine are the training versions;
builds the converted model and counts its parameters;
loads your weights into it strictly, every name and shape matching, with only the new head starting fresh;
compares its output with your original model’s on a fixed input: exact, within tolerance, or shapes only when the original can’t be built on your machine;
for a text model, checks that the converted tokenizer gives the same token ids as yours.

The conversion report, tracebloc_conversion.json, lists every value of the model file with where it came from (the model, a file in your repository, the dataset, or a default), the files written, each finding of the acceptance check, and the licence with your confirmation. When the check fails, the SDK says so and names the report.

When a model can’t be converted

Conversion stops before anything uploads, with one line that names the file or package, the reason and what to bring instead. The lines the SDK prints include:

Cause	The SDK says, for example
A package training doesn’t provide	net.py:1 imports `monai`: training does not provide it; the allowed packages are at https://docs.tracebloc.io/join-use-case/model-imports.
A standard-library module that reaches files, processes, the network or code loading	configuration_hyena.py:2 imports `json`: model code may use only plain modules such as typing, functools, math and collections, never file, process, network or code-loading ones
A model that doesn’t take the use case’s input	`EsmForMaskedLM takes text, and a image_classification use case gives images; bring a model built for image_classification`
A model object of a library class	`the object passed to upload_model is transformers.models.esm.modeling_esm.EsmForMaskedLM, a library class; pass a torch.nn.Module whose class is defined in your code or notebook`
A class head the SDK can’t find	`ProteinCNN's class head for a text_classification use case cannot be identified (…); give its constructor a num_classes argument and upload weights trained for the use case's classes, or none`
Library versions other than the training versions	`The model was not converted under the training versions: … Install the training versions: pip install "tracebloc[training]", then convert again.`
A licence that forbids redistributing the weights	The licence stop above
Nothing the SDK recognises	`tracebloc found nothing it can convert in …: no known model family recognises it. Upload a .py or .zip model file with its header instead.`

Models without Python source, such as TorchScript or ONNX files, compiled code, and models only a registry can build can’t be converted either: bring the Python code that defines the model, with its weights as a checkpoint.

Size limits

What	Limit
Weights	Up to 2 GiB upload in one request. Larger weights, up to 7 GiB, upload in 64 MiB parts: the SDK does this by itself.
Converted weights over 2 GiB	The SDK ships them in bf16, which halves their size. The acceptance check then compares outputs within tolerance. Still over 7 GiB in bf16, conversion stops and asks for a smaller model.
Model file	A `.py` file up to 1 MiB, or a `.zip` of `.py` files up to 17 MiB (64 files, 16 MiB unpacked)
Tokenizer	`tokenizer.json` up to 64 MiB
Training a PyTorch model	At most 705M parameters, with `fedavg`, the default aggregation strategy

Each round, federated averaging merges the model’s full weights, and it merges models of up to 705M parameters. An experiment whose PyTorch model is larger is refused when you start it, before anything trains:

This model has 1.3B parameters. Federated averaging merges the full weights of models of up to 705M parameters, so a round of this model cannot be averaged. To train it, choose a model of at most 705M parameters.

A converted text model with more than 300M parameters trains with LoRA unless you turn it off with training_plan.enable_lora(False). LoRA lowers the memory the training needs in the secure environment. It doesn’t raise the 705M limit: each round still averages the model’s full weights. With fedmedian, fedtrimmedavg or krum, which merge every secure environment’s weights at once, the limit depends instead on how many secure environments the experiment trains on: the refusal says how many of the model’s weights it can merge.

Link and train

Link the uploaded model to the use case’s dataset, then configure and start the experiment as for any model:

training_plan = user.link_model_dataset("<dataset key>")

training_plan.experiment_name("ESM-2 8M, first experiment")
training_plan.epochs(3)
training_plan.get_training_plan()
training_plan.start()

When the converted model’s classes or features don’t match the dataset, linking rebuilds it for the dataset and links it in one step. A converted model trains with its own sequence length and image normalisation. Set its batch size with training_plan.batch_size(n). For every training setting, see Hyperparameters and Start Training.

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

What you can bring

Install the training versions

Upload your model

Confirm the licence

Your own code

The acceptance check

When a model can’t be converted

Size limits

Link and train

​What you can bring

​Install the training versions

​Upload your model

​Confirm the licence

​Your own code

​The acceptance check

​When a model can’t be converted

​Size limits

​Link and train

What you can bring

Install the training versions

Upload your model

Confirm the licence

Your own code

The acceptance check

When a model can’t be converted

Size limits

Link and train