hanzo-ml/trainer
1
0
Fork 0
mirror of https://github.com/hanzo-ml/trainer.git synced 2026-09-24 00:31:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: brand-neutral rebrand (consume @<org>/brand contract) (#1)

Browse Source 
5 new root markdown files. UPSTREAM_README.md preserves original.
No upstream code modified. Branding consumed at runtime from a
brand package per BRAND.md (@hanzo/brand, @luxfi/brand,
@zooai/brand, etc.). Multi-tenant via JWT tenant claim per
MULTI_TENANT.md. Apache-2.0 preserved; NOTICE attributes upstream.
This commit is contained in:
zeekay
2026-05-19 08:12:22 -07:00
committed by GitHub
parent 8704ba0bd4
commit e081842b6f
7 changed files with 352 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BRAND.md
+59
View File
@@ -0,0 +1,59 @@
# Brand package contract
This fork (and every fork in the `hanzo-ml` estate) consumes brand
configuration from a runtime brand package conforming to a shared
schema.
## Schema
A brand package ships:
```
@<org>/brand/
brand.json # source of truth: brand, chains, iam, rpc, walletConnect
dist/
index.{js,mjs,d.ts} # exports: loadBrand(), brand singleton, theme tokens
loader.{js,mjs,d.ts} # loadBrand() runtime
assets/
logo/logo.svg
logo/favicon.png
fonts/
DESIGN.md # design spec (theming, typography, density)
```
## `brand.json` top-level keys
| Key | Purpose |
|---|---|
| `brand` | name, title, domains, social links, theme tokens (light/dark), logoUrl, faviconUrl, supportEmail |
| `chains` | supported chain IDs, default chain |
| `iam` | issuer, jwksUrl, tenantClaim, tenantHeader |
| `rpc` | RPC endpoint matrix per chain/env |
| `walletConnect` | WalletConnect project ID + metadata |
| `api` | API endpoint matrix per env |
## Runtime contract
```typescript
import { brand, loadBrand } from '@<org>/brand/loader'
await loadBrand() // hydrates the singleton from /brand.json
console.log(brand.name) // e.g. "Lux Exchange" / "Hanzo AI" / "Zoo"
console.log(brand.appDomain)
console.log(brand.iam.jwksUrl)
```
## Reseller deployment
A reseller takes this fork, publishes their own brand package
(`@<their-org>/brand`) with their assets + `brand.json`, sets:
```bash
BRAND_PACKAGE=@<their-org>/brand
```
The fork deploys under their brand with zero source changes.
## Available brand packages
See README.md table.
DESIGN.md
+26
View File
@@ -0,0 +1,26 @@
# Design
The design system is defined in the brand package's `DESIGN.md`. Each
brand publishes its own design spec; this fork delegates to whichever
brand package is configured via `BRAND_PACKAGE`.
## Layered design system
| Layer | Where |
|---|---|
| Tokens (colors, typography, spacing, density) | brand package `brand.json` + `DESIGN.md` |
| Components (buttons, forms, cards) | this fork's frontend (where applicable) |
| Brand assets (logos, favicons, fonts) | brand package `assets/` |
| Theme application | brand package `loadBrand()` + framework integration |
## Why no design system in this fork
The design system lives one level up so all forks in the lifecycle
estate share consistent components and tokens without duplication. A
reseller swaps the brand package; design tokens update without code
changes.
## See also
- The configured brand package's `DESIGN.md` (e.g. `@luxfi/brand/DESIGN.md`)
- BRAND.md in this fork
HANZO_CHANGES.md
+24
View File
@@ -0,0 +1,24 @@
# Changes from upstream
- Forked into the `hanzo-ml` GitHub organization
- Brand-neutral README + BRAND.md + DESIGN.md + MULTI_TENANT.md +
HANZO_CHANGES.md + NOTICE added at repo root
- `UPSTREAM_README.md` preserves the original project documentation
- No upstream code modified; `merge-upstream` keeps this current
## Brand-neutral guarantee
This fork hardcodes NO product brand. All branding is consumed at
runtime from a `@<org>/brand` package per the contract in BRAND.md.
Any reseller can deploy this fork under their own brand with zero
source changes.
## Hanzo control plane reference
The canonical control plane for the ML lifecycle estate is the Rust
operator at [`hanzoai/operator`](https://github.com/hanzoai/operator).
This fork is either:
- the shipped frontend (for `pipelines`)
- a reference implementation for the Rust operator's reconciler
patterns (for `kubeflow`, `kuberay`, `trainer`, `katib`,
`spark-operator`, `hub`, `kserve`)
MULTI_TENANT.md
+34
View File
@@ -0,0 +1,34 @@
# Multi-tenant isolation contract
This fork is multi-tenant via a Hanzo-compatible IAM JWT.
## Tenant scope
Every request carries `Authorization: Bearer <jwt>`. The JWT is
validated against the brand package's `iam.jwksUrl`. The `iam.tenantClaim`
(default `org_id`) determines the tenant scope for the request.
## Header propagation
After validation, the gateway/middleware strips any client-supplied
identity headers and emits the validated tenant via
`iam.tenantHeader` (default `X-Org-Id`). Downstream services trust
only the gateway-minted header.
## Storage isolation
Per-tenant data lives at `${DATA_DIR}/orgs/${tenant_id}/...`.
Cross-tenant access is forbidden by default. Services check the JWT
tenant matches the resource owner before any read/write.
## Configurability
`iam.tenantClaim` and `iam.tenantHeader` are brand-package-configurable
so resellers using a non-standard JWT shape can override the defaults
without code changes.
## Reference
- HIP-0026 — Identity and Access Management Standard
- HIP-0106 — Unified Hanzo Cloud Binary (tenant-routing section)
- HIP-0302 — Per-tenant SQLite + ZapDB Durability
NOTICE
+12
View File
@@ -0,0 +1,12 @@
This work is a fork of an upstream open-source project licensed under
the Apache License, Version 2.0 (the "License"). The full upstream
license text and copyright notices are preserved in LICENSE and
throughout the source tree.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Modifications by the hanzo-ml community are documented in
HANZO_CHANGES.md. The fork is brand-neutral; branding is consumed at
runtime from a `@<org>/brand` package per the contract in BRAND.md.
README.md
+70 -102
View File
@@ -1,127 +1,95 @@
# Kubeflow Trainer # Trainer
[![Join Slack](https://img.shields.io/badge/Join_Slack-blue?logo=slack)](https://www.kubeflow.org/docs/about/community/#kubeflow-slack-channels) Distributed model training operator (PyTorch, TensorFlow, MPI, XGBoost).
[![Coverage Status](https://coveralls.io/repos/github/kubeflow/trainer/badge.svg?branch=master)](https://coveralls.io/github/kubeflow/trainer?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/kubeflow/trainer)](https://goreportcard.com/report/github.com/kubeflow/trainer)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10435/badge)](https://www.bestpractices.dev/projects/10435)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kubeflow/trainer)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkubeflow%2Ftrainer.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkubeflow%2Ftrainer?ref=badge_shield)
<h1 align="center"> A brand-neutral fork in the [hanzo-ml](https://github.com/hanzo-ml)
<img src="./docs/images/trainer-logo.svg" alt="logo" width="200"> organization — the open-source ML lifecycle estate. Branding is
<br> consumed at runtime from a brand package via the
</h1> [`@<org>/brand`](#brand-package) contract; the same code deploys under
any white-label brand with zero source changes.
Latest News 🔥 ## Brand package
- [2026/03] Kubeflow Trainer v2.2 is officially released with support for JAX and XGBoost This fork imports brand configuration from a runtime brand package
Training Runtimes, enhanced observability with metrics propagation to TrainJob status, following the contract used across the open-source ML estate. Set
and Flux Framework integration for HPC and MPI workloads. Check out `BRAND_PACKAGE` to the npm package name; the fork's frontend (where
[the blog post announcement](https://blog.kubeflow.org/kubeflow-trainer-v2.2-release/). applicable) calls `loadBrand()` at boot to hydrate the singleton from
- [2025/11] Kubeflow Trainer v2.1 is officially released with support of that package's `brand.json`.
[Distributed Data Cache](https://www.kubeflow.org/docs/components/trainer/user-guides/data-cache/),
topology aware scheduling with Kueue and Volcano, and LLM post-training enhancements. Check out
[the GitHub release notes](https://github.com/kubeflow/trainer/releases/tag/v2.1.0).
- [2025/09] Kubeflow SDK v0.1 is officially released with support for CustomTrainer,
BuiltinTrainer, and local PyTorch execution. Check out
[the GitHub release notes](https://github.com/kubeflow/sdk/releases/tag/0.1.0).
- [2025/07] PyTorch on Kubernetes: Kubeflow Trainer Joins the PyTorch Ecosystem. Find the
announcement in [the PyTorch blog post](https://pytorch.org/blog/pytorch-on-kubernetes-kubeflow-trainer-joins-the-pytorch-ecosystem/).
<details> Available brand packages:
<summary>More</summary>
- [2025/07] Kubeflow Trainer v2.0 has been officially released. Check out | Package | Brand |
[the blog post announcement](https://blog.kubeflow.org/trainer/intro/) and [the |---|---|
release notes](https://github.com/kubeflow/trainer/releases/tag/v2.0.0). | `@hanzo/brand` | default / Hanzo AI |
- [2025/04] From High Performance Computing To AI Workloads on Kubernetes: MPI Runtime in | `@luxfi/brand` | Lux Finance |
Kubeflow TrainJob. See the [KubeCon + CloudNativeCon London talk](https://youtu.be/Fnb1a5Kaxgo) | `@zooai/brand` | Zoo Labs |
| `@osage/brand` | Osage |
| `@parsdao/brand` | Pars DAO |
| `@cyrusdao/brand` | Cyrus DAO |
| `@onyx-plus/brand` | Onyx Plus |
| `@migaprotocol/brand` | Miga Protocol |
| `@vccross/brand` | VC Cross |
| `@mlc/brand` | MLC |
| `@zenlm/brand` | Zen LM |
</details> Or any custom reseller package conforming to the same schema.
## Overview ## Multi-tenant via IAM
Kubeflow Trainer is a Kubernetes-native distributed AI platform for scalable large language model Every request carries a JWT. The brand package's `iam` block specifies:
(LLM) fine-tuning and training of AI models across a wide range of frameworks, including
PyTorch, MLX, HuggingFace, DeepSpeed, JAX, XGBoost, and more.
Kubeflow Trainer brings MPI to Kubernetes, orchestrating multi-node, multi-GPU distributed - `issuer` — JWT issuer URL
jobs efficiently across high-performance computing (HPC) clusters. This enables high-throughput - `jwksUrl` — JWKS endpoint
communication between processes, making it ideal for large-scale AI training that requires - `tenantClaim` — JWT claim with the org/tenant ID (default `org_id`)
ultra-fast synchronization between GPUs nodes. - `tenantHeader` — HTTP header that propagates the validated tenant
ID (default `X-Org-Id`)
Kubeflow Trainer seamlessly integrates with the Cloud Native AI ecosystem, including The tenant ID scopes all storage, queries, and resource ownership.
[Kueue](https://kueue.sigs.k8s.io/docs/tasks/run/trainjobs/) for topology-aware scheduling and Cross-tenant access is forbidden by default.
multi-cluster job dispatching, as well as [JobSet](https://github.com/kubernetes-sigs/jobset) and
[LeaderWorkerSet](https://github.com/kubernetes-sigs/lws) for AI workload orchestration.
Kubeflow Trainer provides a distributed data cache designed to stream large-scale data with zero-copy ## Quick start (reseller deployment)
transfer directly to GPU nodes. This ensures memory-efficient training jobs while maximizing
GPU utilization.
With [the Kubeflow Python SDK](https://github.com/kubeflow/sdk), AI practitioners can effortlessly ```bash
develop and fine-tune LLMs while leveraging the Kubeflow Trainer APIs: TrainJob and Runtimes. export BRAND_PACKAGE="@<your-org>/brand" # e.g. @luxfi/brand
```
<h1 align="center"> The frontend (this fork's case: `pipelines` ships the React DAG UI;
<img src="./docs/images/trainer-tech-stack.drawio.svg" alt="logo" width="500"> the other 7 are read-only reference forks) loads the brand at boot.
<br> The backend reads the brand package's `iam` block for JWKS + tenant
</h1> configuration.
## Kubeflow Trainer Introduction ## Role
Checkout following KubeCon + CloudNativeCon talks for Kubeflow Trainer capabilities: Read-only reference for the Rust operator's `TrainingJob` reconciler.
[![Kubeflow Trainer](https://img.youtube.com/vi/Lgy4ir1AhYw/0.jpg)](https://www.youtube.com/watch?v=Lgy4ir1AhYw) The canonical control plane for the ML lifecycle estate is the Rust
operator at [`hanzoai/operator`](https://github.com/hanzoai/operator).
See [HIP-0109](https://github.com/hanzoai/HIPs/blob/main/HIPs/hip-0109-hanzo-ml-cloud-toolkit.md)
for the lifecycle CRD set.
Additional talks: ## Upstream sync
- [From High Performance Computing To AI Workloads on Kubernetes: MPI Runtime in Kubeflow TrainJob](https://youtu.be/Fnb1a5Kaxgo) This fork stays current with upstream via the GitHub merge-upstream
- [Streamline LLM Fine-tuning on Kubernetes With Kubeflow LLM Trainer](https://youtu.be/O7cNlaz3Hqs) API. No upstream code is modified in this fork; only the 5 markdown
files at root are added.
## Getting Started ```bash
gh api -X POST /repos/hanzo-ml/trainer/merge-upstream \
-f branch=master
```
Please check [the official Kubeflow Trainer documentation](https://www.kubeflow.org/docs/components/trainer/getting-started) See [UPSTREAM_README.md](./UPSTREAM_README.md) for the original
to install and get started with Kubeflow Trainer. project documentation.
## Community ## License
The following links provide information on how to get involved in the community: Apache-2.0. See [NOTICE](./NOTICE) for attribution.
- Join our [`#kubeflow-trainer` Slack channel](https://www.kubeflow.org/docs/about/community/#kubeflow-slack). ## See also
- Attend [the bi-weekly AutoML and Training Working Group](https://bit.ly/2PWVCkV) community meeting.
- Check out [who is using Kubeflow Trainer](ADOPTERS.md).
## Contributing - [DESIGN.md](./DESIGN.md) — design system reference (mirrors the brand
package's design spec)
Please refer to the [CONTRIBUTING guide](CONTRIBUTING.md). - [BRAND.md](./BRAND.md) — brand package contract and reseller guide
- [MULTI_TENANT.md](./MULTI_TENANT.md) — tenant isolation contract
## Changelog - [HANZO_CHANGES.md](./HANZO_CHANGES.md) — divergence from upstream
- [HIP-0109 Hanzo ML Cloud Toolkit](https://github.com/hanzoai/HIPs/blob/main/HIPs/hip-0109-hanzo-ml-cloud-toolkit.md)
Please refer to the [CHANGELOG](CHANGELOG.md).
## Kubeflow Training Operator V1
Kubeflow Trainer project is currently in <strong>alpha</strong> status, and APIs may change.
If you are using Kubeflow Training Operator V1, please refer [to this migration document](https://www.kubeflow.org/docs/components/trainer/operator-guides/migration/).
Kubeflow Community will maintain the Training Operator V1 source code at
[the `release-1.9` branch](https://github.com/kubeflow/trainer/tree/release-1.9).
You can find the documentation for Kubeflow Training Operator V1 in [these guides](https://www.kubeflow.org/docs/components/trainer/legacy-v1).
## Acknowledgement
This project was originally started as a distributed training operator for TensorFlow and later we
merged efforts from other Kubeflow Training Operators to provide a unified and simplified experience
for both users and developers. We are very grateful to all who filed issues or helped resolve them,
asked and answered questions, and were part of inspiring discussions.
We'd also like to thank everyone who's contributed to and maintained the original operators.
- PyTorch Operator: [list of contributors](https://github.com/kubeflow/pytorch-operator/graphs/contributors)
and [maintainers](https://github.com/kubeflow/pytorch-operator/blob/master/OWNERS).
- MPI Operator: [list of contributors](https://github.com/kubeflow/mpi-operator/graphs/contributors)
and [maintainers](https://github.com/kubeflow/mpi-operator/blob/master/OWNERS).
- XGBoost Operator: [list of contributors](https://github.com/kubeflow/xgboost-operator/graphs/contributors)
and [maintainers](https://github.com/kubeflow/xgboost-operator/blob/master/OWNERS).
- Common library: [list of contributors](https://github.com/kubeflow/common/graphs/contributors) and
[maintainers](https://github.com/kubeflow/common/blob/master/OWNERS).
UPSTREAM_README.md
+127
View File
@@ -0,0 +1,127 @@
# Kubeflow Trainer
[![Join Slack](https://img.shields.io/badge/Join_Slack-blue?logo=slack)](https://www.kubeflow.org/docs/about/community/#kubeflow-slack-channels)
[![Coverage Status](https://coveralls.io/repos/github/kubeflow/trainer/badge.svg?branch=master)](https://coveralls.io/github/kubeflow/trainer?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/kubeflow/trainer)](https://goreportcard.com/report/github.com/kubeflow/trainer)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/10435/badge)](https://www.bestpractices.dev/projects/10435)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/kubeflow/trainer)
[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkubeflow%2Ftrainer.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fkubeflow%2Ftrainer?ref=badge_shield)
<h1 align="center">
<img src="./docs/images/trainer-logo.svg" alt="logo" width="200">
<br>
</h1>
Latest News 🔥
- [2026/03] Kubeflow Trainer v2.2 is officially released with support for JAX and XGBoost
Training Runtimes, enhanced observability with metrics propagation to TrainJob status,
and Flux Framework integration for HPC and MPI workloads. Check out
[the blog post announcement](https://blog.kubeflow.org/kubeflow-trainer-v2.2-release/).
- [2025/11] Kubeflow Trainer v2.1 is officially released with support of
[Distributed Data Cache](https://www.kubeflow.org/docs/components/trainer/user-guides/data-cache/),
topology aware scheduling with Kueue and Volcano, and LLM post-training enhancements. Check out
[the GitHub release notes](https://github.com/kubeflow/trainer/releases/tag/v2.1.0).
- [2025/09] Kubeflow SDK v0.1 is officially released with support for CustomTrainer,
BuiltinTrainer, and local PyTorch execution. Check out
[the GitHub release notes](https://github.com/kubeflow/sdk/releases/tag/0.1.0).
- [2025/07] PyTorch on Kubernetes: Kubeflow Trainer Joins the PyTorch Ecosystem. Find the
announcement in [the PyTorch blog post](https://pytorch.org/blog/pytorch-on-kubernetes-kubeflow-trainer-joins-the-pytorch-ecosystem/).
<details>
<summary>More</summary>
- [2025/07] Kubeflow Trainer v2.0 has been officially released. Check out
[the blog post announcement](https://blog.kubeflow.org/trainer/intro/) and [the
release notes](https://github.com/kubeflow/trainer/releases/tag/v2.0.0).
- [2025/04] From High Performance Computing To AI Workloads on Kubernetes: MPI Runtime in
Kubeflow TrainJob. See the [KubeCon + CloudNativeCon London talk](https://youtu.be/Fnb1a5Kaxgo)
</details>
## Overview
Kubeflow Trainer is a Kubernetes-native distributed AI platform for scalable large language model
(LLM) fine-tuning and training of AI models across a wide range of frameworks, including
PyTorch, MLX, HuggingFace, DeepSpeed, JAX, XGBoost, and more.
Kubeflow Trainer brings MPI to Kubernetes, orchestrating multi-node, multi-GPU distributed
jobs efficiently across high-performance computing (HPC) clusters. This enables high-throughput
communication between processes, making it ideal for large-scale AI training that requires
ultra-fast synchronization between GPUs nodes.
Kubeflow Trainer seamlessly integrates with the Cloud Native AI ecosystem, including
[Kueue](https://kueue.sigs.k8s.io/docs/tasks/run/trainjobs/) for topology-aware scheduling and
multi-cluster job dispatching, as well as [JobSet](https://github.com/kubernetes-sigs/jobset) and
[LeaderWorkerSet](https://github.com/kubernetes-sigs/lws) for AI workload orchestration.
Kubeflow Trainer provides a distributed data cache designed to stream large-scale data with zero-copy
transfer directly to GPU nodes. This ensures memory-efficient training jobs while maximizing
GPU utilization.
With [the Kubeflow Python SDK](https://github.com/kubeflow/sdk), AI practitioners can effortlessly
develop and fine-tune LLMs while leveraging the Kubeflow Trainer APIs: TrainJob and Runtimes.
<h1 align="center">
<img src="./docs/images/trainer-tech-stack.drawio.svg" alt="logo" width="500">
<br>
</h1>
## Kubeflow Trainer Introduction
Checkout following KubeCon + CloudNativeCon talks for Kubeflow Trainer capabilities:
[![Kubeflow Trainer](https://img.youtube.com/vi/Lgy4ir1AhYw/0.jpg)](https://www.youtube.com/watch?v=Lgy4ir1AhYw)
Additional talks:
- [From High Performance Computing To AI Workloads on Kubernetes: MPI Runtime in Kubeflow TrainJob](https://youtu.be/Fnb1a5Kaxgo)
- [Streamline LLM Fine-tuning on Kubernetes With Kubeflow LLM Trainer](https://youtu.be/O7cNlaz3Hqs)
## Getting Started
Please check [the official Kubeflow Trainer documentation](https://www.kubeflow.org/docs/components/trainer/getting-started)
to install and get started with Kubeflow Trainer.
## Community
The following links provide information on how to get involved in the community:
- Join our [`#kubeflow-trainer` Slack channel](https://www.kubeflow.org/docs/about/community/#kubeflow-slack).
- Attend [the bi-weekly AutoML and Training Working Group](https://bit.ly/2PWVCkV) community meeting.
- Check out [who is using Kubeflow Trainer](ADOPTERS.md).
## Contributing
Please refer to the [CONTRIBUTING guide](CONTRIBUTING.md).
## Changelog
Please refer to the [CHANGELOG](CHANGELOG.md).
## Kubeflow Training Operator V1
Kubeflow Trainer project is currently in <strong>alpha</strong> status, and APIs may change.
If you are using Kubeflow Training Operator V1, please refer [to this migration document](https://www.kubeflow.org/docs/components/trainer/operator-guides/migration/).
Kubeflow Community will maintain the Training Operator V1 source code at
[the `release-1.9` branch](https://github.com/kubeflow/trainer/tree/release-1.9).
You can find the documentation for Kubeflow Training Operator V1 in [these guides](https://www.kubeflow.org/docs/components/trainer/legacy-v1).
## Acknowledgement
This project was originally started as a distributed training operator for TensorFlow and later we
merged efforts from other Kubeflow Training Operators to provide a unified and simplified experience
for both users and developers. We are very grateful to all who filed issues or helped resolve them,
asked and answered questions, and were part of inspiring discussions.
We'd also like to thank everyone who's contributed to and maintained the original operators.
- PyTorch Operator: [list of contributors](https://github.com/kubeflow/pytorch-operator/graphs/contributors)
and [maintainers](https://github.com/kubeflow/pytorch-operator/blob/master/OWNERS).
- MPI Operator: [list of contributors](https://github.com/kubeflow/mpi-operator/graphs/contributors)
and [maintainers](https://github.com/kubeflow/mpi-operator/blob/master/OWNERS).
- XGBoost Operator: [list of contributors](https://github.com/kubeflow/xgboost-operator/graphs/contributors)
and [maintainers](https://github.com/kubeflow/xgboost-operator/blob/master/OWNERS).
- Common library: [list of contributors](https://github.com/kubeflow/common/graphs/contributors) and
[maintainers](https://github.com/kubeflow/common/blob/master/OWNERS).