tracebloc

Build AI with anyone. On data that can't move.

tracebloc is a collaborative AI workspace you deploy on your own infrastructure. Invite researchers, partners, vendors, or your own teams to train, fine-tune, and benchmark models on your private data — without the data ever leaving your environment.

Install

Pick the extra for your ML framework — the default install contains the core SDK only (~140 MB, ~30 sec) instead of every framework (~8 GB).

pip install "tracebloc[pytorch]"          # most users (incl. the HuggingFace stack)
pip install "tracebloc[sklearn]"          # scikit-learn only
pip install "tracebloc[xgboost]"          # or [catboost] / [lightgbm]
pip install "tracebloc[lifelines]"        # or [scikit-survival]
pip install "tracebloc[all]"              # everything

Requires Python 3.11–3.14. Google Colab and a current macOS python3 are both inside that range; if pip tells you "No matching distribution found for tracebloc", check python3 --version first — that is what an out-of-range interpreter looks like, not a missing package.

Upgrading from an earlier version? See MIGRATION.md.

Quick Start

from tracebloc import User

# 1. Log in to your workspace
user = User()
user.login()

# 2. Upload your model to a use case
user.upload_model(model_name="my_model")

# 3. Link your model to the dataset — returns a training-plan facade
training_plan = user.link_model_dataset(dataset_id="<your-dataset-id>")

# 4. Start training
training_plan.start()

For a full walkthrough, open the Quickstart Notebook on Google Colab.

Logging in from the environment

User() prompts for an email and a password. Where a prompt is not possible — a notebook that is already connected, a scheduled job, CI — set these instead and User() will not ask:

All three are optional and independent. Credentials you pass yourself always win: User(username=..., password=...) logs in with those, whatever is in the environment. TRACEBLOC_API_URL goes the other way — it is a deployment-level setting, so it applies whatever else you pass, and when it is active User() prints the host it is about to talk to.

When TRACEBLOC_API_URL points at a deployment the SDK recognises, the experiment link start() prints follows it automatically, and you do not need TRACEBLOC_APP_URL. Set that one when the API URL is something only your deployment knows — an in-cluster address, a tunnel, a preview environment. If neither names a frontend, start() prints the experiment id and no link at all, rather than a link into an environment your experiment is not in.

Any of them set to an empty value is an error rather than a silent fall-back to the prompt — in a job with no terminal, that prompt would never return. So is a token containing whitespace or a control character, which the server would reject anyway and which cannot be reported without quoting the credential back at you.

Supported Frameworks

How It Works

1. Deploy a tracebloc workspace on any machine or Kubernetes cluster
2. Define a use case — select datasets, set evaluation metrics
3. Invite anyone — researchers, partners, your own teams across locations
4. Build — contributors train models inside your environment using this SDK
5. Compare — every submission benchmarked under identical conditions on one leaderboard

Local development setup

To work on the tracebloc SDK and test changes with the quickstart Jupyter Notebook (also running locally), clone the quickstart repository and set up a virtual environment using Python 3.11–3.14.

Set up virtual environment:

python3.13 -m venv {venv_location}
source {venv_location}/bin/activate
pip install jupyter

Or with Pyenv:

pyenv virtualenv 3.13 quickstart
pyenv activate quickstart
pip install jupyter

Register the venv as a Jupyter kernel so the notebook uses it:

python -m ipykernel install --user --name=quickstart --display-name "quickstart"

Option 1: Editable install (recommended for iterating on source)

pip install -e {path_to}/tracebloc-py-package

Source changes are picked up immediately — no reinstall needed. Best for day-to-day development.

Option 2: Local install (non-editable)

pip install {path_to}/tracebloc-py-package

Installs a snapshot into site-packages. You must re-run this command after every change. Useful for verifying the package works when installed normally.

Option 3: Install from a built distribution

Build a wheel or sdist first, then install it:

cd {path_to}/tracebloc-py-package
python -m build
cd {path_to}/quickstart
pip install {path_to}/tracebloc-py-package/dist/tracebloc-*.whl

Use this to catch packaging issues (missing files, incorrect metadata, incomplete install_requires) before publishing to PyPI.

Switching between options

pip install on the same package name replaces the previous installation automatically. To remove the package entirely:

pip uninstall tracebloc -y

Running the notebook

jupyter notebook notebooks/traceblocTrainingGuide.ipynb

Select the "quickstart" kernel if it isn't already selected.

Note: skip the !pip install tracebloc[pytorch] cell in the notebook — the package is already installed locally via one of the options above.

Releasing

Maintainer-only. Skip this section unless you're cutting a new tracebloc release.

Releases are tag-driven: pushing a tag matching v*.*.* on develop triggers .github/workflows/publish-release.yml, which validates the build matrix, publishes to TestPyPI, verifies the install, then waits for a manual approval before publishing to PyPI.

End-to-end shape: validate matrix → TestPyPI → verify-from-TestPyPI → manual approval → PyPI (~20 min wall-clock with a hold at the approval gate).

Pre-flight (one-time per repo)

These are configured once and stay good. Sanity-check them before the first release on a new repo:

• GitHub secrets in repo settings:
  • TEST_PYPI_API_TOKEN — used by the publish-testpypi stage
  • PYPI_API_TOKEN — used by the publish-pypi stage
• GitHub environment production-pypi exists with required reviewers configured. The publish-pypi job uses this environment to force a manual approval gate before the PyPI upload.

Step 0 — Optional dry-run (first-ever tag pipeline run)

Tag a release candidate first to exercise the pipeline without publishing to production PyPI — deny the approval gate to stop just before the PyPI upload:

git checkout develop && git pull --ff-only
git tag v0.X.YrcN && git push origin v0.X.YrcN

Skip this step on subsequent releases once the pipeline is known good.

Step 1 — Tag the real release

git checkout develop
git pull --ff-only

# Confirm pyproject.toml version matches the tag you're about to push
# (the workflow's verify-tag-matches-version step fails otherwise).
grep "^version" pyproject.toml

git tag v0.X.Y
git push origin v0.X.Y

Step 2 — Watch the workflow

gh run watch
gh run list --workflow=publish-release.yml --limit 5

Stages:

1. validate — Py 3.11 + 3.14 (both ends of the supported range) x 8 extras cells, less scikit-survival on 3.14 (that extra source-builds ecos, which has no wheel past cp312, and a red cell here blocks the tag — see the exclude: comment in the workflow); ~10–15 min
2. publish-testpypi — builds + uploads to TestPyPI; ~2 min
3. verify-testpypi — installs from TestPyPI; ~2 min in the normal case. The index can lag behind the upload (it lagged 78s on v0.18.0 and skipped that release's production publish, backend#2444), so this stage polls instead of sleeping: scripts/pypi-await-install.sh retries up to 7 times over ~7 min of backoff, but only while pip says our exact version is not listed yet. A missing dependency, a broken wheel or a 403 fails on the first attempt.
4. publish-pypi — paused for approval

Step 3 — Approve the production publish

GitHub: Actions → workflow run → publish-pypi job → Review deployments → production-pypi → Approve.

Once approved, the PyPI upload runs (~1 min). Verify:

pip index versions tracebloc    # should show the new version

Step 4 — Same-day cross-repo coordination

Once the version is live on PyPI:

1. tracebloc/quickstart — bump the notebook pin if the release ships user-facing API changes; flip the coordination PR from draft → ready-for-review; merge.
2. tracebloc/docs (Mintlify) — install command + API example updates as a same-day PR.
3. tracebloc/tracebloc-website-main — homepage quickstart snippet PR if relevant.

Skip 2 and 3 for quiet patch releases with no doc-visible surface.

Step 5 — Post-release

1. Update CHANGELOG.md: change ## [0.X.Y] — Unreleased → ## [0.X.Y] — YYYY-MM-DD. One-line follow-up commit on develop.
2. Close any stale test-trigger PRs if still open.
3. Announce per team norms.

Links

• Documentation
• Quickstart Notebook
• Website
• GitHub

License

MIT

Pre-commit

Optional but recommended: pip install pre-commit && pre-commit install sets up the git hooks from .pre-commit-config.yaml. The hooks run automatically on each commit, only on the files you touch. They are a fast local guard — CI remains the guarantee.