Skip to content

Update training guide and improve documentation for tracebloc#15

Closed
saadqbal wants to merge 12 commits into
mainfrom
develop
Closed

Update training guide and improve documentation for tracebloc#15
saadqbal wants to merge 12 commits into
mainfrom
develop

Conversation

@saadqbal

@saadqbal saadqbal commented May 15, 2026

Copy link
Copy Markdown
Collaborator

Note

Low Risk
Low risk: changes are limited to documentation assets and GitHub workflow automation; no application/runtime code paths are modified.

Overview
Adds a complete “start training” quickstart package: replaces the minimal README.md with a Colab-first setup guide and adds the main notebooks/traceblocTrainingGuide.ipynb plus a GenerateCheckWeights.ipynb utility for creating/verifying model weights.

Introduces repo hygiene and GitHub automation: adds Apache 2.0 LICENSE, a Python/Jupyter-focused .gitignore, CLAUDE.md contributor guidance, a PR template, and several GitHub Actions workflows for kanban/project routing, PR status/WIP checks, customer-priority bumps, and auto-closing stale backlog issues.

Reviewed by Cursor Bugbot for commit 73f775f. Bugbot is set up for automated code reviews on this repo. Configure here.

divyasinghds and others added 11 commits April 17, 2025 15:21
* Develop (#1)

* added files

* improvements

* improvements

* license updated

* license updated

* Update LICENSE

* Create requirements.txt

* Delete requirement.txt

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Delete requirements.txt

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update README.md

* Update README.md

* Update traceblocTrainingGuide.ipynb

* Update README.md

* Update README.md

* Update training notebook to match Colab quickstart

The GitHub notebook was outdated — minimal instructions, links to
GitLab (should be GitHub), no prerequisites, no troubleshooting,
no model zoo table, no expected outputs.

Updated to mirror the Colab notebook with:
- Prerequisites checklist with signup/join links
- Model zoo task table with all 9 task types and frameworks
- Option A (model zoo) / Option B (own model) structure
- Dataset ID instructions (where to find it)
- Available training commands table
- Expected outputs and troubleshooting for each step
- "What happens next" section (monitoring, leaderboard, compare)
- Links to docs, support, Discord

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Add auto-add to engineer kanban workflow

* fix(ci): pin actions/add-to-project to v1.0.2

@v1 is not a valid tag — action publishes full semver only. Pin to v1.0.2.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Divya <divyasingh@tracebloc.io>
Co-authored-by: Moritz Berthold <76496190+BerthoMo@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Asad Iqbal (Saadi) <asad.dsoft@gmail.com>
* chore: add PR template

* ci: add customer priority bump caller

* ci: add stale backlog auto-close

* ci: add set-pr-status caller workflow
* Develop (#1)

* added files

* improvements

* improvements

* license updated

* license updated

* Update LICENSE

* Create requirements.txt

* Delete requirement.txt

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Delete requirements.txt

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update README.md

* Update README.md

* Update traceblocTrainingGuide.ipynb

* Update README.md

* Update README.md

* Update training notebook to match Colab quickstart

The GitHub notebook was outdated — minimal instructions, links to
GitLab (should be GitHub), no prerequisites, no troubleshooting,
no model zoo table, no expected outputs.

Updated to mirror the Colab notebook with:
- Prerequisites checklist with signup/join links
- Model zoo task table with all 9 task types and frameworks
- Option A (model zoo) / Option B (own model) structure
- Dataset ID instructions (where to find it)
- Available training commands table
- Expected outputs and troubleshooting for each step
- "What happens next" section (monitoring, leaderboard, compare)
- Links to docs, support, Discord

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: switch install to extras syntax for tracebloc_package 0.6.33

Aligns with the optional-dependency-groups change shipping in
tracebloc-py-package 0.6.33. Default install no longer bundles every
ML framework — users pick the extra that matches their setup.

- README.md: 3-line extras table in the local-setup section.
- notebooks/traceblocTrainingGuide.ipynb cell 3: switch install cmd to
  [pytorch] as the most common setup; comment points at [tensorflow]
  and [all].

DO NOT MERGE until tracebloc_package 0.6.33 is live on real PyPI.
Currently 0.6.33 is only on TestPyPI.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: rename camelCase API calls in notebook + bump install pin to 0.7.0

Builds on top of the install-extras change (eeae340) and broadens scope
for the upcoming tracebloc_package 0.7.0 release.

Notebook changes (notebooks/traceblocTrainingGuide.ipynb):
- Cell 3 install pin: >=0.6.33 -> >=0.7.0
- Cell 11: user.uploadModel(MODEL_PATH) -> user.upload_model(MODEL_PATH)
- Cell 12 (markdown docs example): same uploadModel rename
- Cell 14: user.linkModelDataset(DATASET_ID) -> user.link_model_dataset(DATASET_ID)
- Cell 16 (reference table): experimentName, learningRate, getTrainingPlan,
  resetTrainingPlan -> experiment_name, learning_rate, get_training_plan,
  reset_training_plan
- Cell 17: experimentName + getTrainingPlan call sites updated

README.md: pip install lines bumped from >=0.6.33 to >=0.7.0 across all
three extras (pytorch, tensorflow, all).

Static rewrite only; the notebook was not executed (requires real
workspace credentials). All deprecated symbols touched here have
deprecation aliases on the Python side, so callers using the old names
would still work but emit DeprecationWarning.

Supersedes #4 (which was scoped only to the 0.6.33 install-extras
migration). The 0.6.33 release path is being collapsed into 0.7.0 now
that SDK.2/3 work has landed on develop, so this PR ships both changes
together.

Cannot merge until tracebloc_package 0.7.0 is published to real PyPI —
same merge-coordination block as #4.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add CLAUDE.md for Claude Code guidance (#3)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: migrate notebooks to tracebloc 0.8.x (closes #11)

The SDK was renamed in tracebloc/tracebloc-py-package#135. `tracebloc==0.8.1`
is live on PyPI. Notebooks and docs here still pointed at the old
`tracebloc_package` name.

- Install cells / commands: `tracebloc_package[X]>=0.7.0` -> `tracebloc[X]>=0.8.0`.
- Import cells: `from tracebloc_package import ...` -> `from tracebloc import ...`.
- README links the new PyPI page (`tracebloc`, not `tracebloc-package`).
- CLAUDE.md notes the historical name and the metadata-only redirect that
  keeps `pip install tracebloc_package` working for old notebooks.

Old name keeps working in 0.8.x via the compat shim (with
DeprecationWarning) and the redirect distribution on PyPI; this PR
moves the canonical examples to the new name.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: bump install pin to 0.8.1 (latest)

* chore: align develop with main and tidy up Python conventions

- Delete stale `requirement.txt` (matches main; install lives in README)
- Rename `trainingObject` → `training_object` in traceblocTrainingGuide.ipynb (PEP 8)
- Rewrite GenerateCheckWeights.ipynb against the 0.8.x SDK
  (`from tracebloc import ModelWeights` no longer exists). New version
  walks through generating + verifying a `<name>_weights.pkl` for both
  PyTorch and TensorFlow models, matching the format the SDK expects.

Closes #13

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* chore: rename training_object → training in training guide

Shorter, reads more naturally in the configuration calls
(`training.epochs(10)` vs `training_object.epochs(10)`).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: align dataset wording with actual UI labels

- "Training Dataset ID" → "Dataset" (the actual label in the use case
  panel; the value next to it is the ID)
- "use case page" → "use case panel" (matches the term used elsewhere
  in the notebook)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: add step 0 — save a copy to Drive (Colab)

Colab users who skip "Save a copy in Drive" lose their edits
(model path, dataset ID, training plan) on reload.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: inline Drive-save tip in Prerequisites, drop Step 0

Step 0 was redundant for local readers and broke the 1-5 numbered flow.
Folding the "Save a copy in Drive" reminder into the existing Colab
callout keeps the guidance where Colab users will see it (next to the
Colab link they're about to click) without adding a "Skip this" item
for everyone else.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: repoint Colab links to GitHub-backed URL

Previously the badge + body link + in-notebook link all pointed at a
Drive-hosted Colab copy (file id 1N00idtp...) that had to be manually
synced whenever the notebook changed — which is how it ended up stale.

Switch to the colab.research.google.com/github/... form, which loads
the canonical notebook from the repo on `main` directly. Future
updates to traceblocTrainingGuide.ipynb propagate without any manual
Drive step.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix: use .pth extension for PyTorch weights in GenerateCheckWeights

The setup cell hardcoded weights_path to '<name>_weights.pkl' for all
frameworks, but the notebook header documents the convention as '.pth'
for PyTorch — and torch.save() produces a zip archive that isn't a
generic pickle. Mixing the extension confuses users who hand the file
to anything other than torch.load().

Move weights_path into each framework-specific cell so the extension
matches the documented convention: '.pth' for the PyTorch save/verify
cells, '.pkl' for the TensorFlow ones.

Reported by Cursor Bugbot on PR #14.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Divya <divyasingh@tracebloc.io>
Co-authored-by: Moritz Berthold <76496190+BerthoMo@users.noreply.github.com>
Co-authored-by: lukasWuttke <54042461+LukasWodka@users.noreply.github.com>
Co-authored-by: Lukas Wuttke <lukas@tracebloc.io>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Arturo Peroni <arturo@tracebloc.io>
@saadqbal saadqbal self-assigned this May 15, 2026

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit b593ad3. Configure here.

Comment thread .gitignore
.env
.venv
env/
xrays/

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Project-specific path in standard gitignore template

Low Severity

The xrays/ entry is listed under the "# Environments" section alongside standard virtual-environment directories like .env, .venv, env/, and venv/. It appears to be a project-specific data directory (likely medical imaging data) that was accidentally mixed into an otherwise standard Python .gitignore template. This leaks internal project context into a public repository and doesn't belong with the environment entries.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit b593ad3. Configure here.

* Develop (#1)

* added files

* improvements

* improvements

* license updated

* license updated

* Update LICENSE

* Create requirements.txt

* Delete requirement.txt

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Delete requirements.txt

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update traceblocTrainingGuide.ipynb

* Update README.md

* Update README.md

* Update traceblocTrainingGuide.ipynb

* Update README.md

* Update README.md

* Update training notebook to match Colab quickstart

The GitHub notebook was outdated — minimal instructions, links to
GitLab (should be GitHub), no prerequisites, no troubleshooting,
no model zoo table, no expected outputs.

Updated to mirror the Colab notebook with:
- Prerequisites checklist with signup/join links
- Model zoo task table with all 9 task types and frameworks
- Option A (model zoo) / Option B (own model) structure
- Dataset ID instructions (where to find it)
- Available training commands table
- Expected outputs and troubleshooting for each step
- "What happens next" section (monitoring, leaderboard, compare)
- Links to docs, support, Discord

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: switch install to extras syntax for tracebloc_package 0.6.33

Aligns with the optional-dependency-groups change shipping in
tracebloc-py-package 0.6.33. Default install no longer bundles every
ML framework — users pick the extra that matches their setup.

- README.md: 3-line extras table in the local-setup section.
- notebooks/traceblocTrainingGuide.ipynb cell 3: switch install cmd to
  [pytorch] as the most common setup; comment points at [tensorflow]
  and [all].

DO NOT MERGE until tracebloc_package 0.6.33 is live on real PyPI.
Currently 0.6.33 is only on TestPyPI.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: rename camelCase API calls in notebook + bump install pin to 0.7.0

Builds on top of the install-extras change (eeae340) and broadens scope
for the upcoming tracebloc_package 0.7.0 release.

Notebook changes (notebooks/traceblocTrainingGuide.ipynb):
- Cell 3 install pin: >=0.6.33 -> >=0.7.0
- Cell 11: user.uploadModel(MODEL_PATH) -> user.upload_model(MODEL_PATH)
- Cell 12 (markdown docs example): same uploadModel rename
- Cell 14: user.linkModelDataset(DATASET_ID) -> user.link_model_dataset(DATASET_ID)
- Cell 16 (reference table): experimentName, learningRate, getTrainingPlan,
  resetTrainingPlan -> experiment_name, learning_rate, get_training_plan,
  reset_training_plan
- Cell 17: experimentName + getTrainingPlan call sites updated

README.md: pip install lines bumped from >=0.6.33 to >=0.7.0 across all
three extras (pytorch, tensorflow, all).

Static rewrite only; the notebook was not executed (requires real
workspace credentials). All deprecated symbols touched here have
deprecation aliases on the Python side, so callers using the old names
would still work but emit DeprecationWarning.

Supersedes #4 (which was scoped only to the 0.6.33 install-extras
migration). The 0.6.33 release path is being collapsed into 0.7.0 now
that SDK.2/3 work has landed on develop, so this PR ships both changes
together.

Cannot merge until tracebloc_package 0.7.0 is published to real PyPI —
same merge-coordination block as #4.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Add CLAUDE.md for Claude Code guidance (#3)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: migrate notebooks to tracebloc 0.8.x (closes #11)

The SDK was renamed in tracebloc/tracebloc-py-package#135. `tracebloc==0.8.1`
is live on PyPI. Notebooks and docs here still pointed at the old
`tracebloc_package` name.

- Install cells / commands: `tracebloc_package[X]>=0.7.0` -> `tracebloc[X]>=0.8.0`.
- Import cells: `from tracebloc_package import ...` -> `from tracebloc import ...`.
- README links the new PyPI page (`tracebloc`, not `tracebloc-package`).
- CLAUDE.md notes the historical name and the metadata-only redirect that
  keeps `pip install tracebloc_package` working for old notebooks.

Old name keeps working in 0.8.x via the compat shim (with
DeprecationWarning) and the redirect distribution on PyPI; this PR
moves the canonical examples to the new name.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: bump install pin to 0.8.1 (latest)

---------

Co-authored-by: Divya <divyasingh@tracebloc.io>
Co-authored-by: Moritz Berthold <76496190+BerthoMo@users.noreply.github.com>
Co-authored-by: lukasWuttke <54042461+LukasWodka@users.noreply.github.com>
Co-authored-by: Lukas Wuttke <lukas@tracebloc.io>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Arturo Peroni <arturo@tracebloc.io>
@saadqbal

Copy link
Copy Markdown
Collaborator Author

Closing in favor of the split PRs:

Both branch directly off main and are conflict-free. This PR's history was tangled with develop's stale merge-base, which is why it kept ending up DIRTY despite the merge-from-main commits. Cleaner to ship the two halves as small focused PRs.

@saadqbal saadqbal closed this May 19, 2026
LukasWodka pushed a commit that referenced this pull request May 19, 2026
…link (#18)

Splits the docs portion out of #15. The fix/pr-15-conflicts branch had
correctly resolved these against main; this is the clean cut against
main without the CI workflows or stale merge history.

- notebooks/GenerateCheckWeights.ipynb: rewrite for 0.8.x SDK. The
  previous version imported `from tracebloc import ModelWeights`,
  which no longer exists in 0.8.x — running it on main currently
  raises ImportError. New version uses importlib + torch.save/pickle
  directly, matching the file layout the SDK expects (.pth for
  PyTorch, .pkl for TensorFlow).
- README.md + notebooks/traceblocTrainingGuide.ipynb: repoint the
  Colab badge from the Drive-hosted copy
  (drive/1N00idtpoaq1lk9OJE6g4bMqd8o-Qex2C) to the GitHub-backed URL
  (colab.research.google.com/github/tracebloc/start-training/...).
  The Drive copy required manual sync on every notebook update and
  drifted; the GitHub form loads the canonical notebook from main
  directly.
- notebooks/traceblocTrainingGuide.ipynb: minor UX — training_object
  → training, "Dataset" wording aligned with the use-case panel
  label, Drive-save reminder inlined in Prerequisites, .pth/.pkl
  extension fix flagged by Cursor Bugbot on #14.

Closes #13.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
LukasWodka pushed a commit that referenced this pull request May 19, 2026
Splits the CI portion out of #15. These caller workflows live on
develop (added in #5, #6, #9, #10) but never reached main.

- pull_request_template.md
- workflows/add-to-kanban.yml — auto-add new issues/PRs to project 2
- workflows/customer-priority-bump.yml — bump priority on customer
  label
- workflows/kanban-closure-routing.yml — route closed work to the
  correct column
- workflows/set-pr-status.yml — set PR status on the board
- workflows/stale-backlog.yml — auto-close stale backlog issues
- workflows/wip-limit-check.yml — enforce per-column WIP limits

All delegate to the org-wide reusable workflows. No new logic in this
repo.

Closes #17.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants