@zhuoyuezs/ml-platform 0.1.0

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

@@ -0,0 +1,167 @@
+# Operator Authoring
+
+Read this file whenever a workflow creates or changes executable Operator code.
+
+## Contents
+
+1. Package contract
+2. Feature entrypoint contract
+3. Causal calculation rules
+4. Required tests
+5. Build and publication
+6. 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`.
+
+Minimal `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pressure-features"
+version = "1.0.0"
+requires-python = ">=3.10"
+dependencies = ["pandas>=2.3.3"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pressure_features"]
+```
+
+Keep package version and Operator Registry version independently explicit. Change both when code behavior changes unless a documented release policy maps them differently.
+
+## Feature Entrypoint Contract
+
+Implement:
+
+```python
+def compute_features(context: Any) -> pandas.DataFrame:
+    ...
+```
+
+Available context fields:
+
+```text
+manifest
+features
+inputs
+config
+requested_output_columns
+operator
+parameters
+metric_frames
+target_times
+prediction_horizon
+cutoff_times
+furnace_id
+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.
+
+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.
+
+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
+shared by all inputs. The realtime runner widens a half-open adapter read by one
+grid step, then applies `timestamp <= cutoff`; an Operator must never consume a
+post-cutoff row.
+
+Return requirements:
+
+- Return a pandas DataFrame.
+- Return exactly one row per `context.target_times` entry.
+- Return `event_time` in the same order and with the same timestamps.
+- Optionally return `furnace_id`.
+- Return every requested physical output column.
+- Avoid calculating unrequested expensive columns when practical.
+- Reject unknown requested output columns.
+- Preserve numeric missing values rather than silently filling them without a declared rule.
+
+One Operator may return multiple physical columns. Each public Feature still binds one `output_column` and exact inputs.
+
+## Causal Calculation Rules
+
+State every time rule in tests and descriptions:
+
+- forecast horizon and cutoff derivation;
+- whether an event exactly at cutoff is included (`<=`) or excluded (`<`);
+- rolling window left/right closure;
+- timezone and daylight-saving assumptions;
+- duplicate timestamp resolution;
+- sparse-event fallback behavior;
+- rounding stage and decimal count;
+- behavior before and after dated business-rule changes.
+
+Never infer a rule from a Feature name alone. Require a business decision when a boundary is unspecified.
+
+## Required Tests
+
+Use deterministic fixtures and cover:
+
+1. expected formula values;
+2. the event immediately before cutoff;
+3. an event exactly at cutoff;
+4. an event immediately after cutoff;
+5. missing and duplicate inputs;
+6. empty history or insufficient lookback;
+7. requested output subsets;
+8. exact `event_time` row count and order;
+9. output dtype and rounding;
+10. every dated business-rule branch.
+
+Run package tests before building the wheel. Then inspect the wheel tag and ensure it is `py3-none-any`.
+
+## Build And Publication
+
+Build into the catalog path referenced by `catalog.json`:
+
+```bash
+uv build <catalog>/operator_package \
+  --wheel \
+  --out-dir <catalog>/operator_package/dist
+```
+
+Keep the draft Operator fields null:
+
+```json
+{
+  "code_hash": null,
+  "package_uri": null,
+  "code_artifact": null
+}
+```
+
+Catalog publication uploads the wheel, computes SHA-256 and size, records its immutable object URI, and registers the resolved OperatorSpec.
+
+Do not reuse an Operator version with a different wheel. If the same key already exists with different content or digest, create a new version.
+
+## Security Boundary
+
+The current runtime blocks socket networking, removes storage/source credentials from the child environment, verifies the wheel hash, enforces a timeout, and extracts only pure-Python wheels without native libraries or unsafe paths.
+
+This is not a complete OS sandbox. Therefore:
+
+- publish only reviewed internal code;
+- do not read arbitrary host paths;
+- do not spawn subprocesses;
+- do not access secrets or environment configuration;
+- do not use dynamic code evaluation;
+- do not add native libraries;
+- do not perform network calls;
+- keep resource limits conservative.
+
+Request an engineering/security review when the formula requires capabilities outside this boundary.