Why
views-frames is the platform's leaf data-contract package — numpy-only, frozen at v1.0.0 (ADR-018). views-postprocessing volunteered to be the first live conformance consumer (round-02 review: "convert the proxy into a live proof and stress the contract against a real workload … the single highest-value next milestone"). Doing so makes postprocessing the first real cross-repo proof that the frozen contract holds against a production workload.
Authored from the views-frames side as a context-rich, solution-open brief. Approaches are proposals, not prescriptions.
⚠️ Honest scoping: what postprocessing actually does today
The postprocessing perspective spoke aspirationally about "emitting prediction frames" and using cross_level_align for "pg→country FAO aggregation." The current repo is narrower than that, and the issues reflect the reality:
- It works on point-estimate
pd.DataFrames (no posterior/sample axis), wrapped in pipeline-core's PGMDataset (unfao/managers/unfao.py:7). It imports no views_frames.
- Its "GAUL enrichment" (
unfao/enrichment.py, unfao/gaul_schema.py METADATA_COLS) is a per-cell merge of 9 string metadata columns (country_iso_a3, admin1_gaul1_name, …) — not a cross-level aggregation.
- It computes no HDI/MAP/quantiles and does no sample aggregation.
So postprocessing's honest adoption is two consumer moves: ingest predictions as a views_frames.PredictionFrame, and run conformance. (Point estimates → a (N, 1) frame — sample axis size 1.)
Scope
✅ In: ingest predictions as a PredictionFrame (#28); conformance as the first live consumer (#29). Add the views-frames dependency.
❌ OUT / FUTURE (noted, not filed):
- GAUL enrichment stays in postprocessing — it is domain logic. The leaf explicitly excludes the GAUL hierarchy (views-frames ADR-001: "Must not contain … the GAUL hierarchy"). Adoption does not touch the 9-column enrichment, and the leaf has no
SpatialLevel for admin L1/L2 (only cm/pgm). Also note: the enriched FAO output is a DataFrame with string columns, which a float32 PredictionFrame cannot carry — so conformance validates the ingested predictions (input), not the enriched output.
- Summarizers (HDI/MAP/quantiles),
cross_level_align, aggregate_distributions — not used today. Relevant only if postprocessing later moves to sample-bearing predictions and aggregates pg→admin/country with uncertainty — then the leaf's conservation-correct aggregate_distributions (joint sampling, HDI(sum) ≠ sum(HDI)) is the right path. Forward-looking, not a child here.
- Provenance / C-48 (
run_id/data_version) — not in v1.0.0's FrameMetadata (model/run_type/timestamp/seed only); a future MINOR + a cross-repo decision.
⚠️ Open mechanics — how is views-frames installed?
views-frames is built with uv/hatchling and lives on GitHub; not confirmed to be on PyPI / a private index. postprocessing is Poetry, so it needs views-frames installable — PyPI / private index / git dep (views-frames = { git = "…", tag = "v1.0.0" }). Resolve first (same prerequisite across all the adopting repos).
Toolchain note
postprocessing is Poetry (v0.1.0, Python >=3.11,<3.15), pytest-only CI; deps are just views-pipeline-core>=2.1.3,<3.0.0 + cachetools. The leaf needs Python ≥3.10 (compatible).
Children (sequence: #28 → #29)
References (views-frames @ v1.0.0)
🤖 Filed by the views-frames maintainer agent (issues only; no postprocessing code touched).
Why
views-framesis the platform's leaf data-contract package — numpy-only, frozen at v1.0.0 (ADR-018). views-postprocessing volunteered to be the first live conformance consumer (round-02 review: "convert the proxy into a live proof and stress the contract against a real workload … the single highest-value next milestone"). Doing so makes postprocessing the first real cross-repo proof that the frozen contract holds against a production workload.The postprocessing perspective spoke aspirationally about "emitting prediction frames" and using
cross_level_alignfor "pg→country FAO aggregation." The current repo is narrower than that, and the issues reflect the reality:pd.DataFrames (no posterior/sample axis), wrapped in pipeline-core'sPGMDataset(unfao/managers/unfao.py:7). It imports noviews_frames.unfao/enrichment.py,unfao/gaul_schema.pyMETADATA_COLS) is a per-cell merge of 9 string metadata columns (country_iso_a3,admin1_gaul1_name, …) — not a cross-level aggregation.So postprocessing's honest adoption is two consumer moves: ingest predictions as a
views_frames.PredictionFrame, and run conformance. (Point estimates → a(N, 1)frame — sample axis size 1.)Scope
✅ In: ingest predictions as a
PredictionFrame(#28); conformance as the first live consumer (#29). Add theviews-framesdependency.❌ OUT / FUTURE (noted, not filed):
SpatialLevelfor admin L1/L2 (onlycm/pgm). Also note: the enriched FAO output is a DataFrame with string columns, which a float32PredictionFramecannot carry — so conformance validates the ingested predictions (input), not the enriched output.cross_level_align,aggregate_distributions— not used today. Relevant only if postprocessing later moves to sample-bearing predictions and aggregates pg→admin/country with uncertainty — then the leaf's conservation-correctaggregate_distributions(joint sampling,HDI(sum) ≠ sum(HDI)) is the right path. Forward-looking, not a child here.run_id/data_version) — not in v1.0.0'sFrameMetadata(model/run_type/timestamp/seedonly); a future MINOR + a cross-repo decision.views-frames is built with uv/hatchling and lives on GitHub; not confirmed to be on PyPI / a private index. postprocessing is Poetry, so it needs views-frames installable — PyPI / private index / git dep (
views-frames = { git = "…", tag = "v1.0.0" }). Resolve first (same prerequisite across all the adopting repos).Toolchain note
postprocessing is Poetry (v0.1.0, Python
>=3.11,<3.15), pytest-only CI; deps are justviews-pipeline-core>=2.1.3,<3.0.0+cachetools. The leaf needs Python ≥3.10 (compatible).Children (sequence: #28 → #29)
views_frames.PredictionFrame(drop the privatePGMDatasetdependency). Cross-repo dep: pipeline-core #188 (the upstream re-export shim).assert_frame_contractin CI)References (views-frames @ v1.0.0)
PredictionFrame: https://github.com/views-platform/views-frames/blob/main/src/views_frames/prediction_frame.py🤖 Filed by the views-frames maintainer agent (issues only; no postprocessing code touched).