@zhuoyuezs/ml-platform 0.2.7 → 0.2.9

package/skills/feature-management/references/operator-authoring.md

@@ -7,13 +7,25 @@ Read this file whenever a workflow creates or changes executable Operator code.
 1. Package contract
 2. Feature entrypoint contract
 3. Causal calculation rules
-4. Required tests
-5. Build and publication
-6. Security boundary
+4. Online period aggregates
+5. Required tests
+6. Build and publication
+7. Security boundary
 
 ## Package Contract
 
-Build a standalone pure-Python wheel. Do not import report-local, experiment-local, or unregistered business packages. Declare runtime dependencies explicitly, but keep the package small and compatible with `py3-none-any`.
+Build a standalone pure-Python wheel (`py3-none-any`). The platform verifies
+the wheel digest and only extracts it into an isolated import path; it does not
+install `Requires-Dist` dependencies, run `pip`, or accept native code. At run
+time an Operator can import only the Python standard library, its own wheel,
+and packages already present in the image that executes it: dataset builds
+(the `dataset-chronon` dependency group, which provides `pandas`, `numpy` via
+`pandas`, `pyarrow` and `pydantic`) and API realtime reads (the `api`
+dependency group). Do not import report-local, experiment-local, or
+unregistered business packages, and do not depend on libraries such as `scipy`
+or `scikit-learn` that those images do not provide; vendor small pure-Python
+helpers into the wheel instead. `[project].dependencies` documents the expected
+environment for local tests only; it does not make a dependency available.
 
 Minimal `pyproject.toml`:
 
@@ -63,9 +75,19 @@ computation_hash
 
 Each `metric_frames[parameter_key]` is a standard long frame with source timestamps and values. Resolve frames from `context.inputs`; do not reach into a database, API, filesystem secret, or environment credential.
 
-Use `context.cutoff_times` for causal feature windows. It is derived once from
-`context.target_times - context.prediction_horizon` using the DatasetManifest
-prediction contract; do not parse a duplicated Feature-level horizon.
+Use `context.cutoff_times` for causal feature windows. `context.target_times`
+are the materialized rows' `event_time` values, which are the prediction
+decision times, and `context.cutoff_times` equals them: a row's feature
+cutoff is its own `event_time`. The DatasetManifest `prediction.horizon` moves
+label availability to `label_time = event_time + horizon` (and the realtime
+response `target_time = cutoff_time + horizon`); it does not move the Operator
+context's feature reads earlier. Do not subtract `context.prediction_horizon`
+from either index, and do not parse a duplicated Feature-level horizon. This
+rule covers Operator inputs only: a DatasetManifest `endpoint_policy` evaluates
+abnormal-window context overlap with its own `cutoff = t - h` formula, described
+in [contracts.md](contracts.md). Resolved lineage records this as
+`prediction_time_semantics: event_time_is_causal_cutoff` and
+`label_time_derivation: prediction_time_plus_horizon`.
 
 An Operator requires an explicit forecast contract whenever its formula or code
 uses `context.cutoff_times`, or any `input_schema.history_requirements` entry uses
@@ -100,7 +122,11 @@ One Operator may return multiple physical columns. Each public Feature still bin
 
 ## Causal Calculation Rules
 
-State every time rule in tests and descriptions:
+State every time rule in tests and descriptions. A formula that needs the
+complete requested window rather than a bounded causal lookback (for example
+full-window interpolation or smoothing) is not partition-invariant; document
+that the Dataset must be built with `--partition-duration none
+--max-parallelism 1` (see [commands.md](commands.md)).
 
 - forecast horizon and cutoff derivation;
 - whether an event exactly at cutoff is included (`<=`) or excluded (`<`);
@@ -113,6 +139,72 @@ State every time rule in tests and descriptions:
 
 Never infer a rule from a Feature name alone. Require a business decision when a boundary is unspecified.
 
+## Online Period Aggregates
+
+Use this method when one Feature row summarizes a whole period (for example a
+day, shift or batch window) and the Feature must also be served online through
+`fetch-inference-data` or a model's `feature_lookup`. The realtime path gives
+the Operator exactly one target row, `event_time = cutoff`, and only source
+rows with `timestamp <= cutoff`, so the batch and online values agree only when
+the formula is causal and bounded.
+
+Row semantics:
+
+- Anchor the row at the period end: the row at cutoff `T` summarizes the
+  period that ended at `T` (for a daily Feature, `T` is local midnight and the
+  period is the previous day). Never label a row with the period start and
+  aggregate data after it.
+- Decide the period boundary from the source timestamp meaning, which must be
+  confirmed by the data owner (see [contracts.md](contracts.md), realtime
+  policy questions). If an hourly record is stamped at the hour start, the
+  record stamped `T` belongs to the next period, so use `[T - period, T)`. If it
+  is stamped at the hour end, the record stamped `T` closes the period, so use
+  `(T - period, T]`. Test the record exactly at `T` either way.
+
+Contract declarations:
+
+- `supports_online: true` on the Operator and `offline_online_supported: true`
+  on each Feature that will be served online.
+- `input_schema.history_requirements` with `anchor: cutoff` and a lookback that
+  covers the aggregation period, any multi-period context (for example a
+  3-day rolling statistic), and alignment slack for source timestamps. For
+  example, a daily mean that also uses the two previous days needs at least
+  `3d` plus slack. This lookback is also the per-Parameter realtime read
+  window; the default realtime floor `min_lookback=1h` is far too short for a
+  period aggregate, and it is not a substitute for the declaration.
+- `input_schema.prediction` with `required`, `minimum_horizon` and
+  `maximum_horizon` (a strict nowcast uses `true`, `0min`, `0min`).
+- Do not use `anchor: target_time` with zero lookback for a period aggregate;
+  online that reads almost nothing.
+
+Formula rules:
+
+- Use only rows inside the declared lookback that are at or before the row's
+  cutoff. A row's value must not change when data after its cutoff is added,
+  or when history older than the lookback is added or removed.
+- Freeze fitted constants in Feature `config`. Values fitted on training data,
+  such as fallback medians, clipping limits or normal ranges, must be computed
+  once offline, written into `config`, and versioned with the Feature. Do not
+  recompute them from the window at run time: the online window holds only
+  the lookback, so a recomputed value differs between batch and online and
+  between partitions. A retrain that refits these constants needs a new
+  Feature (and usually Operator) version.
+- Fill gaps only forward in time, and bound each fill by a maximum age or a
+  frozen constant. Never backward-fill from an observation after the row's
+  cutoff. Avoid backward-filling the start of the window too: the result then
+  depends on where the window starts and breaks partition invariance.
+- The Operator owns interior gap handling. The platform's realtime tolerances
+  (`allow_tail_edge_missing`, `allow_internal_gap_fill`) only judge how far the
+  newest source row lags the cutoff; they do not insert values. Keep one
+  missing-data rule, inside the Operator or a declared Parameter rule, so batch
+  builds and realtime reads compute the same value.
+- Emit data-quality flags as their own output columns, each bound to its own
+  Feature: for example a valid-observation count, an "insufficient data" flag,
+  or a business state flag such as "plant stopped". A flag tells consumers
+  that a row was computed under a fallback rule; do not hide that by silently
+  filling the value. Include a flag in the model FeatureSet only if it is an
+  intended model input.
+
 ## Required Tests
 
 Use deterministic fixtures and cover each applicable item with a separately
@@ -131,6 +223,22 @@ requested-output, event-time-order, or dtype/rounding cases below:
 9. output dtype and rounding;
 10. every dated business-rule branch.
 
+For an online-capable Operator (`supports_online: true`), also add:
+
+11. cutoff invariance: adding source rows after the cutoff leaves the row
+    unchanged;
+12. lookback invariance: adding or removing history older than the declared
+    lookback leaves the row unchanged;
+13. partition invariance: computing many cutoffs in one call equals computing
+    each cutoff alone with only its lookback window, which is what a realtime
+    read does;
+14. fallback rows: a period with no or too few valid observations produces the
+    documented fallback value and quality flag, using the frozen constants.
+
+After publication, compare `fetch-inference-data` at a few historical cutoffs
+with the same rows of a batch DatasetArtifact. Any difference means the
+Operator, its fill rule or its lookback is not causal; fix it before training.
+
 Run package tests before building the wheel. Then inspect the wheel tag and ensure it is `py3-none-any`.
 
 ## Build And Publication

package/skills/model-deployment-management/SKILL.md

@@ -35,6 +35,9 @@ deployment does not reach `READY` or an operation is rejected.
   the model capacity and sampling grid. In `feature_lookup` mode, never send
   `future_covariates`; the platform retrieves the complete known-future Feature
   window visible at the cutoff. Inline mode still supplies those rows in inputs.
+- Clustering deployments take no `inference_policy`, `horizon`, or
+  `output_window`; an optional `include_inputs: true` echoes the model input
+  row. See the clustering request in [references/operations.md](references/operations.md).
 - Run `validate-deployment` before `create-deployment`. Validation is read-only
   and does not authorize creation.
 - Obtain explicit authorization for the exact deployment and operation before

package/skills/model-deployment-management/references/operations.md

@@ -39,7 +39,11 @@ ml-platform --profile server list-deployments \
   --model-artifact-id <artifact-id>
 ```
 
-The filters may be used independently and combined with `--service`,
+列表默认按 `deployment_id` 升序；需要按生命周期时间排序时使用
+`--sort-by created_at|updated_at --sort-order asc|desc`。
+
+Use `--service TEXT` for a case-insensitive service-name substring; surrounding
+whitespace is ignored and an empty value does not filter. The filter may be combined with
 `--environment`, `--state`, `--q`, `--limit`, and `--offset`. These results are
 ITSMP platform deployments; external model-center delivery callbacks are a
 separate status surface.
@@ -157,6 +161,15 @@ ml-platform --profile server predict-deployment <deployment-id> \
   /absolute/path/request.json
 ```
 
+For a clustering model (`task_type: clustering` in `GET /v1/model`), send no
+`horizon` or `output_window`; they are rejected. The single result is
+`prediction: {kind: "clustering", cluster_id, distance_to_center |
+cluster_probability}` without `target_time`. Add `"include_inputs": true` to
+receive `results[0].inputs`, the validated model input row in signature column
+order (before the model's own transform); it defaults to `false`, is rejected
+for forecasting models, and requires a package image that supports it. Missing
+or non-finite retrieved inputs fail the request.
+
 For a package with an explicit `availability_boundary`, inspect
 `lineage.visibility` in the prediction response. It records the package's
 boundary, `cutoff_time`, `attempt_started_at`, `knowledge_time`,

package/skills/model-lifecycle-management/SKILL.md

@@ -36,6 +36,22 @@ uses platform CLI contracts and works without an ITSMP TUI or a specific Agent
 Runtime. An execution host may additionally persist plans, method hashes,
 attempts and checkpoints; those records do not replace platform evidence.
 
+For unsupervised clustering (`task.kind=clustering`, for example
+`kmeans_clusterer` or `gaussian_mixture_clusterer`), read the clustering
+section of [references/training-contracts.md](references/training-contracts.md)
+for the Run, parameter and model-file contract, and the clustering section of
+[references/packaging.md](references/packaging.md) for packaging and
+single-row inference without a horizon. The cluster count and preprocessing
+have silent defaults (8 clusters for KMeans, no scaling or PCA). Ask the user
+for them, or select them with the documented method in that reference, before
+submitting a clustering Run.
+
+For clustering evaluation and registration, read the clustering section of
+[references/evaluation.md](references/evaluation.md). Use a `task_type:
+"clustering"` EvaluationConfig with `targets: ["cluster_id"]`, and label
+`all`/`train` rowset results as in-sample. Register only with one PASS,
+COMPLETE EvaluationResult for that artifact.
+
 Read [references/zero-shot-inference.md](references/zero-shot-inference.md) when
 the user wants synchronous zero-shot forecasting from JSON or CSV. This path
 uses the platform-owned `chronos2_forecaster` model name, not a public project

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

@@ -65,6 +65,20 @@ Jobs in lists are immutable specs; use the exact get-job command for refreshed
 status. Lists do not reconcile or schedule workloads. `get-training-run` returns
 `training_run` plus `spec_hash`; artifact/package detail returns the object.
 
+## Download artifact files
+
+```bash
+ml-platform --profile server download-model-artifact ARTIFACT_ID --out-dir /tmp/model-ARTIFACT_ID [--file runtime.json]
+ml-platform --profile server download-evaluation-result-artifact RESULT_ID --out-dir /tmp/eval-RESULT_ID [--file predictions.parquet]
+```
+
+Both commands download only files indexed by the registry record (all of them
+unless `--file` is repeated), verify each sha256 against that record, and remove
+the output directory on any mismatch. `--project` fails closed when the
+resource belongs to another project. Report the returned `files[].sha256` as
+content evidence; metadata reads alone do not prove file contents. Write
+downloads outside the repository.
+
 ## Read-only preflight
 
 ```bash
@@ -97,10 +111,11 @@ Training Run `task`, `data`, `data.artifact`, `features.feature_set`, `splits`,
 config references, members and execution, plus ModelPackage requests, are also
 structured. Unknown keys return 422 with `detail[].loc` identifying the field.
 Keep algorithm-specific `trainer.parameters` governed by the SystemModel
-parameter schema. A typed nested contract such as Chronos-2 `lora_config`
+parameter schema. A typed contract such as Chronos-2 `lora_config` or the
+KMeans/Gaussian Mixture clustering parameters (including `preprocessing`)
 rejects unknown fields; a SystemModel that intentionally advertises
-`additionalProperties` remains extensible. Do not infer one policy from the
-other.
+`additionalProperties` remains extensible. Read `additionalProperties` from
+the exact SystemModel instead of inferring one model's policy from another.
 
 These HTTP checks preserve accepted values and do not rewrite historical stored
 contracts or hashes. Legacy records remain readable. A previously ignored typo

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

@@ -100,6 +100,138 @@ 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 |
@@ -199,6 +331,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/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