@zhuoyuezs/ml-platform 0.2.8 → 0.2.10

package/skills/prediction-report-management/SKILL.md

@@ -22,9 +22,15 @@ ml-platform --profile server get-prediction-report-run RUN_ID
 ```
 
 Check the deployment with `get-deployment DEPLOYMENT_ID` before creating a
-schedule. The deployment must support `feature_lookup` and have a usable
-inference horizon, supplied by either the schedule request or deployment
-policy. A report run may be `SKIPPED` when the selected revision is not READY.
+schedule. The deployment must support `feature_lookup`. A forecasting
+deployment also needs a usable inference horizon, supplied by either the
+schedule request or deployment policy. A clustering deployment (its model
+artifact has `output_bindings`) has no horizon: omit `horizon` and
+`output_window`, which are rejected. A report run may be `SKIPPED` when the
+selected revision is not READY.
+A READY staging revision is eligible; reporting does not require canary or
+production promotion, an Ingress, or a Gateway. Do not promote a deployment
+just to enable its report schedule.
 
 ## Configure a destination
 
@@ -51,8 +57,11 @@ and a non-empty `body` object. This maps each normalized prediction point:
 }
 ```
 
-A point always has `series_index` and `value`; `target_time` is present only
-when Serving returns it.
+A forecast point always has `series_index` and `value`; `target_time` is
+present only when Serving returns it. A clustering row has no `value`; it has
+`series_index`, `kind: "clustering"`, integer `cluster_id`, the model's score
+(`distance_to_center` or `cluster_probability`), and `model_artifact_id`, so
+map those fields instead. A cluster ID is meaningful only for that artifact.
 
 ```bash
 ml-platform --profile server validate-destination-profile PROFILE_JSON
@@ -80,9 +89,15 @@ and `type` for bounded transformations and validation. `timezone` is an IANA
 timezone and must be used together with `format`; it converts an aware ISO-8601
 timestamp before formatting. For a business endpoint that represents local
 midnight as the end of the previous business day, set `midnight_as_24: true`
-on a time field whose format contains `%H` (for example, `%H:%M`). This maps
-local `00:00` to `24:00` after timezone conversion and leaves other times
-unchanged. For example, use
+on both the business date field (`format: "%Y-%m-%d"`) and time field
+(`format: "%H:%M"`), with `timezone: "Asia/Shanghai"` on each. At exact local
+midnight, formatted dates move back one day and `%H` emits `24`; other times
+are unchanged. For example, `2026-10-31T00:00:00+08:00` maps to date
+`2026-10-30` and time `24:00`. Keep the timestamp mapped directly from
+`target_time` and the MW field directly from `value`, without format or
+numeric transforms. This leaves their original values unchanged. Keep
+`midnight_as_24` unset on `origin_date` when it means the local cutoff date.
+For example, use
 `{"source":"cutoff_time","format":"%Y-%m-%d","timezone":"Asia/Shanghai"}`
 to map `2026-09-10T16:00:00Z` to `2026-09-11`. Arbitrary code and expressions
 are not supported. A missing field or type failure produces
@@ -101,6 +116,14 @@ pause, or resume. Use `enabled: false` for a staged schedule that should not
 run yet. `SCHEDULE_JSON` contains `deployment_id`, five-field `cron`, IANA
 `timezone`, `request.entity`, and `destination: {"name":"...","version":"v1"}`.
 Do not assume that an existing destination profile is bound to any schedule.
+For clustering schedules only, `request.include_inputs: true` asks Serving to
+echo the model input row it used; each row then carries `inputs` (column name
+to value, before the model's own transform), e.g. `{"source": "inputs.seg6"}`.
+Rollout order: deploy the Serving runtime that supports the echo and repackage
+(then redeploy) the model with it *before* creating or updating a schedule to
+`include_inputs: true`. An older runtime silently ignores the field, so every
+run fails with `prediction_contract_mismatch` and nothing is sent; if that
+happens, set `include_inputs` back to `false` or finish the repackage first.
 
 ```bash
 ml-platform --profile server create-prediction-report-schedule SCHEDULE_JSON
@@ -116,6 +139,18 @@ revision, destination name/version, next run time, latest run status, and
 redacted error code. Do not claim delivery succeeded based only on validation
 or schedule creation.
 
+## Watch runs
+
+The platform does not send notifications today. A `FAILED` or `SKIPPED` run
+is visible only in the run list. When the API was down over several scheduled
+times, only the latest overdue time gets a run; the earlier ones leave no run
+at all, so look for gaps in `scheduled_at`. No CLI command reruns an earlier
+cutoff. Before enabling a schedule, tell the user this and ask them to name a
+person who will check `list-prediction-report-runs SCHEDULE_ID` after each
+scheduled time, and to agree with the destination owner what happens for a
+cutoff that was not delivered. Record that owner in your report. Do not describe the schedule as
+monitored, and do not promise that failures will be reported automatically.
+
 At completion, offer a next step only when it fits the observed state: after a
 profile is created, optionally bind it to a schedule for a suitable deployment;
 after a disabled schedule is verified, optionally resume it with explicit