Develop

.github/notify-docs.workflow-template.yml

@@ -0,0 +1,33 @@
+# Template — copy into each upstream source repo as
+# .github/workflows/notify-docs.yml
+#
+# Replace <SOURCE_ID> below with the matching `id` from
+# tracebloc/docs:.github/sync-sources.yml
+#
+# Adjust the `paths:` filter if the watched file is not README.md.
+# Adjust `branches:` if the source repo's default branch is not `main`
+# (e.g. some tracebloc repos use `master`).
+#
+# Required: an org-level (or repo-level) secret named DOCS_DISPATCH_TOKEN.
+# - Fine-grained PAT scoped to repo `tracebloc/docs`
+# - Permission: Contents: Read and write (needed to fire repository_dispatch)
+
+name: Notify docs of upstream change
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - "README.md"
+
+jobs:
+ notify:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Trigger docs sync
+ env:
+ GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+ run: |
+ gh api repos/tracebloc/docs/dispatches \
+ -f event_type=upstream-changed \
+ -f 'client_payload[source_id]=<SOURCE_ID>'

.github/sync-sources.yml

@@ -0,0 +1,69 @@
+# Mapping: upstream source files → docs pages
+#
+# Add a new source by appending an entry. The `id` is also used in the
+# source repo's notify workflow (see .github/notify-docs.workflow-template.yml)
+# to tell this repo which mapping changed.
+#
+# Fields:
+# id unique slug for this mapping
+# repo owner/name of the upstream repo
+# ref branch or tag to read from
+# src file path inside the upstream repo
+# dest path in this repo (must exist)
+# private true if the repo is private (requires SOURCE_REPOS_TOKEN)
+# instruction natural-language brief Claude follows when updating dest
+
+sources:
+ - id: tracebloc-package
+ repo: tracebloc/tracebloc-py-package
+ ref: develop
+ src: README.md
+ dest: tools-help/tracebloc.mdx
+ private: true
+ instruction: |
+ Sync the Installation, Key Features, and Quick Start sections to reflect
+ the upstream README. Preserve the page frontmatter and any prose that is
+ unique to the docs page (e.g. links to other Mintlify pages).
+
+ - id: client-setup
+ repo: tracebloc/client
+ ref: main
+ src: README.md
+ dest: environment-setup/setup-guide.mdx
+ private: false
+ instruction: |
+ Sync installer steps, requirements, supported platforms, and verification
+ commands. Preserve the page's narrative framing (numbered top-level steps,
+ requirements table) and any prose unique to the docs page.
+
+ - id: start-training
+ repo: tracebloc/start-training
+ ref: main
+ src: README.md
+ dest: join-use-case/start-training.mdx
+ private: false
+ instruction: |
+ Sync notebook setup and the steps for launching experiments to match the
+ upstream README. Preserve cross-links to other Join-a-Use-Case pages.
+
+ - id: data-ingestors
+ repo: tracebloc/data-ingestors
+ ref: master
+ src: Readme.md
+ dest: create-use-case/prepare-dataset.mdx
+ private: false
+ instruction: |
+ Sync dataset preparation pipeline steps, supported formats, and ingestor
+ configuration from the upstream README. Preserve the page frontmatter and
+ any examples specific to the docs page.
+
+ - id: model-zoo
+ repo: tracebloc/model-zoo
+ ref: master
+ src: README.md
+ dest: create-use-case/templates.mdx
+ private: false
+ instruction: |
+ Sync the list of available model templates and their descriptions from the
+ upstream README. Preserve the page frontmatter and any prose specific to
+ the docs page.

.github/workflows/sync-docs.yml

@@ -0,0 +1,154 @@
+name: Sync docs from upstream
+
+# Triggers:
+# - repository_dispatch: fired by source repos when a watched file changes (push-driven)
+# - workflow_dispatch: manual run from the Actions tab (optional source_id input)
+# - schedule: daily safety-net in case a dispatch is missed
+on:
+ repository_dispatch:
+ types: [upstream-changed]
+ workflow_dispatch:
+ inputs:
+ source_id:
+ description: "Specific source id from sync-sources.yml (leave empty for all)"
+ required: false
+ type: string
+ schedule:
+ - cron: "0 6 * * *"
+
+permissions:
+ contents: write
+ pull-requests: write
+
+concurrency:
+ group: sync-docs
+ cancel-in-progress: false
+
+jobs:
+ sync:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Resolve PR base and accumulate onto existing sync branch
+ id: setup
+ env:
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: |
+ base=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name)
+ echo "base=$base" >> "$GITHUB_OUTPUT"
+ # Snapshot the mapping from the base branch BEFORE possibly switching
+ # to the sync branch, so we never use a stale config from a pending
+ # PR (e.g. if a new source was added on main after the PR opened).
+ cp .github/sync-sources.yml /tmp/sync-sources.yml
+ if git ls-remote --exit-code --heads origin docs/sync-upstream >/dev/null 2>&1; then
+ echo "Existing docs/sync-upstream branch found — checking it out so this run accumulates onto pending changes."
+ git fetch origin docs/sync-upstream:docs/sync-upstream
+ git checkout docs/sync-upstream
+ else
+ echo "No existing sync branch — starting from $base."
+ fi
+
+ - name: Install yq
+ run: |
+ sudo wget -qO /usr/local/bin/yq \
+ https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64
+ sudo chmod +x /usr/local/bin/yq
+
+ - name: Resolve target sources
+ id: filter
+ env:
+ DISPATCH_ID: ${{ github.event.client_payload.source_id }}
+ INPUT_ID: ${{ inputs.source_id }}
+ run: |
+ target="${DISPATCH_ID:-${INPUT_ID:-}}"
+ if [ -n "$target" ]; then
+ echo "Filtering for source: $target"
+ # Pass `target` to yq via env + strenv() so the value never gets
+ # interpolated into the yq expression as a string literal.
+ # Untrusted client_payload / workflow_dispatch input can't break
+ # out of the query or inject yq syntax.
+ TARGET="$target" yq -o=json \
+ '.sources[] | select(.id == strenv(TARGET))' \
+ /tmp/sync-sources.yml | jq -s . > /tmp/sources.json
+ else
+ echo "Processing all sources"
+ yq -o=json '.sources' /tmp/sync-sources.yml > /tmp/sources.json
+ fi
+ count=$(jq length /tmp/sources.json)
+ echo "count=$count" >> "$GITHUB_OUTPUT"
+ echo "Found $count source(s) to process"
+ if [ "$count" = "0" ]; then
+ echo "Nothing to do."
+ fi
+
+ - name: Fetch upstream files
+ if: steps.filter.outputs.count != '0'
+ env:
+ GH_TOKEN: ${{ secrets.SOURCE_REPOS_TOKEN || secrets.GITHUB_TOKEN }}
+ run: |
+ mkdir -p /tmp/sync-cache
+ jq -c '.[]' /tmp/sources.json | while read -r s; do
+ id=$(jq -r .id <<<"$s")
+ repo=$(jq -r .repo <<<"$s")
+ ref=$(jq -r .ref <<<"$s")
+ src=$(jq -r .src <<<"$s")
+ echo "Fetching $repo@$ref:$src -> /tmp/sync-cache/$id"
+ gh api "repos/$repo/contents/$src?ref=$ref" \
+ -H "Accept: application/vnd.github.raw" \
+ > "/tmp/sync-cache/$id"
+ done
+ ls -la /tmp/sync-cache
+
+ - name: Run Claude to update docs
+ if: steps.filter.outputs.count != '0'
+ uses: anthropics/claude-code-action@v1
+ with:
+ anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+ prompt: |
+ You are syncing this Mintlify docs site with upstream README changes.
+
+ The mapping is at `/tmp/sync-sources.yml` (snapshotted from the
+ base branch at the start of this run, so it is always current).
+ The list of sources to process this run is at `/tmp/sources.json`.
+ For each source, the latest upstream file content is at
+ `/tmp/sync-cache/<id>`.
+
+ For every entry in `/tmp/sources.json`:
+ 1. Read `/tmp/sync-cache/<id>` (upstream) and the docs page at `dest`.
+ 2. Apply the entry's `instruction` to update the docs page in place.
+ 3. Preserve YAML frontmatter, page-specific framing, links to other
+ Mintlify pages, and any callouts/components already on the page.
+ 4. Follow `AGENTS.md` style: active voice, second person, sentence
+ case headings, **bold** for UI elements, `code` for paths and
+ commands.
+ 5. If the upstream content does not meaningfully change anything in
+ the docs page, skip that source — do not edit the file.
+
+ Do not edit any files outside the `dest` paths listed in the
+ sources. Do not touch `/tmp/sync-cache/`, `/tmp/sources.json`,
+ or `/tmp/sync-sources.yml`.
+
+ - name: Open or update PR
+ if: steps.filter.outputs.count != '0'
+ uses: peter-evans/create-pull-request@v6
+ with:
+ base: ${{ steps.setup.outputs.base }}
+ branch: docs/sync-upstream
+ delete-branch: true
+ add-paths: "**/*.mdx"
+ commit-message: "docs: sync upstream sources"
+ title: "docs: sync upstream sources"
+ body: |
+ Automated sync from upstream repos via Claude.
+
+ **Triggered by:** `${{ github.event_name }}`
+ **Source filter:** `${{ github.event.client_payload.source_id || inputs.source_id || 'all' }}`
+
+ Review carefully — Claude rewrites prose to fit docs style, but
+ verify accuracy against the upstream README before merging.
+ labels: |
+ docs-sync
+ automated

create-use-case/prepare-dataset.mdx

@@ -1,31 +1,31 @@
 ---
 title: "Prepare Data"
 description: "Learn how to prepare and ingest your datasets into tracebloc using containerized data ingestors. Complete guide for CSV, image, and text data with Kubernetes deployment steps."
 ---
 
 ## Overview
 
 Make your data available to the Kubernetes cluster so it can be used for training and evaluation. Regardless of where your client runs on Azure, AWS, Google Cloud, or a local Minikube setup, the process of ingesting datasets works the same way.
 
 The data ingestor is a lightweight service that bridges your raw data and the cluster's persistent storage. It comes with ready-made templates (CSV, images, text) that you can use as starting points and customize for your own dataset. By containerizing the ingestion step, the ingestor validates data format and schema, enforces consistency, and transfers the dataset securely into cluster's SQL storage where it becomes accessible to all training and evaluation jobs.
 
 This guide covers:
 - Customizing ingestor templates for different data types (CSV, images, text)
 - Deploying the data ingestor for training and test data using Kubernetes
 - Managing datasets through the tracebloc interface
 
 **IMPORTANT** Make sure that the data format and ML task is supported and that data standards are met by reviewing the [docs](/create-use-case/prerequisites). You must run the process twice, once to ingest training and once to ingest testing data.
 
 ## Quick Setup
 
 Use this quick setup if you already have an ingestor configured and just want to switch datasets or toggle between training and testing. If you are setting up for the first time, go to the next section for the detailed walkthrough.
 
 ### Steps
 
 1. Pick a template script and edit it. E.g. `/templates/tabular_classification/tabular_classification.py`
 - Update csv options and data_path
 - Only for tabular data: Update schema
 - Set `schema` and `CSVIngestor()`parameters like category, intent, label_column, etc. to match data type, task and train/test purpose
 
 ```python
 ingestor = CSVIngestor(
@@ -59,9 +59,9 @@
 
 ### 1. Configure a Template
 
 This section walks you through the step-by-step setup of a data ingestor. You will clone the repository, select the right template for your data type, and customize it to match your task. Follow this guide if you are setting up an ingestor for the first time or need full control beyond the quick setup.
 
 ### Clone the Data Ingestor Repository
 
 Clone the public [Data Ingestor GitHub repository](https://github.com/tracebloc/data-ingestors):
 
@@ -126,14 +126,14 @@
  ...
 ```
 
 Both Database, APIClient and other values are configured automatically from the environment variables defined in `ingestor_job.yaml`.
 
 - `config.LABEL_FILE`: Path to local csv label file
 - `config.BATCH_SIZE`: Batch size used during ingestion
 
 ### Customize a Template
 
 Templates provide a starting point, but every dataset has its own format and labels. In this step you adapt the template to your data by tuning CSV ingestion options and setting the ingestor parameters (category, label column, intent, data path and schema). The following example in `templates/tabular_classification/tabular_classification.py` shows how to ingest a tabular dataset, but the setup works the same way for image or text data.
 
 #### Needed for Tabular Data: Define Schema
 
@@ -186,7 +186,7 @@
 ```
 
 #### Set CSV ingestion options
 Customize parsing, memory handling, and data cleaning with the csv_options dictionary:
 
 ```python
 csv_options = {
@@ -201,9 +201,9 @@
 }
 ```
 
 #### Set Up the Ingestor
 
 Define the Ingestor instance with the required configuration. See the tabular data example below:
 
 ```python
 ingestor = CSVIngestor(
@@ -235,7 +235,7 @@
 
 ### Docker Hub Setup (first-time users)
 
 The cluster pulls your ingestor image from a public Docker registry, so you need an account before you can push. If you already have one, skip to [Edit Dockerfile](#edit-dockerfile).
 
 1. **Create a Docker Hub account** at [hub.docker.com/signup](https://hub.docker.com/signup) and verify your email.
 2. **Log in from your terminal** so the `docker push` command can authenticate:
@@ -244,18 +244,18 @@
  docker login
  ```
 
 3. **Push the data ingestor image** to your account using the build/push commands in the next section. The image name takes the form `<your-docker-username>/<image-name>:<tag>` — the username segment must match the account you just created.
 4. **Make the image public** so the cluster can pull it without credentials:
  - Go to [hub.docker.com/repositories](https://hub.docker.com/repositories), open the repository you just pushed.
  - Click **Settings → Visibility settings → Make public**.
 
  Keeping the image private is also fine, but then you must create a Kubernetes `imagePullSecret` named `regcred` in the client namespace (the `ingestor-job.yaml` already references it).
 
 ### Place data files on the client host
 
 Datasets are **not** baked into the Docker image. They live on the client host in the per-workspace data directory and are mounted into the ingestor pod through the shared PVC (`client-pvc` → `/data/shared`).
 
 Copy your dataset into the client's data directory, where `<workspace>` is the workspace name you chose during client install (which is also the Helm release name and the Kubernetes namespace — the chart uses the same value for all three). The directory `~/.tracebloc/<workspace>/data/` is created automatically by the installer; just drop your files into it:
 
 ```bash
 # Host path on the machine where the tracebloc client is installed.
@@ -264,20 +264,20 @@
 cp LOCAL_PATH/labels.csv ~/.tracebloc/<workspace>/data/
 ```
 
 Inside the ingestor pod this directory is mounted at `/data/shared`, so the same files appear as `/data/shared/images/...` and `/data/shared/labels.csv`. Set `SRC_PATH` and `LABEL_FILE` in `ingestor-job.yaml` to point at those in-pod paths (see [Configure Kubernetes](#3-configure-kubernetes) below).
 
 For tabular data the same rule applies — drop the single `labels.csv` (with features and labels) into `~/.tracebloc/<workspace>/data/`.
 
 ### Edit Dockerfile
 
 The Dockerfile only needs to package the ingestion script — the dataset is mounted at runtime, so do **not** `COPY` data into the image:
 
 ```dockerfile
 # Copy the ingestion script into /app
 COPY templates/tabular_classification/tabular_classification.py /app/ingestor.py
 ```
 
 If the cluster enforces the `restricted` Pod Security Standard (see [Run as non-root](#run-as-non-root) below), also add a non-root user to the Dockerfile, **before** the `# Set the entrypoint` line:
 
 ```dockerfile
 RUN groupadd -g 1000 app && \
@@ -292,22 +292,9 @@
 
 ### Build Docker Image
 
-You need a docker user and password to proceed with the next step. Cloud platforms run a mix of x86 and ARM nodes (e.g. AWS Graviton, Azure Ampere, GCP Tau T2A). Building a multi-arch image with `--platform linux/amd64,linux/arm64` guarantees the image runs on either, particularly if you build on Apple Silicon (M1/M2) or other ARM-based systems. Pick a setup, build and deploy the image:
-
-#### For Local Development/Testing
-
-```bash
-# Build for your local platform
-docker build -t <your-username>/<image-name>:<tag> .
-
-# Optional: Push to registry for sharing
-docker push <your-username>/<image-name>:<tag>
-```
-
-#### For Cloud Deployment (AWS, Azure, GCP)
+You need a docker user and password to proceed with the next step. Cloud platforms run a mix of x86 and ARM nodes (e.g. AWS Graviton, Azure Ampere, GCP Tau T2A). Building a multi-arch image with `--platform linux/amd64,linux/arm64` guarantees the image runs on either, particularly if you build on Apple Silicon (M1/M2) or other ARM-based systems. Build and push the image with a single command:
 
 ```bash
-# Build a multi-arch image (works on x86 and ARM cloud nodes) and push directly to the registry
 docker buildx build --platform linux/amd64,linux/arm64 -t <your-username>/<image-name>:<tag> --push .
 ```
 
@@ -389,14 +376,14 @@
 - `image`, your Docker image (imagePullPolicy: Always for DockerHub, IfNotPresent for local)
 - `CLIENT_ID`, `CLIENT_PASSWORD` from the [tracebloc client view](https://ai.tracebloc.io/clients)
 - `TABLE_NAME`, unique per dataset, train and test use different names, no spaces. Different names for train and test data is mandatory
 - `LABEL_FILE`, path inside the ingestor pod (under `/data/shared`) to the CSV with file paths and labels — must match the location of the file you placed in `~/.tracebloc/<workspace>/data/`
 - `SRC_PATH`, root inside the pod where the dataset directory is mounted (`/data/shared`)
 - `BATCH_SIZE` is the number of entries sent to the server per request. Optional — defaults to 4000. Keep it consistent across data types. It depends on available CPU memory, not for example image size. Too large can exhaust memory. It was tested up to 10,000, but 5,000 is a safe default for most systems.
 - `LOG_LEVEL`, "WARNING" for all warnings and errors, "INFO" for all logs, "ERROR" for errors only
 
 ### 4. Deploy
 
 Run the ingestor as a Kubernetes Job:
 
 ```bash
 kubectl apply -f ingestor-job.yaml -n <workspace>
@@ -412,7 +399,7 @@
 
 ### Run as non-root
 
 If the namespace enforces the `restricted` [Pod Security Standard](https://kubernetes.io/docs/concepts/security/pod-security-standards/), `kubectl apply` will be admitted but the pod will be rejected with a warning like:
 
 ```text
 Warning: would violate PodSecurity "restricted:latest":
@@ -438,7 +425,7 @@
  type: RuntimeDefault
 ```
 
 **2. Run the container as a non-root user.** Add the following to the Dockerfile **before** the `# Set the entrypoint` line so the image ships with a UID that satisfies `runAsNonRoot: true`:
 
 ```dockerfile
 RUN groupadd -g 1000 app && \
@@ -450,7 +437,7 @@
 
 Rebuild and push the image, then re-apply the job.
 
 The data ingestor always runs a validation step before ingestion and moving files.
 
 
 #### Verify Deployment
@@ -472,7 +459,7 @@
 **Interface displays:**
 - Dataset name, ID, and record count
 - Data type (Tabular, Image, Text) and purpose (Training/Testing)
 - Namespace and GPU requirements
 
 ## Best Practices
 - Deploy jobs for training and testing simultaneously using different job names

docs.json

@@ -84,7 +84,7 @@
  {
  "group": "Tools & Help",
  "pages": [
- "tools-help/tracebloc-package",
+ "tools-help/tracebloc",
  "tools-help/faqs",
  "tools-help/key-terms"
  ]
@@ -143,10 +143,11 @@
  { "source": "/environment-setup/eks-deployment-guide", "destination": "/environment-setup/eks-client-deployment-guide" },
  { "source": "/environment-setup/architecture", "destination": "/environment-setup/configuration" },
  { "source": "/environment-setup/setup_eks.sh", "destination": "/environment-setup/eks-client-deployment-guide" },
- { "source": "/join-use-case/tracebloc-package", "destination": "/tools-help/tracebloc-package" },
+ { "source": "/join-use-case/tracebloc-package", "destination": "/tools-help/tracebloc" },
+ { "source": "/tools-help/tracebloc-package", "destination": "/tools-help/tracebloc" },
  { "source": "/join-use-case/model-optimisation.md", "destination": "/join-use-case/model-optimization" },
  { "source": "/join-use-case/join-use-case/model-optimisation.md", "destination": "/join-use-case/model-optimization" },
- { "source": "/tracebloc-package/user-linkModelDataset", "destination": "/tools-help/tracebloc-package" },
+ { "source": "/tracebloc-package/user-linkModelDataset", "destination": "/tools-help/tracebloc" },
  { "source": "/experiment/details", "destination": "/join-use-case/explore-use-case" },
  { "source": "/experiment/exp-guide", "destination": "/join-use-case/start-training" },
  { "source": "/collaboration/collaboration-overview", "destination": "/join-use-case/overview" },
@@ -156,7 +157,7 @@
  { "source": "/create-use-case/set-evaluation", "destination": "/create-use-case/evaluate-models" },
  { "source": "/client-setup/setup-requirements", "destination": "/environment-setup/setup-guide" },
  { "source": "/training-guide/jupyter-notebook", "destination": "/join-use-case/start-training" },
- { "source": "/model-requirements/api-supported", "destination": "/tools-help/tracebloc-package" },
+ { "source": "/model-requirements/api-supported", "destination": "/tools-help/tracebloc" },
  { "source": "/model-requirements/model-zoo", "destination": "/create-use-case/templates" },
  { "source": "/FAQ/Collaboration", "destination": "/tools-help/faqs" },
  { "source": "/FAQ/General", "destination": "/tools-help/faqs" },
@@ -172,7 +173,7 @@
  { "source": "/tags/:slug*", "destination": "/overview/tracebloc" },
  { "source": "/blog/authors", "destination": "https://tracebloc.io/blog" },
  { "source": "/blog/archive", "destination": "https://tracebloc.io/blog" },
- { "source": "/tracebloc-package", "destination": "/tools-help/tracebloc-package" }
+ { "source": "/tracebloc-package", "destination": "/tools-help/tracebloc" }
  ],
  "seo": {
  "indexHiddenPages": false

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

@@ -1,11 +1,11 @@
 ---
 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 [open a support ticket](mailto:support@tracebloc.io) — the source of truth is the open client code in [`tracebloc/tracebloc-client`](https://github.com/tracebloc/tracebloc-client).
+If something here does not match what you observe in your run, please [contact us](mailto:support@tracebloc.io) so we can investigate together.
 
 ## Shared lifecycle
 
@@ -13,7 +13,7 @@
 
 <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 +22,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 +34,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 +53,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 — those parts are baked into the platform pipeline and are not configurable from the notebook.
 
@@ -67,18 +67,18 @@
 
 **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 +87,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 +101,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 +156,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 +188,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 +199,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 +211,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 +237,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 +259,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 +275,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 +286,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).
 
 **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 +311,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.** Numeric columns are filled with the **median** of the training split. Categorical columns are filled with the literal string `"Unknown"`. The label column is not imputed.
 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 z-scored (mean 0, standard deviation 1) using training-split statistics; the label column is excluded. On by default and can be turned off.
 
 **Train/validation split**
@@ -326,34 +326,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).
 
 **Input**
 - A tabular file with feature columns plus a continuous target column. The target column name is configurable.
@@ -364,7 +364,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 +374,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.
 
@@ -410,7 +410,7 @@
 **Preprocessing**
 
 - **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 you set in the notebook, default 60), and each target covers the next **forecast horizon** steps (default 1). 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**
@@ -436,8 +436,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.
 
@@ -465,7 +465,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**
@@ -487,26 +487,26 @@
 ## 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.
 
-If your local numbers land within a reasonable band of the platform's, the run reproduced. If they diverge by a meaningful margin, please [open a support ticket](mailto:support@tracebloc.io) — that signals a real mismatch (likely preprocessing, data-slice, or configuration drift) worth investigating together.
+If your local numbers land within a reasonable band of the platform's, the run reproduced. If they diverge by a meaningful margin, please [contact us](mailto:support@tracebloc.io) — that signals a real mismatch (likely preprocessing, data-slice, or configuration drift) worth investigating together.
 </Warning>
 
 To validate a result you saw on the platform:
 
 <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, 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.
@@ -526,5 +526,5 @@
 </Steps>
 
 <Tip>
-The platform code is open source at [`tracebloc/tracebloc-client`](https://github.com/tracebloc/tracebloc-client) — if a number on your end doesn't line up with what the platform reports, please [open a support ticket](mailto:support@tracebloc.io) so we can investigate together.
+If a number on your end doesn't line up with what the platform reports, please [contact us](mailto:support@tracebloc.io) so we can investigate together.
 </Tip>