From 89ffdc4d19d71d7ce4d782f2afd8888679558dd4 Mon Sep 17 00:00:00 2001 From: Divya Date: Mon, 11 May 2026 15:53:09 +0530 Subject: [PATCH 1/7] docs: consolidate Docker build into single multi-arch command (#35) Co-authored-by: Claude Opus 4.7 (1M context) --- create-use-case/prepare-dataset.mdx | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/create-use-case/prepare-dataset.mdx b/create-use-case/prepare-dataset.mdx index a2136ea..b8ee3d5 100644 --- a/create-use-case/prepare-dataset.mdx +++ b/create-use-case/prepare-dataset.mdx @@ -292,22 +292,9 @@ USER 1000 ### Build Docker Image -You need a docker user and password to proceed with the next step. Cloud platforms run a mix of x86 and ARM nodes (e.g. AWS Graviton, Azure Ampere, GCP Tau T2A). Building a multi-arch image with `--platform linux/amd64,linux/arm64` guarantees the image runs on either, particularly if you build on Apple Silicon (M1/M2) or other ARM-based systems. Pick a setup, build and deploy the image: - -#### For Local Development/Testing - -```bash -# Build for your local platform -docker build -t /: . - -# Optional: Push to registry for sharing -docker push /: -``` - -#### For Cloud Deployment (AWS, Azure, GCP) +You need a docker user and password to proceed with the next step. Cloud platforms run a mix of x86 and ARM nodes (e.g. AWS Graviton, Azure Ampere, GCP Tau T2A). Building a multi-arch image with `--platform linux/amd64,linux/arm64` guarantees the image runs on either, particularly if you build on Apple Silicon (M1/M2) or other ARM-based systems. Build and push the image with a single command: ```bash -# Build a multi-arch image (works on x86 and ARM cloud nodes) and push directly to the registry docker buildx build --platform linux/amd64,linux/arm64 -t /: --push . ``` From a16ce90e41885095e3e4805d9012354fc72cf67d Mon Sep 17 00:00:00 2001 From: Divya Date: Mon, 11 May 2026 15:53:19 +0530 Subject: [PATCH 2/7] docs: remove open-source client claim from how-training-works (#36) * docs: remove open-source client claim from how-training-works Co-Authored-By: Claude Opus 4.7 (1M context) * docs: say "contact us" instead of "open a support ticket" Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Asad Iqbal (Saadi) Co-authored-by: Claude Opus 4.7 (1M context) --- join-use-case/how-training-works.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/join-use-case/how-training-works.mdx b/join-use-case/how-training-works.mdx index 5e9a59b..ab0d252 100644 --- a/join-use-case/how-training-works.mdx +++ b/join-use-case/how-training-works.mdx @@ -5,7 +5,7 @@ description: "What the tracebloc client does to your data and model in each use This page documents the training and inference pipeline that the tracebloc client runs for every supported use case. The goal is full transparency: you can read what happens step-by-step, write an equivalent script on your own machine against the same dataset, and compare metrics number-for-number against what the platform reports. -If something here does not match what you observe in your run, please [open a support ticket](mailto:support@tracebloc.io) — the source of truth is the open client code in [`tracebloc/tracebloc-client`](https://github.com/tracebloc/tracebloc-client). +If something here does not match what you observe in your run, please [contact us](mailto:support@tracebloc.io) so we can investigate together. ## Shared lifecycle @@ -499,7 +499,7 @@ Common reasons numbers move: - **Stateful layers.** Batch normalization's running statistics, dropout masks, and any other stochastic layer state depend on batch order and initialization, both of which are sensitive to the points above. - **Mixed precision.** If your local run uses different mixed-precision settings than the platform did, you'll see small differences from rounding alone. -If your local numbers land within a reasonable band of the platform's, the run reproduced. If they diverge by a meaningful margin, please [open a support ticket](mailto:support@tracebloc.io) — that signals a real mismatch (likely preprocessing, data-slice, or configuration drift) worth investigating together. +If your local numbers land within a reasonable band of the platform's, the run reproduced. If they diverge by a meaningful margin, please [contact us](mailto:support@tracebloc.io) — that signals a real mismatch (likely preprocessing, data-slice, or configuration drift) worth investigating together. To validate a result you saw on the platform: @@ -526,5 +526,5 @@ To validate a result you saw on the platform: -The platform code is open source at [`tracebloc/tracebloc-client`](https://github.com/tracebloc/tracebloc-client) — if a number on your end doesn't line up with what the platform reports, please [open a support ticket](mailto:support@tracebloc.io) so we can investigate together. +If a number on your end doesn't line up with what the platform reports, please [contact us](mailto:support@tracebloc.io) so we can investigate together. From 0e6fa7418f5582a735d5507bfe92ccba20fdc39e Mon Sep 17 00:00:00 2001 From: Divya Date: Wed, 13 May 2026 15:28:13 +0530 Subject: [PATCH 3/7] docs: add automated upstream sync workflow (#27) * docs: add automated upstream sync workflow Adds a Claude-powered workflow that syncs docs pages with upstream README changes from five source repos (tracebloc-py-package, client, start-training, data-ingestors, model-zoo). Source repos fire repository_dispatch on push; this repo's workflow fetches the upstream file, has Claude rewrite the target .mdx in docs voice, and opens a PR. - .github/sync-sources.yml: mapping of upstream files to docs pages - .github/workflows/sync-docs.yml: dispatch + manual + cron-driven sync job - .github/notify-docs.workflow-template.yml: template for source repos Co-Authored-By: Claude Opus 4.7 (1M context) * fix: address bugbot issues in sync workflow - Pass ANTHROPIC_API_KEY as anthropic_api_key input to claude-code-action instead of env var (action reads via core.getInput, not env). - Move sync cache from .sync-cache/ to /tmp/sync-cache/ so untracked cache files are not picked up by create-pull-request. Co-Authored-By: Claude Opus 4.7 * fix: address remaining bugbot issues in sync workflow - Add concurrency group so overlapping cron/dispatch/manual runs serialize instead of racing on the docs/sync-upstream branch (would otherwise fail with "failed to push some refs" and drop changes from the losing run). - Pin yq to v4.44.3 instead of latest for deterministic builds. - Restrict create-pull-request add-paths to **/*.mdx so stray edits outside docs pages cannot be staged into the sync PR. - Note in the notify template that branches may need adjusting for repos using master (e.g. data-ingestors). Co-Authored-By: Claude Opus 4.7 * fix: accumulate sync runs onto existing PR branch Previously each run checked out the default branch fresh and force-pushed only the dispatched source's diff to docs/sync-upstream, silently overwriting any earlier dispatched sources' pending changes. Now the workflow: - Checks if docs/sync-upstream exists on the remote; if so, checks it out so prior accumulated changes are part of the working tree. - Resolves the default branch dynamically and passes it to peter-evans as the explicit base so the PR continues targeting the right branch even after we switched off it. Result: sequential dispatches for different sources combine into one PR instead of clobbering each other. Co-Authored-By: Claude Opus 4.7 * fix: read sync-sources.yml from base branch, not stale sync branch After the previous fix switched the working tree to docs/sync-upstream to accumulate changes, all subsequent reads of .github/sync-sources.yml were coming from the (potentially stale) sync branch instead of the base branch. If a new source were added or an instruction edited on main while a sync PR was pending, the workflow would silently use the outdated config. Snapshot the mapping to /tmp/sync-sources.yml before any branch switch, and point both the yq filter step and the Claude prompt at the snapshot. Co-Authored-By: Claude Opus 4.7 --------- Co-authored-by: Claude Opus 4.7 (1M context) Co-authored-by: Asad Iqbal --- .github/notify-docs.workflow-template.yml | 33 +++++ .github/sync-sources.yml | 69 ++++++++++ .github/workflows/sync-docs.yml | 149 ++++++++++++++++++++++ 3 files changed, 251 insertions(+) create mode 100644 .github/notify-docs.workflow-template.yml create mode 100644 .github/sync-sources.yml create mode 100644 .github/workflows/sync-docs.yml diff --git a/.github/notify-docs.workflow-template.yml b/.github/notify-docs.workflow-template.yml new file mode 100644 index 0000000..2c608ec --- /dev/null +++ b/.github/notify-docs.workflow-template.yml @@ -0,0 +1,33 @@ +# Template — copy into each upstream source repo as +# .github/workflows/notify-docs.yml +# +# Replace below with the matching `id` from +# tracebloc/docs:.github/sync-sources.yml +# +# Adjust the `paths:` filter if the watched file is not README.md. +# Adjust `branches:` if the source repo's default branch is not `main` +# (e.g. some tracebloc repos use `master`). +# +# Required: an org-level (or repo-level) secret named DOCS_DISPATCH_TOKEN. +# - Fine-grained PAT scoped to repo `tracebloc/docs` +# - Permission: Contents: Read and write (needed to fire repository_dispatch) + +name: Notify docs of upstream change + +on: + push: + branches: [main] + paths: + - "README.md" + +jobs: + notify: + runs-on: ubuntu-latest + steps: + - name: Trigger docs sync + env: + GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }} + run: | + gh api repos/tracebloc/docs/dispatches \ + -f event_type=upstream-changed \ + -f 'client_payload[source_id]=' diff --git a/.github/sync-sources.yml b/.github/sync-sources.yml new file mode 100644 index 0000000..ea966b0 --- /dev/null +++ b/.github/sync-sources.yml @@ -0,0 +1,69 @@ +# Mapping: upstream source files → docs pages +# +# Add a new source by appending an entry. The `id` is also used in the +# source repo's notify workflow (see .github/notify-docs.workflow-template.yml) +# to tell this repo which mapping changed. +# +# Fields: +# id unique slug for this mapping +# repo owner/name of the upstream repo +# ref branch or tag to read from +# src file path inside the upstream repo +# dest path in this repo (must exist) +# private true if the repo is private (requires SOURCE_REPOS_TOKEN) +# instruction natural-language brief Claude follows when updating dest + +sources: + - id: tracebloc-package + repo: tracebloc/tracebloc-py-package + ref: main + src: README.md + dest: tools-help/tracebloc-package.mdx + private: true + instruction: | + Sync the Installation, Key Features, and Quick Start sections to reflect + the upstream README. Preserve the page frontmatter and any prose that is + unique to the docs page (e.g. links to other Mintlify pages). + + - id: client-setup + repo: tracebloc/client + ref: main + src: README.md + dest: environment-setup/setup-guide.mdx + private: false + instruction: | + Sync installer steps, requirements, supported platforms, and verification + commands. Preserve the page's narrative framing (numbered top-level steps, + requirements table) and any prose unique to the docs page. + + - id: start-training + repo: tracebloc/start-training + ref: main + src: README.md + dest: join-use-case/start-training.mdx + private: false + instruction: | + Sync notebook setup and the steps for launching experiments to match the + upstream README. Preserve cross-links to other Join-a-Use-Case pages. + + - id: data-ingestors + repo: tracebloc/data-ingestors + ref: main + src: Readme.md + dest: create-use-case/prepare-dataset.mdx + private: false + instruction: | + Sync dataset preparation pipeline steps, supported formats, and ingestor + configuration from the upstream README. Preserve the page frontmatter and + any examples specific to the docs page. + + - id: model-zoo + repo: tracebloc/model-zoo + ref: main + src: README.md + dest: create-use-case/templates.mdx + private: false + instruction: | + Sync the list of available model templates and their descriptions from the + upstream README. Preserve the page frontmatter and any prose specific to + the docs page. diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml new file mode 100644 index 0000000..037180e --- /dev/null +++ b/.github/workflows/sync-docs.yml @@ -0,0 +1,149 @@ +name: Sync docs from upstream + +# Triggers: +# - repository_dispatch: fired by source repos when a watched file changes (push-driven) +# - workflow_dispatch: manual run from the Actions tab (optional source_id input) +# - schedule: daily safety-net in case a dispatch is missed +on: + repository_dispatch: + types: [upstream-changed] + workflow_dispatch: + inputs: + source_id: + description: "Specific source id from sync-sources.yml (leave empty for all)" + required: false + type: string + schedule: + - cron: "0 6 * * *" + +permissions: + contents: write + pull-requests: write + +concurrency: + group: sync-docs + cancel-in-progress: false + +jobs: + sync: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Resolve PR base and accumulate onto existing sync branch + id: setup + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + base=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name) + echo "base=$base" >> "$GITHUB_OUTPUT" + # Snapshot the mapping from the base branch BEFORE possibly switching + # to the sync branch, so we never use a stale config from a pending + # PR (e.g. if a new source was added on main after the PR opened). + cp .github/sync-sources.yml /tmp/sync-sources.yml + if git ls-remote --exit-code --heads origin docs/sync-upstream >/dev/null 2>&1; then + echo "Existing docs/sync-upstream branch found — checking it out so this run accumulates onto pending changes." + git fetch origin docs/sync-upstream:docs/sync-upstream + git checkout docs/sync-upstream + else + echo "No existing sync branch — starting from $base." + fi + + - name: Install yq + run: | + sudo wget -qO /usr/local/bin/yq \ + https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 + sudo chmod +x /usr/local/bin/yq + + - name: Resolve target sources + id: filter + env: + DISPATCH_ID: ${{ github.event.client_payload.source_id }} + INPUT_ID: ${{ inputs.source_id }} + run: | + target="${DISPATCH_ID:-${INPUT_ID:-}}" + if [ -n "$target" ]; then + echo "Filtering for source: $target" + yq -o=json ".sources[] | select(.id == \"$target\")" \ + /tmp/sync-sources.yml | jq -s . > /tmp/sources.json + else + echo "Processing all sources" + yq -o=json '.sources' /tmp/sync-sources.yml > /tmp/sources.json + fi + count=$(jq length /tmp/sources.json) + echo "count=$count" >> "$GITHUB_OUTPUT" + echo "Found $count source(s) to process" + if [ "$count" = "0" ]; then + echo "Nothing to do." + fi + + - name: Fetch upstream files + if: steps.filter.outputs.count != '0' + env: + GH_TOKEN: ${{ secrets.SOURCE_REPOS_TOKEN || secrets.GITHUB_TOKEN }} + run: | + mkdir -p /tmp/sync-cache + jq -c '.[]' /tmp/sources.json | while read -r s; do + id=$(jq -r .id <<<"$s") + repo=$(jq -r .repo <<<"$s") + ref=$(jq -r .ref <<<"$s") + src=$(jq -r .src <<<"$s") + echo "Fetching $repo@$ref:$src -> /tmp/sync-cache/$id" + gh api "repos/$repo/contents/$src?ref=$ref" \ + -H "Accept: application/vnd.github.raw" \ + > "/tmp/sync-cache/$id" + done + ls -la /tmp/sync-cache + + - name: Run Claude to update docs + if: steps.filter.outputs.count != '0' + uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + prompt: | + You are syncing this Mintlify docs site with upstream README changes. + + The mapping is at `/tmp/sync-sources.yml` (snapshotted from the + base branch at the start of this run, so it is always current). + The list of sources to process this run is at `/tmp/sources.json`. + For each source, the latest upstream file content is at + `/tmp/sync-cache/`. + + For every entry in `/tmp/sources.json`: + 1. Read `/tmp/sync-cache/` (upstream) and the docs page at `dest`. + 2. Apply the entry's `instruction` to update the docs page in place. + 3. Preserve YAML frontmatter, page-specific framing, links to other + Mintlify pages, and any callouts/components already on the page. + 4. Follow `AGENTS.md` style: active voice, second person, sentence + case headings, **bold** for UI elements, `code` for paths and + commands. + 5. If the upstream content does not meaningfully change anything in + the docs page, skip that source — do not edit the file. + + Do not edit any files outside the `dest` paths listed in the + sources. Do not touch `/tmp/sync-cache/`, `/tmp/sources.json`, + or `/tmp/sync-sources.yml`. + + - name: Open or update PR + if: steps.filter.outputs.count != '0' + uses: peter-evans/create-pull-request@v6 + with: + base: ${{ steps.setup.outputs.base }} + branch: docs/sync-upstream + delete-branch: true + add-paths: "**/*.mdx" + commit-message: "docs: sync upstream sources" + title: "docs: sync upstream sources" + body: | + Automated sync from upstream repos via Claude. + + **Triggered by:** `${{ github.event_name }}` + **Source filter:** `${{ github.event.client_payload.source_id || inputs.source_id || 'all' }}` + + Review carefully — Claude rewrites prose to fit docs style, but + verify accuracy against the upstream README before merging. + labels: | + docs-sync + automated From 91dfae5aa85b3fdf3814c7f1841ac9eddf0b4e11 Mon Sep 17 00:00:00 2001 From: Divya Date: Wed, 13 May 2026 17:00:01 +0530 Subject: [PATCH 4/7] docs: migrate join-use-case API examples to snake_case (tracebloc_package 0.7.0) (#14) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sync hyperparameters and start-training pages with the legacy tracebloc/documentation repo: - Rename camelCase API methods to snake_case: upload_model, link_model_dataset, experiment_name, get_training_plan, learning_rate, loss_function, layers_freeze, early_stop_callback, reduce_lr_callback, model_checkpoint_callback, terminate_on_nan_callback, training_classes, data_type - Rename trainingObject → training - Update terminate-on-NaN description (any NaN loss) - Use pip optional-extras syntax: tracebloc_package[pytorch|tensorflow|sklearn|all] Co-authored-by: Claude Opus 4.7 (1M context) --- join-use-case/hyperparameters.mdx | 78 +++++++++++++++---------------- join-use-case/start-training.mdx | 25 ++++++---- 2 files changed, 54 insertions(+), 49 deletions(-) diff --git a/join-use-case/hyperparameters.mdx b/join-use-case/hyperparameters.mdx index 0a8c3ba..c78284e 100644 --- a/join-use-case/hyperparameters.mdx +++ b/join-use-case/hyperparameters.mdx @@ -5,14 +5,14 @@ description: "Configure your model's training behavior by setting hyperparameter ## Training Parameters -All parameters are set through the `trainingObject` after linking your model with the dataset. +All parameters are set through the `training` after linking your model with the dataset. ```python -trainingObject = user.linkModelDataset('Dataset ID') +training = user.link_model_dataset('Dataset ID') ``` -To see all current parameter settings, run `trainingObject.getTrainingPlan()`. To run consecutive experiments, overwrite parameters and re-start training with `trainingObject.start()`. +To see all current parameter settings, run `training.get_training_plan()`. To run consecutive experiments, overwrite parameters and re-start training with `training.start()`. You can refer to the [TensorFlow Documentation](https://www.tensorflow.org/api_docs/python/tf/keras/preprocessing/image/ImageDataGenerator) for more information on TensorFlow augmentation parameters and the [PyTorch Documentation](https://albumentations.ai/docs/examples/pytorch-classification/) for more information on PyTorch augmentation parameters. @@ -23,10 +23,10 @@ Basic training configuration parameters that control the fundamental aspects of | Parameter | Description | Default | Example | |-----------|-------------|---------|---------| -| **Epochs** | Number of complete passes through the entire dataset | 10 | `trainingObject.epochs(100)` | -| **Cycles** | Number of complete passes through training and validation datasets | 1 | `trainingObject.cycles(10)` | +| **Epochs** | Number of complete passes through the entire dataset | 10 | `training.epochs(100)` | +| **Cycles** | Number of complete passes through training and validation datasets | 1 | `training.cycles(10)` | | **Batch Size** | Number of samples processed at one time. Set automatically from the `batch_size` variable in your model file | Datatype dependent

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

20% in most cases | `trainingObject.validation_split(0.2)` | +| **Validation Split** | Percentage of dataset used for validation (0-1) | Dataset dependent

20% in most cases | `training.validation_split(0.2)` | ## Core Hyperparameters @@ -39,7 +39,7 @@ Controls how the model's parameters are updated during training. Supports differ - **PyTorch**: adam, rmsprop, sgd, adadelta, adagrad, adamax ```python -trainingObject.optimizer('rmsprop') +training.optimizer('rmsprop') ``` ### 2. Learning Rate @@ -48,20 +48,20 @@ Controls the rate at which the model learns. Supports three different types: | Type | Description | Framework Support | Example | |------|-------------|-------------------|---------| -| **Constant** | Fixed learning rate throughout training | TensorFlow, PyTorch | `trainingObject.learningRate({'type': 'constant', 'value': 0.002})` | -| **Adaptive** | Learning rate that changes based on schedule | TensorFlow | `trainingObject.learningRate({'type': 'adaptive', 'value': {'decay_rate': 0.9, 'decay_steps': 100, 'initial_learning_rate': 0.1, 'scheduler': 'ExponentialDecay'}})` | -| **Custom** | User-defined learning rate function | TensorFlow | `trainingObject.learningRate({'type': 'custom', 'value': {'name': custom_function, 'epoch': 5}})` | +| **Constant** | Fixed learning rate throughout training | TensorFlow, PyTorch | `training.learning_rate({'type': 'constant', 'value': 0.002})` | +| **Adaptive** | Learning rate that changes based on schedule | TensorFlow | `training.learning_rate({'type': 'adaptive', 'value': {'decay_rate': 0.9, 'decay_steps': 100, 'initial_learning_rate': 0.1, 'scheduler': 'ExponentialDecay'}})` | +| **Custom** | User-defined learning rate function | TensorFlow | `training.learning_rate({'type': 'custom', 'value': {'name': custom_function, 'epoch': 5}})` | **Default:** `{'type': 'constant', 'value': 0.001}` -* **Custom for TensorFlow**: Define a custom learning rate function, then pass it via `learningRate()` with `type: 'custom'`: +* **Custom for TensorFlow**: Define a custom learning rate function, then pass it via `learning_rate()` with `type: 'custom'`: ```python def custom_LearningRate_scheduler(epoch): if epoch < 5: return 0.01 else: return 0.01 * tf.math.exp(0.1 * (10 - epoch)) - trainingObject.learningRate({'type': 'custom', 'value': {'name': custom_LearningRate_scheduler, 'epoch': 5}}) + training.learning_rate({'type': 'custom', 'value': {'name': custom_LearningRate_scheduler, 'epoch': 5}}) ``` @@ -75,7 +75,7 @@ Defines how the model measures prediction errors. Supports standard and custom l ```python # Standard loss function -trainingObject.lossFunction({'type': 'standard', 'value': 'categorical_crossentropy'}) +training.loss_function({'type': 'standard', 'value': 'categorical_crossentropy'}) # Custom loss function (TensorFlow only) def custom_mse(y_true, y_pred): @@ -89,7 +89,7 @@ def custom_mse(y_true, y_pred): loss = K.sum(loss, axis=1) # (batch_size,) return loss -trainingObject.lossFunction({'type': 'custom', 'value': custom_mse}) +training.loss_function({'type': 'custom', 'value': custom_mse}) ``` **Default:** `{'type': 'standard', 'value': 'mse'}` @@ -100,7 +100,7 @@ trainingObject.lossFunction({'type': 'custom', 'value': custom_mse}) Specify which layers should remain unchanged during training (TensorFlow only): ```python -trainingObject.layersFreeze(['conv1','fc1']) +training.layers_freeze(['conv1','fc1']) ``` @@ -113,10 +113,10 @@ Control training behavior with various callbacks: | Callback | Purpose | Parameters | Example | |----------|---------|------------|---------| -| **Early Stopping** | Stop training when metric stops improving | metric, patience | `trainingObject.earlystopCallback('loss', 10)` | -| **Reduce LR** | Reduce learning rate when metric plateaus | metric, factor, patience, threshold | `trainingObject.reducelrCallback('loss', 0.1, 10, 0.0001)` | -| **Model Checkpoint** | Save model weights at specific intervals | metric, save_best_only | `trainingObject.modelCheckpointCallback('val_loss', True)` | -| **Terminate on NaN** | Stop training if validation loss becomes NaN | None | `trainingObject.terminateOnNaNCallback()` | +| **Early Stopping** | Stop training when metric stops improving | metric, patience | `training.early_stop_callback('loss', 10)` | +| **Reduce LR** | Reduce learning rate when metric plateaus | metric, factor, patience, threshold | `training.reduce_lr_callback('loss', 0.1, 10, 0.0001)` | +| **Model Checkpoint** | Save model weights at specific intervals | metric, save_best_only | `training.model_checkpoint_callback('val_loss', True)` | +| **Terminate on NaN** | Stop training when a NaN loss is encountered | None | `training.terminate_on_nan_callback()` | @@ -129,21 +129,21 @@ Enhance your dataset with real-time image transformations. All parameters suppor | 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 | `trainingObject.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 | `trainingObject.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 | `trainingObject.height_shift_range(0.1)` | -| **shear_range** | Shear intensity in degrees in counter-clockwise direction | 0.0 | TensorFlow | `trainingObject.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 | `trainingObject.zoom_range(0.1)`, `trainingObject.zoom_range([0.2, 0.8])` | -| **horizontal_flip** | Randomly flip images horizontally | False | TensorFlow | `trainingObject.horizontal_flip(True)` | -| **vertical_flip** | Randomly flip images vertically | False | TensorFlow | `trainingObject.vertical_flip(True)` | +| **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.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.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.height_shift_range(0.1)` | +| **shear_range** | Shear intensity in degrees in counter-clockwise direction | 0.0 | TensorFlow | `training.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.zoom_range(0.1)`, `training.zoom_range([0.2, 0.8])` | +| **horizontal_flip** | Randomly flip images horizontally | False | TensorFlow | `training.horizontal_flip(True)` | +| **vertical_flip** | Randomly flip images vertically | False | TensorFlow | `training.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 | `trainingObject.brightness_range((0.1,0.4))` | -| **channel_shift_range** | Range for random channel shifts | 0 | TensorFlow, PyTorch* | `trainingObject.channel_shift_range(0.4)` | -| **rescale** | Rescaling factor for pixel values (float) | None | TensorFlow, PyTorch | `trainingObject.rescale(1.0/255.0)` | +| **brightness_range** | Range for brightness shifts (tuple of floats) | None | TensorFlow, PyTorch | `training.brightness_range((0.1,0.4))` | +| **channel_shift_range** | Range for random channel shifts | 0 | TensorFlow, PyTorch* | `training.channel_shift_range(0.4)` | +| **rescale** | Rescaling factor for pixel values (float) | None | TensorFlow, PyTorch | `training.rescale(1.0/255.0)` | *PyTorch: Only supported for RGB images @@ -151,16 +151,16 @@ Enhance your dataset with real-time image transformations. All parameters suppor | Parameter | Description | Default | Framework Support | Example | |-----------|-------------|---------|-------------------|---------| -| **samplewise_center** | Center each image by subtracting mean | False | TensorFlow | `trainingObject.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 | `trainingObject.samplewise_std_normalization(True)` | +| **samplewise_center** | Center each image by subtracting mean | False | TensorFlow | `training.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.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 | `trainingObject.fill_mode("nearest")` | -| **cval** | Fill value for points outside the image boundaries when fill_mode="constant" | 0.0 | TensorFlow, PyTorch | `trainingObject.cval(0.3)` | -| **shuffle** | Whether to shuffle the data | True | TensorFlow, PyTorch | `trainingObject.shuffle(True)` | +| **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.fill_mode("nearest")` | +| **cval** | Fill value for points outside the image boundaries when fill_mode="constant" | 0.0 | TensorFlow, PyTorch | `training.cval(0.3)` | +| **shuffle** | Whether to shuffle the data | True | TensorFlow, PyTorch | `training.shuffle(True)` | ## LLM Parameters (Text Classification) @@ -168,10 +168,10 @@ For text classification tasks in PyTorch, you can enable and configure LoRA (Low ```python # Enable LoRA first -trainingObject.enable_lora(True) +training.enable_lora(True) # Configure LoRA parameters (positional arguments: lora_r, lora_alpha, lora_dropout, q_lora) -trainingObject.set_lora_parameters(256, 512, 0.05, False) +training.set_lora_parameters(256, 512, 0.05, False) ``` | Parameter | Description | Type | Default | Example | @@ -191,9 +191,9 @@ Customize your dataset configuration and preprocessing options: | Parameter | Description | Example | |-----------|-------------|---------| -| **trainingClasses** | Customize dataset by specifying samples per class | `trainingObject.trainingClasses({'car': 30, 'person': 30})` | -| **dataType** | Image format: 'rgb' or 'grayscale' | `trainingObject.dataType('rgb')` | -| **seed** | Set global random seed | `trainingObject.seed(True)` | +| **training_classes** | Customize dataset by specifying samples per class | `training.training_classes({'car': 30, 'person': 30})` | +| **data_type** | Image format: 'rgb' or 'grayscale' | `training.data_type('rgb')` | +| **seed** | Set global random seed | `training.seed(True)` | --- diff --git a/join-use-case/start-training.mdx b/join-use-case/start-training.mdx index 7183db7..6ea7471 100644 --- a/join-use-case/start-training.mdx +++ b/join-use-case/start-training.mdx @@ -36,7 +36,12 @@ Then, install requirements: ```bash python -m pip install --upgrade pip -pip install tracebloc_package + +# Install with the extra that matches your framework: +pip install "tracebloc_package[pytorch]" +# pip install "tracebloc_package[tensorflow]" +# pip install "tracebloc_package[sklearn]" +# pip install "tracebloc_package[all]" # legacy behaviour — all frameworks ``` ## Install and Launch Jupyter Notebook @@ -149,7 +154,7 @@ In case of multiple uploads, only the most recently uploaded model will be linke Upload the model to the use case workspace from your notebook: ```python -user.uploadModel("../../model-zoo/model_zoo///model.py") +user.upload_model("../../model-zoo/model_zoo///model.py") ``` For details on model code formats, mandatory variables per framework, and pre-trained weights, see [Customize Models](/join-use-case/model-optimization). @@ -159,7 +164,7 @@ For details on model code formats, mandatory variables per framework, and pre-tr Navigate to the use case and copy the "Training Dataset ID" at the center of the use case pane and enter it to establish the link ```python -trainingObject = user.linkModelDataset('Dataset ID') +training = user.link_model_dataset('Dataset ID') ``` You should get "Assignment successful!" and the dataset parameters. @@ -170,14 +175,14 @@ Set the experiment name and configure hyperparameters. ```python # Set experiment name -trainingObject.experimentName("My Experiment") +training.experiment_name("My Experiment") # Set training parameters -trainingObject.epochs(10) +training.epochs(10) ... # Get training plan -trainingObject.getTrainingPlan() +training.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). @@ -186,10 +191,10 @@ For classical, non federated and non gradient descent-based machine learning alg ```python # Set training parameters -trainingObject.epochs(1) +training.epochs(1) # Set federated learning cycles = 1 -trainingObject.cycles(1) +training.cycles(1) ``` @@ -198,13 +203,13 @@ trainingObject.cycles(1) To send the model to the workspace infrastructure and start training on the training data, run: ```python -trainingObject.start() +training.start() ``` Go to the [tracebloc website](https://ai.tracebloc.io/my-use-cases) and your use case, then navigate to the "Training/Finetuning" tab you will see your experiment. Monitor the training process hover over the learning curves to check the performance at specific epochs and cycles. -If you want to run a second experiment, overwrite parameters and re-start training with `trainingObject.start()`. +If you want to run a second experiment, overwrite parameters and re-start training with `training.start()`. ### Pause, Re-Start and Stop: From 97ba9ced1c825bb791a5be04dba16a03ce08fd69 Mon Sep 17 00:00:00 2001 From: "Asad Iqbal (Saadi)" Date: Wed, 13 May 2026 16:43:43 +0500 Subject: [PATCH 5/7] docs: migrate SDK page to tracebloc 0.8.x (#39) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: migrate SDK page to tracebloc 0.8.x (closes #38) The SDK was renamed in tracebloc/tracebloc-py-package#135. `tracebloc==0.8.1` is live on PyPI. Migrating Mintlify docs to the canonical name. - Rename `tools-help/tracebloc-package.mdx` -> `tools-help/tracebloc.mdx`. - Rewrite the page: `tracebloc` install + import, snake_case API (post-SDK.2), historical Note about the rename, link to redirect package on PyPI. - Bump install pin to `>=0.8.0` (was `>=0.6.32`); add per-extra install options. - `docs.json`: - Nav: `tools-help/tracebloc-package` -> `tools-help/tracebloc`. - Add `/tools-help/tracebloc-package` -> `/tools-help/tracebloc` redirect to preserve old inbound links. - Existing redirects pointing at `/tools-help/tracebloc-package` now point at `/tools-help/tracebloc`. - Internal cross-links in faqs.mdx + key-terms.mdx -> new URL. - `join-use-case/start-training.mdx` install snippet -> new name + pin. Co-Authored-By: Claude Opus 4.7 * docs: bump install pin to 0.8.1 (latest) * docs: migrate SDK examples to snake_case API (post-SDK.2) The 0.7.0 SDK.2 release renamed the public Python API to PEP 8 / snake_case. The old camelCase forms still work via deprecation aliases (with DeprecationWarning) but new examples should use the canonical names. Updates the three customer-facing pages that still showed the camelCase API: - `join-use-case/start-training.mdx` — the main walk-through. - `join-use-case/hyperparameters.mdx` — the full reference table. - `join-use-case/model-optimization.mdx` — pretrained-weights upload. Method renames applied (per tracebloc-py-package/MIGRATION.md): - `uploadModel` -> `upload_model` (+ `model_name=` kwarg) - `linkModelDataset` -> `link_model_dataset` (+ `dataset_id=` kwarg) - `getTrainingPlan` -> `get_training_plan` - `experimentName` -> `experiment_name` - `learningRate` -> `learning_rate` - `lossFunction` -> `loss_function` - `layersFreeze` -> `layers_freeze` - `earlystopCallback` -> `early_stop_callback` - `reducelrCallback` -> `reduce_lr_callback` - `modelCheckpointCallback` -> `model_checkpoint_callback` - `terminateOnNaNCallback` -> `terminate_on_nan_callback` - `trainingClasses` -> `training_classes` - `dataType` -> `data_type` The `model_name` and `dataset_id` keyword names are no longer aliased in 0.8.x — passing positional args still works, but the kwargs `modelname=` / `datasetId=` raise TypeError, so the docs use the explicit kwarg form everyone should adopt. Also renames the local variable `trainingObject` -> `training_plan` throughout, matching the canonical sample workflow in tracebloc's project CLAUDE.md. Co-Authored-By: Claude Opus 4.7 * fix(ci): update sync-sources.yml dest after file rename (bugbot) `tools-help/tracebloc-package.mdx` was renamed to `tools-help/tracebloc.mdx` earlier in this PR, but the daily `sync-docs.yml` cron reads `.github/sync-sources.yml` and would have either recreated the old orphan path or failed outright — silently preventing upstream README edits from reaching the new page. Repointing the dest at `tools-help/tracebloc.mdx` keeps the upstream README -> docs page sync working. The mapping `id` stays `tracebloc-package` (it's a slug used for dispatch; changing it would need a coordinated edit in the upstream notify workflow, which doesn't exist yet — scope creep here). Co-Authored-By: Claude Opus 4.7 --------- Co-authored-by: Claude Opus 4.7 --- .github/sync-sources.yml | 2 +- docs.json | 11 +-- join-use-case/hyperparameters.mdx | 76 +++++++++---------- join-use-case/model-optimization.mdx | 4 +- join-use-case/start-training.mdx | 26 +++---- tools-help/faqs.mdx | 4 +- tools-help/key-terms.mdx | 2 +- .../{tracebloc-package.mdx => tracebloc.mdx} | 39 ++++++---- 8 files changed, 88 insertions(+), 76 deletions(-) rename tools-help/{tracebloc-package.mdx => tracebloc.mdx} (54%) diff --git a/.github/sync-sources.yml b/.github/sync-sources.yml index ea966b0..21638b6 100644 --- a/.github/sync-sources.yml +++ b/.github/sync-sources.yml @@ -18,7 +18,7 @@ sources: repo: tracebloc/tracebloc-py-package ref: main src: README.md - dest: tools-help/tracebloc-package.mdx + dest: tools-help/tracebloc.mdx private: true instruction: | Sync the Installation, Key Features, and Quick Start sections to reflect diff --git a/docs.json b/docs.json index 7778f05..042d90b 100644 --- a/docs.json +++ b/docs.json @@ -84,7 +84,7 @@ { "group": "Tools & Help", "pages": [ - "tools-help/tracebloc-package", + "tools-help/tracebloc", "tools-help/faqs", "tools-help/key-terms" ] @@ -143,10 +143,11 @@ { "source": "/environment-setup/eks-deployment-guide", "destination": "/environment-setup/eks-client-deployment-guide" }, { "source": "/environment-setup/architecture", "destination": "/environment-setup/configuration" }, { "source": "/environment-setup/setup_eks.sh", "destination": "/environment-setup/eks-client-deployment-guide" }, - { "source": "/join-use-case/tracebloc-package", "destination": "/tools-help/tracebloc-package" }, + { "source": "/join-use-case/tracebloc-package", "destination": "/tools-help/tracebloc" }, + { "source": "/tools-help/tracebloc-package", "destination": "/tools-help/tracebloc" }, { "source": "/join-use-case/model-optimisation.md", "destination": "/join-use-case/model-optimization" }, { "source": "/join-use-case/join-use-case/model-optimisation.md", "destination": "/join-use-case/model-optimization" }, - { "source": "/tracebloc-package/user-linkModelDataset", "destination": "/tools-help/tracebloc-package" }, + { "source": "/tracebloc-package/user-linkModelDataset", "destination": "/tools-help/tracebloc" }, { "source": "/experiment/details", "destination": "/join-use-case/explore-use-case" }, { "source": "/experiment/exp-guide", "destination": "/join-use-case/start-training" }, { "source": "/collaboration/collaboration-overview", "destination": "/join-use-case/overview" }, @@ -156,7 +157,7 @@ { "source": "/create-use-case/set-evaluation", "destination": "/create-use-case/evaluate-models" }, { "source": "/client-setup/setup-requirements", "destination": "/environment-setup/setup-guide" }, { "source": "/training-guide/jupyter-notebook", "destination": "/join-use-case/start-training" }, - { "source": "/model-requirements/api-supported", "destination": "/tools-help/tracebloc-package" }, + { "source": "/model-requirements/api-supported", "destination": "/tools-help/tracebloc" }, { "source": "/model-requirements/model-zoo", "destination": "/create-use-case/templates" }, { "source": "/FAQ/Collaboration", "destination": "/tools-help/faqs" }, { "source": "/FAQ/General", "destination": "/tools-help/faqs" }, @@ -172,7 +173,7 @@ { "source": "/tags/:slug*", "destination": "/overview/tracebloc" }, { "source": "/blog/authors", "destination": "https://tracebloc.io/blog" }, { "source": "/blog/archive", "destination": "https://tracebloc.io/blog" }, - { "source": "/tracebloc-package", "destination": "/tools-help/tracebloc-package" } + { "source": "/tracebloc-package", "destination": "/tools-help/tracebloc" } ], "seo": { "indexHiddenPages": false diff --git a/join-use-case/hyperparameters.mdx b/join-use-case/hyperparameters.mdx index c78284e..338511c 100644 --- a/join-use-case/hyperparameters.mdx +++ b/join-use-case/hyperparameters.mdx @@ -5,14 +5,14 @@ description: "Configure your model's training behavior by setting hyperparameter ## Training Parameters -All parameters are set through the `training` after linking your model with the dataset. +All parameters are set through the `training_plan` after linking your model with the dataset. ```python -training = user.link_model_dataset('Dataset ID') +training_plan = user.link_model_dataset(dataset_id='Dataset ID') ``` -To see all current parameter settings, run `training.get_training_plan()`. To run consecutive experiments, overwrite parameters and re-start training with `training.start()`. +To see all current parameter settings, run `training_plan.get_training_plan()`. To run consecutive experiments, overwrite parameters and re-start training with `training_plan.start()`. You can refer to the [TensorFlow Documentation](https://www.tensorflow.org/api_docs/python/tf/keras/preprocessing/image/ImageDataGenerator) for more information on TensorFlow augmentation parameters and the [PyTorch Documentation](https://albumentations.ai/docs/examples/pytorch-classification/) for more information on PyTorch augmentation parameters. @@ -23,10 +23,10 @@ Basic training configuration parameters that control the fundamental aspects of | Parameter | Description | Default | Example | |-----------|-------------|---------|---------| -| **Epochs** | Number of complete passes through the entire dataset | 10 | `training.epochs(100)` | -| **Cycles** | Number of complete passes through training and validation datasets | 1 | `training.cycles(10)` | +| **Epochs** | Number of complete passes through the entire dataset | 10 | `training_plan.epochs(100)` | +| **Cycles** | Number of complete passes through training and validation datasets | 1 | `training_plan.cycles(10)` | | **Batch Size** | Number of samples processed at one time. Set automatically from the `batch_size` variable in your model file | Datatype dependent

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

20% in most cases | `training.validation_split(0.2)` | +| **Validation Split** | Percentage of dataset used for validation (0-1) | Dataset dependent

20% in most cases | `training_plan.validation_split(0.2)` | ## Core Hyperparameters @@ -39,7 +39,7 @@ Controls how the model's parameters are updated during training. Supports differ - **PyTorch**: adam, rmsprop, sgd, adadelta, adagrad, adamax ```python -training.optimizer('rmsprop') +training_plan.optimizer('rmsprop') ``` ### 2. Learning Rate @@ -48,9 +48,9 @@ Controls the rate at which the model learns. Supports three different types: | Type | Description | Framework Support | Example | |------|-------------|-------------------|---------| -| **Constant** | Fixed learning rate throughout training | TensorFlow, PyTorch | `training.learning_rate({'type': 'constant', 'value': 0.002})` | -| **Adaptive** | Learning rate that changes based on schedule | TensorFlow | `training.learning_rate({'type': 'adaptive', 'value': {'decay_rate': 0.9, 'decay_steps': 100, 'initial_learning_rate': 0.1, 'scheduler': 'ExponentialDecay'}})` | -| **Custom** | User-defined learning rate function | TensorFlow | `training.learning_rate({'type': 'custom', 'value': {'name': custom_function, 'epoch': 5}})` | +| **Constant** | Fixed learning rate throughout training | TensorFlow, PyTorch | `training_plan.learning_rate({'type': 'constant', 'value': 0.002})` | +| **Adaptive** | Learning rate that changes based on schedule | TensorFlow | `training_plan.learning_rate({'type': 'adaptive', 'value': {'decay_rate': 0.9, 'decay_steps': 100, 'initial_learning_rate': 0.1, 'scheduler': 'ExponentialDecay'}})` | +| **Custom** | User-defined learning rate function | TensorFlow | `training_plan.learning_rate({'type': 'custom', 'value': {'name': custom_function, 'epoch': 5}})` | **Default:** `{'type': 'constant', 'value': 0.001}` @@ -61,7 +61,7 @@ Controls the rate at which the model learns. Supports three different types: return 0.01 else: return 0.01 * tf.math.exp(0.1 * (10 - epoch)) - training.learning_rate({'type': 'custom', 'value': {'name': custom_LearningRate_scheduler, 'epoch': 5}}) + training_plan.learning_rate({'type': 'custom', 'value': {'name': custom_LearningRate_scheduler, 'epoch': 5}}) ``` @@ -75,7 +75,7 @@ Defines how the model measures prediction errors. Supports standard and custom l ```python # Standard loss function -training.loss_function({'type': 'standard', 'value': 'categorical_crossentropy'}) +training_plan.loss_function({'type': 'standard', 'value': 'categorical_crossentropy'}) # Custom loss function (TensorFlow only) def custom_mse(y_true, y_pred): @@ -89,7 +89,7 @@ def custom_mse(y_true, y_pred): loss = K.sum(loss, axis=1) # (batch_size,) return loss -training.loss_function({'type': 'custom', 'value': custom_mse}) +training_plan.loss_function({'type': 'custom', 'value': custom_mse}) ``` **Default:** `{'type': 'standard', 'value': 'mse'}` @@ -100,7 +100,7 @@ training.loss_function({'type': 'custom', 'value': custom_mse}) Specify which layers should remain unchanged during training (TensorFlow only): ```python -training.layers_freeze(['conv1','fc1']) +training_plan.layers_freeze(['conv1','fc1']) ``` @@ -113,10 +113,10 @@ Control training behavior with various callbacks: | Callback | Purpose | Parameters | Example | |----------|---------|------------|---------| -| **Early Stopping** | Stop training when metric stops improving | metric, patience | `training.early_stop_callback('loss', 10)` | -| **Reduce LR** | Reduce learning rate when metric plateaus | metric, factor, patience, threshold | `training.reduce_lr_callback('loss', 0.1, 10, 0.0001)` | -| **Model Checkpoint** | Save model weights at specific intervals | metric, save_best_only | `training.model_checkpoint_callback('val_loss', True)` | -| **Terminate on NaN** | Stop training when a NaN loss is encountered | None | `training.terminate_on_nan_callback()` | +| **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,21 +129,21 @@ Enhance your dataset with real-time image transformations. All parameters suppor | 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.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.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.height_shift_range(0.1)` | -| **shear_range** | Shear intensity in degrees in counter-clockwise direction | 0.0 | TensorFlow | `training.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.zoom_range(0.1)`, `training.zoom_range([0.2, 0.8])` | -| **horizontal_flip** | Randomly flip images horizontally | False | TensorFlow | `training.horizontal_flip(True)` | -| **vertical_flip** | Randomly flip images vertically | False | TensorFlow | `training.vertical_flip(True)` | +| **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.brightness_range((0.1,0.4))` | -| **channel_shift_range** | Range for random channel shifts | 0 | TensorFlow, PyTorch* | `training.channel_shift_range(0.4)` | -| **rescale** | Rescaling factor for pixel values (float) | None | TensorFlow, PyTorch | `training.rescale(1.0/255.0)` | +| **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,16 +151,16 @@ Enhance your dataset with real-time image transformations. All parameters suppor | Parameter | Description | Default | Framework Support | Example | |-----------|-------------|---------|-------------------|---------| -| **samplewise_center** | Center each image by subtracting mean | False | TensorFlow | `training.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.samplewise_std_normalization(True)` | +| **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.fill_mode("nearest")` | -| **cval** | Fill value for points outside the image boundaries when fill_mode="constant" | 0.0 | TensorFlow, PyTorch | `training.cval(0.3)` | -| **shuffle** | Whether to shuffle the data | True | TensorFlow, PyTorch | `training.shuffle(True)` | +| **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) @@ -168,10 +168,10 @@ For text classification tasks in PyTorch, you can enable and configure LoRA (Low ```python # Enable LoRA first -training.enable_lora(True) +training_plan.enable_lora(True) # Configure LoRA parameters (positional arguments: lora_r, lora_alpha, lora_dropout, q_lora) -training.set_lora_parameters(256, 512, 0.05, False) +training_plan.set_lora_parameters(256, 512, 0.05, False) ``` | Parameter | Description | Type | Default | Example | @@ -191,9 +191,9 @@ Customize your dataset configuration and preprocessing options: | Parameter | Description | Example | |-----------|-------------|---------| -| **training_classes** | Customize dataset by specifying samples per class | `training.training_classes({'car': 30, 'person': 30})` | -| **data_type** | Image format: 'rgb' or 'grayscale' | `training.data_type('rgb')` | -| **seed** | Set global random seed | `training.seed(True)` | +| **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)` | --- diff --git a/join-use-case/model-optimization.mdx b/join-use-case/model-optimization.mdx index cd6604f..2f986c0 100644 --- a/join-use-case/model-optimization.mdx +++ b/join-use-case/model-optimization.mdx @@ -5,10 +5,10 @@ description: "Learn the model format requirements, mandatory variables per frame ## Use Pre-trained Weights -Upload weights along with your model in the `user.uploadModel()` step and set `weights=True`, the default value is False: +Upload weights along with your model in the `user.upload_model()` step and set `weights=True`, the default value is False: ```python -user.uploadModel("../../model-zoo/model_zoo///model.py", weights=True) +user.upload_model(model_name="../../model-zoo/model_zoo///model.py", weights=True) ``` A weights file with the same base name as the model and suffix "\_weights.pkl" must exist in the same directory. For example, if the model file is "mymodel.py", the corresponding weights file should be "mymodel_weights.pkl". diff --git a/join-use-case/start-training.mdx b/join-use-case/start-training.mdx index 6ea7471..63c22ac 100644 --- a/join-use-case/start-training.mdx +++ b/join-use-case/start-training.mdx @@ -38,10 +38,10 @@ Then, install requirements: python -m pip install --upgrade pip # Install with the extra that matches your framework: -pip install "tracebloc_package[pytorch]" -# pip install "tracebloc_package[tensorflow]" -# pip install "tracebloc_package[sklearn]" -# pip install "tracebloc_package[all]" # legacy behaviour — all frameworks +pip install "tracebloc[pytorch]>=0.8.1" +# pip install "tracebloc[tensorflow]>=0.8.1" +# pip install "tracebloc[sklearn]>=0.8.1" +# pip install "tracebloc[all]>=0.8.1" # legacy behaviour — all frameworks ``` ## Install and Launch Jupyter Notebook @@ -154,7 +154,7 @@ In case of multiple uploads, only the most recently uploaded model will be linke Upload the model to the use case workspace from your notebook: ```python -user.upload_model("../../model-zoo/model_zoo///model.py") +user.upload_model(model_name="../../model-zoo/model_zoo///model.py") ``` For details on model code formats, mandatory variables per framework, and pre-trained weights, see [Customize Models](/join-use-case/model-optimization). @@ -164,7 +164,7 @@ For details on model code formats, mandatory variables per framework, and pre-tr Navigate to the use case and copy the "Training Dataset ID" at the center of the use case pane and enter it to establish the link ```python -training = user.link_model_dataset('Dataset ID') +training_plan = user.link_model_dataset(dataset_id='Dataset ID') ``` You should get "Assignment successful!" and the dataset parameters. @@ -175,14 +175,14 @@ Set the experiment name and configure hyperparameters. ```python # Set experiment name -training.experiment_name("My Experiment") +training_plan.experiment_name("My Experiment") # Set training parameters -training.epochs(10) +training_plan.epochs(10) ... # Get training plan -training.get_training_plan() +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). @@ -191,10 +191,10 @@ For classical, non federated and non gradient descent-based machine learning alg ```python # Set training parameters -training.epochs(1) +training_plan.epochs(1) # Set federated learning cycles = 1 -training.cycles(1) +training_plan.cycles(1) ``` @@ -203,13 +203,13 @@ training.cycles(1) To send the model to the workspace infrastructure and start training on the training data, run: ```python -training.start() +training_plan.start() ``` Go to the [tracebloc website](https://ai.tracebloc.io/my-use-cases) and your use case, then navigate to the "Training/Finetuning" tab you will see your experiment. Monitor the training process hover over the learning curves to check the performance at specific epochs and cycles. -If you want to run a second experiment, overwrite parameters and re-start training with `training.start()`. +If you want to run a second experiment, overwrite parameters and re-start training with `training_plan.start()`. ### Pause, Re-Start and Stop: diff --git a/tools-help/faqs.mdx b/tools-help/faqs.mdx index a4164ef..de77be4 100644 --- a/tools-help/faqs.mdx +++ b/tools-help/faqs.mdx @@ -40,7 +40,7 @@ Through the [tracebloc dashboard](https://ai.tracebloc.io) — every experiment, 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-package) to upload a model file (PyTorch, TensorFlow, or a custom container). For ready-made starting points, see the [model zoo](https://github.com/tracebloc/model-zoo). +Yes. Use the [tracebloc Python package](/tools-help/tracebloc) to upload a model file (PyTorch, 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. @@ -60,4 +60,4 @@ See the [pricing page](https://tracebloc.io/#pricing) on the website. - [Get started](/environment-setup/setup-guide) — install the client - [Browse key terms](/tools-help/key-terms) -- [Use the Python SDK](/tools-help/tracebloc-package) +- [Use the Python SDK](/tools-help/tracebloc) diff --git a/tools-help/key-terms.mdx b/tools-help/key-terms.mdx index bccd573..1cf8766 100644 --- a/tools-help/key-terms.mdx +++ b/tools-help/key-terms.mdx @@ -45,4 +45,4 @@ The process of adjusting a pre-trained model for a specific task. ## Next Steps - [Check FAQs](/tools-help/faqs) -- [Review package documentation](/tools-help/tracebloc-package) +- [Review SDK documentation](/tools-help/tracebloc) diff --git a/tools-help/tracebloc-package.mdx b/tools-help/tracebloc.mdx similarity index 54% rename from tools-help/tracebloc-package.mdx rename to tools-help/tracebloc.mdx index 54195fc..c3874f5 100644 --- a/tools-help/tracebloc-package.mdx +++ b/tools-help/tracebloc.mdx @@ -1,14 +1,25 @@ --- -title: "tracebloc Package" +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." --- -The `tracebloc_package` is a 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. + + + 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. + ## Installation +Pick the extra that matches your ML framework — the default install ships the core SDK only (~140 MB, ~30 sec) instead of every framework (~8 GB): + ```bash -pip install tracebloc_package>=0.6.32 +pip install "tracebloc[pytorch]>=0.8.1" # most users +# pip install "tracebloc[tensorflow]>=0.8.1" # TensorFlow +# pip install "tracebloc[sklearn]>=0.8.1" # scikit-learn only +# pip install "tracebloc[boosting]>=0.8.1" # XGBoost / CatBoost / LightGBM +# pip install "tracebloc[survival]>=0.8.1" # lifelines / scikit-survival +# pip install "tracebloc[all]>=0.8.1" # everything ``` ## Key Features @@ -22,33 +33,33 @@ pip install tracebloc_package>=0.6.32 ## Quick Start ```python -from tracebloc_package import User +from tracebloc import User # 1. Log in to your tracebloc account user = User() # prompts for email and password # 2. Upload a model file (must be in your current directory or provide a path) -user.uploadModel("densenet.py") +user.upload_model(model_name="densenet.py") # To upload with pretrained weights (weights file must be in the same directory): -# user.uploadModel("densenet.py", weights=True) +# user.upload_model(model_name="densenet.py", weights=True) # 3. Link model with a dataset from your use case # Find the Dataset ID on your use case page at ai.tracebloc.io -trainingObject = user.linkModelDataset("YOUR_DATASET_ID") +training_plan = user.link_model_dataset(dataset_id="YOUR_DATASET_ID") # 4. Configure training parameters -trainingObject.experimentName("My first experiment") -trainingObject.epochs(10) -trainingObject.optimizer("adam") -trainingObject.learningRate({"type": "constant", "value": 0.001}) -trainingObject.validation_split(0.2) +training_plan.experiment_name("My first experiment") +training_plan.epochs(10) +training_plan.optimizer("adam") +training_plan.learning_rate({"type": "constant", "value": 0.001}) +training_plan.validation_split(0.2) # 5. Review your training plan -trainingObject.getTrainingPlan() +training_plan.get_training_plan() # 6. Start training -trainingObject.start() +training_plan.start() # 7. Log out when done user.logout() From aaaac321e6cc50950e0102a15fed38127db11801 Mon Sep 17 00:00:00 2001 From: Asad Iqbal Date: Wed, 13 May 2026 17:05:52 +0500 Subject: [PATCH 6/7] fix(ci): correct upstream refs in sync-sources.yml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three entries pointed at `main` branches that do not exist in the upstream repos, which would cause the sync fetch step to 404: - tracebloc-py-package → develop (default; `main` does not exist; per the SDK repo's CLAUDE.md, develop is the canonical source of truth) - data-ingestors → master (default branch) - model-zoo → master (default branch) Verified against the GitHub API for each repo. The `Readme.md` casing flagged by bugbot is correct as-is: data-ingestors actually ships `Readme.md` (mixed case), so the bugbot suggestion would have broken the fetch — left unchanged. Co-Authored-By: Claude Opus 4.7 --- .github/sync-sources.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/sync-sources.yml b/.github/sync-sources.yml index 21638b6..75779f2 100644 --- a/.github/sync-sources.yml +++ b/.github/sync-sources.yml @@ -16,7 +16,7 @@ sources: - id: tracebloc-package repo: tracebloc/tracebloc-py-package - ref: main + ref: develop src: README.md dest: tools-help/tracebloc.mdx private: true @@ -48,7 +48,7 @@ sources: - id: data-ingestors repo: tracebloc/data-ingestors - ref: main + ref: master src: Readme.md dest: create-use-case/prepare-dataset.mdx private: false @@ -59,7 +59,7 @@ sources: - id: model-zoo repo: tracebloc/model-zoo - ref: main + ref: master src: README.md dest: create-use-case/templates.mdx private: false From 4771d1f5be259d6f74167c312e0ba4b387b7f88c Mon Sep 17 00:00:00 2001 From: Asad Iqbal Date: Wed, 13 May 2026 17:19:44 +0500 Subject: [PATCH 7/7] fix(ci): pass source_id to yq via strenv() to avoid query injection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bugbot flagged the previous `yq ".sources[] | select(.id == \"$target\")"` pattern as shell-injectable. The specific RCE described doesn't actually trigger — `DISPATCH_ID` / `INPUT_ID` are routed through `env:` (Actions best practice) and bash does not re-tokenize variable values inside double quotes, so `$()`, backticks, and `;` in the value remain literal. However, a `"` in the value would still terminate the yq string literal at the yq parser level and could yield a malformed query or unintended filter. Routing the value through `strenv(TARGET)` keeps it entirely out of the yq expression syntax — defense in depth at zero cost. Co-Authored-By: Claude Opus 4.7 --- .github/workflows/sync-docs.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml index 037180e..6f5f431 100644 --- a/.github/workflows/sync-docs.yml +++ b/.github/workflows/sync-docs.yml @@ -66,7 +66,12 @@ jobs: target="${DISPATCH_ID:-${INPUT_ID:-}}" if [ -n "$target" ]; then echo "Filtering for source: $target" - yq -o=json ".sources[] | select(.id == \"$target\")" \ + # Pass `target` to yq via env + strenv() so the value never gets + # interpolated into the yq expression as a string literal. + # Untrusted client_payload / workflow_dispatch input can't break + # out of the query or inject yq syntax. + TARGET="$target" yq -o=json \ + '.sources[] | select(.id == strenv(TARGET))' \ /tmp/sync-sources.yml | jq -s . > /tmp/sources.json else echo "Processing all sources"