# Developer Guide: Key Components

This document describes the major classes and modules that form the core of the Asset Processor Tool.

## `ProcessingEngine` (`processing_engine.py`)

The `ProcessingEngine` class is the new core component responsible for executing the asset processing pipeline for a *single* input asset. Unlike the older `AssetProcessor`, this engine operates *solely* based on a complete `SourceRule` object provided to its `process()` method and the static `Configuration` object passed during initialization. It contains no internal prediction, classification, or fallback logic. Its key responsibilities include:

*   Setting up and cleaning up a temporary workspace for processing (potentially using `utils.workspace_utils`).
*   Extracting or copying input files to the workspace.
*   Processing files based on the explicit rules and predicted values contained within the input `SourceRule`.
*   Processing texture maps (resizing, format/bit depth conversion, inversion, stats calculation) using parameters from the `SourceRule` or static `Configuration`.
*   Merging channels based on rules defined in the static `Configuration` and parameters from the `SourceRule`.
*   Generating the `metadata.json` file containing details about the processed asset, incorporating information from the `SourceRule`.
*   Organizing the final output files into the structured library directory.

## `Rule Structure` (`rule_structure.py`)

This module defines the data structures used to represent the hierarchical processing rules:

*   `SourceRule`: A dataclass representing rules applied at the source level. It contains nested `AssetRule` objects.
*   `AssetRule`: A dataclass representing rules applied at the asset level. It contains nested `FileRule` objects.
*   `FileRule`: A dataclass representing rules applied at the file level.

These classes hold specific rule parameters (e.g., `supplier_identifier`, `asset_type`, `asset_type_override`, `item_type`, `item_type_override`, `target_asset_name_override`). Attributes like `asset_type` and `item_type_override` now use string types, which are validated against centralized lists in `config/app_settings.json`. These structures support serialization (Pickle, JSON) to allow them to be passed between different parts of the application, including across process boundaries.

## `Configuration` (`configuration.py`)

The `Configuration` class manages the tool's settings. It is responsible for:

*   Loading the core default settings defined in `config/app_settings.json`.
*   Loading the supplier-specific rules from a selected preset JSON file (`Presets/*.json`).
*   Merging the core settings and preset rules into a single, unified configuration object.
*   Validating the loaded configuration to ensure required settings are present.
*   Pre-compiling regular expression patterns defined in the preset for efficient file classification by the `PredictionHandler`.

An instance of the `Configuration` class is typically created once per application run (or per processing batch) and passed to the `ProcessingEngine`.

## GUI Components (`gui/`)

The GUI has been refactored into several key components:

### `MainWindow` (`gui/main_window.py`)

The `MainWindow` class acts as the main application window and **coordinator** for the GUI. Its primary responsibilities now include:

*   Setting up the main window structure and menu bar.
*   Instantiating and arranging the major GUI widgets:
    *   `MainPanelWidget` (containing core controls and the rule editor)
    *   `PresetEditorWidget`
    *   `LogConsoleWidget`
*   Connecting signals and slots between these widgets, the underlying models (`UnifiedViewModel`), and background handlers (`RuleBasedPredictionHandler`, `LLMPredictionHandler`, `LLMInteractionHandler`).
*   Managing the overall application state related to GUI interactions (e.g., enabling/disabling controls).
*   Handling top-level actions like loading sources (drag-and-drop), initiating predictions, and starting the processing task (via `main.ProcessingTask`).
*   Managing the `QThreadPool` for running background tasks (prediction).
*   Implementing slots like `_handle_prediction_completion` to update the model/view when prediction results are ready.

### `MainPanelWidget` (`gui/main_panel_widget.py`)

This widget contains the central part of the GUI, including:

*   Controls for loading source files/directories.
*   The preset selection dropdown.
*   Buttons for initiating prediction and processing.
*   The `RuleEditorWidget` which houses the hierarchical rule view.

### `PresetEditorWidget` (`gui/preset_editor_widget.py`)

This widget provides the interface for managing presets:

*   Loading, saving, and editing preset files (`Presets/*.json`).
*   Displaying preset rules and settings.

### `LogConsoleWidget` (`gui/log_console_widget.py`)

This widget displays application logs within the GUI:

*   Provides a text area for log messages.
*   Integrates with Python's `logging` system via a custom `QtLogHandler`.
*   Can be shown/hidden via the main window's "View" menu.

### `UnifiedViewModel` (`gui/unified_view_model.py`)

The `UnifiedViewModel` implements a `QAbstractItemModel` for use with Qt's model-view architecture. It is specifically designed to:

*   Wrap a list of `SourceRule` objects and expose their hierarchical structure (Source -> Asset -> File) to a `QTreeView` (the Unified Hierarchical View).
*   Provide methods (`data`, `index`, `parent`, `rowCount`, `columnCount`, `flags`, `setData`) required by `QAbstractItemModel` to allow the `QTreeView` to display the rule hierarchy and support inline editing of specific attributes (e.g., `supplier_override`, `asset_type_override`, `item_type_override`, `target_asset_name_override`).
*   Handle requests for data editing (`setData`) by validating input and updating the underlying `RuleHierarchyModel`. **Note:** Complex restructuring logic (e.g., moving files between assets when `target_asset_name_override` changes) is now delegated to the `AssetRestructureHandler`.
*   Determine row background colors based on the `asset_type` and `item_type`/`item_type_override` using color metadata from the `Configuration`.
*   Hold the `SourceRule` data (via `RuleHierarchyModel`) that is the single source of truth for the GUI's processing rules.
*   Cache configuration data (`ASSET_TYPE_DEFINITIONS`, `FILE_TYPE_DEFINITIONS`, color maps) during initialization for improved performance in the `data()` method.
*   Includes the `update_rules_for_sources` method, which intelligently merges new prediction results into the existing model data, preserving user overrides where possible.

### `RuleHierarchyModel` (`gui/rule_hierarchy_model.py`)

A simpler, non-Qt model used internally by `UnifiedViewModel` to manage the list of `SourceRule` objects and provide methods for accessing and modifying the hierarchy.

### `AssetRestructureHandler` (`gui/asset_restructure_handler.py`)

This handler contains the complex logic required to modify the `SourceRule` hierarchy when a file's target asset is changed via the GUI's `UnifiedViewModel`. It:

*   Is triggered by a signal (`targetAssetOverrideChanged`) from the `UnifiedViewModel`.
*   Uses dedicated methods on the `RuleHierarchyModel` (`moveFileRule`, `createAssetRule`, `removeAssetRule`) to safely move `FileRule` objects between `AssetRule`s, creating or removing `AssetRule`s as needed.
*   Ensures data consistency during these potentially complex restructuring operations.

### `Delegates` (`gui/delegates.py`)

This module contains custom `QStyledItemDelegate` implementations used by the Unified Hierarchical View (`QTreeView`) to provide inline editors for specific data types or rule attributes. Examples include delegates for:

*   `ComboBoxDelegate`: For selecting from predefined lists of allowed asset and file types, sourced from the `Configuration` (originally from `config/app_settings.json`).
*   `LineEditDelegate`: For free-form text editing, such as the `target_asset_name_override`.
*   `SupplierSearchDelegate`: For the "Supplier" column. Provides a `QLineEdit` with auto-completion suggestions loaded from `config/suppliers.json` and handles adding/saving new suppliers.

These delegates handle the presentation and editing of data within the tree view cells, interacting with the `UnifiedViewModel` to get and set data.

## Prediction Handlers (`gui/`)

Prediction logic is handled by classes inheriting from a common base class, running in background threads.

### `BasePredictionHandler` (`gui/base_prediction_handler.py`)

An abstract base class (`QRunnable`) for prediction handlers. It defines the common structure and signals (`prediction_signal`) used by specific predictor implementations. It's designed to be run in a `QThreadPool`.

### `RuleBasedPredictionHandler` (`gui/prediction_handler.py`)

This class (inheriting from `BasePredictionHandler`) is responsible for generating the initial `SourceRule` hierarchy using predefined rules from presets. It:

*   Takes an input source identifier, file list, and `Configuration` object.
*   Analyzes files based on regex patterns and rules defined in the loaded preset.
*   Constructs a `SourceRule` hierarchy with predicted values.
*   Emits the `prediction_signal` with the generated `SourceRule` object.

### `LLMPredictionHandler` (`gui/llm_prediction_handler.py`)

An experimental predictor (inheriting from `BasePredictionHandler`) that uses a Large Language Model (LLM). It:

*   Takes an input source identifier, file list, and `Configuration` object.
*   Interacts with the `LLMInteractionHandler` to send data to the LLM and receive predictions.
*   Parses the LLM response to construct a `SourceRule` hierarchy.
*   Emits the `prediction_signal` with the generated `SourceRule` object.

### `LLMInteractionHandler` (`gui/llm_interaction_handler.py`)

This class manages the specifics of communicating with the configured LLM API:

*   Handles constructing prompts based on templates and input data.
*   Sends requests to the LLM endpoint.
*   Receives and potentially pre-processes the LLM's response before returning it to the `LLMPredictionHandler`.

## Utility Modules (`utils/`)

Common utility functions have been extracted into separate modules:

### `workspace_utils.py`

Contains functions related to managing the processing workspace:

*   `prepare_processing_workspace`: Creates temporary directories, extracts archive files (ZIP, RAR, 7z), and returns the path to the prepared workspace. Used by `main.ProcessingTask` and `monitor.py`.

### `prediction_utils.py`

Contains utility functions supporting prediction tasks:

*   `generate_source_rule_from_archive`: A helper function used by `monitor.py` to perform rule-based prediction directly on an archive file without needing the full GUI setup. It extracts files temporarily, runs prediction logic similar to `RuleBasedPredictionHandler`, and returns a `SourceRule`.

## Monitor (`monitor.py`)

The `monitor.py` script implements the directory monitoring feature. It has been refactored to:

*   Use `watchdog` to detect new archive files in the input directory.
*   Use a `ThreadPoolExecutor` to process detected archives asynchronously in a `_process_archive_task` function.
*   Within the task, it:
    *   Loads the necessary `Configuration`.
    *   Calls `utils.prediction_utils.generate_source_rule_from_archive` to get the `SourceRule`.
    *   Calls `utils.workspace_utils.prepare_processing_workspace` to set up the workspace.
    *   Instantiates and runs the `ProcessingEngine`.
    *   Handles moving the source archive to 'processed' or 'error' directories.
    *   Cleans up the workspace.

## Summary

These key components, along with the refactored GUI structure and new utility modules, work together to provide the tool's functionality. The architecture emphasizes separation of concerns (configuration, rule generation, processing, UI), utilizes background processing for responsiveness (GUI prediction, Monitor tasks), and relies on the `SourceRule` object as the central data structure passed between different stages of the workflow.