release: promote develop → main (machine-sizing + Mintlify rebuild + page-coverage CI)

.github/workflows/preview-page-coverage.yml

@@ -0,0 +1,154 @@
+name: Docs preview page coverage
+
+# Verifies that every page declared in docs.json's navigation is reachable
+# (HTTP 200) on both the dev preview and prod docs site.
+#
+# Catches the failure mode from 2026-06-06: Mintlify's incremental builder
+# left tracebloc-develop.mintlify.app with most pages returning 404 for days
+# because the full-page index was wiped and only files touched by subsequent
+# commits got re-rendered. Mintlify's own check reported "deploy success"
+# every time. This workflow probes the actual rendered URLs and fails the
+# build if any page is missing.
+#
+# Trigger:
+#   - schedule:      daily 06:00 UTC (catches Mintlify state drift)
+#   - push:          to develop / main (catches build regressions immediately)
+#   - workflow_dispatch: manual rerun
+#
+# After a push, waits 120s for Mintlify's deploy to complete before probing.
+
+on:
+  schedule:
+    - cron: '0 6 * * *'
+  push:
+    branches: [develop, main]
+  workflow_dispatch:
+    inputs:
+      env:
+        description: "Which environment to probe (default: both)"
+        type: choice
+        options: [both, dev, prod]
+        default: both
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-coverage-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  resolve-env:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.set.outputs.matrix }}
+    steps:
+      - id: set
+        env:
+          CHOICE: ${{ github.event.inputs.env || 'both' }}
+        run: |
+          case "$CHOICE" in
+            dev)  m='[{"name":"dev","url":"https://tracebloc-develop.mintlify.app"}]' ;;
+            prod) m='[{"name":"prod","url":"https://docs.tracebloc.io"}]' ;;
+            both|*) m='[{"name":"dev","url":"https://tracebloc-develop.mintlify.app"},{"name":"prod","url":"https://docs.tracebloc.io"}]' ;;
+          esac
+          echo "matrix=$m" >> "$GITHUB_OUTPUT"
+
+  probe:
+    needs: resolve-env
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        env: ${{ fromJSON(needs.resolve-env.outputs.matrix) }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Wait for Mintlify to deploy (push events only)
+        if: github.event_name == 'push'
+        env:
+          ENV_NAME: ${{ matrix.env.name }}
+        run: |
+          # Mintlify's deploy typically completes in 30-90s after push.
+          # Allow a generous buffer so the probe sees the new state.
+          if [ "$ENV_NAME" = "prod" ] && [ "$GITHUB_REF_NAME" != "main" ]; then
+            echo "Push not to main — prod deploy won't run, skipping wait."
+          elif [ "$ENV_NAME" = "dev" ] && [ "$GITHUB_REF_NAME" != "develop" ]; then
+            echo "Push not to develop — dev deploy won't run, skipping wait."
+          else
+            echo "Waiting 120s for Mintlify ($ENV_NAME) deploy to complete..."
+            sleep 120
+          fi
+
+      - name: Extract every page path from docs.json
+        run: |
+          set -euo pipefail
+          # Walk the entire navigation tree and collect string-valued
+          # page references. docs.json nests pages under .navigation.tabs[]
+          # .groups[].pages[] (which can itself recurse).
+          jq -r '
+            [.. | objects | .pages? | values | .[]?]
+            | map(select(type == "string"))
+            | unique
+            | .[]
+          ' docs.json > /tmp/pages.txt
+          count=$(wc -l < /tmp/pages.txt | tr -d ' ')
+          echo "Found $count pages to probe"
+          if [ "$count" = "0" ]; then
+            echo "::error::No pages found in docs.json — navigation structure may have changed"
+            exit 1
+          fi
+
+      - name: Probe each page on ${{ matrix.env.name }}
+        env:
+          BASE_URL: ${{ matrix.env.url }}
+          ENV_NAME: ${{ matrix.env.name }}
+        run: |
+          set -uo pipefail
+          : > /tmp/broken.csv
+          : > /tmp/ok.csv
+          while IFS= read -r path; do
+            [ -z "$path" ] && continue
+            # Follow redirects (-L); cap each request at 15s.
+            code=$(curl -s -L -o /dev/null -w "%{http_code}" --max-time 15 "$BASE_URL/$path" 2>/dev/null || echo "000")
+            if [ "$code" = "200" ]; then
+              echo "/$path,$code" >> /tmp/ok.csv
+            else
+              echo "/$path,$code" >> /tmp/broken.csv
+              echo "  ✗ /$path -> HTTP $code"
+            fi
+          done < /tmp/pages.txt
+
+          ok=$(wc -l < /tmp/ok.csv | tr -d ' ')
+          broken=$(wc -l < /tmp/broken.csv | tr -d ' ')
+          total=$((ok + broken))
+
+          echo ""
+          echo "═══ Result on $ENV_NAME: $ok/$total ok, $broken broken ═══"
+
+          {
+            echo "## $ENV_NAME page coverage"
+            echo ""
+            echo "**$total pages probed · $ok ok · $broken broken**"
+            echo ""
+            echo "Base URL: \`$BASE_URL\`"
+            echo ""
+            if [ "$broken" -gt 0 ]; then
+              echo "### Broken paths"
+              echo ""
+              echo "| Path | HTTP code |"
+              echo "|---|---|"
+              awk -F, '{print "| `"$1"` | "$2" |"}' /tmp/broken.csv
+              echo ""
+              echo "**Likely cause:** Mintlify incremental builder did not re-render"
+              echo "these paths. Fix by touching every \`.mdx\` in one commit to"
+              echo "force a full rebuild (see PR #55 from 2026-06-06)."
+            else
+              echo "All pages render correctly. ✓"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          if [ "$broken" -gt 0 ]; then
+            echo "::error::$broken pages on $ENV_NAME returned non-200"
+            exit 1
+          fi

create-use-case/define.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Define Use Case"
 description: "Create, configure, and publish an AI use case on tracebloc in four steps."
 ---
 
 This guide walks you through the 4 key steps to create, publish, and manage an AI use case on the tracebloc platform. Make sure you have a [tracebloc client](/environment-setup/setup-guide) running and your data is ingested. Navigate to the [use cases section](https://ai.tracebloc.io/my-use-cases), click on the "+" on the top right corner and simply follow along. Use this documentation for context, clarification and examples when needed.
 
 ## Step 1: Initialize and Set Privacy
 
@@ -26,13 +26,13 @@
 
 ![Data & Evaluation](/images/Step-2-data-&-evalation.avif)
 
 - **Training and test metadataset**: A metadataset is a reference to an ingested dataset that stores summary information such as the number of samples and columns. Select the training and test metadatasets that correspond to the datasets you ingested in the [Prepare Data](/create-use-case/prepare-dataset) step.
 - **Score**: Define which benchmark to use for evaluation (e.g. Accuracy, F1, etc.). In case your evaluation metric is not yet supported, please reach out to us at [support@tracebloc.io](mailto:support@tracebloc.io).
 - **Upload EDA File (Optional)**: Attach a .ipynb EDA file to help participants understand the data context. Explore [template use cases](https://ai.tracebloc.io/explore) for inspiration.
 
 ### Supported Metrics per Data Type and Task
 
 The tables below list all evaluation metrics grouped by task type. Each metric uses either **higher is better** or **lower is better** sort order on the leaderboard.
 
 #### Image Classification
 
@@ -67,7 +67,7 @@
 | Log Loss | Measures how well a model predicts probability estimates for each class. Penalizes overconfident incorrect predictions. | Lower is better |
 | AUC-ROC | Measures ability to distinguish between classes across all thresholds, independent of any single decision threshold. | Higher is better |
 | Hamming Loss | Measures the fraction of labels incorrectly predicted. Commonly used in multi-label classification tasks. | Lower is better |
 | Jaccard Score | Measures similarity between predicted and ground truth labels by comparing their intersection to their union. | Higher is better |
 | Cohen's Kappa | Measures agreement between predicted and ground truth labels while accounting for chance agreement. | Higher is better |
 | Matthews Correlation Coefficient (MCC) | Classification quality using all parts of the confusion matrix. Balanced even with imbalanced classes. Ranges from -1 to 1. | Higher is better |
 | Quadratic Weighted Kappa (QWK) | Measures agreement between predicted and ground truth labels, penalizing larger disagreements more heavily. | Higher is better |
@@ -92,13 +92,13 @@
 | F-beta Score (beta = 0.5) | Balances precision and recall with more emphasis on precision. Suitable when false positives are more costly. | Higher is better |
 | F-beta Score (beta = 2) | Balances precision and recall with more emphasis on recall. Suitable when missing positive instances is more costly. | Higher is better |
 | Hamming Loss | Measures the fraction of labels incorrectly predicted. Commonly used in multi-label classification tasks. | Lower is better |
 | Jaccard Score | Measures similarity between predicted and ground truth labels by comparing their intersection to their union. | Higher is better |
 | Cohen's Kappa | Measures agreement between predicted and ground truth labels while accounting for chance agreement. | Higher is better |
 | Matthews Correlation Coefficient (MCC) | Classification quality using all parts of the confusion matrix. Balanced even with imbalanced classes. Ranges from -1 to 1. | Higher is better |
 | Quadratic Weighted Kappa (QWK) | Measures agreement between predicted and ground truth labels, penalizing larger disagreements more heavily. | Higher is better |
 | Brier Score | Mean squared difference between predicted probabilities and actual outcomes. | Lower is better |
 | Gini Coefficient | Measures discriminatory power between positive and negative classes. Closely related to AUC-ROC. | Higher is better |
 | Normalized Gini | Scales the Gini Coefficient relative to a perfect model, enabling fair comparison across datasets. Ranges from -1 to 1. | Higher is better |
 
 #### Object Detection
 
@@ -145,7 +145,7 @@
 | F1 Score | Balances precision and recall into a single metric. | Higher is better |
 | Loss | Quantifies the error between predicted outputs and actual values. | Lower is better |
 
 #### Keypoint Detection
 
 | Metric | Description | Sort Order |
 |--------|-------------|------------|
@@ -154,15 +154,15 @@
 | F1 Score | Balances precision and recall into a single metric. | Higher is better |
 | Loss | Quantifies the error between predicted outputs and actual values. | Lower is better |
 | Mean Absolute Error (MAE) | Average magnitude of errors between predicted and actual values, expressed in the same units as the target. | Lower is better |
 | PCK (Percentage of Correct Keypoints) | Measures how accurately predicted keypoints fall within a specified distance of ground truth. | Higher is better |
 | PCK@0.05 | Keypoints within a normalized distance threshold of 0.05 from ground truth. Strictest variant. | Higher is better |
 | PCK@0.10 | Keypoints within a normalized distance threshold of 0.10 from ground truth. | Higher is better |
 | PCK@0.20 | Keypoints within a normalized distance threshold of 0.20 from ground truth. | Higher is better |
 | PCK@0.30 | Keypoints within a normalized distance threshold of 0.30 from ground truth. | Higher is better |
 | PCK@0.50 | Keypoints within a normalized distance threshold of 0.50 from ground truth. Most lenient variant. | Higher is better |
 | Object Keypoint Similarity (OKS) | Measures similarity between predicted and ground truth keypoints, accounting for scale and localization uncertainty. | Higher is better |
 | Mean Per Joint Position Error (MPJPE) | Average Euclidean distance between predicted and ground truth joint positions. Standard for pose estimation. | Lower is better |
 | Visibility Accuracy | Measures how correctly the model predicts the visibility status of keypoints, independent of spatial localization. | Higher is better |
 
 #### Tabular Regression
 
@@ -193,7 +193,7 @@
 | Mean Absolute Percentage Error (MAPE) | Average percentage difference between predicted and actual values. Easy to interpret across different scales. | Lower is better |
 | Symmetric Mean Absolute Percentage Error (SMAPE) | Symmetric variant of MAPE that reduces issues when actual values are close to zero. | Lower is better |
 | Median Absolute Percentage Error (MdAPE) | Uses the median of absolute percentage errors. More robust to outliers. | Lower is better |
 | Theil's U (U2 Statistic) | Measures forecasting accuracy relative to a naive benchmark. Values below 1.0 mean the model outperforms the baseline. | Lower is better |
 | Max Error | Captures the single largest absolute difference between predicted and actual values. | Lower is better |
 | Direction Accuracy | Measures how often the model correctly predicts the direction of change (up or down) between consecutive values. | Higher is better |
 
@@ -226,9 +226,9 @@
 
 ### Compute Assignment
 
 Define training budget in PFLOPs.
 Example: 10 participants × 200 PFLOPs each = 2,000 PFLOPs
 Cost Calculation: 2,000 PFLOPs × €0.025 = €50.00
 
 Always allocate more resources than minimum requirements and monitor resource usage regularly. You can stop or adjust training at any time.
 
@@ -246,7 +246,7 @@
 
 - total resource consumption
 - daily submits and user activity
 - overall leaderboard and submissions
 
 Once models have been submitted, you can [compare them in the leaderboard section](/create-use-case/evaluate-models) of a use case.
 
@@ -255,3 +255,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

create-use-case/evaluate-models.mdx

@@ -1,17 +1,17 @@
 ---
 title: "Evaluate models"
 description: "Compare vendor models side by side on the leaderboard."
 ---
 
 Navigate to the Leaderboard section of your use case to compare submitted models, for example the [Breast Cancer Screening Use Case](https://ai.tracebloc.io/explore/ai-breast-cancer-screening-and-image-classification?tab=leaderboard).
 
 ## The Leaderboard
 
 Vendors are ranked by the score of their best performing model. Scores are calculated using the evaluation metric you selected when [defining the use case](/create-use-case/define#supported-metrics-per-data-type-and-task) (e.g. Accuracy, F1, mAP).
 
 ![Leaderboard](/images/Breast-cancer-screening-use-case-the-leaderboard.avif)
 
 ### Leaderboard Columns
 
 | Column | Description |
 |--------|-------------|
@@ -21,13 +21,13 @@
 | Model Size | Size of the submitted model in parameters or MB. Useful for comparing efficiency. |
 | Energy Consumption | Compute resources consumed during training. Helps assess cost-efficiency. |
 | Submissions | Total number of models submitted by the team. |
 | Remaining Budget | How much of the allocated compute budget (in PFLOPs) the team has left. |
 
 ### Actions You Can Take
 
 From the use case view, you can:
 
 - **Compare models** — Use the leaderboard to identify the best performing and most efficient models side by side.
 - **Stop or adjust training** — Reduce or revoke a team's remaining compute budget to control costs or end a round of evaluation.
 - **Contact participants** — Reach out to vendors or researchers directly to discuss results, request further iterations, or negotiate next steps.
 - **Select a winner** — Once evaluation is complete, choose the best model based on score, model size, and resource efficiency.
@@ -36,7 +36,7 @@
 
 ## Supported Evaluation Metrics
 
 Scores on the leaderboard are calculated using the metric you selected when defining the use case. See the full list of [supported metrics per data type and task](/create-use-case/define#supported-metrics-per-data-type-and-task).
 
 ---
 
@@ -49,3 +49,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

create-use-case/prepare-dataset.mdx

@@ -1,18 +1,18 @@
 ---
 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. Whether 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.
 
@@ -20,14 +20,14 @@
 
 You can ingest data into your client in two ways:
 
 - **Declarative YAML (recommended, simpler)** — describe your dataset in ~8 lines of `ingest.yaml`, then `helm install`. No Dockerfile, no custom Python script. The official ingestor image runs it for you. Use this for any dataset that fits a supported category.
 - **Custom Python template + Kubernetes Job (advanced)** — clone the [data-ingestors repo](https://github.com/tracebloc/data-ingestors), pick a per-category template script, edit it, build and push a Docker image, then `kubectl apply` an `ingestor-job.yaml`. Use this when the declarative schema can't express what your data needs — e.g. non-trivial preprocessing, a custom validator, or a `BaseProcessor` subclass.
 
 Start with the declarative method below. Drop down to the custom-template flow only if you need it.
 
 ## Declarative YAML (recommended)
 
 Describe your dataset in ~8 lines of YAML, then `helm install`. The official ingestor image (published as `ghcr.io/tracebloc/ingestor`) runs it. No Dockerfile, no Python script.
 
 <Note>
 **Before you run any commands in this section:** if you installed the client via the one-liner (`bash <(curl -fsSL https://tracebloc.io/i.sh)`), every later `helm upgrade <workspace> tracebloc/client …` **must** include `--reset-then-reuse-values`, otherwise the upgrade drops the values the installer applied and breaks the workspace:
@@ -46,11 +46,11 @@
 helm repo update
 ```
 
 The `tracebloc/client` parent chart bootstraps the cluster (jobs-manager, MySQL, RBAC). The `tracebloc/ingestor` subchart submits per-dataset ingestion runs against it.
 
 ### 2. Stage your data on the cluster's shared PVC
 
 The chart **doesn't transport data into the cluster** — it points at data already accessible to the cluster's shared PVC (`client-pvc` by default, mounted at `/data/shared/` inside the ingestor Pod). Before installing, get your raw files there.
 
 For a single-node workspace (the default install), the PVC is backed by a host directory the installer created at `~/.tracebloc/<workspace>/data/`. Drop your files into a per-dataset subdirectory:
 
@@ -62,15 +62,15 @@
 cp    LOCAL_PATH/labels.csv ~/.tracebloc/<workspace>/data/<prefix>/
 ```
 
 Inside the ingestor Pod those files appear at `/data/shared/<prefix>/...` — that's what you'll put in `ingest.yaml` below.
 
 <Note>
 For multi-node or EKS deployments where the PVC isn't backed by a local host path, use a throwaway `kubectl cp` Pod or a cloud-storage init container instead. See the [client ingestor README](https://github.com/tracebloc/client/blob/develop/ingestor/README.md#stage-your-data-on-the-shared-pvc) for those recipes.
 </Note>
 
 ### 3. Write your `ingest.yaml`
 
 The example below is for `image_classification`. **Other categories require different fields** — e.g. `tabular_classification` has no `images:` and instead needs a typed `schema:` block. Don't copy this one blindly; grab the matching file from [`examples/yaml/`](https://github.com/tracebloc/data-ingestors/tree/master/examples/yaml) (one per category) and edit from there. Per-category sample data and READMEs live under [`templates/`](https://github.com/tracebloc/data-ingestors/tree/master/templates).
 
 ```yaml
 apiVersion: tracebloc.io/v1
@@ -83,11 +83,11 @@
 label: label
 ```
 
 The top-level shape (`apiVersion`, `kind`, `category`, `table`, `intent`, `label`) is the same for every category; the `category` field picks the validator set, file-extension defaults, and column conventions. The data-source fields (`csv:`, `images:`, `schema:`, …) vary per category. The paths are *paths inside the ingestor Pod*, which is the PVC mount you populated in step 2.
 
 ### 4. Install once per dataset
 
 The ingestor runs once: validates your data, copies files into the destination directory on the PVC, inserts rows into MySQL, sends metadata to the tracebloc backend, then exits. **Run it twice per dataset** — once with `intent: train`, once with `intent: test` — using distinct `table:` names. The example below shows both releases:
 
 ```bash
 # Train release — points at the ingest.yaml from step 3 (table: cats_dogs_train, intent: train)
@@ -101,10 +101,10 @@
   --set-file ingestConfig=./ingest-test.yaml
 ```
 
 Each `helm install` is a separate release (the first argument is the release name), so the two runs don't collide. The ingestor Pod picks up `CLIENT_ID` / `CLIENT_PASSWORD` automatically from the Kubernetes Secret the parent `tracebloc/client` chart created in `<workspace>` at install time — you don't pass credentials on the `helm install` command.
 
 <Warning>
 **Validation error like `'<your_category>' is not one of [...]` or `Additional properties are not allowed (<field> was unexpected)`?** This comes from the cluster's `jobs-manager` validating against its own bundled schema at submit time — the deployed schema is older than the ingestor image you're installing. `helm repo update` won't fix it (that only refreshes the local chart index, not the running server). The fix is on the cluster side: upgrade the parent chart so jobs-manager redeploys with the current schema.
 
 ```bash
 helm upgrade <workspace> tracebloc/client \
@@ -118,18 +118,18 @@
 
 ## Custom Python template (advanced)
 
 Use this flow when the declarative schema can't express what your data needs — typically when you have non-trivial preprocessing logic, a custom validator, or a `BaseProcessor` subclass. The sections below — Quick Setup and Detailed Setup — both describe this advanced path.
 
 ## 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(
@@ -163,9 +163,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):
 
@@ -230,14 +230,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
 
@@ -290,7 +290,7 @@
 ```
 
 #### Set CSV ingestion options
 Customize parsing, memory handling, and data cleaning with the csv_options dictionary:
 
 ```python
 csv_options = {
@@ -305,9 +305,9 @@
 }
 ```
 
 #### Set Up the Ingestor
 
 Define the Ingestor instance with the required configuration. See the tabular data example below:
 
 ```python
 ingestor = CSVIngestor(
@@ -339,7 +339,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:
@@ -348,18 +348,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.
@@ -368,20 +368,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 && \
@@ -480,14 +480,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>
@@ -503,7 +503,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":
@@ -529,7 +529,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 && \
@@ -541,7 +541,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
@@ -563,7 +563,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
@@ -597,3 +597,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

create-use-case/prerequisites.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Prerequisites"
 description: "Supported data types, tasks, and requirements for creating a use case on tracebloc."
 ---
 
 tracebloc is continually expanding supported data types and tasks to enable your use cases. In case your use case is not yet supported, please reach out to us at [support@tracebloc.io](mailto:support@tracebloc.io).
 
 Before you can create a use case on the [tracebloc website](https://ai.tracebloc.io/my-use-cases), make sure the following requirements are met:
 
 - You are registered as a user on the tracebloc platform
 - You have a client deployed using kubernetes either [locally or in the cloud](/environment-setup/setup-guide)
 - Your dataset is cleaned and preprocessed
 - You are familiar with the supported data types and tasks
@@ -23,22 +23,22 @@
 
 ### Image Data
 
 **Requirements for all image data tasks:** Uniform image sizes and uniform file types. For example all images as 256x256 rgb .jpg files. Convert files if necessary and in case your images do not fit the supported size, crop or resize accordingly.
 
 <Note>
 **Filenames in the label CSV:** For all image and text tasks, the `filename` column in the label CSV **must not include the file extension** (e.g. use `cat01`, not `cat01.jpg`). The extension is configured once on the ingestor side via `file_options.extension` in the template and applied to every row at ingestion time.
 </Note>
 
 All images are validated before ingestion by the data ingestor. The ingestion process only starts when every file meets the requirements. Fix or remove any invalid images, then retry.
 
 For object detection, images and annotations are automatically up- or downsized to 448x448 pixels.
 
 | Task                  | Input file type | Color mode                                                   | Supported image size | Label file type                   | Requirements                                 | Links    |
 |-----------------------|-----------------|--------------------------------------------------------------|----------------|-----------------------------------|----------------------------------------------|----------|
 | Classification        | PNG, JPG, JPEG             | rgb (3 channels) or grayscale (1 channel), 8-bit per channel | Square (height = width)   | CSV                               | Uniform image size and file type per dataset | [Detailed structure](#image-classification) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/image_classification) |
 | Keypoint Detection    | PNG, JPG, JPEG             | rgb (3 channels) or grayscale (1 channel), 8-bit per channel | Square (height = width)   | CSV                              | Uniform image sizes <br></br> Same number of keypoints per image and class  | [Detailed structure](#image-keypoint-detection) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/keypoint_detection) |
 | Object Detection      | PNG, JPG, JPEG             | rgb (3 channels) or grayscale (1 channel), 8-bit per channel | Square (height = width). Images and annotations will be resized to 448x448 px automatically | Pascal VOC                        | Uniform image sizes, one xml per image       | [Detailed structure](#image-object-detection) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/object_detection) |
 | Semantic Segmentation | PNG, JPG, JPEG             | rgb (3 channels) or grayscale (1 channel), 8-bit per channel | Square (height = width)   | PNG, JPG, JPEG | Uniform image and mask sizes                 | [Detailed structure](#image-semantic-segmentation) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/semantic_segmentation) |
 
 ### Image Classification
 
@@ -60,11 +60,11 @@
 ...
 ```
 
 The `filename` column must not include the file extension. Set the expected extension once via `file_options.extension` in the ingestor template.
 
 ### Image Keypoint Detection
 
 The number of keypoints per class and per image must be fixed. For example, in a person/car keypoint detection project, both classes must define the same keypoints, and every image must contain the full set for its class. You cannot mix classes with different keypoint counts (e.g., 16 for person and 32 for car) or annotate some images with fewer keypoints for the same class.
 
 ``` structure
 train/
@@ -85,8 +85,8 @@
 image02,car,115,145,2
 ```
 
 - **X and Y** determine the X-/Y-coordinates of a keypoint
 - **Visibility** indicates whether a keypoint is visible in the image or not: 0 = not visible (point outside the image or point is in the image but occluded), 1 = visible
 - **Filename** should not include the file extension.
 
 ### Image Object Detection
@@ -141,8 +141,8 @@
 
 ### Image Semantic Segmentation
 
 Each mask is an rgb image whose pixel values map to classes defined in labels.csv. The labels.csv contains a global list per image and class. All masks must exactly match their corresponding image sizes and file names.
 For binary segmentation (two classes), provide a single-channel grayscale mask where background pixels are black (0) and foreground pixels are white (255).
 For three or more classes, supply an RGB mask where each class is represented by a unique color (or pixel value). The filename should not include the file extension.
 
 
@@ -174,13 +174,13 @@
 
 ### Tabular Data
 
 **Requirements for all tabular data tasks:** Each dataset must be provided as a single CSV file with a header row. Every column must contain uniform data types, for example numeric values for features and a categorical or alphanumeric column for labels. Use UTF-8 encoding with comma separators and validate that your schema matches the expected types. Invalid rows are skipped by the ingestor.
 
 | Task                     | Data file type                              | Requirements                                                                                                                                  | Links    |
 |--------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|----------|
 | Classification           | CSV (features and label in one single file) | Uniform data formats per column. <br></br>Feature columns: Numeric <br></br>Label columns: Alphanumeric                                       | [Detailed structure](#tabular-classification) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/tabular_classification) |
 | Regression               | CSV (features and label in one single file) | Uniform data formats per column. <br></br>Feature columns: Numeric <br></br>Label column: Numeric (continuous target)                         | [Detailed structure](#tabular-regression) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/tabular_regression) |
 | Time Series Forecasting  | CSV (timestamp, features and target in one single file) | A timestamp column in a parsable format (e.g. `YYYY-MM-DD` or ISO 8601). <br></br>Feature columns: Numeric <br></br>Target column: Numeric    | [Detailed structure](#time-series-forecasting) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/time_series_forecasting) |
 | Time to Event Prediction | CSV (features, time and event in one single file) | A `time` column (duration until event or censoring, integer or numeric). <br></br>An event column (binary 0/1 indicating whether the event occurred). <br></br>Feature columns: Numeric | [Detailed structure](#time-to-event-prediction) <br></br>[Example](https://github.com/tracebloc/data-ingestors/tree/develop/templates/time_to_event_prediction) |
 
 ### Tabular Classification
@@ -239,7 +239,7 @@
 
 ### Text Classification
 
 The `filename` column must not include the file extension. The extension is set once via `file_options.extension` in the ingestor template (e.g. `FileExtension.TXT`).
 
 ``` structure
 train/
@@ -275,3 +275,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

create-use-case/templates.mdx

@@ -3,7 +3,7 @@
 description: "Ready-made data ingestion templates for every supported task — clone, configure, deploy."
 ---
 
 Each task tracebloc supports comes with a runnable data-ingestion template — a working `Dockerfile`, `ingestor.py`, and `ingestor-job.yaml` you can copy, point at your data, and ship.
 
 ## Available templates
 
@@ -11,7 +11,7 @@
 |---|---|
 | Image classification | [`templates/image_classification`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/image_classification) |
 | Object detection | [`templates/object_detection`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/object_detection) |
 | Keypoint detection | [`templates/keypoint_detection`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/keypoint_detection) |
 | Semantic segmentation | [`templates/semantic_segmentation`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/semantic_segmentation) |
 | Text classification | [`templates/text_classification`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/text_classification) |
 | Masked language modeling | [`templates/masked_language_modeling`](https://github.com/tracebloc/data-ingestors/tree/develop/templates/masked_language_modeling) |
@@ -35,3 +35,4 @@
 ## Need help?
 
 Email [support@tracebloc.io](mailto:support@tracebloc.io).
+

environment-setup/cli.mdx

@@ -1,9 +1,9 @@
 ---
 title: "tracebloc CLI"
 description: "Manage and operate your workspace from the command line — inspect the cluster, ingest and remove datasets, validate configs."
 ---
 
 The `tracebloc` CLI is how you **manage and operate your workspace and its data** from your own machine: inspect the cluster, ingest datasets, remove them, validate configs — with more verbs on the way. It's the friendly front end to the same ingestion protocol the [Helm ingestor chart](https://github.com/tracebloc/client/tree/main/ingestor) speaks, so it works against any workspace running the `tracebloc/client` chart.
 
 <Note>
 You never touch Helm, edit YAML, or run `kubectl cp`. `dataset push` discovers your workspace, stages the files, submits, and streams the job for you.
@@ -21,7 +21,7 @@
   </Tab>
   <Tab title="Windows (PowerShell)">
   ```powershell
   irm https://github.com/tracebloc/cli/releases/latest/download/install.ps1 | iex
   ```
   </Tab>
 </Tabs>
@@ -36,10 +36,10 @@
 ```bash
 tracebloc cluster info
 ```
 Shows the cluster, namespace, parent release, and ingestor-token state — your first check that the CLI can reach your workspace.
 
 <Note>
 If `cluster info` reports *"no parent client release found in namespace default"*, your client runs in another namespace — add `-n <your-namespace>`, or set it once with `kubectl config set-context --current --namespace <your-namespace>`. Every command below accepts `-n`.
 </Note>
 
 ## Manage data
@@ -66,7 +66,7 @@
 ```bash
 tracebloc ingest validate ingest.yaml
 ```
 Checks an `ingest.yaml` against the embedded schema — no cluster required. The declarative form (also accepted by the Helm ingestor chart):
 ```yaml
 apiVersion: tracebloc.io/v1
 kind: IngestConfig
@@ -83,7 +83,7 @@
 |---|---|
 | `tracebloc dataset push <path>` | Stage + ingest a local dataset (guided if you omit flags) |
 | `tracebloc dataset rm <table>` | Delete a pushed dataset (table + staged files) |
 | `tracebloc cluster info` | Cluster, namespace, parent release, and token state |
 | `tracebloc ingest validate <path>` | Validate an `ingest.yaml` against the v1 schema, locally |
 | `tracebloc version` | CLI version, git SHA, and build date |
 | `tracebloc completion` | Generate shell completion |
@@ -99,3 +99,4 @@
 ## Coming soon
 
 Cloud-source ingestion (S3 / GCS / HTTPS) for large datasets, a `dataset list` verb, and `semantic_segmentation` support.
+

environment-setup/configuration.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Configuration"
 description: "Customize your tracebloc workspace — environment variables, cluster management, GPU support, and manual Helm deployment."
 ---
 
 The installer uses sensible defaults; this page covers what you can change.
@@ -42,7 +42,7 @@
 
 ### View logs
 
 The jobs manager is the main tracebloc process. Check its logs when debugging connectivity or job execution issues:
 
 ```bash
 kubectl logs -n <workspace> -l app=manager
@@ -70,7 +70,7 @@
 
 Fully automatic. The installer:
 
 1. Detects NVIDIA GPUs via `nvidia-smi` or `lspci`
 2. Installs drivers if missing (Ubuntu, RHEL/CentOS, Arch)
 3. Installs the NVIDIA Container Toolkit and configures Docker
 4. Deploys the NVIDIA k8s device plugin into the cluster
@@ -80,11 +80,11 @@
 
 ### AMD (Linux)
 
 Auto-detected. ROCm is installed automatically on Ubuntu and RHEL/CentOS. A logout/login may be needed for full GPU access.
 
 ### macOS
 
 CPU only. Docker Desktop on macOS does not support GPU passthrough. For GPU workloads, deploy on a Linux machine with NVIDIA GPUs or use [AWS (EKS)](/environment-setup/eks-client-deployment-guide).
 
 ### Windows
 
@@ -242,7 +242,7 @@
 
 #### Docker Registry
 
 The chart pulls the client image from a container registry — credentials are required in production. Use a token, not a plaintext password.
 
 ```yaml
 dockerRegistry:
@@ -279,11 +279,11 @@
   timeout: "10m"
 ```
 
 The CronJob's ServiceAccount is bound to the built-in `cluster-admin` ClusterRole because the chart templates cluster-scoped resources (PriorityClass, StorageClass, ClusterRoleBinding, optionally Namespace). Disable if you need a manual approval gate on upgrades.
 
 #### NetworkPolicy hardening for training pods
 
 Training pods run untrusted ML code. The chart can apply a NetworkPolicy that denies ingress and restricts egress to DNS + external HTTPS only — blocking pod-to-pod, MySQL, and Kubernetes API access from the training pod.
 
 ```yaml
 networkPolicy:
@@ -309,12 +309,12 @@
 Leave `enabled: false` on clusters without an enforcing CNI — silently having no protection is worse than explicitly disabling it.
 
 <Warning>
 The chart's training-pod egress lockdown only blocks traffic if your CNI enforces NetworkPolicy. Verify your CNI before relying on it.
 </Warning>
 
 #### Resource Monitor and node-agents namespace
 
 The `tracebloc-resource-monitor` DaemonSet collects node-level CPU/memory metrics. It mounts `hostPath` volumes (`/proc`, `/sys`) which Pod Security Admission's `restricted` profile bans — so the chart isolates it in a dedicated **privileged** namespace (default `tracebloc-node-agents`).
 
 ```yaml
 resourceMonitor: true          # set false on clusters where metrics-server cannot be installed
@@ -324,7 +324,7 @@
     name: tracebloc-node-agents
 ```
 
 When `create: false`, create the namespace yourself with the required PSA labels:
 
 ```bash
 kubectl create namespace tracebloc-node-agents
@@ -338,7 +338,7 @@
 
 #### Pod Security Admission labels
 
 Training Jobs run untrusted user-supplied ML code. The chart can create the release namespace with Pod Security Admission `warn`/`audit`/`enforce` labels at the `restricted` profile for defense-in-depth:
 
 ```yaml
 namespace:
@@ -349,7 +349,7 @@
     enforce: restricted        # set "" for bare-metal hostPath installs
 ```
 
 When `create: false` (default) and you want PSA labels on an existing namespace:
 
 ```bash
 kubectl label namespace <workspace> \
@@ -374,7 +374,7 @@
 
 #### PriorityClass and PodDisruptionBudgets
 
 The chart pins the MySQL pod with a `tracebloc-data-plane` PriorityClass (value `1000000`) so it survives node-level OOM and scheduling pressure, and applies PDBs to MySQL and the jobs manager. Override only if you run a multi-replica MySQL externally:
 
 ```yaml
 priorityClass:
@@ -389,7 +389,7 @@
 
 ### Deploy
 
 Install the chart into a new namespace:
 
 ```bash
 helm upgrade --install <workspace> tracebloc/client \
@@ -420,7 +420,7 @@
 helm uninstall <workspace> -n <workspace>
 ```
 
 PVCs and the PriorityClass are annotated `helm.sh/resource-policy: keep` so your data and shared cluster resources survive uninstall. To remove them too:
 
 ```bash
 kubectl delete pvc --all -n <workspace>
@@ -440,10 +440,11 @@
 
 ## Security
 
 Tracebloc is designed so your data never has to leave your network. Here's how:
 
 - **Data stays local.** Training data never leaves your infrastructure. Only metadata and metrics are shared with the platform.
 - **Encrypted.** All communication between client and platform is TLS-encrypted.
 - **Isolated.** Training runs in containers with restricted system access. Kubernetes namespaces separate workloads from each other.
 - **Scanned.** Submitted models are analyzed for vulnerabilities before execution on your infrastructure.
 - **Minimal footprint.** The installer only modifies `~/.tracebloc/` and Docker. No system-wide changes.
+

environment-setup/deploy-aks.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Azure AKS"
 description: "Deploy a tracebloc workspace on Azure Kubernetes Service."
 ---
 
 **When to pick it** — You're on Azure and want managed Kubernetes with autoscaling and GPU node pools.
 
 ## Prerequisites
 
@@ -45,10 +45,11 @@
 clusterScope: true
 ```
 
 - **NetworkPolicy:** create the AKS cluster with `--network-policy azure` (Azure NPM) or Calico — otherwise the training-pod egress lockdown won't enforce.
 - `metrics-server` is bundled on AKS.
 
 ## Production notes
 
 - Use GPU node pools for training workloads; size requests/limits per job.
 - Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations).
+

environment-setup/deploy-bare-metal.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Bare-metal"
 description: "Deploy a tracebloc workspace on your own on-prem Kubernetes cluster."
 ---
 
 **When to pick it** — You already run Kubernetes on-prem (k3s, kubeadm, RKE, …) and want a workspace on it, with full control over scheduling and storage.
 
 ## Prerequisites
 
@@ -49,10 +49,11 @@
 clusterScope: true
 ```
 
 - **NetworkPolicy** (training-pod egress lockdown) only enforces if your CNI supports it — Calico, Cilium, or kube-router. Flannel alone does **not** enforce.
 
 ## Production notes
 
 - Schedule MySQL and storage on reliable nodes; back up the data PVCs.
 - Size training compute per job via `RESOURCE_REQUESTS` / `RESOURCE_LIMITS` ([Configuration](/environment-setup/configuration#resource-limits-for-training-jobs)).
 - Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations).
+

environment-setup/deploy-local.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Local / k3d"
 description: "Run a tracebloc workspace on a single machine — laptop or on-prem server. Production-capable."
 ---
 
 **When to pick it** — A single machine you own: a laptop to try things, or an on-prem server you run in production. The installer brings up a self-contained Kubernetes cluster (k3d) inside Docker — you don't need a cluster of your own.
 
 ## Prerequisites
 
-- A machine: macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk.
+- A machine: macOS, Linux, or Windows · 2 CPU · 5 GB RAM · 10 GB free disk to run (4 CPU · 16 GB · 50 GB to train on it).
 - Your **Client ID** and password from the [clients page](https://ai.tracebloc.io/clients).
 
 That's it — no Docker or Kubernetes knowledge needed. The installer sets up Docker and the cluster for you.
@@ -22,12 +22,12 @@
   </Tab>
   <Tab title="Windows (PowerShell as admin)">
   ```powershell
   irm https://tracebloc.io/i.ps1 | iex
   ```
   </Tab>
 </Tabs>
 
 See [Quick Start](/environment-setup/quickstart) for the full walkthrough, including the inspect-first option.
 
 ## Verify
 
@@ -35,7 +35,7 @@
 kubectl get pods -A
 ```
 
 The tracebloc pods should be `Running`, and your workspace should read **Online** on the clients page.
 
 ## Environment-specific config
 
@@ -45,7 +45,7 @@
 CLUSTER_NAME=my-cluster AGENTS=2 HOST_DATA_DIR=/data/tracebloc bash <(curl -fsSL https://tracebloc.io/i.sh)
 ```
 
 GPUs are auto-detected on Linux (NVIDIA/AMD) — drivers, container toolkit, and device plugin are installed for you.
 
 ## Production notes
 
@@ -53,3 +53,4 @@
 - Your data persists in `HOST_DATA_DIR` across stop/start cycles (see [Operations](/environment-setup/operations)).
 - Need more headroom? Re-run the installer on a bigger machine, or add worker nodes with `AGENTS`.
 - For multi-node high availability, use [bare-metal](/environment-setup/deploy-bare-metal) or a managed cloud instead.
+

environment-setup/deploy-openshift.mdx

@@ -1,9 +1,9 @@
 ---
 title: "OpenShift"
 description: "Deploy a tracebloc workspace on Red Hat OpenShift or OKD."
 ---
 
 **When to pick it** — You run Red Hat OpenShift (or OKD) and need the workspace to fit its security model (SCCs, OVN networking).
 
 ## Prerequisites
 
@@ -49,10 +49,11 @@
       dns.operator.openshift.io/daemonset-dns: default
 ```
 
 - OVN-Kubernetes **enforces** NetworkPolicy by default, so the training-pod egress lockdown works out of the box.
 - `metrics-server` is present on OpenShift.
 
 ## Production notes
 
 - The bundled SCC grants the resource-monitor the host access it needs — review it against your cluster policy.
 - Size training compute per job; day-2 management is in [Operations](/environment-setup/operations).
+

environment-setup/deployment-environments.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Deployment environments"
 description: "Run tracebloc anywhere — local, bare-metal, EKS, AKS, or OpenShift. Same chart, same steps, your choice of infrastructure."
 ---
 
 tracebloc runs the same way everywhere: one chart (`tracebloc/client`), one set of steps, your choice of infrastructure. **Local is a first-class production option** — a workspace on an on-prem server is every bit as real as one on a managed cloud cluster.
 
 ## Pick your environment
 
@@ -11,7 +11,7 @@
 |---|---|---|---|
 | [Local / k3d](/environment-setup/deploy-local) | One machine you own | NVIDIA / AMD, auto-detected | A laptop or a single on-prem server — the fastest start |
 | [Bare-metal](/environment-setup/deploy-bare-metal) | Your own Kubernetes cluster | Your nodes | You already run on-prem Kubernetes |
 | [Amazon EKS](/environment-setup/eks-client-deployment-guide) | AWS (managed) | GPU nodegroups | You're on AWS and want managed, autoscaling compute |
 | [Azure AKS](/environment-setup/deploy-aks) | Azure (managed) | GPU node pools | You're on Azure |
 | [OpenShift](/environment-setup/deploy-openshift) | OpenShift / OKD | Your nodes | You run Red Hat OpenShift |
 
@@ -26,3 +26,4 @@
 **When to pick it · Prerequisites · Install · Verify · Environment-specific config · Production notes.**
 
 Adding a new target later (GKE, on-prem k3s, …) means filling the same template. All environments deploy the same chart — see [Configuration](/environment-setup/configuration) for every value, and [Operations](/environment-setup/operations) for day-2 management.
+

environment-setup/eks-client-deployment-guide.mdx

@@ -1,17 +1,17 @@
 ---
 title: "Amazon EKS"
 description: "Deploy a tracebloc workspace on Amazon EKS using the AWS CLI — networking, GPU support, storage, and security for a production cluster."
 ---
 
 ## Overview
 
 <Note>
 **Use EKS for production** — multi-node, autoscaling, or shared GPU clusters on AWS. For a single machine (a laptop or one server), the [local installer](/environment-setup/setup-guide) is simpler and faster.
 </Note>
 
 Running machine learning workloads in the cloud often requires a reliable, secure, and scalable infrastructure—yet setting it up can be complex. This guide walks you through building a complete Amazon EKS (Elastic Kubernetes Service) environment from scratch using the AWS CLI. By following these steps, you'll create a production-ready foundation with networking, GPU-optional compute, storage, and security fully aligned with AWS and Kubernetes best practices.
 
 Once the infrastructure is in place, you'll deploy and configure the tracebloc client to securely train and benchmark AI models. This setup ensures that your proprietary data stays within your environment, while still allowing external AI models to be tested and fine-tuned in a controlled, isolated way. The result: a scalable, secure platform for high-performance ML workloads that accelerates collaboration with external experts while maintaining full control over your data and IP.
 
 The entire setup takes ~1–2 hours.
 
@@ -25,7 +25,7 @@
 
 #### 1. Create or use an AWS Account
 - If you don't already have one, [create an AWS account](https://signin.aws.amazon.com/signup?request_type=register).
 - Your account must have permissions to create and manage EKS resources, VPCs, EC2 instances, and IAM roles.
 
 #### 2. Install and configure AWS CLI
 - [Install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) on your local machine.
@@ -53,10 +53,10 @@
 - EC2 instances and security groups
 - IAM roles and policies
 
 ### Required Tooling & Tracebloc Account
 - **Helm 3.x**: Install Helm on your local machine. [Installation Guide](https://helm.sh/docs/intro/install/)
 - **kubectl**: Install kubectl to interact with your EKS cluster. [Installation Guide](https://kubernetes.io/docs/tasks/tools/)
 - **Tracebloc Account**: You will need your Client ID and Client Password ([from the tracebloc client view](https://ai.tracebloc.io/clients)).
 - **Docker Registry Credentials**: Docker Hub username, password/token, and email for pulling container images.
 
 ### Recommended for Monitoring: Use k9s
@@ -66,15 +66,15 @@
 
 ### Components
 
 The EKS infrastructure setup consists of two main parts: Core Infrastructure and Client Deployment. Together, they provide a secure, scalable environment for running ML workloads with the tracebloc client.
 
 #### Core Infrastructure
 
 **VPC with isolated networking**
 Creates a dedicated, secure network environment with subnets across multiple Availability Zones for high availability.
 
 **EKS Cluster**
 A managed Kubernetes control plane with auto-scaling nodegroups to run your ML workloads.
 
 **IAM Roles and Policies**
 Granular roles for the cluster and worker nodes following least-privilege principles.
@@ -87,7 +87,7 @@
 
 #### Client Deployment
 
 **tracebloc Client Application**
 Deployed into the EKS cluster using Helm, configured with your account credentials and storage.
 
 **Monitoring and Verification**
@@ -98,7 +98,7 @@
 ### Process Flow
 
 1. **Infrastructure Setup** - Create VPC, networking, EKS cluster, and storage
 2. **Client Deployment** - Configure and deploy the tracebloc application
 3. **Verification** - Validate everything is running correctly
 
 
@@ -113,26 +113,26 @@
 - **Model Encryption**: Model weights are encrypted and never leave your environment.
 - **Secure Communication**: All platform communication is protected with TLS.
 
 ### tracebloc Backend Security
 
 - **Code Analysis**: Submitted external models are scanned with the Bandit library to detect vulnerabilities or malicious code.
 - **Input Validation**: Training scripts and model code undergo strict validation before execution.
 - **Sandboxed Execution**: Training workloads run in isolated environments with restricted system access.
 - **Namespace Isolation**: Kubernetes namespaces ensure logical separation from other applications.
 
 ### Identity & Access Management
 
 **AWS IAM Roles:**
 - **Cluster Role**: Minimal permissions (`AmazonEKSClusterPolicy`) for cluster management.
 - **Nodegroup Role**: Least-privilege permissions for worker nodes, networking, container registry, and storage access.
 
 **Kubernetes RBAC:**
 - Cluster roles provide limited permissions for jobs, pods, and deployments.
 - Service accounts are bound to roles within their namespace, preventing cross-namespace access.
 
 ### Network Security
 
 - **VPC Isolation**: Dedicated VPC with private subnets and an Internet Gateway for controlled communication.
 - **Security Groups**: Restrict access to EFS mount targets and cluster traffic.
 - **Outbound Access**: Limited to required destinations such as `*.amazonaws.com`, `*.docker.io`, and `*.tracebloc.io`.
 
@@ -143,13 +143,13 @@
 Quick Setup runs an automated script that builds the whole cluster in one go. Want step-by-step control (or to customize networking)? Use [Detailed Setup](#detailed-setup) instead.
 
 ### Purpose
 Spin up a production-ready EKS baseline (VPC, subnets, internet gateway, EKS cluster, managed nodegroup, EFS + CSI driver) in one go. Includes basic validation, colored logging, and a cleanup mode.
 
 ### What this script does
 - Creates networking (VPC + 3 public subnets + route to IGW)
 - Provisions an EKS cluster and a system nodegroup (t3.medium, 2–5 nodes)
 - Creates EFS and mount targets in all AZs, sets up the EFS CSI driver + storage class
 - Updates your kubeconfig for kubectl access
 - Prints a summary and next steps
 
 ### Prerequisites
@@ -165,34 +165,34 @@
 4. Execute: `./setup_eks.sh`
 5. When finished, follow the printed "Next steps" to create your Docker registry secret and deploy workloads
 
 ### Cleanup (teardown)
 Run `./setup_eks.sh cleanup` to remove cluster, nodegroup, EFS, subnets, gateway, roles, and VPC (irreversible).
 
 ### Tips:
 - **Costs**: This creates billable resources (EC2, EKS, EFS, data transfer). Remove when not needed.
 - **Network model**: Subnets are configured to auto-assign public IPs for simplicity. Adjust to private subnets + NAT as needed.
 - **Kubernetes version**: The script requests `--kubernetes-version 1.32`; update if your region/account supports a different current version.
 - **Security hardening**: This is a production baseline; harden further for your environment (security groups, private subnets, IRSA, Pod Security/OPA).
 
 If you prefer more control over your setup and want to customize the environment to your needs, follow the step-by-step guide below.
 
 ## Detailed Setup
 
 This section walks through a step-by-step build with AWS CLI and kubectl. It mirrors the Quick Setup but lets you choose your own resource settings (# of CPUs, Memory, VPC CIDRs, instance types, namespace, Helm release name, StorageClass, etc.). Expect about 1–2 hours end-to-end.
 
 ### What you'll do (Steps 1–6):
 1. **VPC & Network Configuration** — Create an isolated Virtual Private Cloud (VPC) with subnets distributed across three availability zones for high availability, an Internet Gateway for outbound connectivity, and routing tables with proper associations. This provides network isolation and fault tolerance for your cluster infrastructure.
 2. **EKS Cluster Setup** — Create the cluster service role and provision the EKS control plane which manages the Kubernetes API server.
 3. **EKS Nodegroup Setup** — Create a node service role and provision two managed nodegroups: A system nodegroup for Kubernetes system components and a training nodegroup for ML workloads. Each nodegroup can be customized with different instance types, scaling parameters, and capacity types depending on the work loads and data types.
 4. **Storage** — Create an Amazon EFS file system for shared persistent storage, configure a security group that allows NFS traffic from the cluster nodes, and create mount targets in each availability zone. This provides scalable, shared storage for training data as well as weights and logs.
 5. **Client Configuration** — Install the Amazon EFS (Elastic File System) CSI driver (Container Storage Interface) in your EKS (Elastic Kubernetes Service) cluster. This driver is what lets Kubernetes automatically create and mount EFS storage volumes.
 6. **Client Deployment** — Add the tracebloc Helm repository, configure your deployment values (authentication credentials, registry access, storage settings, resource limits), install the chart into your chosen namespace. Deploy and verify that all pods are running and persistent volume claims are properly bound.
 
 **Helm Usage**: Helm is used to install and manage Kubernetes applications. In steps 5 and 6 you will deploy the tracebloc client via the unified `tracebloc/client` chart with EKS-specific values.
 
 ## 1. VPC and Network Configuration
 
 Your AWS EKS cluster must run in a secure and isolated network with subnets across availability zones, DNS resolution, and internet access. This is provided by an AWS VPC (Virtual Private Cloud), which is a logically isolated section of AWS where you define your own IP address range (CIDR block), subnets, routing, and gateways.
 This section sets up the foundation.
 
 ### VPC Creation
@@ -207,20 +207,20 @@
 
 Creates an isolated network environment where your EKS cluster runs securely. Uses CIDR (Classless Inter-Domain Routing) block `10.0.0.0/16` to define the IP address range for all resources in the VPC and tags it with the specified owner name. Replace `<OWNER_NAME>` with your preferred identifier. Keep the output and the `VPC_ID`for the next steps.
 
 ### Enable DNS Hostnames
 
 DNS (Domain Name System) support and hostnames let Kubernetes pods and services find each other by name, which is essential for service discovery in Kubernetes, which relies on DNS resolution.
 
 ```bash
 aws ec2 modify-vpc-attribute --vpc-id <VPC_ID> --enable-dns-hostnames
 ```
 
 Enables DNS resolution so nodes and services can resolve each other by name instead of IP addresses. Find the `VPC_ID`from the previous step or list VPCs using `aws ec2 describe-vpcs`.
 
 
 ### Create Subnets Across Availability Zones
 
 Subnets (smaller ranges of IP addresses inside the VPC) are spread across multiple AZs (Availability Zones) to ensure high availability and fault tolerance. EKS requires subnets in at least 2 availability zones for high availability - using 3 zones provides better fault tolerance and load distribution.
 
 ```bash
 aws ec2 create-subnet \
@@ -242,18 +242,18 @@
   --tag-specifications "ResourceType=subnet,Tags=[{Key=owner,Value=<OWNER_NAME>}]"
 ```
 
 Creates three subnets with separate CIDR blocks (`10.0.1.0/24`, `10.0.2.0/24`, `10.0.3.0/24`) distributed across different availability zones. Use or create tags if needed. Register the generated `SUBNET_IDs` for the following steps.
 
 ### Enable Public IPs on Subnets
 
 EKS worker nodes need public IPs to communicate with the EKS control plane, download container images from Dockerhub, and allow external traffic to reach applications.
 
 ```bash
 aws ec2 modify-subnet-attribute --subnet-id <SUBNET_ID_1A> --map-public-ip-on-launch
 aws ec2 modify-subnet-attribute --subnet-id <SUBNET_ID_1B> --map-public-ip-on-launch
 aws ec2 modify-subnet-attribute --subnet-id <SUBNET_ID_1C> --map-public-ip-on-launch
 ```
 Configures each subnet to automatically assign public IP addresses to new EC2 instances.
 
 ### Create and Attach an Internet Gateway
 
@@ -300,7 +300,7 @@
 ## 2. EKS Cluster Setup
 
 Amazon EKS provides the managed Kubernetes control plane. It needs permissions through AWS IAM (Identity and Access Management) to create and manage resources such as load balancers, security groups, and network interfaces.
 The cluster itself is the logical container for the API server, linking your VPC networking with the control plane and IAM role. To interact with it you must update your local kubeconfig so kubectl can send commands. Setting this up gives you a working API server that can manage workloads once worker nodes are added in the next step.
 
 ### Create EKS Cluster Role
 
@@ -339,7 +339,7 @@
 
 ### Create EKS Cluster
 
 Create the EKS cluster to provision the managed Kubernetes control plane and connect it to your VPC, subnets, and IAM role.
 
 ```bash
 aws eks create-cluster \
@@ -350,7 +350,7 @@
   --kubernetes-version 1.32 \
   --tags owner=<OWNER_NAME>
 ```
 Creates the EKS cluster using the specified role, VPC subnets, and Kubernetes version. Set an appropriate `CLUSTER_NAME`, **expect this to take around 10 minutes**. If you do not have your accound ID ready, run `aws sts get-caller-identity`.
 
 ### Configure kubectl
 
@@ -359,7 +359,7 @@
 ```bash
 aws eks update-kubeconfig --region eu-central-1 --name <CLUSTER_NAME>
 ```
 Updates your local kubeconfig for kubectl.
 
 ### Manage Multiple Clusters (Optional)
 
@@ -375,22 +375,22 @@
 ```
 This ensures subsequent kubectl commands apply to the intended cluster.
 
 ### Create Application Namespace
 
 Namespaces let you isolate your workloads from system components and other applications running in the cluster. Define an appropriate namespace for your setup
 
 ```bash
 kubectl create namespace <NAMESPACE>
 ```
 Adds a dedicated namespace for your workloads, keeping them isolated from system components.
 
 
 
 ## 3. EKS Nodegroup Setup
 
 Nodegroups are sets of EC2 instances that act as worker nodes, running your system and training workloads. Each nodegroup needs an IAM role so the nodes can join the cluster and interact with AWS services such as pulling images from registries, attaching EFS storage, and sending logs. It is best practice to create at least two groups: a small system nodegroup to host cluster services and a training nodegroup sized for your ML workloads. The training nodegroup can be CPU-based for general jobs or GPU-based for deep learning, ensuring that heavy jobs do not interfere with core Kubernetes functions.
 
 ### Create Nodegroup Role
 
 Worker nodes need an IAM role to join the cluster and access AWS services.
 
@@ -432,11 +432,11 @@
 - **AmazonEC2ContainerRegistryReadOnly:** allows pulling images from ECR
 - **AmazonEKS_CNI_Policy:** required for pod networking via the Container Network Interface (CNI) plugin
 
 ### Create Managed Nodegroups
 
 Now let`s create two nodegroups: A system nodegroup that runs critical Kubernetes components (CoreDNS, kube-proxy, Container Network Interface (CNI), Storage Interface drivers (CSI), metrics-server, etc.) and a training nodegroup that runs your machine learning workloads. This separation ensures cluster stability even under heavy training load.
 
 #### System Nodegroup
 
 It is recommended to use [AWS EC2 instance type t3.medium](https://aws.amazon.com/ec2/instance-types/t3/) for system pods as they are relatively cheap and sufficient. Spread nodes across three Availability Zones for resilience, set ON_DEMAND for reliability and label as "system":
 
@@ -455,11 +455,11 @@
   --tags owner=<OWNER_NAME>
 ```
 
 Creates a nodegroup with `t3.medium` instances (2 vCPUs, 4 GiB memory) spread across three AZs. The group scales between 2 and 5 nodes (EC2s), each node is labeled for system workloads. Set an appropriate `SYSTEM_NODEGROUP_NAME`. Always make sure to use `AL2_x86_64` for system nodes so that the data ingestor runs on this node, too.
 
 #### Training Nodegroup
 
 This group runs your ML training workloads — size it for your dataset, model type, number of parallel workloads, and whether you need GPUs.
 
 Refer to the [EC2 instance types list](https://aws.amazon.com/ec2/instance-types) and [EKS managed nodegroups docs](https://docs.aws.amazon.com/eks/latest/userguide/create-managed-node-group.html) for guidance.
 
@@ -483,17 +483,17 @@
 
 | Compute Type | INSTANCE_TYPE | AMI_TYPE | LABEL |
 |--------------|---------------|----------|-------|
 | CPU | t3.xlarge | AL2_x86_64 | cpu |
 | GPU | g5g.xlarge | AL2023_x86_64_NVIDIA | gpu |
 
 The first example provisions a training nodegroup with t3.xlarge instances (4 vCPUs, 16 GiB memory). It starts with 2 nodes, can scale down to 0 when idle, and grows to 5 under load.
 
 You can limit the compute per participant or team: Refer to the [creating a use case](/create-use-case/define) section for details.
 
 
 #### Optional for GPU Training Nodegroup
 
 Install the NVIDIA device plugin so Kubernetes can automatically detect and schedule GPUs on any new node:
 
 ```bash
 kubectl create -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.17.1/deployments/static/nvidia-device-plugin.yml
@@ -506,7 +506,7 @@
 - model checkpoints and weights during training
 - client logs
 
 Tracebloc leverages Amazon EFS (Elastic File System) to provide a scalable, managed file system that integrates directly with Kubernetes via the EFS CSI (Container Storage Interface) driver. It provides shared, persistent storage that all nodes and pods in the cluster can access at the same time.
 
 
 ### Create EFS File System
@@ -557,7 +557,7 @@
   --security-groups <SECURITY_GROUP_ID>
 ```
 
 Creates EFS mount targets in each subnet so nodes across all Availability Zones can attach to the same shared file system.
 
 ### Attach EFS CSI Driver Policy to Node Role
 
@@ -568,7 +568,7 @@
   --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEFSCSIDriverPolicy \
   --role-name <NODEGROUP_ROLE_NAME>
 ```
 Attaches the AWS-managed AmazonEFSCSIDriverPolicy to your nodegroup role. This lets the EFS CSI driver running on your nodes provision and mount EFS storage for pods, so workloads can share datasets, logs, and model checkpoints across the cluster.
 
 ### Add EFS CSI Driver Helm Repository
 
@@ -578,7 +578,7 @@
 helm repo add aws-efs-csi-driver https://kubernetes-sigs.github.io/aws-efs-csi-driver
 ```
 
 This command registers the AWS EFS CSI driver Helm repository with your local Helm setup. Once added, you can install or update the EFS CSI driver in your cluster using Helm commands. The driver runs as pods in the kube-system namespace and allows Kubernetes to dynamically provision and mount EFS volumes for your workloads.
 
 ### Configure EFS CSI Driver Placement
 
@@ -604,11 +604,11 @@
             values:
             - system
 ```
 This node affinity ensures the EFS CSI controller pods run on the system nodegroup (nodes labeled node.kubernetes.io/scope=system) instead of training nodes.
 
 ### Install EFS CSI Driver with Helm
 
 Now, the EFS CSI driver needs to be installed into the cluster (namespace kube-system by convention) using the configuration file.
 
 ```bash
 helm install efs-csi-driver aws-efs-csi-driver/aws-efs-csi-driver \
@@ -618,7 +618,7 @@
 
 ### Install Metrics Server
 
 The Metrics Server is the cluster-wide aggregator for resource usage data. It collects CPU and memory metrics for autoscaling and live resource monitoring. Install it to monitor resources usage:
 
 ```bash
 kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/high-availability-1.21+.yaml
@@ -629,12 +629,12 @@
 
 ## 5. Client Configuration
 
 You can now prepare the Helm chart that deploys the tracebloc client itself: The client is the component that runs your model evaluation and training jobs inside the cluster. To install it, you use a Helm chart, which bundles all required Kubernetes manifests into a single, configurable package.
 A values.yaml file controls this deployment, where you specify credentials (to authenticate with tracebloc), registry access (to pull container images), and storage settings (to mount your EFS volumes). This configuration ensures the client can securely connect, schedule workloads, and store results.
 
 ### Add Helm Repository
 
 The tracebloc client is delivered as a single unified Helm chart (`tracebloc/client`) that supports AKS, EKS, bare-metal, and OpenShift. Source: [tracebloc/client](https://github.com/tracebloc/client).
 
 ```bash
 helm repo add tracebloc https://tracebloc.github.io/client
@@ -651,7 +651,7 @@
 
 Open and update the following sections in `values.yaml`:
 
 #### Tracebloc Authentication
 
 Provide your Client ID and password from the [tracebloc client view](https://ai.tracebloc.io/clients):
 
@@ -662,7 +662,7 @@
 
 #### Docker Registry Configuration
 
 The tracebloc client images live on Docker Hub. Provide credentials so Kubernetes can pull them — the chart auto-creates a secret named `{{ .Release.Name }}-regcred`:
 
 ```yaml
 dockerRegistry:
@@ -711,7 +711,7 @@
 
 #### Set Resource Limits for Training Jobs
 
 Each training Job inherits these resource requests/limits. Make sure they fit within your EC2 instance capacity. **IMPORTANT:** For GPU jobs, `requests` and `limits` must be equal — Kubernetes rejects configs where they differ.
 
 ```yaml
 env:
@@ -721,7 +721,7 @@
   GPU_LIMITS: ""          # for GPU support set "nvidia.com/gpu=1"
 ```
 
 **Tip:** Estimating VRAM requirements for LLMs can be tricky. Use the [VRAM Calculator](https://apxml.com/tools/vram-calculator) to approximate memory needs for different model sizes and batch configurations.
 
 **Node, Pod, Job relationship**
 
@@ -769,11 +769,11 @@
 
 ## 6. Client Deployment
 
 With the configuration ready, deploy the tracebloc client into your EKS cluster using Helm.
 
 ### Deploy the client with Helm
 
 Install the chart into your namespace using your customized values file:
 
 ```bash
 helm install <RELEASE_NAME> tracebloc/client \
@@ -785,12 +785,12 @@
 This creates:
 
 - One MySQL pod: `mysql-...`
 - One tracebloc client pod: `<release>-jobs-manager-...`
 - A `tracebloc-resource-monitor` DaemonSet in the `tracebloc-node-agents` namespace
 - A `<release>-auto-upgrade` CronJob for daily chart upgrades (see [Configuration → Auto-upgrade](/environment-setup/configuration#auto-upgrade-on-by-default))
 - Supporting resources: Service, ConfigMap, Secrets, PVCs, PriorityClass, PDBs
 
 Expect a few minutes for pods to pull images, bind PVCs, and reach `Running`.
 
 
 ## Verification and Maintenance
@@ -798,7 +798,7 @@
 After deployment, confirm the client is running correctly and learn how to maintain it.
 
 ### Verify Deployment
 Check that all pods are running in your namespace:
 
 #### Check pod status:
 ```bash
@@ -816,7 +816,7 @@
 ```bash
 kubectl get pvc -n <NAMESPACE>
 ```
 Verifies that PVCs are bound and storage is available.
 
 ### Maintenance
 
@@ -865,3 +865,4 @@
 
 - Email: [support@tracebloc.io](mailto:support@tracebloc.io)
 - Docs: [tracebloc Documentation Portal](https://docs.tracebloc.io)
+

environment-setup/operations.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Operations"
 description: "Run, monitor, upgrade, and maintain a tracebloc workspace day to day."
 ---
 
 Everything you do *after* your workspace is running. Commands assume the default namespace `tracebloc` — substitute yours if you changed it.
 
 <Note>
 Day-to-day management — inspecting the cluster, ingesting and removing data — is easiest with the [tracebloc CLI](/environment-setup/cli). The Helm/kubectl commands here cover the lifecycle bits the CLI doesn't (upgrade, stop/start, uninstall) and deeper debugging.
 </Note>
 
 ## Which version am I on?
@@ -68,18 +68,19 @@
 <Tabs>
   <Tab title="Local / k3d">
   ```bash
   k3d cluster delete tracebloc      # removes the cluster and your workspace
   ```
   </Tab>
   <Tab title="Helm (any cluster)">
   ```bash
   helm uninstall tracebloc -n tracebloc
   ```
   </Tab>
 </Tabs>
 
 PVCs are annotated `helm.sh/resource-policy: keep`, so your data survives an uninstall. To remove it too: `kubectl delete pvc --all -n tracebloc`.
 
 ## Back up
 
 Your data lives in the data PVCs (or `~/.tracebloc` on a local install). Back up that directory / those volumes on your normal schedule — tracebloc keeps nothing of yours off your infrastructure.
+

environment-setup/overview.mdx

@@ -1,14 +1,14 @@
 ---
 title: "Overview"
 description: "How tracebloc runs on your infrastructure — and why your data never leaves it."
 ---
 
 **Models come to your data — your data never leaves your infrastructure.** You run a tracebloc *workspace* on your own hardware. Contributors submit models that are scanned and run in isolation against your data, on your machines. Only results leave — and trained model weights only if you choose to share them.
 
 ## The trust boundary
 
 <Frame>
   ![How tracebloc keeps your data on your infrastructure — models come to the data, only results leave](/images/traceblocfederatedlearning.png)
 </Frame>
 
 Raw data stays inside your infrastructure. Your workspace opens an **outbound-only** connection — nothing reaches in to pull your data out.
@@ -55,7 +55,7 @@
 
 | Term | What it is |
 |---|---|
 | **Workspace** | Your private, dedicated AI environment — tracebloc's software running on your own infrastructure, where you invite contributors to train models on your data |
 | **Client ID** | The credential that connects your workspace to the platform (created on the clients page) |
 | **Dataset** | Data you've staged locally for use cases |
 | **Use case** | A task contributors build models for, against your datasets |
@@ -79,3 +79,4 @@
 <Note>
 Want the guarantees in detail for your security team? See [Security & data handling](/environment-setup/configuration#security).
 </Note>
+

environment-setup/quickstart.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Quick Start"
 description: "From zero to a running tracebloc workspace in about 10 minutes."
 ---
 
 A running workspace in about 10 minutes, with one command. Deploying on a specific environment instead (EKS, AKS, bare-metal, OpenShift)? See [Deployment environments](/environment-setup/deployment-environments).
@@ -13,10 +13,10 @@
 
 | You need | Minimum |
 |---|---|
-| A machine | macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk |
+| A machine | macOS, Linux, or Windows · 2 CPU · 5 GB RAM · 10 GB free disk |
 | A tracebloc account | [Sign up free](https://ai.tracebloc.io) — no credit card |
 
-The installer runs below these too — it only warns, and more RAM mainly helps once models train.
+That's enough to run a workspace. To **train on this machine**, give it 4 CPU · 16 GB RAM · 50 GB disk — a single training job alone reserves ~8 GB. The installer checks before it starts: below the minimum it stops on Linux (on macOS/Windows it warns — raise Docker Desktop's memory in Settings → Resources).
 
 <Steps>
   <Step title="Register your workspace">
@@ -32,7 +32,7 @@
       </Tab>
       <Tab title="Windows (PowerShell as admin)">
       ```powershell
       irm https://tracebloc.io/i.ps1 | iex
       ```
       </Tab>
     </Tabs>
@@ -79,3 +79,4 @@
     Define a task and invite contributors.
   </Card>
 </CardGroup>
+

environment-setup/security.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Security & data handling"
 description: "What stays on your infrastructure, what leaves, and how tracebloc enforces it — the page to share with your security team."
 ---
 
 tracebloc is built so your data never has to leave your network. This page is the summary to hand to your security or compliance team.
 
 ## What's shared, what isn't
 
@@ -17,7 +17,7 @@
 ## How it's enforced
 
 - **Data locality.** Training runs against your data on your hardware. Raw data never crosses the boundary.
 - **Isolation.** Each training job runs in its own container with restricted system access; Kubernetes namespaces separate workloads.
 - **Network policy.** Training pods are denied data egress — they can't reach MySQL, other pods, or the Kubernetes API.
 - **Model scanning.** Submitted models are scanned for vulnerabilities (Bandit) before anything executes.
 - **Encryption in transit.** All workspace ↔ platform traffic is TLS, on an **outbound-only** connection.
@@ -35,3 +35,4 @@
 ## Outbound access
 
 Your workspace needs outbound HTTPS to: `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. Nothing needs to reach *in*.
+

environment-setup/setup-guide.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Setup Guide"
 description: "Detailed walkthrough for deploying a tracebloc workspace — requirements, installer internals, GPU support, and verification."
 ---
 
 Everything the installer does, explained. This page walks through the full setup process — what each step does, what to expect, and how to verify it worked.
@@ -13,17 +13,17 @@
 
 ## Requirements
 
-The installer runs on any modern machine (one host per workspace). These are the minimum specs to run a workspace comfortably:
+The installer runs on any modern machine (one host per workspace) and **checks these before it starts** — below the minimum it stops on Linux with a clear message (on macOS/Windows it warns; raise Docker Desktop's memory in Settings → Resources). "To run" keeps a workspace online; **training on the same machine needs the headroom** — a single training job alone reserves ~8 GB.
 
-| | Minimum | Recommended |
+| | To run the workspace | To train on this machine |
 |---|---------|-------------|
-| **CPU** | 2 cores | 8+ cores |
-| **RAM** | 4 GB | 16+ GB |
-| **Disk** | 20 GB free | 50+ GB free |
+| **CPU** | 2 cores | 4+ cores |
+| **RAM** | 5 GB | 16 GB |
+| **Disk** | 10 GB free | 50+ GB free |
 
 **Supported platforms:** macOS (Intel & Apple Silicon) · Linux (x86_64 & arm64) · Windows (x86_64 & arm64)
 
 **Outbound access needed:** The installer pulls container images, the install scripts, and the Helm chart, then connects to the tracebloc platform. Allow traffic to `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`.
 
 ---
 
@@ -33,7 +33,7 @@
 
 ## 2. Register a Client
 
 A **client** is your workspace's identity on the platform. It ties a specific machine to your account and controls what data and use cases are accessible from it.
 
 Open the [client page](https://ai.tracebloc.io/clients) and click **"+"**.
 
@@ -97,11 +97,11 @@
 **Step 2/4 — Set up secure compute environment**
 Provisions a lightweight local Kubernetes cluster inside Docker. First run takes 1–2 minutes to download components.
 
 **Step 3/4 — Install tracebloc client**
 Prompts for a **workspace name** (e.g. `berlin-team`, `vision-lab`, `ml-mardan`). This identifies the client on your machine and becomes the Kubernetes namespace.
 
 **Step 4/4 — Connect to tracebloc network**
 Prompts for your **Client ID** and **password** from step 2 above. This links your secure local environment to the tracebloc platform so vendors can submit models for evaluation.
 
 When it finishes you'll see a summary like:
 
@@ -146,7 +146,7 @@
 | `mysql-...` | Local metadata store — tracks jobs, metrics, and configuration |
 | `tracebloc-jobs-manager-...` | The client — executes training jobs and communicates with the platform |
 
 Then open [ai.tracebloc.io](https://ai.tracebloc.io) and check that your client status shows **Online**. This confirms the client has established a secure connection to the tracebloc backend.
 
 <Tip>
 Stuck on Offline? Check the [Troubleshooting](/environment-setup/troubleshooting) page — most issues resolve with a pod restart or credential check.
@@ -163,3 +163,4 @@
 **Data scientists:** [Join a use case](/join-use-case/join-use-case) — connect to a workspace, train models on real data, and submit results.
 
 **Advanced configuration:** [Configuration](/environment-setup/configuration) — customize installer options, manage the cluster, configure GPU settings, or deploy manually with Helm.
+

environment-setup/troubleshooting.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Troubleshooting"
 description: "Common issues and debugging commands for your tracebloc workspace."
 ---
 
 Most issues fall into a few categories: pods not starting, client not connecting, or resource limits being hit. Start with the quick checks below — they cover the most common problems.
@@ -43,7 +43,7 @@
 
 | Error Message | Description | Resolution |
 |---------------|-------------|------------|
 | ServiceBus connection error after Docker restart | When Docker overutilizes local resources and restarts, the ServiceBus connection may fail with `NoneType` errors. | Monitor resources via Docker Dashboard. Restart the jobs manager pod (e.g. in k9s, exit with Ctrl+D) to restore the connection. |
 
 ## Debugging Commands
 
@@ -105,7 +105,8 @@
 If training is slow, these are the factors to look at:
 
 - **Batch size** — larger batches increase GPU utilization up to memory saturation
 - **Model complexity** — transformer attention is O(seq_len² x hidden_dim); CNNs scale with kernel x feature map x filters
 - **Precision** — FP16/BF16 can speed up training 2-3x on modern GPUs
 - **Data pipeline** — slow CPU preprocessing (augmentation, tokenization) can bottleneck training
 - **Parallelization** — data parallelism splits batches across GPUs; model parallelism splits the model itself
+

join-use-case/explore-use-case.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Explore Use Cases"
 description: "Understand the use case page: leaderboard, description, EDA, training experiments, submissions and evaluation metrics."
 ---
 
 ## Understanding the Use Case View
@@ -9,9 +9,9 @@
 
 ![Use Case View](/images/Understanding-the-Use-Case-View.avif)
 
 ## 1. Leaderboard
 
 The leaderboard ranks the teams by their best performing model. After [submitting an experiment](/join-use-case/model-evaluation), the model gets evaluated on the test dataset or a dedicated evaluation dataset and will appear on the leaderboard.
 
 It includes:
 
@@ -47,7 +47,7 @@
 
 ---
 
 ## 4. Training / Finetuning
 
 View your model training experiments and those of your team members. If no trainings have yet been started and the tab is still empty, look at [template use case experiments](https://ai.tracebloc.io/explore).
 
@@ -59,7 +59,7 @@
 - **Performance Metrics**: Accuracy, F1 score, precision, recall, etc.
 - **Learning Curves**: Performance and loss learning curves
 - **Training Time**: Training duration and estimated remaining time
 - **Resource Usage**: Peta FLOPS (PFLOPS) and grams of CO2 equivalent (gCO2e) emissions utilized
 
 Find the detailed training plan, model architecture as well as a confusion matrix in the bottom tab of the experiment:
 
@@ -76,7 +76,7 @@
 
 ![My Submissions](/images/My-Submissions.avif)
 
 To prevent overfitting, daily submissions are limited. See [Evaluate Model](/join-use-case/model-evaluation#submit-to-leaderboard) for details. The leaderboard automatically picks the best submission.
 
 ---
 
@@ -95,3 +95,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

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

@@ -1,9 +1,9 @@
 ---
 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.
 
@@ -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,15 +487,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.
 
@@ -506,7 +506,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, 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.
@@ -528,3 +528,4 @@
 <Tip>
 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>
+

join-use-case/hyperparameters.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Hyperparameters"
 description: "Configure your model's training behavior by setting hyperparameters, training parameters, and augmentation options."
 ---
 
 ## Training Parameters
@@ -28,15 +28,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 +70,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 +115,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()` |
 
 
@@ -129,20 +129,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
@@ -151,15 +151,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)
@@ -176,10 +176,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.
 
@@ -191,8 +191,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)` |
 
 
@@ -211,4 +211,4 @@
 user.help()
 ```
 
-- Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+- Email us at [support@tracebloc.io](mailto:support@tracebloc.io)

join-use-case/join-use-case.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Join"
 description: "Learn how to join a use case on the tracebloc platform."
 ---
 
 To join a use case on our platform, the first step is to [sign up](https://ai.tracebloc.io/signup) at tracebloc.
 
 ## Joining Process
 
@@ -26,7 +26,7 @@
 
 1. **Click on the "+" button** next to your team name
 2. **Enter the email address** of the person you want to invite
 3. **Click "Invite"** - the invitee will receive an invitation to the team and to create a tracebloc account
 
 ![Invite Others](/images/Inviting-Others-to-Your-Team.avif)
 
@@ -35,3 +35,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

join-use-case/model-evaluation.mdx

@@ -1,24 +1,24 @@
 ---
 title: "Evaluate Model"
 description: "Learn how to evaluate your model on the test data and submit it to the leaderboard."
 ---
 
 
 ## Submit to Leaderboard
 
 Local evaluation is not possible since model weights are encrypted and cannot be downloaded.
 
 1. Navigate to the Training section of your use case, choose an experiment, hover over the learning curves to identify the best performing validation cycle, then enter it into the "Submit for inference" field
 2. Click "Submit" to start inference on the test dataset
 3. View your model's performance on the leaderboard tab once complete
 
 ![Submit a Model](/images/Submit-an-Experiment-to-the-Leaderboard.avif)
 
 **Note:** Track your team's remaining daily submissions at the top of the use case page. The number of submissions is restricted to 5 to prevent overfitting on the test dataset.
 
 ## Leaderboard Rankings
 
 Navigate to the Leaderboard section of your use case (e.g., [Breast Cancer Screening Use Case](https://ai.tracebloc.io/explore/ai-breast-cancer-screening-and-image-classification?tab=leaderboard)) to compare submitted models.
 
 Contributors are ranked by their best performing model score on the test data. Compare:
 
@@ -37,3 +37,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

join-use-case/model-optimization.mdx

@@ -1,6 +1,6 @@
 ---
 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."
 ---
 
 ## Use Pre-trained Weights
@@ -36,39 +36,39 @@
 ### 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
 
 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 +78,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 +131,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,10 +165,10 @@
 ```
 
 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
 
@@ -248,9 +248,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 +308,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.
 
@@ -348,3 +348,4 @@
 ## Need Help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

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,18 @@
 
 ## 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.
 
 
 → [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 +44,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)
 
@@ -53,3 +53,4 @@
 ## Need help?
 
 - Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+

join-use-case/start-training.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Start Training"
 description: "Step-by-step guide to training a model on the tracebloc platform."
 ---
 
 You have joined a use case and accepted the terms. Training a model is easy: you run a Jupyter notebook locally to connect and submit models to the workspace.
@@ -10,7 +10,7 @@
 
 ## Pull Training Notebook and Model Repositories
 
 On your machine, create a tracebloc folder and pull the [Training GitHub repository](https://github.com/tracebloc/start-training/tree/main) and the [Model Zoo GitHub repository](https://github.com/tracebloc/model-zoo/tree/master). The notebook contains all commands to connect and start training, the model zoo contains a selection of compatible models ready for training. The easiest way to customize models is by starting from the model zoo. Open a terminal and run the following commands:
 
 ```bash
 mkdir tracebloc && cd tracebloc
@@ -25,7 +25,7 @@
 
 ## Create a Virtual Environment
 
 Create a new environment, name it for example "tracebloc":
 
 ```bash
 conda create -n tracebloc python=3.9
@@ -58,9 +58,9 @@
 jupyter notebook notebooks/traceblocTrainingGuide.ipynb
 ```
 
 ## 1. Connect to the tracebloc workspace
 
 Follow the instructions in the notebook to authenticate. Have your tracebloc user credentials ready:
 
 ![Log in](/images/Connect-to-the-tracebloc-Client.avif)
 
@@ -84,7 +84,7 @@
 | Image     | Classification         | `image_size` has to match image x/y-dimensions <br></br> `output_classes` has to match # of image classes                                                             |
 | Image     | Object Detection       | `image_size` has to match image x/y-dimensions <br></br> `output_classes` has to match # of object types                                                              |
 | Image     | Semantic Segmentation  | `image_size` has to match image x/y-dimensions <br></br> `output_classes` has to match # of object classes                                                            |
 | Image     | Keypoint Detection     | `image_size` has to match image x/y-dimensions <br></br> `output_classes` has to match # of object classes <br></br> `num_feature_points` has to match # of keypoints |
 | Tabular   | Tabular Classification | `output_classes` has to match # of classes <br></br> `num_feature_points` has to match # of features                                                                  |
 | Text      | Text Classification    | `input_shape`<br></br> `sequence_length` <br></br> `output_classes`                                                                                                   |
 
@@ -171,7 +171,7 @@
 
 ## 4. Set Training Plan
 
 Set the experiment name and configure hyperparameters.
 
 ```python
 # Set experiment name
@@ -185,9 +185,9 @@
 training_plan.get_training_plan()
 ```
 
 Get the training plan to check settings before you start the training. For a detailed list of all hyperparameter options, see [Hyperparameters](/join-use-case/hyperparameters).
 
 For classical, non federated and non gradient descent-based machine learning algorithms like random forests, XGBoost, SVMs, logistic regression, use simplified settings:
 
 ```python
 # Set training parameters
@@ -222,9 +222,9 @@
 
 **Note:** The compute budget is set by the use case owner. Your team shares one compute budget with no per-person limit.
 
 ## Submit an Experiment to the Leaderboard
 
 Once training is complete, submit your best model to the leaderboard for evaluation on the test dataset. For the full submission flow and leaderboard details, see the [Evaluate Model guide](/join-use-case/model-evaluation#submit-to-leaderboard).
 
 ## Inviting Others to Your Team
 
@@ -244,4 +244,4 @@
 user.help()
 ```
 
-- Email us at [support@tracebloc.io](mailto:support@tracebloc.io)
+- Email us at [support@tracebloc.io](mailto:support@tracebloc.io)

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 />
@@ -73,17 +73,17 @@
     Contributors submit models and train inside your environment. PyTorch, TensorFlow, 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,10 +113,10 @@
   </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">
     GPU configuration, Helm deployment, EKS.
   </Card>
-</CardGroup>
+</CardGroup>

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.
@@ -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).
 
 ### Do you support fine-tuning?
 Yes — the same upload flow handles full training, fine-tuning with pretrained weights, and inference-only evaluation.
 
 ## Cost & support
 
@@ -61,3 +61,4 @@
 - [Get started](/environment-setup/setup-guide) — install the client
 - [Browse key terms](/tools-help/key-terms)
 - [Use the Python SDK](/tools-help/tracebloc)
+

tools-help/key-terms.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Key Terms"
 description: "Important terminology and concepts used in Tracebloc."
 ---
 
 Important terminology and concepts used in Tracebloc.
 
 ## Platform Terms
 - data owner
@@ -15,7 +15,7 @@
 A specific AI project or evaluation scenario where data owners and data scientists collaborate.
 
 ### Client
 The Tracebloc component deployed on the data owner's infrastructure that manages data and model execution.
 
 ### Model
 An AI/ML model submitted by data scientists for evaluation on the data owner's infrastructure.
@@ -46,3 +46,4 @@
 
 - [Check FAQs](/tools-help/faqs)
 - [Review SDK documentation](/tools-help/tracebloc)
+

tools-help/tracebloc.mdx

@@ -1,12 +1,12 @@
 ---
 title: "tracebloc Python SDK"
 description: "Python library for uploading models, linking them with datasets, configuring training parameters, and launching training runs on the tracebloc platform."
 ---
 
 `tracebloc` is a Python library for uploading models, linking them with datasets, configuring training parameters, and launching training runs on the tracebloc platform.
 
 <Note>
   The package was renamed from `tracebloc_package` to `tracebloc` in 0.8.0. The old name keeps working — `pip install tracebloc_package` resolves via a redirect, and `from tracebloc_package import User` still works with a `DeprecationWarning`. New code should use the canonical `tracebloc` name; the shim is removed in 1.0.0.
 </Note>
 
 ## Installation
@@ -24,7 +24,7 @@
 
 ## Key Features
 
 - Upload model files and pretrained weights
 - Link models with datasets from your use cases
 - Configure training parameters (epochs, optimizer, learning rate, augmentation, callbacks)
 - Review training plans before starting
@@ -67,15 +67,16 @@
 
 ## Model Zoo
 
 Use a ready-made model from the [tracebloc model zoo](https://github.com/tracebloc/model-zoo) or bring your own. Supported tasks include image classification, object detection, text classification, tabular classification/regression, time series forecasting, semantic segmentation, keypoint detection, and time-to-event prediction.
 
 ## Google Colab Quickstart
 
 The fastest way to get started is our [Google Colab notebook](https://colab.research.google.com/drive/1N00idtpoaq1lk9OJE6g4bMqd8o-Qex2C) — runs entirely in your browser, no local setup needed.
 
 ## Next Steps
 
 - [Start training](/join-use-case/start-training) — detailed walkthrough of the training workflow
 - [Hyperparameters](/join-use-case/hyperparameters) — full reference for all training configuration options
 - [FAQs](/tools-help/faqs)
 - [Key terms](/tools-help/key-terms)
+