Eli 219 support action r rules (#140)

* Adding tests.

* added include actions flag with some tests

* added in handling for incorrect query key plus tests

* added in default comms routing to the iteration model and a test to prove

* added in actions mapper to the iteration model and a test to prove

* added comms routing to rule model, and started new method test

* added some prettier printing, some more function for new method and more testing of method

* improved testing

* Stubbed out some tests for AC on ticket.

* Fleshed out R rule in test with detail defined in ticket.

* part way through changes

* Fixed failing unit tests.

* returned actions properly and tested

* Added test for cohort label not used for redirect rule.

* refactor test.

* WIP

* WIP - Pydantic AvailableActionMap.

* Revert "WIP - Pydantic AvailableActionMap."

This reverts commit 29c3aeb.

* Patch

* Patch 2

* fixing some of the tests

* fixing the final test

* fleshing out testing scenarios.

* Patch - added tests fixed multiple campaign bug.

* started passing through flag to calc

* Patch - Added tests and fixed some linting.

* started passing through flag to calc

* extra test

* extra test

* Updated cohort_label test for better coverage.

* Patch - Fixed None issue and lint errors and tests.

* JSON formatted.

* Updated JSON file.

* Removed unnecessary =none

---------

Co-authored-by: ayeshalshukri1-nhs <[email protected]>

Author: TOEL2

src/eligibility_signposting_api/config/contants.py

@@ -1 +1,2 @@
 MAGIC_COHORT_LABEL = "elid_all_people"
+RULE_STOP_DEFAULT = False

src/eligibility_signposting_api/model/eligibility.py

@@ -14,6 +14,12 @@
 RuleName = NewType("RuleName", str)
 RuleDescription = NewType("RuleDescription", str)
 
+ActionType = NewType("ActionType", str)
+ActionCode = NewType("ActionCode", str)
+ActionDescription = NewType("ActionDescription", str)
+UrlLink = NewType("UrlLink", str)
+UrlLabel = NewType("UrlLabel", str)
+
 
 class RuleType(StrEnum):
     filter = "F"
@@ -61,13 +67,29 @@ class Reason:
     rule_type: RuleType
     rule_name: RuleName
     rule_description: RuleDescription | None
+    matcher_matched: bool
+
+
+@dataclass
+class SuggestedAction:
+    action_type: ActionType
+    action_code: ActionCode
+    action_description: ActionDescription | None
+    url_link: UrlLink | None
+    url_label: UrlLabel | None
+
+
+@dataclass
+class SuggestedActions:
+    actions: list[SuggestedAction]
 
 
 @dataclass
 class Condition:
     condition_name: ConditionName
     status: Status
     cohort_results: list[CohortGroupResult]
+    actions: SuggestedActions | None = None
 
 
 @dataclass
@@ -82,6 +104,7 @@ class CohortGroupResult:
 class IterationResult:
     status: Status
     cohort_results: list[CohortGroupResult]
+    actions: SuggestedActions | None
 
 
 @dataclass

src/eligibility_signposting_api/model/rules.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import typing
 from collections import Counter
 from datetime import UTC, date, datetime
@@ -8,9 +9,9 @@
 from operator import attrgetter
 from typing import Literal, NewType
 
-from pydantic import BaseModel, Field, field_serializer, field_validator, model_validator
+from pydantic import BaseModel, Field, RootModel, field_serializer, field_validator, model_validator
 
-from eligibility_signposting_api.config.contants import MAGIC_COHORT_LABEL
+from eligibility_signposting_api.config.contants import MAGIC_COHORT_LABEL, RULE_STOP_DEFAULT
 
 if typing.TYPE_CHECKING:  # pragma: no cover
     from pydantic import SerializationInfo
@@ -34,6 +35,7 @@
 CohortGroup = NewType("CohortGroup", str)
 Description = NewType("Description", str)
 RuleStop = NewType("RuleStop", bool)
+CommsRouting = NewType("CommsRouting", str)
 
 
 class RuleType(StrEnum):
@@ -111,7 +113,8 @@ class IterationRule(BaseModel):
     operator: RuleOperator = Field(..., alias="Operator")
     comparator: RuleComparator = Field(..., alias="Comparator")
     attribute_target: RuleAttributeTarget | None = Field(None, alias="AttributeTarget")
-    rule_stop: RuleStop = Field(RuleStop(False), alias="RuleStop")  # noqa: FBT003
+    rule_stop: RuleStop = Field(RuleStop(RULE_STOP_DEFAULT), alias="RuleStop")
+    comms_routing: CommsRouting | None = Field(None, alias="CommsRouting")
 
     model_config = {"populate_by_name": True, "extra": "ignore"}
 
@@ -121,6 +124,24 @@ def parse_yn_to_bool(cls, v: str | bool) -> bool:  # noqa: N805
             return v.upper() == "Y"
         return v
 
+    def __str__(self) -> str:
+        return json.dumps(self.model_dump(by_alias=True), indent=2)
+
+
+class AvailableAction(BaseModel):
+    action_type: str = Field(..., alias="ActionType")
+    action_code: str = Field(..., alias="ExternalRoutingCode")
+    action_description: str | None = Field(None, alias="ActionDescription")
+    url_link: str | None = Field(None, alias="UrlLink")
+    url_label: str | None = Field(None, alias="UrlLabel")
+
+    model_config = {"populate_by_name": True}
+
+
+class ActionsMapper(RootModel[dict[str, AvailableAction]]):
+    def get(self, key: str, default: AvailableAction | None = None) -> AvailableAction | None:
+        return self.root.get(key, default)
+
 
 class Iteration(BaseModel):
     id: IterationID = Field(..., alias="ID")
@@ -131,8 +152,10 @@ class Iteration(BaseModel):
     approval_minimum: int | None = Field(None, alias="ApprovalMinimum")
     approval_maximum: int | None = Field(None, alias="ApprovalMaximum")
     type: Literal["A", "M", "S"] = Field(..., alias="Type")
+    default_comms_routing: str = Field(..., alias="DefaultCommsRouting")
     iteration_cohorts: list[IterationCohort] = Field(..., alias="IterationCohorts")
     iteration_rules: list[IterationRule] = Field(..., alias="IterationRules")
+    actions_mapper: ActionsMapper = Field(..., alias="ActionsMapper")
 
     model_config = {"populate_by_name": True, "arbitrary_types_allowed": True, "extra": "ignore"}
 
@@ -148,6 +171,9 @@ def parse_dates(cls, v: str | date) -> date:
     def serialize_dates(v: date, _info: SerializationInfo) -> str:
         return v.strftime("%Y%m%d")
 
+    def __str__(self) -> str:
+        return json.dumps(self.model_dump(by_alias=True), indent=2)
+
 
 class CampaignConfig(BaseModel):
     id: CampaignID = Field(..., alias="ID")
@@ -224,6 +250,9 @@ def current_iteration(self) -> Iteration:
         iterations_by_date_descending = sorted(self.iterations, key=attrgetter("iteration_date"), reverse=True)
         return next(i for i in iterations_by_date_descending if i.iteration_date <= today)
 
+    def __str__(self) -> str:
+        return json.dumps(self.model_dump(by_alias=True), indent=2)
+
 
 class Rules(BaseModel):
     """Eligibility rules.

src/eligibility_signposting_api/services/calculators/eligibility_calculator.py

@@ -8,17 +8,24 @@
 from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from eligibility_signposting_api.model.rules import Iteration, IterationCohort
+    from eligibility_signposting_api.model.rules import ActionsMapper, Iteration, IterationCohort
 
 from wireup import service
 
 from eligibility_signposting_api.model import eligibility, rules
 from eligibility_signposting_api.model.eligibility import (
+    ActionCode,
+    ActionDescription,
+    ActionType,
     CohortGroupResult,
     Condition,
     ConditionName,
     IterationResult,
     Status,
+    SuggestedAction,
+    SuggestedActions,
+    UrlLabel,
+    UrlLink,
 )
 from eligibility_signposting_api.services.calculators.rule_calculator import (
     RuleCalculator,
@@ -108,32 +115,78 @@ def get_rules_by_type(
         )
         return filter_rules, suppression_rules
 
-    def evaluate_eligibility(self) -> eligibility.EligibilityStatus:
+    @staticmethod
+    def get_redirect_rules(
+        active_iteration: Iteration,
+    ) -> tuple[tuple[rules.IterationRule, ...], ActionsMapper, str]:
+        redirect_rules = tuple(
+            rule for rule in active_iteration.iteration_rules if rule.type in rules.RuleType.redirect
+        )
+        default_comms = active_iteration.default_comms_routing
+        action_mapper = active_iteration.actions_mapper
+        return redirect_rules, action_mapper, default_comms
+
+    def evaluate_eligibility(self, *, include_actions_flag: bool = True) -> eligibility.EligibilityStatus:
         """Iterates over campaign groups, evaluates eligibility, and returns a consolidated status."""
         condition_results: dict[ConditionName, IterationResult] = {}
+        actions: SuggestedActions | None = SuggestedActions([])
 
         for condition_name, campaign_group in self.campaigns_grouped_by_condition_name:
-            iteration_results: dict[str, IterationResult] = {}
+            iteration_results: dict[str, tuple[Iteration, IterationResult]] = {}
 
             for active_iteration in [cc.current_iteration for cc in campaign_group]:
                 cohort_results: dict[str, CohortGroupResult] = self.get_cohort_results(active_iteration)
 
                 # Determine Result between cohorts - get the best
                 status, best_cohorts = self.get_the_best_cohort_memberships(cohort_results)
-
-                iteration_results[active_iteration.name] = IterationResult(status, best_cohorts)
+                iteration_results[active_iteration.name] = (
+                    active_iteration,
+                    IterationResult(status, best_cohorts, actions),
+                )
 
             # Determine results between iterations - get the best
             if iteration_results:
-                best_candidate = max(iteration_results.values(), key=lambda r: r.status.value)
+                best_iteration_name, (best_active_iteration, best_candidate) = max(
+                    iteration_results.items(), key=lambda item: item[1][1].status.value
+                )
             else:
-                best_candidate = IterationResult(eligibility.Status.not_eligible, [])
+                best_candidate = IterationResult(eligibility.Status.not_eligible, [], actions)
+                best_active_iteration = None
             condition_results[condition_name] = best_candidate
 
+            if best_candidate.status == Status.actionable and best_active_iteration is not None:
+                actions = self.handle_redirect_rules(best_active_iteration) if include_actions_flag else None
+            if best_candidate.status in (Status.not_eligible, Status.not_actionable) and not include_actions_flag:
+                actions = None
+
+            # add actions to condition results
+            condition_results[condition_name].actions = actions
         # Consolidate all the results and return
         final_result = self.build_condition_results(condition_results)
         return eligibility.EligibilityStatus(conditions=final_result)
 
+    def handle_redirect_rules(self, best_active_iteration: Iteration) -> SuggestedActions | None:
+        redirect_rules, action_mapper, default_comms = self.get_redirect_rules(best_active_iteration)
+        priority_getter = attrgetter("priority")
+        sorted_rules_by_priority = sorted(redirect_rules, key=priority_getter)
+
+        actions: SuggestedActions | None = self.get_actions_from_comms(action_mapper, default_comms)
+        for _, rule_group in groupby(sorted_rules_by_priority, key=priority_getter):
+            rule_group_list = list(rule_group)
+            matcher_matched_list = [
+                RuleCalculator(person_data=self.person_data, rule=rule).evaluate_exclusion()[1].matcher_matched
+                for rule in rule_group_list
+            ]
+
+            comms_routing = rule_group_list[0].comms_routing
+            if comms_routing and all(matcher_matched_list):
+                rule_actions = self.get_actions_from_comms(action_mapper, comms_routing)
+                if rule_actions and len(rule_actions.actions) > 0:
+                    actions = rule_actions
+                break
+
+        return actions
+
     def get_cohort_results(self, active_iteration: rules.Iteration) -> dict[str, CohortGroupResult]:
         cohort_results: dict[str, CohortGroupResult] = {}
         filter_rules, suppression_rules = self.get_rules_by_type(active_iteration)
@@ -156,9 +209,7 @@ def get_cohort_results(self, active_iteration: rules.Iteration) -> dict[str, Coh
         return cohort_results
 
     @staticmethod
-    def build_condition_results(
-        condition_results: dict[ConditionName, IterationResult],
-    ) -> list[Condition]:
+    def build_condition_results(condition_results: dict[ConditionName, IterationResult]) -> list[Condition]:
         conditions: list[Condition] = []
         # iterate over conditions
         for condition_name, active_iteration_result in condition_results.items():
@@ -188,6 +239,7 @@ def build_condition_results(
                     condition_name=condition_name,
                     status=active_iteration_result.status,
                     cohort_results=list(deduplicated_cohort_results),
+                    actions=condition_results[condition_name].actions,
                 )
             )
         return conditions
@@ -276,3 +328,22 @@ def evaluate_rules_priority_group(
                 inclusion_reasons.append(reason)
 
         return best_status, inclusion_reasons, exclusion_reasons, is_rule_stop
+
+    @staticmethod
+    def get_actions_from_comms(action_mapper: ActionsMapper, comms: str) -> SuggestedActions | None:
+        suggested_actions: SuggestedActions = SuggestedActions([])
+        for comm in comms.split("|"):
+            action = action_mapper.get(comm)
+            if action is not None:
+                suggested_actions.actions.append(
+                    SuggestedAction(
+                        action_type=ActionType(action.action_type),
+                        action_code=ActionCode(action.action_code),
+                        action_description=ActionDescription(action.action_description)
+                        if action.action_description
+                        else None,
+                        url_link=UrlLink(action.url_link) if action.url_link else None,
+                        url_label=UrlLabel(action.url_label) if action.url_label else None,
+                    )
+                )
+        return suggested_actions

src/eligibility_signposting_api/services/calculators/rule_calculator.py

@@ -20,11 +20,12 @@ class RuleCalculator:
     def evaluate_exclusion(self) -> tuple[eligibility.Status, eligibility.Reason]:
         """Evaluate if a particular rule excludes this person. Return the result, and the reason for the result."""
         attribute_value = self.get_attribute_value()
-        status, reason = self.evaluate_rule(attribute_value)
+        status, reason, matcher_matched = self.evaluate_rule(attribute_value)
         reason = eligibility.Reason(
             rule_name=eligibility.RuleName(self.rule.name),
             rule_type=eligibility.RuleType(self.rule.type),
             rule_description=eligibility.RuleDescription(self.rule.description),
+            matcher_matched=matcher_matched,
         )
         return status, reason
 
@@ -69,18 +70,20 @@ def get_value(dictionary: Mapping[str, Any] | None, key: str) -> dict:
         v = dictionary.get(key, {}) if isinstance(dictionary, dict) else {}
         return v if isinstance(v, dict) else {}
 
-    def evaluate_rule(self, attribute_value: str | None) -> tuple[eligibility.Status, str]:
+    def evaluate_rule(self, attribute_value: str | None) -> tuple[eligibility.Status, str, bool]:
         """Evaluate a rule against a person data attribute. Return the result, and the reason for the result."""
         matcher_class = OperatorRegistry.get(self.rule.operator)
         matcher = matcher_class(rule_value=self.rule.comparator)
 
+        matcher_matched = matcher.matches(attribute_value)
         reason = StringDescription()
-        if matcher.matches(attribute_value):
+        if matcher_matched:
             matcher.describe_match(attribute_value, reason)
             status = {
                 rules.RuleType.filter: eligibility.Status.not_eligible,
                 rules.RuleType.suppression: eligibility.Status.not_actionable,
+                rules.RuleType.redirect: eligibility.Status.actionable,
             }[self.rule.type]
-            return status, str(reason)
+            return status, str(reason), matcher_matched
         matcher.describe_mismatch(attribute_value, reason)
-        return eligibility.Status.actionable, str(reason)
+        return eligibility.Status.actionable, str(reason), matcher_matched

src/eligibility_signposting_api/services/eligibility_services.py

@@ -13,6 +13,10 @@ class UnknownPersonError(Exception):
     pass
 
 
+class InvalidQueryParamError(Exception):
+    pass
+
+
 @service
 class EligibilityService:
     def __init__(
@@ -26,7 +30,9 @@ def __init__(
         self.campaign_repo = campaign_repo
         self.calculator_factory = calculator_factory
 
-    def get_eligibility_status(self, nhs_number: eligibility.NHSNumber | None = None) -> eligibility.EligibilityStatus:
+    def get_eligibility_status(
+        self, nhs_number: eligibility.NHSNumber | None = None, *, include_actions_flag: bool = True
+    ) -> eligibility.EligibilityStatus:
         """Calculate a person's eligibility for vaccination given an NHS number."""
         if nhs_number:
             try:
@@ -45,6 +51,6 @@ def get_eligibility_status(self, nhs_number: eligibility.NHSNumber | None = None
                 raise UnknownPersonError from e
             else:
                 calc: calculator.EligibilityCalculator = self.calculator_factory.get(person_data, campaign_configs)
-                return calc.evaluate_eligibility()
+                return calc.evaluate_eligibility(include_actions_flag=include_actions_flag)
 
         raise UnknownPersonError  # pragma: no cover