Model/domain/epc_prediction/epc_prediction.py

"""EPC Prediction synthesis (ADR-0029).

`EpcPrediction.predict` turns the selected `ComparableProperties` into a
predicted `EpcPropertyData`: copy a coherent representative template's structure
(building parts, windows, geometry), set the homogeneous categoricals to the
recency-weighted cohort mode, then apply Landlord Overrides on top. Pure domain
logic — deterministic neighbour synthesis, not ML.
"""

from __future__ import annotations

import copy
import statistics
from collections import Counter
from typing import Iterable, Optional, Union

from datatypes.epc.domain.epc_property_data import (
    EpcPropertyData,
    SapBuildingPart,
)
from domain.epc_prediction.comparable_properties import (
    Comparable,
    ComparableProperties,
    PredictionTarget,
)


class EpcPrediction:
    """Synthesises a predicted `EpcPropertyData` from Comparable Properties."""

    def predict(
        self, target: PredictionTarget, comparables: ComparableProperties
    ) -> EpcPropertyData:
        """Predict the target's EPC picture: copy a representative template's
        structure (coherent for the calculator), then set the homogeneous
        categoricals to the cohort mode."""
        template: Comparable = self._template(comparables)
        predicted: EpcPropertyData = copy.deepcopy(template.epc)
        self._apply_categorical_modes(predicted, comparables)
        self._apply_overrides(predicted, target)
        return predicted

    @staticmethod
    def _template(comparables: ComparableProperties) -> Comparable:
        """The representative comparable whose structure seeds the prediction:
        the member whose floor area is closest to the cohort median. A single
        neighbour's geometry is copied wholesale, so a size-representative
        template keeps the prediction off the cohort's size outliers (ADR-0029
        decision 4: closest on size)."""
        members: tuple[Comparable, ...] = comparables.members
        median_area: float = statistics.median(
            c.epc.total_floor_area_m2 for c in members
        )
        return min(
            members,
            key=lambda c: abs(c.epc.total_floor_area_m2 - median_area),
        )

    @staticmethod
    def _apply_categorical_modes(
        predicted: EpcPropertyData, comparables: ComparableProperties
    ) -> None:
        """Override the predicted picture's homogeneous categoricals — wall /
        roof / floor construction, wall insulation, age band — with the cohort
        mode (robust to an atypical template, per ADR-0029 decision 4). The
        template still supplies the geometry; only the categorical codes move to
        the mode."""
        if not predicted.sap_building_parts:
            return
        main: SapBuildingPart = predicted.sap_building_parts[0]
        members = comparables.members
        for attr in _MAIN_PART_CATEGORICALS:
            mode = _mode(_main_part_attr(c, attr) for c in members)
            if mode is not None:
                setattr(main, attr, mode)
        floor_values: list[int] = [
            v for c in members if (v := _main_floor_construction(c)) is not None
        ]
        floor_dims = main.sap_floor_dimensions
        if floor_values and floor_dims:
            floor_dims[0].floor_construction = Counter(floor_values).most_common(
                1
            )[0][0]

    @staticmethod
    def _apply_overrides(
        predicted: EpcPropertyData, target: PredictionTarget
    ) -> None:
        """Apply the known Landlord Overrides on top of the estimate — a known
        value always wins over the cohort mode (ADR-0029)."""
        if not predicted.sap_building_parts:
            return
        if target.wall_construction is not None:
            predicted.sap_building_parts[0].wall_construction = (
                target.wall_construction
            )


# The homogeneous categoricals carried directly on the main building part. Floor
# construction lives on the main floor dimension and is handled separately.
_MAIN_PART_CATEGORICALS: tuple[str, ...] = (
    "wall_construction",
    "wall_insulation_type",
    "construction_age_band",
    "roof_construction",
)


def _main_part_attr(
    comparable: Comparable, attr: str
) -> Optional[Union[int, str]]:
    parts: list[SapBuildingPart] = comparable.epc.sap_building_parts
    return getattr(parts[0], attr) if parts else None


def _main_floor_construction(comparable: Comparable) -> Optional[int]:
    parts: list[SapBuildingPart] = comparable.epc.sap_building_parts
    if not parts:
        return None
    dims = parts[0].sap_floor_dimensions
    return dims[0].floor_construction if dims else None


def _mode(
    values: Iterable[Optional[Union[int, str]]],
) -> Optional[Union[int, str]]:
    """The most common non-None value, or None when there are none."""
    present = [v for v in values if v is not None]
    if not present:
        return None
    return Counter(present).most_common(1)[0][0]