Source code for energy_data_retrieval.hydro_catalogue.reconcile

"""Apply explicitly reviewed NVE/WRI crosswalks; never discover or fuzzy-merge identities."""

from __future__ import annotations

import json
from copy import deepcopy
from typing import Any

from energy_data_retrieval.pv_catalogue.catalogue import canonical_json


[docs] def enrich_reviewed( existing: dict[str, Any], candidate: dict[str, Any], review: dict[str, Any], *, now: str ) -> dict[str, Any]: """Preserve WRI identity/history and add NVE facts after explicit identity review. Aggregation remains unresolved. Different historical/current capacity ratings are separate observations, not evidence of uprating or a common scope. """ ids = json.loads(existing["external_ids_json"]) nve_ids = json.loads(candidate["external_ids_json"]) if ( review.get("decision") != "reviewed_identity_match" or review["record_id"] != existing["record_id"] or review["nve_id"] != nve_ids.get("nve") or existing["name"] != candidate["name"] or review["name"] != existing["name"] or existing["country_code"] != "NOR" or not 0 <= review["distance_m"] <= 250 ): raise ValueError("Crosswalk identity review does not match inputs") if ids.get("nve") not in {None, review["nve_id"]}: raise ValueError("Conflicting existing NVE identity") row = deepcopy(existing) fs = json.loads(row["field_sources_json"]) evidence = json.loads(row["evidence_json"]) incoming_fs = json.loads(candidate["field_sources_json"]) incoming_evidence = json.loads(candidate["evidence_json"]) for key in ( "status", "status_as_of", "status_date_basis", "installed_capacity_mw", "operational_capacity_mw", "gross_head_m", "design_flow_m3_s", "basin", "owner_names", "operator_names", ): if key not in candidate: continue if ( key in row and row[key] != candidate[key] and key not in {"status", "status_as_of", "status_date_basis"} ): raise ValueError(f"Existing factual value needs conflict review: {key}") row[key] = candidate[key] fs[key] = incoming_fs[key] evidence[key] = incoming_evidence[key] row["sources"] = sorted(set(row["sources"] + candidate["sources"] + [review["source_id"]])) # Historical generation and API normal-period generation retain distinct bases. observations = json.loads(row.get("observations_json") or "[]") for obs in json.loads(candidate.get("observations_json") or "[]"): if obs not in observations: observations.append(obs) combined = { "external_ids_json": canonical_json({**ids, **nve_ids}), "observations_json": canonical_json(observations), } ext = json.loads(row.get("extensions_json") or "{}") ext["nve_registry"] = json.loads(candidate["extensions_json"]) ext["identity_review"] = review ext["capacity_comparison"] = ( "WRI historical and NVE current ratings retained separately; differences are not " "attributed to uprating. Scope unresolved; excluded from capacity sums." ) combined["extensions_json"] = canonical_json(ext) for key, value in combined.items(): row[key] = value fs[key] = row["sources"] evidence[key] = { "locator": review["locator"], "confidence": "high", "unit": None, "normalization": "Explicit reviewed identity; preserve original observations", "original_value": value, } row["field_sources_json"] = canonical_json(fs) row["evidence_json"] = canonical_json(evidence) row["notes"] = ( "NVE identity/lifecycle enriched; historical WRI ratings retained. " "Aggregation scope remains unresolved; not included in current capacity sums." ) if {k: v for k, v in row.items() if k not in {"updated_at", "last_verified_at"}} != { k: v for k, v in existing.items() if k not in {"updated_at", "last_verified_at"} }: row["updated_at"] = now row["last_verified_at"] = now return row