release-train: staging -> main

join-use-case/how-training-works.mdx

@@ -1,19 +1,23 @@
 ---
 title: "How training works"
 description: "What the tracebloc client does to your data and model in each use case, so you can reproduce a run locally and compare results."
 ---
 
 This page documents the training and inference pipeline that the tracebloc client runs for every supported use case. The goal is full transparency: you can read what happens step-by-step, write an equivalent script on your own machine against the same dataset, and compare metrics number-for-number against what the platform reports.
 
 If something here does not match what you observe in your run, please [contact us](mailto:support@tracebloc.io) so we can investigate together.
 
+<Note>
+  **TensorFlow is deprecated.** New TensorFlow model uploads are no longer accepted — use **PyTorch** for new models (scikit-learn is also supported where noted). Existing TensorFlow experiments remain readable, so the TensorFlow-specific behavior described below applies only to them.
+</Note>
+
 ## Shared lifecycle
 
 Every use case runs through the same outer loop on the edge:
 
 <Steps>
   <Step title="Resolve the experiment">
     The platform reads your experiment configuration — dataset, hyperparameters, framework choice, training-or-inference mode — and selects the right framework backend (PyTorch, TensorFlow, scikit-learn, lifelines, or scikit-survival).
   </Step>
   <Step title="Load your model">
     Your uploaded model file is fetched and instantiated. For continued cycles and inference, the latest weights from the experiment are loaded into it.
@@ -22,7 +26,7 @@
     The platform loads your raw data, runs the use-case-specific preprocessing, and produces training and validation batches (or a single test set in inference mode).
   </Step>
   <Step title="Configure optimizer and loss">
     Your hyperparameters are normalized, your loss function is constructed, and your optimizer (and learning-rate scheduler, if any) is built — all from the values you set in the notebook.
   </Step>
   <Step title="Run the training loop">
     For each epoch, every training batch goes through forward, loss, backward, and optimizer step. Validation batches run a forward pass only. Per-batch numbers feed into the metrics layer.
@@ -34,7 +38,7 @@
 
 ### Experiment parameters (shared across all use cases)
 
 Every use case below pulls its run-time configuration from the same set of experiment parameters. **You set these values in your Jupyter notebook** when you configure and submit the experiment with the `tracebloc` Python package; the platform deserializes them on the edge before training begins. The same parameter names work the same way across image classification, object detection, segmentation, keypoint detection, text, tabular, time series, and survival use cases — only the subset that applies to a given task is read.
 
 The values that reach the platform are always whatever you set in the notebook. The SDK initializes every parameter to a default at construction time, so even an experiment where you change nothing arrives on the edge with concrete values for every field. When you call a setter (`optimizer("adam")`, `batch_size(64)`, …), the SDK overwrites that field; on `start()` the assembled payload is what the platform receives.
 
@@ -53,7 +57,7 @@
 | All augmentation flags | off | `<flag>(...)` |
 | Pre-trained weights | off | model upload setting |
 
 **Class weighting** is applied automatically by the platform for **image classification** and **tabular classification** only, when your loss function is cross-entropy, NLL, or binary BCE. The formula is described in those sections. Other use cases do not reweight the loss.
 
 To replicate a run locally, read the actual values your experiment was launched with from the experiment view (or your notebook), then match the per-use-case preprocessing and metrics described below. The preprocessing *defaults* are part of the platform pipeline, but the key levers — imputation on/off and strategy, categorical encoding, feature scaling — are configurable per experiment from the notebook (see [Preprocessing on the Hyperparameters page](/join-use-case/hyperparameters#preprocessing-tabular--time-series)), so always replicate with the values your experiment actually ran with.
 
@@ -63,22 +67,22 @@
 
 <Accordion title="Image classification" icon="image">
 
-**Frameworks:** PyTorch, TensorFlow
+**Frameworks:** PyTorch (TensorFlow is deprecated and read-only for existing experiments)
 
 **Input**
 - Image files (JPEG / PNG) supplied through the dataset metadata as `data_id` (the image filename) and `label` (the class name).
 - Class names are mapped to integer indices in the order defined by the dataset's class list, so the same class always lines up with the same logit position across cycles and inference.
 
 **Preprocessing**
 - Images are resized to a square at the size you set in the notebook (default 256). Aspect ratio is **not** preserved — the resize is a direct stretch.
 - Pixel values are normalized using ImageNet mean and standard deviation. You can override the mean and standard deviation in the notebook if your model was pre-trained against different statistics.
 - The augmentation flags you set in the notebook (rotation, shifts, brightness, etc.) drive an image augmentation pipeline that runs on the training split only — validation always sees the unaugmented preprocessing so metrics stay deterministic across epochs. For reference, the SDK only allows the geometric and color augmentation flags to be set on PyTorch experiments — horizontal and vertical flip flags are TensorFlow-only at the SDK level.
 - Train/validation split is **stratified by class label** (so class proportions are preserved on both sides) and uses a deterministic seed. If your chosen split would leave one side empty on a small dataset, it is silently retried with the ratio clamped into a safe range.
 
 **Training step**
 1. Forward pass through the model produces a logit per class.
 2. The loss function you configured in the notebook is used. Cross-entropy is the common choice; if you pick a regression-style loss (such as MSE) the labels are converted to one-hot floats automatically so the shapes line up.
 3. **Class weighting** is applied automatically: for cross-entropy / NLL, each class gets a weight inversely proportional to its training-split frequency (normalized so the weights average to 1, so balanced classes effectively pass through unchanged); for binary BCE, the positive class gets a weight equal to `negative_count / positive_count`. Regression losses like MSE and L1 are not reweighted. This means a verifier who computes loss locally without these weights will see different numbers, especially on imbalanced datasets.
 4. Backward pass and optimizer step.
 5. Per-batch monitoring metric: accuracy — the fraction of images whose predicted class matches the ground-truth class.
 
@@ -87,11 +91,11 @@
 
 **Cycle metrics**
 - **Accuracy family**: accuracy, top-3 accuracy, top-5 accuracy. For datasets with fewer than 3 (or 5) classes, the corresponding top-k accuracy collapses to 1.0 — interpret it accordingly.
 - **Probability-based**: macro-averaged AUC-ROC, macro-averaged AUC-PR, log loss, Brier score (multiclass squared-error form, not the binary sklearn version), quadratic weighted kappa.
 - **Confusion matrix** is produced and surfaced in the run output.
 
 **Inference output**
 - Per image: the predicted class index and the full softmax probability vector. The class-index ordering is the dataset's class list — match this ordering when comparing locally.
 
 </Accordion>
 
@@ -101,34 +105,34 @@
 
 **Input**
 - Images plus per-image annotation files (Pascal VOC-style XML sidecars) listing each object's class name and bounding-box coordinates.
 - Class names are matched case-insensitively against the dataset's class list and mapped to integer indices in the order that list defines.
 
 **Choosing the model family**
 
 You select the model family in the notebook — either an R-CNN family model (Faster R-CNN, Mask R-CNN) or a YOLO family model. The platform branches its training and validation logic on this choice, so it has to be set correctly for your model. If left unset, the platform falls back to inspecting the model name and class for the word "yolo"; if neither matches, it defaults to R-CNN. Picking an unsupported value will fail the run early.
 
 **Preprocessing**
 - Images are resized to a square at the size you set in the notebook (default 416 for R-CNN; for YOLO the platform pins the image size at 448 regardless of what you configure). Aspect ratio is **not** preserved — the resize is a direct stretch, and bounding-box coordinates are rescaled to the same stretched frame. Letterbox padding is **not** used today.
 - Pixel values are scaled to `[0, 1]`. ImageNet mean/std normalization is **not** applied in the object-detection pipeline by default — torchvision R-CNN models normalize internally as part of the model, and YOLO consumes the `[0, 1]` tensor directly.
 - Bounding boxes are validated before training: boxes that fall outside the image, are smaller than 2 pixels on a side, have an extreme aspect ratio, or cover a near-zero area are dropped (along with their labels) so the model never sees degenerate targets.
 - Class labels are **zero-indexed** — the first class in your dataset list is class 0. This differs from torchvision's R-CNN convention where class 0 is reserved for background, so a torchvision pre-trained classifier head cannot be reused as-is.
 - The augmentation flags you set in the notebook drive a joint image-and-bounding-box augmentation pipeline that runs on the training split only. Geometric transforms are applied to the image and to its bounding-box coordinates together so labels stay aligned. Validation always sees the unaugmented preprocessing.
 - Train/validation split is random (non-stratified) and deduplicated by image filename, so all the boxes for a given image stay on the same side of the split. Default split is 85/15.
 
 **Training step**
 
 - **R-CNN family**: the model is run in training mode and returns its internal loss dict (region-proposal, classification, box-regression, objectness). The platform sums these with equal weights and backpropagates. The loss function you set in the notebook is **ignored** for R-CNN — the model defines its own losses.
 - **YOLO family**: the model returns raw grid predictions. The loss is computed by an external loss module supplied alongside your model — the platform does not ship a built-in YOLO loss.
 
 A backward pass and optimizer step follow.
 
 **Per-batch monitoring metrics** (loss-curve only, not the cycle metric)
 - **R-CNN**: an "all boxes correct" rate — an image counts as correct only if every ground-truth box has a predicted box of the same class with IoU above 0.2. Strict criterion; expect low values early in training.
 - **YOLO**: the fraction of grid cells with objectness confidence above 0.5.
 
 **Validation step**
 - For R-CNN, the model is run in evaluation mode and produces a list of per-image predictions (boxes, scores, class labels) directly. No additional non-maximum suppression or score filtering is applied by the platform — whatever thresholds the model was constructed with apply.
 - For YOLO, every grid cell with positive objectness is decoded into a box in pixel coordinates. **Non-maximum suppression is not applied** by the platform on the YOLO path. If you want NMS for a fair local comparison, apply it in your local script with the same thresholds.
 
 **Cycle metrics**
 
@@ -156,29 +160,29 @@
 
 **Preprocessing**
 - The image and mask are resized to a square at the size you set in the notebook (default 256). Aspect ratio is **not** preserved — the resize is a direct stretch.
 - The image uses bilinear resampling; the mask uses **nearest-neighbor** so class indices stay integers. This is the most common reproduction mistake — bilinear on a mask invents non-existent classes.
 - Image pixel values are scaled to `[0, 1]`. ImageNet mean/std normalization is **not** applied by default in the segmentation pipeline.
 - The augmentation flags you set in the notebook drive a joint image-and-mask augmentation pipeline that runs on the training split only. The same geometric transform is applied to the image and to its mask so per-pixel labels stay aligned. Validation always sees the unaugmented preprocessing.
 - Train/validation split is random (non-stratified, deterministic seed). The platform uses your `validation_split` value, with two safety nets: a one-row dataset reuses the same data for train and val instead of crashing, and if your chosen split produces a degenerate partition the run silently retries with 80/20.
 
 **Mask handling**
 
 Mask files are first read as grayscale, even if they are RGB on disk (so a multi-color RGB-encoded mask is effectively flattened before the class-index lookup). The grayscale pixel values are then mapped to class indices:
 
 - **Binary problems (2 classes):** the mask is thresholded at the midpoint of the 8-bit range — pixel values above 127 become class 1, the rest become class 0.
 - **Multi-class problems:** the first `num_classes` sorted unique pixel values in the mask file are treated as the canonical encodings and mapped to `0..N-1` in sorted order. Extra unique values that come from JPEG noise or anti-aliased edges are snapped to the nearest canonical neighbor, so every pixel ends up in `[0, num_classes)`.
 
 A user who encodes their masks differently locally (one-hot, RGB-color → class table, etc.) will not get the same loss numbers. Match this exact mapping when reproducing.
 
 **Training step**
 1. Forward pass through the model. The pipeline accepts either a raw logits tensor or a dict-shaped output (the torchvision FCN / DeepLab family returns one), so torchvision-style models work without adaptation.
 2. The loss function you configured in the notebook is used (cross-entropy is the common choice for segmentation). If no loss is configured, cross-entropy is used as a fallback.
 3. If the model has an auxiliary classifier head (FCN / DeepLab with `aux_loss=True`), the total loss is `main_loss + 0.4 × aux_loss`, matching the torchvision reference recipe. The 0.4 weight is configurable.
 4. Backward pass and optimizer step.
 5. Per-batch monitoring metric: pixel accuracy — the fraction of pixels whose predicted class matches the ground-truth class.
 
 **Validation step**
 - Same forward pass without backward. Predictions are taken as the argmax across the class dimension, producing a per-pixel class-index mask.
 
 **Cycle metrics**
 - **Pixel-level**: pixel accuracy, mean pixel accuracy, IoU, mean IoU, frequency-weighted IoU, Dice
@@ -188,7 +192,7 @@
 - **Per-class IoU**: one number per class that appeared in the cycle
 
 A few definitions worth pinning down for local replication:
 - **IoU** here is the global Jaccard index across all pixels; **mean IoU** is the per-class IoU averaged across classes. They genuinely diverge on imbalanced data — pick the right one for your comparison.
 - **Dice** is macro-averaged across classes, computed on integer-class inputs (not one-hot).
 - **Precision / recall / F1** are macro-averaged across classes.
 
@@ -199,11 +203,11 @@
 
 <Accordion title="Keypoint detection" icon="crosshairs">
 
 **Frameworks:** PyTorch — three model families are supported: R-CNN-style keypoint detectors (KeypointRCNN), heatmap regressors, and direct coordinate regressors.
 
 **Input**
 - Images and per-image keypoint annotations supplied through the dataset metadata. Each keypoint is an `[x, y, visibility]` triple; the visibility component is optional.
 - Keypoints with non-positive x or y are treated as **missing or out-of-frame** — they contribute an all-zero plane in the heatmap target instead of needing a separate mask channel.
 
 **Choosing the model family**
 
@@ -211,24 +215,24 @@
 
 **Preprocessing**
 - Two size knobs that do different things:
   - **Image size for the model**: the size you set in the notebook for what the model actually sees. Default 224. The image is resized to a square at this size, and keypoint coordinates are rescaled by the same factors so they stay aligned with the resized image. Aspect ratio is **not** preserved — the resize is a direct stretch.
   - **PCK reference size**: a separate size used only as the reference scale for the per-batch PCK threshold (the threshold is set to 20% of this size). Default 256. Changing it does not change what the model sees — only how strict the per-batch correctness threshold is.
 - Pixel values are scaled to `[0, 1]`. ImageNet mean/std normalization is **not** applied by default in the keypoint pipeline.
 - For the heatmap family, ground-truth heatmaps are generated as 2D Gaussian peaks centered on each keypoint, at the resized image size, with a fixed standard deviation of 2 pixels. They are generated **after** augmentation so the targets stay aligned with the augmented image.
 - The augmentation flags you set in the notebook drive a joint image-and-keypoint augmentation pipeline that runs on the training split only. The same geometric transform is applied to the image and to its keypoint coordinates so the labels stay consistent.
 - Train/validation split is random (non-stratified) and uses a deterministic seed. Default 85/15. If the split fails on a tiny dataset, the same data is reused for both train and val instead of crashing.
 
 **Training step**
 
 - **R-CNN family**: the model is run in training mode and returns its internal loss dict (region-proposal, classification, box-regression, keypoint losses). The platform sums these with equal weights and backpropagates. The loss function you set in the notebook is **ignored** for R-CNN — the model defines its own losses. A second forward pass in evaluation mode produces the per-image predictions used by the metrics layer.
 - **Heatmap family**: the model returns a heatmap tensor with one channel per keypoint. The loss function you configured in the notebook is applied between predicted and ground-truth heatmaps (mean squared error is the common choice). Per-batch keypoints are recovered by taking the argmax of each predicted heatmap channel.
 - **Direct regression**: the model returns keypoint coordinates directly. The loss function you configured in the notebook is applied between predicted and ground-truth coordinates.
 
 A backward pass and optimizer step follow.
 
 **Per-batch monitoring metric**
 
 Percentage of Correct Keypoints (PCK): the fraction of predicted keypoints whose Euclidean distance to the ground truth is below `0.2 × PCK reference size` (in pixels of the resized image).
 
 **Validation step**
 
@@ -237,16 +241,16 @@
 **Cycle metrics**
 
 - **Detection-style**: precision, recall, F1 — computed from a per-keypoint TP/FP/FN match against a configurable distance threshold.
 - **Position error**: Mean Per-Joint Position Error (MPJPE), the mean Euclidean distance between predicted and ground-truth keypoints in pixels of the resized image. Mean Absolute Error (MAE) is also reported.
 - **COCO-style**: Object Keypoint Similarity (OKS). Per-image scale is derived from the bounding box of the ground-truth keypoints, and per-keypoint sigma defaults to a uniform 0.05.
 - **PCK at multiple thresholds**: `pck@0.05`, `pck@0.1`, `pck@0.2`, `pck@0.3`, `pck@0.5`.
 - **Visibility accuracy**: reported only when your dataset carries a visibility component on each keypoint.
 
 **Inference output**
 
 - **R-CNN**: per-image predicted bounding boxes, confidence scores, class labels, and keypoints.
 - **Heatmap**: per-image heatmap stack; the predicted keypoint per channel is the argmax of that channel.
 - **Direct regression**: per-image `(K, 2)` keypoint coordinates.
 
 </Accordion>
 
@@ -259,15 +263,15 @@
 - The platform looks up `<dataset_path>/<filename>.txt` for each row, so your filenames must match exactly.
 
 **Preprocessing**
 - Each text is tokenized with your configured tokenizer. If you didn't specify one, the platform falls back to your configured model ID, and finally to a default tokenizer.
 - Tokens are padded and truncated to your configured **maximum sequence length** (default 512). Padding happens at tokenization time, so all batches see fixed-shape inputs.
 - **Label-to-index mapping** is fixed in the first training cycle and persisted alongside your weights. Subsequent cycles and inference reuse the same mapping, so the same class always maps to the same logit position. When reproducing locally, use the saved mapping rather than your own ordering.
 - Train/validation split is **stratified by label** with a deterministic seed (default 80/20). If stratification fails because a class has too few examples, the run silently falls back to a non-stratified random split with the same seed.
 
 **Training step**
 
 - **HuggingFace-style models**: the model is called with `input_ids`, `attention_mask`, and `labels`, and returns its own loss. Your notebook's loss function is ignored on this path — the model defines it.
 - **Plain PyTorch models**: the model is called with `input_ids` only and returns logits. The platform applies the loss function you configured in the notebook to compute the training loss. Input dtype is automatically cast to match the model's parameter dtype (float, half, or long).
 
 A backward pass and optimizer step follow. Gradient clipping is applied during the backward pass.
 
@@ -275,7 +279,7 @@
 
 **Validation step**
 
 - Same forward pass without backward. Logits are retained on CPU so the cycle metrics layer can compute probability-based metrics from them.
 
 **Optional model adaptations**
 
@@ -286,23 +290,23 @@
 - **Classification basics** (per-class, macro-averaged): precision, recall, F1.
 - **F1 variants**: F1 macro, F1 micro, F1 weighted.
 - **Agreement metrics**: Matthews correlation coefficient, Cohen's kappa, quadratic weighted kappa.
 - **Other classification**: Hamming loss, Jaccard score (macro), F-beta at β = 0.5 and β = 2.0 (macro), specificity, negative predictive value (binary direct; multiclass macro-averaged), balanced accuracy.
 - **Probability-based**: AUC-ROC (binary on the positive class; multiclass one-vs-rest macro-averaged), AUC-PR (average precision; multiclass macro-averaged over one-hot encodings), Gini coefficient and normalized Gini, log loss, Brier score (multiclass squared-error form).
 - **Top-k accuracy** for problems with more than two classes: top-3 and top-5, reported only when *k* is strictly less than the number of classes.
 - **Confusion matrix**: produced with a fixed label order matching your dataset's class list — pin to that order when comparing locally.
 
 Each metric is computed independently; if one fails (for example, AUC-ROC on a single-class validation slice), it falls back to zero rather than failing the entire cycle.
 
 **Class weighting** is **not** applied automatically for text classification. If your dataset is imbalanced, configure class weights in your loss function from the notebook.
 
 **Inference output**
 - Per text: the predicted class index plus the softmax probability vector. The class-index ordering follows your dataset's class list — match that ordering when comparing locally.
 
 </Accordion>
 
 <Accordion title="Tabular classification" icon="table">
 
-**Frameworks:** PyTorch, TensorFlow, and any scikit-learn-compatible estimator (including XGBoost and LightGBM).
+**Frameworks:** PyTorch and any scikit-learn-compatible estimator (including XGBoost and LightGBM). (TensorFlow is deprecated and read-only for existing experiments.)
 
 **Input**
 - A tabular file with feature columns plus a label column. The label column name is configurable; categorical feature values can be strings.
@@ -311,13 +315,13 @@
 
 The preprocessing pipeline runs in this order, and the full set of fitted statistics (which columns to use, imputation values, category mappings, label-to-index map, scaling means and standard deviations) is **frozen in the first training cycle and reused** in subsequent cycles and at inference. When reproducing a run locally, pull these statistics from the experiment artifacts rather than refitting on your own data slice.
 
 1. **Column selection.** You can configure which columns the model sees from the notebook — either an include list, an exclude list, or derived feature definitions. If you don't configure anything, all columns from the dataset's schema are used.
 2. **Missing value imputation.** On by default and configurable from the notebook: `imputation_strategy(...)` selects the numeric method — `median` (default), `mean`, `most_frequent`, `constant` (fills `0.0`), or `iterative` (MICE, fitted per site on the local training split). Categorical columns are filled with the literal string `"Unknown"` (or the per-column mode under `most_frequent`). The label column is never imputed. `handle_missing_values(False)` — or `imputation_strategy('none')` — disables the step entirely and hands raw NaNs to the model: the right setting when your model owns its own missing-data handling (an sklearn `Pipeline` with an imputer, or a native-NaN model like XGBoost/LightGBM/CatBoost). `knn` is deliberately not offered: a fitted KNN imputer memorizes raw training rows, which would leave the secure environment inside the preprocessing artifact.
 3. **Binary encoding.** Columns with exactly two distinct values that look like booleans (`Y`/`N`, `YES`/`NO`, `TRUE`/`FALSE`, `1`/`0`, plus literal Python booleans) are auto-encoded to `0`/`1` integers. The truthy and falsy strings are configurable.
 4. **Categorical encoding.** Two strategies, configurable from the notebook:
    - **Label encoding** (default): each distinct string in a categorical column maps to a small integer based on the order it first appears in the training split. Categories not seen during training map to `-1` at inference.
    - **One-hot encoding**: each distinct string becomes its own `0`/`1` column.
 5. **Label-to-index mapping.** Class labels are mapped to integer indices in the order defined by your dataset's class list, so a class always lines up with the same logit position. By default, encountering a label that isn't in the class list fails the run; this strict check is configurable.
 6. **Numeric feature scaling.** Numeric feature columns are scaled using training-split statistics; the label column is excluded. On by default (`normalize_features(False)` turns it off) and z-scored by default; `scaler(...)` selects another scikit-learn scaler (`MinMaxScaler`, `RobustScaler`, `MaxAbsScaler`, `Normalizer`, `PowerTransformer`). `QuantileTransformer` is not offered — its fitted state memorizes per-feature value tables, which would leave the secure environment inside the preprocessing artifact.
 
 **Train/validation split**
@@ -326,34 +330,34 @@
 
 **Training step**
 
 - **PyTorch and TensorFlow**: a forward pass produces a logit per class. The loss function you configured in the notebook is applied; cross-entropy is the typical choice. A backward pass and optimizer step follow.
 - **scikit-learn**: training is a single `fit(X, y)` call per batch using the estimator's built-in objective. There is no separate forward / backward pass and no notebook-configured loss on this path.
 
 **Class weighting** is applied automatically across all three frameworks. For cross-entropy and similar log-likelihood losses, each class is weighted in inverse proportion to its training-split frequency, normalized so the weights average to 1 — so balanced datasets effectively pass through unchanged, and imbalanced ones get the rarer classes upweighted.
 
 **Per-batch monitoring metric**: accuracy — the fraction of rows whose predicted class matches the ground-truth class.
 
 **Validation step**
 
 - Same forward pass without backward. Predictions and raw logits are retained so the cycle metrics layer can compute probability-based metrics from them.
 
 **Cycle metrics**
 
 - **Classification basics** (per-class, macro-averaged): precision, recall, F1.
 - **Other classification metrics**: balanced accuracy, F-beta at β = 0.5 and β = 2.0 (macro), Matthews correlation coefficient, Cohen's kappa, quadratic weighted kappa, Hamming loss, Jaccard score (macro), specificity, negative predictive value (binary direct; multiclass macro-averaged).
 - **Probability-based** (when raw logits are available): AUC-ROC (binary on the positive class; multiclass one-vs-rest macro), AUC-PR (average precision; multiclass macro over one-hot), Gini coefficient and normalized Gini, Brier score (multiclass squared-error form).
 - **Confusion matrix**: produced with a fixed label order matching your dataset's class list — pin to that order when comparing locally.
 
 Each metric is computed independently; if one fails, it falls back to zero rather than crashing the cycle.
 
 **Inference output**
 - Per row: the predicted class index plus the predicted probability vector (softmax for multiclass, sigmoid for binary). The class-index ordering follows your dataset's class list — match that ordering when comparing locally.
 
 </Accordion>
 
 <Accordion title="Tabular regression" icon="chart-line">
 
-**Frameworks:** PyTorch, TensorFlow, and any scikit-learn-compatible regressor (including XGBoost and LightGBM).
+**Frameworks:** PyTorch and any scikit-learn-compatible regressor (including XGBoost and LightGBM). (TensorFlow is deprecated and read-only for existing experiments.)
 
 **Input**
 - A tabular file with feature columns plus a continuous target column. The target column name is configurable.
@@ -364,7 +368,7 @@
 The feature pipeline is the same as tabular classification — column selection (or full schema if you don't configure one), median / `"Unknown"` imputation, binary encoding, categorical encoding (label or one-hot), and z-scoring of numeric feature columns. There are two regression-specific differences:
 
 - **Label-to-index mapping is skipped.** The target stays numeric.
 - **Target scaling.** By default, the target column is also z-scored using training-split statistics (mean and standard deviation). The platform stores the scaling parameters alongside your weights and **inverse-transforms** predictions and labels back to the original target scale before computing cycle metrics — so the reported error numbers are in your data's original units, not in the z-scored space the loss is computed in. Target scaling can be turned off from the notebook; if you turn it off but leave feature scaling on, and your target has a much wider range than your scaled features, you'll see a warning in the run log because the loss will dominate strangely.
 
 The fitted preprocessing state (column choices, imputation values, category mappings, feature scaling stats, target scaling stats) is **frozen in the first training cycle and reused** in subsequent cycles and at inference.
 
@@ -374,8 +378,8 @@
 
 **Training step**
 
 - **PyTorch and TensorFlow**: a forward pass produces a continuous prediction per row (or per timestep, for sequence-shaped outputs — the platform takes the last timestep). The loss function you configured in the notebook is applied; MSE is the typical default, with MAE, smooth L1, and Huber as common alternatives. A backward pass and optimizer step follow. Gradient clipping is applied **only when the global gradient norm exceeds 10**, then clipped to 10 — so well-behaved training runs see no clipping and unstable runs are kept from blowing up.
 - **scikit-learn**: training is a single `fit(X, y)` call using the estimator's built-in objective. The platform fits the estimator **once** in the first training batch of the first cycle; subsequent cycles only run prediction. If you want a sklearn regressor that actually updates across federated cycles, choose one that supports incremental / warm-start fitting.
 
 **Per-batch monitoring metric**: R² (coefficient of determination), accumulated from the running residual sum of squares and target variance.
 
@@ -409,9 +413,9 @@
 
 **Preprocessing**
 
 - **Missing value imputation.** On by default, with the same `handle_missing_values` / `imputation_strategy` notebook knobs as the tabular use cases: feature columns are forward-filled in timestamp order (each gap takes the most recent earlier observation), and a leading gap with no earlier observation falls back to a per-column statistic fitted on the training window (median by default, honoring your configured strategy). The timestamp and target columns are never imputed — a missing target stays your data-quality signal. The fitted fallback statistics are persisted alongside the scalers and reused across cycles and at inference.
 - **Feature and target scaling.** Both the feature columns and the target column are scaled using statistics fit on the training window only, then re-applied to the validation window and to inference data. The choice of scaler is configurable from the notebook (Min-Max scaling or standard z-scoring); Min-Max is the default. The fitted scaler instances are persisted alongside your weights and reused in subsequent cycles and at inference, so a federated run keeps a consistent scale across cycles.
 - **Sliding-window construction.** From the chronologically ordered, scaled rows the platform builds sliding-window samples: each input is a sequence of length **sequence length** (the lookback window), and each target covers the next **forecast horizon** steps. Both values come from your model template's declarations or your notebook settings; when neither sets them, the platform defaults apply — **sequence length 25** and **forecast horizon 1**. Model templates commonly declare their own window and override those defaults, so read the values your experiment actually ran with from the experiment view. With a single-step horizon the target is scalar; with a longer horizon it's a vector of that length.
 - **Auto-adjusted sequence length.** If your training or validation window is too short to fit even one full lookback-plus-horizon sample, the platform shortens the sequence length to the largest feasible value rather than crashing, and logs a warning. Forecast horizon is never silently shrunk — that's part of your experiment contract.
 
 **Train/validation split**
@@ -437,8 +441,8 @@
 - **Standard error metrics**: mean absolute error, mean squared error, root mean squared error, max absolute error.
 - **Goodness of fit**: R² (returns NaN on degenerate slices, e.g. constant targets).
 - **Percentage errors**: mean absolute percentage error (skips rows whose true value is near zero), median absolute percentage error (robust to outliers), symmetric MAPE.
 - **Direction accuracy**: the percentage of consecutive timestep pairs where the predicted change has the same sign as the actual change — a "did the model get the trend right" metric.
 - **Theil's U**: a normalized error statistic comparing predicted vs. actual change between consecutive steps. Lower is better.
 
 Each metric is wrapped in error handling — degenerate inputs return NaN rather than failing the cycle.
 
@@ -452,10 +456,10 @@
 **Frameworks:** PyTorch
 
 **Input**
 - A table where each row is one timestep of a sequence: a `sequence_id` column (which sequence the row belongs to), a `timestamp` column (temporal order within the sequence — a SQL timestamp or a numeric step index), one or more feature columns, and a `label` column.
 - The class is a property of the **whole sequence**, not of a single row: `label` must be constant across all rows of a `sequence_id`. This is validated before training — a sequence carrying two different labels fails the run instead of training on corrupted targets.
 - The sample unit everywhere in this use case is **one sequence**: the train/validation split, the batches, the class counts, the metrics, and the predictions all count sequences, never rows.
 - Class labels are mapped to integer indices in the order defined by the dataset's class list, so the same class always lines up with the same logit position across cycles and inference. A label outside the class list fails the run.
 
 **Preprocessing**
 
@@ -463,11 +467,11 @@
 
 1. **Per-sequence missing-value imputation.** Each feature column is forward-filled *within its own sequence* in timestamp order — a gap takes the most recent earlier observation from the same sequence, never from another sequence and never from the future. A **leading gap** (a missing value with no earlier observation in its sequence) falls back to a per-column statistic fitted on the training split: the median for numeric columns (if you configured a different numeric imputation strategy in the notebook, its statistic is used instead; strategies that don't reduce to a per-column statistic fall back to the median here), and the most frequent observed value for categorical columns. `sequence_id`, `timestamp`, and `label` are never imputed. Imputation is on by default and can be turned off from the notebook, in which case raw missing values pass through to the model unchanged.
 2. **`sequence_id` and `timestamp` are set aside** before the feature pipeline runs and re-attached unchanged after it — they are never encoded or scaled, so timestamps don't get z-scored and sequence ids never end up in the feature matrix.
 3. **Binary and categorical encoding.** Same behavior as tabular classification: the feature set defaults to every column in the dataset's schema, two-valued boolean-like columns are auto-encoded to `0`/`1`, and categorical string columns are label-encoded (default) or one-hot encoded — the encoding strategy is configurable from the notebook.
 4. **Numeric feature scaling.** Numeric feature columns are scaled using training-split statistics with the scaler configured in the notebook — the same `scaler` parameter the forecasting use case uses, Min-Max unless you change it; z-scoring and other scikit-learn scalers are selectable. The label column is excluded. Scaling is on by default and can be turned off from the notebook.
 5. **Sequence assembly — scale first, then pad.** After scaling, rows are grouped by `sequence_id` and sorted by `timestamp`, and every sequence becomes exactly one fixed-length sample of **sequence length** timesteps (the notebook parameter shared with the forecasting use case; when neither your model template nor the notebook sets it, the platform default of **25** applies, though templates commonly declare their own — read the value your experiment ran with from the experiment view). Shorter sequences are **zero post-padded** (real timesteps first, zero rows after); longer sequences are **tail-keep truncated** (the most recent timesteps survive). Padding is applied *after* scaling, so padding zeros never pass through the scaler and a model can recover the padding mask by treating all-zero timestep rows as padding. Unlike forecasting, the sequence length is never auto-shrunk on short data — it is part of your experiment contract and identical across secure environments, which federated weight averaging requires.
 
 The model therefore sees batches of shape `(batch, sequence length, features)` as float32 with one int64 class label per sequence, and is expected to return one logit per class for each sequence.
 
 **Train/validation split**
 
@@ -475,8 +479,8 @@
 
 **Training step**
 
 1. Training batches are drawn with a **weighted random sampler**: each sequence is weighted inversely to its class frequency and drawn with replacement, so minority-class sequences are oversampled toward class-balanced batches. This is the platform's class-imbalance mechanism for this use case — the **loss is not reweighted** (unlike image and tabular classification), and no synthetic samples are generated. A local run with a plain shuffled loader will see a different batch composition, and different loss curves, on imbalanced data.
 2. The forward pass produces a logit per class for each sequence. Models that emit per-timestep outputs of shape `(batch, length, classes)` are collapsed to the last timestep; 1-D outputs are lifted to a single-logit column.
 3. The loss function you configured in the notebook is applied; cross-entropy is the typical choice. BCE-style losses get one-hot (or reshaped single-column) float targets, and regression-style losses (MSE, L1, smooth L1) get float or one-hot targets so the shapes line up.
 4. Backward pass and optimizer step. Gradient clipping is applied **only when the global gradient norm exceeds 10**, then clipped to 10 — well-behaved runs see no clipping. A non-finite loss skips the weight update for that batch, and a mini-batch reduced to a single sequence is skipped entirely (it would crash batch-normalization layers in training mode).
 
@@ -484,22 +488,22 @@
 
 **Validation step**
 
 - Same forward pass without backward, over an unshuffled loader that sees every validation sequence exactly once — the weighted sampler applies to training only. Raw logits are retained so the cycle metrics layer can compute the probability-based metrics.
 - Predictions are the argmax over the class logits; a binary model that emits a single logit is thresholded at sigmoid > 0.5.
 
 **Cycle metrics**
 
 The metric suite is identical to tabular classification — per-sequence labels and logits have the same shape as per-row tabular ones — with every number computed over sequences:
 
 - **Classification basics** (per-class, macro-averaged): precision, recall, F1.
 - **Other classification metrics**: balanced accuracy, F-beta at β = 0.5 and β = 2.0 (macro), Matthews correlation coefficient, Cohen's kappa, quadratic weighted kappa, Hamming loss, Jaccard score (macro), specificity, negative predictive value (binary direct; multiclass macro-averaged).
 - **Probability-based** (computed from the retained logits): AUC-ROC (binary on the positive class; multiclass one-vs-rest macro), AUC-PR (average precision; multiclass macro over one-hot), Gini coefficient and normalized Gini, Brier score (multiclass squared-error form).
 - **Confusion matrix**: produced with a fixed label order matching your dataset's class list — pin to that order when comparing locally.
 
 Each metric is computed independently; if one fails, it falls back to zero rather than crashing the cycle.
 
 **Inference output**
 - Per sequence: a predicted class index (argmax over the class logits; sigmoid > 0.5 for a single-logit binary model). The preprocessing artifact saved during training is replayed as-is — nothing is refit on the test slice — and the full cycle-metric suite above, including the confusion matrix, is reported over the test set.
 
 </Accordion>
 
@@ -522,7 +526,7 @@
 
 **Training step**
 
 - **PyTorch**: the model takes the feature matrix and produces a single risk score per row (higher = worse prognosis). The loss is **Cox partial log-likelihood** — a survival-specific loss that ranks each observed event against everyone who was still at risk at that event time. The loss is hardcoded for this use case; the loss function you configured in the notebook is ignored on this path because Cox is the only canonical choice. A backward pass and optimizer step follow. Gradient clipping is applied **only when the global gradient norm exceeds 10**, then clipped to 10 — Cox loss can spike on small batches when one event dominates the risk set, but well-behaved batches see no clipping.
 - **Lifelines / scikit-survival**: a single `fit` call on the full training slice, using the estimator's own optimization. There is no separate forward / backward pass.
 
 **Validation step**
@@ -544,15 +548,15 @@
 ## Reproducing a run locally
 
 <Warning>
 **Expect small variation, even with everything matched.** Two runs of the same script on the same data on the same machine can produce slightly different metric values — that's a property of modern deep-learning stacks, not a tracebloc-specific quirk. Reproducing a tracebloc run on your own machine compounds the same effects, so plan to compare numbers within a tolerance band (typically the second or third decimal place for accuracy-style metrics, a few percent for percentage errors), not exactly.
 
 Common reasons numbers move:
 
 - **Hardware differences.** GPU vs CPU, different GPU models, and different CUDA / cuDNN versions execute the same operations through different kernels. Sums of floating-point numbers are not associative, so reductions on different hardware can produce slightly different last-decimal-place values.
 - **GPU non-determinism.** Several common operations (some convolution backward passes, some scatter/gather kernels, atomic accumulation) are not deterministic by default — running the same forward/backward twice on the same GPU can produce different gradients.
 - **Library versions.** Different versions of PyTorch, TensorFlow, scikit-learn, and torchmetrics can change defaults, fix bugs, or alter numerical paths in ways that move the final numbers a little.
 - **Data-loader worker timing.** When the data loader uses multiple worker processes, the order batches actually arrive in can depend on process scheduling — different orderings produce slightly different gradient sequences and slightly different end-of-epoch state, even with the same shuffle seed.
 - **Federated averaging.** A tracebloc run trains across multiple federated cycles in which model weights are averaged across edges between cycles. A single-machine local run cannot reproduce that averaging step exactly — for multi-cycle and multi-edge experiments, the platform's cycle-end weights and your local cycle-end weights will diverge after the first averaging round.
 - **Stateful layers.** Batch normalization's running statistics, dropout masks, and any other stochastic layer state depend on batch order and initialization, both of which are sensitive to the points above.
 - **Mixed precision.** If your local run uses different mixed-precision settings than the platform did, you'll see small differences from rounding alone.
 
@@ -563,7 +567,7 @@
 
 <Steps>
   <Step title="Take the same data slice">
     Use the same dataset and the same train/validation split ratio you configured. Match the split strategy for your use case — stratified by label for image and tabular classification, deduplicated by image for object detection, temporal (no shuffle) for time-series forecasting, sequence-level and stratified by sequence label for time-series classification, and so on.
   </Step>
   <Step title="Apply the same preprocessing">
     Match the preprocessing described in the section for your use case — especially feature scaling, target scaling (for regression and time series), and categorical encoding, all of which materially shift loss values. For use cases where the preprocessing state is frozen in the first cycle (tabular, time series, time-to-event), pull the saved statistics from your experiment artifacts rather than refitting on your slice.

join-use-case/hyperparameters.mdx

@@ -1,8 +1,12 @@
 ---
 title: "Hyperparameters"
 description: "Configure your model's training behavior by setting hyperparameters, training parameters, and augmentation options."
 ---
 
+<Note>
+  **TensorFlow is deprecated.** New TensorFlow model uploads are no longer accepted — use **PyTorch** for new models. The TensorFlow-specific optimizers, learning-rate schedules, loss functions, layer freezing, and augmentation flags documented below apply only to existing TensorFlow experiments, which remain readable.
+</Note>
+
 ## Training Parameters
 
 All parameters are set through the `training_plan` after linking your model with the dataset.
@@ -28,15 +32,15 @@
 | **Batch Size** | Number of samples processed at one time. Set automatically from the `batch_size` variable in your model file | Datatype dependent <br></br> 16 in most cases | Set via `batch_size = 16` in your model `.py` file |
 | **Validation Split** | Percentage of dataset used for validation (0-1) | Dataset dependent <br></br> 20% in most cases | `training_plan.validation_split(0.2)` |
 
 ## Core Hyperparameters
 
 ### 1. Optimizer
 
 Controls how the model's parameters are updated during training. Supports different optimizers for TensorFlow and PyTorch. The default optimizer is SGD for both PyTorch and TensorFlow.
 
 **Supported Optimizers:**
 - **TensorFlow**: adam, rmsprop, sgd, adadelta, adagrad, adamax, nadam, ftrl
 - **PyTorch**: adam, rmsprop, sgd, adadelta, adagrad, adamax
 
 ```python
 training_plan.optimizer('rmsprop')
@@ -70,8 +74,8 @@
 Defines how the model measures prediction errors. Supports standard and custom loss functions. It is implemented similarly to the built-in [loss function](https://www.tensorflow.org/api_docs/python/tf/keras/losses) in TensorFlow.
 
 **Supported Loss Functions:**
 - **TensorFlow**: binary_crossentropy, categorical_crossentropy, mse, custom loss functions
 - **PyTorch**: crossentropy, mse, l1
 
 ```python
 # Standard loss function
@@ -115,7 +119,7 @@
 |----------|---------|------------|---------|
 | **Early Stopping** | Stop training when metric stops improving | metric, patience | `training_plan.early_stop_callback('loss', 10)` |
 | **Reduce LR** | Reduce learning rate when metric plateaus | metric, factor, patience, threshold | `training_plan.reduce_lr_callback('loss', 0.1, 10, 0.0001)` |
 | **Model Checkpoint** | Save model weights at specific intervals | metric, save_best_only | `training_plan.model_checkpoint_callback('val_loss', True)` |
 | **Terminate on NaN** | Stop training if validation loss becomes NaN | None | `training_plan.terminate_on_nan_callback()` |
 
 ## Preprocessing (Tabular & Time Series)
@@ -145,7 +149,7 @@
 training_plan.missingness_indicators(True)
 ```
 
 **When to disable imputation:** if your model embeds its own imputer (an sklearn `Pipeline`) or handles NaNs natively (XGBoost, LightGBM, HistGradientBoosting, CatBoost, EBM), set `handle_missing_values(False)` — otherwise the built-in step fills every gap first and your model never sees a raw NaN.
 
 <Info>
 `knn` imputation and the `QuantileTransformer` scaler are deliberately unavailable: their fitted state memorizes raw training data, which would leave the secure environment inside the preprocessing artifact. `iterative` (MICE) persists only learned coefficients — the same privacy class as model weights.
@@ -161,20 +165,20 @@
 
 | Parameter | Description | Default | Framework Support | Example |
 |-----------|-------------|---------|-------------------|---------|
 | **rotation_range** | Degree range for random rotations. For example, if the rotation_range is set to 2, images will be rotated by a random degree between -2 and 2 | 0 | TensorFlow, PyTorch | `training_plan.rotation_range(2)` |
 | **width_shift_range** | Range for horizontal shifts (float: fraction, int: pixels). If the value is a float less than 1, it represents a fraction of total width; otherwise it represents pixels. Integers represent pixel values from the interval (-width_shift_range, +width_shift_range) | 0.0 | TensorFlow, PyTorch | `training_plan.width_shift_range(0.1)` |
 | **height_shift_range** | Range for vertical shifts (float: fraction, int: pixels). Works like width_shift_range | 0.0 | TensorFlow, PyTorch | `training_plan.height_shift_range(0.1)` |
 | **shear_range** | Shear intensity in degrees in counter-clockwise direction | 0.0 | TensorFlow | `training_plan.shear_range(0.2)` |
 | **zoom_range** | Range for zooming (float or list). If the value is a float, then zoom range is defined as [1-zoom_range, 1+zoom_range]. If the value is a list, it represents the range of zoom | 0.0 | TensorFlow, PyTorch | `training_plan.zoom_range(0.1)`, `training_plan.zoom_range([0.2, 0.8])` |
 | **horizontal_flip** | Randomly flip images horizontally | False | TensorFlow | `training_plan.horizontal_flip(True)` |
 | **vertical_flip** | Randomly flip images vertically | False | TensorFlow | `training_plan.vertical_flip(True)` |
 
 ### Color and Intensity Transformations
 
 | Parameter | Description | Default | Framework Support | Example |
 |-----------|-------------|---------|-------------------|---------|
 | **brightness_range** | Range for brightness shifts (tuple of floats) | None | TensorFlow, PyTorch | `training_plan.brightness_range((0.1,0.4))` |
 | **channel_shift_range** | Range for random channel shifts | 0 | TensorFlow, PyTorch* | `training_plan.channel_shift_range(0.4)` |
 | **rescale** | Rescaling factor for pixel values (float) | None | TensorFlow, PyTorch | `training_plan.rescale(1.0/255.0)` |
 
 *PyTorch: Only supported for RGB images
@@ -183,15 +187,15 @@
 
 | Parameter | Description | Default | Framework Support | Example |
 |-----------|-------------|---------|-------------------|---------|
 | **samplewise_center** | Center each image by subtracting mean | False | TensorFlow | `training_plan.samplewise_center(True)` |
 | **samplewise_std_normalization** | Standardize each image by subtracting the mean and dividing by the standard deviation of pixel values. Calculated individually | False | TensorFlow | `training_plan.samplewise_std_normalization(True)` |
 
 ### Other Parameters
 
 | Parameter | Description | Default | Framework Support | Example |
 |-----------|-------------|---------|-------------------|---------|
 | **fill_mode** | Method for filling points outside boundaries. Supported for TensorFlow: "constant", "nearest", "reflect", "wrap". For PyTorch: "constant", "edge", "symmetric", "reflect", "wrap". | 'constant' | TensorFlow, PyTorch | `training_plan.fill_mode("nearest")` |
 | **cval** | Fill value for points outside the image boundaries when fill_mode="constant" | 0.0 | TensorFlow, PyTorch | `training_plan.cval(0.3)` |
 | **shuffle** | Whether to shuffle the data | True | TensorFlow, PyTorch | `training_plan.shuffle(True)` |
 
 ## LLM Parameters (Text Classification)
@@ -208,10 +212,10 @@
 
 | Parameter | Description | Type | Default | Example |
 |-----------|-------------|------|---------|---------|
 | **lora_r** | Rank for the LoRA layer | Positive integer | 256 | `lora_r=256` |
 | **lora_alpha** | Scaling factor alpha for LoRA | Positive integer | 512 | `lora_alpha=512` |
 | **lora_dropout** | Dropout rate for LoRA layers | Float (0-1) | 0.05 | `lora_dropout=0.05` |
 | **q_lora** | Enable or disable Q LoRA | Boolean | False | `q_lora=False` |
 
 **Note:** LLM parameters are supported only for PyTorch.
 
@@ -223,8 +227,8 @@
 
 | Parameter | Description | Example |
 |-----------|-------------|---------|
 | **training_classes** | Customize dataset by specifying samples per class | `training_plan.training_classes({'car': 30, 'person': 30})` |
 | **data_type** | Image format: 'rgb' or 'grayscale' | `training_plan.data_type('rgb')` |
 | **seed** | Set global random seed | `training_plan.seed(True)` |
 
 

join-use-case/model-optimization.mdx

@@ -1,8 +1,12 @@
 ---
 title: "Customize Models"
 description: "Learn the model format requirements, mandatory variables per framework and pre-trained weights for uploading and training models on the tracebloc workspace."
 ---
 
+<Note>
+  **TensorFlow is deprecated.** New TensorFlow model uploads are no longer accepted — author new models in **PyTorch** or **scikit-learn**. The TensorFlow mandatory variables and TensorFlow file-format examples below are retained only as reference for existing TensorFlow experiments, which remain readable.
+</Note>
+
 ## Use Pre-trained Weights
 
 Upload weights along with your model in the `user.upload_model()` step and set `weights=True`, the default value is False:
@@ -36,39 +40,43 @@
 ### PyTorch mandatory variables
 
 The file must contain these variables:
 * **framework** : name of the framework for which this model file is created. For PyTorch its value will be pytorch.
 * **model_type** : name of the model type for which this model file is created. its value will be either *empty* or *rcnn* or *heatmap* or *yolo*.
 * **main_class** : name of the main class of the model.
 * **image_size** : name of the variable defining the input size considered for creating model layers.
 * **category** : name of the category for which this model file is created. its value will be either of these : *image_classification*, *object_detection*, *keypoint_detection*, *text_classification*.
 * **batch_size** : name of the variable defining the batch size of the images considered for creating model layers.
 
 ### Sklearn mandatory variables
 
 The file must contain these variables:
 * **framework** : name of the framework for which this model file is created. For Sklearn its value will be sklearn.
 * **model_type** : name of the model type for which this model file is created. Its value will be either *empty* or *tree* or *linear* or *knn* or *naive* or *mlp*.
 * **main_class or main_method** : name of the main class or main method of the model. Any one of these is necessary for model.
 * **image_size** : name of the variable defining the input size considered for creating model layers.
 * **category** : name of the category for which this model file is created. Its value will be either of these : *image_classification*, *object_detection*, *keypoint_detection*, *text_classification*.
 * **batch_size** : name of the variable defining the batch size of the images considered for creating model layers.
 
 ### Tensorflow mandatory variables
 
+<Note>
+  Deprecated — retained for existing TensorFlow experiments. New uploads must use PyTorch or scikit-learn.
+</Note>
+
 Each format must contain these variables on the main file:
 * **framework** : name of the framework for which this model file is created. For tensorflow its value will be tensorflow.
 * **model_type** : name of the model type for which this model file is created. Its value will be either *empty* or *rcnn* or *heatmap*.
 * **main_method** : name of the main function
 * **input_shape or image_size** : name of the variable defining the input shape of the model
 * **category** : name of the category for which this model file is created. Its value will be either of these : *image_classification*, *object_detection*, *keypoint_detection*, *text_classification*.
 * **output_classes** : name of the variable defining the output shape of the variables. The value of this variable is equal to the number of classes in the dataset.
 
 ### Additional variables
 
 Some additional variables are required for specific categories
 * **num_feature_points** : number of keypoints or feature points for which this model file is created. This variable is used only for keypoint_detection and generic_classification category.
 * **model_id** : model id using which this model file is created. This variable is used only for text_classification category.
 * **hf_token** : hf token using which this model file is created. This variable is used only for text_classification category.
 
 <Warning>
 * The framework variable is compulsory and should always be placed at the top of your code just after the imports, before any other variable.
@@ -78,7 +86,7 @@
 
 ## Detailed Information on each format
 
 ### 1. Single python file containing one class for pyTorch
 
 All your model code needs to be contained in a **single python file** with the following structure:
 
@@ -131,15 +139,15 @@
 ```
 
 The value of the above variables would look like this:
 * framework = 'pytorch'
 * main_method = 'Net'
 * image_size = 224
 * batch_size = 16
 
 
 An example model file of this format can be found [here](https://github.com/tracebloc/model-zoo/blob/master/model_zoo/image_classification/pytorch/CNN.py).
 
 ### 2. Single python file containing one class for sklearn
 
 All your model code needs to be contained in a **single python file** with the following structure:
 
@@ -165,13 +173,17 @@
 ```
 
 The value of the above variables would look like this:
 * framework = 'sklearn'
 * main_method = 'MyModel'
 * image_size = 224
 * batch_size = 16
 
 ### 3. Single python file containing one/multiple methods for tensorflow
 
+<Note>
+  Formats 3 and 4 (TensorFlow) are deprecated and retained only for existing TensorFlow experiments. New uploads must use the PyTorch or scikit-learn formats above.
+</Note>
+
 All your model code needs to be contained in a **single python file** with the following structure:
 
 
@@ -248,9 +260,9 @@
 
 The value of the above variables would look like this:
 * framework = 'tensorflow'
 * main_method = 'MyModel'
 * input_shape = 'input_shape'
 * output_classes = 'classes'
 
 
 ### 4. Single python file having no method for tensorflow
@@ -308,9 +320,9 @@
 
 The value of the above variables would look like this:
 * framework = 'tensorflow'
 * main_method = ''
 * input_shape = 'input_shape'
 * output_classes = 'classes'
 
 Add the mandatory variables at the top of the file (after imports) to get a complete model file ready for upload.
 

join-use-case/overview.mdx

@@ -1,10 +1,10 @@
 ---
 title: 'Overview'
 description: 'Learn how the tracebloc AI workspace works: explore use cases, train models on private data, and submit models to the leaderboard.'
 sidebar_position: 0
 ---
 
 tracebloc is an AI workspace where you can train and evaluate models on datasets you never directly access. The data stays with the data owner, your code runs on their infrastructure, and a leaderboard ranks every submission side by side.
 
 
 Here is how it works, step by step.
@@ -25,18 +25,22 @@
 
 ## 3. Set up and train
 
 You work from a Jupyter notebook on your local machine or Google Colab. The notebook connects to the tracebloc workspace, where you upload a model, link it to the dataset, configure hyperparameters, and start training. Your model code executes on the data owner's infrastructure. You never download or see the raw data.
 
 → [Start Training](/join-use-case/start-training)
 
 ## 4. Customize your model
 
-You can use any architecture: PyTorch, TensorFlow, or sklearn. The easiest way to get started is the [tracebloc model zoo](https://github.com/tracebloc/model-zoo), a collection of starter templates you can modify freely. Pick a template, adjust it to your needs, and upload. The only requirement is that a few mandatory variables at the top of your model file match the use case parameters.
+You can use any architecture: PyTorch or sklearn. The easiest way to get started is the [tracebloc model zoo](https://github.com/tracebloc/model-zoo), a collection of starter templates you can modify freely. Pick a template, adjust it to your needs, and upload. The only requirement is that a few mandatory variables at the top of your model file match the use case parameters.
+
+<Note>
+  TensorFlow is deprecated: new TensorFlow model uploads are no longer accepted. Use PyTorch (or sklearn) for new models. Existing TensorFlow experiments remain readable.
+</Note>
 
 
 → [Customize Models](/join-use-case/model-optimization)
 
 ## 5. Tune hyperparameters
 
 Configure optimizers, learning rates, loss functions, callbacks, data augmentation, and LoRA parameters for LLM fine-tuning. All parameters are set through the notebook before or between training runs.
 
@@ -44,7 +48,7 @@
 
 ## 6. Evaluate and submit
 
 Once training is complete, you select your best performing cycle and submit it for evaluation on the test dataset. Your score appears on the leaderboard, ranked against all other teams. Submissions are limited daily to prevent overfitting.
 
 → [Evaluate Model](/join-use-case/model-evaluation)
 

overview/tracebloc.mdx

@@ -1,5 +1,5 @@
 ---
 title: "tracebloc"
 description: "Build better AI together. Without moving data."
 mode: "default"
 ---
@@ -8,7 +8,7 @@
   ![Traceblocfederatedlearning](/images/traceblocfederatedlearning.png)
 </Frame>
 
 tracebloc is **your collaborative AI workspace** you deploy on your own infrastructure. Invite friends, peers, researchers, partners, vendors — anyone — to train, fine-tune, and benchmark models on your private data. Your data never moves.
 
 <CardGroup cols={3}>
   <Card title="Quick Setup" icon="rocket" href="/environment-setup/setup-guide">
@@ -20,24 +20,24 @@
   </Card>
 
   <Card title="Join a Use Case" icon="users" href="/join-use-case/join-use-case">
     Train and submit models on someone else's data.
   </Card>
 </CardGroup>
 
 <br />
 
 ## What is tracebloc?
 
 tracebloc is a **collaborative AI workspace** you deploy on your own infrastructure. Anyone you invite — researchers, partners, vendors, startups — can train, fine-tune, and benchmark models on your data. Your data never moves. Compliance is solved by architecture.
 
 **Who is it for?** Anyone who asks "which model works best on MY data?" and wants external input without the nightmare of NDAs, data-sharing agreements, and security reviews.
 
 **What makes it different?**
 
 - <Icon icon="server" /> **Your infrastructure:** runs on your Mac, Linux box, GPU server, or any Kubernetes cluster
 - <Icon icon="lock" /> **Your data:** stays inside your network. Contributors never see raw records.
 - <Icon icon="user-plus" /> **Invite anyone:** whitelist contributors by email. They see EDA and metadata. Never raw data.
 - <Icon icon="ranking-star" /> **One leaderboard:** every submission benchmarked under identical conditions. Ship the winner.
 - <Icon icon="shield-check" /> **Compliance by architecture:** data never moves. Sign off once on the architecture, not once per partner.
 
 <br />
@@ -70,20 +70,20 @@
     Whitelist contributors by email. Assign compute budgets. They never see raw data.
   </Step>
   <Step title="Build together">
-    Contributors submit models and train inside your environment. PyTorch, TensorFlow, custom containers.
+    Contributors submit models and train inside your environment. PyTorch, scikit-learn, custom containers.
   </Step>
   <Step title="Compare and decide">
     Every submission benchmarked under identical conditions. One leaderboard. Ship the winner.
   </Step>
 </Steps>
 
 <br />
 
 ## When Should You Use tracebloc
 
 <CardGroup cols={2}>
   <Card title="Vendor Benchmarking" icon="ranking-star">
     5 vendors claim they have the best model. Invite all five to submit. One leaderboard. One week. Decisions based on measured performance — not claims.
   </Card>
 
   <Card title="Cross-Org Research" icon="building">
@@ -113,7 +113,7 @@
   </Card>
 
   <Card title="Explore Workspaces" icon="compass" href="https://ai.tracebloc.io/explore">
     See what builders are creating on tracebloc.
   </Card>
 
   <Card title="Advanced Setup" icon="gear" href="/environment-setup/setup-guide">

tools-help/faqs.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Frequently Asked Questions"
 description: "Common questions about running tracebloc — privacy, infrastructure, training, and getting help."
 ---
 
 ## Privacy & security
@@ -8,19 +8,19 @@
 ### Can the data scientist see my raw data?
 No. Data scientists submit model code; the code runs on your client, against your data, in an isolated sandbox. They only ever see the metrics you decide to expose. Raw data, in-flight model state, and intermediate artifacts never leave your infrastructure.
 
 ### What gets shared with the data scientist or with tracebloc?
 Only the evaluation metrics you configure on the use case (accuracy, F1, latency, and so on). No raw data, no trained weights, no logs.
 
 ### Where do trained model weights end up?
 On your storage. Trained weights stay on the persistent volume claim attached to your client. Data scientists never receive them.
 
 ### Is the client's egress restricted?
 Yes — the chart applies a Kubernetes `NetworkPolicy` that only allows training pods to reach the tracebloc backend (for orchestration metadata) and the in-cluster proxy that handles result and FLOPs reporting. **The egress lockdown only takes effect on a CNI that enforces NetworkPolicy.** EKS's default VPC CNI does not, out of the box — see the [EKS deployment guide](/environment-setup/eks-client-deployment-guide) for what to install.
 
 ## Infrastructure
 
 ### Do I need a GPU?
 For most ML workloads, yes. The standalone installer detects NVIDIA and AMD GPUs and installs the right drivers automatically. CPU-only is fine for small tabular and text models, but expect long training times on anything image- or sequence-heavy.
 
 ### What Kubernetes versions do you support?
 Kubernetes 1.24 and above. See the [setup guide](/environment-setup/setup-guide) for the full prerequisites.
@@ -29,7 +29,7 @@
 Yes. The standalone installer provisions a local cluster on your machine, or you can deploy the unified Helm chart into your existing on-prem Kubernetes. The client never depends on cloud infrastructure for training.
 
 ### Can I install offline or run behind an egress proxy?
 You can install from a packaged chart `.tgz` rather than the public chart repo, and platform traffic can route through your corporate proxy (set `HTTP_PROXY` / `HTTPS_PROXY` before installing). The environment is **outbound-only** — nothing needs to reach *in* — but it does need outbound HTTPS to the tracebloc platform to run experiments, so it is **not** fully air-gapped. What you get instead is defined, auditable ingress and egress: raw data never leaves your infrastructure, and only the results and weights you choose to share are sent out. See the [install guide](https://github.com/tracebloc/client/blob/main/docs/INSTALL.md).
 
 ## Training & models
 
@@ -37,13 +37,13 @@
 Through the [tracebloc dashboard](https://ai.tracebloc.io) — every experiment, every model, every metric. Or query the API if you prefer programmatic access.
 
 ### What if a training run fails?
 The client retries transient failures automatically. Persistent failures show up in the dashboard with logs and exit codes. For ingestion-time failures, check the Job logs in the namespace you deployed into.
 
 ### Can I bring my own model?
-Yes. Use the [tracebloc Python package](/tools-help/tracebloc) to upload a model file (PyTorch, TensorFlow, or a custom container). For ready-made starting points, see the [model zoo](https://github.com/tracebloc/model-zoo).
+Yes. Use the [tracebloc Python package](/tools-help/tracebloc) to upload a model file (PyTorch, scikit-learn, or a custom container). For ready-made starting points, see the [model zoo](https://github.com/tracebloc/model-zoo). TensorFlow is deprecated — new TensorFlow uploads are no longer accepted, though existing TensorFlow experiments remain readable.
 
 ### Do you support fine-tuning?
 Yes — the same upload flow handles full training, fine-tuning with pretrained weights, and inference-only evaluation.
 
 ## Cost & support