@zhuoyuezs/ml-platform 0.1.3 → 0.1.5

package/skills/feature-management/assets/catalog-template/operators/example_temperature_features.v1.json

@@ -1,5 +1,6 @@
 {
   "schema_version": "ml_data_platform.operator/v1",
+  "project": "replace_with_project",
   "name": "example_temperature_features",
   "version": "v1",
   "type": "feature",
@@ -10,7 +11,21 @@
   "code_artifact": null,
   "input_schema": {
     "parameters": [
-      "example_temperature:v1"
+      "replace_with_project/example_temperature:v1"
+    ],
+    "prediction": {
+      "required": true,
+      "minimum_horizon": "0min",
+      "maximum_horizon": "0min"
+    },
+    "history_requirements": [
+      {
+        "anchor": "cutoff",
+        "lookback": "5min",
+        "output_columns": [
+          "example_temperature_mean_5m"
+        ]
+      }
     ]
   },
   "output_schema": {

package/skills/feature-management/assets/catalog-template/parameters/example_temperature.v1.json

@@ -1,5 +1,6 @@
 {
   "schema_version": "ml_data_platform.parameter/v1",
+  "project": "replace_with_project",
   "name": "example_temperature",
   "display_name": "Example temperature",
   "version": "v1",

package/skills/feature-management/references/commands.md

@@ -49,6 +49,15 @@ ml-platform --profile server list-feature-sets -q <stable-name>
 ml-platform --profile server list-datasets -q <stable-dataset-id>
 ```
 
+Run each command separately. Check `ml-platform --help` and the specific
+subcommand help before adding flags. In the deployed 0.6.x CLI, `list-*`
+commands print JSON by default and do not accept a `--json` flag.
+If a deployed release rejects the global `--profile server` prefix, treat that
+as CLI compatibility drift: record the syntax error, inspect `show-config` and
+the subcommand help, then retry the same read-only command without the rejected
+flag only if the installed help permits it. Do not report this as API/network
+unavailability or switch to a direct HTTP client.
+
 By default each `list-*` command auto-pages through the whole result set and
 prints a **bare JSON array** of every matching item, so it never silently stops
 at the server's default page size. Use `-q` for a case-insensitive identifier
@@ -217,6 +226,17 @@ ml-platform --profile server wait-job <job_id>
 ml-platform --profile server get-job <job_id>
 ```
 
+With explicit user authorization, stop a running build through the server CLI:
+
+```bash
+ml-platform --profile server cancel-job <job_id>
+```
+
+Cancellation is terminal for that Job; it does not change the immutable
+DatasetManifest and it does not automatically resubmit with different
+partition or parallelism settings. Check `get-job` after the request and
+record the returned terminal status.
+
 ## Fetch Realtime Inference Data
 
 Fetch one causal-cutoff row in memory:
@@ -252,6 +272,15 @@ ml-platform --profile server \
 `--project` defaults to `default`; pass the owning project when the dataset lives
 elsewhere, or the lookup returns `artifact_not_found`.
 
+The download command writes progress to stderr after response headers arrive.
+Interpret a timeout with no progress line as a request/header or first-byte
+failure. Interpret a timeout after one or more `artifact download: received ...`
+lines as an incomplete response body. In either case, report the timeout and
+keep downloaded-file validation incomplete; do not replace the supported CLI
+with direct HTTP or object-store access. A successful metadata query remains
+valid metadata-only evidence, but it does not prove Parquet schema, column
+order, or file-content hashes.
+
 Inspect at least:
 
 ```text

package/skills/feature-management/references/contracts.md

@@ -35,6 +35,9 @@ Use this reference for the implemented V1 schemas. Prefer the running CLI and `s
   `project` field in its own JSON spec (it defaults to `default` when omitted).
   So to place an asset in a non-default project, set `"project": "<name>"` in the
   spec before `apply`.
+- For a confirmed non-default target, include that field in every draft
+  Parameter, Operator, Feature, Feature input, FeatureSet, and DatasetManifest;
+  do not rely on Pydantic's `default` fallback during authoring.
 - Reads and filters, by contrast, take the project out-of-band: `list-* --project`
   and the leading project argument of the artifact commands. `apply --project`
   scopes the comparison snapshot that publication is validated against.
@@ -91,6 +94,11 @@ Required shape:
 
 Supported source modes are `direct_column`, `sql`, and `derived`. Prefer `direct_column` for ordinary business parameters.
 
+For `sql`, `source.sql` must contain one statement without a trailing semicolon,
+and named placeholders must be supplied through `source.params`; `start` and
+`end` are reserved runtime window parameters. `source.parameters` is not a
+supported field.
+
 `availability.strategy` 支持 `source_field`、`fixed_delay` 和 `unsupported`。只有一个
 事件时间列时，可以使用经过数据 owner 确认的固定延迟上界，例如
 `{"strategy":"fixed_delay","delay":"PT10M","accuracy":"upper_bound"}`。
@@ -282,6 +290,14 @@ The list must be nonempty, unique, and ordered exactly as consumers expect.
     "horizon": "10min"
   },
   "parameters": [],
+  "parameter_missing_policies": [
+    {
+      "parameter": "hot_blast_pressure",
+      "version": "v1",
+      "project": "default",
+      "policy": "report_only"
+    }
+  ],
   "feature_set": {"name": "pressure_core", "version": "v1"},
   "preprocess": [],
   "output": {
@@ -321,9 +337,13 @@ declared `realtime_fetch` policy contains meaningful defaults and changes the
 manifest hash. Declaring `endpoint_policy` also changes the manifest hash.
 
 Each explicit `parameters` request may set `missing_policy`. A
-`parameter_missing_policies` entry uses the same Parameter `name` and `version`
-but is reserved for Parameters used only through the selected FeatureSet's
-input closure; it must not also appear in `parameters`. The policies are:
+`parameter_missing_policies` entry is reserved for a Parameter used only through
+the selected FeatureSet's input closure; it must not also appear in
+`parameters`. Its exact V1 shape is `{"parameter": "<name>", "version":
+"<version>", "project": "<project>", "policy": "<policy>"}`. Do not use
+the `ParameterRequest` field names `name` or `missing_policy` in this list. For
+a confirmed non-default target, set `project` explicitly instead of relying on
+its `default` fallback. The policies are:
 
 - `report_only`: retain all target rows and report source gaps.
 - `fail_on_requested_range_gap`: fail when a detected gap affects the requested
@@ -424,13 +444,30 @@ near the end of the target range can have its lookback clipped by the range end,
 and a window close to the end can remove most remaining rows.
 
 `target` states which instant the label is aligned to, so reviewing a manifest
-shows the target definition rather than only a Parameter version string.
-`si_time_source` is `weight_time` or `dispatch_time`.
+shows the target definition rather than only a Parameter version string. When
+the target is a Parameter, keep its complete versioned reference **inside**
+`target.parameter`; do not flatten `version` or `project` onto `target`.
+`si_time_source` is `weight_time` or `dispatch_time`. `interpolation` is an
+object with a `method`, never a bare string.
 
 ```json
-"target": {"si_time_source": "weight_time", "offset_minutes": 0}
+"target": {
+  "parameter": {
+    "parameter": "hot_metal_si",
+    "version": "v1",
+    "project": "replace_with_project"
+  },
+  "si_time_source": "weight_time",
+  "offset_minutes": 0,
+  "interpolation": {"method": "linear"}
+}
 ```
 
+Allowed interpolation methods are `none`, `linear`, and `forward_fill`. A
+business phrase such as "allow and report target nulls" belongs in an existing
+Parameter missing policy, Feature configuration, or the semantic review; it is
+not a free-form `target` or DatasetManifest field.
+
 The declaration is checked against the selected Si Parameter, but only for
 `direct_column` reads, which name their time column in the contract. A `sql` or
 `derived` Parameter can apply an offset inside its query text, so those are

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

@@ -67,12 +67,17 @@ 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.
 
-If an Operator requires a forecast contract, declare `input_schema.prediction`
-with `required`, `minimum_horizon`, and `maximum_horizon`. Declare source history
-as `input_schema.history_requirements`, using `anchor: cutoff` for causal windows
-and `anchor: target_time` only for intentional target-aligned formulas. Scope a
-requirement with `output_columns` when only some outputs need it. Include alignment
-slack such as hourly floor boundaries in the declared lookback.
+An Operator requires an explicit forecast contract whenever its formula or code
+uses `context.cutoff_times`, or any `input_schema.history_requirements` entry uses
+`anchor: cutoff`. In that case always declare `input_schema.prediction` with
+`required`, `minimum_horizon`, and `maximum_horizon`. This includes a strict
+nowcast: declare `required=true` and both bounds as `0min`; do not omit the
+section and silently accept the runtime's `default_nowcast` fallback. Declare
+source history as `input_schema.history_requirements`, using `anchor: cutoff`
+for causal windows and `anchor: target_time` only for intentional target-aligned
+formulas. Scope a requirement with `output_columns` when only some outputs need
+it. Include alignment slack such as hourly floor boundaries in the declared
+lookback.
 
 For realtime reads, `history_requirements` is also the per-Parameter fetch
 contract. Do not rely on a package-local lookback map or a single fixed window
@@ -110,7 +115,10 @@ Never infer a rule from a Feature name alone. Require a business decision when a
 
 ## Required Tests
 
-Use deterministic fixtures and cover:
+Use deterministic fixtures and cover each applicable item with a separately
+named test. A broad formula or happy-path test does not substitute for the
+cutoff-before, cutoff-at, cutoff-after, duplicate/missing, empty-history,
+requested-output, event-time-order, or dtype/rounding cases below:
 
 1. expected formula values;
 2. the event immediately before cutoff;

package/skills/feature-management/references/platform-capability-guide.md

@@ -0,0 +1,73 @@
+# Platform Capability Guide
+
+Use this guide to explain what the platform can execute. It is not business
+evidence. A platform default never answers an unresolved business question.
+
+## Platform In One Paragraph
+
+The platform is a versioned data-contract, registry, execution, and delivery
+layer for algorithm projects. It turns confirmed source Parameters and approved
+deterministic Operators into ordered Features and reproducible DatasetManifests,
+then either materializes a batch DatasetArtifact or serves one causal realtime
+read. It owns source adapters, quality/missingness/freshness evidence, lineage,
+replay metadata, and Job execution; it does not own model training, model
+evaluation, model serving, source-table creation, or Kubernetes administration.
+
+The following distinctions are part of the platform contract:
+
+- A `Parameter` is a public source-data contract, not an arbitrary raw table or
+  a model feature.
+- An `Operator` is versioned executable code; a `Feature` is exactly one output
+  column; a `FeatureSet` is the consumer-visible column order.
+- A `DatasetManifest` is a versioned request for time range, read policy,
+  rowsets, missing/endpoint rules, prediction, and one FeatureSet.
+- A `DatasetArtifact` is an output of an authorized build, not evidence that the
+  source contract or business formula was semantically approved.
+- Realtime inference is a causal cutoff read. It must not run a batch build,
+  write Parquet, or publish a DatasetArtifact.
+
+Dry-run and registry resolution are structural evidence. They may not detect a
+missing source relation; source-backed success must be established by the build
+or realtime fetch response. Artifact metadata is separate from downloaded-file
+evidence: schema, column order, file hashes, and numeric parity require the
+complete files.
+
+## Public Assets
+
+| Asset | Stores | Use when | Do not use for |
+|---|---|---|---|
+| Project | Namespace and isolation boundary | Every independent business release | A dataset version or a source table |
+| Parameter | One readable source contract and its quality/time semantics | Raw or independently readable source values/events | Rolling means, ratios, trends, model columns |
+| Operator | Versioned deterministic executable code | A formula needs computation over declared inputs | A business definition without confirmed formula |
+| Feature | One immutable output-column contract | One model/input column produced by an Operator | A group of columns or an unnamed formula |
+| FeatureSet | Ordered Feature references | Consumer column order is part of the contract | Copying formulas or creating multiple datasets |
+| DatasetManifest | Dataset mode, time grid, rowsets, policy and FeatureSet reference | A reproducible dataset contract is ready | Filling unknown source or business semantics |
+| DatasetArtifact | Output of an authorized build | Build was explicitly approved and completed | Proving a Catalog is semantically correct |
+
+## Decision Rules
+
+- Parameter answers **what source value is exposed**; Operator/Feature answers
+  **how a confirmed business formula is computed**.
+- FeatureSet order is consumer-facing and must be confirmed; it is not inferred
+  from filesystem order or JSON discovery order.
+- Dataset `time_range`, `prediction`, `rowset_splits`, `abnormal_windows` and
+  `endpoint_policy` are separate contracts. A platform default does not choose
+  a business policy.
+- `apply --dry-run` checks structure, references, package and immutability. It
+  does not prove source correctness, formula correctness or artifact parity.
+- `publish` creates immutable Registry resources. `build` creates an execution
+  Job and must have a separate explicit approval.
+
+## Required Semantic Asset Review
+
+Before writing Catalog JSON, produce a local review table with one row per
+Parameter, Operator, Feature and Dataset field:
+
+```text
+asset_key | business_meaning | source/evidence | confirmed_by | unresolved | proposed_value
+```
+
+Stop before Catalog generation if any required `source/evidence`, formula,
+time boundary, unit, null policy, output dtype, FeatureSet order, read policy,
+or approval field is unresolved. The review table is a proposal for the user;
+it is not a Registry asset and must not contain guessed values.