@zhuoyuezs/ml-platform 0.1.10 → 0.1.12

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

@@ -0,0 +1,58 @@
+# Model Packaging Commands
+
+## Request shape and managed runtime
+
+```json
+{
+  "model_artifact_id": "replace_registered_model_artifact_id",
+  "package_version": "1.0.0",
+  "input_modes": ["inline"]
+}
+```
+
+The artifact must be `REGISTERED` and pass validation. Creation submits work;
+first use `validate-model-package` for read-only contract/runtime preflight. Version defaults to `1` if omitted;
+use an explicit immutable version (semantic versioning is a convention, not an
+enforced three-component schema). Capture `package.package_id` and
+`package.package_version` from the creation response.
+
+The server resolves images and destination from the approved trainer/device
+runtime configuration. Optional request keys `base_image`, `worker_image`,
+`builder_image`, `destination_repository` are equality assertions against that
+configuration, not arbitrary overrides. Omit them when using managed defaults;
+do not guess registries or pass deployment secrets. A mismatch needs the approved
+runtime contract, not repeated package versions. Unknown request keys return 422; do not add `runtime`, `image`, or `resources`
+fields. Inspect the returned resolved package.
+
+`input_modes` must be unique, include `inline`, and may additionally include
+`feature_lookup` or `tabular_forecast` only when supported by the selected
+runtime. `feature_lookup` still requires artifact lineage
+`online_eligible=true`; `tabular_forecast` requires a direct tabular model
+signature. Do not infer either capability from training success.
+Omit rather than use an empty list to request default inline behavior.
+
+Always query the exact package ID and version; states are `PACKAGING`, `READY`,
+`FAILED`, `CANCELLED`. A client timeout does not prove packaging failed. Retain the
+known identity and query it before attempting another creation.
+
+```bash
+ml-platform --profile server validate-model-artifact <artifact-id>
+ml-platform --profile server validate-model-package model-package-request.json
+ml-platform --profile server create-model-package model-package-request.json
+ml-platform --profile server get-model-package <package-id> --package-version <version>
+```
+
+Confirm the ModelArtifact, signature, runtime, immutable base/builder/worker image digests, input modes, semantic package version, and destination repository. Creation submits a workload and needs separate authorization. Never put registry credentials in JSON.
+
+A deliverable package is `READY` and includes its remote image digest, immutable reference, manifest, signature and adapter hashes, runtime capabilities, and a passing test report for the same digest. Other states are not deliverable.
+
+For a sequence-output artifact, inspect the returned runtime contract for
+`output_schema.kind=sequence`, its fixed maximum `length` and frequency, and
+`horizon_prediction=prefix`. Inference returns the requested aligned prefix up
+to that maximum; a one-step artifact remains scalar.
+
+```bash
+ml-platform --profile server cancel-model-package <package-id> --package-version <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.

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

@@ -0,0 +1,259 @@
+# Training request and response contracts
+
+These examples require only the released CLI, inspected registry definitions and
+downloaded dataset contracts. Replace example identities and business choices;
+they are not a ready-to-submit trainer recommendation. Never import platform
+Python modules or require a checkout to author these requests.
+
+## TrainingRunSpec
+
+Example forecasting sequence run:
+
+```json
+{
+  "schema_version": "ml_data_platform.training_run/v3",
+  "run_id": "pressure_forecast_run_01",
+  "experiment": "pressure_forecast",
+  "task": {"kind": "forecasting", "objective": "regression"},
+  "data": {
+    "artifact": {
+      "project": "default", "dataset_id": "pressure_dataset",
+      "manifest_hash": "REPLACE_WITH_RETURNED_MANIFEST_HASH"
+    },
+    "features": {"feature_set": {
+      "project": "default", "name": "pressure_features", "version": "v1"
+    }},
+    "labels": ["future_pressure"],
+    "temporal": {
+      "prediction_time_column": "event_time", "label_time_column": "label_time",
+      "frequency": "5min", "horizon": "5min", "series_keys": []
+    },
+    "splits": {
+      "assignment_column": "rowset_split", "train": ["training"],
+      "validation": ["validation"], "test": ["test"]
+    }
+  },
+  "input_adapter": {
+    "kind": "sequence", "context_length": 24,
+    "context_end": "prediction_time_inclusive", "frequency": "5min",
+    "stride": 1, "gap_policy": "reject", "padding_policy": "none"
+  },
+  "forecast_target_adapter": {
+    "schema_version": "ml_data_platform.forecast_target_adapter/v1",
+    "kind": "continuous_target_series",
+    "target_input_column": "pressure",
+    "output_label_column": "future_pressure",
+    "target_gap_policy": "reject",
+    "point_output": {"statistic": "median", "step": "horizon"}
+  },
+  "label_transform": {"name": "identity", "version": "v1"},
+  "trainer": {
+    "project": "default", "name": "replace_approved_trainer", "version": "v1",
+    "parameters": {}
+  },
+  "reproducibility": {"seed": 0, "deterministic": true},
+  "evaluation": {"split": "validation", "metrics": ["mae", "rmse", "r2"]}
+}
+```
+
+`task.kind`, objective and input kind must match inspected TrainerCapabilities.
+`trainer.parameters` must satisfy the definition's parameter schema; `{}` only
+works if no parameters are required. Resource/device settings belong to the Job,
+not the Run. `run_id` is the immutable run identity, not a name/version pair.
+Do not add guessed `version`, `model`, `dataset` or `hyperparameters` top-level keys.
+
+For tabular input use `input_adapter: {"kind":"tabular"}`; omit sequence context
+fields. Forecasting tasks still require `data.temporal`, even with tabular input.
+Non-temporal regression can omit it. Do not change task kind just to evade checks.
+`series_keys` must identify entity-key columns when multiple series coexist;
+an empty list treats the entire artifact as one series.
+
+## Direct tabular forecasting with known-future features
+
+Tree and other matrix-based models can forecast a variable target grid without
+pretending that future observations are available. Set the tabular adapter to
+`forecast_mode="direct"`. The dataset's `TemporalBinding.prediction_time_column`
+is the historical `cutoff_time`; `label_time_column` is the row's future
+`target_time`. Each row is one `(cutoff_time, target_time)` pair. Values such as
+weather forecasts, schedules, calendar fields and `lead_hours` are ordinary
+feature columns; list the forecast columns in `known_future_columns`.
+
+```json
+{
+  "input_adapter": {
+    "kind": "tabular",
+    "forecast_mode": "direct",
+    "known_future_columns": ["weather_temperature", "weather_wind"]
+  },
+  "data": {
+    "temporal": {
+      "prediction_time_column": "cutoff_time",
+      "label_time_column": "target_time",
+      "frequency": "1h",
+      "horizon": "240h",
+      "series_keys": ["market"]
+    }
+  }
+}
+```
+
+At serving time use `input_mode="tabular_forecast"` and send one row per
+target. `target_time` must be later than the cutoff and aligned to the model
+frequency. When known-future columns are declared, every row must include
+`available_at <= cutoff_time`; this prevents using a forecast revision that did
+not exist when the prediction was made.
+
+```json
+{
+  "input_mode": "tabular_forecast",
+  "cutoff_time": "2026-09-09T10:30:00+08:00",
+  "targets": [
+    {
+      "target_time": "2026-09-10T00:00:00+08:00",
+      "available_at": "2026-09-09T08:00:00+08:00",
+      "values": {
+        "weather_temperature": 21.3,
+        "weather_wind": 2.8,
+        "lead_hours": 13.5
+      }
+    }
+  ]
+}
+```
+
+The serving runtime calls the same plugin `predict()` with a two-dimensional
+batch and returns one result carrying each `target_time`. XGBoost and LightGBM
+already implement this batch matrix operation; the platform adapter owns the
+cutoff, target-grid and availability checks. Training must use historical
+forecast snapshots selected by `available_at <= cutoff_time`, never later actual
+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). The FeatureSet reference must match
+the artifact; the full ordered FeatureSet determines model channels. There is
+no documented `data.features.columns` shortcut for choosing a subset.
+
+`identity:v1` leaves labels unchanged. `difference` requires a baseline Feature
+in `required_inputs` and at least one `online_inputs` entry, which must be a
+subset; it must have an inverse. Do not use target transforms to fix incorrect
+dataset label clocks or to invent unsupported transforms.
+
+## Chronos-2 v2 targets and covariates
+
+Use the v2 adapter when Chronos-2 should jointly forecast multiple storage
+channels or consume covariates. The target and output-label arrays are ordered,
+and `data.labels` must use that same output-label order:
+
+```json
+{
+  "labels": ["future_storage_soc", "future_storage_power"],
+  "forecast_target_adapter": {
+    "schema_version": "ml_data_platform.forecast_target_adapter/v2",
+    "kind": "continuous_target_series_with_covariates",
+    "targets": [
+      {"input_column": "storage_soc", "output_label_column": "future_storage_soc"},
+      {"input_column": "storage_power", "output_label_column": "future_storage_power"}
+    ],
+    "covariates": [
+      {"column": "recent_load", "role": "past_only"},
+      {"column": "weather_temperature", "role": "known_future"},
+      {"column": "peak_valley", "role": "known_future"}
+    ],
+    "target_gap_policy": "reject",
+    "point_output": {"statistic": "median", "step": "horizon"}
+  }
+}
+```
+
+Every target and covariate must be a numeric Feature. `past_only` is available
+only through the cutoff. `known_future` must be represented in training by the
+forecast or schedule available at that historic cutoff, never by a later actual
+observation. At runtime callers provide one finite numeric value for every
+`known_future` column and every prediction step. The current contract validates
+the names, values, and row count; retain forecast issue/availability lineage in
+the upstream Feature data when revisions must be audited.
+
+## TrainingJobRequest and identity propagation
+
+After validation and authorized registration, use the returned `spec_hash`
+unchanged in the Job request. Do not calculate it from raw JSON bytes.
+
+```json
+{
+  "run": {
+    "run_id": "pressure_forecast_run_01",
+    "spec_hash": "REPLACE_WITH_REGISTERED_SPEC_HASH"
+  },
+  "execution": {
+    "executor": "kubernetes", "device": "cpu",
+    "resources": {"cpu": "2", "memory": "4Gi"},
+    "deadline": "90min", "retry_limit": 0
+  }
+}
+```
+
+Sizing is illustrative. `spec_hash` uses `sha256:<64 hex>`. Omit `output_uri`
+to use managed storage unless an approved contract supplies it. Runtime device
+approval occurs during Job resolution; `validate-training-run` has no execution
+device and cannot prove device approval. Use `validate-training-job` after Run registration to validate device and
+execution settings without creating a Job.
+
+| Command | Fields to retain / inspect |
+| --- | --- |
+| `validate-training-run` | `status=valid`, `spec_hash`, `data_schema_hash`, `feature_columns`, `label_columns` |
+| `register-training-run` | `training_run.run_id`, top-level `spec_hash`; response `status=validated` also represents registration, not mere dry-run |
+| `submit-training-job` | `job_spec.job_id`, `job_spec.job_spec_hash`, `job.phase`; top-level `status=accepted` is not completion |
+| `get-training-job` | `spec` and `status`; inspect `status.phase`, then successful `status.artifact_id` |
+| `validate-model-artifact` | Validation evidence for the exact returned artifact ID; Job success alone is insufficient |
+
+Use `get-training-run`, `get-model-artifact` and their list commands to recover
+identities; see [discovery.md](discovery.md). There is no training wait command.
+Preserve the original Run JSON and IDs.
+Poll `get-training-job` at a bounded interval (for example 15 seconds) with a
+user-appropriate deadline; a polling timeout does not cancel or fail the Job.
+After a submission timeout, retain the request and reconcile any known Job ID
+before retrying. Never create a new run merely because the HTTP response was lost.
+
+## Sequence population semantics
+
+Context step is `frequency * stride`. Stride spaces context observations; it
+does not select every Nth target endpoint. Inclusive context with length L covers
+offsets `(L-1)..0`; exclusive covers `L..1`. For 24 points, 5min frequency and
+stride 1, inclusive context starts 115min before the cutoff, exclusive 120min.
+Keep Operator source history and endpoint-policy lookback as separate contracts.
+
+The adapter materializes history over the full series, then assigns samples by
+the target endpoint's split. Test endpoints may use causal Feature history from
+earlier splits; splitting does not truncate their context. Duplicate timestamps
+within a series are invalid. Missing early context with no padding is skipped;
+null Features or labels also skip samples. Candidate row counts therefore are
+not training/evaluation sample counts. Report the materialized population and
+coverage instead of assuming all Parquet rows were used.
+
+For `continuous_target_series`, TrainingRun v3 derives the fixed maximum
+`prediction_length` as `data.temporal.horizon / data.temporal.frequency`; the
+horizon must be a positive exact multiple of the frequency. The target input
+must be a numeric, at-prediction Feature and the output label must be the sole
+entry in `data.labels`. Use this adapter only when the inspected TrainerDefinition
+advertises `forecast_target_modes=["continuous_target_series"]`.
+
+The resulting model emits the complete fixed-length trajectory. Serving accepts
+aligned horizons up to that maximum and returns the corresponding trajectory
+prefix; it rejects unaligned or longer horizons. A one-step model remains a
+scalar response.
+
+`gap_policy=fill` requires `padding_policy=edge` or `zero`; non-fill requires
+`padding_policy=none`. Filling changes model inputs and needs an intended
+business policy. `skip` and padding are not automatic fixes for rejected grids.
+
+Training's `evaluation.metrics` uses `mae`, `rmse`, `r2`. Independent governed
+EvaluationConfig uses versioned names such as `regression.mae`. They are different
+contracts. Training `evaluation.split=auto` prefers nonempty test, then validation,
+then train; choose an explicit split when reserving the test set for final review.
+Training metrics are not a governed EvaluationResult or release gate pass.
+
+For sequence outputs, current training and governed evaluation apply regression
+metrics to the terminal point at the trained maximum horizon. They do not yet
+provide per-step or whole-trajectory release gates; record this limitation when
+reporting evidence for a multi-point package.

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

@@ -0,0 +1,107 @@
+# Training Commands
+
+## Preflight before expensive training
+
+Settle the final DataSchema (including split/metadata and label/time columns),
+FeatureSet order and evaluation runtime before the first Job. See
+[evaluation.md](evaluation.md) for inherited split bindings and runtime failures.
+
+- Inspect exact TrainerDefinition `project/name:v1`, entrypoint, image digest,
+  capabilities (including `forecast_target_modes`) and parameter schema. Similar names in different projects are
+  distinct identities; registration does not imply runtime approval.
+- Match definition and device to the active runtime release. On `not approved
+  for device`, preserve the rejected identity, device and release ID. Use `get-model-runtime-release` to find the
+  approved binding; if the deployed release lacks discovery, request its contract;
+  do not try similar names or re-register trainers to bypass approval.
+- 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
+  drop business inputs: declare every target and covariate in the adapter.
+- Keep labels outside FeatureSet order, verify temporal horizon against
+  `label_time - prediction_time`, and validate the complete TrainingRun before
+  registration/submission. Validation may not catch undeclared plugin limits or
+  missing dependencies in the eventual Worker.
+- For a continuous future trajectory, use TrainingRun v3. Use
+  `continuous_target_series` for legacy v1 or
+  `continuous_target_series_with_covariates` for v2. Its fixed maximum
+  prediction length comes from temporal horizon divided by frequency; do not
+  put `prediction_length` in trainer-specific parameters.
+
+Merge this fragment under TrainingRun `data`, alongside `artifact`, `features`,
+`labels` and the applicable `temporal` binding:
+
+```json
+{
+  "splits": {
+    "assignment_column": "rowset_split",
+    "train": ["training"],
+    "validation": ["validation"],
+    "test": ["test"]
+  }
+}
+```
+
+`train` is the consumer role; `training` is an example observed artifact value.
+Use the actual assignment values. Evaluation inherits this original binding;
+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.
+
+## Commands
+
+Read [training-contracts.md](training-contracts.md) when authoring a Run or Job
+JSON. It provides complete request shapes, response paths and sequence semantics.
+
+Discover already-registered TrainerDefinitions (read-only) before authoring a
+TrainingRunSpec or deciding whether registration is needed:
+
+```bash
+ml-platform --profile server list-trainer-definitions
+ml-platform --profile server get-trainer-definition <name> <version> [--project default]
+```
+
+`get-trainer-definition` returns the entrypoint, immutable training image digest,
+`artifact_format`, `model_file`, capabilities, and parameter schema. Use it to confirm
+the referenced `v1` definition exists and its image digest matches the approved runtime
+release; discovery never mutates the registry. Registering a new definition is the
+separate mutation below, and a 404 means the definition (not the model plugin) is missing.
+
+```bash
+ml-platform --profile server register-trainer trainer-definition.json
+ml-platform --profile server validate-training-run training-run.json
+ml-platform --profile server register-training-run training-run.json
+ml-platform --profile server validate-training-job training-job-request.json
+ml-platform --profile server submit-training-job training-job-request.json
+ml-platform --profile server get-training-job <job-id>
+```
+
+The TrainingRun binds immutable DatasetArtifact identities, DataSchema, ordered inputs, targets, InputAdapter, TrainerDefinition `v1`, reproducibility controls, and runtime identity. Validation proves compatibility only. Submit the run and Job separately after authorization and record spec hash and Job ID. Terminal success must expose a ModelArtifact ID; validate it before evaluation or packaging.
+
+```bash
+ml-platform --profile server validate-model-artifact <artifact-id>
+ml-platform --profile server retry-training-job <job-id>
+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.
+
+## Chronos-2 future-known inputs
+
+For storage forecasting, tomorrow's weather forecast and peak/valley schedule
+are `known_future` covariates. The v2 adapter binds their Feature columns and
+the ordered target/output-label pairs; see [training-contracts.md](training-contracts.md)
+for the complete JSON fragment.
+
+Training records must contain the forecast that was available at each historic
+cutoff, not actual weather observed later. At online inference, pass one numeric
+row per forecast step using the Serving runtime, not `fetch-inference-data`:
+
+```bash
+ml-platform predict-model /absolute/path/to/inference-request.json \
+  --serving-url https://storage-forecast.example
+```
+
+For `input_mode=inline`, put those rows in `inputs.future_covariates`. For
+`input_mode=feature_lookup`, put them in the top-level `future_covariates`.
+Their column names must exactly match the adapter's `known_future` covariates,
+and their count must equal the trained `prediction_length`.