@zhuoyuezs/ml-platform 0.1.8 → 0.1.10

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

@@ -1,51 +0,0 @@
-# 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` only when supported by the selected runtime and artifact lineage
-has `online_eligible=true`. Do not infer online eligibility 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.
-
-```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

@@ -1,139 +0,0 @@
-# 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/v2",
-  "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"
-  },
-  "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.
-
-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.
-
-## 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.
-
-`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.

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

@@ -1,81 +0,0 @@
-# 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 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.
-- The current platform Chronos2Plugin requires `[sample, context, 1]`, exactly
-  one channel. This is a platform adapter restriction, not a universal statement
-  about Chronos-2. Six-feature sequences are incompatible. Do not silently drop
-  business inputs: select a suitable trainer or agree a univariate contract.
-- 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.
-
-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.