endoreg-db 0.8.4.4__py3-none-any.whl → 0.8.6.1__py3-none-any.whl

endoreg_db/services/lookup_service.py

@@ -1,35 +1,81 @@
+"""
+Lookup Service Module
+
+This module provides server-side evaluation and lookup functionality for patient examinations.
+It handles requirement set evaluation, finding availability, and status computation for
+medical examination workflows.
+
+The lookup system uses a token-based approach where client sessions are stored in Django cache,
+allowing for efficient state management and recomputation of derived data.
+
+Key Components:
+- PatientExamination loading with optimized prefetching
+- Requirement set resolution and evaluation
+- Status computation for requirements and requirement sets
+- Suggested actions for unsatisfied requirements
+- Cache-based session management
+
+Architecture:
+1. LookupStore: Handles cache-based session storage
+2. lookup_service: Core business logic for evaluation
+3. LookupViewSet: Django REST API endpoints
+"""
+
 # services/lookup_service.py
 from __future__ import annotations
-from typing import Dict, Any, List
+
+from typing import Any, Dict, List
+
 from django.db.models import Prefetch
-from endoreg_db.models.medical.patient.patient_examination import PatientExamination
+
 from endoreg_db.models.medical.examination import ExaminationRequirementSet
+from endoreg_db.models.medical.patient.patient_examination import PatientExamination
 from endoreg_db.models.requirement.requirement_set import RequirementSet
+
 from .lookup_store import LookupStore
 
 
 def load_patient_exam_for_eval(pk: int) -> PatientExamination:
     """
-    Fetch PatientExamination with everything needed for evaluation,
-    following the *Examination → ExaminationRequirementSet → RequirementSet* graph.
+    Load a PatientExamination with all related data needed for evaluation.
+
+    This function performs optimized database queries to fetch a PatientExamination
+    along with all related objects required for requirement evaluation, including:
+    - Patient and examination details
+    - Patient findings
+    - Examination requirement sets and their requirements
+    - Nested requirement set relationships
+
+    The query uses select_related and prefetch_related to minimize database hits
+    and ensure all data is available for evaluation without additional queries.
+
+    Args:
+        pk: Primary key of the PatientExamination to load
+
+    Returns:
+        PatientExamination: Fully loaded instance with all related data prefetched
+
+    Raises:
+        PatientExamination.DoesNotExist: If no examination exists with the given pk
     """
     return (
-        PatientExamination.objects
-        .select_related("patient", "examination")
+        PatientExamination.objects.select_related("patient", "examination")
         .prefetch_related(
             "patient_findings",
             # Prefetch ERS groups on the Examination…
             Prefetch(
                 "examination__exam_reqset_links",
-                queryset=ExaminationRequirementSet.objects.only("id", "name", "enabled_by_default"),
+                queryset=ExaminationRequirementSet.objects.only(
+                    "id", "name", "enabled_by_default"
+                ),
             ),
             # …and the RequirementSets reachable via those ERS groups.
             Prefetch(
                 "examination__exam_reqset_links__requirement_set",
                 queryset=(
-                    RequirementSet.objects
-                    .select_related("requirement_set_type")
-                    .prefetch_related(
+                    RequirementSet.objects.select_related(
+                        "requirement_set_type"
+                    ).prefetch_related(
                         "requirements",
                         "links_to_sets",
                         "links_to_sets__requirements",
@@ -44,27 +90,66 @@ def load_patient_exam_for_eval(pk: int) -> PatientExamination:
 
 def requirement_sets_for_patient_exam(pe: PatientExamination) -> List[RequirementSet]:
     """
-    Correctly resolve RequirementSets for a PE via ERS hub:
-        RequirementSet.objects.filter(reqset_exam_links__examinations=exam)
+    Get all requirement sets applicable to a patient examination.
+
+    This function resolves requirement sets through the examination's requirement set links.
+    It follows the relationship: PatientExamination → Examination → ExaminationRequirementSet → RequirementSet
+
+    Args:
+        pe: PatientExamination instance to get requirement sets for
+
+    Returns:
+        List of RequirementSet instances applicable to the examination, with related data prefetched
     """
     exam = pe.examination
     if not exam:
         return []
     return list(
-        RequirementSet.objects
-        .filter(reqset_exam_links__examinations=exam)
+        RequirementSet.objects.filter(reqset_exam_links__examinations=exam)
         .select_related("requirement_set_type")
         .prefetch_related("requirements")
         .distinct()
     )
 
+
 def build_initial_lookup(pe: PatientExamination) -> Dict[str, Any]:
     """
-    Build the initial lookup dict you will return to the client.
-    Keep keys small and stable; values must be JSON-serializable.
+    Build the initial lookup dictionary for a patient examination.
+
+    This function creates the base lookup data structure that will be stored in cache
+    and used by the client for requirement evaluation. It includes:
+
+    - Available findings for the examination type
+    - Required findings based on requirement defaults
+    - Requirement sets metadata
+    - Default findings and classification choices per requirement
+    - Empty placeholders for dynamic data (status, suggestions, etc.)
+
+    The returned dictionary is JSON-serializable and contains stable keys that
+    won't change between versions.
+
+    Args:
+        pe: PatientExamination instance to build lookup for
+
+    Returns:
+        Dictionary containing initial lookup data with the following keys:
+        - patient_examination_id: ID of the patient examination
+        - requirement_sets: List of available requirement sets with metadata
+        - availableFindings: List of finding IDs available for the examination
+        - requiredFindings: List of finding IDs that are required by defaults
+        - requirementDefaults: Default findings per requirement
+        - classificationChoices: Available classification choices per requirement
+        - requirementsBySet: Empty dict (populated on selection)
+        - requirementStatus: Empty dict (computed on evaluation)
+        - requirementSetStatus: Empty dict (computed on evaluation)
+        - suggestedActions: Empty dict (computed on evaluation)
     """
     # Available + required findings
-    available_findings = [f.id for f in pe.examination.get_available_findings()] if pe.examination else []
+    available_findings = (
+        [f.id for f in pe.examination.get_available_findings()]
+        if pe.examination
+        else []
+    )
     required_findings: List[int] = []  # fill by scanning requirements below
 
     # Requirement sets: ids + meta
@@ -90,9 +175,13 @@ def build_initial_lookup(pe: PatientExamination) -> Dict[str, Any]:
             choices = getattr(req, "classification_choices", lambda pe: [])(pe)
             if defaults:
                 req_defaults[str(req.id)] = defaults  # list of {finding_id, payload...}
-                required_findings.extend([d.get("finding_id") for d in defaults if "finding_id" in d])
+                required_findings.extend(
+                    [d.get("finding_id") for d in defaults if "finding_id" in d]
+                )
             if choices:
-                cls_choices[str(req.id)] = choices   # list of {classification_id, label, ...}
+                cls_choices[str(req.id)] = (
+                    choices  # list of {classification_id, label, ...}
+                )
 
     # De-dup required
     required_findings = sorted(set(required_findings))
@@ -112,62 +201,129 @@ def build_initial_lookup(pe: PatientExamination) -> Dict[str, Any]:
         # You can add "selectedRequirementSetIds" as the user makes choices
     }
 
+
 def create_lookup_token_for_pe(pe_id: int) -> str:
+    """
+    Create a lookup token for a patient examination.
+
+    This function initializes a new lookup session for the given patient examination
+    by building the initial lookup data and storing it in the cache via LookupStore.
+
+    Args:
+        pe_id: Primary key of the PatientExamination
+
+    Returns:
+        String token that can be used to access the lookup session
+
+    Raises:
+        PatientExamination.DoesNotExist: If examination doesn't exist
+        Exception: For any other errors during initialization
+    """
     pe = load_patient_exam_for_eval(pe_id)
     token = LookupStore().init(build_initial_lookup(pe))
     return token
 
+
 def recompute_lookup(token: str) -> Dict[str, Any]:
+    """
+    Recompute derived lookup data based on current patient examination state and user selections.
+
+    This function performs the core evaluation logic for the lookup system. It:
+
+    1. Validates and recovers corrupted lookup data
+    2. Loads the current PatientExamination state from database
+    3. Evaluates requirements against the current examination state
+    4. Computes status for individual requirements and requirement sets
+    5. Generates suggested actions for unsatisfied requirements
+    6. Updates the cache with new derived data (idempotent)
+
+    The function includes reentrancy protection to prevent concurrent recomputation
+    of the same token.
+
+    Args:
+        token: Lookup session token
+
+    Returns:
+        Dictionary of updates containing:
+        - requirementsBySet: Requirements grouped by selected requirement sets
+        - requirementStatus: Boolean status for each requirement
+        - requirementSetStatus: Boolean status for each requirement set
+        - requirementDefaults: Default findings per requirement
+        - classificationChoices: Available choices per requirement
+        - suggestedActions: UI actions to satisfy unsatisfied requirements
+
+    Raises:
+        ValueError: If lookup data is invalid or patient examination not found
+    """
     import logging
+
     logger = logging.getLogger(__name__)
-    
+
     store = LookupStore(token=token)
-    
+
     # Simple reentrancy guard using data
     data = store.get_all()
-    if data.get('_recomputing'):
+    if data.get("_recomputing"):
         logger.warning(f"Recompute already in progress for token {token}, skipping")
         return {}
-    
-    store.set('_recomputing', True)
-    
+
+    store.set("_recomputing", True)
+
     try:
         # First validate and attempt to recover corrupted data
         validated_data = store.validate_and_recover_data(token)
         if validated_data is None:
             logger.error(f"No lookup data found for token {token}")
             raise ValueError(f"No lookup data found for token {token}")
-        
+
         data = validated_data
-        logger.debug(f"Recomputing lookup for token {token}, data keys: {list(data.keys())}")
-        
+        logger.debug(
+            f"Recomputing lookup for token {token}, data keys: {list(data.keys())}"
+        )
+
         # Check if required data exists
         if "patient_examination_id" not in data:
-            logger.error(f"Invalid lookup data for token {token}: missing patient_examination_id. Data: {data}")
-            raise ValueError(f"Invalid lookup data for token {token}: missing patient_examination_id")
-        
+            logger.error(
+                f"Invalid lookup data for token {token}: missing patient_examination_id. Data: {data}"
+            )
+            raise ValueError(
+                f"Invalid lookup data for token {token}: missing patient_examination_id"
+            )
+
         if not data.get("patient_examination_id"):
-            logger.error(f"Invalid lookup data for token {token}: patient_examination_id is empty. Data: {data}")
-            raise ValueError(f"Invalid lookup data for token {token}: patient_examination_id is empty")
+            logger.error(
+                f"Invalid lookup data for token {token}: patient_examination_id is empty. Data: {data}"
+            )
+            raise ValueError(
+                f"Invalid lookup data for token {token}: patient_examination_id is empty"
+            )
 
         pe_id = data["patient_examination_id"]
         logger.debug(f"Loading patient examination {pe_id} for token {token}")
-        
+
         try:
             pe = load_patient_exam_for_eval(pe_id)
         except Exception as e:
-            logger.error(f"Failed to load patient examination {pe_id} for token {token}: {e}")
+            logger.error(
+                f"Failed to load patient examination {pe_id} for token {token}: {e}"
+            )
             raise ValueError(f"Failed to load patient examination {pe_id}: {e}")
 
         selected_rs_ids: List[int] = data.get("selectedRequirementSetIds", [])
-        logger.debug(f"Selected requirement set IDs for token {token}: {selected_rs_ids}")
-        
-        rs_objs = [rs for rs in requirement_sets_for_patient_exam(pe) if rs.id in selected_rs_ids]
+        logger.debug(
+            f"Selected requirement set IDs for token {token}: {selected_rs_ids}"
+        )
+
+        rs_objs = [
+            rs
+            for rs in requirement_sets_for_patient_exam(pe)
+            if rs.id in selected_rs_ids
+        ]
         logger.debug(f"Found {len(rs_objs)} requirement set objects for token {token}")
 
         # 1) requirements grouped by set (already prefetched in load func)
         requirements_by_set = {
-            rs.id: [ {"id": r.id, "name": r.name} for r in rs.requirements.all() ]
+            rs.id: [{"id": r.id, "name": r.name} for r in rs.requirements.all()]
             for rs in rs_objs
         }
 
@@ -180,7 +336,9 @@ def recompute_lookup(token: str) -> Dict[str, Any]:
                 ok = bool(r.evaluate(pe, mode="strict"))  # or "loose" if you prefer
                 requirement_status[str(r.id)] = ok
                 req_results.append(ok)
-            set_status[str(rs.id)] = rs.eval_function(req_results) if rs.eval_function else all(req_results)
+            set_status[str(rs.id)] = (
+                rs.eval_function(req_results) if rs.eval_function else all(req_results)
+            )
 
         # 3) suggestions per requirement (defaults + classification choices you already expose)
         suggested_actions: Dict[str, List[Dict[str, Any]]] = {}
@@ -189,8 +347,12 @@ def recompute_lookup(token: str) -> Dict[str, Any]:
 
         for rs in rs_objs:
             for r in rs.requirements.all():
-                defaults = getattr(r, "default_findings", lambda pe: [])(pe)  # [{finding_id, payload...}]
-                choices  = getattr(r, "classification_choices", lambda pe: [])(pe)  # [{classification_id, label,...}]
+                defaults = getattr(r, "default_findings", lambda pe: [])(
+                    pe
+                )  # [{finding_id, payload...}]
+                choices = getattr(r, "classification_choices", lambda pe: [])(
+                    pe
+                )  # [{classification_id, label,...}]
                 if defaults:
                     req_defaults[str(r.id)] = defaults
                 if choices:
@@ -200,15 +362,19 @@ def recompute_lookup(token: str) -> Dict[str, Any]:
                     # turn default proposals into explicit UI actions
                     acts = []
                     for d in defaults or []:
-                        acts.append({
-                            "type": "add_finding",
-                            "finding_id": d.get("finding_id"),
-                            "classification_ids": d.get("classification_ids") or [],
-                            "note": "default"
-                        })
+                        acts.append(
+                            {
+                                "type": "add_finding",
+                                "finding_id": d.get("finding_id"),
+                                "classification_ids": d.get("classification_ids") or [],
+                                "note": "default",
+                            }
+                        )
                     # If r expects patient edits, add an edit action hint
                     if "PatientExamination" in [m.__name__ for m in r.expected_models]:
-                        acts.append({"type": "edit_patient", "fields": ["gender", "dob"]})  # example
+                        acts.append(
+                            {"type": "edit_patient", "fields": ["gender", "dob"]}
+                        )  # example
                     if acts:
                         suggested_actions[str(r.id)] = acts
 
@@ -220,22 +386,26 @@ def recompute_lookup(token: str) -> Dict[str, Any]:
             "requirementsBySet": requirements_by_set,
             "requirementStatus": requirement_status,
             "requirementSetStatus": set_status,
-            "requirementDefaults": req_defaults,         # keep your existing key
-            "classificationChoices": cls_choices,        # keep your existing key
-            "suggestedActions": suggested_actions,       # new
+            "requirementDefaults": req_defaults,  # keep your existing key
+            "classificationChoices": cls_choices,  # keep your existing key
+            "suggestedActions": suggested_actions,  # new
         }
-        
-        logger.debug(f"Updating store for token {token} with {len(updates)} update keys")
-        
+
+        logger.debug(
+            f"Updating store for token {token} with {len(updates)} update keys"
+        )
+
         # Only write if changed (idempotent)
         prev_derived = store.get_many(list(updates.keys()))
         if prev_derived != updates:
             store.set_many(updates)  # <-- does NOT call recompute
             logger.debug(f"Derived data changed, updated store for token {token}")
         else:
-            logger.debug(f"Derived data unchanged, skipping store update for token {token}")
-        
+            logger.debug(
+                f"Derived data unchanged, skipping store update for token {token}"
+            )
+
         store.mark_recompute_done()
         return updates
     finally:
-        store.set('_recomputing', False)
+        store.set("_recomputing", False)