h-adminsim 1.0.0__py3-none-any.whl

h_adminsim/pipeline/__init__.py

@@ -0,0 +1,3 @@
+from .data_generator import DataGenerator
+from .simulation import Simulator
+from .evaluator import Evaluator

h_adminsim/pipeline/data_generator.py

@@ -0,0 +1,192 @@
+import os
+import random
+import numpy as np
+from sconf import Config
+from pathlib import Path
+from importlib import resources
+from typing import Optional, Union
+
+from h_adminsim.task.fhir_manager import FHIRManager
+from h_adminsim.tools import DataSynthesizer, DataConverter, AgentDataBuilder
+from h_adminsim.utils import Information, colorstr, log
+from h_adminsim.utils.random_utils import random_uuid
+from h_adminsim.utils.filesys_utils import get_files, json_load
+
+
+
+class DataGenerator:
+    def __init__(self,
+                 care_level: str = 'primary',
+                 config: Optional[Union[str, Config]] = None):
+        
+        # Initialize
+        self.config = self.load_config(care_level, config)
+        self.__env_setup(self.config)
+        self.fhir_url = self.config.get('fhir_url', None)
+        self.data_synthesizer = DataSynthesizer(self.config)
+        self.save_dir = self.data_synthesizer._save_dir
+        log(f'Data saving directory: {colorstr(self.save_dir)}')
+
+        
+    def load_config(self, care_level: str, config: Optional[Union[str, Config]]) -> Config:
+        """
+        Load a configuration object.
+
+        If `config` is None, a default configuration is loaded based on the given
+        `care_level`. If `config` is a string, it is treated as a file path and
+        loaded as a Config object. If a Config instance is provided, it is returned
+        as-is.
+
+        Args:
+            care_level (str): Care level used to select the default config.
+            config (Optional[Union[str, Config]]): A file path or Config instance.
+
+        Raises:
+            TypeError: If `config` is not None, str, or Config.
+
+        Returns:
+            Config: A fully initialized Config object.
+        """
+        # Case 1: config is None -> load built-in config based on care_level
+        if config is None:
+            log(f"No config provided; using default {care_level} config.", "warning")
+            assert care_level in ['primary', 'secondary', 'tertiary'], \
+                log(f"Invalid care_level: '{care_level}'. Expected one of: primary, secondary, tertiary.", "error")
+            default_path = str(resources.files("h_adminsim.assets.configs").joinpath(f"data4{care_level}.yaml"))
+            return Config(default_path)
+
+        # Case 2: config is a string path
+        if isinstance(config, str):
+            config_inst = Config(config)
+            return config_inst
+
+        # Case 3: config is already a Config object
+        if isinstance(config, Config):
+            return config
+
+        # Otherwise error
+        raise TypeError(
+            log(f"Invalid config: expected None, str, or Config, got {type(config).__name__}", "error")
+        )
+
+
+    def __env_setup(self, config: Config):
+        """
+        Initialize environment-level random seeds using the given configuration.
+
+        Args:
+            config (Config): Configuration containing the seed value.
+        """
+        random.seed(config.seed)
+        np.random.seed(config.seed)
+    
+
+    def build(self, 
+              sanity_check: bool = True,
+              convert_to_fhir: bool = False,
+              build_agent_data: bool = True) -> Information:
+        """
+        Build the complete information bundle for the administrative simulation pipeline.
+
+        Args:
+            sanity_check (bool, optional): Whether to perform validation checks during synthetic data generation. Defaults to True.
+            convert_to_fhir (bool, optional): If True, converts synthesized data into FHIR-compliant resources and stores them 
+                                              in the configured output directory. Defaults to False.
+            build_agent_data (bool, optional): If True, generates additional derived data required for agent-based
+                                               simulations (e.g., patient profiles, department assignments, task inputs). Defaults to True.
+
+        Raises:
+            Exception: Propagates any exception encountered during:
+                - synthetic data synthesis
+                - FHIR conversion
+                - agent data generation
+
+        Returns:
+            Information:
+                A structured container holding:
+                    - `data`: the synthesized dataset
+                    - `fhir_data`: list of FHIR resources (or None if disabled)
+                    - `agent_data`: processed agent input data (or None if disabled)
+        """
+        # Data generator
+        try:
+            data, hospital_obj = self.data_synthesizer.synthesize(sanity_check=sanity_check)
+            log(f"Data synthesis completed successfully", color=True)
+        except Exception as e:
+            log("Data synthesis failed.", level="error")
+            raise e
+        
+        # FHIR conversion
+        all_resource_list = None
+        if convert_to_fhir:
+            converter = DataConverter(self.config)
+            try:
+                all_resource_list = converter(self.save_dir / 'fhir_data', sanity_check)
+                log(f"Data FHIR conversion completed successfully", color=True)
+            except Exception as e:
+                log("Data FHIR conversion failed.", level='error')
+                raise e
+            
+        # Build data for agent simulation
+        agent_data_list = None
+        if build_agent_data:
+            builder = AgentDataBuilder(self.config)
+            try:
+                agent_data_list = builder(self.save_dir / 'agent_data')
+                log(f"Agent data generation completed successfully", color=True)
+            except Exception as e:
+                log("Agent data generation failed.", level='error')
+                raise e
+        
+        output = Information(
+            data=data,
+            fhir_data=all_resource_list,
+            agent_data=agent_data_list
+        )
+        
+        return output
+    
+
+    def upload_to_fhir(self,
+                       fhir_data_dir: str,
+                       fhir_url: Optional[str] = None):
+        """
+        Upload synthesized FHIR resources to the specified FHIR server.
+
+        Args:
+            fhir_data_dir (str): Directory containing FHIR resource JSON files (e.g., practitioner, practitionerrole, schedule, slot).
+            fhir_url (Optional[str], optional): Base URL of the FHIR server. If not provided, the instance's default FHIR URL is used.
+        """
+        # Initialize FHIR URL and manager
+        if not fhir_url:
+            fhir_url = self.fhir_url
+        assert fhir_url != None, log('')
+        
+        if not fhir_url.endswith('fhir'):
+            fhir_url = os.path.join(fhir_url, 'fhir')
+
+        fhir_manager = FHIRManager(fhir_url)
+
+        # FHIR resources
+        fhir_data_dir = Path(fhir_data_dir)
+        fhir_resources_dirs = [fhir_data_dir / resource for resource in ['practitioner', 'practitionerrole', 'schedule', 'slot']]
+
+        # Upload resources to FHIR
+        for path in fhir_resources_dirs:
+            files = get_files(path, ext='json')
+            error_files = list()
+
+            for file in files:
+                resource_data = json_load(file)
+                resource_type = resource_data.get('resourceType')
+                if 'id' not in resource_data:
+                    resource_data['id'] = random_uuid(False)
+                
+                response = fhir_manager.create(resource_type, resource_data)
+                if 200 <= response.status_code < 300:
+                    log(f"Created {resource_type} with ID {response.json().get('id')}")
+                else:
+                    error_files.append(file)
+            
+            if len(error_files):
+                log(f'Error files during creating data: {error_files}', 'warning')

h_adminsim/pipeline/evaluator.py

@@ -0,0 +1,33 @@
+from h_adminsim.tools import Evaluator as BaseEvaluator
+from h_adminsim.utils import log
+
+
+
+class Evaluator(BaseEvaluator):
+    def __init__(self, path: str):
+        super().__init__(path)
+        
+    
+    def evaluate(self, tasks: list[str]):
+        """
+        Evaluate the performance of an agent.
+
+        Args:
+            tasks (list[str]): A task list to evaluate.
+        """
+        if 'task' in tasks:
+            self.task_evaluation()
+            log('')
+
+        # if 'feedback' in tasks:
+        #     self.supervisor_evaluation()
+        #     log('')
+
+        if 'rounds' in tasks:
+            self.calculate_avg_rounds()
+            log('')
+
+        if 'department' in tasks:
+            self.department_evaluation()
+            log('')
+        

h_adminsim/pipeline/simulation.py

@@ -0,0 +1,231 @@
+import os
+import random
+import numpy as np
+from typing import Optional
+
+from h_adminsim.task.agent_task import *
+from h_adminsim.task.fhir_manager import FHIRManager
+from h_adminsim.environment.hospital import HospitalEnvironment
+from h_adminsim.utils.filesys_utils import json_load, json_save_fast, get_files
+
+
+
+class Simulator:
+    def __init__(self,
+                 intake_task: Optional[OutpatientFirstIntake] = None,
+                 scheduling_task: Optional[OutpatientFirstScheduling] = None,
+                 simulation_start_day_before: float = 3,
+                 fhir_integration: bool = False,
+                 fhir_url: Optional[str] = None,
+                 fhir_max_connection_retries: int = 5,
+                 random_seed: int = 9999):
+        
+        # Initialize
+        self.__env_setup(random_seed)
+        self.simulation_start_day_before = simulation_start_day_before
+        self.fhir_integration = fhir_integration
+        self.fhir_url = fhir_url if self.fhir_integration else None
+        self.fhir_max_connection_retries = fhir_max_connection_retries
+        self.task_queue, self.task_list = self._init_task(intake_task, scheduling_task)
+
+
+    def __env_setup(self, random_seed: int):
+        """
+        Initialize environment-level random seeds.
+
+        Args:
+            random_seed (int): Random seed.
+        """
+        random.seed(random_seed)
+        np.random.seed(random_seed)
+
+
+    def _init_task(self, 
+                   intake_task: Optional[OutpatientFirstIntake] = None,
+                   scheduling_task: Optional[OutpatientFirstScheduling] = None) -> Tuple[list[FirstVisitOutpatientTask], list[str]]:
+        """
+        Initialize the task queue for first-visit outpatient workflow.
+
+        Args:
+            intake_task (Optional[OutpatientFirstIntake], optional): Intake task instance to include in the queue. Defaults to None.
+            scheduling_task (Optional[OutpatientFirstScheduling], optional): Scheduling task instance to include in the queue. Defaults to None.
+
+        Returns:
+            Tuple[list[FirstVisitOutpatientTask], list[str]]:
+                A tuple containing:
+                    - the ordered list of task objects
+                    - the list of task names in execution order
+        """
+        task_queue, task_list = list(), list()
+        assert intake_task != None or scheduling_task != None, \
+            log("At least one of 'intake_task' or 'scheduling_task' must be provided (both cannot be None).", level='error')
+
+        if intake_task != None:
+            task_queue.append(intake_task)
+            task_list.append(intake_task.name)
+        if scheduling_task != None:
+            task_queue.append(scheduling_task)
+            task_list.append(scheduling_task.name)
+        
+        return task_queue, task_list
+    
+
+    def clean_fhir(self):
+        """
+        Clear the FHIR data.
+        """
+        if self.fhir_integration:
+            fhir_manager = FHIRManager(self.fhir_url)
+            appointment_entries = fhir_manager.read_all('Appointment')
+            patient_entries = fhir_manager.read_all('Patient')
+            fhir_manager.delete_all(appointment_entries, verbose=False)
+            fhir_manager.delete_all(patient_entries, verbose=False)
+
+    
+    @staticmethod
+    def shuffle_data(data: dict):
+        """
+        Shuffle the agent test data by the schedule start time.
+
+        Args:
+            data (dict): An agent test data to simulate a hospital environmnet.
+        """
+        random.shuffle(data['agent_data'])        # In-place logic
+
+
+    @staticmethod
+    def resume_results(agent_simulation_data: dict, results_path: str, d_results_path: str) -> Tuple[dict, dict, dict, set]:
+        """
+        Resume a previously saved simulation by aligning agent results.
+
+        Args:
+            agent_simulation_data (dict): Static agent test data for a simulation.
+            results_path (str): Path to the JSON file containing the saved simulation results.
+            d_results_path (str): Path to the JSON file containing the saved dialog results.
+
+        Returns:
+            Tuple[dict, int]:
+                - dict: Schedule updated static agent test data.
+                - dict: Previously saved agent results.
+                - dict: Previously saved dialog results.
+                - set: A dictionary containing patients that have already been processed for each task.
+        """
+        # Load previous results
+        agent_results = json_load(results_path)
+        dialog_results = json_load(d_results_path) if os.path.exists(d_results_path) else dict()
+
+        # Get patients that have already been processed for each task
+        done_patients = dict()
+        for task_name, result in agent_results.items():
+            if task_name == 'intake':
+                done_patients[task_name] = {done['patient']['name'] for done in result['gt']}
+            elif task_name == 'schedule':
+                done_patients[task_name] = set()
+                for done in result['gt']:
+                    try:
+                        done_patients[task_name].add(done['patient'])
+                    except (KeyError, TypeError):
+                        continue
+        
+        # Updated doctor schedules based on the resumed results
+        if 'schedule' in agent_results:
+            fixed_schedule = agent_simulation_data['doctor']
+            statuses = [x for y in agent_results['schedule']['status'] for x in (y if isinstance(y, list) or isinstance(y, tuple) else [y])]
+            preds = [x for y in agent_results['schedule']['pred'] for x in (y if isinstance(y, list) or isinstance(y, tuple) else [y])]
+            for status, pred in zip(statuses, preds):
+                if status and 'status' in pred and pred['status'] != 'cancelled':
+                    fixed_schedule[pred['attending_physician']]['schedule'][pred['date']].append(pred['schedule'])
+                    fixed_schedule[pred['attending_physician']]['schedule'][pred['date']].sort()
+        
+        return agent_simulation_data, agent_results, dialog_results, done_patients
+
+    
+    def run(self,
+            simulation_data_path: str,
+            output_dir: str,
+            resume: bool = False,
+            verbose: bool = False):
+        """
+        Run the agent-based hospital administrative simulation.
+
+        Args:
+            simulation_data_path (str): Path to a JSON file or directory containing agent simulation input data.
+            output_dir (str): Directory to store simulation results.
+            resume (bool, optional): Whether to resume a previous simulation if result files exist. Defaults to False.
+            verbose (bool, optional): Whether to print detailed logs during task execution. Defaults to False.
+
+        Raises:
+            Exception: Propagates any errors encountered during simulation or result saving.
+        """
+        # Clear FHIR data
+        if not resume:
+            self.clean_fhir()
+        
+        # Load agent simulation data
+        is_file = os.path.isfile(simulation_data_path)
+        agent_simulation_data_files = [simulation_data_path] if is_file else get_files(simulation_data_path, ext='json')
+        all_agent_simulation_data = [json_load(path) for path in agent_simulation_data_files]   # one agent simulation data per hospital
+
+        try:
+            os.makedirs(output_dir, exist_ok=True)
+
+            # Data per hospital
+            for i, agent_simulation_data in enumerate(all_agent_simulation_data):
+                agent_results, done_patients, dialog_results = dict(), dict(), dict()
+                Simulator.shuffle_data(agent_simulation_data)
+                environment = HospitalEnvironment(
+                    agent_simulation_data,
+                    self.fhir_url,
+                    self.fhir_max_connection_retries,
+                    self.simulation_start_day_before
+                )
+                basename = os.path.splitext(os.path.basename(agent_simulation_data_files[i]))[0]
+                save_path = os.path.join(output_dir, f'{basename}_result.json')
+                d_save_path = os.path.join(output_dir, f'{basename}_dialog.json')
+                log(f'{basename} simulation started..', color=True)
+
+                # Resume the results and the virtual hospital environment
+                if resume and os.path.exists(save_path):
+                    agent_simulation_data, agent_results, dialog_results, done_patients = Simulator.resume_results(agent_simulation_data, save_path, d_save_path)
+                    environment.resume(agent_results)
+
+                # Data per patient
+                for j, (gt, test_data) in enumerate(agent_simulation_data['agent_data']):
+                    for task in self.task_queue:
+                        if task.name in done_patients and gt['patient'] in done_patients[task.name]:
+                            continue
+
+                        result = task((gt, test_data), agent_simulation_data, agent_results, environment, verbose)
+                        dialogs = result.pop('dialog')
+
+                        # Append a single result 
+                        agent_results.setdefault(task.name, {'gt': [], 'pred': [], 'status': [], 'status_code': [], 'trial': [], 'dialog': []})
+                        for k in result:
+                            agent_results[task.name][k] += result[k]
+                        
+                        if task.name == 'intake':
+                            dialog_results[gt['patient']] = dialogs[0]
+                        else:
+                            agent_results[task.name]['dialog'] += dialogs
+
+                # Logging the results
+                for task_name, result in agent_results.items():
+                    correctness = [x for y in result['status'] for x in (y if isinstance(y, list) or isinstance(y, tuple) else [y])]
+                    status_code = [x for y in result['status_code'] for x in (y if isinstance(y, list) or isinstance(y, tuple) else [y])]
+                    accuracy = sum(correctness) / len(correctness)
+                    log(f'{basename} - {task_name} task results..', color=True)
+                    log(f'   - accuracy: {accuracy:.3f}, length: {len(correctness)}, status_code: {status_code}')
+
+                json_save_fast(save_path, agent_results)
+                if 'intake' in self.task_list:
+                    json_save_fast(d_save_path, dialog_results)
+            
+            log(f"Agent completed the tasks successfully", color=True)
+        
+        except Exception as e:
+            if len(agent_results):
+                json_save_fast(save_path, agent_results)
+                if 'intake' in self.task_list:
+                    json_save_fast(d_save_path, dialog_results)
+            log("Error occured while execute the tasks.", level='error')
+            raise e

h_adminsim/registry/__init__.py

@@ -0,0 +1,5 @@
+from .pydantic_models import *
+from .variables import *
+from .models import *
+from .errors import STATUS_CODES
+from .phrases import *

h_adminsim/registry/errors.py

@@ -0,0 +1,89 @@
+STATUS_CODES = {
+    'format': 'incorrect format',
+    'department': 'incorrect department',
+    'patient': 'incorrect patient information',
+    'department & patient': 'incorrect department and patient information',
+    'simulation': 'incomplete simulation',
+    'schedule': 'invalid schedule',
+    'duration': 'wrong duration',
+    'conflict': {
+        'physician': 'physician conflict', 
+        'time': 'time conflict'
+    },
+    'preference': {
+        'physician': 'mismatched physician',
+        'asap': 'not earliest schedule',
+        'date': 'not valid date',
+    },
+    'cancel': {
+        'identify': 'cancel: fail to identify requested schedule',
+        'type': 'cancel: unexpected tool calling result'
+    },
+    'reschedule': {
+        'identify': 'reschedule: fail to identify requested schedule',
+        'schedule': 'reschedule: {status_code}',
+        'type': 'reschedule: unexpected tool calling result'
+    },
+    'preceding': 'preceding task failed',
+    'unexpected': "unexpected error: {e}",
+    'correct': 'pass',
+}
+
+# SCHEDULING_ERROR_CAUSE = {
+#     'incorrect format': [
+#         '* There is an issue with the output format. Please perform scheduling in the correct format.',
+#     ],
+#     'physician conflict': [
+#         '* More than one doctor has been assigned. A schedule must be made with exactly one doctor.',
+#     ],
+#     'time conflict': [
+#         "* The scheduling result overlaps with the doctor's existing schedule.",
+#     ],
+#     'mismatched physician': [
+#         '* A different doctor was assigned even though the patient requested a specific doctor.',
+#     ],
+#     'not earliest schedule': [
+#         '* The patient wants the earliest possible appointment in the department, but the assigned time is not the earliest available based on the current time.',
+#         '* When scheduling, it is possible to assign an earlier date or time.',
+#         "* The previous patient's schedule may have been cancelled. Therefore, it is necessary to carefully compare the hospital's start time with the doctor's schedule to identify available time slots.",
+#     ],
+#     'not valid date': [
+#         '* The patient is available after a specific date and would like to make an appointment. Please choose the earliest possible time after that date.',
+#     ],
+#     'invalid schedule': [
+#         "* The scheduling result may fall outside the hospital's operating hours.",
+#         "* The scheduling result may be in the past relative to the current time.",
+#         "* The scheduling result may not be a valid date.",
+#         "* The assigned doctor may not belong to the department the patient should visit.",
+#     ],
+#     'wrong duration': [
+#         "* The patient's schedule does not match the consultation duration required by the doctor.",
+#     ],
+#     # 'workload balancing': [
+#     #     "* You must schedule the appointment with a doctor who has a lower workload than the current doctor.",
+#     # ]
+# }
+
+
+class ToolCallingError(Exception):
+    error_code = "TOOL_CALLING_ERROR"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+
+class ScheduleNotFoundError(Exception):
+    error_code = "SCHEDULE_NOT_FOUND_ERROR"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+
+
+class SchedulingError(Exception):
+    error_code = "SCHEDULING_ERROR"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message

h_adminsim/registry/models.py

@@ -0,0 +1,126 @@
+class Hospital:
+    def __init__(self, 
+                 hospital_name: str,
+                 department_num: int,
+                 doctor_num: int,
+                 time: dict,
+                 **kwargs):
+        self.hospital_name = hospital_name
+        self.department_num = department_num
+        self.doctor_num = doctor_num
+        self.time = time
+        self.department: list[Department] = []
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+
+    def add_department(self, department_name: str, **kwargs):
+        """
+        Add a department to the hospital.
+
+        Args:
+            department_name (str): Name of the department to add.
+        
+        Returns:
+            Department: The newly created Department object.
+        """
+        dept = Department(department_name, **kwargs)
+        self.department.append(dept)
+        return dept
+
+
+    def reset_departments(self):
+        """
+        Reset the list of departments in the hospital.
+        """
+        self.department = []
+
+
+    def __repr__(self):
+        return f"Hospital(name={self.hospital_name}, departments={[d.name for d in self.department]}, time={self.time})"
+
+
+
+class Department:
+    def __init__(self, name: str, **kwargs):
+        self.name = name
+        self.doctor: list[Doctor] = []
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+
+    def add_doctor(self, doctor_name: str, **kwargs):
+        """
+        Add a doctor to the department.
+        
+        Args:
+            doctor_name (str): Name of the doctor to add.
+        
+        Returns:
+            Doctor: The newly created Doctor object.
+        """
+        doctor = Doctor(doctor_name, self, **kwargs)
+        self.doctor.append(doctor)
+        return doctor
+
+    
+    def reset_doctors(self):
+        """
+        Reset the list of doctors in the department.
+        """
+        self.doctor = []
+
+
+    def __repr__(self):
+        return f"Department(name={self.name}, doctors={[d.name for d in self.doctor]})"
+
+
+
+class Doctor:
+    def __init__(self, name: str, department: Department, **kwargs):
+        self.name = name
+        self.department = department
+        self.schedule = []
+        self.patient: list[Patient] = []
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    
+    def add_patient(self, patient_name: str, **kwargs):
+        """
+        Add a patient to the doctor.
+        
+        Args:
+            patient_name (str): Name of the patient to add.
+        
+        Returns:
+            Paitnet: The newly created Paitent object.
+        """
+        patient = Patient(patient_name, self, **kwargs)
+        self.patient.append(patient)
+        return patient
+
+    
+    def reset_patients(self):
+        """
+        Reset the list of patients in the doctor.
+        """
+        self.patient = []
+
+
+    def __repr__(self):
+        return f"Doctor(name={self.name}, department={self.department.name}), schedule={self.schedule})"
+    
+
+
+class Patient:
+    def __init__(self, name: str, attending_physician: Doctor, **kwargs):
+        self.name = name
+        self.attending_physician = attending_physician
+        self.schedule = []
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+    
+
+    def __repr__(self):
+        return f"Patient(name={self.name}, department={self.attending_physician.department.name}), attending_physician={self.attending_physician.name}), schedule={self.schedule})"