chore: added mermaid and updated weights (#2552)

* chore: added mermaid and updated weights

* chore: updated docs

---------

Co-authored-by: Mirco Rudolph <mirco@openearth.org>

Author: mircorudolph

hiap-meed/README.md

@@ -188,7 +188,7 @@ Impact block behavior (implemented):
   - The service sums activity emissions per GPC key before scoring.
 - Impact computes canonical score as:
   - `0.80 * reduction_share_of_city_emissions + 0.20 * timeline_score`
-  - Timeline mapping: `<5 years -> 1.0`, `5-10 years -> 0.5`, `>10 years -> 0.0`
+  - Timeline mapping: `<5 years -> 1.0`, `5-10 years -> 0.5`, `>10 years -> 0.0`, missing or unknown timeline `-> 0.5`
 - Unknown `impact_text` values are rejected with `422` (raised during Impact scoring and surfaced by the API error handler).
 
 Alignment block behavior (implemented):

hiap-meed/app/modules/prioritizer/blocks/alignment.py

@@ -167,6 +167,15 @@ def _co_benefit_effect_label(impact_numeric: float | None, *, present: bool) ->
     return "neutral"
 
 
+def _co_benefit_score_source(impact_numeric: float | None, *, present: bool) -> str:
+    """Explain whether the normalized score came from a real value or a missing fallback."""
+    if not present:
+        return "missing_co_benefit"
+    if impact_numeric is None:
+        return "missing_impact_numeric"
+    return "derived_from_value"
+
+
 def _build_selected_co_benefit_match_details(
     *,
     action_co_benefits: dict[str, dict[str, object]],
@@ -196,7 +205,11 @@ def _build_selected_co_benefit_match_details(
                 "normalized_preference_score": (
                     _normalized_co_benefit_score(impact_numeric)
                     if impact_numeric is not None
-                    else 0.0
+                    else 0.5
+                ),
+                "score_source": _co_benefit_score_source(
+                    impact_numeric,
+                    present=benefit is not None,
                 ),
                 "effect_label": _co_benefit_effect_label(
                     impact_numeric,

hiap-meed/app/modules/prioritizer/config.py

@@ -27,7 +27,7 @@
     "very high": 1.0,
 }
 
-IMPACT_DEFAULT_TIMELINE_SCORE = 0.0
+IMPACT_DEFAULT_TIMELINE_SCORE = 0.5
 
 IMPACT_TIMELINE_TO_SCORE: dict[str, float] = {
     "<5 years": 1.0,

hiap-meed/docs/pipeline-description.md

@@ -577,7 +577,7 @@ Timeline mapping:
 - `<5 years` -> `1.0`
 - `5-10 years` -> `0.5`
 - `>10 years` -> `0.0`
-- missing or unknown timeline -> `0.0`
+- missing or unknown timeline -> `0.5`
 
 Meaning:
 

hiap-meed/docs/scoring-weights-overview.md

@@ -0,0 +1,151 @@
+# Scoring Weights Overview
+
+This diagram summarizes the scoring weights currently implemented in the `hiap-meed` prioritization pipeline.
+
+```mermaid
+%%{init: {"flowchart": {"nodeSpacing": 38, "rankSpacing": 48, "curve": "basis"}, "themeVariables": {"lineColor": "#7a7a7a"}} }%%
+flowchart TD
+    FS["Final Score"]
+    FS -->|0.55| IMP["Impact Pillar"]
+    FS -->|0.22| ALN["Alignment Pillar"]
+    FS -->|0.23| FEA["Feasibility Pillar"]
+
+    IMP -->|0.80| IMP_RED["Emissions Reduction Share of City Total"]
+    IMP -->|0.20| IMP_TIME["Timeline Component"]
+
+    IMP_TIME -->|1.0| IMP_T_SHORT["<5 years"]
+    IMP_TIME -->|0.5| IMP_T_MED["5-10 years"]
+    IMP_TIME -->|0.0| IMP_T_LONG[">10 years"]
+    IMP_TIME -->|0.5| IMP_T_UNKNOWN["Missing / Unknown timeline"]
+
+    IMP_RED --> IMP_BAND["Impact Text Multiplier"]
+    IMP_BAND -->|0.2| BAND_VLOW["very low"]
+    IMP_BAND -->|0.4| BAND_LOW["low"]
+    IMP_BAND -->|0.6| BAND_MED["medium"]
+    IMP_BAND -->|0.8| BAND_HIGH["high"]
+    IMP_BAND -->|1.0| BAND_VHIGH["very high"]
+
+    ALN -->|0.75| ALN_POL["Policy Component"]
+    ALN -->|0.15| ALN_SEC["Sector Match Component"]
+    ALN -->|0.05| ALN_COB["Co-benefit Preference Component"]
+    ALN -->|0.05| ALN_TIME["Timeframe Preference Component"]
+
+    ALN_POL -->|direct 0..1 input| POL_SCORE["policy_support_score"]
+    POL_SCORE -->|fallback 0.0| POL_MISS["Missing policy score"]
+
+    ALN_SEC -->|1.0| SEC_MATCH["Sector overlap with city preference"]
+    ALN_SEC -->|0.0| SEC_NO["No sector overlap"]
+
+    ALN_COB -->|normalize from -2..2 to 0..1| COB_NORM["Selected co-benefit impacts"]
+    COB_NORM -->|0.0| COB_HARM["Most harmful aggregate"]
+    COB_NORM -->|0.5| COB_NEUT["Neutral aggregate"]
+    COB_NORM -->|1.0| COB_POS["Most beneficial aggregate"]
+    ALN_COB -->|0.5| COB_NONE["No co-benefits selected"]
+
+    ALN_TIME -->|1.0| ALN_TIME_EXACT["Exact timeframe match"]
+    ALN_TIME -->|0.5| ALN_TIME_ADJ["Adjacent match"]
+    ALN_TIME -->|0.0| ALN_TIME_FAR["Far mismatch"]
+    ALN_TIME -->|0.5| ALN_TIME_NOPREF["no_preference / no supported preference"]
+    ALN_TIME -->|0.5| ALN_TIME_UNKNOWN["Missing / Unknown action timeline"]
+
+    FEA -->|0.50| FEA_LEG["Soft Legal Component"]
+    FEA -->|0.50| FEA_SOC["Socioeconomic Component"]
+
+    FEA_LEG -->|aligned_soft / total_soft| LEG_RATIO["Recommended + Optional requirements only"]
+    LEG_RATIO -->|0.0 fallback| LEG_NONE["No soft legal requirements"]
+
+    FEA_SOC -->|normalize from -2..2 to 0..1| SOC_NORM["Weighted socioeconomic average"]
+    SOC_NORM -->|bucket -2| SOC_VLOW["very_low"]
+    SOC_NORM -->|bucket -1| SOC_LOW["low"]
+    SOC_NORM -->|bucket 0| SOC_MED["medium"]
+    SOC_NORM -->|bucket 1| SOC_HIGH["high"]
+    SOC_NORM -->|bucket 2| SOC_VHIGH["very_high"]
+    FEA_SOC -->|missing city indicator -> raw 0| SOC_MISS["Missing city indicator contributes 0 before normalization"]
+    FEA_SOC -->|0.5 fallback| SOC_NONE["No socioeconomic rules on action"]
+
+    linkStyle 0,1,2 stroke-width:4px
+    linkStyle 3,4,16,17 stroke-width:3px
+    linkStyle 18,19,20,21,27,28 stroke-width:2.5px
+```
+
+## Notes
+
+- `0.5` is not universally neutral across all components.
+- `0.5` is a true neutral midpoint only for components normalized from a signed scale such as `-2..2`.
+- Timeline is scored differently in Impact and Alignment:
+  - Impact uses intrinsic speed scoring.
+  - Alignment uses match-to-city-preference scoring.
+
+## Weight Intuition
+
+These examples use the current default final weights:
+
+- Impact = `0.55`
+- Alignment = `0.22`
+- Feasibility = `0.23`
+
+### Top-level pillars
+
+- A `+0.10` change in Impact changes the final score by `+0.055`
+- A `+0.10` change in Alignment changes the final score by `+0.022`
+- A `+0.10` change in Feasibility changes the final score by `+0.023`
+
+This means Impact is a bit more than twice as influential as Alignment or Feasibility in the final ranking.
+
+### Impact examples
+
+- Impact timeline has internal weight `0.20`, so a full `1.0` swing inside that component changes:
+  - Impact score by `0.20`
+  - Final score by `0.55 * 0.20 = 0.11`
+
+- Example: changing Impact timeline from missing/unknown `0.5` to short `<5 years = 1.0`
+  - Impact score change = `+0.10`
+  - Final score change = `+0.055`
+
+- Example: changing Impact timeline from long `0.0` to short `1.0`
+  - Impact score change = `+0.20`
+  - Final score change = `+0.11`
+
+- Impact emissions reduction share has internal weight `0.80`, so a `+0.10` change there changes:
+  - Impact score by `+0.08`
+  - Final score by `0.55 * 0.08 = 0.044`
+
+### Alignment examples
+
+- Policy support has internal weight `0.75`, so a `+0.10` change in `policy_support_score` changes:
+  - Alignment score by `+0.075`
+  - Final score by `0.22 * 0.075 = 0.0165`
+
+- Sector match is binary with internal weight `0.15`
+  - no match `0.0` -> match `1.0`
+  - Alignment score change = `+0.15`
+  - Final score change = `0.22 * 0.15 = 0.033`
+
+- Timeframe preference has internal weight `0.05`
+  - far mismatch `0.0` -> exact match `1.0`
+  - Alignment score change = `+0.05`
+  - Final score change = `0.22 * 0.05 = 0.011`
+
+- Co-benefit preference also has internal weight `0.05`
+  - harmful aggregate `0.0` -> beneficial aggregate `1.0`
+  - Alignment score change = `+0.05`
+  - Final score change = `0.011`
+
+### Feasibility examples
+
+- Soft legal has internal weight `0.50`
+  - `0.0` -> `1.0`
+  - Feasibility score change = `+0.50`
+  - Final score change = `0.23 * 0.50 = 0.115`
+
+- Socioeconomic fit also has internal weight `0.50`
+  - `0.5` neutral -> `1.0` very supportive
+  - Feasibility score change = `+0.25`
+  - Final score change = `0.23 * 0.25 = 0.0575`
+
+### Quick reading guide
+
+- The biggest single driver in the current setup is usually Impact.
+- Inside Alignment, Policy support dominates the other Alignment subcomponents.
+- Alignment timeframe matters, but its effect on the final score is small relative to Impact timeline.
+- Missing Impact timeline is now neutral at `0.5`, so it no longer penalizes actions just because the timeline is unknown.

hiap-meed/tests/unit/test_prioritizer_blocks.py

@@ -304,6 +304,30 @@ def test_impact_block_timeline_mapping_prefers_faster_implementation() -> None:
     assert result.score_by_action_id["A_fast"] > result.score_by_action_id["A_slow"]
 
 
+@pytest.mark.unit
+def test_impact_block_missing_timeline_is_neutral_not_punitive() -> None:
+    """Missing impact timeline uses the neutral 0.5 fallback score."""
+    result = impact.run(
+        actions=[
+            Action(
+                action_id="A_missing_timeline",
+                action_name="Missing timeline",
+                implementation_timeline=None,
+                emissions={
+                    "gpc_reference_number": ["I.1.1"],
+                    "impact_text": "high",
+                },
+            )
+        ],
+        city_emissions_by_gpc_ref={"I.1.1": 100.0},
+    )
+
+    evidence = result.evidence_by_action_id["A_missing_timeline"]
+    assert evidence["timeline_bucket_known"] is False
+    assert evidence["timeline_component_score"] == pytest.approx(0.5)
+    assert evidence["timeline_score"] == pytest.approx(0.5)
+
+
 @pytest.mark.unit
 def test_alignment_block_with_mock_api_data() -> None:
     """Alignment block computes canonical weighted scores with policy and sectors."""
@@ -381,6 +405,100 @@ def test_alignment_other_preference_component_is_neutral_without_selected_keys()
     assert first_action_evidence["co_benefit_component_score"] == pytest.approx(0.5)
 
 
+@pytest.mark.unit
+def test_alignment_selected_co_benefit_evidence_marks_missing_entry_as_neutral() -> None:
+    """Missing selected co-benefit entries stay neutral in evidence and say why."""
+    result = alignment.run(
+        actions=[
+            Action(
+                action_id="A_missing_key",
+                action_name="Missing key action",
+                co_benefits={},
+            )
+        ],
+        policy_signals_by_action_id={},
+        city_preference_sectors=[],
+        city_preference_timeframes=[],
+        city_preference_co_benefit_keys=["air_quality"],
+    )
+
+    evidence = result.evidence_by_action_id["A_missing_key"]
+    assert evidence["co_benefit_component_score"] == pytest.approx(0.5)
+    assert evidence["matched_preferred_co_benefits"] == []
+    detail = evidence["selected_co_benefit_match_details"][0]
+    assert detail["co_benefit_key"] == "air_quality"
+    assert detail["action_has_co_benefit"] is False
+    assert detail["impact_numeric"] is None
+    assert detail["normalized_preference_score"] == pytest.approx(0.5)
+    assert detail["score_source"] == "missing_co_benefit"
+    assert detail["effect_label"] == "not_provided"
+
+
+@pytest.mark.unit
+def test_alignment_selected_co_benefit_evidence_marks_missing_numeric_as_neutral() -> None:
+    """Missing impact_numeric stays neutral in evidence and is distinct from missing key."""
+    result = alignment.run(
+        actions=[
+            Action(
+                action_id="A_missing_numeric",
+                action_name="Missing numeric action",
+                co_benefits={
+                    "air_quality": {
+                        "impact_text": "unknown",
+                        "impact_relationship": "unknown",
+                    }
+                },
+            )
+        ],
+        policy_signals_by_action_id={},
+        city_preference_sectors=[],
+        city_preference_timeframes=[],
+        city_preference_co_benefit_keys=["air_quality"],
+    )
+
+    evidence = result.evidence_by_action_id["A_missing_numeric"]
+    assert evidence["co_benefit_component_score"] == pytest.approx(0.5)
+    assert evidence["matched_preferred_co_benefits"] == ["air_quality"]
+    detail = evidence["selected_co_benefit_match_details"][0]
+    assert detail["co_benefit_key"] == "air_quality"
+    assert detail["action_has_co_benefit"] is True
+    assert detail["impact_numeric"] is None
+    assert detail["normalized_preference_score"] == pytest.approx(0.5)
+    assert detail["score_source"] == "missing_impact_numeric"
+    assert detail["effect_label"] == "unknown"
+
+
+@pytest.mark.unit
+def test_alignment_selected_co_benefit_evidence_marks_real_value_source() -> None:
+    """Known co-benefit values keep their normalized score and explicit value source."""
+    result = alignment.run(
+        actions=[
+            Action(
+                action_id="A_known_numeric",
+                action_name="Known numeric action",
+                co_benefits={
+                    "air_quality": {
+                        "impact_numeric": 1,
+                        "impact_text": "beneficial",
+                        "impact_relationship": "positive",
+                    }
+                },
+            )
+        ],
+        policy_signals_by_action_id={},
+        city_preference_sectors=[],
+        city_preference_timeframes=[],
+        city_preference_co_benefit_keys=["air_quality"],
+    )
+
+    detail = result.evidence_by_action_id["A_known_numeric"][
+        "selected_co_benefit_match_details"
+    ][0]
+    assert detail["normalized_preference_score"] == pytest.approx(0.75)
+    assert detail["score_source"] == "derived_from_value"
+    assert detail["effect_label"] == "beneficial"
+
+
 @pytest.mark.unit
 @pytest.mark.parametrize(
     ("city_preference_timeframes", "action_timeline", "expected_component_value"),