diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..cea0c18 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,28 @@ +## Summary + + +## Related + + +## Type of change +- [ ] Feature +- [ ] Bug fix +- [ ] Tech-debt / refactor +- [ ] Docs +- [ ] Security / hardening +- [ ] Breaking change + +## Test plan + + +## Screenshots / recordings + + +## Deployment notes + + +## Checklist +- [ ] Tests added / updated and passing locally +- [ ] Docs updated if behavior or config changed +- [ ] No secrets / credentials in the diff +- [ ] For security-sensitive paths: appropriate reviewer requested diff --git a/.github/workflows/add-to-kanban.yml b/.github/workflows/add-to-kanban.yml new file mode 100644 index 0000000..45aa70a --- /dev/null +++ b/.github/workflows/add-to-kanban.yml @@ -0,0 +1,16 @@ +name: Add to engineer kanban + +on: + issues: + types: [opened, reopened, transferred] + pull_request: + types: [opened, reopened, ready_for_review] + +jobs: + add-to-project: + runs-on: ubuntu-latest + steps: + - uses: actions/add-to-project@v1.0.2 + with: + project-url: https://github.com/orgs/tracebloc/projects/2 + github-token: ${{ secrets.PROJECTS_KANBAN_TOKEN }} diff --git a/.github/workflows/customer-priority-bump.yml b/.github/workflows/customer-priority-bump.yml new file mode 100644 index 0000000..ea4e9ea --- /dev/null +++ b/.github/workflows/customer-priority-bump.yml @@ -0,0 +1,10 @@ +name: Customer priority bump + +on: + issues: + types: [labeled] + +jobs: + bump: + uses: tracebloc/.github/.github/workflows/customer-priority-bump.yml@main + secrets: inherit diff --git a/.github/workflows/kanban-closure-routing.yml b/.github/workflows/kanban-closure-routing.yml new file mode 100644 index 0000000..0b54df5 --- /dev/null +++ b/.github/workflows/kanban-closure-routing.yml @@ -0,0 +1,12 @@ +name: Kanban closure routing + +on: + pull_request: + types: [closed] + issues: + types: [closed] + +jobs: + route: + uses: tracebloc/.github/.github/workflows/kanban-closure-router.yml@main + secrets: inherit diff --git a/.github/workflows/set-pr-status.yml b/.github/workflows/set-pr-status.yml new file mode 100644 index 0000000..e19a67e --- /dev/null +++ b/.github/workflows/set-pr-status.yml @@ -0,0 +1,10 @@ +name: Set PR Status + +on: + pull_request: + types: [opened, reopened, ready_for_review, converted_to_draft] + +jobs: + set-status: + uses: tracebloc/.github/.github/workflows/set-pr-status.yml@main + secrets: inherit diff --git a/.github/workflows/stale-backlog.yml b/.github/workflows/stale-backlog.yml new file mode 100644 index 0000000..318e372 --- /dev/null +++ b/.github/workflows/stale-backlog.yml @@ -0,0 +1,33 @@ +name: Close stale backlog issues + +on: + schedule: + - cron: '0 0 * * 1' # Mondays 00:00 UTC + workflow_dispatch: {} + +permissions: + issues: write + pull-requests: write + +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v9 + with: + days-before-issue-stale: 42 # 6 weeks of no activity โ†’ warning + days-before-issue-close: 14 # +2 weeks of silence โ†’ close + stale-issue-label: 'stale' + stale-issue-message: | + ๐Ÿ‘‹ This issue has had no activity for 6 weeks. + + If it's still relevant, please leave a comment with current context (or assign someone). Otherwise it will auto-close in 2 weeks. + + To exempt permanently, add the `keep-open` label. + close-issue-message: | + Closing due to 8+ weeks of inactivity. Please reopen with current context if relevant. + exempt-issue-labels: 'keep-open,blocked' + # PRs: don't auto-stale โ€” branch protection + active reviews govern those + days-before-pr-stale: -1 + days-before-pr-close: -1 + operations-per-run: 50 diff --git a/.github/workflows/wip-limit-check.yml b/.github/workflows/wip-limit-check.yml new file mode 100644 index 0000000..8c027df --- /dev/null +++ b/.github/workflows/wip-limit-check.yml @@ -0,0 +1,10 @@ +name: WIP limit check + +on: + pull_request: + types: [opened, ready_for_review] + +jobs: + check: + uses: tracebloc/.github/.github/workflows/wip-limit-check.yml@main + secrets: inherit diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..34af4a1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,146 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +xrays/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# ds store +.DS_Store/* + +.idea +.DS_Store + diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..05b4cc2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,35 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repo does + +Jupyter notebook quick-start guide for running ML training experiments on the tracebloc platform. Walks users through connecting their account, uploading a model, linking a dataset, configuring training parameters, and starting an experiment. + +## Notebook locations + +- `notebooks/traceblocTrainingGuide.ipynb` -- main training guide (also available on [Google Colab](https://colab.research.google.com/drive/1N00idtpoaq1lk9OJE6g4bMqd8o-Qex2C?usp=sharing)) +- `notebooks/GenerateCheckWeights.ipynb` -- utility for generating/checking model weights + +## How users run it + +### Google Colab (recommended) +Open the Colab link, copy to Drive, and run cells. + +### Locally +```bash +pip install "tracebloc[pytorch]>=0.8.1" +jupyter notebook notebooks/traceblocTrainingGuide.ipynb +``` + +## Prerequisites + +- A tracebloc account +- An active use case with a dataset +- A model file (from the [model-zoo](https://github.com/tracebloc/model-zoo) repo or custom) + +## Key dependency + +[`tracebloc`](https://pypi.org/project/tracebloc/) (PyPI, 0.8.x+) -- the Python SDK used in the notebook to authenticate, upload models, and start training. + +> Was published as `tracebloc_package` before 0.8.0. The old install command (`pip install tracebloc_package`) still resolves via a metadata-only redirect on PyPI, but new notebooks should use the canonical `tracebloc` name. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d5f76c2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2025 tracebloc + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 6ba9392..6e9eb7d 100644 --- a/README.md +++ b/README.md @@ -1 +1,57 @@ -# start-training \ No newline at end of file +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/tracebloc/start-training/blob/main/notebooks/traceblocTrainingGuide.ipynb) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE) [![Platform](https://img.shields.io/badge/platform-tracebloc-00C9A7.svg)](https://ai.tracebloc.io) + +# Start Training ๐Ÿš€ + +Launch an ML training experiment on [tracebloc](https://tracebloc.io/) in under 10 minutes. Connect your account, upload a model, link it to a dataset, configure training parameters, and start benchmarking โ€” all from a single notebook. + +## Get started + +### Option A: Google Colab (recommended) + +No local setup. Click the badge above or: + +**๐Ÿ‘‰ [Open in Google Colab](https://colab.research.google.com/github/tracebloc/start-training/blob/main/notebooks/traceblocTrainingGuide.ipynb)** + +Copy the notebook to your Drive and start running cells. + +### Option B: Run locally + +```bash +git clone https://github.com/tracebloc/start-training.git +cd start-training + +# Pick the extra that matches your ML framework: +pip install "tracebloc[pytorch]>=0.8.1" # most common +# pip install "tracebloc[tensorflow]>=0.8.1" # TensorFlow +# pip install "tracebloc[all]>=0.8.1" # everything + +jupyter notebook notebooks/traceblocTrainingGuide.ipynb +``` + +## What the notebook covers + +| Step | What you do | +|:---:|---| +| **1** | Connect to tracebloc with your email + password | +| **2** | Upload a model from the [model zoo](https://github.com/tracebloc/model-zoo) or your own | +| **3** | Link it to a dataset from your use case | +| **4** | Configure training โ€” epochs, batch size, learning rate, augmentation | +| **5** | Start training โ€” model runs inside your secure Kubernetes environment | + +Results appear on the use case leaderboard in the [tracebloc web app](https://ai.tracebloc.io/). + +## Before you start + +- A **tracebloc account** โ€” [sign up free](https://ai.tracebloc.io/signup) +- An **active use case** with a dataset โ€” [how to join one](https://docs.tracebloc.io/join-use-case/) +- A **model file** โ€” grab one from the [model zoo](https://github.com/tracebloc/model-zoo) or [build your own](https://docs.tracebloc.io/join-use-case/model-optimization) + +## Links + +[Platform](https://ai.tracebloc.io/) ยท [Docs](https://docs.tracebloc.io/) ยท [Model zoo](https://github.com/tracebloc/model-zoo) ยท [PyPI package](https://pypi.org/project/tracebloc/) ยท [Discord](https://discord.gg/tracebloc) + +## License + +Apache 2.0 โ€” see [LICENSE](LICENSE). + +**Need help?** [support@tracebloc.io](mailto:support@tracebloc.io) or [open an issue](https://github.com/tracebloc/start-training/issues). diff --git a/notebooks/GenerateCheckWeights.ipynb b/notebooks/GenerateCheckWeights.ipynb new file mode 100644 index 0000000..0f079bc --- /dev/null +++ b/notebooks/GenerateCheckWeights.ipynb @@ -0,0 +1,165 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0e68ce9a", + "metadata": {}, + "source": [ + "# Generate & Verify Model Weights\n", + "\n", + "A small utility for producing a starting-weights file that pairs with a tracebloc model file.\n", + "\n", + "Use this when:\n", + "- You wrote a custom model and need a `_weights.pkl` to upload alongside it\n", + "- You want to confirm a weights file loads correctly before running `user.upload_model(..., weights=True)`\n", + "\n", + "**Convention:** tracebloc expects a model file `mymodel.py` defining a function `MyModel()`, and a companion weights file named `mymodel_weights.pkl` (or `.pth` for PyTorch) in the same directory.\n", + "\n", + "\ud83d\udcd6 [Model structure requirements](https://docs.tracebloc.io/join-use-case/model-optimization)" + ] + }, + { + "cell_type": "markdown", + "id": "db0877bc", + "metadata": {}, + "source": [ + "## 1. Point at your model file\n", + "\n", + "Set the path to the `.py` file that defines `MyModel()`. The weights file will be written next to it." + ] + }, + { + "cell_type": "code", + "id": "732903bb", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": "import importlib.util\nimport os\n\nMODEL_PATH = \"mymodel.py\" # <-- change to your model file\n\nmodel_dir = os.path.dirname(os.path.abspath(MODEL_PATH)) or \".\"\nmodel_name = os.path.splitext(os.path.basename(MODEL_PATH))[0]\n\nspec = importlib.util.spec_from_file_location(model_name, MODEL_PATH)\nmodule = importlib.util.module_from_spec(spec)\nspec.loader.exec_module(module)" + }, + { + "cell_type": "markdown", + "id": "d7e0f3ca", + "metadata": {}, + "source": [ + "## 2. Generate weights\n", + "\n", + "Pick the cell that matches your framework. Each one builds the model via `MyModel()` and writes a weights file using the format tracebloc expects." + ] + }, + { + "cell_type": "markdown", + "id": "c55d3110", + "metadata": {}, + "source": [ + "### PyTorch\n", + "\n", + "Saves the model's `state_dict` with `torch.save` \u2014 tracebloc loads it back via `model.load_state_dict(torch.load(...))`." + ] + }, + { + "cell_type": "code", + "id": "0356466d", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": "import torch\n\nweights_path = os.path.join(model_dir, f\"{model_name}_weights.pth\")\n\nmodel = module.MyModel()\ntorch.save(model.state_dict(), weights_path)\nprint(f\"Wrote {weights_path}\")" + }, + { + "cell_type": "markdown", + "id": "25068e30", + "metadata": {}, + "source": [ + "### TensorFlow / Keras\n", + "\n", + "Saves the weights as a pickled list of arrays \u2014 tracebloc loads it back via `model.set_weights(pickle.load(...))`." + ] + }, + { + "cell_type": "code", + "id": "0c902690", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": "import pickle\n\nweights_path = os.path.join(model_dir, f\"{model_name}_weights.pkl\")\n\nmodel = module.MyModel()\nwith open(weights_path, \"wb\") as f:\n pickle.dump(model.get_weights(), f)\nprint(f\"Wrote {weights_path}\")" + }, + { + "cell_type": "markdown", + "id": "fcdd9389", + "metadata": {}, + "source": [ + "## 3. Verify the weights file\n", + "\n", + "Reload the weights into a fresh model instance to confirm shapes match and the file is readable. Run the cell that matches your framework." + ] + }, + { + "cell_type": "markdown", + "id": "62c3b96f", + "metadata": {}, + "source": [ + "### PyTorch" + ] + }, + { + "cell_type": "code", + "id": "2a98f6ae", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": "import torch\n\nweights_path = os.path.join(model_dir, f\"{model_name}_weights.pth\")\n\nverify_model = module.MyModel()\nverify_model.load_state_dict(torch.load(weights_path))\nprint(f\"Loaded weights into {type(verify_model).__name__}\")\nprint(f\" parameters: {sum(p.numel() for p in verify_model.parameters()):,}\")" + }, + { + "cell_type": "markdown", + "id": "860d0ad5", + "metadata": {}, + "source": [ + "### TensorFlow / Keras" + ] + }, + { + "cell_type": "code", + "id": "bb9a78ae", + "metadata": {}, + "execution_count": null, + "outputs": [], + "source": "import pickle\n\nweights_path = os.path.join(model_dir, f\"{model_name}_weights.pkl\")\n\nverify_model = module.MyModel()\nwith open(weights_path, \"rb\") as f:\n verify_model.set_weights(pickle.load(f))\nverify_model.summary()" + }, + { + "cell_type": "markdown", + "id": "8ac220ec", + "metadata": {}, + "source": [ + "## 4. Upload with your model\n", + "\n", + "Once the weights file is in place, upload both together from the main training notebook:\n", + "\n", + "```python\n", + "user.upload_model(MODEL_PATH, weights=True)\n", + "```\n", + "\n", + "The SDK will look for `_weights.pkl` (or `.pth`) next to your `.py` file." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} \ No newline at end of file diff --git a/notebooks/traceblocTrainingGuide.ipynb b/notebooks/traceblocTrainingGuide.ipynb new file mode 100644 index 0000000..d9a9ecc --- /dev/null +++ b/notebooks/traceblocTrainingGuide.ipynb @@ -0,0 +1,314 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Guide to Train Machine Learning Models on tracebloc \ud83d\ude80\n", + "\n", + "This notebook walks you through training an ML model on the tracebloc platform \u2014 from connecting your account to launching a training run.\n", + "\n", + "**What you'll do:**\n", + "1. Connect to your tracebloc account\n", + "2. Upload a model & weights\n", + "3. Link the model with a dataset\n", + "4. Configure a training plan\n", + "5. Start training\n", + "\n", + "This guide takes about **10\u201315 minutes** to complete." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": "## Prerequisites\n\nBefore you begin, make sure you have:\n\n- \u2705 A **tracebloc account** \u2014 [Sign up here](https://ai.tracebloc.io/signup) if you don't have one\n- \u2705 **Joined a use case** \u2014 you need an active use case with a dataset. [How to join a use case \u2192](https://docs.tracebloc.io/join-use-case/explore-use-case)\n- \u2705 A **model file** (`.py`) compatible with the dataset \u2014 you can use one from the [tracebloc model zoo](https://github.com/tracebloc/model-zoo) or bring your own. [Model structure requirements \u2192](https://docs.tracebloc.io/join-use-case/model-optimization)\n\n\ud83d\udcd6 **Full documentation:** [docs.tracebloc.io](https://docs.tracebloc.io)\n\n\ud83d\udca1 **Prefer Google Colab?** [Open this guide in Colab](https://colab.research.google.com/github/tracebloc/start-training/blob/main/notebooks/traceblocTrainingGuide.ipynb) \u2014 runs entirely in your browser, no local setup needed. Once it opens, do **File \u2192 Save a copy in Drive** so your edits persist." + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## 1. Connect to tracebloc\n", + "\n", + "First, install the tracebloc package and log in with your tracebloc account email and password." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": "# Install the tracebloc package \u2014 the [pytorch] extra covers the most common setup.\n# Using TensorFlow? Replace [pytorch] with [tensorflow]. See the README for all extras.\n!pip install \"tracebloc[pytorch]>=0.8.1\" -q" + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "from tracebloc import User\n", + "\n", + "# This will prompt you for your tracebloc email and password\n", + "user = User()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "**Expected output:** You'll see a prompt asking for your email and password. After entering them, you should see a confirmation that you're logged in.\n", + "\n", + "\u26a0\ufe0f **If login fails:**\n", + "- Double-check your email and password at [ai.tracebloc.io](https://ai.tracebloc.io)\n", + "- Make sure you've verified your email address\n", + "- If you don't have an account yet, [sign up here](https://ai.tracebloc.io/signup)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## 2. Upload model & weights file\n", + "\n", + "Next, upload your model file to the platform. You have two options:" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Option A: Use a model from the tracebloc model zoo\n", + "\n", + "The [tracebloc model zoo](https://github.com/tracebloc/model-zoo) has ready-to-use models for common tasks:\n", + "\n", + "| Task | Framework | Path |\n", + "|------|-----------|------|\n", + "| Image classification | PyTorch / TensorFlow | `model_zoo/image_classification/` |\n", + "| Object detection | PyTorch | `model_zoo/object_detection/pytorch/` |\n", + "| Text classification | PyTorch | `model_zoo/text_classification/pytorch/` |\n", + "| Tabular classification | PyTorch / Sklearn | `model_zoo/tabular_classification/` |\n", + "| Tabular regression | PyTorch / Sklearn | `model_zoo/tabular_regression/` |\n", + "| Time series forecasting | PyTorch | `model_zoo/time_series_forecasting/pytorch/` |\n", + "| Semantic segmentation | PyTorch | `model_zoo/semantic_segmentation/pytorch/` |\n", + "| Keypoint detection | PyTorch | `model_zoo/keypoint_detection/pytorch/` |\n", + "| Time-to-event prediction | PyTorch / Lifelines / Scikit-survival | `model_zoo/time_to_event_prediction/` |\n", + "\n", + "Clone the model zoo and pick a model that fits your use case:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Clone the tracebloc model zoo (skip if you already have it)\n", + "!git clone https://github.com/tracebloc/model-zoo.git ../model-zoo 2>/dev/null || echo \"model-zoo already cloned\"" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# List available models\n", + "!ls ../model-zoo/model_zoo/" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Option B: Use your own model\n", + "\n", + "You can upload your own model file. Place your `.py` file in the working directory or provide the full path.\n", + "\n", + "Make sure your model follows the [model structure requirements](https://docs.tracebloc.io/join-use-case/model-optimization)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Upload your model file to tracebloc\n", + "# Replace the path with your actual model file location\n", + "MODEL_PATH = \"../model-zoo/model_zoo/image_classification/pytorch/densenet.py\" # <-- change this\n", + "\n", + "user.upload_model(MODEL_PATH)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "**Expected output:** A confirmation message showing the model was uploaded successfully.\n", + "\n", + "\ud83d\udca1 **Loading weights?** Follow this naming convention:\n", + "- Model file: `mymodel.py`\n", + "- Weights file: `mymodel_weights.pkl`\n", + "\n", + "The weights file must be in the same directory as the model file.\n", + "\n", + "```python\n", + "# To upload with pretrained weights:\n", + "user.upload_model(MODEL_PATH, weights=True)\n", + "```" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": "---\n## 3. Link uploaded model with dataset\n\nNow connect your uploaded model to a dataset from your use case.\n\n**Where to find the Dataset ID:**\n1. Go to [ai.tracebloc.io](https://ai.tracebloc.io) and open your use case\n2. Copy the ID shown next to **Dataset** in the use case panel\n3. Paste it below\n\nThe dataset ID is a short alphanumeric string (e.g., `DKbtefZy`)." + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": "# Paste your Dataset ID here\nDATASET_ID = \"YOUR_DATASET_ID_HERE\" # <-- replace with your actual dataset ID (e.g., \"DKbtefZy\")\n\ntraining = user.link_model_dataset(DATASET_ID)" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": "**Expected output:** A confirmation that the model and dataset are linked.\n\n\u26a0\ufe0f **If this fails:**\n- Make sure the dataset ID is correct (check your use case panel)\n- Your model must be compatible with the dataset (e.g., an image classification model for an image dataset)" + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## 4. Set training plan\n", + "\n", + "Configure your training parameters. Start by naming your experiment, then adjust any parameters you need.\n", + "\n", + "| Command | Description | Example |\n", + "|---------|-------------|--------|\n", + "| `training.experiment_name(\"...\")` | Name your experiment | `training.experiment_name(\"My first run\")` |\n", + "| `training.epochs(n)` | Number of training epochs | `training.epochs(10)` |\n", + "| `training.optimizer(\"...\")` | Set optimizer | `training.optimizer(\"adam\")` |\n", + "| `training.learning_rate({...})` | Set learning rate | `training.learning_rate({\"type\": \"constant\", \"value\": 0.001})` |\n", + "| `training.validation_split(n)` | Validation split | `training.validation_split(0.2)` |\n", + "| `training.get_training_plan()` | View the full training plan | |\n", + "| `training.reset_training_plan()` | Reset to defaults | |\n", + "\n", + "For all available parameters, see the [Hyperparameters reference](https://docs.tracebloc.io/join-use-case/hyperparameters)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Set experiment name\n", + "training.experiment_name(\"My Experiment\")\n", + "\n", + "# Set training parameters\n", + "training.epochs(10)\n", + "\n", + "# Review your training plan\n", + "training.get_training_plan()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "**Expected output:** A summary showing all training parameters including:\n", + "- **Training Description** \u2014 experiment name, model name, objective\n", + "- **Dataset Parameters** \u2014 dataset ID, size, classes\n", + "- **Training Parameters** \u2014 epochs, cycles, batch size, validation split\n", + "- **Hyperparameters** \u2014 optimizer, loss function, learning rate, callbacks\n", + "- **Augmentation Parameters** \u2014 data augmentation settings\n", + "\n", + "Review these carefully before starting. Adjust any values using the commands in the table above." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## 5. Start training\n", + "\n", + "Everything configured? Launch the training run:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "training.start() # start the experiment as configured above" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## What happens next?\n", + "\n", + "Your model is now being trained on the tracebloc infrastructure. Here's what to expect:\n", + "\n", + "1. **Training starts** \u2014 the model will begin training on the linked dataset inside a secure environment\n", + "2. **Monitor progress** \u2014 go to your use case on [ai.tracebloc.io](https://ai.tracebloc.io) to see training status and logs\n", + "3. **View results** \u2014 once training completes, check the leaderboard in your use case to see how your model performed\n", + "4. **Compare models** \u2014 if other team members or vendors have submitted models, you can compare performance metrics side by side\n", + "\n", + "Training time depends on your dataset size, model complexity, and the number of epochs. A typical training run takes a few minutes to a few hours.\n", + "\n", + "\ud83d\udcd6 **Learn more:** [How to evaluate models \u2192](https://docs.tracebloc.io/join-use-case/model-evaluation)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## Logout\n", + "\n", + "When you're done, log out to end your session:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "user.logout()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "---\n", + "## Need help?\n", + "\n", + "- \ud83d\udcd6 [Documentation](https://docs.tracebloc.io)\n", + "- \ud83d\udce7 [support@tracebloc.io](mailto:support@tracebloc.io)\n", + "- \ud83d\udc1b [Open an issue](https://github.com/tracebloc/start-training/issues)\n", + "- \ud83d\udcac [Discord](https://discord.gg/tracebloc)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "version": "3.9.0" + } + }, + "nbformat": 4, + "nbformat_minor": 4 +} \ No newline at end of file