Add a build_prediction_frame(y_pred, time, unit, level) factory to the leaf

[Polichinel]

Driver: the views-frames adoption across the platform (views-pipeline-core #188 → 3.0.0; engine repos views-hydranet/views-baseline migrating their PF construction). An expert-code-review concluded that a frame-construction convenience belongs in the leaf (where the type lives), NOT re-published from a consumer package like pipeline-core. This issue is that leaf-side factory.

What

A thin convenience constructor that returns a real PredictionFrame so callers don't have to build the SpatioTemporalIndex themselves:

def build_prediction_frame(y_pred, time, unit, level: SpatialLevel,
                           metadata: FrameMetadata | None = None) -> PredictionFrame:
    index = SpatioTemporalIndex(time=..., unit=..., level=level)
    return PredictionFrame(y_pred, index, metadata)

(Exact signature/dtype-coercion is the maintainer's call — match the leaf's existing validation conventions.)

Why in the leaf, not pipeline-core

• It's frame-construction knowledge → it belongs with the frame (single-homed contract; no forked construction API across packages).
• Engines then bind their construction to the API-frozen leaf (most stable node), not to pipeline-core's faster release cadence.
• It retires the duplicated local build_prediction_frame in views-baseline (views_baseline/model/helpers.py:110).

Notes / scope

• API-frozen (ADR-018): this is an additive convenience (new public function), so a minor release suffices; no break.
• Optional/lower-priority: engines can migrate today by constructing SpatioTemporalIndex directly (the hydranet/baseline issues do this). This factory just shrinks those call sites to one line once released.

DoD

from views_frames import build_prediction_frame returns a conformant PredictionFrame; covered by the leaf's own tests; released so engines + views-baseline can adopt it.

[Polichinel]

Decision (ratified with the views-frames owner + pipeline-core owner)

Ship as Option B — a classmethod, not a free function. @classmethod PredictionFrame.from_arrays(y_pred, *, time, unit, level, metadata=None) -> PredictionFrame:

• matches the leaf's only construction-helper convention (FeatureFrame.from_2d, *.load), single-homes construction (SRP/CCP), and is the smaller addition to the frozen surface;
• singular (PredictionFrame only — defer Feature/Target until a second consumer needs it; CRP + ADR-011);
• zero own logic — body delegates to SpatioTemporalIndex(...) + __init__, so future identifiers (ADR-013) flow through automatically;
• keyword-only time/unit/level; lives in prediction_frame.py (no factory.py); no free-function alias (every consumer already imports PredictionFrame, so the classmethod is strictly fewer symbols).

Additive/MINOR; CONFORMANCE_FLOOR stays 1.0.0. Tracked in the views-frames risk register: C-52 (accretion/camel's-nose), C-53 (two frozen construction paths), C-54 (this DoD scope), D-09 (the free-fn-vs-classmethod resolution).

DoD correction

This issue said it "retires baseline's local build_prediction_frame." That overstates it: baseline's helper is a domain grid-builder (loops value_fn over entity×time → dict[str, PredictionFrame]) — a consumer edge (ADR-001) that must stay in views-baseline. from_arrays retires only its innermost SpatioTemporalIndex + PredictionFrame construction line.

Priority / sequencing — does NOT block the engine migration

from_arrays is a low-priority ergonomic nicety (the panel's own regret test: "Low regret to not ship"). It must not gate the urgent engine fixes (views-hydranet#137 / views-baseline#21). Those ship now via direct construction against the already-frozen API — no new leaf release needed:

PredictionFrame(y_pred, SpatioTemporalIndex(time=…, unit=…, level=…), metadata)

Engines should centralize that to a single local line so the later switch to from_arrays is a one-line swap (no re-migration). from_arrays lands as a later v1.x MINOR once the break is handled.

[Polichinel]

Heads-up for whoever picks this up: the construction-factory shape was ratified afterward as D-09 in the technical risk register — ship it as a classmethod PredictionFrame.from_arrays, not the free function build_prediction_frame sketched above, with the C-52/C-53/C-54 guards:

• zero own logic — pure delegation to SpatioTemporalIndex(time, unit, level) + PredictionFrame(values, index, metadata), so a future index identifier flows through automatically;
• a CIC "Construction" non-goal fencing out grid / value_fn / inference / adapters (ADR-001 accretion guard).

C-52/C-53/C-54 are "Resolved when from_arrays lands with those guards, or closed if #113 is declined." Still additive (ADR-018 → minor); engines can construct the index directly today, so this stays a convenience, not a blocker.