fix: protocol agent absent value

Author: marceloarocha

services/admin/admin_protocol_service.py

@@ -225,7 +225,11 @@ def _validate_variables(variables: list[dict], protocol_type: int):
                     )
 
         else:
-            if not operator or not value:
+            # 0 is a legitimate threshold, not an empty field: comparing an exam
+            # to "> 0" is how the absence of a result is expressed (the trigger
+            # negates the variable), so only a genuinely empty value is rejected.
+            # The editor sends numbers as text, so it reaches here as "0".
+            if not operator or value is None or value == "" or value == []:
                 raise ValidationError(
                     f"Variável {name}: Todos os campos são obrigatórios",
                     "errors.businessRules",

services/protocol_agent_service.py

@@ -42,6 +42,15 @@
 # three are merged in as extra keys derived from the exam initials.
 EXAM_TYPE_ALIASES = {"cr", "tgo", "tgp", "plqt"}
 
+# Fields where the model tends to invent an impossible value to mean "absent".
+# No real threshold reaches -999, so anything at or below it is a sentinel.
+SENTINEL_CHECKED_FIELDS = {
+    ProtocolVariableFieldEnum.EXAM.value,
+    ProtocolVariableFieldEnum.EXAM_REF.value,
+    ProtocolVariableFieldEnum.CN_STATS.value,
+}
+SENTINEL_VALUE_THRESHOLD = -999
+
 # Per-item criteria of a "combination" variable. They live as flat sibling keys
 # of the variable itself (that is what the form renders and what
 # utils.alert_protocol reads), but the model likes to wrap them in an object
@@ -90,7 +99,7 @@
     "- config.trigger: expression combining variables as {{name}} with "
     '"and", "or", "not" and parentheses (Python precedence: or < and < not). '
     "Nothing else is allowed — no literals, no comparisons, no function "
-    "calls. Maximum 500 characters.\n"
+    "calls. Write the operators in LOWER CASE. Maximum 500 characters.\n"
     '- config.result: {"type": "SHOW_MESSAGE", "level": "low"|"medium"|"high", '
     '"message": "<short alert>", "description": "<longer explanation>"}.\n\n'
     "VARIABLE FIELDS (field → operator → value)\n"
@@ -134,6 +143,29 @@
     '"doseOperator": ">", "defaultMeasureUnit": "mg"}\n'
     'WRONG (criteria are lost): {"name": "...", "field": "combination", '
     '"operator": "PRESENT", "value": {"substance": ["22165008"]}}\n\n'
+    "ABSENCE OF DATA (exam, exam_ref, cn_stats)\n"
+    "When the user asks about the ABSENCE of an exam or indicator — 'paciente "
+    "sem creatinina', 'não tem hemograma', 'nenhum exame de função renal' — "
+    "there is NO value that means absent. NEVER invent an impossible number "
+    "like -999 to represent it: no such row exists in the database, so the "
+    "comparison is simply never true and the protocol never fires.\n"
+    "The pattern is: declare the variable POSITIVELY with operator '>' and "
+    "value 0, which is true whenever any result of that type exists, and negate "
+    "it in the TRIGGER with 'not'. A variable is false when the patient has no "
+    "result, so its negation is exactly 'the patient has no such exam'.\n"
+    'CORRECT — variable {"name": "tem_creatinina", "field": "exam_ref", '
+    '"examRefType": "<tpexam>", "operator": ">", "value": 0} '
+    'with trigger "not {{tem_creatinina}}".\n'
+    'WRONG (never matches): {"name": "sem_creatinina", "field": "exam_ref", '
+    '"examRefType": "<tpexam>", "operator": "=", "value": -999} '
+    'with trigger "{{sem_creatinina}}".\n'
+    "Name the variable after what it detects when TRUE (tem_..., possui_...), "
+    "because the trigger is what inverts it. Combine it freely with other "
+    "variables, e.g. \"{{idoso}} and not {{tem_creatinina}}\".\n"
+    "This trick is ONLY for the numeric fields (exam, exam_ref, cn_stats), which "
+    "have no negative operator. For list fields (substance, class, idDrug, "
+    "route, idDepartment, idSegment, idIcd) use the NOTIN operator directly on "
+    "the variable and do NOT negate the trigger.\n\n"
     "RULES\n"
     "- NEVER invent ids (sctid, idDrug, class, examType, examRefType, "
     "statsType...). Only ever write an id you read from a tool result in this "
@@ -331,6 +363,39 @@ def _normalize_variable(variable: dict) -> dict:
     return normalized
 
 
+def _sentinel_value_errors(variables: list) -> list[str]:
+    """Reject an impossible value used to mean "the patient has no such result".
+
+    No row in the database carries a sentinel, so the comparison never matches
+    and the protocol silently never fires. Absence is expressed by declaring the
+    variable positively (operator '>' value 0, true when any result exists) and
+    negating it in the trigger with 'not'.
+    """
+    errors = []
+
+    for variable in variables:
+        if not isinstance(variable, dict):
+            continue
+
+        if variable.get("field") not in SENTINEL_CHECKED_FIELDS:
+            continue
+
+        try:
+            value = float(variable.get("value"))
+        except (TypeError, ValueError):
+            continue
+
+        if value <= SENTINEL_VALUE_THRESHOLD:
+            errors.append(
+                f"Variável {variable.get('name')}: valor {variable.get('value')} não "
+                "existe na base. Para detectar a ausência do resultado, declare a "
+                'variável com operator ">" e value 0 e negue no gatilho com "not '
+                '{{nome_da_variavel}}"'
+            )
+
+    return errors
+
+
 def _load_exam_catalogs(variables: list) -> dict:
     """Load the catalogs needed to check the ids used by these variables.
 
@@ -472,6 +537,7 @@ def _validate_proposal(proposal: dict, draft: dict) -> list[str]:
         errors.append(str(error))
 
     errors.extend(_combination_criteria_errors(variables=variables))
+    errors.extend(_sentinel_value_errors(variables=variables))
     errors.extend(
         _catalog_errors(
             variables=variables, catalogs=_load_exam_catalogs(variables=variables)

tests/unit/test_alerts_protocol.py

@@ -1021,6 +1021,66 @@
             },
             False,
         ),
+        # absence of an exam: "> 0" is true whenever a result exists, so the
+        # negated trigger is what detects a patient without the exam
+        (
+            {
+                "variables": [
+                    {"name": "tem", "field": "exam", "examType": "ckd21",
+                     "operator": ">", "value": 0},
+                ],
+                "trigger": "{{tem}}",
+                "result": {"message": "result"},
+            },
+            True,
+        ),
+        (
+            {
+                "variables": [
+                    {"name": "tem", "field": "exam", "examType": "ckd21",
+                     "operator": ">", "value": 0},
+                ],
+                "trigger": "not {{tem}}",
+                "result": {"message": "result"},
+            },
+            False,
+        ),
+        (
+            {
+                "variables": [
+                    {"name": "tem", "field": "exam", "examType": "hemograma",
+                     "operator": ">", "value": 0},
+                ],
+                "trigger": "not {{tem}}",
+                "result": {"message": "result"},
+            },
+            True,
+        ),
+        # combined with another condition
+        (
+            {
+                "variables": [
+                    {"name": "idoso", "field": "age", "operator": ">", "value": 40},
+                    {"name": "tem", "field": "exam", "examType": "hemograma",
+                     "operator": ">", "value": 0},
+                ],
+                "trigger": "{{idoso}} and not {{tem}}",
+                "result": {"message": "result"},
+            },
+            True,
+        ),
+        # the sentinel the model reaches for instead: never matches
+        (
+            {
+                "variables": [
+                    {"name": "sem", "field": "exam", "examType": "ckd21",
+                     "operator": "=", "value": -999},
+                ],
+                "trigger": "{{sem}}",
+                "result": {"message": "result"},
+            },
+            False,
+        ),
     ],
 )
 def test_trigger(protocol, has_result):

tests/unit/test_protocol_agent_service.py

@@ -668,3 +668,52 @@ def test_validate_protocol_tool_reports_an_invented_exam():
     assert result["valid"] is False
     assert any("CREAT_FAKE" in e for e in result["errors"])
     assert any("search_reference_exams" in e for e in result["errors"])
+
+
+def test_sentinel_exam_value_is_rejected():
+    # the model reaches for an impossible value to mean "no such exam"
+    with _patch_global_exams("creatinina_NH"):
+        errors = _validate_proposal(
+            proposal=_exam_proposal(
+                _exam_ref_variable(
+                    examRefType="creatinina_NH", operator="=", value=-999
+                )
+            ),
+            draft={},
+        )
+
+    assert len(errors) == 1
+    assert "-999" in errors[0]
+    assert "not" in errors[0]
+
+
+def test_absence_pattern_passes():
+    # the supported way to express absence: positive variable, negated trigger
+    with _patch_global_exams("creatinina_NH"):
+        proposal = _exam_proposal(
+            _exam_ref_variable(examRefType="creatinina_NH", operator=">", value=0)
+        )
+        proposal["config"]["trigger"] = "not {{v1}}"
+
+        assert _validate_proposal(proposal=proposal, draft={}) == []
+
+
+def test_negated_trigger_is_accepted_by_the_trigger_validator():
+    assert _is_valid_trigger(trigger="not {{v1}}", variable_names=["v1"])
+    assert _is_valid_trigger(
+        trigger="{{v1}} and not {{v2}}", variable_names=["v1", "v2"]
+    )
+
+
+def test_plausible_negative_threshold_is_not_treated_as_a_sentinel():
+    # some exams are legitimately negative (base excess, delta values)
+    with _patch_exam_types("be"):
+        assert (
+            _validate_proposal(
+                proposal=_exam_proposal(
+                    _exam_variable(examType="be", operator="<", value=-5)
+                ),
+                draft={},
+            )
+            == []
+        )