> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracebloc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring your model

> Upload the model you already have, a Hugging Face folder, a checkpoint, your own code or a model object, and let the SDK convert it into the model file tracebloc trains.

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](https://docs.tracebloc.io/join-use-case/model-optimization.md) 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](https://docs.tracebloc.io/join-use-case/bioinformatics.md).

## 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:

```bash theme={null}
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:

```python theme={null}
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:

1. Recognises the model, reads its **licence** and asks you to confirm it.
2. 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`.
3. Runs the **acceptance check** on the converted model.
4. 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:

```text theme={null}
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:

```python theme={null}
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:

```text theme={null}
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:

```text theme={null}
protein_cnn/
├── net.py      # defines your torch.nn.Module
└── best.pth    # its trained weights (optional)
```

```python theme={null}
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`:

```python theme={null}
user.upload_model("protein_cnn", tokenizer="tokenizer.json", dataset_id="<dataset key>")
```

Your code may import only the [allowed imports](https://docs.tracebloc.io/join-use-case/model-imports.md) 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](https://docs.tracebloc.io/join-use-case/hyperparameters.md#federated-aggregation) |

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:

```text theme={null}
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:

```python theme={null}
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](https://docs.tracebloc.io/join-use-case/hyperparameters.md) and [Start Training](https://docs.tracebloc.io/join-use-case/start-training.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.