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..75779f2 --- /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: develop + src: README.md + dest: tools-help/tracebloc.mdx + private: true + instruction: | + Sync the Installation, Key Features, and Quick Start sections to reflect + the upstream README. Preserve the page frontmatter and any prose that is + unique to the docs page (e.g. links to other Mintlify pages). + + - id: client-setup + repo: tracebloc/client + ref: main + src: README.md + dest: environment-setup/setup-guide.mdx + private: false + instruction: | + Sync installer steps, requirements, supported platforms, and verification + commands. Preserve the page's narrative framing (numbered top-level steps, + requirements table) and any prose unique to the docs page. + + - id: start-training + repo: tracebloc/start-training + ref: main + src: README.md + dest: join-use-case/start-training.mdx + private: false + instruction: | + Sync notebook setup and the steps for launching experiments to match the + upstream README. Preserve cross-links to other Join-a-Use-Case pages. + + - id: data-ingestors + repo: tracebloc/data-ingestors + ref: master + src: Readme.md + dest: create-use-case/prepare-dataset.mdx + private: false + instruction: | + Sync dataset preparation pipeline steps, supported formats, and ingestor + configuration from the upstream README. Preserve the page frontmatter and + any examples specific to the docs page. + + - id: model-zoo + repo: tracebloc/model-zoo + ref: master + src: README.md + dest: create-use-case/templates.mdx + private: false + instruction: | + Sync the list of available model templates and their descriptions from the + upstream README. Preserve the page frontmatter and any prose specific to + the docs page. diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml new file mode 100644 index 0000000..6f5f431 --- /dev/null +++ b/.github/workflows/sync-docs.yml @@ -0,0 +1,154 @@ +name: Sync docs from upstream + +# Triggers: +# - repository_dispatch: fired by source repos when a watched file changes (push-driven) +# - workflow_dispatch: manual run from the Actions tab (optional source_id input) +# - schedule: daily safety-net in case a dispatch is missed +on: + repository_dispatch: + types: [upstream-changed] + workflow_dispatch: + inputs: + source_id: + description: "Specific source id from sync-sources.yml (leave empty for all)" + required: false + type: string + schedule: + - cron: "0 6 * * *" + +permissions: + contents: write + pull-requests: write + +concurrency: + group: sync-docs + cancel-in-progress: false + +jobs: + sync: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Resolve PR base and accumulate onto existing sync branch + id: setup + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + base=$(gh repo view --json defaultBranchRef -q .defaultBranchRef.name) + echo "base=$base" >> "$GITHUB_OUTPUT" + # Snapshot the mapping from the base branch BEFORE possibly switching + # to the sync branch, so we never use a stale config from a pending + # PR (e.g. if a new source was added on main after the PR opened). + cp .github/sync-sources.yml /tmp/sync-sources.yml + if git ls-remote --exit-code --heads origin docs/sync-upstream >/dev/null 2>&1; then + echo "Existing docs/sync-upstream branch found — checking it out so this run accumulates onto pending changes." + git fetch origin docs/sync-upstream:docs/sync-upstream + git checkout docs/sync-upstream + else + echo "No existing sync branch — starting from $base." + fi + + - name: Install yq + run: | + sudo wget -qO /usr/local/bin/yq \ + https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 + sudo chmod +x /usr/local/bin/yq + + - name: Resolve target sources + id: filter + env: + DISPATCH_ID: ${{ github.event.client_payload.source_id }} + INPUT_ID: ${{ inputs.source_id }} + run: | + target="${DISPATCH_ID:-${INPUT_ID:-}}" + if [ -n "$target" ]; then + echo "Filtering for source: $target" + # Pass `target` to yq via env + strenv() so the value never gets + # interpolated into the yq expression as a string literal. + # Untrusted client_payload / workflow_dispatch input can't break + # out of the query or inject yq syntax. + TARGET="$target" yq -o=json \ + '.sources[] | select(.id == strenv(TARGET))' \ + /tmp/sync-sources.yml | jq -s . > /tmp/sources.json + else + echo "Processing all sources" + yq -o=json '.sources' /tmp/sync-sources.yml > /tmp/sources.json + fi + count=$(jq length /tmp/sources.json) + echo "count=$count" >> "$GITHUB_OUTPUT" + echo "Found $count source(s) to process" + if [ "$count" = "0" ]; then + echo "Nothing to do." + fi + + - name: Fetch upstream files + if: steps.filter.outputs.count != '0' + env: + GH_TOKEN: ${{ secrets.SOURCE_REPOS_TOKEN || secrets.GITHUB_TOKEN }} + run: | + mkdir -p /tmp/sync-cache + jq -c '.[]' /tmp/sources.json | while read -r s; do + id=$(jq -r .id <<<"$s") + repo=$(jq -r .repo <<<"$s") + ref=$(jq -r .ref <<<"$s") + src=$(jq -r .src <<<"$s") + echo "Fetching $repo@$ref:$src -> /tmp/sync-cache/$id" + gh api "repos/$repo/contents/$src?ref=$ref" \ + -H "Accept: application/vnd.github.raw" \ + > "/tmp/sync-cache/$id" + done + ls -la /tmp/sync-cache + + - name: Run Claude to update docs + if: steps.filter.outputs.count != '0' + uses: anthropics/claude-code-action@v1 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + prompt: | + You are syncing this Mintlify docs site with upstream README changes. + + The mapping is at `/tmp/sync-sources.yml` (snapshotted from the + base branch at the start of this run, so it is always current). + The list of sources to process this run is at `/tmp/sources.json`. + For each source, the latest upstream file content is at + `/tmp/sync-cache/`. + + 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 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 . ``` 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/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. diff --git a/join-use-case/hyperparameters.mdx b/join-use-case/hyperparameters.mdx index 0a8c3ba..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 `trainingObject` after linking your model with the dataset. +All parameters are set through the `training_plan` after linking your model with the dataset. ```python -trainingObject = user.linkModelDataset('Dataset ID') +training_plan = user.link_model_dataset(dataset_id='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_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 | `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_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 | `trainingObject.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 -trainingObject.optimizer('rmsprop') +training_plan.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_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}` -* **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_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 -trainingObject.lossFunction({'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 -trainingObject.lossFunction({'type': 'custom', 'value': custom_mse}) +training_plan.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_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 | `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_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 | `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_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 | `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_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 | `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_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 | `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_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 -trainingObject.enable_lora(True) +training_plan.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_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 | |-----------|-------------|---------| -| **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_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 7183db7..63c22ac 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[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 @@ -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_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). @@ -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_plan = user.link_model_dataset(dataset_id='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_plan.experiment_name("My Experiment") # Set training parameters -trainingObject.epochs(10) +training_plan.epochs(10) ... # Get training plan -trainingObject.getTrainingPlan() +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). @@ -186,10 +191,10 @@ For classical, non federated and non gradient descent-based machine learning alg ```python # Set training parameters -trainingObject.epochs(1) +training_plan.epochs(1) # Set federated learning cycles = 1 -trainingObject.cycles(1) +training_plan.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_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 `trainingObject.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()