def _choose_random_template(self) -> str:
    """
    Select a random template file from the template folder.
    :return: The path to the randomly selected template file.
    """

    template_folder = Path(_configs["TEMPLATE_PATH"]) / self._app_name
    template_files = [f for f in template_folder.iterdir() if f.is_file()]

    if not template_files:
        raise Exception("No template files found in the specified directory.")

    chosen_template_file = random.choice(template_files)
    print(f"Randomly selected template: {chosen_template_file.name}")
    return str(chosen_template_file)

def _choose_target_template_file(
    self, given_task: str, doc_files_description: Dict[str, str]
) -> str:
    """
    Get the target file based on the semantic similarity of the given task and the template file descriptions.
    :param given_task: The task to be matched.
    :param doc_files_description: A dictionary of template file descriptions.
    :return: The path to the chosen template file.
    """

    if _configs["TEMPLATE_METHOD"] == "SemanticSimilarity":
        return self._choose_target_template_file_semantic(
            given_task, doc_files_description
        )
    elif _configs["TEMPLATE_METHOD"] == "LLM":
        self.template_agent = TemplateAgent(
            "template",
            is_visual=True,
            main_prompt=_configs["TEMPLATE_PROMPT"],
        )
        return self._choose_target_template_file_llm(
            given_task, doc_files_description
        )
    else:
        raise ValueError("Invalid TEMPLATE_METHOD.")

def _choose_target_template_file_llm(
    self, given_task: str, doc_files_description: Dict[str, str]
) -> str:
    """
    Get the target file based on the LLM of the given task and the template file descriptions.
    :param given_task: The task to be matched.
    :param doc_files_description: A dictionary of template file descriptions.
    :return: The path to the chosen template file.
    """

    prompt_message = self.template_agent.message_constructor(
        doc_files_description, given_task
    )
    response_string, _ = self.template_agent.get_response(
        prompt_message, "prefill", use_backup_engine=True, configs=_configs
    )
    if response_string is None:
        raise ValueError("No similar templates found.")
    elif "```json" in response_string:
        response_string = response_string[7:-3]
    response_json = json.loads(response_string)
    file_name = list(response_json.keys())[0]
    if file_name not in doc_files_description:
        print(f"Template {file_name} not found in the description.")
        raise ValueError("No similar templates found.")
    return file_name

def _choose_target_template_file_semantic(
    self, given_task: str, doc_files_description: Dict[str, str]
) -> str:
    """
    Get the target file based on the semantic similarity of the given task and the template file descriptions.
    :param given_task: The task to be matched.
    :param doc_files_description: A dictionary of template file descriptions.
    :return: The path to the chosen template file.
    """

    file_doc_map = {
        desc: file_name for file_name, desc in doc_files_description.items()
    }
    db = FAISS.from_texts(
        list(doc_files_description.values()), self._embedding_model
    )
    most_similar = db.similarity_search(given_task, k=1)

    if not most_similar:
        raise ValueError("No similar templates found.")
    return file_doc_map[most_similar[0].page_content]

def _choose_template_and_copy(self) -> str:
    """
    Choose the template and copy it to the cache folder.
    :return: The path to the copied template file.
    """

    chosen_template_file_path = self._get_chosen_file_path()
    chosen_template_full_path = (
        Path(_configs["TEMPLATE_PATH"]) / self._app_name / chosen_template_file_path
    )

    target_template_folder_path = Path(
        _configs["RESULT_HUB"].format(task_type="saved_document")
    ) / (os.path.dirname(os.path.dirname(self._task_file_name)))

    return self._create_copied_file(
        chosen_template_full_path, target_template_folder_path, self._task_file_name
    )

def _create_copied_file(
    self, copy_from_path: Path, copy_to_folder_path: Path, file_name: str = None
) -> str:
    """
    Create a cache file from the specified source.
    :param copy_from_path: The original path of the file.
    :param copy_to_folder_path: The path where the cache file will be created.
    :param file_name: Optional; the name of the task file.
    :return: The path to the newly created cache file.
    """

    os.makedirs(copy_to_folder_path, exist_ok=True)
    copied_template_path = self._generate_copied_file_path(
        copy_to_folder_path, file_name
    )

    with open(copy_from_path, "rb") as f:
        ori_content = f.read()
    with open(copied_template_path, "wb") as f:
        f.write(ori_content)

    return copied_template_path

def _generate_copied_file_path(self, folder_path: Path, file_name: str) -> str:
    """
    Generate the file path for the copied template.
    :param folder_path: The folder where the file will be created.
    :param file_name: Optional; the name of the task file.
    :return: The path to the newly created file.
    """

    template_extension = self._file_extension
    if file_name:
        return str(folder_path / f"{file_name}{template_extension}")
    timestamp = datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
    return str(folder_path / f"{timestamp}{template_extension}")

def _get_chosen_file_path(self) -> str:
    """
    Choose the most relevant template file based on the task.
    :return: The path to the most relevant template file.
    """

    templates_description_path = (
        Path(_configs["TEMPLATE_PATH"]) / self._app_name / "description.json"
    )

    try:
        with open(templates_description_path, "r") as f:
            return self._choose_target_template_file(
                self._task_file_name, json.load(f)
            )
    except FileNotFoundError:
        warnings.warn(
            f"Warning: {templates_description_path} does not exist. Choosing a random template."
        )
        return self._choose_random_template()

@staticmethod
def _load_embedding_model(model_name: str) -> CacheBackedEmbeddings:
    """
    Load the embedding model.
    :param model_name: The name of the embedding model to load.
    :return: The loaded embedding model.
    """

    store = LocalFileStore(_configs["CONTROL_EMBEDDING_CACHE_PATH"])
    if not model_name.startswith(ChooseTemplateFlow._SENTENCE_TRANSFORMERS_PREFIX):
        model_name = ChooseTemplateFlow._SENTENCE_TRANSFORMERS_PREFIX + model_name
    embedding_model = HuggingFaceEmbeddings(model_name=model_name)
    return CacheBackedEmbeddings.from_bytes_store(
        embedding_model, store, namespace=model_name
    )

def execute(self) -> str:
    """
    Execute the flow and return the copied template path.
    :return: The path to the copied template file.
    """

    start_time = time.time()
    try:
        template_copied_path = self._choose_template_and_copy()
    except Exception as e:
        raise e
    finally:
        self.execution_time = round(time.time() - start_time, 3)
    return template_copied_path

def _get_prefill_actions(
    self, given_task: str, reference_steps: List[str], file_path: str
) -> Tuple[str, List[str]]:
    """
    Generate refined tasks and action plans using the PrefillAgent.
    :param given_task: The task to refine.
    :param reference_steps: Reference steps for the task.
    :param file_path: Path to the task template.
    :return: The refined task and corresponding action plans.
    """

    self._update_state(file_path)
    execution_time = 0
    # Save a screenshot of the app state
    screenshot_path = os.path.join(self._log_path_configs, "screenshot.png")
    self._save_screenshot(self._task_file_name, screenshot_path)

    # Construct prompt message for the PrefillAgent
    prompt_message = self._prefill_agent.message_constructor(
        "",
        given_task,
        reference_steps,
        self._log_path_configs,
    )

    # Log the constructed message
    self._log_message(prompt_message)

    try:
        # Record start time and get PrefillAgent response
        start_time = time.time()
        response_string, _ = self._prefill_agent.get_response(
            prompt_message, "prefill", use_backup_engine=True, configs=_configs
        )
        execution_time = round(time.time() - start_time, 3)

        # Parse and log the response
        response_json = self._prefill_agent.response_to_dict(response_string)
        instantiated_request = response_json["New_task"]
        instantiated_plan = response_json["Actions_plan"]

    except Exception as e:
        self._status = "ERROR"
        logging.exception(f"Error in prefilling task: {e}")
        raise e
    finally:
        # Log the response and execution time
        self._log_response(response_json, execution_time)

    return instantiated_request, instantiated_plan

def _instantiate_task(
    self, template_copied_path: str, original_task: str, refined_steps: List[str]
) -> Tuple[str, List[str]]:
    """
    Retrieve and process the instantiated result for the task.
    Interacts with the PrefillAgent to refine the task and generate action plans.
    :param template_copied_path: The path of the copied template to use.
    :param original_task: The original task to refine.
    :param refined_steps: The steps to guide the refinement process.
    :return: The refined task and corresponding action plans.
    """

    try:
        # Retrieve prefill actions and task plan
        instantiated_request, instantiated_plan = self._get_prefill_actions(
            original_task,
            refined_steps,
            template_copied_path,
        )

        print(f"Original Task: {original_task}")
        print(f"Prefilled Task: {instantiated_request}")

    except Exception as e:
        logging.exception(f"Error in prefilling task: {e}")
        raise e

    return instantiated_request, instantiated_plan

def _log_message(self, prompt_message: str) -> None:
    """
    Log the constructed prompt message for the PrefillAgent.
    :param prompt_message: The message constructed for PrefillAgent.
    """

    messages_log_entry = {
        "step": self._execute_step,
        "messages": prompt_message,
        "error": "",
    }
    self._message_logger.info(json.dumps(messages_log_entry, indent=4))

def _log_response(
    self, response_json: Dict[str, Any], execution_time: float
) -> None:
    """
    Log the response received from PrefillAgent along with execution time.
    :param response_json: Response data from PrefillAgent.
    :param execution_time: Time taken for the PrefillAgent call.
    """

    response_log_entry = {
        "step": self._execute_step,
        "execution_time": execution_time,
        "agent_response": response_json,
        "error": "",
    }
    self._response_logger.info(json.dumps(response_log_entry, indent=4))

def _save_screenshot(self, doc_name: str, save_path: str) -> None:
    """
    Captures a screenshot of the current window or the full screen if the window is not found.
    :param doc_name: The name or description of the document to match the window.
    :param save_path: The path where the screenshot will be saved.
    """

    try:
        # Find the window matching the document name
        matched_window = self._app_env.find_matching_window(doc_name)
        if matched_window:
            screenshot = self._photographer.capture_app_window_screenshot(
                matched_window
            )
        else:
            logging.warning("Window not found, taking a full-screen screenshot.")
            screenshot = self._photographer.capture_desktop_screen_screenshot()

        screenshot.save(save_path)
        print(f"Screenshot saved to {save_path}")
    except Exception as e:
        logging.exception(f"Failed to save screenshot: {e}")
        raise e

def _update_state(self, file_path: str) -> None:
    """
    Update the current state of the app by inspecting UI elements.
    :param file_path: Path of the app file to inspect.
    """

    print(f"Updating the app state using the file: {file_path}")

    # Retrieve control elements in the app window
    control_list = self._control_inspector.find_control_elements_in_descendants(
        self._app_env.app_window,
        control_type_list=_ufo_configs["CONTROL_LIST"],
        class_name_list=_ufo_configs["CONTROL_LIST"],
    )

    # Capture UI control annotations
    self._annotation_dict = self._photographer.get_annotation_dict(
        self._app_env.app_window, control_list, annotation_type="number"
    )

    # Filter out irrelevant control elements
    self._filtered_annotation_dict = self.get_filtered_annotation_dict(
        self._annotation_dict, configs=_configs
    )

    # Gather control info for both full and filtered lists
    self._control_info = self._control_inspector.get_control_info_list_of_dict(
        self._annotation_dict,
        ["control_text", "control_type" if _BACKEND == "uia" else "control_class"],
    )
    self._filtered_control_info = (
        self._control_inspector.get_control_info_list_of_dict(
            self._filtered_annotation_dict,
            [
                "control_text",
                "control_type" if _BACKEND == "uia" else "control_class",
            ],
        )
    )

def execute(
    self, template_copied_path: str, original_task: str, refined_steps: List[str]
) -> Dict[str, Any]:
    """
    Start the execution by retrieving the instantiated result.
    :param template_copied_path: The path of the copied template to use.
    :param original_task: The original task to refine.
    :param refined_steps: The steps to guide the refinement process.
    :return: The refined task and corresponding action plans.
    """

    start_time = time.time()
    try:
        instantiated_request, instantiated_plan = self._instantiate_task(
            template_copied_path, original_task, refined_steps
        )
    except Exception as e:
        raise e
    finally:
        self.execution_time = round(time.time() - start_time, 3)

    return {
        "instantiated_request": instantiated_request,
        "instantiated_plan": instantiated_plan,
    }

def get_prompter(self, is_visual: bool, main_prompt: str, example_prompt: str, api_prompt: str) -> str:
    """
    Get the prompt for the agent.
    This is the abstract method from BasicAgent that needs to be implemented.
    :param is_visual: The flag indicating whether the agent is visual or not.
    :param main_prompt: The main prompt.
    :param example_prompt: The example prompt.
    :param api_prompt: The API prompt.
    :return: The prompt string.
    """

    return PrefillPrompter(is_visual, main_prompt, example_prompt, api_prompt)

def message_constructor(
    self,
    dynamic_examples: str,
    given_task: str,
    reference_steps: List[str],
    log_path: str,
) -> List[str]:
    """
    Construct the prompt message for the PrefillAgent.
    :param dynamic_examples: The dynamic examples retrieved from the self-demonstration and human demonstration.
    :param given_task: The given task.
    :param reference_steps: The reference steps.
    :param log_path: The path of the log.
    :return: The prompt message.
    """

    prefill_agent_prompt_system_message = self.prompter.system_prompt_construction(
        dynamic_examples
    )
    prefill_agent_prompt_user_message = self.prompter.user_content_construction(
        given_task, reference_steps, log_path
    )
    appagent_prompt_message = self.prompter.prompt_construction(
        prefill_agent_prompt_system_message,
        prefill_agent_prompt_user_message,
    )

    return appagent_prompt_message

def process_comfirmation(self) -> None:
    """
    Confirm the process.
    This is the abstract method from BasicAgent that needs to be implemented.
    """

    pass

def _fix_json_commas(self, json_string: str) -> str:
    """
    Function to add missing commas between key-value pairs in a JSON string
    and remove newline characters for proper formatting.
    :param json_string: The JSON string to be fixed.
    :return: The fixed JSON string.
    """

    # Remove newline characters
    json_string = json_string.replace("\n", "")

    return json_string

def _get_filtered_result(self, instantiated_request: str) -> Tuple[bool, str, str]:
    """
    Get the filtered result from the filter agent.
    :param instantiated_request: Request object containing task details.
    :return: Tuple containing task quality flag, request comment, and request type.
    """

    # Construct the prompt message for the filter agent
    prompt_message = self._filter_agent.message_constructor(
        instantiated_request,
        self._app_name,
    )
    prompt_json = json.dumps(prompt_message, indent=4)
    self._filter_message_logger.info(prompt_json)

    # Get the response from the filter agent
    try:
        start_time = time.time()
        response_string, _ = self._filter_agent.get_response(
            prompt_message, "filter", use_backup_engine=True, configs=_configs
        )
        try:
            fixed_response_string = self._fix_json_commas(response_string)
            response_json = self._filter_agent.response_to_dict(
                fixed_response_string
            )
        except json.JSONDecodeError as e:
            logging.error(
                f"JSONDecodeError: {e.msg} at position {e.pos}. Response: {response_string}"
            )
            raise e

        execution_time = round(time.time() - start_time, 3)

        response_json["execution_time"] = execution_time
        self._filter_response_logger.info(json.dumps(response_json, indent=4))

        return (
            response_json["judge"],
            response_json["thought"],
            response_json["type"],
        )
    except Exception as e:
        logging.error(f"Error occurred while filtering: {e}")
        raise e

def _get_or_create_filter_agent(self) -> FilterAgent:
    """
    Retrieve or create a filter agent for the given application.
    :return: FilterAgent instance for the specified application.
    """

    if self._app_name not in FilterFlow._app_filter_agent_dict:
        FilterFlow._app_filter_agent_dict[self._app_name] = FilterAgent(
            "filter",
            self._app_name,
            is_visual=True,
            main_prompt=_configs["FILTER_PROMPT"],
            example_prompt="",
            api_prompt=_configs["API_PROMPT"],
        ) 
    return FilterFlow._app_filter_agent_dict[self._app_name]

def _initialize_logs(self) -> None:
    """
    Initialize logging for filter messages and responses.
    """

    os.makedirs(self._log_path_configs, exist_ok=True)
    self._filter_message_logger = BaseSession.initialize_logger(
        self._log_path_configs, "filter_messages.json", "w", _configs
    )
    self._filter_response_logger = BaseSession.initialize_logger(
        self._log_path_configs, "filter_responses.json", "w", _configs
    )

def execute(self, instantiated_request: str) -> Dict[str, Any]:
    """
    Execute the filter flow: Filter the task and save the result.
    :param instantiated_request: Request object to be filtered.
    :return: Tuple containing task quality flag, comment, and task type.
    """

    start_time = time.time()
    try:
        judge, thought, request_type = self._get_filtered_result(
            instantiated_request
        )
    except Exception as e:
        raise e
    finally:
        self.execution_time = round(time.time() - start_time, 3)
    return {
        "judge": judge,
        "thought": thought,
        "request_type": request_type,
    }

def get_prompter(
    self, is_visual: bool, main_prompt: str, example_prompt: str, api_prompt: str
) -> FilterPrompter:
    """
    Get the prompt for the agent.
    :param is_visual: The flag indicating whether the agent is visual or not.
    :param main_prompt: The main prompt.
    :param example_prompt: The example prompt.
    :param api_prompt: The API prompt.
    :return: The prompt string.
    """

    return FilterPrompter(is_visual, main_prompt, example_prompt, api_prompt)

def message_constructor(self, request: str, app: str) -> List[str]:
    """
    Construct the prompt message for the FilterAgent.
    :param request: The request sentence.
    :param app: The name of the operated app.
    :return: The prompt message.
    """

    filter_agent_prompt_system_message = self.prompter.system_prompt_construction(
        app=app
    )
    filter_agent_prompt_user_message = self.prompter.user_content_construction(
        request
    )
    filter_agent_prompt_message = self.prompter.prompt_construction(
        filter_agent_prompt_system_message, filter_agent_prompt_user_message
    )

    return filter_agent_prompt_message

def process_comfirmation(self) -> None:
    """
    Confirm the process.
    This is the abstract method from BasicAgent that needs to be implemented.
    """

    pass