@zhuoyuezs/ml-platform 0.2.8 → 0.2.10

package/skills/model-lifecycle-management/references/evaluation.md

@@ -51,6 +51,43 @@ Inspect `get-metric-definition regression.mae v1` before relying on this metric.
 Release mode additionally requires at least one required validation rule with a
 business-approved threshold; do not invent thresholds to obtain PASS.
 
+`regression.hit_rate:v1` is available for point-prediction regression metrics.
+Set `parameters.tolerance` in the metric entry; tolerance is a finite,
+nonnegative absolute error in the target's units, and equality counts as a hit:
+
+```json
+{
+  "name": "regression.hit_rate", "version": "v1",
+  "targets": ["future_pressure"], "calculation_space": "business",
+  "parameters": {"tolerance": 5.0}
+}
+```
+
+The result is the fraction of valid rows whose absolute prediction error is at
+most the tolerance. The resolved tolerance is recorded in each MetricResult and
+must match when results are summarized or compared. It is an absolute threshold,
+not a percentage; choose it using the target's unit and business acceptance
+criteria.
+
+To calculate per-day metrics on China Standard Time dates, add the time bucket
+contract to the registered EvaluationConfig:
+
+```json
+{
+  "time_buckets": {
+    "width": "1d",
+    "timezone": "Asia/Shanghai",
+    "alignment": "left"
+  }
+}
+```
+
+`timezone` accepts IANA timezone names and defaults to `UTC`. Daily buckets use
+local calendar midnights and half-open intervals, so a bucket is keyed by the
+local date; use `dimension: "time_bucket"` when creating an analysis view from
+the resulting EvaluationResult IDs. The configured timezone is part of the
+immutable EvaluationConfig identity.
+
 For a fixed-length multi-step forecast, `regression.mae` and
 `regression.rmse` cover only the terminal point at the maximum trained horizon.
 Use `regression.trajectory_mae` and `regression.trajectory_rmse` for a release
@@ -100,12 +137,144 @@ not prove Worker dependency availability. Validate before submitting and confirm
 the approved Worker supports the model plugin. Successful training in another
 image does not establish evaluation support.
 
+## Clustering evaluation
+
+A clustering ModelArtifact (with `output_bindings`) is evaluated only by an
+EvaluationConfig with `task_type: "clustering"`. Supervised configs reject
+clustering artifacts, and clustering configs reject supervised artifacts.
+There are no labels: the Worker loads the frozen model, predicts assignments
+for the requested rowset, and computes metrics. It never refits the model or
+its preprocessing and never relabels clusters.
+
+Example release `evaluation-config.json`. The thresholds are placeholders and
+must be business-approved before use:
+
+```json
+{
+  "name": "process_regimes_release",
+  "version": "v1",
+  "task_type": "clustering",
+  "mode": "release",
+  "metrics": [
+    {"name": "clustering.silhouette", "calculation_space": "transformed"},
+    {"name": "clustering.davies_bouldin", "calculation_space": "transformed"},
+    {"name": "clustering.cluster_count"},
+    {"name": "clustering.min_cluster_share"}
+  ],
+  "validation": [
+    {"metric": "clustering.silhouette", "operator": ">=", "threshold": 0.25},
+    {"metric": "clustering.min_cluster_share", "operator": ">=", "threshold": 0.05}
+  ],
+  "clustering": {"sample_limit": 5000, "sample_seed": 0}
+}
+```
+
+The `clustering` object is optional and accepted only for `task_type:
+"clustering"`:
+
+- `sample_limit` (>= 2, default 5000) bounds the silhouette computation. Larger
+  rowsets are sampled deterministically with `sample_seed` (default 0). Other
+  metrics use every valid row.
+- `reference_label_column` (optional) names an independent DataSchema column
+  with role `label` or `metadata`, never a model feature. It is required by the
+  external metrics `clustering.adjusted_rand_index` and
+  `clustering.normalized_mutual_info`, and is only a comparison reference,
+  never a training input.
+- `distance_metric` currently accepts only `euclidean`.
+
+Clustering configs reject `baseline`, comparison rules, sample weights and
+package (code) metrics. Built-in `clustering.*` metrics and expression metrics
+over them are supported:
+
+| Metric | Inputs | Direction | Calculation spaces |
+| --- | --- | --- | --- |
+| `clustering.silhouette` | features, assignment | maximize | `business`, `transformed` |
+| `clustering.davies_bouldin` | features, assignment | minimize | `business`, `transformed` |
+| `clustering.calinski_harabasz` | features, assignment | maximize | `business`, `transformed` |
+| `clustering.cluster_count` | assignment | neutral | `business` |
+| `clustering.min_cluster_share` | assignment | maximize | `business` |
+| `clustering.adjusted_rand_index` | assignment, reference label | maximize | `business` |
+| `clustering.normalized_mutual_info` | assignment, reference label | maximize | `business` |
+
+For feature-based metrics, `business` uses the raw FeatureSet values from the
+DatasetArtifact. `transformed` uses the model's own train-fitted preprocessing
+(the plugin's `transform`), which is the space the estimator clustered in and
+is identical to `business` when the model has no preprocessing. Prefer
+`transformed` for gates on models trained with a scaler or PCA, and record the
+chosen space. `cluster_count` and `min_cluster_share` describe only the
+non-empty clusters observed in the evaluated rowset. A trained cluster that
+receives no rows there is not counted.
+
+Example `evaluation-request.json`; `targets` is exactly the assignment output:
+
+```json
+{
+  "model_artifact_id": "replace_clustering_artifact_id",
+  "dataset": {
+    "project": "default",
+    "dataset_id": "replace_dataset_id",
+    "manifest_hash": "replace_with_exact_artifact_manifest_hash"
+  },
+  "rowset": "test",
+  "targets": ["cluster_id"],
+  "config": {"name": "process_regimes_release", "version": "v1"},
+  "execution": {"executor": "kubernetes", "resources": {"cpu": "2", "memory": "4Gi"}}
+}
+```
+
+The rowset comes from the original TrainingRun's `data.splits`. Prefer a
+holdout pool (`validation` or `test`). When the run declared no splits, the
+only accepted rowset is `all`, which is the complete training population.
+Evaluating `all` or `train` measures the population that fitted the model.
+Label any such Result as in-sample in every report, and do not present it as
+held-out evidence; the platform does not add that label for you.
+
+Decision semantics follow the shared release policy. Exploratory mode is
+always `INCONCLUSIVE`. In release mode:
+
+- When a metric cannot be computed meaningfully (fewer than two non-empty
+  clusters, no more rows than clusters, zero dispersion, non-finite inputs),
+  the platform records reason `CLUSTERING_DEGENERATE` and writes no number.
+- When a `transformed` metric is requested but the model runtime has no
+  `transform`, the platform records `CLUSTERING_TRANSFORM_UNAVAILABLE`.
+- A required rule on such a missing metric is `INCONCLUSIVE`, and that
+  outranks a `FAIL` in another rule, so the decision is `INCONCLUSIVE`.
+- Any configured metric that is missing makes `evidence_status` `INCOMPLETE`.
+
+Fix the population or configuration rather than dropping the metric to get a
+PASS.
+
+Each Result stores `clustering_diagnostics.json` beside the standard artifacts.
+It records the assignment and score outputs, feature order and hash, distance
+metric, sampling parameters, whether the transformed space was available,
+cluster sizes per slice, and the status of each metric (`computed`,
+`degenerate` or `unavailable`, with sampled-row counts). The prediction
+artifact carries the assignment and score per row key. List them with
+`get-evaluation-result-artifacts <result-id>` and download sha256-verified
+copies with `download-evaluation-result-artifact <result-id> --out-dir DIR
+[--file NAME]`.
+
+Registration requires all of the following:
+
+- one Result for the same artifact with `decision=PASS`,
+  `evidence_status=COMPLETE` and compatibility `ok`;
+- no required summary-level rule;
+- a model runtime that reports `production_ready=true`.
+
+```bash
+ml-platform --profile server register-model-artifact <artifact-id> \
+  --evaluation-id <evaluation-result-id>
+```
+
+Training feedback (`cluster_count`, `min_cluster_share`,
+`assignment_score_mean` in `metrics.json`) is not registration evidence.
+
 ## Diagnose before another build or training run
 
 | Symptom | Actual check and next action |
 | --- | --- |
 | `requires a named split` | Inherited TrainingRun `data.splits` is not a dictionary and requested rowset is not `all`. Inspect the original training request, not only manifest/resolved/Parquet splits. This check has no horizon-zero branch. |
-| `rowset is not declared` | Inspect `data.splits` role keys (`train`, `validation`, `test`), nonempty value arrays, assignment column and observed values. Manifest `training` can map to consumer role `train`. |
+| `rowset is not declared` | Inspect `data.splits` role keys (`train`, `validation`, `test`). For an ordinary binding, check nonempty value arrays, assignment column and observed values. For `mode: derived`, check the timezone-aware `strategy: time_range` ranges and the resolved row counts. Manifest `training` can map to consumer role `train`. |
 | DataSchema mismatch | Compare the full schema with the trained Job's hash, including split columns, roles and dtypes. Do not remove columns or falsify hashes to pass. |
 | Label leakage | Materialize label columns separately from FeatureSet order; input selection alone cannot repair the contract. |
 | Chronos-2 runtime unavailable | Record executor, error stage/Job, runtime identity and Worker image evidence. The prediction plugin cannot load a dependency; request runtime support from the platform owner. New dataset/model versions do not install dependencies. |
@@ -183,6 +352,23 @@ ml-platform --profile server publish-executable-package <name> <version>
 
 Custom metric packages must be deterministic, digest-bound, network-restricted, verified, and separately authorized for publication.
 
+The published wheel entrypoint is called as `entrypoint(inputs, context)` in an
+isolated evaluation worker. `inputs` contains only the declared arrays (for
+example `label`, `prediction`, `probability`, and `weight`). `context` contains
+the frozen metric identity and the resolved parameters for this evaluation under
+`context["parameters"]`; read that mapping instead of relying on package or
+process globals. Parameter validation happens when the EvaluationConfig is
+resolved, and the resolved values are persisted in the MetricResult and its
+comparison/summary evidence. A package metric that declares no parameter schema
+must reject supplied parameters.
+
+```python
+def score(inputs, context):
+    tolerance = float(context["parameters"]["tolerance"])
+    error = abs(inputs["prediction"] - inputs["label"])
+    return float((error <= tolerance).mean())
+```
+
 ```bash
 ml-platform --profile server validate-evaluation-run evaluation-request.json
 ml-platform --profile server submit-evaluation evaluation-request.json
@@ -199,6 +385,7 @@ An EvaluationRunRequest binds ModelArtifact(s), a frozen DatasetArtifact rowset,
 ml-platform --profile server get-evaluation-result <result-id>
 ml-platform --profile server get-evaluation-result-metrics <result-id>
 ml-platform --profile server get-evaluation-result-artifacts <result-id>
+ml-platform --profile server download-evaluation-result-artifact <result-id> --out-dir /tmp/eval-<result-id> --file predictions.parquet
 ml-platform --profile server summarize-evaluation-run <run-id>
 ml-platform --profile server get-evaluation-summary <summary-id>
 ```

package/skills/model-lifecycle-management/references/experiment-runs.md

@@ -0,0 +1,59 @@
+# ExperimentRun
+
+`ExperimentRun` is the platform control-plane record for a finite comparison
+over one frozen `DatasetArtifact`. It supports model comparison, feature/input
+ablation and a small candidate matrix while reusing existing TrainingRun,
+TrainingJob, ModelArtifact, EvaluationRun, EvaluationResult and
+EvaluationComparison records.
+
+It does not implement AutoML, a general DAG engine, automatic model selection,
+packaging or deployment. The Skill owns the modeling method and stopping rules;
+the platform owns durable candidate state and reconciliation.
+
+## Lifecycle
+
+Use the installed `ml-platform` CLI:
+
+```text
+ml-platform create-experiment-run SPEC.json
+ml-platform validate-experiment-run RUN_ID
+ml-platform submit-experiment-run RUN_ID
+ml-platform get-experiment-run RUN_ID
+ml-platform list-experiment-candidates RUN_ID --limit 50 --offset 0
+ml-platform reconcile-experiment-run RUN_ID
+ml-platform cancel-experiment-run RUN_ID
+```
+
+Create is idempotent for the same `experiment_run_id` and immutable
+`spec_hash`. Always validate before submit. Validation resolves every candidate's
+TrainingJob snapshot and has no training side effects. Submit is the mutation
+that may create TrainingJob records, subject to `max_parallelism`.
+
+## Candidate contract
+
+The spec must contain at least two candidates, a baseline candidate, one
+DatasetArtifact identity and one evaluation contract. Each candidate carries a
+complete TrainingRun v4 JSON object, a stable `candidate_id`, an optional
+hypothesis and parent candidate, and an execution policy. Candidate FeatureSets
+may be different exact-version subset/order projections of the same wide
+DatasetArtifact. Labels, split membership, temporal semantics, evaluation
+configuration and comparison population remain shared.
+
+## Recovery rules
+
+`UNKNOWN` means the platform cannot prove whether a remote submission happened.
+Reconcile first queries the durable TrainingJob/EvaluationRun records. It may
+resume only when the lifecycle record proves no remote submission was reached;
+it never blindly retries an unknown Kubernetes operation. An unknown candidate
+also stops new candidate submissions until it is reconciled. A known terminal
+failure is preserved and does not consume a parallel slot for independent
+candidates.
+
+## Completion
+
+Every candidate must be `RESULT_READY`, `FAILED`, `SKIPPED` or otherwise
+accounted for. The service calls the existing EvaluationComparison implementation
+only after complete results exist. `COMPLETE` with `ranking_allowed=true` requires
+complete evidence, comparable population and a release-mode EvaluationConfig;
+otherwise the run is `INCONCLUSIVE`. A result never authorizes registration,
+packaging or deployment by itself.

package/skills/model-lifecycle-management/references/model-comparison.md

@@ -1,10 +1,16 @@
 # Comparing models within one experiment
 
+Feature or input ablation is the controlled one-factor variant of this
+workflow. Read [ablation.md](ablation.md) for the baseline, removal-set and
+round-closeout rules; the comparison gates below still apply.
+
 Use one documented goal and user-authorized scope: metric, target, candidate
 constraints and any maximum number of training submissions. Preserve that goal
 when a follow-up changes a constraint or asks for verification. Reuse existing
 authorization when it covers the next action; ask only for missing decisions.
 No TUI, session service, or Runtime-specific tool is required for this method.
+Persist the candidate set and execution links in an `ExperimentRun`; see
+[experiment-runs.md](experiment-runs.md) for its CLI lifecycle.
 
 ## Shared scope and candidate execution
 
@@ -45,9 +51,8 @@ forecast horizon, and do not let trajectory construction cross split
 boundaries. Compare complete platform-produced EvaluationResults only after
 each candidate passes its own TrainingRun and evaluation preflight.
 
-For each candidate, record its hypothesis, exact changed inputs, parent attempt
-if any, request JSON and returned immutable IDs in the agent's working
-directory. Submit within the user's authorization, observe the TrainingJob,
+For each candidate, record its hypothesis, exact changed inputs and parent
+candidate in the ExperimentRun spec. Submit within the user's authorization, observe the TrainingJob,
 validate the resulting ModelArtifact, then submit and inspect governed
 evaluation. Explain the observed result before choosing another candidate.
 Do not resubmit after an unknown outcome: reconcile the existing Job or retry
@@ -57,12 +62,9 @@ the authorization described in the training reference.
 ## Rounds, failure evidence and stopping
 
 A round groups candidates that test a related hypothesis under the frozen
-comparison scope. Keep a small round record in the agent's working directory
-(outside a platform source checkout), using normal file tools. Include the
-scope/request paths, candidate identities and changes, submission IDs, observed
-status, result IDs, per-candidate reflection and the round's next decision.
-This is an agent work record, not a new platform resource or required tool.
-Update it after submissions and observations so another coding agent can resume.
+comparison scope. ExperimentRun and its candidates are the durable execution
+record. Keep any additional method reflection in the agent's working directory
+without duplicating platform status or IDs.
 
 When a candidate fails, inspect the actual Job status, attempts and diagnostic
 evidence. Distinguish a model execution failure from a runtime/infrastructure

package/skills/model-lifecycle-management/references/packaging.md

@@ -159,3 +159,49 @@ ml-platform --profile server cancel-model-package <package-id> --package-version
 ```
 
 Cancellation requires exact-package authorization. Do not rebuild an immutable failed version; correct inputs and create a new semantic package version. This Skill does not deploy images or write model-center delivery status.
+
+## Clustering packages and requests
+
+A clustering ModelArtifact has `output_bindings` and no `target_bindings`. Its
+Serving contract reports `task_type=clustering`, `horizon_mode=null`, no
+supported horizons, and `output_schema.kind=clustering` with the `cluster_id`
+assignment and one score (`distance_to_center` or `cluster_probability`).
+
+Package it with the ordinary request shape and `"input_modes": ["inline"]`.
+Add `feature_lookup` only when the generic retrieval conditions above hold. A
+clustering `feature_lookup_test` must omit `horizon` and `output_window`.
+The platform-generated image smoke test sends exactly one inline row, in
+ModelSignature column order, with no horizon. It requires one successful
+result with `prediction.kind=clustering`, an integer `cluster_id` >= 0 and a
+finite score.
+
+Packaging includes every model file the artifact declares, including the v2
+preprocessing sidecar. The Serving image must provide the scikit-learn version
+recorded in a v2 model file, otherwise model loading fails and the package
+cannot become `READY`. Use the clustering runtime binding from the same Runtime
+Release rather than another image.
+
+An inline request carries exactly one row, whose column names match the
+ModelSignature order exactly. Its timestamp must not be later than
+`cutoff_time`. Clustering requests reject `horizon` and `output_window`:
+
+```json
+{
+  "input_mode": "inline",
+  "cutoff_time": "2026-01-01T08:00:00+08:00",
+  "inputs": {
+    "timestamps": ["2026-01-01T08:00:00+08:00"],
+    "values": [{"pressure": 0.82, "temperature": 1180.0, "flow": 3.4}]
+  }
+}
+```
+
+```bash
+ml-platform predict-model /absolute/path/to/cluster-request.json \
+  --serving-url https://process-regimes.example
+```
+
+The single result returns `prediction.kind=clustering`, `cluster_id` and the
+score field, and has no `horizon` or `target_time`. Report the `model_version`
+(artifact ID) with each assignment, because cluster ids are not comparable
+across artifacts.

package/skills/model-lifecycle-management/references/training-contracts.md

@@ -112,6 +112,173 @@ capability requires it; do not attach it just because the task is a forecast.
 For the platform's detailed diagnostic and label-statistics procedure, read
 [`feature-management/references/supervised-datasets.md`](../../feature-management/references/supervised-datasets.md).
 
+## Unsupervised clustering runs
+
+Use this method for tabular clustering SystemModels such as
+`kmeans_clusterer:v1` and `gaussian_mixture_clusterer:v1`. Confirm that the
+inspected SystemModel advertises `tasks=["clustering"]`; do not reuse a
+supervised Trainer for clustering.
+
+```json
+{
+  "schema_version": "ml_data_platform.training_run/v4",
+  "run_id": "process_regimes_kmeans_01",
+  "experiment": "process_regimes",
+  "task": {"kind": "clustering", "objective": "clustering"},
+  "data": {
+    "artifact": {
+      "project": "default", "dataset_id": "process_features",
+      "manifest_hash": "REPLACE_WITH_RETURNED_MANIFEST_HASH"
+    },
+    "features": {"feature_set": {
+      "project": "default", "name": "process_cluster_inputs", "version": "v1"
+    }},
+    "labels": [],
+    "splits": {
+      "assignment_column": "rowset_split", "train": ["training"],
+      "validation": ["validation"], "test": ["test"]
+    }
+  },
+  "input_adapter": {"kind": "tabular"},
+  "label_transform": {"name": "identity", "version": "v1"},
+  "trainer": {
+    "project": "default", "name": "kmeans_clusterer", "version": "v1",
+    "parameters": {
+      "n_clusters": 4, "n_init": 20, "random_state": 42,
+      "preprocessing": {"scaler": "robust", "pca_variance": 0.95}
+    }
+  },
+  "reproducibility": {"seed": 42, "deterministic": true}
+}
+```
+
+Validation enforces these rules:
+
+- `task.objective` is `clustering`, `data.labels` is empty, `input_adapter.kind`
+  is `tabular`, and `label_transform` is `identity:v1`. Do not declare
+  `data.temporal`, `forecast_target_adapter` or label materializations for the
+  model; clustering has no supervised target.
+- The model FeatureSet is non-empty. Every column is a numeric
+  `role=feature` column available `at_prediction` or `static`, and every
+  artifact row's value is finite and non-null. Correct data gaps in the
+  DatasetArtifact; the trainer does not impute.
+- `data.splits` is optional. Without it, every artifact row is a training row.
+  With it, the cluster count must be between 2 and the train-pool row count.
+  Validation and test pools may be empty. Splits matter for preprocessing,
+  because transforms are fitted on train rows only.
+- `trainer.parameters` is strict. Unknown keys, booleans in integer fields,
+  integral floats such as `4.0`, and out-of-range values are rejected before
+  scheduling. Read the authoritative schema with
+  `get-system-model kmeans_clusterer v1` or
+  `get-system-model gaussian_mixture_clusterer v1`.
+
+| SystemModel | Cluster count (default) | Other estimator fields (defaults) |
+| --- | --- | --- |
+| `kmeans_clusterer:v1` | `n_clusters` >= 2 (8) | `init` `k-means++`/`random`; `n_init` >= 1 or `auto` (`auto`); `max_iter` >= 1 (300); `tol` >= 0 (1e-4) |
+| `gaussian_mixture_clusterer:v1` | `n_components` >= 2 (2) | `covariance_type` `full`/`tied`/`diag`/`spherical` (`full`); `init_params` `kmeans`/`k-means++`/`random`/`random_from_data` (`kmeans`); `n_init` >= 1 (1); `max_iter` >= 1 (100); `tol` >= 0 (1e-3); `reg_covar` >= 0 (1e-6) |
+
+Both models also accept `random_state` (0..2^32-1; when it is unset, the
+Worker uses the run's `reproducibility.seed`, which it injects as `seed` at
+run time and which overrides any `seed` in the parameters) and an optional
+`preprocessing` object with exactly two fields:
+
+- `scaler`: `"robust"` or `null`. A robust scaler centers each column on its
+  train-pool median and divides by its interquartile range.
+- `pca_variance`: a float strictly between 0 and 1, or `null`. PCA keeps the
+  fewest components that explain that fraction of train-pool variance and runs
+  after the scaler.
+
+The trainer fits both transforms on train rows only and freezes them in the
+artifact. Validation, test, evaluation and Serving rows are transformed and
+assigned without refitting. Clustering distances and scores are computed in
+this transformed space.
+
+Apart from that runtime `seed`, clustering parameters are not filled from
+top-level `reproducibility`.
+`effective_trainer_parameters` contains exactly the submitted keys, and omitted
+fields use the schema defaults inside the Worker. Set the cluster count,
+`random_state` and `n_init` explicitly when the run must be reproducible and
+reviewable. Changing any of them requires a new `run_id`.
+
+### Choosing the cluster count and preprocessing
+
+The defaults are silent. If the Run omits the cluster count, KMeans trains 8
+clusters and Gaussian Mixture 2; if it omits `preprocessing`, no scaling or PCA
+is applied. Validation does not warn, and `effective_trainer_parameters` echoes
+only the submitted keys, so the default does not show up in the evidence you
+review. Never submit a clustering Run that relies on either default.
+
+Cluster count. Ask the user whether the business has a fixed number of regimes
+or categories. If it does, use that number and record who confirmed it. If it
+does not, select K with a documented method before treating any Run as final:
+
+1. Agree a candidate range with the user (for example 2–10), bounded by how
+   many clusters the business can name and act on and by the train-pool size.
+2. Fix everything except K: the same DatasetArtifact, model FeatureSet,
+   `preprocessing`, `n_init` and `random_state`. Each K is a separate
+   TrainingRun with its own `run_id`. Get authorization for the whole scan,
+   and follow [model-comparison.md](model-comparison.md) for recording
+   candidates, failures and stopping.
+3. Evaluate every candidate with one shared clustering EvaluationConfig
+   ([evaluation.md](evaluation.md)): `clustering.silhouette` (higher is
+   better), `clustering.davies_bouldin` (lower is better),
+   `clustering.calinski_harabasz` and `clustering.min_cluster_share`. Compare
+   transformed-space metrics only between runs with identical preprocessing;
+   use `calculation_space: "business"` when the comparison spans different
+   preprocessing.
+4. Check stability: retrain the leading candidates with two or three other
+   `random_state` values (or on subsamples) and compare the assignments, for
+   example with adjusted Rand index. Compute this in the workspace and label it
+   exploratory; it is not a governed EvaluationResult. A K whose clusters
+   change between seeds is not a stable business vocabulary.
+5. Show the user the leading candidates with cluster sizes and per-cluster
+   feature profiles in business units, and let the business judge whether the
+   clusters can be named and acted on. Metrics rarely give one clear winner,
+   so the final K is a business decision backed by the evidence above. Record
+   the range, metrics, stability result and decision.
+
+Preprocessing. Ask, or justify from the data, instead of accepting the
+default:
+
+- `scaler`: KMeans and Gaussian Mixture are distance-based, so a column with a
+  large numeric range dominates. Use `"robust"` when columns have different
+  units or scales, or contain outliers. Use `null` only when every column
+  shares one unit and absolute differences are meaningful to the business
+  (for example, a set of temperatures where a 10-degree gap means the same
+  thing in every column), and record that reason.
+- `pca_variance`: use it when many input columns are strongly correlated and
+  would otherwise count the same signal several times. A higher fraction
+  (0.95–0.99) keeps more detail; a lower one removes more noise. PCA makes
+  clusters harder to explain in business terms, so leave it `null` unless the
+  correlation is shown and the user accepts the trade-off.
+
+Write the chosen K and `preprocessing` explicitly in `trainer.parameters`, even
+when they equal the defaults.
+
+A successful clustering Job writes training feedback (`cluster_count`,
+`min_cluster_share`, `assignment_score_mean`) on the training `evaluation.split`,
+which defaults to `auto`. This is diagnostic evidence only. The ModelSignature
+outputs are `cluster_id` (int64) plus `distance_to_center` for KMeans or
+`cluster_probability` for Gaussian Mixture. Cluster ids are meaningful only
+within one immutable ModelArtifact.
+
+The model file (`model.kmeans.json` or `model.gmm.json`) records its format:
+
+- `<kind>_clustering/v1`: no preprocessing; estimator sidecar only.
+- `<kind>_clustering/v2`: preprocessing is present. The file additionally
+  lists `transform_file` in `model_files`, records the training-time
+  `scikit_learn_version`, the preprocessing config, and the fitted summary:
+  scaler type, PCA component count, retained explained-variance ratio and
+  input feature order.
+
+Loading refuses an unknown format, a missing estimator or transform sidecar,
+or a v2 file whose recorded scikit-learn version differs from the runtime.
+A v1 file records no scikit-learn version. Its safety relies on the training,
+evaluation and Serving images of one Runtime Release sharing the same locked
+scikit-learn stack, so keep v1 artifacts on images from that release line. Resolve a
+version mismatch by using the Runtime Release binding whose image matches the
+training runtime, or by retraining. Never edit artifact files.
+
 ## Chronos-2 LoRA parameters
 
 Chronos-2 fine-tuning settings belong under `trainer.parameters`; they are
@@ -227,7 +394,11 @@ weather observations.
 
 Inspect `data_schema.json`, `resolved_manifest.json` and the feature Parquet via
 `download-dataset-artifact DATASET_ID MANIFEST_HASH --project PROJECT --out-dir DIR`
-(repeat `--file` for selective downloads). In TrainingRun v4, the FeatureSet
+(repeat `--file` for selective downloads). `MANIFEST_HASH` is the artifact
+manifest hash from `list-dataset-artifacts` or `artifact.manifest_hash` of a
+succeeded `build-registered-dataset --wait`, not the registered manifest hash.
+After training, `download-model-artifact ARTIFACT_ID --out-dir DIR [--file NAME]`
+returns sha256-verified ModelArtifact files such as `runtime.json` and the model file. In TrainingRun v4, the FeatureSet
 reference defines the ordered model inputs. It may be a registered exact-version
 subset of the DatasetArtifact's materialized FeatureSet, in its own order. The
 platform freezes both identities and the projected dependency contract in the

package/skills/model-lifecycle-management/references/training.md

@@ -15,6 +15,11 @@ FeatureSet order and evaluation runtime before the first Job. See
   do not try similar names or re-register trainers to bypass approval.
 - ARIMA supports the v1 single-target adapter for single-channel CPU
   forecasting; it does not support covariates or the v2 adapter.
+- Clustering (`task.kind=clustering`) is unsupervised, CPU-only and tabular.
+  It uses TrainingRun v4 with `labels: []` and no temporal binding, optional
+  splits, and a strict parameter schema that includes train-fitted
+  `preprocessing`. Read the clustering section of
+  [training-contracts.md](training-contracts.md) before authoring the Run.
 - Chronos-2 supports the legacy v1 single-target adapter and the v2
   covariate-aware adapter. v2 jointly forecasts ordered target channels and
   accepts numeric `past_only` and `known_future` covariates. Do not silently
@@ -49,6 +54,40 @@ it does not reconstruct it from manifest `rowset_splits`. Save the submitted
 TrainingRun JSON, validation output, Job ID and ModelArtifact ID in the user's
 working directory so later diagnosis needs no source repository.
 
+For a second experiment over the same immutable DatasetArtifact, a TrainingRun
+may freeze a time based split without adding a split column to the artifact:
+
+```json
+{
+  "splits": {
+    "mode": "derived",
+    "strategy": "time_range",
+    "source_rowsets": ["all"],
+    "ranges": {
+      "train": {"start": "2026-01-01T00:00:00+08:00", "end": "2026-07-01T00:00:00+08:00"},
+      "validation": {"start": "2026-07-01T00:00:00+08:00", "end": "2026-08-01T00:00:00+08:00"},
+      "test": {"start": "2026-08-01T00:00:00+08:00", "end": "2026-09-01T00:00:00+08:00"}
+    }
+  }
+}
+```
+
+`time_range` uses timezone aware, left closed/right open prediction time
+intervals and requires unique row keys. The platform freezes each role's row
+identity in the resolved TrainingJob and rechecks it in the Worker. Samples
+whose `label_time` reaches or passes their role's end are excluded and counted
+in the validation snapshot; if that leaves no train samples, validation fails.
+Training time evaluation must explicitly use `train` or `validation`; `test`
+is reserved for an independent EvaluationRun. For `chronological_ratio`, provide
+`ratios` with `train`, `validation` and `test` values summing to `1`; equal
+prediction timestamps stay together. Actual counts may differ from requested
+ratios, and the algorithm version and row identities are frozen in the Job
+snapshot. Derived splits currently use all artifact rows as candidates; use
+`assignment_column` for artifacts containing auxiliary history or truth rows.
+Only `time_range` and `chronological_ratio` are supported. Confirm the selected
+training and evaluation Worker images support derived splits before submission.
+Existing `assignment_column` contracts keep their original behavior.
+
 ## Commands
 
 Read [training-contracts.md](training-contracts.md) when authoring a Run or Job
@@ -87,6 +126,27 @@ ml-platform --profile server cancel-training-job <job-id>
 
 Retry and cancellation require exact-Job authorization. Never change a run contract while retrying; create a new immutable run when semantic inputs change.
 
+## Clustering training sequence
+
+Every step below is a separate gate. Registration and submission still need
+explicit authorization.
+
+```bash
+ml-platform --profile server get-system-model kmeans_clusterer v1 --project default
+ml-platform --profile server validate-training-run cluster-run.json
+ml-platform --profile server register-training-run cluster-run.json
+ml-platform --profile server validate-training-job cluster-job-request.json
+ml-platform --profile server submit-training-job cluster-job-request.json
+ml-platform --profile server get-training-job <job-id>
+ml-platform --profile server validate-model-artifact <artifact-id>
+```
+
+The Job request uses `"device": "cpu"`; clustering SystemModels advertise no
+other device. Before submission, confirm that `effective_trainer_parameters`
+equals the submitted `trainer.parameters`. After success, validate the exact
+`status.artifact_id`; the artifact must carry clustering `output_bindings`
+instead of `target_bindings`.
+
 ## Chronos-2 fine-tuning parameters
 
 Configure Chronos-2 algorithm parameters only under