feat: add v0.9.8 release notes and update version

- Pass ModelUpdateService to CheckpointService, EmbeddingService, and LoraService constructors
- Add has_update query parameter filter to model listing handler
- Update BaseModelService to accept optional update_service parameter

These changes enable model update functionality across different model types and provide filtering capability for models with available updates.

.github/workflows/backend-tests.yml

@@ -0,0 +1,69 @@
+name: Backend Tests
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'py/**'
+      - 'standalone.py'
+      - 'tests/**'
+      - 'requirements.txt'
+      - 'requirements-dev.txt'
+      - 'pyproject.toml'
+      - 'pytest.ini'
+      - '.github/workflows/backend-tests.yml'
+  pull_request:
+    paths:
+      - 'py/**'
+      - 'standalone.py'
+      - 'tests/**'
+      - 'requirements.txt'
+      - 'requirements-dev.txt'
+      - 'pyproject.toml'
+      - 'pytest.ini'
+      - '.github/workflows/backend-tests.yml'
+
+jobs:
+  pytest:
+    name: Run pytest with coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Run pytest with coverage
+        env:
+          COVERAGE_FILE: coverage/backend/.coverage
+        run: |
+          mkdir -p coverage/backend
+          python -m pytest \
+            --cov=py \
+            --cov=standalone \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage/backend/coverage.xml \
+            --cov-report=html:coverage/backend/html \
+            --cov-report=json:coverage/backend/coverage.json
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: backend-coverage
+          path: coverage/backend
+          if-no-files-found: warn

.github/workflows/frontend-tests.yml

@@ -0,0 +1,52 @@
+name: Frontend Tests
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - 'vitest.config.js'
+      - 'tests/frontend/**'
+      - 'static/js/**'
+      - 'scripts/run_frontend_coverage.js'
+      - '.github/workflows/frontend-tests.yml'
+  pull_request:
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - 'vitest.config.js'
+      - 'tests/frontend/**'
+      - 'static/js/**'
+      - 'scripts/run_frontend_coverage.js'
+      - '.github/workflows/frontend-tests.yml'
+
+jobs:
+  vitest:
+    name: Run Vitest with coverage
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run frontend tests with coverage
+        run: npm run test:coverage
+
+      - name: Upload coverage artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: frontend-coverage
+          path: coverage/frontend
+          if-no-files-found: warn

.gitignore

@@ -5,3 +5,7 @@ output/*
 py/run_test.py
 .vscode/
 cache/
+civitai/
+node_modules/
+coverage/
+.coverage

AGENTS.md

@@ -0,0 +1,22 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+ComfyUI LoRA Manager pairs a Python backend with browser-side widgets. Backend modules live in <code>py/</code> with HTTP entry points in <code>py/routes/</code>, feature logic in <code>py/services/</code>, shared helpers in <code>py/utils/</code>, and custom nodes in <code>py/nodes/</code>. UI scripts extend ComfyUI from <code>web/comfyui/</code>, while deploy-ready assets remain in <code>static/</code> and <code>templates/</code>. Localization files live in <code>locales/</code>, example workflows in <code>example_workflows/</code>, and interim tests such as <code>test_i18n.py</code> sit beside their source until a dedicated <code>tests/</code> tree lands.
+
+## Build, Test, and Development Commands
+- <code>pip install -r requirements.txt</code> installs backend dependencies.
+- <code>python standalone.py --port 8188</code> launches the standalone server for iterative development.
+- <code>python -m pytest test_i18n.py</code> runs the current regression suite; target new files explicitly, e.g. <code>python -m pytest tests/test_recipes.py</code>.
+- <code>python scripts/sync_translation_keys.py</code> synchronizes locale keys after UI string updates.
+
+## Coding Style & Naming Conventions
+Follow PEP 8 with four-space indentation and descriptive snake_case file and function names such as <code>settings_manager.py</code>. Classes stay PascalCase, constants in UPPER_SNAKE_CASE, and loggers retrieved via <code>logging.getLogger(__name__)</code>. Prefer explicit type hints and docstrings on public APIs. JavaScript under <code>web/comfyui/</code> uses ES modules with camelCase helpers and the <code>_widget.js</code> suffix for UI components.
+
+## Testing Guidelines
+Pytest powers backend tests. Name modules <code>test_<feature>.py</code> and keep them near the code or in a future <code>tests/</code> package. Mock ComfyUI dependencies through helpers in <code>standalone.py</code>, keep filesystem fixtures deterministic, and ensure translations are covered. Run <code>python -m pytest</code> before submitting changes.
+
+## Commit & Pull Request Guidelines
+Commits follow the conventional format, e.g. <code>feat(settings): add default model path</code>, and should stay focused on a single concern. Pull requests must outline the problem, summarize the solution, list manual verification steps (server run, targeted pytest), and link related issues. Include screenshots or GIFs for UI or locale updates and call out migration steps such as <code>settings.json</code> adjustments.
+
+## Configuration & Localization Tips
+Copy <code>settings.json.example</code> to <code>settings.json</code> and adapt model directories before running the standalone server. Store reference assets in <code>civitai/</code> or <code>docs/</code> to keep runtime directories deploy-ready. Whenever UI text changes, update every <code>locales/&lt;lang&gt;.json</code> file and rerun the translation sync script so ComfyUI surfaces localized strings.

IFLOW.md

@@ -0,0 +1,103 @@
+# ComfyUI LoRA Manager - iFlow 上下文
+
+## 项目概述
+
+ComfyUI LoRA Manager 是一个全面的工具集，用于简化 ComfyUI 中 LoRA 模型的组织、下载和应用。它提供了强大的功能，如配方管理、检查点组织和一键工作流集成，使模型操作更快、更流畅、更简单。
+
+该项目是一个 Python 后端与 JavaScript 前端结合的 Web 应用程序，既可以作为 ComfyUI 的自定义节点运行，也可以作为独立应用程序运行。
+
+## 项目结构
+
+```
+D:\Workspace\ComfyUI\custom_nodes\ComfyUI-Lora-Manager\
+├── py/                 # Python 后端代码
+│   ├── config.py       # 全局配置
+│   ├── lora_manager.py # 主入口点
+│   ├── controllers/    # 控制器
+│   ├── metadata_collector/ # 元数据收集器
+│   ├── middleware/     # 中间件
+│   ├── nodes/          # ComfyUI 节点
+│   ├── recipes/        # 配方相关
+│   ├── routes/         # API 路由
+│   ├── services/       # 业务逻辑服务
+│   ├── utils/          # 工具函数
+│   └── validators/     # 验证器
+├── static/             # 静态资源 (CSS, JS, 图片)
+├── templates/          # HTML 模板
+├── locales/            # 国际化文件
+├── tests/              # 测试代码
+├── standalone.py       # 独立模式入口
+├── requirements.txt    # Python 依赖
+├── package.json        # Node.js 依赖和脚本
+└── README.md           # 项目说明
+```
+
+## 核心组件
+
+### 后端 (Python)
+
+- **主入口**: `py/lora_manager.py` 和 `standalone.py`
+- **配置**: `py/config.py` 管理全局配置和路径
+- **路由**: `py/routes/` 目录下包含各种 API 路由
+- **服务**: `py/services/` 目录下包含业务逻辑，如模型扫描、下载管理等
+- **模型管理**: 使用 `ModelServiceFactory` 来管理不同类型的模型 (LoRA, Checkpoint, Embedding)
+
+### 前端 (JavaScript)
+
+- **构建工具**: 使用 Node.js 和 npm 进行依赖管理和测试
+- **测试**: 使用 Vitest 进行前端测试
+
+## 构建和运行
+
+### 安装依赖
+
+```bash
+# Python 依赖
+pip install -r requirements.txt
+
+# Node.js 依赖 (用于测试)
+npm install
+```
+
+### 运行 (ComfyUI 模式)
+
+作为 ComfyUI 的自定义节点安装后，在 ComfyUI 中启动即可。
+
+### 运行 (独立模式)
+
+```bash
+# 使用默认配置运行
+python standalone.py
+
+# 指定主机和端口
+python standalone.py --host 127.0.0.1 --port 9000
+```
+
+### 测试
+
+#### 后端测试
+
+```bash
+# 安装开发依赖
+pip install -r requirements-dev.txt
+
+# 运行测试
+pytest
+```
+
+#### 前端测试
+
+```bash
+# 运行测试
+npm run test
+
+# 运行测试并生成覆盖率报告
+npm run test:coverage
+```
+
+## 开发约定
+
+- **代码风格**: Python 代码应遵循 PEP 8 规范
+- **测试**: 新功能应包含相应的单元测试
+- **配置**: 使用 `settings.json` 文件进行用户配置
+- **日志**: 使用 Python 标准库 `logging` 模块进行日志记录

README.md

@@ -34,6 +34,28 @@ Enhance your Civitai browsing experience with our companion browser extension! S
 
 ## Release Notes
 
+### v0.9.8
+* **Full CivArchive API Support** - Added complete support for the CivArchive API as a fallback metadata source beyond Civitai API. Models deleted from Civitai can now still retrieve metadata through the CivArchive API.
+* **Download Models from CivArchive** - Added support for downloading models directly from CivArchive, similar to downloading from Civitai. Simply click the Download button and paste the model URL to download the corresponding model.
+* **Custom Priority Tags** - Introduced Custom Priority Tags feature, allowing users to define custom priority tags. These tags will appear as suggestions when editing tags or during auto organization/download using default paths, providing more precise and controlled folder organization. [Guide](https://github.com/willmiao/ComfyUI-Lora-Manager/wiki/Priority-Tags-Configuration-Guide)
+* **Drag and Drop Tag Reordering** - Added drag and drop functionality to reorder tags in the tags edit mode for improved usability.
+* **Download Control in Example Images Panel** - Added stop control in the Download Example Images Panel for better download management.
+* **Prompt (LoraManager) Node with Autocomplete** - Added new Prompt (LoraManager) node with autocomplete feature for adding embeddings.
+* **Lora Manager Nodes in Subgraphs** - Lora Manager nodes now support being placed within subgraphs for more flexible workflow organization.
+
+### v0.9.6
+* **Metadata Archive Database Support** - Added the ability to download and utilize a metadata archive database, enabling access to metadata for models that have been deleted from CivitAI.
+* **App-Level Proxy Settings** - Introduced support for configuring a global proxy within the application, making it easier to use the manager behind network restrictions.
+* **Bug Fixes** - Various bug fixes for improved stability and reliability.
+
+### v0.9.2
+* **Bulk Auto-Organization Action** - Added a new bulk auto-organization feature. You can now select multiple models and automatically organize them according to your current path template settings for streamlined management.
+* **Bug Fixes** - Addressed several bugs to improve stability and reliability.
+
+### v0.9.1
+* **Enhanced Bulk Operations** - Improved bulk operations with Marquee Selection and a bulk operation context menu, providing a more intuitive, desktop-application-like user experience.
+* **New Bulk Actions** - Added bulk operations for adding tags and setting base models to multiple models simultaneously.
+
 ### v0.9.0
 * **UI Overhaul for Enhanced Navigation** - Replaced the top flat folder tags with a new folder sidebar and breadcrumb navigation system for a more intuitive folder browsing and selection experience.
 * **Dual-Mode Folder Sidebar** - The new folder sidebar offers two display modes: 'List Mode,' which mirrors the classic folder view, and 'Tree Mode,' which presents a hierarchical folder structure for effortless navigation through nested directories.
@@ -69,61 +91,6 @@ Enhance your Civitai browsing experience with our companion browser extension! S
 * **Enhanced Node Usability** - Improved user experience for Lora Loader, Lora Stacker, and WanVideo Lora Select nodes by fixing the maximum height of the text input area. Users can now freely and conveniently adjust the LoRA region within these nodes.
 * **Compatibility Fixes** - Resolved compatibility issues with ComfyUI and certain custom nodes, including ComfyUI-Custom-Scripts, ensuring smoother integration and operation.
 
-### v0.8.25
-* **LoRA List Reordering**  
-  - Drag & Drop: Easily rearrange LoRA entries using the drag handle.
-  - Keyboard Shortcuts:  
-    - Arrow keys: Navigate between LoRAs  
-    - Ctrl/Cmd + Arrow: Move selected LoRA up/down  
-    - Ctrl/Cmd + Home/End: Move selected LoRA to top/bottom  
-    - Delete/Backspace: Remove selected LoRA  
-  - Context Menu: Right-click for quick actions like Move Up, Move Down, Move to Top, Move to Bottom.
-* **Bulk Operations for Checkpoints & Embeddings**  
-  - Bulk Mode: Select multiple checkpoints or embeddings for batch actions.
-  - Bulk Refresh: Update Civitai metadata for selected models.
-  - Bulk Delete: Remove multiple models at once.
-  - Bulk Move (Embeddings): Move selected embeddings to a different folder.
-* **New Setting: Auto Download Example Images**  
-  - Automatically fetch example images for models missing previews (requires download location to be set). Enabled by default.
-* **General Improvements**  
-  - Various user experience enhancements and stability fixes.
-
-### v0.8.22
-* **Embeddings Management** - Added Embeddings page for comprehensive embedding model management.
-* **Advanced Sorting Options** - Introduced flexible sorting controls, allowing sorting by name, added date, or file size in both ascending and descending order.
-* **Custom Download Path Templates & Base Model Mapping** - Implemented UI settings for configuring download path templates and base model path mappings, allowing customized model organization and storage location when downloading models via LM Civitai Extension.
-* **LM Civitai Extension Enhancements** - Improved concurrent download performance and stability, with new support for canceling active downloads directly from the extension interface.
-* **Update Feature** - Added update functionality, allowing users to update LoRA Manager to the latest release version directly from the LoRA Manager UI.
-* **Bulk Operations: Refresh All** - Added bulk refresh functionality, allowing users to update Civitai metadata across multiple LoRAs.
-
-### v0.8.20
-* **LM Civitai Extension** - Released [browser extension through Chrome Web Store](https://chromewebstore.google.com/detail/lm-civitai-extension/capigligggeijgmocnaflanlbghnamgm?utm_source=item-share-cb) that works seamlessly with LoRA Manager to enhance Civitai browsing experience, showing which models are already in your local library, enabling one-click downloads, and providing queue and parallel download support
-* **Enhanced Lora Loader** - Added support for nunchaku, improving convenience when working with ComfyUI-nunchaku workflows, plus new template workflows for quick onboarding
-* **WanVideo Integration** - Introduced WanVideo Lora Select (LoraManager) node compatible with ComfyUI-WanVideoWrapper for streamlined lora usage in video workflows, including a template workflow to help you get started quickly
-
-### v0.8.19
-* **Analytics Dashboard** - Added new Statistics page providing comprehensive visual analysis of model collection and usage patterns for better library insights
-* **Target Node Selection** - Enhanced workflow integration with intelligent target choosing when sending LoRAs/recipes to workflows with multiple loader/stacker nodes; a visual selector now appears showing node color, type, ID, and title for precise targeting
-* **Enhanced NSFW Controls** - Added support for setting NSFW levels on recipes with automatic content blurring based on user preferences
-* **Customizable Card Display** - New display settings allowing users to choose whether card information and action buttons are always visible or only revealed on hover
-* **Expanded Compatibility** - Added support for efficiency-nodes-comfyui in Save Recipe and Save Image nodes, plus fixed compatibility with ComfyUI_Custom_Nodes_AlekPet
-
-### v0.8.18
-* **Custom Example Images** - Added ability to import your own example images for LoRAs and checkpoints with automatic metadata extraction from embedded information
-* **Enhanced Example Management** - New action buttons to set specific examples as previews or delete custom examples
-* **Improved Duplicate Detection** - Enhanced "Find Duplicates" with hash verification feature to eliminate false positives when identifying duplicate models
-* **Tag Management** - Added tag editing functionality allowing users to customize and manage model tags
-* **Advanced Selection Controls** - Implemented Ctrl+A shortcut for quickly selecting all filtered LoRAs, automatically entering bulk mode when needed
-* **Note**: Cache file functionality temporarily disabled pending rework
-
-### v0.8.17
-* **Duplicate Model Detection** - Added "Find Duplicates" functionality for LoRAs and checkpoints using model file hash detection, enabling convenient viewing and batch deletion of duplicate models
-* **Enhanced URL Recipe Imports** - Optimized import recipe via URL functionality using CivitAI API calls instead of web scraping, now supporting all rated images (including NSFW) for recipe imports
-* **Improved TriggerWord Control** - Enhanced TriggerWord Toggle node with new default_active switch to set the initial state (active/inactive) when trigger words are added
-* **Centralized Example Management** - Added "Migrate Existing Example Images" feature to consolidate downloaded example images from model folders into central storage with customizable naming patterns
-* **Intelligent Word Suggestions** - Implemented smart trigger word suggestions by reading class tokens and tag frequency from safetensors files, displaying recommendations when editing trigger words
-* **Model Version Management** - Added "Re-link to CivitAI" context menu option for connecting models to different CivitAI versions when needed
-
 [View Update History](./update_logs.md)
 
 ---
@@ -181,9 +148,9 @@ Enhance your Civitai browsing experience with our companion browser extension! S
 
 ### Option 2: **Portable Standalone Edition** (No ComfyUI required)
 
-1. Download the [Portable Package](https://github.com/willmiao/ComfyUI-Lora-Manager/releases/download/v0.8.26/lora_manager_portable.7z)
+1. Download the [Portable Package](https://github.com/willmiao/ComfyUI-Lora-Manager/releases/download/v0.9.2/lora_manager_portable.7z)
 2. Copy the provided `settings.json.example` file to create a new file named `settings.json` in `comfyui-lora-manager` folder
-3. Edit `settings.json` to include your correct model folder paths and CivitAI API key
+3. Edit the new `settings.json` to include your correct model folder paths and CivitAI API key
 4. Run run.bat
     - To change the startup port, edit `run.bat` and modify the parameter (e.g. `--port 9001`)
 
@@ -251,7 +218,7 @@ You can combine multiple patterns to create detailed, organized filenames for yo
 You can now run LoRA Manager independently from ComfyUI:
 
 1. **For ComfyUI users**:
-   - Launch ComfyUI with LoRA Manager at least once to initialize the necessary path information in the `settings.json` file.
+   - Launch ComfyUI with LoRA Manager at least once to initialize the necessary path information in the `settings.json` file located in your user settings folder (see paths above).
    - Make sure dependencies are installed: `pip install -r requirements.txt`
    - From your ComfyUI root directory, run:
      ```bash
@@ -273,8 +240,37 @@ You can now run LoRA Manager independently from ComfyUI:
      ```
    - Access the interface through your browser at: `http://localhost:8188/loras`
 
+   > **Note:** Existing installations automatically migrate the legacy `settings.json` from the plugin folder to the user settings directory the first time you launch this version.
+
 This standalone mode provides a lightweight option for managing your model and recipe collection without needing to run the full ComfyUI environment, making it useful even for users who primarily use other stable diffusion interfaces.
 
+## Testing & Coverage
+
+### Backend
+
+Install the development dependencies and run pytest with coverage reports:
+
+```bash
+pip install -r requirements-dev.txt
+COVERAGE_FILE=coverage/backend/.coverage pytest \
+  --cov=py \
+  --cov=standalone \
+  --cov-report=term-missing \
+  --cov-report=html:coverage/backend/html \
+  --cov-report=xml:coverage/backend/coverage.xml \
+  --cov-report=json:coverage/backend/coverage.json
+```
+
+HTML, XML, and JSON artifacts are stored under `coverage/backend/` so you can inspect hot spots locally or from CI artifacts.
+
+### Frontend
+
+Run the Vitest coverage suite to analyze widget hot spots:
+
+```bash
+npm run test:coverage
+```
+
 ---
 
 ## Contributing

__init__.py

@@ -1,21 +1,45 @@
-from .py.lora_manager import LoraManager
-from .py.nodes.lora_loader import LoraManagerLoader, LoraManagerTextLoader
-from .py.nodes.trigger_word_toggle import TriggerWordToggle
-from .py.nodes.lora_stacker import LoraStacker
-from .py.nodes.save_image import SaveImage
-from .py.nodes.debug_metadata import DebugMetadata
-from .py.nodes.wanvideo_lora_select import WanVideoLoraSelect
-# Import metadata collector to install hooks on startup
-from .py.metadata_collector import init as init_metadata_collector
+try:  # pragma: no cover - import fallback for pytest collection
+    from .py.lora_manager import LoraManager
+    from .py.nodes.lora_loader import LoraManagerLoader, LoraManagerTextLoader
+    from .py.nodes.trigger_word_toggle import TriggerWordToggle
+    from .py.nodes.prompt import PromptLoraManager
+    from .py.nodes.lora_stacker import LoraStacker
+    from .py.nodes.save_image import SaveImage
+    from .py.nodes.debug_metadata import DebugMetadata
+    from .py.nodes.wanvideo_lora_select import WanVideoLoraSelect
+    from .py.nodes.wanvideo_lora_select_from_text import WanVideoLoraSelectFromText
+    from .py.metadata_collector import init as init_metadata_collector
+except ImportError:  # pragma: no cover - allows running under pytest without package install
+    import importlib
+    import pathlib
+    import sys
+
+    package_root = pathlib.Path(__file__).resolve().parent
+    if str(package_root) not in sys.path:
+        sys.path.append(str(package_root))
+
+    PromptLoraManager = importlib.import_module("py.nodes.prompt").PromptLoraManager
+    LoraManager = importlib.import_module("py.lora_manager").LoraManager
+    LoraManagerLoader = importlib.import_module("py.nodes.lora_loader").LoraManagerLoader
+    LoraManagerTextLoader = importlib.import_module("py.nodes.lora_loader").LoraManagerTextLoader
+    TriggerWordToggle = importlib.import_module("py.nodes.trigger_word_toggle").TriggerWordToggle
+    LoraStacker = importlib.import_module("py.nodes.lora_stacker").LoraStacker
+    SaveImage = importlib.import_module("py.nodes.save_image").SaveImage
+    DebugMetadata = importlib.import_module("py.nodes.debug_metadata").DebugMetadata
+    WanVideoLoraSelect = importlib.import_module("py.nodes.wanvideo_lora_select").WanVideoLoraSelect
+    WanVideoLoraSelectFromText = importlib.import_module("py.nodes.wanvideo_lora_select_from_text").WanVideoLoraSelectFromText
+    init_metadata_collector = importlib.import_module("py.metadata_collector").init
 
 NODE_CLASS_MAPPINGS = {
+    PromptLoraManager.NAME: PromptLoraManager,
     LoraManagerLoader.NAME: LoraManagerLoader,
     LoraManagerTextLoader.NAME: LoraManagerTextLoader,
     TriggerWordToggle.NAME: TriggerWordToggle,
     LoraStacker.NAME: LoraStacker,
     SaveImage.NAME: SaveImage,
     DebugMetadata.NAME: DebugMetadata,
-    WanVideoLoraSelect.NAME: WanVideoLoraSelect
+    WanVideoLoraSelect.NAME: WanVideoLoraSelect,
+    WanVideoLoraSelectFromText.NAME: WanVideoLoraSelectFromText
 }
 
 WEB_DIRECTORY = "./web/comfyui"

docs/LM-Extension-Wiki.md

@@ -0,0 +1,180 @@
+## Overview
+
+The **LoRA Manager Civitai Extension** is a Browser extension designed to work seamlessly with [LoRA Manager](https://github.com/willmiao/ComfyUI-Lora-Manager) to significantly enhance your browsing experience on [Civitai](https://civitai.com).
+It also supports browsing on [CivArchive](https://civarchive.com/) (formerly CivitaiArchive).
+
+With this extension, you can:
+
+✅ Instantly see which models are already present in your local library  
+✅ Download new models with a single click  
+✅ Manage downloads efficiently with queue and parallel download support  
+✅ Keep your downloaded models automatically organized according to your custom settings    
+
+![Civitai Models page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civitai-models-page.png)  
+![CivArchive Models page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civarchive-models-page.png)  
+
+---
+
+## Why Are All Features for Supporters Only?
+
+I love building tools for the Stable Diffusion and ComfyUI communities, and LoRA Manager is a passion project that I've poured countless hours into. When I created this companion extension, my hope was to offer its core features for free, as a thank-you to all of you.
+
+Unfortunately, I've reached a point where I need to be realistic. The level of support from the free model has been far lower than what's needed to justify the continuous development and maintenance for both projects. It was a difficult decision, but I've chosen to make the extension's features exclusive to supporters.
+
+This change is crucial for me to be able to continue dedicating my time to improving the free and open-source LoRA Manager, which I'm committed to keeping available for everyone.
+
+Your support does more than just unlock a few features—it allows me to keep innovating and ensures the core LoRA Manager project thrives. I'm incredibly grateful for your understanding and any support you can offer. ❤️
+
+(_For those who previously supported me on Ko-fi with a one-time donation, I'll be sending out license keys individually as a thank-you._)
+
+
+---
+
+## Installation
+
+### Supported Browsers & Installation Methods
+
+| Browser            | Installation Method                                                                 |
+|--------------------|-------------------------------------------------------------------------------------|
+| **Google Chrome**   | [Chrome Web Store link](https://chromewebstore.google.com/detail/capigligggeijgmocnaflanlbghnamgm?utm_source=item-share-cb) |
+| **Microsoft Edge**  | Install via Chrome Web Store (compatible)                                          |
+| **Brave Browser**   | Install via Chrome Web Store (compatible)                                          |
+| **Opera**           | Install via Chrome Web Store (compatible)                                          |
+| **Firefox**         | <div id="firefox-install" class="install-ok"><a href="https://github.com/willmiao/lm-civitai-extension-firefox/releases/latest/download/extension.xpi">📦 Install Firefox Extension (reviewed and verified by Mozilla)</a></div>             |
+
+For non-Chrome browsers (e.g., Microsoft Edge), you can typically install extensions from the Chrome Web Store by following these steps: open the extension’s Chrome Web Store page, click 'Get extension', then click 'Allow' when prompted to enable installations from other stores, and finally click 'Add extension' to complete the installation.
+
+---
+
+## Privacy & Security
+
+I understand concerns around browser extensions and privacy, and I want to be fully transparent about how the **LM Civitai Extension** works:
+
+- **Reviewed and Verified**  
+  This extension has been **manually reviewed and approved by the Chrome Web Store**. The Firefox version uses the **exact same code** (only the packaging format differs) and has passed **Mozilla’s Add-on review**.
+
+- **Minimal Network Access**  
+  The only external server this extension connects to is:  
+  **`https://willmiao.shop`** — used solely for **license validation**.
+
+  It does **not collect, transmit, or store any personal or usage data**.  
+  No browsing history, no user IDs, no analytics, no hidden trackers.
+
+- **Local-Only Model Detection**  
+  Model detection and LoRA Manager communication all happen **locally** within your browser, directly interacting with your local LoRA Manager backend.
+
+I value your trust and are committed to keeping your local setup private and secure. If you have any questions, feel free to reach out!
+
+---
+
+## How to Use
+
+After installing the extension, you'll automatically receive a **7-day trial** to explore all features.
+
+When the extension is correctly installed and your license is valid:
+
+- Open **Civitai**, and you'll see visual indicators added by the extension on model cards, showing:
+  - ✅ Models already present in your local library  
+  - ⬇️ A download button for models not in your library  
+
+Clicking the download button adds the corresponding model version to the download queue, waiting to be downloaded. You can set up to **5 models to download simultaneously**.
+
+### Visual Indicators Appear On:
+
+- **Home Page** — Featured models  
+- **Models Page**  
+- **Creator Profiles** — If the creator has set their models to be visible  
+- **Recommended Resources** — On individual model pages  
+
+### Version Buttons on Model Pages
+
+On a specific model page, visual indicators also appear on version buttons, showing which versions are already in your local library.
+
+When switching to a specific version by clicking a version button:
+
+- Clicking the download button will open a dropdown:
+  - Download via **LoRA Manager**  
+  - Download via **Original Download** (browser download)  
+
+You can check **Remember my choice** to set your preferred default. You can change this setting anytime in the extension's settings.
+
+![Civitai Model Page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civitai-model-page.png)
+
+### Resources on Image Pages (2025-08-05) — now shows in-library indicators for image resources. ‘Import image as recipe’ coming soon!
+
+![Civitai Image Page](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/civitai-image-page.jpg)
+
+---
+
+## Model Download Location & LoRA Manager Settings
+
+To use the **one-click download function**, you must first set:
+
+- Your **Default LoRAs Root**  
+- Your **Default Checkpoints Root**  
+
+These are set within LoRA Manager's settings.
+
+When everything is configured, downloaded model files will be placed in:  
+
+`<Default_Models_Root>/<Base_Model_of_the_Model>/<First_Tag_of_the_Model>`
+
+
+### Update: Default Path Customization (2025-07-21)  
+
+A new setting to customize the default download path has been added in the nightly version. You can now personalize where models are saved when downloading via the LM Civitai Extension.
+
+![Default Path Customization](https://github.com/willmiao/ComfyUI-Lora-Manager/blob/main/wiki-images/default-path-customization.png)
+
+The previous YAML path mapping file will be deprecated—settings will now be unified in settings.json to simplify configuration.
+
+---
+
+## Backend Port Configuration
+
+If your **ComfyUI** or **LoRA Manager** backend is running on a port **other than the default 8188**, you must configure the backend port in the extension's settings.
+
+After correctly setting and saving the port, you'll see in the extension's header area:  
+- A **Healthy** status with the tooltip:  `Connected to LoRA Manager on port xxxx`
+
+
+---
+
+## Advanced Usage
+
+### Connecting to a Remote LoRA Manager
+
+If your LoRA Manager is running on another computer, you can still connect from your browser using port forwarding.
+
+> **Why can't you set a remote IP directly?**
+>
+> For privacy and security, the extension only requests access to `http://127.0.0.1/*`. Supporting remote IPs would require much broader permissions, which may be rejected by browser stores and could raise user concerns.
+
+**Solution: Port Forwarding with `socat`**
+
+On your browser computer, run:
+
+`socat TCP-LISTEN:8188,bind=127.0.0.1,fork TCP:REMOTE.IP.ADDRESS.HERE:8188`
+
+- Replace `REMOTE.IP.ADDRESS.HERE` with the IP of the machine running LoRA Manager.
+- Adjust the port if needed.
+
+This lets the extension connect to `127.0.0.1:8188` as usual, with traffic forwarded to your remote server.
+
+_Thanks to user **Temikus** for sharing this solution!_
+
+---
+
+## Roadmap
+
+The extension will evolve alongside **LoRA Manager** improvements. Planned features include:
+
+- [x] Support for **additional model types** (e.g., embeddings)
+- [ ] One-click **Recipe Import**  
+- [x] Display of in-library status for all resources in the **Resources Used** section of the image page  
+- [x] One-click **Auto-organize Models**
+
+**Stay tuned — and thank you for your support!**
+
+---
+

docs/architecture/example_images_routes.md

@@ -0,0 +1,93 @@
+# Example image route architecture
+
+The example image routing stack mirrors the layered model route stack described in
+[`docs/architecture/model_routes.md`](model_routes.md). HTTP wiring, controller setup,
+handler orchestration, and long-running workflows now live in clearly separated modules so
+we can extend download/import behaviour without touching the entire feature surface.
+
+```mermaid
+graph TD
+    subgraph HTTP
+        A[ExampleImagesRouteRegistrar] -->|binds| B[ExampleImagesRoutes controller]
+    end
+    subgraph Application
+        B --> C[ExampleImagesHandlerSet]
+        C --> D1[Handlers]
+        D1 --> E1[Use cases]
+        E1 --> F1[Download manager / processor / file manager]
+    end
+    subgraph Side Effects
+        F1 --> G1[Filesystem]
+        F1 --> G2[Model metadata]
+        F1 --> G3[WebSocket progress]
+    end
+```
+
+## Layer responsibilities
+
+| Layer | Module(s) | Responsibility |
+| --- | --- | --- |
+| Registrar | `py/routes/example_images_route_registrar.py` | Declarative catalogue of every example image endpoint plus helpers that bind them to an `aiohttp` router. Keeps HTTP concerns symmetrical with the model registrar. |
+| Controller | `py/routes/example_images_routes.py` | Lazily constructs `ExampleImagesHandlerSet`, injects defaults for the download manager, processor, and file manager, and exposes the registrar-ready mapping just like `BaseModelRoutes`. |
+| Handler set | `py/routes/handlers/example_images_handlers.py` | Groups HTTP adapters by concern (downloads, imports/deletes, filesystem access). Each handler translates domain errors into HTTP responses and defers to a use case or utility service. |
+| Use cases | `py/services/use_cases/example_images/*.py` | Encapsulate orchestration for downloads and imports. They validate input, translate concurrency/configuration errors, and keep handler logic declarative. |
+| Supporting services | `py/utils/example_images_download_manager.py`, `py/utils/example_images_processor.py`, `py/utils/example_images_file_manager.py` | Execute long-running work: pull assets from Civitai, persist uploads, clean metadata, expose filesystem actions with guardrails, and broadcast progress snapshots. |
+
+## Handler responsibilities & invariants
+
+`ExampleImagesHandlerSet` flattens the handler objects into the `{"handler_name": coroutine}`
+mapping consumed by the registrar. The table below outlines how each handler collaborates
+with the use cases and utilities.
+
+| Handler | Key endpoints | Collaborators | Contracts |
+| --- | --- | --- | --- |
+| `ExampleImagesDownloadHandler` | `/api/lm/download-example-images`, `/api/lm/example-images-status`, `/api/lm/pause-example-images`, `/api/lm/resume-example-images`, `/api/lm/force-download-example-images` | `DownloadExampleImagesUseCase`, `DownloadManager` | Delegates payload validation and concurrency checks to the use case; progress/status endpoints expose the same snapshot used for WebSocket broadcasts; pause/resume surface `DownloadNotRunningError` as HTTP 400 instead of 500. |
+| `ExampleImagesManagementHandler` | `/api/lm/import-example-images`, `/api/lm/delete-example-image` | `ImportExampleImagesUseCase`, `ExampleImagesProcessor` | Multipart uploads are streamed to disk via the use case; validation failures return HTTP 400 with no filesystem side effects; deletion funnels through the processor to prune metadata and cached images consistently. |
+| `ExampleImagesFileHandler` | `/api/lm/open-example-images-folder`, `/api/lm/example-image-files`, `/api/lm/has-example-images` | `ExampleImagesFileManager` | Centralises filesystem access, enforcing settings-based root paths and returning HTTP 400/404 for missing configuration or folders; responses always include `success`/`has_images` booleans for UI consumption. |
+
+## Use case boundaries
+
+| Use case | Entry point | Dependencies | Guarantees |
+| --- | --- | --- | --- |
+| `DownloadExampleImagesUseCase` | `execute(payload)` | `DownloadManager.start_download`, download configuration errors | Raises `DownloadExampleImagesInProgressError` when the manager reports an active job, rewraps configuration errors into `DownloadExampleImagesConfigurationError`, and lets `ExampleImagesDownloadError` bubble as 500s so handlers do not duplicate logging. |
+| `ImportExampleImagesUseCase` | `execute(request)` | `ExampleImagesProcessor.import_images`, temporary file helpers | Supports multipart or JSON payloads, normalises file paths into a single list, cleans up temp files even on failure, and maps validation issues to `ImportExampleImagesValidationError` for HTTP 400 responses. |
+
+## Maintaining critical invariants
+
+* **Shared progress snapshots** - The download handler returns the same snapshot built by
+  `DownloadManager`, guaranteeing parity between HTTP polling endpoints and WebSocket
+  progress events.
+* **Safe filesystem access** - All folder/file actions flow through
+  `ExampleImagesFileManager`, which validates the configured example image root and ensures
+  responses never leak absolute paths outside the allowed directory.
+* **Metadata hygiene** - Import/delete operations run through `ExampleImagesProcessor`,
+  which updates model metadata via `MetadataManager` and notifies the relevant scanners so
+  cache state stays in sync.
+
+## Migration notes
+
+The refactor brings the example image stack in line with the model/recipe stacks:
+
+1. `ExampleImagesRouteRegistrar` now owns the declarative route list. Downstream projects
+   should rely on `ExampleImagesRoutes.to_route_mapping()` instead of manually wiring
+   handler callables.
+2. `ExampleImagesRoutes` caches its `ExampleImagesHandlerSet` just like
+   `BaseModelRoutes`. If you previously instantiated handlers directly, inject custom
+   collaborators via the controller constructor (`download_manager`, `processor`,
+   `file_manager`) to keep test seams predictable.
+3. Tests that mocked `ExampleImagesRoutes.setup_routes` should switch to patching
+   `DownloadExampleImagesUseCase`/`ImportExampleImagesUseCase` at import time. The handlers
+   expect those abstractions to surface validation/concurrency errors, and bypassing them
+   will skip the HTTP-friendly error mapping.
+
+## Extending the stack
+
+1. Add the endpoint to `ROUTE_DEFINITIONS` with a unique `handler_name`.
+2. Expose the coroutine on an existing handler class (or create a new handler and extend
+   `ExampleImagesHandlerSet`).
+3. Wire additional services or factories inside `_build_handler_set` on
+   `ExampleImagesRoutes`, mirroring how the model stack introduces new use cases.
+
+`tests/routes/test_example_images_routes.py` exercises registrar binding, download pause
+flows, and import validations. Use it as a template when introducing new handler
+collaborators or error mappings.

docs/architecture/model_routes.md

@@ -0,0 +1,100 @@
+# Base model route architecture
+
+The model routing stack now splits HTTP wiring, orchestration logic, and
+business rules into discrete layers.  The goal is to make it obvious where a
+new collaborator should live and which contract it must honour.  The diagram
+below captures the end-to-end flow for a typical request:
+
+```mermaid
+graph TD
+    subgraph HTTP
+        A[ModelRouteRegistrar] -->|binds| B[BaseModelRoutes handler proxy]
+    end
+    subgraph Application
+        B --> C[ModelHandlerSet]
+        C --> D1[Handlers]
+        D1 --> E1[Use cases]
+        E1 --> F1[Services / scanners]
+    end
+    subgraph Side Effects
+        F1 --> G1[Cache & metadata]
+        F1 --> G2[Filesystem]
+        F1 --> G3[WebSocket state]
+    end
+```
+
+Every box maps to a concrete module:
+
+| Layer | Module(s) | Responsibility |
+| --- | --- | --- |
+| Registrar | `py/routes/model_route_registrar.py` | Declarative list of routes shared by every model type and helper methods for binding them to an `aiohttp` application. |
+| Route controller | `py/routes/base_model_routes.py` | Constructs the handler graph, injects shared services, exposes proxies that surface `503 Service not ready` when the model service has not been attached. |
+| Handler set | `py/routes/handlers/model_handlers.py` | Thin HTTP adapters grouped by concern (page rendering, listings, mutations, queries, downloads, CivitAI integration, move operations, auto-organize). |
+| Use cases | `py/services/use_cases/*.py` | Encapsulate long-running flows (`DownloadModelUseCase`, `BulkMetadataRefreshUseCase`, `AutoOrganizeUseCase`).  They normalise validation errors and concurrency constraints before returning control to the handlers. |
+| Services | `py/services/*.py` | Existing services and scanners that mutate caches, write metadata, move files, and broadcast WebSocket updates. |
+
+## Handler responsibilities & contracts
+
+`ModelHandlerSet` flattens the handler objects into the exact callables used by
+the registrar.  The table below highlights the separation of concerns within
+the set and the invariants that must hold after each handler returns.
+
+| Handler | Key endpoints | Collaborators | Contracts |
+| --- | --- | --- | --- |
+| `ModelPageView` | `/{prefix}` | `SettingsManager`, `server_i18n`, Jinja environment, `service.scanner` | Template is rendered with `is_initializing` flag when caches are cold; i18n filter is registered exactly once per environment instance. |
+| `ModelListingHandler` | `/api/lm/{prefix}/list` | `service.get_paginated_data`, `service.format_response` | Listings respect pagination query parameters and cap `page_size` at 100; every item is formatted before response. |
+| `ModelManagementHandler` | Mutations (delete, exclude, metadata, preview, tags, rename, bulk delete, duplicate verification) | `ModelLifecycleService`, `MetadataSyncService`, `PreviewAssetService`, `TagUpdateService`, scanner cache/index | Cache state mirrors filesystem changes: deletes prune cache & hash index, preview replacements synchronise metadata and cache NSFW levels, metadata saves trigger cache resort when names change. |
+| `ModelQueryHandler` | Read-only queries (top tags, folders, duplicates, metadata, URLs) | Service query helpers & scanner cache | Outputs always wrapped in `{"success": True}` when no error; duplicate/filename grouping omits empty entries; invalid parameters (e.g. missing `model_root`) return HTTP 400. |
+| `ModelDownloadHandler` | `/api/lm/download-model`, `/download-model-get`, `/download-progress/{id}`, `/cancel-download-get` | `DownloadModelUseCase`, `DownloadCoordinator`, `WebSocketManager` | Payload validation errors become HTTP 400 without mutating download progress cache; early-access failures surface as HTTP 401; successful downloads cache progress snapshots that back both WebSocket broadcasts and polling endpoints. |
+| `ModelCivitaiHandler` | CivitAI metadata routes | `MetadataSyncService`, metadata provider factory, `BulkMetadataRefreshUseCase` | `fetch_all_civitai` streams progress via `WebSocketBroadcastCallback`; version lookups validate model type before returning; local availability fields derive from hash lookups without mutating cache state. |
+| `ModelMoveHandler` | `move_model`, `move_models_bulk` | `ModelMoveService` | Moves execute atomically per request; bulk operations aggregate success/failure per file set. |
+| `ModelAutoOrganizeHandler` | `/api/lm/{prefix}/auto-organize` (GET/POST), `/auto-organize-progress` | `AutoOrganizeUseCase`, `WebSocketProgressCallback`, `WebSocketManager` | Enforces single-flight execution using the shared lock; progress broadcasts remain available to polling clients until explicitly cleared; conflicts return HTTP 409 with a descriptive error. |
+
+## Use case boundaries
+
+Each use case exposes a narrow asynchronous API that hides the underlying
+services.  Their error mapping is essential for predictable HTTP responses.
+
+| Use case | Entry point | Dependencies | Guarantees |
+| --- | --- | --- | --- |
+| `DownloadModelUseCase` | `execute(payload)` | `DownloadCoordinator.schedule_download` | Translates `ValueError` into `DownloadModelValidationError` for HTTP 400, recognises early-access errors (`"401"` in message) and surfaces them as `DownloadModelEarlyAccessError`, forwards success dictionaries untouched. |
+| `AutoOrganizeUseCase` | `execute(file_paths, progress_callback)` | `ModelFileService.auto_organize_models`, `WebSocketManager` lock | Guarded by `ws_manager` lock + status checks; raises `AutoOrganizeInProgressError` before invoking the file service when another run is already active. |
+| `BulkMetadataRefreshUseCase` | `execute_with_error_handling(progress_callback)` | `MetadataSyncService`, `SettingsManager`, `WebSocketBroadcastCallback` | Iterates through cached models, applies metadata sync, emits progress snapshots that handlers broadcast unchanged. |
+
+## Maintaining legacy contracts
+
+The refactor preserves the invariants called out in the previous architecture
+notes.  The most critical ones are reiterated here to emphasise the
+collaboration points:
+
+1. **Cache mutations** – Delete, exclude, rename, and bulk delete operations are
+   channelled through `ModelManagementHandler`.  The handler delegates to
+   `ModelLifecycleService` or `MetadataSyncService`, and the scanner cache is
+   mutated in-place before the handler returns.  The accompanying tests assert
+   that `scanner._cache.raw_data` and `scanner._hash_index` stay in sync after
+   each mutation.
+2. **Preview updates** – `PreviewAssetService.replace_preview` writes the new
+   asset, `MetadataSyncService` persists the JSON metadata, and
+   `scanner.update_preview_in_cache` mirrors the change.  The handler returns
+   the static URL produced by `config.get_preview_static_url`, keeping browser
+   clients in lockstep with disk state.
+3. **Download progress** – `DownloadCoordinator.schedule_download` generates the
+   download identifier, registers a WebSocket progress callback, and caches the
+   latest numeric progress via `WebSocketManager`.  Both `download_model`
+   responses and `/download-progress/{id}` polling read from the same cache to
+   guarantee consistent progress reporting across transports.
+
+## Extending the stack
+
+To add a new shared route:
+
+1. Declare it in `COMMON_ROUTE_DEFINITIONS` using a unique handler name.
+2. Implement the corresponding coroutine on one of the handlers inside
+   `ModelHandlerSet` (or introduce a new handler class when the concern does not
+   fit existing ones).
+3. Inject additional dependencies in `BaseModelRoutes._create_handler_set` by
+   wiring services or use cases through the constructor parameters.
+
+Model-specific routes should continue to be registered inside the subclass
+implementation of `setup_specific_routes`, reusing the shared registrar where
+possible.

docs/architecture/multi_library_design.md

@@ -0,0 +1,34 @@
+# Multi-Library Management for Standalone Mode
+
+## Requirements Summary
+- **Independent libraries**: In standalone mode, users can maintain multiple libraries, where each library represents a distinct set of model folders (LoRAs, checkpoints, embeddings, etc.). Only one library is active at any given time, but users need a fast way to switch between them.
+- **Library-specific settings**: The fields that vary per library are `folder_paths`, `default_lora_root`, `default_checkpoint_root`, and `default_embedding_root` inside `settings.json`.
+- **Persistent caches**: Every library must have its own SQLite persistent model cache so that metadata generated for one library does not leak into another.
+- **Backward compatibility**: Existing single-library setups should continue to work. When no multi-library configuration is provided, the application should behave exactly as before.
+
+## Proposed Design
+1. **Library registry**
+   - Extend the standalone configuration to hold a list of libraries, each identified by a unique name.
+   - Each entry stores the folder path configuration plus any library-scoped metadata (e.g. creation time, display name).
+   - The active library key is stored separately to allow quick switching without rewriting the full config.
+2. **Settings management**
+   - Update `settings_manager` to load and persist the library registry. When a library is activated, hydrate the in-memory settings object with that library's folder configuration.
+   - Provide helper methods for creating, renaming, and deleting libraries, ensuring validation for duplicate names and path collisions.
+   - Continue writing the active library settings to `settings.json` for compatibility, while storing the registry in a new section such as `libraries`.
+3. **Persistent model cache**
+   - Derive the SQLite file path from the active library, e.g. `model_cache_<library>.sqlite` or a nested directory structure like `model_cache/<library>/models.sqlite`.
+   - Update `PersistentModelCache` so it resolves the database path dynamically whenever the active library changes. Ensure connections are closed before switching to avoid locking issues.
+   - Migrate existing single cache files by treating them as the default library's cache.
+4. **Model scanning workflow**
+   - Modify `ModelScanner` and related services to react to library switches by clearing in-memory caches, re-reading folder paths, and rehydrating metadata from the library-specific SQLite cache.
+   - Provide API endpoints in standalone mode to list libraries, activate one, and trigger a rescan.
+5. **UI/UX considerations**
+   - In the standalone UI, introduce a library selector component that surfaces available libraries and offers quick switching.
+   - Offer feedback when switching libraries (e.g. spinner while rescanning) and guard destructive actions with confirmation prompts.
+
+## Implementation Notes
+- **Data migration**: On startup, detect if the old `settings.json` structure is present. If so, create a default library entry using the current folder paths and point the active library to it.
+- **Thread safety**: Ensure that any long-running scans are cancelled or awaited before switching libraries to prevent race conditions in cache writes.
+- **Testing**: Add unit tests for the settings manager to cover library CRUD operations and cache path resolution. Include integration tests that simulate switching libraries and verifying that the correct models are loaded.
+- **Documentation**: Update user guides to explain how to define libraries, switch between them, and where the new cache files are stored.
+- **Extensibility**: Keep the design open to future per-library settings (e.g. auto-refresh intervals, metadata overrides) by storing library data as objects instead of flat maps.

docs/architecture/recipe_routes.md

@@ -0,0 +1,89 @@
+# Recipe route architecture
+
+The recipe routing stack now mirrors the modular model route design. HTTP
+bindings, controller wiring, handler orchestration, and business rules live in
+separate layers so new behaviours can be added without re-threading the entire
+feature. The diagram below outlines the flow for a typical request:
+
+```mermaid
+graph TD
+    subgraph HTTP
+        A[RecipeRouteRegistrar] -->|binds| B[RecipeRoutes controller]
+    end
+    subgraph Application
+        B --> C[RecipeHandlerSet]
+        C --> D1[Handlers]
+        D1 --> E1[Use cases]
+        E1 --> F1[Services / scanners]
+    end
+    subgraph Side Effects
+        F1 --> G1[Cache & fingerprint index]
+        F1 --> G2[Metadata files]
+        F1 --> G3[Temporary shares]
+    end
+```
+
+## Layer responsibilities
+
+| Layer | Module(s) | Responsibility |
+| --- | --- | --- |
+| Registrar | `py/routes/recipe_route_registrar.py` | Declarative list of every recipe endpoint and helper methods that bind them to an `aiohttp` application. |
+| Controller | `py/routes/base_recipe_routes.py`, `py/routes/recipe_routes.py` | Lazily resolves scanners/clients from the service registry, wires shared templates/i18n, instantiates `RecipeHandlerSet`, and exposes a `{handler_name: coroutine}` mapping for the registrar. |
+| Handler set | `py/routes/handlers/recipe_handlers.py` | Thin HTTP adapters grouped by concern (page view, listings, queries, mutations, sharing). They normalise responses and translate service exceptions into HTTP status codes. |
+| Services & scanners | `py/services/recipes/*.py`, `py/services/recipe_scanner.py`, `py/services/service_registry.py` | Concrete business logic: metadata parsing, persistence, sharing, fingerprint/index maintenance, and cache refresh. |
+
+## Handler responsibilities & invariants
+
+`RecipeHandlerSet` flattens purpose-built handler objects into the callables the
+registrar binds. Each handler is responsible for a narrow concern and enforces a
+set of invariants before returning:
+
+| Handler | Key endpoints | Collaborators | Contracts |
+| --- | --- | --- | --- |
+| `RecipePageView` | `/loras/recipes` | `SettingsManager`, `server_i18n`, Jinja environment, recipe scanner getter | Template rendered with `is_initializing` flag when caches are still warming; i18n filter registered exactly once per environment instance. |
+| `RecipeListingHandler` | `/api/lm/recipes`, `/api/lm/recipe/{id}` | `recipe_scanner.get_paginated_data`, `recipe_scanner.get_recipe_by_id` | Listings respect pagination and search filters; every item receives a `file_url` fallback even when metadata is incomplete; missing recipes become HTTP 404. |
+| `RecipeQueryHandler` | Tag/base-model stats, syntax, LoRA lookups | Recipe scanner cache, `format_recipe_file_url` helper | Cache snapshots are reused without forcing refresh; duplicate lookups collapse groups by fingerprint; syntax lookups return helpful errors when LoRAs are absent. |
+| `RecipeManagementHandler` | Save, update, reconnect, bulk delete, widget ingest | `RecipePersistenceService`, `RecipeAnalysisService`, recipe scanner | Persistence results propagate HTTP status codes; fingerprint/index updates flow through the scanner before returning; validation errors surface as HTTP 400 without touching disk. |
+| `RecipeAnalysisHandler` | Uploaded/local/remote analysis | `RecipeAnalysisService`, `civitai_client`, recipe scanner | Unsupported content types map to HTTP 400; download errors (`RecipeDownloadError`) are not retried; every response includes a `loras` array for client compatibility. |
+| `RecipeSharingHandler` | Share + download | `RecipeSharingService`, recipe scanner | Share responses provide a stable download URL and filename; expired shares surface as HTTP 404; downloads stream via `web.FileResponse` with attachment headers. |
+
+## Use case boundaries
+
+The dedicated services encapsulate long-running work so handlers stay thin.
+
+| Use case | Entry point | Dependencies | Guarantees |
+| --- | --- | --- | --- |
+| `RecipeAnalysisService` | `analyze_uploaded_image`, `analyze_remote_image`, `analyze_local_image`, `analyze_widget_metadata` | `ExifUtils`, `RecipeParserFactory`, downloader factory, optional metadata collector/processor | Normalises missing/invalid payloads into `RecipeValidationError`; generates consistent fingerprint data to keep duplicate detection stable; temporary files are cleaned up after every analysis path. |
+| `RecipePersistenceService` | `save_recipe`, `delete_recipe`, `update_recipe`, `reconnect_lora`, `bulk_delete`, `save_recipe_from_widget` | `ExifUtils`, recipe scanner, card preview sizing constants | Writes images/JSON metadata atomically; updates scanner caches and hash indices before returning; recalculates fingerprints whenever LoRA assignments change. |
+| `RecipeSharingService` | `share_recipe`, `prepare_download` | `tempfile`, recipe scanner | Copies originals to TTL-managed temp files; metadata lookups re-use the scanner; expired shares trigger cleanup and `RecipeNotFoundError`. |
+
+## Maintaining critical invariants
+
+* **Cache updates** – Mutations (`save`, `delete`, `bulk_delete`, `update`) call
+  back into the recipe scanner to mutate the in-memory cache and fingerprint
+  index before returning a response. Tests assert that these methods are invoked
+  even when stubbing persistence.
+* **Fingerprint management** – `RecipePersistenceService` recomputes
+  fingerprints whenever LoRA metadata changes and duplicate lookups use those
+  fingerprints to group recipes. Handlers bubble the resulting IDs so clients
+  can merge duplicates without an extra fetch.
+* **Metadata synchronisation** – Saving or reconnecting a recipe updates the
+  JSON sidecar, refreshes embedded metadata via `ExifUtils`, and instructs the
+  scanner to resort its cache. Sharing relies on this metadata to generate
+  filenames and ensure downloads stay in sync with on-disk state.
+
+## Extending the stack
+
+1. Declare the new endpoint in `ROUTE_DEFINITIONS` with a unique handler name.
+2. Implement the coroutine on an existing handler or introduce a new handler
+   class inside `py/routes/handlers/recipe_handlers.py` when the concern does
+   not fit existing ones.
+3. Wire additional collaborators inside
+   `BaseRecipeRoutes._create_handler_set` (inject new services or factories) and
+   expose helper getters on the handler owner if the handler needs to share
+   utilities.
+
+Integration tests in `tests/routes/test_recipe_routes.py` exercise the listing,
+mutation, analysis-error, and sharing paths end-to-end, ensuring the controller
+and handler wiring remains valid as new capabilities are added.
+

docs/custom_priority_tags_format.md

@@ -0,0 +1,46 @@
+# Custom Priority Tag Format Proposal
+
+To support user-defined priority tags with flexible aliasing across different model types, the configuration will be stored as editable strings. The format balances readability with enough structure for parsing on both the backend and frontend.
+
+## Format Overview
+
+- Each model type is declared on its own line: `model_type: entries`.
+- Entries are comma-separated and ordered by priority from highest to lowest.
+- An entry may be a single canonical tag (e.g., `realistic`) or a canonical tag with aliases.
+- Canonical tags define the final folder name that should be used when matching that entry.
+- Aliases are enclosed in parentheses and separated by `|` (vertical bar).
+- All matching is case-insensitive; stored canonical names preserve the user-specified casing for folder creation and UI suggestions.
+
+### Grammar
+
+```
+priority-config := model-config { "\n" model-config }
+model-config    := model-type ":" entry-list
+model-type      := <identifier without spaces>
+entry-list      := entry { "," entry }
+entry           := canonical [ "(" alias { "|" alias } ")" ]
+canonical       := <tag text without parentheses or commas>
+alias           := <tag text without parentheses, commas, or pipes>
+```
+
+Examples:
+
+```
+lora: celebrity(celeb|celebrity), stylized, character(char)
+checkpoint: realistic(realism|realistic), anime(anime-style|toon)
+embedding: face, celeb(celebrity|celeb)
+```
+
+## Parsing Notes
+
+- Whitespace around separators is ignored to make manual editing more forgiving.
+- Duplicate canonical tags within the same model type collapse to a single entry; the first definition wins.
+- Aliases map to their canonical tag. When generating folder names, the canonical form is used.
+- Tags that do not match any alias or canonical entry fall back to the first tag in the model's tag list, preserving current behavior.
+
+## Usage
+
+- **Backend:** Convert each model type's string into an ordered list of canonical tags with alias sets. During path generation, iterate by priority order and match tags against both canonical names and their aliases.
+- **Frontend:** Surface canonical tags as suggestions, optionally displaying aliases in tooltips or secondary text. Input validation should warn about duplicate aliases within the same model type.
+
+This format allows users to customize priority tag handling per model type while keeping editing simple and avoiding proliferation of folder names through alias normalization.

docs/frontend-dom-fixtures.md

@@ -0,0 +1,51 @@
+# Frontend DOM Fixture Strategy
+
+This guide outlines how to reproduce the markup emitted by the Django templates while running Vitest in jsdom.  The aim is to make it straightforward to write integration-style unit tests for managers and UI helpers without having to duplicate template fragments inline.
+
+## Loading Template Markup
+
+Vitest executes inside Node, so we can read the same HTML templates that ship with the extension:
+
+1. Use the helper utilities from `tests/frontend/utils/domFixtures.js` to read files under the `templates/` directory.
+2. Mount the returned markup into `document.body` (or any custom container) before importing the module under test so its query selectors resolve correctly.
+
+```js
+import { renderTemplate } from '../utils/domFixtures.js'; // adjust the relative path to your spec
+
+beforeEach(() => {
+  renderTemplate('loras.html', {
+    dataset: { page: 'loras' }
+  });
+});
+```
+
+The helper ensures the dataset is applied to the container, which mirrors how Django sets `data-page` in production.
+
+## Working with Partial Components
+
+Many features are implemented as template partials located under `templates/components/`.  When a test only needs a fragment (for example, the progress panel or context menu markup), load the component file directly:
+
+```js
+const container = renderTemplate('components/progress_panel.html');
+
+const progressPanel = container.querySelector('#progress-panel');
+```
+
+This pattern avoids hand-written fixture strings and keeps the tests aligned with the actual markup.
+
+## Resetting Between Tests
+
+The shared Vitest setup clears `document.body` and storage APIs before each test.  If a suite adds additional DOM nodes outside of the body or needs to reset custom attributes mid-test, use `resetDom()` exported from `domFixtures.js`.
+
+```js
+import { resetDom } from '../utils/domFixtures.js';
+
+afterEach(() => {
+  resetDom();
+});
+```
+
+## Future Enhancements
+
+- Provide typed helpers for injecting mock script tags (e.g., replicating ComfyUI globals).
+- Compose higher-level fixtures that mimic specific pages (loras, checkpoints, recipes) once those managers receive dedicated suites.

docs/frontend-filtering-test-matrix.md

@@ -0,0 +1,44 @@
+# LoRA & Checkpoints Filtering/Sorting Test Matrix
+
+This matrix captures the scenarios that Phase 3 frontend tests should cover for the LoRA and Checkpoint managers. It focuses on how search, filter, sort, and duplicate badge toggles interact so future specs can share fixtures and expectations.
+
+## Scope
+
+- **Components**: `PageControls`, `FilterManager`, `SearchManager`, and `ModelDuplicatesManager` wiring invoked through `CheckpointsPageManager` and `LorasPageManager`.
+- **Templates**: `templates/loras.html` and `templates/checkpoints.html` along with shared filter panel and toolbar partials.
+- **APIs**: Requests issued through `baseModelApi.fetchModels` (via `resetAndReload`/`refreshModels`) and duplicates badge updates.
+
+## Shared Setup Considerations
+
+1. Render full page templates using `renderLorasPage` / `renderCheckpointsPage` helpers before importing modules so DOM queries resolve.
+2. Stub storage helpers (`getStorageItem`, `setStorageItem`, `getSessionItem`, `setSessionItem`) to observe persistence behavior without mutating real storage.
+3. Mock `sidebarManager` to capture refresh calls triggered after sort/filter actions.
+4. Provide fake API implementations exposing `resetAndReload`, `refreshModels`, `fetchFromCivitai`, `toggleBulkMode`, and `clearCustomFilter` so control events remain asynchronous but deterministic.
+5. Supply a minimal `ModelDuplicatesManager` mock exposing `toggleDuplicateMode`, `checkDuplicatesCount`, and `updateDuplicatesBadgeAfterRefresh` to validate duplicate badge wiring.
+
+## Scenario Matrix
+
+| ID | Feature | Scenario | LoRAs Expectations | Checkpoints Expectations | Notes |
+| --- | --- | --- | --- | --- | --- |
+| F-01 | Search filter | Typing a query updates `pageState.filters.search`, persists to session, and triggers `resetAndReload` on submit | Validate `SearchManager` writes query and reloads via API stub; confirm LoRA cards pass query downstream | Same as LoRAs | Cover `enter` press and clicking search icon |
+| F-02 | Tag filter | Selecting a tag chip adds it to filters, applies active styling, and reloads results | Tag stored under `filters.tags`; `FilterManager.applyFilters` persists and triggers `resetAndReload(true)` | Same; ensure base model tag set is scoped to checkpoints dataset | Include removal path |
+| F-03 | Base model filter | Toggling base model checkboxes updates `filters.baseModel`, persists, and reloads | Ensure only LoRA-supported models show; toggle multi-select | Ensure SDXL/Flux base models appear as expected | Capture UI state restored from storage on next init |
+| F-04 | Favorites-only | Clicking favorites toggle updates session flag and calls `resetAndReload(true)` | Button gains `.active` class and API called | Same | Verify duplicates badge refresh when active |
+| F-05 | Sort selection | Changing sort select saves preference (legacy + new format) and reloads | Confirm `PageControls.saveSortPreference` invoked with option and API called | Same with checkpoints-specific defaults | Cover `convertLegacySortFormat` branch |
+| F-06 | Filter persistence | Re-initializing manager loads stored filters/sort and updates DOM | Filters pre-populate chips/checkboxes; favorites state restored | Same | Requires simulating repeated construction |
+| F-07 | Combined filters | Applying search + tag + base model yields aggregated query params for fetch | Assert API receives merged filter payload | Same | Validate toast messaging for active filters |
+| F-08 | Clearing filters | Using "Clear filters" resets state, storage, and reloads list | `FilterManager.clearFilters` empties `filters`, removes active class, shows toast | Same | Ensure favorites-only toggle unaffected |
+| F-09 | Duplicate badge toggle | Pressing "Find duplicates" toggles duplicate mode and updates badge counts post-refresh | `ModelDuplicatesManager.toggleDuplicateMode` invoked and badge refresh called after API rebuild | Same plus checkpoint-specific duplicate badge dataset | Connects to future duplicate-specific specs |
+| F-10 | Bulk actions menu | Opening bulk dropdown keeps filters intact and closes on outside click | Validate dropdown class toggling and no unintended reload | Same | Guard against regression when dropdown interacts with filters |
+
+## Automation Coverage Status
+
+- ✅ F-01 Search filter, F-02 Tag filter, F-03 Base model filter, F-04 Favorites-only toggle, F-05 Sort selection, and F-09 Duplicate badge toggle are covered by `tests/frontend/components/pageControls.filtering.test.js` for both LoRA and checkpoint pages.
+- ⏳ F-06 Filter persistence, F-07 Combined filters, F-08 Clearing filters, and F-10 Bulk actions remain to be automated alongside upcoming bulk mode refinements.
+
+## Coverage Gaps & Follow-Ups
+
+- Write Vitest suites that exercise the matrix for both managers, sharing fixtures through page helpers to avoid duplication.
+- Capture API parameter assertions by inspecting `baseModelApi.fetchModels` mocks rather than relying solely on state mutations.
+- Add regression cases for legacy storage migrations (old filter keys) once fixtures exist for older payloads.
+- Extend duplicate badge coverage with scenarios where `checkDuplicatesCount` signals zero duplicates versus pending calculations.

docs/frontend-testing-roadmap.md

@@ -0,0 +1,33 @@
+# Frontend Automation Testing Roadmap
+
+This roadmap tracks the planned rollout of automated testing for the ComfyUI LoRA Manager frontend. Each phase builds on the infrastructure introduced in this change set and records progress so future contributors can quickly identify the next tasks.
+
+## Phase Overview
+
+| Phase | Goal | Primary Focus | Status | Notes |
+| --- | --- | --- | --- | --- |
+| Phase 0 | Establish baseline tooling | Add Node test runner, jsdom environment, and seed smoke tests | ✅ Complete | Vitest + jsdom configured, example state tests committed |
+| Phase 1 | Cover state management logic | Unit test selectors, derived data helpers, and storage utilities under `static/js/state` and `static/js/utils` | ✅ Complete | Storage helpers and state selectors now exercised via deterministic suites |
+| Phase 2 | Test AppCore orchestration | Simulate page bootstrapping, infinite scroll hooks, and manager registration using JSDOM DOM fixtures | ✅ Complete | AppCore initialization + page feature suites now validate manager wiring, infinite scroll hooks, and onboarding gating |
+| Phase 3 | Validate page-specific managers | Add focused suites for `loras`, `checkpoints`, `embeddings`, and `recipes` managers covering filtering, sorting, and bulk actions | ✅ Complete | LoRA/checkpoint suites expanded; embeddings + recipes managers now covered with initialization, filtering, and duplicate workflows |
+| Phase 4 | Interaction-level regression tests | Exercise template fragments, modals, and menus to ensure UI wiring remains intact | ✅ Complete | Vitest DOM suites cover NSFW selector, recipe modal editing, and global context menus |
+| Phase 5 | Continuous integration & coverage | Integrate frontend tests into CI workflow and track coverage metrics | ✅ Complete | CI workflow runs Vitest and aggregates V8 coverage into `coverage/frontend` via a dedicated script |
+
+## Next Steps Checklist
+
+- [x] Expand unit tests for `storageHelpers` covering migrations and namespace behavior.
+- [x] Document DOM fixture strategy for reproducing template structures in tests.
+- [x] Prototype AppCore initialization test that verifies manager bootstrapping with stubbed dependencies.
+- [x] Add AppCore page feature suite exercising context menu creation and infinite scroll registration via DOM fixtures.
+- [x] Extend AppCore orchestration tests to cover manager wiring, bulk menu setup, and onboarding gating scenarios.
+- [x] Add interaction regression suites for context menus and recipe modals to complete Phase 4.
+- [x] Evaluate integrating coverage reporting once test surface grows (> 20 specs).
+- [x] Create shared fixtures for the loras and checkpoints pages once dedicated manager suites are added.
+- [x] Draft focused test matrix for loras/checkpoints manager filtering and sorting paths ahead of Phase 3.
+- [x] Implement LoRAs manager filtering/sorting specs for scenarios F-01–F-05 & F-09; queue remaining edge cases after duplicate/bulk flows stabilize.
+- [x] Implement checkpoints manager filtering/sorting specs for scenarios F-01–F-05 & F-09; cover remaining paths alongside bulk action work.
+- [x] Implement checkpoints page manager smoke tests covering initialization and duplicate badge wiring.
+- [x] Outline focused checkpoints scenarios (filtering, sorting, duplicate badge toggles) to feed into the shared test matrix.
+- [ ] Add duplicate badge regression coverage for zero/pending states after API refreshes.
+
+Maintaining this roadmap alongside code changes will make it easier to append new automated test tasks and update their progress.

docs/library-switching.md

@@ -0,0 +1,28 @@
+# Library Switching and Preview Routes
+
+Library switching no longer requires restarting the backend. The preview
+thumbnails shown in the UI are now served through a dynamic endpoint that
+resolves files against the folders registered for the active library at request
+time. This allows the multi-library flow to update model roots without touching
+the aiohttp router, so previews remain available immediately after a switch.
+
+## How the dynamic preview endpoint works
+
+* `config.get_preview_static_url()` now returns `/api/lm/previews?path=<encoded>`
+  for any preview path. The raw filesystem location is URL encoded so that it
+  can be passed through the query string without leaking directory structure in
+  the route itself.【F:py/config.py†L398-L404】
+* `PreviewRoutes` exposes the `/api/lm/previews` handler which validates the
+  decoded path against the directories registered for the current library. The
+  request is rejected if it falls outside those roots or if the file does not
+  exist.【F:py/routes/preview_routes.py†L5-L21】【F:py/routes/handlers/preview_handlers.py†L9-L48】
+* `Config` keeps an up-to-date cache of allowed preview roots. Every time a
+  library is applied the cache is rebuilt using the declared LoRA, checkpoint
+  and embedding directories (including symlink targets). The validation logic
+  checks preview requests against this cache.【F:py/config.py†L51-L68】【F:py/config.py†L180-L248】【F:py/config.py†L332-L346】
+
+Both the ComfyUI runtime (`LoraManager.add_routes`) and the standalone launcher
+(`StandaloneLoraManager.add_routes`) register the new preview routes instead of
+mounting a static directory per root. Switching libraries therefore works
+without restarting the application, and preview URLs generated before or after a
+switch continue to resolve correctly.【F:py/lora_manager.py†L21-L82】【F:standalone.py†L302-L315】

docs/priority_tags_help.md

@@ -0,0 +1,71 @@
+# Priority Tags Configuration Guide
+
+This guide explains how to tailor the tag priority order that powers folder naming and tag suggestions in the LoRA Manager. You only need to edit the comma-separated list of entries shown in the **Priority Tags** field for each model type.
+
+## 1. Pick the Model Type
+
+In the **Priority Tags** dialog you will find one tab per model type (LoRA, Checkpoint, Embedding). Select the tab you want to update; changes on one tab do not affect the others.
+
+## 2. Edit the Entry List
+
+Inside the textarea you will see a line similar to:
+
+```
+character, concept, style(toon|toon_style)
+```
+
+This entire line is the **entry list**. Replace it with your own ordered list.
+
+### Entry Rules
+
+Each entry is separated by a comma, in order from highest to lowest priority:
+
+- **Canonical tag only:** `realistic`
+- **Canonical tag with aliases:** `character(char|chars)`
+
+Aliases live inside `()` and are separated with `|`. The canonical name is what appears in folder names and UI suggestions when any of the aliases are detected. Matching is case-insensitive.
+
+## Use `{first_tag}` in Path Templates
+
+When your path template contains `{first_tag}`, the app picks a folder name based on your priority list and the model’s own tags:
+
+- It checks the priority list from top to bottom. If a canonical tag or any of its aliases appear in the model tags, that canonical name becomes the folder name.
+- If no priority tags are found but the model has tags, the very first model tag is used.
+- If the model has no tags at all, the folder falls back to `no tags`.
+
+### Example
+
+With a template like `/{model_type}/{first_tag}` and the priority entry list `character(char|chars), style(anime|toon)`:
+
+| Model Tags | Folder Name | Why |
+| --- | --- | --- |
+| `["chars", "female"]` | `character` | `chars` matches the `character` alias, so the canonical wins. |
+| `["anime", "portrait"]` | `style` | `anime` hits the `style` entry, so its canonical label is used. |
+| `["portrait", "bw"]` | `portrait` | No priority match, so the first model tag is used. |
+| `[]` | `no tags` | Nothing to match, so the fallback is applied. |
+
+## 3. Save the Settings
+
+After editing the entry list, press **Enter** to save. Use **Shift+Enter** whenever you need a new line. Clicking outside the field also saves automatically. A success toast confirms the update.
+
+## Examples
+
+| Goal | Entry List |
+| --- | --- |
+| Prefer people over styles | `character, portraits, style(anime\|toon)` |
+| Group sci-fi variants | `sci-fi(scifi\|science_fiction), cyberpunk(cyber\|punk)` |
+| Alias shorthand tags | `realistic(real\|realisim), photorealistic(photo_real)` |
+
+## Tips
+
+- Keep canonical names short and meaningful—they become folder names.
+- Place the most important categories first; the first match wins.
+- Avoid duplicate canonical names within the same list; only the first instance is used.
+
+## Troubleshooting
+
+- **Unexpected folder name?** Check that the canonical name you want is placed before other matches.
+- **Alias not working?** Ensure the alias is inside parentheses and separated with `|`, e.g. `character(char|chars)`.
+- **Validation error?** Look for missing parentheses or stray commas. Each entry must follow the `canonical(alias|alias)` pattern or just `canonical`.
+
+With these basics you can quickly adapt Priority Tags to match your library’s organization style.

docs/testing/coverage_analysis.md

@@ -0,0 +1,26 @@
+# Backend Test Coverage Notes
+
+## Pytest Execution
+- Command: `python -m pytest`
+- Result: All 283 collected tests passed in the current environment.
+- Coverage tooling (``pytest-cov``/``coverage``) is unavailable in the offline sandbox, so line-level metrics could not be generated. The earlier attempt to install ``pytest-cov`` failed because the package index cannot be reached from the container.
+
+## High-Priority Gaps to Address
+
+### 1. Standalone server bootstrapping
+* **Source:** [`standalone.py`](../../standalone.py)
+* **Why it matters:** The standalone entry point wires together the aiohttp application, static asset routes, model-route registration, and configuration validation. None of these behaviours are covered by automated tests, leaving regressions in bootstrapping logic undetected.
+* **Suggested coverage:** Add integration-style tests that instantiate `StandaloneServer`/`StandaloneLoraManager` with temporary settings and assert that routes (HTTP + websocket) are registered, configuration warnings fire for missing paths, and the mock ComfyUI shims behave as expected.
+
+### 2. Model service registration factory
+* **Source:** [`py/services/model_service_factory.py`](../../py/services/model_service_factory.py)
+* **Why it matters:** The factory coordinates which model services and routes the API exposes, including error handling when unknown model types are requested. No current tests verify registration, memoization of route instances, or the logging path on failures.
+* **Suggested coverage:** Unit tests that exercise `register_model_type`, `get_route_instance`, error branches in `get_service_class`/`get_route_class`, and `setup_all_routes` when a route setup raises. Use lightweight fakes to confirm the logger is called and state is cleared via `clear_registrations`.
+
+### 3. Server-side i18n helper
+* **Source:** [`py/services/server_i18n.py`](../../py/services/server_i18n.py)
+* **Why it matters:** Template rendering relies on the `ServerI18nManager` to load locale JSON, perform key lookups, and format parameters. The fallback logic (dot-notation lookup, English fallbacks, placeholder substitution) is untested, so malformed locale files or regressions in placeholder handling would slip through.
+* **Suggested coverage:** Tests that load fixture locale dictionaries, assert `set_locale` fallbacks, verify nested key resolution and placeholder substitution, and ensure missing keys return the original identifier.
+
+## Next Steps
+Prioritize creating focused unit tests around these modules, then re-run pytest once coverage tooling is available to confirm the new tests close the identified gaps.

i18n_migration_summary.md

@@ -1,170 +0,0 @@
-# i18n System Migration Complete
-
-## 概要 (Summary)
-
-成功完成了从JavaScript ES6模块到JSON格式的国际化系统迁移，包含完整的多语言翻译和代码更新。
-
-Successfully completed the migration from JavaScript ES6 modules to JSON format for the internationalization system, including complete multilingual translations and code updates.
-
-## 完成的工作 (Completed Work)
-
-### 1. 文件结构重组 (File Structure Reorganization)
-- **新建目录**: `/locales/` - 集中存放所有JSON翻译文件
-- **移除目录**: `/static/js/i18n/locales/` - 删除了旧的JavaScript文件
-
-### 2. 格式转换 (Format Conversion)
-- **转换前**: ES6模块格式 (`export const en = { ... }`)
-- **转换后**: 标准JSON格式 (`{ ... }`)
-- **支持语言**: 9种语言完全转换
-  - English (en)
-  - 简体中文 (zh-CN)
-  - 繁體中文 (zh-TW)
-  - 日本語 (ja)
-  - Русский (ru)
-  - Deutsch (de)
-  - Français (fr)
-  - Español (es)
-  - 한국어 (ko)
-
-### 3. 翻译完善 (Translation Completion)
-- **翻译条目**: 每种语言386个翻译键值对
-- **覆盖范围**: 完整覆盖所有UI元素
-- **质量保证**: 所有翻译键在各语言间保持一致
-
-### 4. JavaScript代码更新 (JavaScript Code Updates)
-
-#### 主要修改文件: `static/js/i18n/index.js`
-```javascript
-// 旧版本: 静态导入
-import { en } from './locales/en.js';
-
-// 新版本: 动态JSON加载
-async loadLocale(locale) {
-    const response = await fetch(`/locales/${locale}.json`);
-    return await response.json();
-}
-```
-
-#### 核心功能更新:
-- **构造函数**: 从静态导入改为配置驱动
-- **语言加载**: 异步JSON获取机制
-- **初始化**: 支持Promise-based的异步初始化
-- **错误处理**: 增强的回退机制到英语
-- **向后兼容**: 保持现有API接口不变
-
-### 5. Python服务端更新 (Python Server-side Updates)
-
-#### 修改文件: `py/services/server_i18n.py`
-```python
-# 旧版本: 解析JavaScript文件
-def _load_locale_file(self, path, filename, locale_code):
-    # 复杂的JS到JSON转换逻辑
-    
-# 新版本: 直接加载JSON
-def _load_locale_file(self, path, filename, locale_code):
-    with open(file_path, 'r', encoding='utf-8') as f:
-        translations = json.load(f)
-```
-
-#### 路径更新:
-- **旧路径**: `static/js/i18n/locales/*.js`
-- **新路径**: `locales/*.json`
-
-### 6. 服务器路由配置 (Server Route Configuration)
-
-#### 修改文件: `standalone.py`
-```python
-# 新增静态路由服务JSON文件
-app.router.add_static('/locales', locales_path)
-```
-
-## 技术架构 (Technical Architecture)
-
-### 前端 (Frontend)
-```
-Browser → JavaScript i18n Manager → fetch('/locales/{lang}.json') → JSON Response
-```
-
-### 后端 (Backend)
-```
-Python Server → ServerI18nManager → Direct JSON loading → Template Rendering
-```
-
-### 文件组织 (File Organization)
-```
-ComfyUI-Lora-Manager/
-├── locales/                    # 新的JSON翻译文件目录
-│   ├── en.json                 # 英语翻译 (基准)
-│   ├── zh-CN.json             # 简体中文翻译
-│   ├── zh-TW.json             # 繁体中文翻译
-│   ├── ja.json                # 日语翻译
-│   ├── ru.json                # 俄语翻译
-│   ├── de.json                # 德语翻译
-│   ├── fr.json                # 法语翻译
-│   ├── es.json                # 西班牙语翻译
-│   └── ko.json                # 韩语翻译
-├── static/js/i18n/
-│   └── index.js               # 更新的JavaScript i18n管理器
-└── py/services/
-    └── server_i18n.py        # 更新的Python服务端i18n
-```
-
-## 测试验证 (Testing & Validation)
-
-### 测试脚本: `test_i18n.py`
-```bash
-🚀 Testing updated i18n system...
-✅ All JSON locale files are valid (9 languages)
-✅ Server-side i18n system working correctly
-✅ All languages have complete translations (386 keys each)
-🎉 All tests passed!
-```
-
-### 验证内容:
-1. **JSON文件完整性**: 所有文件格式正确，语法有效
-2. **翻译完整性**: 各语言翻译键值一致，无缺失
-3. **服务端功能**: Python i18n服务正常加载和翻译
-4. **参数插值**: 动态参数替换功能正常
-
-## 优势与改进 (Benefits & Improvements)
-
-### 1. 维护性提升
-- **简化格式**: JSON比JavaScript对象更易于编辑和维护
-- **工具支持**: 更好的编辑器语法高亮和验证支持
-- **版本控制**: 更清晰的diff显示，便于追踪更改
-
-### 2. 性能优化
-- **按需加载**: 只加载当前所需语言，减少初始加载时间
-- **缓存友好**: JSON文件可以被浏览器和CDN更好地缓存
-- **压缩效率**: JSON格式压缩率通常更高
-
-### 3. 开发体验
-- **动态切换**: 支持运行时语言切换，无需重新加载页面
-- **易于扩展**: 添加新语言只需增加JSON文件
-- **调试友好**: 更容易定位翻译问题和缺失键
-
-### 4. 部署便利
-- **静态资源**: JSON文件可以作为静态资源部署
-- **CDN支持**: 可以通过CDN分发翻译文件
-- **版本管理**: 更容易管理不同版本的翻译
-
-## 兼容性保证 (Compatibility Assurance)
-
-- **API兼容**: 所有现有的JavaScript API保持不变
-- **调用方式**: 现有代码无需修改即可工作
-- **错误处理**: 增强的回退机制确保用户体验
-- **性能**: 新系统性能与旧系统相当或更好
-
-## 后续建议 (Future Recommendations)
-
-1. **监控**: 部署后监控翻译加载性能和错误率
-2. **优化**: 考虑实施翻译缓存策略以进一步提升性能
-3. **扩展**: 可以考虑添加翻译管理界面，便于非技术人员更新翻译
-4. **自动化**: 实施CI/CD流程自动验证翻译完整性
-
----
-
-**迁移完成时间**: 2024年
-**影响文件数量**: 21个文件 (9个新JSON + 2个JS更新 + 1个Python更新 + 1个服务器配置)
-**翻译键总数**: 386个 × 9种语言 = 3,474个翻译条目
-**测试状态**: ✅ 全部通过

locales/de.json

@@ -16,7 +16,9 @@
             "loading": "Wird geladen...",
             "unknown": "Unbekannt",
             "date": "Datum",
-            "version": "Version"
+            "version": "Version",
+            "enabled": "Aktiviert",
+            "disabled": "Deaktiviert"
         },
         "language": {
             "select": "Sprache",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 Bytes",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "Keine Remote-Beispielbilder für dieses Modell auf Civitai verfügbar"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "Beispielbilder herunterladen",
+            "missingPath": "Bitte legen Sie einen Speicherort fest, bevor Sie Beispielbilder herunterladen.",
+            "unavailable": "Beispielbild-Downloads sind noch nicht verfügbar. Versuchen Sie es erneut, nachdem die Seite vollständig geladen ist."
+        },
+        "cleanupExampleImages": {
+            "label": "Beispielbild-Ordner bereinigen",
+            "success": "{count} Ordner wurden in den Papierkorb verschoben",
+            "none": "Keine Beispielbild-Ordner mussten bereinigt werden",
+            "partial": "Bereinigung abgeschlossen, {failures} Ordner übersprungen",
+            "error": "Fehler beim Bereinigen der Beispielbild-Ordner: {message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA Manager",
         "navigation": {
@@ -171,14 +188,23 @@
         "civitaiApiKey": "Civitai API Key",
         "civitaiApiKeyPlaceholder": "Geben Sie Ihren Civitai API Key ein",
         "civitaiApiKeyHelp": "Wird für die Authentifizierung beim Herunterladen von Modellen von Civitai verwendet",
+        "openSettingsFileLocation": {
+            "label": "Einstellungsordner öffnen",
+            "tooltip": "Den Ordner mit der settings.json öffnen",
+            "success": "Einstellungsordner geöffnet",
+            "failed": "Einstellungsordner konnte nicht geöffnet werden"
+        },
         "sections": {
             "contentFiltering": "Inhaltsfilterung",
             "videoSettings": "Video-Einstellungen",
             "layoutSettings": "Layout-Einstellungen",
             "folderSettings": "Ordner-Einstellungen",
+            "priorityTags": "Prioritäts-Tags",
             "downloadPathTemplates": "Download-Pfad-Vorlagen",
             "exampleImages": "Beispielbilder",
-            "misc": "Verschiedenes"
+            "misc": "Verschiedenes",
+            "metadataArchive": "Metadaten-Archiv-Datenbank",
+            "proxySettings": "Proxy-Einstellungen"
         },
         "contentFiltering": {
             "blurNsfwContent": "NSFW-Inhalte unscharf stellen",
@@ -194,14 +220,14 @@
             "displayDensity": "Anzeige-Dichte",
             "displayDensityOptions": {
                 "default": "Standard",
-                "medium": "Mittel", 
+                "medium": "Mittel",
                 "compact": "Kompakt"
             },
             "displayDensityHelp": "Wählen Sie, wie viele Karten pro Zeile angezeigt werden sollen:",
             "displayDensityDetails": {
-                "default": "Standard: 5 (1080p), 6 (2K), 8 (4K)",
-                "medium": "Mittel: 6 (1080p), 7 (2K), 9 (4K)",
-                "compact": "Kompakt: 7 (1080p), 8 (2K), 10 (4K)"
+                "default": "5 (1080p), 6 (2K), 8 (4K)",
+                "medium": "6 (1080p), 7 (2K), 9 (4K)",
+                "compact": "7 (1080p), 8 (2K), 10 (4K)"
             },
             "displayDensityWarning": "Warnung: Höhere Dichten können bei Systemen mit begrenzten Ressourcen zu Performance-Problemen führen.",
             "cardInfoDisplay": "Karten-Info-Anzeige",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "Wählen Sie, wann Modellinformationen und Aktionsschaltflächen angezeigt werden sollen:",
             "cardInfoDisplayDetails": {
-                "always": "Immer sichtbar: Kopf- und Fußzeilen sind immer sichtbar",
-                "hover": "Bei Hover anzeigen: Kopf- und Fußzeilen erscheinen nur beim Darüberfahren mit der Maus"
+                "always": "Kopf- und Fußzeilen sind immer sichtbar",
+                "hover": "Kopf- und Fußzeilen erscheinen nur beim Darüberfahren mit der Maus"
+            },
+            "modelNameDisplay": "Anzeige des Modellnamens",
+            "modelNameDisplayOptions": {
+                "modelName": "Modellname",
+                "fileName": "Dateiname"
+            },
+            "modelNameDisplayHelp": "Wählen Sie aus, was in der Fußzeile der Modellkarte angezeigt werden soll:",
+            "modelNameDisplayDetails": {
+                "modelName": "Den beschreibenden Namen des Modells anzeigen",
+                "fileName": "Den tatsächlichen Dateinamen auf der Festplatte anzeigen"
             }
         },
         "folderSettings": {
+            "activeLibrary": "Aktive Bibliothek",
+            "activeLibraryHelp": "Zwischen den konfigurierten Bibliotheken wechseln, um die Standardordner zu aktualisieren. Eine Änderung der Auswahl lädt die Seite neu.",
+            "loadingLibraries": "Bibliotheken werden geladen...",
+            "noLibraries": "Keine Bibliotheken konfiguriert",
             "defaultLoraRoot": "Standard-LoRA-Stammordner",
             "defaultLoraRootHelp": "Legen Sie den Standard-LoRA-Stammordner für Downloads, Importe und Verschiebungen fest",
             "defaultCheckpointRoot": "Standard-Checkpoint-Stammordner",
@@ -224,6 +264,26 @@
             "defaultEmbeddingRootHelp": "Legen Sie den Standard-Embedding-Stammordner für Downloads, Importe und Verschiebungen fest",
             "noDefault": "Kein Standard"
         },
+        "priorityTags": {
+            "title": "Prioritäts-Tags",
+            "description": "Passen Sie die Tag-Prioritätsreihenfolge für jeden Modelltyp an (z. B. character, concept, style(toon|toon_style))",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "Prioritäts-Tags-Hilfe öffnen",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "Checkpoint",
+                "embedding": "Embedding"
+            },
+            "saveSuccess": "Prioritäts-Tags aktualisiert.",
+            "saveError": "Prioritäts-Tags konnten nicht aktualisiert werden.",
+            "loadingSuggestions": "Lade Vorschläge...",
+            "validation": {
+                "missingClosingParen": "Eintrag {index} fehlt eine schließende Klammer.",
+                "missingCanonical": "Eintrag {index} muss einen kanonischen Tag-Namen enthalten.",
+                "duplicateCanonical": "Der kanonische Tag \"{tag}\" kommt mehrfach vor.",
+                "unknown": "Ungültige Prioritäts-Tag-Konfiguration."
+            }
+        },
         "downloadPathTemplates": {
             "title": "Download-Pfad-Vorlagen",
             "help": "Konfigurieren Sie Ordnerstrukturen für verschiedene Modelltypen beim Herunterladen von Civitai.",
@@ -231,17 +291,18 @@
             "templateOptions": {
                 "flatStructure": "Flache Struktur",
                 "byBaseModel": "Nach Basis-Modell",
-                "byAuthor": "Nach Autor", 
+                "byAuthor": "Nach Autor",
                 "byFirstTag": "Nach erstem Tag",
                 "baseModelFirstTag": "Basis-Modell + Erster Tag",
                 "baseModelAuthor": "Basis-Modell + Autor",
                 "authorFirstTag": "Autor + Erster Tag",
+                "baseModelAuthorFirstTag": "Basis-Modell + Autor + Erster Tag",
                 "customTemplate": "Benutzerdefinierte Vorlage"
             },
             "customTemplatePlaceholder": "Benutzerdefinierte Vorlage eingeben (z.B. {base_model}/{author}/{first_tag})",
             "modelTypes": {
                 "lora": "LoRA",
-                "checkpoint": "Checkpoint", 
+                "checkpoint": "Checkpoint",
                 "embedding": "Embedding"
             },
             "baseModelPathMappings": "Basis-Modell-Pfad-Zuordnungen",
@@ -273,6 +334,48 @@
         "misc": {
             "includeTriggerWords": "Trigger Words in LoRA-Syntax einschließen",
             "includeTriggerWordsHelp": "Trainierte Trigger Words beim Kopieren der LoRA-Syntax in die Zwischenablage einschließen"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "Metadaten-Archiv-Datenbank aktivieren",
+            "enableArchiveDbHelp": "Verwenden Sie eine lokale Datenbank, um auf Metadaten von Modellen zuzugreifen, die von Civitai gelöscht wurden.",
+            "status": "Status",
+            "statusAvailable": "Verfügbar",
+            "statusUnavailable": "Nicht verfügbar",
+            "enabled": "Aktiviert",
+            "management": "Datenbankverwaltung",
+            "managementHelp": "Laden Sie die Metadaten-Archiv-Datenbank herunter oder entfernen Sie sie",
+            "downloadButton": "Datenbank herunterladen",
+            "downloadingButton": "Wird heruntergeladen...",
+            "downloadedButton": "Heruntergeladen",
+            "removeButton": "Datenbank entfernen",
+            "removingButton": "Wird entfernt...",
+            "downloadSuccess": "Metadaten-Archiv-Datenbank erfolgreich heruntergeladen",
+            "downloadError": "Fehler beim Herunterladen der Metadaten-Archiv-Datenbank",
+            "removeSuccess": "Metadaten-Archiv-Datenbank erfolgreich entfernt",
+            "removeError": "Fehler beim Entfernen der Metadaten-Archiv-Datenbank",
+            "removeConfirm": "Sind Sie sicher, dass Sie die Metadaten-Archiv-Datenbank entfernen möchten? Dadurch wird die lokale Datenbankdatei gelöscht und Sie müssen sie erneut herunterladen, um diese Funktion zu nutzen.",
+            "preparing": "Download wird vorbereitet...",
+            "connecting": "Verbindung zum Download-Server wird hergestellt...",
+            "completed": "Abgeschlossen",
+            "downloadComplete": "Download erfolgreich abgeschlossen"
+        },
+        "proxySettings": {
+            "enableProxy": "App-Proxy aktivieren",
+            "enableProxyHelp": "Aktivieren Sie benutzerdefinierte Proxy-Einstellungen für diese Anwendung. Überschreibt die System-Proxy-Einstellungen.",
+            "proxyType": "Proxy-Typ",
+            "proxyTypeHelp": "Wählen Sie den Typ des Proxy-Servers (HTTP, HTTPS, SOCKS4, SOCKS5)",
+            "proxyHost": "Proxy-Host",
+            "proxyHostPlaceholder": "proxy.beispiel.de",
+            "proxyHostHelp": "Der Hostname oder die IP-Adresse Ihres Proxy-Servers",
+            "proxyPort": "Proxy-Port",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "Die Portnummer Ihres Proxy-Servers",
+            "proxyUsername": "Benutzername (optional)",
+            "proxyUsernamePlaceholder": "benutzername",
+            "proxyUsernameHelp": "Benutzername für die Proxy-Authentifizierung (falls erforderlich)",
+            "proxyPassword": "Passwort (optional)",
+            "proxyPasswordPlaceholder": "passwort",
+            "proxyPasswordHelp": "Passwort für die Proxy-Authentifizierung (falls erforderlich)"
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "{count} ausgewählt",
             "selectedSuffix": "ausgewählt",
-            "viewSelected": "Klicken Sie, um ausgewählte Elemente anzuzeigen",
-            "sendToWorkflow": "An Workflow senden",
-            "copyAll": "Alle kopieren",
-            "refreshAll": "Alle aktualisieren",
-            "moveAll": "Alle verschieben",
-            "deleteAll": "Alle löschen",
-            "clear": "Leeren"
+            "viewSelected": "Auswahl anzeigen",
+            "addTags": "Allen Tags hinzufügen",
+            "setBaseModel": "Basis-Modell für alle festlegen",
+            "setContentRating": "Inhaltsbewertung für alle festlegen",
+            "copyAll": "Alle Syntax kopieren",
+            "refreshAll": "Alle Metadaten aktualisieren",
+            "moveAll": "Alle in Ordner verschieben",
+            "autoOrganize": "Automatisch organisieren",
+            "deleteAll": "Alle Modelle löschen",
+            "clear": "Auswahl löschen",
+            "autoOrganizeProgress": {
+                "initializing": "Automatische Organisation wird initialisiert...",
+                "starting": "Automatische Organisation für {type} wird gestartet...",
+                "processing": "Verarbeitung ({processed}/{total}) – {success} verschoben, {skipped} übersprungen, {failures} fehlgeschlagen",
+                "cleaning": "Leere Verzeichnisse werden bereinigt...",
+                "completed": "Abgeschlossen: {success} verschoben, {skipped} übersprungen, {failures} fehlgeschlagen",
+                "complete": "Automatische Organisation abgeschlossen",
+                "error": "Fehler: {error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "Civitai-Daten aktualisieren",
@@ -445,13 +560,19 @@
         "title": "Embedding-Modelle"
     },
     "sidebar": {
-        "modelRoot": "Modell-Stammverzeichnis",
+        "modelRoot": "Stammverzeichnis",
         "collapseAll": "Alle Ordner einklappen",
         "pinSidebar": "Sidebar anheften",
         "unpinSidebar": "Sidebar lösen",
         "switchToListView": "Zur Listenansicht wechseln",
         "switchToTreeView": "Zur Baumansicht wechseln",
-        "collapseAllDisabled": "Im Listenmodus nicht verfügbar"
+        "recursiveOn": "Unterordner durchsuchen",
+        "recursiveOff": "Nur aktuellen Ordner durchsuchen",
+        "recursiveUnavailable": "Rekursive Suche ist nur in der Baumansicht verfügbar",
+        "collapseAllDisabled": "Im Listenmodus nicht verfügbar",
+        "dragDrop": {
+            "unableToResolveRoot": "Zielpfad für das Verschieben konnte nicht ermittelt werden."
+        }
     },
     "statistics": {
         "title": "Statistiken",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "Vorschaubild heruntergeladen",
                 "downloadingFile": "{type}-Datei wird heruntergeladen",
                 "finalizing": "Download wird abgeschlossen..."
+            },
+            "progress": {
+                "currentFile": "Aktuelle Datei:",
+                "downloading": "Wird heruntergeladen: {name}",
+                "transferred": "Heruntergeladen: {downloaded} / {total}",
+                "transferredSimple": "Heruntergeladen: {downloaded}",
+                "transferredUnknown": "Heruntergeladen: --",
+                "speed": "Geschwindigkeit: {speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "Inhaltsbewertung festlegen",
             "current": "Aktuell",
+            "multiple": "Mehrere Werte",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "Modelle werden dauerhaft gelöscht.",
             "action": "Alle löschen"
         },
+        "bulkAddTags": {
+            "title": "Tags zu mehreren Modellen hinzufügen",
+            "description": "Tags hinzufügen zu",
+            "models": "Modelle",
+            "tagsToAdd": "Hinzugefügte Tags",
+            "placeholder": "Tag eingeben und Enter drücken...",
+            "appendTags": "Tags anhängen",
+            "replaceTags": "Tags ersetzen",
+            "saveChanges": "Änderungen speichern"
+        },
+        "bulkBaseModel": {
+            "title": "Basis-Modell für mehrere Modelle festlegen",
+            "description": "Basis-Modell festlegen für",
+            "models": "Modelle",
+            "selectBaseModel": "Basis-Modell auswählen",
+            "save": "Basis-Modell aktualisieren",
+            "cancel": "Abbrechen"
+        },
         "exampleAccess": {
             "title": "Lokale Beispielbilder",
             "message": "Keine lokalen Beispielbilder für dieses Modell gefunden. Ansichtsoptionen:",
@@ -622,7 +770,12 @@
                 "editBaseModel": "Basis-Modell bearbeiten",
                 "viewOnCivitai": "Auf Civitai anzeigen",
                 "viewOnCivitaiText": "Auf Civitai anzeigen",
-                "viewCreatorProfile": "Ersteller-Profil anzeigen"
+                "viewCreatorProfile": "Ersteller-Profil anzeigen",
+                "openFileLocation": "Dateispeicherort öffnen"
+            },
+            "openFileLocation": {
+                "success": "Dateispeicherort erfolgreich geöffnet",
+                "failed": "Fehler beim Öffnen des Dateispeicherorts"
             },
             "metadata": {
                 "version": "Version",
@@ -646,6 +799,7 @@
                 "strengthMin": "Stärke Min",
                 "strengthMax": "Stärke Max",
                 "strength": "Stärke",
+                "clipStrength": "Clip-Stärke",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "Wert",
                 "add": "Hinzufügen"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "{completed} von {total} LoRAs heruntergeladen. {accessFailures} fehlgeschlagen aufgrund von Zugriffsbeschränkungen. Überprüfen Sie Ihren API-Schlüssel in den Einstellungen oder den Early Access-Status.",
             "pleaseSelectVersion": "Bitte wählen Sie eine Version aus",
             "versionExists": "Diese Version existiert bereits in Ihrer Bibliothek",
-            "downloadCompleted": "Download erfolgreich abgeschlossen"
+            "downloadCompleted": "Download erfolgreich abgeschlossen",
+            "autoOrganizeSuccess": "Automatische Organisation für {count} {type} erfolgreich abgeschlossen",
+            "autoOrganizePartialSuccess": "Automatische Organisation abgeschlossen: {success} verschoben, {failures} fehlgeschlagen von insgesamt {total} Modellen",
+            "autoOrganizeFailed": "Automatische Organisation fehlgeschlagen: {error}",
+            "noModelsSelected": "Keine Modelle ausgewählt"
         },
         "recipes": {
             "fetchFailed": "Fehler beim Abrufen der Rezepte: {message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "Fehler: {error}",
             "deleteFailedGeneral": "Fehler beim Löschen der Modelle",
             "selectedAdditional": "{count} zusätzliche {type}(s) ausgewählt",
+            "marqueeSelectionComplete": "{count} {type}(s) mit Rahmenauswahl ausgewählt",
             "refreshMetadataFailed": "Fehler beim Aktualisieren der Metadaten",
             "nameCannotBeEmpty": "Modellname darf nicht leer sein",
             "nameUpdatedSuccessfully": "Modellname erfolgreich aktualisiert",
             "nameUpdateFailed": "Fehler beim Aktualisieren des Modellnamens",
             "baseModelUpdated": "Basis-Modell erfolgreich aktualisiert",
             "baseModelUpdateFailed": "Fehler beim Aktualisieren des Basis-Modells",
+            "baseModelNotSelected": "Bitte ein Basis-Modell auswählen",
+            "bulkBaseModelUpdating": "Basis-Modell wird für {count} Modell(e) aktualisiert...",
+            "bulkBaseModelUpdateSuccess": "Basis-Modell erfolgreich für {count} Modell(e) aktualisiert",
+            "bulkBaseModelUpdatePartial": "{success} Modelle aktualisiert, {failed} fehlgeschlagen",
+            "bulkBaseModelUpdateFailed": "Aktualisierung des Basis-Modells für ausgewählte Modelle fehlgeschlagen",
+            "bulkContentRatingUpdating": "Inhaltsbewertung wird für {count} Modell(e) aktualisiert...",
+            "bulkContentRatingSet": "Inhaltsbewertung auf {level} für {count} Modell(e) gesetzt",
+            "bulkContentRatingPartial": "Inhaltsbewertung auf {level} für {success} Modell(e) gesetzt, {failed} fehlgeschlagen",
+            "bulkContentRatingFailed": "Inhaltsbewertung für ausgewählte Modelle konnte nicht aktualisiert werden",
             "invalidCharactersRemoved": "Ungültige Zeichen aus Dateiname entfernt",
             "filenameCannotBeEmpty": "Dateiname darf nicht leer sein",
             "renameFailed": "Fehler beim Umbenennen der Datei: {message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "Diese Gruppe wurde bereits verifiziert",
             "verificationCompleteMismatch": "Verifikation abgeschlossen. {count} Datei(en) haben unterschiedliche tatsächliche Hashes.",
             "verificationCompleteSuccess": "Verifikation abgeschlossen. Alle Dateien sind bestätigte Duplikate.",
-            "verificationFailed": "Fehler beim Verifizieren der Hashes: {message}"
+            "verificationFailed": "Fehler beim Verifizieren der Hashes: {message}",
+            "noTagsToAdd": "Keine Tags zum Hinzufügen",
+            "tagsAddedSuccessfully": "Erfolgreich {tagCount} Tag(s) zu {count} {type}(s) hinzugefügt",
+            "tagsReplacedSuccessfully": "Tags für {count} {type}(s) erfolgreich durch {tagCount} Tag(s) ersetzt",
+            "tagsAddFailed": "Fehler beim Hinzufügen von Tags zu {count} Modell(en)",
+            "tagsReplaceFailed": "Fehler beim Ersetzen von Tags für {count} Modell(e)",
+            "bulkTagsAddFailed": "Fehler beim Hinzufügen von Tags zu Modellen",
+            "bulkTagsReplaceFailed": "Fehler beim Ersetzen von Tags für Modelle"
         },
         "search": {
             "atLeastOneOption": "Mindestens eine Suchoption muss ausgewählt werden"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "Kompakt-Modus {state}",
             "settingSaveFailed": "Fehler beim Speichern der Einstellung: {message}",
             "displayDensitySet": "Anzeige-Dichte auf {density} gesetzt",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "Fehler beim Ändern der Sprache: {message}",
             "cacheCleared": "Cache-Dateien wurden erfolgreich gelöscht. Cache wird bei der nächsten Aktion neu aufgebaut.",
             "cacheClearFailed": "Fehler beim Löschen des Caches: {error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "Beispielbilder-Pfad erfolgreich aktualisiert",
+            "pathUpdateFailed": "Fehler beim Aktualisieren des Beispielbilder-Pfads: {message}",
             "downloadInProgress": "Download bereits in Bearbeitung",
             "enterLocationFirst": "Bitte geben Sie zuerst einen Download-Speicherort ein",
             "downloadStarted": "Beispielbilder-Download gestartet",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "Fehler beim Pausieren des Downloads: {error}",
             "downloadResumed": "Download fortgesetzt",
             "resumeFailed": "Fehler beim Fortsetzen des Downloads: {error}",
+            "downloadStopped": "Download abgebrochen",
+            "stopFailed": "Download konnte nicht abgebrochen werden: {error}",
             "deleted": "Beispielbild gelöscht",
             "deleteFailed": "Fehler beim Löschen des Beispielbilds",
             "setPreviewFailed": "Fehler beim Setzen des Vorschaubilds"
@@ -1123,6 +1303,12 @@
             "refreshNow": "Jetzt aktualisieren",
             "refreshingIn": "Aktualisierung in",
             "seconds": "Sekunden"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/en.json

@@ -16,7 +16,9 @@
             "loading": "Loading...",
             "unknown": "Unknown",
             "date": "Date",
-            "version": "Version"
+            "version": "Version",
+            "enabled": "Enabled",
+            "disabled": "Disabled"
         },
         "language": {
             "select": "Language",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+			"Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 Bytes",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "No remote example images available for this model on Civitai"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "Download example images",
+            "missingPath": "Set a download location before downloading example images.",
+            "unavailable": "Example image downloads aren't available yet. Try again after the page finishes loading."
+        },
+        "cleanupExampleImages": {
+            "label": "Clean up example image folders",
+            "success": "Moved {count} folder(s) to the deleted folder",
+            "none": "No example image folders needed cleanup",
+            "partial": "Cleanup completed with {failures} folder(s) skipped",
+            "error": "Failed to clean example image folders: {message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA Manager",
         "navigation": {
@@ -171,14 +188,23 @@
         "civitaiApiKey": "Civitai API Key",
         "civitaiApiKeyPlaceholder": "Enter your Civitai API key",
         "civitaiApiKeyHelp": "Used for authentication when downloading models from Civitai",
+        "openSettingsFileLocation": {
+            "label": "Open settings folder",
+            "tooltip": "Open the folder containing settings.json",
+            "success": "Opened settings.json folder",
+            "failed": "Failed to open settings.json folder"
+        },
         "sections": {
             "contentFiltering": "Content Filtering",
             "videoSettings": "Video Settings",
             "layoutSettings": "Layout Settings",
             "folderSettings": "Folder Settings",
+            "priorityTags": "Priority Tags",
             "downloadPathTemplates": "Download Path Templates",
             "exampleImages": "Example Images",
-            "misc": "Misc."
+            "misc": "Misc.",
+            "metadataArchive": "Metadata Archive Database",
+            "proxySettings": "Proxy Settings"
         },
         "contentFiltering": {
             "blurNsfwContent": "Blur NSFW Content",
@@ -199,9 +225,9 @@
             },
             "displayDensityHelp": "Choose how many cards to display per row:",
             "displayDensityDetails": {
-                "default": "Default: 5 (1080p), 6 (2K), 8 (4K)",
-                "medium": "Medium: 6 (1080p), 7 (2K), 9 (4K)",
-                "compact": "Compact: 7 (1080p), 8 (2K), 10 (4K)"
+                "default": "5 (1080p), 6 (2K), 8 (4K)",
+                "medium": "6 (1080p), 7 (2K), 9 (4K)",
+                "compact": "7 (1080p), 8 (2K), 10 (4K)"
             },
             "displayDensityWarning": "Warning: Higher densities may cause performance issues on systems with limited resources.",
             "cardInfoDisplay": "Card Info Display",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "Choose when to display model information and action buttons:",
             "cardInfoDisplayDetails": {
-                "always": "Always Visible: Headers and footers are always visible",
-                "hover": "Reveal on Hover: Headers and footers only appear when hovering over a card"
+                "always": "Headers and footers are always visible",
+                "hover": "Headers and footers only appear when hovering over a card"
+            },
+            "modelNameDisplay": "Model Name Display",
+            "modelNameDisplayOptions": {
+                "modelName": "Model Name",
+                "fileName": "File Name"
+            },
+            "modelNameDisplayHelp": "Choose what to display in the model card footer:",
+            "modelNameDisplayDetails": {
+                "modelName": "Display the model's descriptive name",
+                "fileName": "Display the actual file name on disk"
             }
         },
         "folderSettings": {
+            "activeLibrary": "Active Library",
+            "activeLibraryHelp": "Switch between configured libraries to update default folders. Changing the selection reloads the page.",
+            "loadingLibraries": "Loading libraries...",
+            "noLibraries": "No libraries configured",
             "defaultLoraRoot": "Default LoRA Root",
             "defaultLoraRootHelp": "Set the default LoRA root directory for downloads, imports and moves",
             "defaultCheckpointRoot": "Default Checkpoint Root",
@@ -224,6 +264,26 @@
             "defaultEmbeddingRootHelp": "Set the default embedding root directory for downloads, imports and moves",
             "noDefault": "No Default"
         },
+        "priorityTags": {
+            "title": "Priority Tags",
+            "description": "Customize the tag priority order for each model type (e.g., character, concept, style(toon|toon_style))",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "Open priority tags help",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "Checkpoint",
+                "embedding": "Embedding"
+            },
+            "saveSuccess": "Priority tags updated.",
+            "saveError": "Failed to update priority tags.",
+            "loadingSuggestions": "Loading suggestions...",
+            "validation": {
+                "missingClosingParen": "Entry {index} is missing a closing parenthesis.",
+                "missingCanonical": "Entry {index} must include a canonical tag name.",
+                "duplicateCanonical": "The canonical tag \"{tag}\" appears more than once.",
+                "unknown": "Invalid priority tag configuration."
+            }
+        },
         "downloadPathTemplates": {
             "title": "Download Path Templates",
             "help": "Configure folder structures for different model types when downloading from Civitai.",
@@ -236,6 +296,7 @@
                 "baseModelFirstTag": "Base Model + First Tag",
                 "baseModelAuthor": "Base Model + Author",
                 "authorFirstTag": "Author + First Tag",
+                "baseModelAuthorFirstTag": "Base Model + Author + First Tag",
                 "customTemplate": "Custom Template"
             },
             "customTemplatePlaceholder": "Enter custom template (e.g., {base_model}/{author}/{first_tag})",
@@ -273,6 +334,48 @@
         "misc": {
             "includeTriggerWords": "Include Trigger Words in LoRA Syntax",
             "includeTriggerWordsHelp": "Include trained trigger words when copying LoRA syntax to clipboard"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "Enable Metadata Archive Database",
+            "enableArchiveDbHelp": "Use a local database to access metadata for models that have been deleted from Civitai.",
+            "status": "Status",
+            "statusAvailable": "Available",
+            "statusUnavailable": "Not Available",
+            "enabled": "Enabled",
+            "management": "Database Management",
+            "managementHelp": "Download or remove the metadata archive database",
+            "downloadButton": "Download Database",
+            "downloadingButton": "Downloading...",
+            "downloadedButton": "Downloaded",
+            "removeButton": "Remove Database",
+            "removingButton": "Removing...",
+            "downloadSuccess": "Metadata archive database downloaded successfully",
+            "downloadError": "Failed to download metadata archive database",
+            "removeSuccess": "Metadata archive database removed successfully",
+            "removeError": "Failed to remove metadata archive database",
+            "removeConfirm": "Are you sure you want to remove the metadata archive database? This will delete the local database file and you'll need to download it again to use this feature.",
+            "preparing": "Preparing download...",
+            "connecting": "Connecting to download server...",
+            "completed": "Completed",
+            "downloadComplete": "Download completed successfully"
+        },
+        "proxySettings": {
+            "enableProxy": "Enable App-level Proxy",
+            "enableProxyHelp": "Enable custom proxy settings for this application, overriding system proxy settings",
+            "proxyType": "Proxy Type",
+            "proxyTypeHelp": "Select the type of proxy server (HTTP, HTTPS, SOCKS4, SOCKS5)",
+            "proxyHost": "Proxy Host",
+            "proxyHostPlaceholder": "proxy.example.com",
+            "proxyHostHelp": "The hostname or IP address of your proxy server",
+            "proxyPort": "Proxy Port", 
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "The port number of your proxy server",
+            "proxyUsername": "Username (Optional)",
+            "proxyUsernamePlaceholder": "username", 
+            "proxyUsernameHelp": "Username for proxy authentication (if required)",
+            "proxyPassword": "Password (Optional)",
+            "proxyPasswordPlaceholder": "password",
+            "proxyPasswordHelp": "Password for proxy authentication (if required)"
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "{count} selected",
             "selectedSuffix": "selected",
-            "viewSelected": "Click to view selected items",
-            "sendToWorkflow": "Send to Workflow",
-            "copyAll": "Copy All",
-            "refreshAll": "Refresh All",
-            "moveAll": "Move All",
-            "deleteAll": "Delete All",
-            "clear": "Clear"
+            "viewSelected": "View Selected",
+            "addTags": "Add Tags to Selected",
+            "setBaseModel": "Set Base Model for Selected",
+            "setContentRating": "Set Content Rating for Selected",
+            "copyAll": "Copy Selected Syntax",
+            "refreshAll": "Refresh Selected Metadata",
+            "moveAll": "Move Selected to Folder",
+            "autoOrganize": "Auto-Organize Selected",
+            "deleteAll": "Delete Selected Models",
+            "clear": "Clear Selection",
+            "autoOrganizeProgress": {
+                "initializing": "Initializing auto-organize...",
+                "starting": "Starting auto-organize for {type}...",
+                "processing": "Processing ({processed}/{total}) - {success} moved, {skipped} skipped, {failures} failed",
+                "cleaning": "Cleaning up empty directories...",
+                "completed": "Completed: {success} moved, {skipped} skipped, {failures} failed",
+                "complete": "Auto-organize complete",
+                "error": "Error: {error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "Refresh Civitai Data",
@@ -445,13 +560,19 @@
         "title": "Embedding Models"
     },
     "sidebar": {
-        "modelRoot": "Model Root",
+        "modelRoot": "Root",
         "collapseAll": "Collapse All Folders",
         "pinSidebar": "Pin Sidebar",
         "unpinSidebar": "Unpin Sidebar",
         "switchToListView": "Switch to List View",
         "switchToTreeView": "Switch to Tree View",
-        "collapseAllDisabled": "Not available in list view"
+        "recursiveOn": "Search subfolders",
+        "recursiveOff": "Search current folder only",
+        "recursiveUnavailable": "Recursive search is available in tree view only",
+        "collapseAllDisabled": "Not available in list view",
+        "dragDrop": {
+            "unableToResolveRoot": "Unable to determine destination path for move."
+        }
     },
     "statistics": {
         "title": "Statistics",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "Downloaded preview image",
                 "downloadingFile": "Downloading {type} file",
                 "finalizing": "Finalizing download..."
+            },
+            "progress": {
+                "currentFile": "Current file:",
+                "downloading": "Downloading: {name}",
+                "transferred": "Transferred: {downloaded} / {total}",
+                "transferredSimple": "Transferred: {downloaded}",
+                "transferredUnknown": "Transferred: --",
+                "speed": "Speed: {speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "Set Content Rating",
             "current": "Current",
+            "multiple": "Multiple values",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "models will be permanently deleted.",
             "action": "Delete All"
         },
+        "bulkAddTags": {
+            "title": "Add Tags to Multiple Models",
+            "description": "Add tags to",
+            "models": "models",
+            "tagsToAdd": "Tags to Add",
+            "placeholder": "Enter tag and press Enter...",
+            "appendTags": "Append Tags",
+            "replaceTags": "Replace Tags",
+            "saveChanges": "Save changes"
+        },
+        "bulkBaseModel": {
+            "title": "Set Base Model for Multiple Models",
+            "description": "Set base model for",
+            "models": "models",
+            "selectBaseModel": "Select Base Model",
+            "save": "Update Base Model",
+            "cancel": "Cancel"
+        },
         "exampleAccess": {
             "title": "Local Example Images",
             "message": "No local example images found for this model. View options:",
@@ -622,7 +770,12 @@
                 "editBaseModel": "Edit base model",
                 "viewOnCivitai": "View on Civitai",
                 "viewOnCivitaiText": "View on Civitai",
-                "viewCreatorProfile": "View Creator Profile"
+                "viewCreatorProfile": "View Creator Profile",
+                "openFileLocation": "Open File Location"
+            },
+            "openFileLocation": {
+                "success": "File location opened successfully",
+                "failed": "Failed to open file location"
             },
             "metadata": {
                 "version": "Version",
@@ -646,6 +799,7 @@
                 "strengthMin": "Strength Min",
                 "strengthMax": "Strength Max",
                 "strength": "Strength",
+                "clipStrength": "Clip Strength",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "Value",
                 "add": "Add"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "Downloaded {completed} of {total} LoRAs. {accessFailures} failed due to access restrictions. Check your API key in settings or early access status.",
             "pleaseSelectVersion": "Please select a version",
             "versionExists": "This version already exists in your library",
-            "downloadCompleted": "Download completed successfully"
+            "downloadCompleted": "Download completed successfully",
+            "autoOrganizeSuccess": "Auto-organize completed successfully for {count} {type}",
+            "autoOrganizePartialSuccess": "Auto-organize completed with {success} moved, {failures} failed out of {total} models",
+            "autoOrganizeFailed": "Auto-organize failed: {error}",
+            "noModelsSelected": "No models selected"
         },
         "recipes": {
             "fetchFailed": "Failed to fetch recipes: {message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "Error: {error}",
             "deleteFailedGeneral": "Failed to delete models",
             "selectedAdditional": "Selected {count} additional {type}(s)",
+            "marqueeSelectionComplete": "Selected {count} {type}(s) with marquee selection",
             "refreshMetadataFailed": "Failed to refresh metadata",
             "nameCannotBeEmpty": "Model name cannot be empty",
             "nameUpdatedSuccessfully": "Model name updated successfully",
             "nameUpdateFailed": "Failed to update model name",
             "baseModelUpdated": "Base model updated successfully",
             "baseModelUpdateFailed": "Failed to update base model",
+            "baseModelNotSelected": "Please select a base model",
+            "bulkBaseModelUpdating": "Updating base model for {count} model(s)...",
+            "bulkBaseModelUpdateSuccess": "Successfully updated base model for {count} model(s)",
+            "bulkBaseModelUpdatePartial": "Updated {success} model(s), failed {failed} model(s)",
+            "bulkBaseModelUpdateFailed": "Failed to update base model for selected models",
+            "bulkContentRatingUpdating": "Updating content rating for {count} model(s)...",
+            "bulkContentRatingSet": "Set content rating to {level} for {count} model(s)",
+            "bulkContentRatingPartial": "Set content rating to {level} for {success} model(s), {failed} failed",
+            "bulkContentRatingFailed": "Failed to update content rating for selected models",
             "invalidCharactersRemoved": "Invalid characters removed from filename",
             "filenameCannotBeEmpty": "File name cannot be empty",
             "renameFailed": "Failed to rename file: {message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "This group has already been verified",
             "verificationCompleteMismatch": "Verification complete. {count} file(s) have different actual hashes.",
             "verificationCompleteSuccess": "Verification complete. All files are confirmed duplicates.",
-            "verificationFailed": "Failed to verify hashes: {message}"
+            "verificationFailed": "Failed to verify hashes: {message}",
+            "noTagsToAdd": "No tags to add",
+            "tagsAddedSuccessfully": "Successfully added {tagCount} tag(s) to {count} {type}(s)",
+            "tagsReplacedSuccessfully": "Successfully replaced tags for {count} {type}(s) with {tagCount} tag(s)",
+            "tagsAddFailed": "Failed to add tags to {count} model(s)",
+            "tagsReplaceFailed": "Failed to replace tags for {count} model(s)",
+            "bulkTagsAddFailed": "Failed to add tags to models",
+            "bulkTagsReplaceFailed": "Failed to replace tags for models"
         },
         "search": {
             "atLeastOneOption": "At least one search option must be selected"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "Compact Mode {state}",
             "settingSaveFailed": "Failed to save setting: {message}",
             "displayDensitySet": "Display Density set to {density}",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "Failed to change language: {message}",
             "cacheCleared": "Cache files have been cleared successfully. Cache will rebuild on next action.",
             "cacheClearFailed": "Failed to clear cache: {error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "Example images path updated successfully",
+            "pathUpdateFailed": "Failed to update example images path: {message}",
             "downloadInProgress": "Download already in progress",
             "enterLocationFirst": "Please enter a download location first",
             "downloadStarted": "Example images download started",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "Failed to pause download: {error}",
             "downloadResumed": "Download resumed",
             "resumeFailed": "Failed to resume download: {error}",
+            "downloadStopped": "Download cancelled",
+            "stopFailed": "Failed to cancel download: {error}",
             "deleted": "Example image deleted",
             "deleteFailed": "Failed to delete example image",
             "setPreviewFailed": "Failed to set preview image"
@@ -1123,6 +1303,12 @@
             "refreshNow": "Refresh Now",
             "refreshingIn": "Refreshing in",
             "seconds": "seconds"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/es.json

@@ -16,7 +16,9 @@
             "loading": "Cargando...",
             "unknown": "Desconocido",
             "date": "Fecha",
-            "version": "Versión"
+            "version": "Versión",
+            "enabled": "Habilitado",
+            "disabled": "Deshabilitado"
         },
         "language": {
             "select": "Idioma",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 Bytes",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "No hay imágenes de ejemplo remotas disponibles para este modelo en Civitai"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "Descargar imágenes de ejemplo",
+            "missingPath": "Establece una ubicación de descarga antes de descargar imágenes de ejemplo.",
+            "unavailable": "Las descargas de imágenes de ejemplo aún no están disponibles. Intenta de nuevo después de que la página termine de cargar."
+        },
+        "cleanupExampleImages": {
+            "label": "Limpiar carpetas de imágenes de ejemplo",
+            "success": "Se movieron {count} carpeta(s) a la carpeta de eliminados",
+            "none": "No hay carpetas de imágenes de ejemplo que necesiten limpieza",
+            "partial": "Limpieza completada con {failures} carpeta(s) omitidas",
+            "error": "No se pudieron limpiar las carpetas de imágenes de ejemplo: {message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA Manager",
         "navigation": {
@@ -171,14 +188,23 @@
         "civitaiApiKey": "Clave API de Civitai",
         "civitaiApiKeyPlaceholder": "Introduce tu clave API de Civitai",
         "civitaiApiKeyHelp": "Utilizada para autenticación al descargar modelos de Civitai",
+        "openSettingsFileLocation": {
+            "label": "Abrir carpeta de ajustes",
+            "tooltip": "Abrir la carpeta que contiene settings.json",
+            "success": "Carpeta de settings.json abierta",
+            "failed": "No se pudo abrir la carpeta de settings.json"
+        },
         "sections": {
             "contentFiltering": "Filtrado de contenido",
             "videoSettings": "Configuración de video",
             "layoutSettings": "Configuración de diseño",
             "folderSettings": "Configuración de carpetas",
+            "priorityTags": "Etiquetas prioritarias",
             "downloadPathTemplates": "Plantillas de rutas de descarga",
             "exampleImages": "Imágenes de ejemplo",
-            "misc": "Varios"
+            "misc": "Varios",
+            "metadataArchive": "Base de datos de archivo de metadatos",
+            "proxySettings": "Configuración de proxy"
         },
         "contentFiltering": {
             "blurNsfwContent": "Difuminar contenido NSFW",
@@ -194,14 +220,14 @@
             "displayDensity": "Densidad de visualización",
             "displayDensityOptions": {
                 "default": "Predeterminado",
-                "medium": "Medio", 
+                "medium": "Medio",
                 "compact": "Compacto"
             },
             "displayDensityHelp": "Elige cuántas tarjetas mostrar por fila:",
             "displayDensityDetails": {
-                "default": "Predeterminado: 5 (1080p), 6 (2K), 8 (4K)",
-                "medium": "Medio: 6 (1080p), 7 (2K), 9 (4K)",
-                "compact": "Compacto: 7 (1080p), 8 (2K), 10 (4K)"
+                "default": "5 (1080p), 6 (2K), 8 (4K)",
+                "medium": "6 (1080p), 7 (2K), 9 (4K)",
+                "compact": "7 (1080p), 8 (2K), 10 (4K)"
             },
             "displayDensityWarning": "Advertencia: Densidades más altas pueden causar problemas de rendimiento en sistemas con recursos limitados.",
             "cardInfoDisplay": "Visualización de información de tarjeta",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "Elige cuándo mostrar información del modelo y botones de acción:",
             "cardInfoDisplayDetails": {
-                "always": "Siempre visible: Los encabezados y pies de página siempre son visibles",
-                "hover": "Mostrar al pasar el ratón: Los encabezados y pies de página solo aparecen al pasar el ratón sobre una tarjeta"
+                "always": "Los encabezados y pies de página siempre son visibles",
+                "hover": "Los encabezados y pies de página solo aparecen al pasar el ratón sobre una tarjeta"
+            },
+            "modelNameDisplay": "Visualización del nombre del modelo",
+            "modelNameDisplayOptions": {
+                "modelName": "Nombre del modelo",
+                "fileName": "Nombre del archivo"
+            },
+            "modelNameDisplayHelp": "Elige qué mostrar en el pie de la tarjeta del modelo:",
+            "modelNameDisplayDetails": {
+                "modelName": "Mostrar el nombre descriptivo del modelo",
+                "fileName": "Mostrar el nombre real del archivo en el disco"
             }
         },
         "folderSettings": {
+            "activeLibrary": "Biblioteca activa",
+            "activeLibraryHelp": "Alterna entre las bibliotecas configuradas para actualizar las carpetas predeterminadas. Cambiar la selección recarga la página.",
+            "loadingLibraries": "Cargando bibliotecas...",
+            "noLibraries": "No hay bibliotecas configuradas",
             "defaultLoraRoot": "Raíz predeterminada de LoRA",
             "defaultLoraRootHelp": "Establecer el directorio raíz predeterminado de LoRA para descargas, importaciones y movimientos",
             "defaultCheckpointRoot": "Raíz predeterminada de checkpoint",
@@ -224,6 +264,26 @@
             "defaultEmbeddingRootHelp": "Establecer el directorio raíz predeterminado de embedding para descargas, importaciones y movimientos",
             "noDefault": "Sin predeterminado"
         },
+        "priorityTags": {
+            "title": "Etiquetas prioritarias",
+            "description": "Personaliza el orden de prioridad de etiquetas para cada tipo de modelo (p. ej., character, concept, style(toon|toon_style))",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "Abrir ayuda de etiquetas prioritarias",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "Checkpoint",
+                "embedding": "Embedding"
+            },
+            "saveSuccess": "Etiquetas prioritarias actualizadas.",
+            "saveError": "Error al actualizar las etiquetas prioritarias.",
+            "loadingSuggestions": "Cargando sugerencias...",
+            "validation": {
+                "missingClosingParen": "A la entrada {index} le falta un paréntesis de cierre.",
+                "missingCanonical": "La entrada {index} debe incluir un nombre de etiqueta canónica.",
+                "duplicateCanonical": "La etiqueta canónica \"{tag}\" aparece más de una vez.",
+                "unknown": "Configuración de etiquetas prioritarias no válida."
+            }
+        },
         "downloadPathTemplates": {
             "title": "Plantillas de rutas de descarga",
             "help": "Configurar estructuras de carpetas para diferentes tipos de modelos al descargar de Civitai.",
@@ -231,17 +291,18 @@
             "templateOptions": {
                 "flatStructure": "Estructura plana",
                 "byBaseModel": "Por modelo base",
-                "byAuthor": "Por autor", 
+                "byAuthor": "Por autor",
                 "byFirstTag": "Por primera etiqueta",
                 "baseModelFirstTag": "Modelo base + primera etiqueta",
                 "baseModelAuthor": "Modelo base + autor",
                 "authorFirstTag": "Autor + primera etiqueta",
+                "baseModelAuthorFirstTag": "Modelo base + autor + primera etiqueta",
                 "customTemplate": "Plantilla personalizada"
             },
             "customTemplatePlaceholder": "Introduce plantilla personalizada (ej., {base_model}/{author}/{first_tag})",
             "modelTypes": {
                 "lora": "LoRA",
-                "checkpoint": "Checkpoint", 
+                "checkpoint": "Checkpoint",
                 "embedding": "Embedding"
             },
             "baseModelPathMappings": "Mapeos de rutas de modelo base",
@@ -273,6 +334,48 @@
         "misc": {
             "includeTriggerWords": "Incluir palabras clave en la sintaxis de LoRA",
             "includeTriggerWordsHelp": "Incluir palabras clave entrenadas al copiar la sintaxis de LoRA al portapapeles"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "Habilitar base de datos de archivo de metadatos",
+            "enableArchiveDbHelp": "Utiliza una base de datos local para acceder a metadatos de modelos que han sido eliminados de Civitai.",
+            "status": "Estado",
+            "statusAvailable": "Disponible",
+            "statusUnavailable": "No disponible",
+            "enabled": "Habilitado",
+            "management": "Gestión de base de datos",
+            "managementHelp": "Descargar o eliminar la base de datos de archivo de metadatos",
+            "downloadButton": "Descargar base de datos",
+            "downloadingButton": "Descargando...",
+            "downloadedButton": "Descargado",
+            "removeButton": "Eliminar base de datos",
+            "removingButton": "Eliminando...",
+            "downloadSuccess": "Base de datos de archivo de metadatos descargada exitosamente",
+            "downloadError": "Error al descargar la base de datos de archivo de metadatos",
+            "removeSuccess": "Base de datos de archivo de metadatos eliminada exitosamente",
+            "removeError": "Error al eliminar la base de datos de archivo de metadatos",
+            "removeConfirm": "¿Estás seguro de que quieres eliminar la base de datos de archivo de metadatos? Esto eliminará el archivo de base de datos local y tendrás que descargarlo de nuevo para usar esta función.",
+            "preparing": "Preparando descarga...",
+            "connecting": "Conectando al servidor de descarga...",
+            "completed": "Completado",
+            "downloadComplete": "Descarga completada exitosamente"
+        },
+        "proxySettings": {
+            "enableProxy": "Habilitar proxy a nivel de aplicación",
+            "enableProxyHelp": "Habilita la configuración de proxy personalizada para esta aplicación, sobrescribiendo la configuración de proxy del sistema",
+            "proxyType": "Tipo de proxy",
+            "proxyTypeHelp": "Selecciona el tipo de servidor proxy (HTTP, HTTPS, SOCKS4, SOCKS5)",
+            "proxyHost": "Host del proxy",
+            "proxyHostPlaceholder": "proxy.ejemplo.com",
+            "proxyHostHelp": "El nombre de host o dirección IP de tu servidor proxy",
+            "proxyPort": "Puerto del proxy",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "El número de puerto de tu servidor proxy",
+            "proxyUsername": "Usuario (opcional)",
+            "proxyUsernamePlaceholder": "usuario",
+            "proxyUsernameHelp": "Usuario para autenticación de proxy (si es necesario)",
+            "proxyPassword": "Contraseña (opcional)",
+            "proxyPasswordPlaceholder": "contraseña",
+            "proxyPasswordHelp": "Contraseña para autenticación de proxy (si es necesario)"
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "{count} seleccionados",
             "selectedSuffix": "seleccionados",
-            "viewSelected": "Clic para ver elementos seleccionados",
-            "sendToWorkflow": "Enviar al flujo de trabajo",
-            "copyAll": "Copiar todo",
-            "refreshAll": "Actualizar todo",
-            "moveAll": "Mover todo",
-            "deleteAll": "Eliminar todo",
-            "clear": "Limpiar"
+            "viewSelected": "Ver seleccionados",
+            "addTags": "Añadir etiquetas a todos",
+            "setBaseModel": "Establecer modelo base para todos",
+            "setContentRating": "Establecer clasificación de contenido para todos",
+            "copyAll": "Copiar toda la sintaxis",
+            "refreshAll": "Actualizar todos los metadatos",
+            "moveAll": "Mover todos a carpeta",
+            "autoOrganize": "Auto-organizar seleccionados",
+            "deleteAll": "Eliminar todos los modelos",
+            "clear": "Limpiar selección",
+            "autoOrganizeProgress": {
+                "initializing": "Inicializando auto-organización...",
+                "starting": "Iniciando auto-organización para {type}...",
+                "processing": "Procesando ({processed}/{total}) - {success} movidos, {skipped} omitidos, {failures} fallidos",
+                "cleaning": "Limpiando directorios vacíos...",
+                "completed": "Completado: {success} movidos, {skipped} omitidos, {failures} fallidos",
+                "complete": "Auto-organización completada",
+                "error": "Error: {error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "Actualizar datos de Civitai",
@@ -445,13 +560,19 @@
         "title": "Modelos embedding"
     },
     "sidebar": {
-        "modelRoot": "Raíz del modelo",
+        "modelRoot": "Raíz",
         "collapseAll": "Colapsar todas las carpetas",
         "pinSidebar": "Fijar barra lateral",
         "unpinSidebar": "Desfijar barra lateral",
         "switchToListView": "Cambiar a vista de lista",
         "switchToTreeView": "Cambiar a vista de árbol",
-        "collapseAllDisabled": "No disponible en vista de lista"
+        "recursiveOn": "Buscar en subcarpetas",
+        "recursiveOff": "Buscar solo en la carpeta actual",
+        "recursiveUnavailable": "La búsqueda recursiva solo está disponible en la vista en árbol",
+        "collapseAllDisabled": "No disponible en vista de lista",
+        "dragDrop": {
+            "unableToResolveRoot": "No se puede determinar la ruta de destino para el movimiento."
+        }
     },
     "statistics": {
         "title": "Estadísticas",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "Imagen de vista previa descargada",
                 "downloadingFile": "Descargando archivo de {type}",
                 "finalizing": "Finalizando descarga..."
+            },
+            "progress": {
+                "currentFile": "Archivo actual:",
+                "downloading": "Descargando: {name}",
+                "transferred": "Descargado: {downloaded} / {total}",
+                "transferredSimple": "Descargado: {downloaded}",
+                "transferredUnknown": "Descargado: --",
+                "speed": "Velocidad: {speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "Establecer clasificación de contenido",
             "current": "Actual",
+            "multiple": "Valores múltiples",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "modelos serán eliminados permanentemente.",
             "action": "Eliminar todo"
         },
+        "bulkAddTags": {
+            "title": "Añadir etiquetas a múltiples modelos",
+            "description": "Añadir etiquetas a",
+            "models": "modelos",
+            "tagsToAdd": "Etiquetas a añadir",
+            "placeholder": "Introduce una etiqueta y presiona Enter...",
+            "appendTags": "Añadir etiquetas",
+            "replaceTags": "Reemplazar etiquetas",
+            "saveChanges": "Guardar cambios"
+        },
+        "bulkBaseModel": {
+            "title": "Establecer modelo base para múltiples modelos",
+            "description": "Establecer modelo base para",
+            "models": "modelos",
+            "selectBaseModel": "Seleccionar modelo base",
+            "save": "Actualizar modelo base",
+            "cancel": "Cancelar"
+        },
         "exampleAccess": {
             "title": "Imágenes de ejemplo locales",
             "message": "No se encontraron imágenes de ejemplo locales para este modelo. Opciones de visualización:",
@@ -622,7 +770,12 @@
                 "editBaseModel": "Editar modelo base",
                 "viewOnCivitai": "Ver en Civitai",
                 "viewOnCivitaiText": "Ver en Civitai",
-                "viewCreatorProfile": "Ver perfil del creador"
+                "viewCreatorProfile": "Ver perfil del creador",
+                "openFileLocation": "Abrir ubicación del archivo"
+            },
+            "openFileLocation": {
+                "success": "Ubicación del archivo abierta exitosamente",
+                "failed": "Error al abrir la ubicación del archivo"
             },
             "metadata": {
                 "version": "Versión",
@@ -646,6 +799,7 @@
                 "strengthMin": "Fuerza mínima",
                 "strengthMax": "Fuerza máxima",
                 "strength": "Fuerza",
+                "clipStrength": "Fuerza de Clip",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "Valor",
                 "add": "Añadir"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "Descargados {completed} de {total} LoRAs. {accessFailures} fallaron debido a restricciones de acceso. Revisa tu clave API en configuración o estado de acceso temprano.",
             "pleaseSelectVersion": "Por favor selecciona una versión",
             "versionExists": "Esta versión ya existe en tu biblioteca",
-            "downloadCompleted": "Descarga completada exitosamente"
+            "downloadCompleted": "Descarga completada exitosamente",
+            "autoOrganizeSuccess": "Auto-organización completada exitosamente para {count} {type}",
+            "autoOrganizePartialSuccess": "Auto-organización completada con {success} movidos, {failures} fallidos de un total de {total} modelos",
+            "autoOrganizeFailed": "Auto-organización fallida: {error}",
+            "noModelsSelected": "No hay modelos seleccionados"
         },
         "recipes": {
             "fetchFailed": "Error al obtener recetas: {message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "Error: {error}",
             "deleteFailedGeneral": "Error al eliminar modelos",
             "selectedAdditional": "Seleccionados {count} {type}(s) adicionales",
+            "marqueeSelectionComplete": "Seleccionados {count} {type}(s) con selección de marco",
             "refreshMetadataFailed": "Error al actualizar metadatos",
             "nameCannotBeEmpty": "El nombre del modelo no puede estar vacío",
             "nameUpdatedSuccessfully": "Nombre del modelo actualizado exitosamente",
             "nameUpdateFailed": "Error al actualizar nombre del modelo",
             "baseModelUpdated": "Modelo base actualizado exitosamente",
             "baseModelUpdateFailed": "Error al actualizar modelo base",
+            "baseModelNotSelected": "Por favor selecciona un modelo base",
+            "bulkBaseModelUpdating": "Actualizando modelo base para {count} modelo(s)...",
+            "bulkBaseModelUpdateSuccess": "Modelo base actualizado exitosamente para {count} modelo(s)",
+            "bulkBaseModelUpdatePartial": "Actualizados {success} modelo(s), fallaron {failed} modelo(s)",
+            "bulkBaseModelUpdateFailed": "Error al actualizar el modelo base para los modelos seleccionados",
+            "bulkContentRatingUpdating": "Actualizando la clasificación de contenido para {count} modelo(s)...",
+            "bulkContentRatingSet": "Clasificación de contenido establecida en {level} para {count} modelo(s)",
+            "bulkContentRatingPartial": "Clasificación de contenido establecida en {level} para {success} modelo(s), {failed} fallaron",
+            "bulkContentRatingFailed": "No se pudo actualizar la clasificación de contenido para los modelos seleccionados",
             "invalidCharactersRemoved": "Caracteres inválidos eliminados del nombre de archivo",
             "filenameCannotBeEmpty": "El nombre de archivo no puede estar vacío",
             "renameFailed": "Error al renombrar archivo: {message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "Este grupo ya ha sido verificado",
             "verificationCompleteMismatch": "Verificación completa. {count} archivo(s) tienen hashes reales diferentes.",
             "verificationCompleteSuccess": "Verificación completa. Todos los archivos son confirmados duplicados.",
-            "verificationFailed": "Error al verificar hashes: {message}"
+            "verificationFailed": "Error al verificar hashes: {message}",
+            "noTagsToAdd": "No hay etiquetas para añadir",
+            "tagsAddedSuccessfully": "Se añadieron exitosamente {tagCount} etiqueta(s) a {count} {type}(s)",
+            "tagsReplacedSuccessfully": "Se reemplazaron exitosamente las etiquetas de {count} {type}(s) con {tagCount} etiqueta(s)",
+            "tagsAddFailed": "Error al añadir etiquetas a {count} modelo(s)",
+            "tagsReplaceFailed": "Error al reemplazar etiquetas para {count} modelo(s)",
+            "bulkTagsAddFailed": "Error al añadir etiquetas a los modelos",
+            "bulkTagsReplaceFailed": "Error al reemplazar etiquetas para los modelos"
         },
         "search": {
             "atLeastOneOption": "Al menos una opción de búsqueda debe estar seleccionada"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "Modo compacto {state}",
             "settingSaveFailed": "Error al guardar configuración: {message}",
             "displayDensitySet": "Densidad de visualización establecida a {density}",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "Error al cambiar idioma: {message}",
             "cacheCleared": "Archivos de caché limpiados exitosamente. La caché se reconstruirá en la próxima acción.",
             "cacheClearFailed": "Error al limpiar caché: {error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "Ruta de imágenes de ejemplo actualizada exitosamente",
+            "pathUpdateFailed": "Error al actualizar la ruta de imágenes de ejemplo: {message}",
             "downloadInProgress": "Descarga ya en progreso",
             "enterLocationFirst": "Por favor introduce primero una ubicación de descarga",
             "downloadStarted": "Descarga de imágenes de ejemplo iniciada",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "Error al pausar descarga: {error}",
             "downloadResumed": "Descarga reanudada",
             "resumeFailed": "Error al reanudar descarga: {error}",
+            "downloadStopped": "Descarga cancelada",
+            "stopFailed": "Error al cancelar descarga: {error}",
             "deleted": "Imagen de ejemplo eliminada",
             "deleteFailed": "Error al eliminar imagen de ejemplo",
             "setPreviewFailed": "Error al establecer imagen de vista previa"
@@ -1123,6 +1303,12 @@
             "refreshNow": "Actualizar ahora",
             "refreshingIn": "Actualizando en",
             "seconds": "segundos"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/fr.json

@@ -16,7 +16,9 @@
             "loading": "Chargement...",
             "unknown": "Inconnu",
             "date": "Date",
-            "version": "Version"
+            "version": "Version",
+            "enabled": "Activé",
+            "disabled": "Désactivé"
         },
         "language": {
             "select": "Langue",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 Octets",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "Aucune image d'exemple distante disponible pour ce modèle sur Civitai"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "Télécharger les images d'exemple",
+            "missingPath": "Définissez un emplacement de téléchargement avant de télécharger les images d'exemple.",
+            "unavailable": "Le téléchargement des images d'exemple n'est pas encore disponible. Réessayez après le chargement complet de la page."
+        },
+        "cleanupExampleImages": {
+            "label": "Nettoyer les dossiers d'images d'exemple",
+            "success": "{count} dossier(s) déplacé(s) vers le dossier supprimé",
+            "none": "Aucun dossier d'images d'exemple à nettoyer",
+            "partial": "Nettoyage terminé avec {failures} dossier(s) ignoré(s)",
+            "error": "Échec du nettoyage des dossiers d'images d'exemple : {message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA Manager",
         "navigation": {
@@ -171,6 +188,12 @@
         "civitaiApiKey": "Clé API Civitai",
         "civitaiApiKeyPlaceholder": "Entrez votre clé API Civitai",
         "civitaiApiKeyHelp": "Utilisée pour l'authentification lors du téléchargement de modèles depuis Civitai",
+        "openSettingsFileLocation": {
+            "label": "Ouvrir le dossier des paramètres",
+            "tooltip": "Ouvrir le dossier contenant settings.json",
+            "success": "Dossier settings.json ouvert",
+            "failed": "Impossible d'ouvrir le dossier settings.json"
+        },
         "sections": {
             "contentFiltering": "Filtrage du contenu",
             "videoSettings": "Paramètres vidéo",
@@ -178,7 +201,10 @@
             "folderSettings": "Paramètres des dossiers",
             "downloadPathTemplates": "Modèles de chemin de téléchargement",
             "exampleImages": "Images d'exemple",
-            "misc": "Divers"
+            "misc": "Divers",
+            "metadataArchive": "Base de données d'archive des métadonnées",
+            "proxySettings": "Paramètres du proxy",
+            "priorityTags": "Étiquettes prioritaires"
         },
         "contentFiltering": {
             "blurNsfwContent": "Flouter le contenu NSFW",
@@ -194,14 +220,14 @@
             "displayDensity": "Densité d'affichage",
             "displayDensityOptions": {
                 "default": "Par défaut",
-                "medium": "Moyen", 
+                "medium": "Moyen",
                 "compact": "Compact"
             },
             "displayDensityHelp": "Choisissez combien de cartes afficher par ligne :",
             "displayDensityDetails": {
-                "default": "Par défaut : 5 (1080p), 6 (2K), 8 (4K)",
-                "medium": "Moyen : 6 (1080p), 7 (2K), 9 (4K)",
-                "compact": "Compact : 7 (1080p), 8 (2K), 10 (4K)"
+                "default": "5 (1080p), 6 (2K), 8 (4K)",
+                "medium": "6 (1080p), 7 (2K), 9 (4K)",
+                "compact": "7 (1080p), 8 (2K), 10 (4K)"
             },
             "displayDensityWarning": "Attention : Des densités plus élevées peuvent causer des problèmes de performance sur les systèmes avec des ressources limitées.",
             "cardInfoDisplay": "Affichage des informations de carte",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "Choisissez quand afficher les informations du modèle et les boutons d'action :",
             "cardInfoDisplayDetails": {
-                "always": "Toujours visible : Les en-têtes et pieds de page sont toujours visibles",
-                "hover": "Révéler au survol : Les en-têtes et pieds de page n'apparaissent qu'au survol d'une carte"
+                "always": "Les en-têtes et pieds de page sont toujours visibles",
+                "hover": "Les en-têtes et pieds de page n'apparaissent qu'au survol d'une carte"
+            },
+            "modelNameDisplay": "Affichage du nom du modèle",
+            "modelNameDisplayOptions": {
+                "modelName": "Nom du modèle",
+                "fileName": "Nom du fichier"
+            },
+            "modelNameDisplayHelp": "Choisissez ce qui doit être affiché dans le pied de page de la carte du modèle :",
+            "modelNameDisplayDetails": {
+                "modelName": "Afficher le nom descriptif du modèle",
+                "fileName": "Afficher le nom réel du fichier sur le disque"
             }
         },
         "folderSettings": {
+            "activeLibrary": "Bibliothèque active",
+            "activeLibraryHelp": "Basculer entre les bibliothèques configurées pour mettre à jour les dossiers par défaut. Changer la sélection recharge la page.",
+            "loadingLibraries": "Chargement des bibliothèques...",
+            "noLibraries": "Aucune bibliothèque configurée",
             "defaultLoraRoot": "Racine LoRA par défaut",
             "defaultLoraRootHelp": "Définir le répertoire racine LoRA par défaut pour les téléchargements, imports et déplacements",
             "defaultCheckpointRoot": "Racine Checkpoint par défaut",
@@ -231,17 +271,18 @@
             "templateOptions": {
                 "flatStructure": "Structure plate",
                 "byBaseModel": "Par modèle de base",
-                "byAuthor": "Par auteur", 
+                "byAuthor": "Par auteur",
                 "byFirstTag": "Par premier tag",
                 "baseModelFirstTag": "Modèle de base + Premier tag",
                 "baseModelAuthor": "Modèle de base + Auteur",
                 "authorFirstTag": "Auteur + Premier tag",
+                "baseModelAuthorFirstTag": "Modèle de base + Auteur + Premier tag",
                 "customTemplate": "Modèle personnalisé"
             },
             "customTemplatePlaceholder": "Entrez un modèle personnalisé (ex: {base_model}/{author}/{first_tag})",
             "modelTypes": {
                 "lora": "LoRA",
-                "checkpoint": "Checkpoint", 
+                "checkpoint": "Checkpoint",
                 "embedding": "Embedding"
             },
             "baseModelPathMappings": "Mappages de chemin de modèle de base",
@@ -273,6 +314,68 @@
         "misc": {
             "includeTriggerWords": "Inclure les mots-clés dans la syntaxe LoRA",
             "includeTriggerWordsHelp": "Inclure les mots-clés d'entraînement lors de la copie de la syntaxe LoRA dans le presse-papiers"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "Activer la base de données d'archive des métadonnées",
+            "enableArchiveDbHelp": "Utiliser une base de données locale pour accéder aux métadonnées des modèles supprimés de Civitai.",
+            "status": "Statut",
+            "statusAvailable": "Disponible",
+            "statusUnavailable": "Non disponible",
+            "enabled": "Activé",
+            "management": "Gestion de la base de données",
+            "managementHelp": "Télécharger ou supprimer la base de données d'archive des métadonnées",
+            "downloadButton": "Télécharger la base de données",
+            "downloadingButton": "Téléchargement...",
+            "downloadedButton": "Téléchargé",
+            "removeButton": "Supprimer la base de données",
+            "removingButton": "Suppression...",
+            "downloadSuccess": "Base de données d'archive des métadonnées téléchargée avec succès",
+            "downloadError": "Échec du téléchargement de la base de données d'archive des métadonnées",
+            "removeSuccess": "Base de données d'archive des métadonnées supprimée avec succès",
+            "removeError": "Échec de la suppression de la base de données d'archive des métadonnées",
+            "removeConfirm": "Êtes-vous sûr de vouloir supprimer la base de données d'archive des métadonnées ? Cela supprimera le fichier local et vous devrez la télécharger à nouveau pour utiliser cette fonctionnalité.",
+            "preparing": "Préparation du téléchargement...",
+            "connecting": "Connexion au serveur de téléchargement...",
+            "completed": "Terminé",
+            "downloadComplete": "Téléchargement terminé avec succès"
+        },
+        "proxySettings": {
+            "enableProxy": "Activer le proxy au niveau de l'application",
+            "enableProxyHelp": "Activer les paramètres de proxy personnalisés pour cette application, remplaçant les paramètres de proxy système",
+            "proxyType": "Type de proxy",
+            "proxyTypeHelp": "Sélectionnez le type de serveur proxy (HTTP, HTTPS, SOCKS4, SOCKS5)",
+            "proxyHost": "Hôte du proxy",
+            "proxyHostPlaceholder": "proxy.exemple.com",
+            "proxyHostHelp": "Le nom d'hôte ou l'adresse IP de votre serveur proxy",
+            "proxyPort": "Port du proxy",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "Le numéro de port de votre serveur proxy",
+            "proxyUsername": "Nom d'utilisateur (optionnel)",
+            "proxyUsernamePlaceholder": "nom_utilisateur",
+            "proxyUsernameHelp": "Nom d'utilisateur pour l'authentification proxy (si nécessaire)",
+            "proxyPassword": "Mot de passe (optionnel)",
+            "proxyPasswordPlaceholder": "mot_de_passe",
+            "proxyPasswordHelp": "Mot de passe pour l'authentification proxy (si nécessaire)"
+        },
+        "priorityTags": {
+            "title": "Étiquettes prioritaires",
+            "description": "Personnalisez l'ordre de priorité des étiquettes pour chaque type de modèle (par ex. : character, concept, style(toon|toon_style))",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "Ouvrir l'aide sur les étiquettes prioritaires",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "Checkpoint",
+                "embedding": "Embedding"
+            },
+            "saveSuccess": "Étiquettes prioritaires mises à jour.",
+            "saveError": "Échec de la mise à jour des étiquettes prioritaires.",
+            "loadingSuggestions": "Chargement des suggestions...",
+            "validation": {
+                "missingClosingParen": "L'entrée {index} n'a pas de parenthèse fermante.",
+                "missingCanonical": "L'entrée {index} doit inclure un nom d'étiquette canonique.",
+                "duplicateCanonical": "L'étiquette canonique \"{tag}\" apparaît plusieurs fois.",
+                "unknown": "Configuration d'étiquettes prioritaires invalide."
+            }
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "{count} sélectionné(s)",
             "selectedSuffix": "sélectionné(s)",
-            "viewSelected": "Cliquez pour voir les éléments sélectionnés",
-            "sendToWorkflow": "Envoyer vers le workflow",
-            "copyAll": "Tout copier",
-            "refreshAll": "Tout actualiser",
-            "moveAll": "Tout déplacer",
-            "deleteAll": "Tout supprimer",
-            "clear": "Effacer"
+            "viewSelected": "Voir la sélection",
+            "addTags": "Ajouter des tags à tous",
+            "setBaseModel": "Définir le modèle de base pour tous",
+            "setContentRating": "Définir la classification du contenu pour tous",
+            "copyAll": "Copier toute la syntaxe",
+            "refreshAll": "Actualiser toutes les métadonnées",
+            "moveAll": "Déplacer tout vers un dossier",
+            "autoOrganize": "Auto-organiser la sélection",
+            "deleteAll": "Supprimer tous les modèles",
+            "clear": "Effacer la sélection",
+            "autoOrganizeProgress": {
+                "initializing": "Initialisation de l'auto-organisation...",
+                "starting": "Démarrage de l'auto-organisation pour {type}...",
+                "processing": "Traitement ({processed}/{total}) - {success} déplacés, {skipped} ignorés, {failures} échecs",
+                "cleaning": "Nettoyage des répertoires vides...",
+                "completed": "Terminé : {success} déplacés, {skipped} ignorés, {failures} échecs",
+                "complete": "Auto-organisation terminée",
+                "error": "Erreur : {error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "Actualiser les données Civitai",
@@ -445,13 +560,19 @@
         "title": "Modèles Embedding"
     },
     "sidebar": {
-        "modelRoot": "Racine du modèle",
+        "modelRoot": "Racine",
         "collapseAll": "Réduire tous les dossiers",
         "pinSidebar": "Épingler la barre latérale",
         "unpinSidebar": "Désépingler la barre latérale",
         "switchToListView": "Passer en vue liste",
         "switchToTreeView": "Passer en vue arborescence",
-        "collapseAllDisabled": "Non disponible en vue liste"
+        "recursiveOn": "Rechercher dans les sous-dossiers",
+        "recursiveOff": "Rechercher uniquement dans le dossier actuel",
+        "recursiveUnavailable": "La recherche récursive n'est disponible qu'en vue arborescente",
+        "collapseAllDisabled": "Non disponible en vue liste",
+        "dragDrop": {
+            "unableToResolveRoot": "Impossible de déterminer le chemin de destination pour le déplacement."
+        }
     },
     "statistics": {
         "title": "Statistiques",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "Image d'aperçu téléchargée",
                 "downloadingFile": "Téléchargement du fichier {type}",
                 "finalizing": "Finalisation du téléchargement..."
+            },
+            "progress": {
+                "currentFile": "Fichier actuel :",
+                "downloading": "Téléchargement : {name}",
+                "transferred": "Téléchargé : {downloaded} / {total}",
+                "transferredSimple": "Téléchargé : {downloaded}",
+                "transferredUnknown": "Téléchargé : --",
+                "speed": "Vitesse : {speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "Définir la classification du contenu",
             "current": "Actuel",
+            "multiple": "Valeurs multiples",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "modèles seront définitivement supprimés.",
             "action": "Tout supprimer"
         },
+        "bulkAddTags": {
+            "title": "Ajouter des tags à plusieurs modèles",
+            "description": "Ajouter des tags à",
+            "models": "modèles",
+            "tagsToAdd": "Tags à ajouter",
+            "placeholder": "Entrez un tag et appuyez sur Entrée...",
+            "appendTags": "Ajouter les tags",
+            "replaceTags": "Remplacer les tags",
+            "saveChanges": "Enregistrer les modifications"
+        },
+        "bulkBaseModel": {
+            "title": "Définir le modèle de base pour plusieurs modèles",
+            "description": "Définir le modèle de base pour",
+            "models": "modèles",
+            "selectBaseModel": "Sélectionner le modèle de base",
+            "save": "Mettre à jour le modèle de base",
+            "cancel": "Annuler"
+        },
         "exampleAccess": {
             "title": "Images d'exemple locales",
             "message": "Aucune image d'exemple locale trouvée pour ce modèle. Options d'affichage :",
@@ -622,7 +770,12 @@
                 "editBaseModel": "Modifier le modèle de base",
                 "viewOnCivitai": "Voir sur Civitai",
                 "viewOnCivitaiText": "Voir sur Civitai",
-                "viewCreatorProfile": "Voir le profil du créateur"
+                "viewCreatorProfile": "Voir le profil du créateur",
+                "openFileLocation": "Ouvrir l'emplacement du fichier"
+            },
+            "openFileLocation": {
+                "success": "Emplacement du fichier ouvert avec succès",
+                "failed": "Échec de l'ouverture de l'emplacement du fichier"
             },
             "metadata": {
                 "version": "Version",
@@ -646,6 +799,7 @@
                 "strengthMin": "Force Min",
                 "strengthMax": "Force Max",
                 "strength": "Force",
+                "clipStrength": "Force Clip",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "Valeur",
                 "add": "Ajouter"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "{completed} sur {total} LoRAs téléchargés. {accessFailures} ont échoué en raison de restrictions d'accès. Vérifiez votre clé API dans les paramètres ou le statut d'accès anticipé.",
             "pleaseSelectVersion": "Veuillez sélectionner une version",
             "versionExists": "Cette version existe déjà dans votre bibliothèque",
-            "downloadCompleted": "Téléchargement terminé avec succès"
+            "downloadCompleted": "Téléchargement terminé avec succès",
+            "autoOrganizeSuccess": "Auto-organisation terminée avec succès pour {count} {type}",
+            "autoOrganizePartialSuccess": "Auto-organisation terminée avec {success} déplacés, {failures} échecs sur {total} modèles",
+            "autoOrganizeFailed": "Échec de l'auto-organisation : {error}",
+            "noModelsSelected": "Aucun modèle sélectionné"
         },
         "recipes": {
             "fetchFailed": "Échec de la récupération des recipes : {message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "Erreur : {error}",
             "deleteFailedGeneral": "Échec de la suppression des modèles",
             "selectedAdditional": "{count} {type}(s) supplémentaire(s) sélectionné(s)",
+            "marqueeSelectionComplete": "{count} {type}(s) sélectionné(s) avec la sélection par glisser-déposer",
             "refreshMetadataFailed": "Échec de l'actualisation des métadonnées",
             "nameCannotBeEmpty": "Le nom du modèle ne peut pas être vide",
             "nameUpdatedSuccessfully": "Nom du modèle mis à jour avec succès",
             "nameUpdateFailed": "Échec de la mise à jour du nom du modèle",
             "baseModelUpdated": "Modèle de base mis à jour avec succès",
             "baseModelUpdateFailed": "Échec de la mise à jour du modèle de base",
+            "baseModelNotSelected": "Veuillez sélectionner un modèle de base",
+            "bulkBaseModelUpdating": "Mise à jour du modèle de base pour {count} modèle(s)...",
+            "bulkBaseModelUpdateSuccess": "Modèle de base mis à jour avec succès pour {count} modèle(s)",
+            "bulkBaseModelUpdatePartial": "{success} modèle(s) mis à jour, {failed} modèle(s) en échec",
+            "bulkBaseModelUpdateFailed": "Échec de la mise à jour du modèle de base pour les modèles sélectionnés",
+            "bulkContentRatingUpdating": "Mise à jour de la classification du contenu pour {count} modèle(s)...",
+            "bulkContentRatingSet": "Classification du contenu définie sur {level} pour {count} modèle(s)",
+            "bulkContentRatingPartial": "Classification du contenu définie sur {level} pour {success} modèle(s), {failed} échec(s)",
+            "bulkContentRatingFailed": "Impossible de mettre à jour la classification du contenu pour les modèles sélectionnés",
             "invalidCharactersRemoved": "Caractères invalides supprimés du nom de fichier",
             "filenameCannotBeEmpty": "Le nom de fichier ne peut pas être vide",
             "renameFailed": "Échec du renommage du fichier : {message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "Ce groupe a déjà été vérifié",
             "verificationCompleteMismatch": "Vérification terminée. {count} fichier(s) ont des hash différents.",
             "verificationCompleteSuccess": "Vérification terminée. Tous les fichiers sont confirmés comme doublons.",
-            "verificationFailed": "Échec de la vérification des hash : {message}"
+            "verificationFailed": "Échec de la vérification des hash : {message}",
+            "noTagsToAdd": "Aucun tag à ajouter",
+            "tagsAddedSuccessfully": "{tagCount} tag(s) ajouté(s) avec succès à {count} {type}(s)",
+            "tagsReplacedSuccessfully": "Tags remplacés avec succès pour {count} {type}(s) avec {tagCount} tag(s)",
+            "tagsAddFailed": "Échec de l'ajout des tags à {count} modèle(s)",
+            "tagsReplaceFailed": "Échec du remplacement des tags pour {count} modèle(s)",
+            "bulkTagsAddFailed": "Échec de l'ajout des tags aux modèles",
+            "bulkTagsReplaceFailed": "Échec du remplacement des tags pour les modèles"
         },
         "search": {
             "atLeastOneOption": "Au moins une option de recherche doit être sélectionnée"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "Mode compact {state}",
             "settingSaveFailed": "Échec de la sauvegarde du paramètre : {message}",
             "displayDensitySet": "Densité d'affichage définie sur {density}",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "Échec du changement de langue : {message}",
             "cacheCleared": "Les fichiers de cache ont été vidés avec succès. Le cache sera reconstruit à la prochaine action.",
             "cacheClearFailed": "Échec du vidage du cache : {error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "Chemin des images d'exemple mis à jour avec succès",
+            "pathUpdateFailed": "Échec de la mise à jour du chemin des images d'exemple : {message}",
             "downloadInProgress": "Téléchargement déjà en cours",
             "enterLocationFirst": "Veuillez d'abord entrer un emplacement de téléchargement",
             "downloadStarted": "Téléchargement des images d'exemple démarré",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "Échec de la mise en pause du téléchargement : {error}",
             "downloadResumed": "Téléchargement repris",
             "resumeFailed": "Échec de la reprise du téléchargement : {error}",
+            "downloadStopped": "Téléchargement annulé",
+            "stopFailed": "Échec de l'annulation du téléchargement : {error}",
             "deleted": "Image d'exemple supprimée",
             "deleteFailed": "Échec de la suppression de l'image d'exemple",
             "setPreviewFailed": "Échec de la définition de l'image d'aperçu"
@@ -1123,6 +1303,12 @@
             "refreshNow": "Actualiser maintenant",
             "refreshingIn": "Actualisation dans",
             "seconds": "secondes"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/ja.json

@@ -16,7 +16,9 @@
             "loading": "読み込み中...",
             "unknown": "不明",
             "date": "日付",
-            "version": "バージョン"
+            "version": "バージョン",
+            "enabled": "有効",
+            "disabled": "無効"
         },
         "language": {
             "select": "言語",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0バイト",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "このモデルのCivitaiでのリモート例画像は利用できません"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "例画像をダウンロード",
+            "missingPath": "例画像をダウンロードする前にダウンロード場所を設定してください。",
+            "unavailable": "例画像のダウンロードはまだ利用できません。ページの読み込みが完了してから再度お試しください。"
+        },
+        "cleanupExampleImages": {
+            "label": "例画像フォルダをクリーンアップ",
+            "success": "{count} 個のフォルダを削除フォルダに移動しました",
+            "none": "クリーンアップが必要な例画像フォルダはありません",
+            "partial": "クリーンアップが完了しましたが、{failures} 個のフォルダはスキップされました",
+            "error": "例画像フォルダのクリーンアップに失敗しました：{message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA Manager",
         "navigation": {
@@ -171,6 +188,12 @@
         "civitaiApiKey": "Civitai APIキー",
         "civitaiApiKeyPlaceholder": "Civitai APIキーを入力してください",
         "civitaiApiKeyHelp": "Civitaiからモデルをダウンロードするときの認証に使用されます",
+        "openSettingsFileLocation": {
+            "label": "設定フォルダーを開く",
+            "tooltip": "settings.json を含むフォルダーを開きます",
+            "success": "settings.json フォルダーを開きました",
+            "failed": "settings.json フォルダーを開けませんでした"
+        },
         "sections": {
             "contentFiltering": "コンテンツフィルタリング",
             "videoSettings": "動画設定",
@@ -178,7 +201,10 @@
             "folderSettings": "フォルダ設定",
             "downloadPathTemplates": "ダウンロードパステンプレート",
             "exampleImages": "例画像",
-            "misc": "その他"
+            "misc": "その他",
+            "metadataArchive": "メタデータアーカイブデータベース",
+            "proxySettings": "プロキシ設定",
+            "priorityTags": "優先タグ"
         },
         "contentFiltering": {
             "blurNsfwContent": "NSFWコンテンツをぼかす",
@@ -199,9 +225,9 @@
             },
             "displayDensityHelp": "1行に表示するカード数を選択：",
             "displayDensityDetails": {
-                "default": "デフォルト：5（1080p）、6（2K）、8（4K）",
-                "medium": "中：6（1080p）、7（2K）、9（4K）",
-                "compact": "コンパクト：7（1080p）、8（2K）、10（4K）"
+                "default": "5（1080p）、6（2K）、8（4K）",
+                "medium": "6（1080p）、7（2K）、9（4K）",
+                "compact": "7（1080p）、8（2K）、10（4K）"
             },
             "displayDensityWarning": "警告：高密度設定は、リソースが限られたシステムでパフォーマンスの問題を引き起こす可能性があります。",
             "cardInfoDisplay": "カード情報表示",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "モデル情報とアクションボタンの表示タイミングを選択：",
             "cardInfoDisplayDetails": {
-                "always": "常に表示：ヘッダーとフッターが常に表示されます",
-                "hover": "ホバー時に表示：カードにホバーしたときのみヘッダーとフッターが表示されます"
+                "always": "ヘッダーとフッターが常に表示されます",
+                "hover": "カードにホバーしたときのみヘッダーとフッターが表示されます"
+            },
+            "modelNameDisplay": "モデル名表示",
+            "modelNameDisplayOptions": {
+                "modelName": "モデル名",
+                "fileName": "ファイル名"
+            },
+            "modelNameDisplayHelp": "モデルカードのフッターに表示する内容を選択：",
+            "modelNameDisplayDetails": {
+                "modelName": "モデルの説明的な名前を表示",
+                "fileName": "ディスク上の実際のファイル名を表示"
             }
         },
         "folderSettings": {
+            "activeLibrary": "アクティブライブラリ",
+            "activeLibraryHelp": "設定済みのライブラリを切り替えてデフォルトのフォルダを更新します。選択を変更するとページが再読み込みされます。",
+            "loadingLibraries": "ライブラリを読み込み中...",
+            "noLibraries": "ライブラリが設定されていません",
             "defaultLoraRoot": "デフォルトLoRAルート",
             "defaultLoraRootHelp": "ダウンロード、インポート、移動用のデフォルトLoRAルートディレクトリを設定",
             "defaultCheckpointRoot": "デフォルトCheckpointルート",
@@ -236,6 +276,7 @@
                 "baseModelFirstTag": "ベースモデル + 最初のタグ",
                 "baseModelAuthor": "ベースモデル + 作成者",
                 "authorFirstTag": "作成者 + 最初のタグ",
+                "baseModelAuthorFirstTag": "ベースモデル + 作成者 + 最初のタグ",
                 "customTemplate": "カスタムテンプレート"
             },
             "customTemplatePlaceholder": "カスタムテンプレートを入力（例：{base_model}/{author}/{first_tag}）",
@@ -273,6 +314,68 @@
         "misc": {
             "includeTriggerWords": "LoRA構文にトリガーワードを含める",
             "includeTriggerWordsHelp": "LoRA構文をクリップボードにコピーする際、学習済みトリガーワードを含めます"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "メタデータアーカイブデータベースを有効化",
+            "enableArchiveDbHelp": "Civitaiから削除されたモデルのメタデータにアクセスするためにローカルデータベースを使用します。",
+            "status": "ステータス",
+            "statusAvailable": "利用可能",
+            "statusUnavailable": "利用不可",
+            "enabled": "有効",
+            "management": "データベース管理",
+            "managementHelp": "メタデータアーカイブデータベースのダウンロードまたは削除",
+            "downloadButton": "データベースをダウンロード",
+            "downloadingButton": "ダウンロード中...",
+            "downloadedButton": "ダウンロード済み",
+            "removeButton": "データベースを削除",
+            "removingButton": "削除中...",
+            "downloadSuccess": "メタデータアーカイブデータベースのダウンロードが完了しました",
+            "downloadError": "メタデータアーカイブデータベースのダウンロードに失敗しました",
+            "removeSuccess": "メタデータアーカイブデータベースが削除されました",
+            "removeError": "メタデータアーカイブデータベースの削除に失敗しました",
+            "removeConfirm": "本当にメタデータアーカイブデータベースを削除しますか？ローカルのデータベースファイルが削除され、この機能を再度利用するには再ダウンロードが必要です。",
+            "preparing": "ダウンロードを準備中...",
+            "connecting": "ダウンロードサーバーに接続中...",
+            "completed": "完了",
+            "downloadComplete": "ダウンロードが正常に完了しました"
+        },
+        "proxySettings": {
+            "enableProxy": "アプリレベルのプロキシを有効化",
+            "enableProxyHelp": "このアプリケーション専用のカスタムプロキシ設定を有効にします（システムのプロキシ設定を上書きします）",
+            "proxyType": "プロキシタイプ",
+            "proxyTypeHelp": "プロキシサーバーの種類を選択（HTTP、HTTPS、SOCKS4、SOCKS5）",
+            "proxyHost": "プロキシホスト",
+            "proxyHostPlaceholder": "proxy.example.com",
+            "proxyHostHelp": "プロキシサーバーのホスト名またはIPアドレス",
+            "proxyPort": "プロキシポート",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "プロキシサーバーのポート番号",
+            "proxyUsername": "ユーザー名（任意）",
+            "proxyUsernamePlaceholder": "ユーザー名",
+            "proxyUsernameHelp": "プロキシ認証用のユーザー名（必要な場合）",
+            "proxyPassword": "パスワード（任意）",
+            "proxyPasswordPlaceholder": "パスワード",
+            "proxyPasswordHelp": "プロキシ認証用のパスワード（必要な場合）"
+        },
+        "priorityTags": {
+            "title": "優先タグ",
+            "description": "各モデルタイプのタグ優先順位をカスタマイズします (例: character, concept, style(toon|toon_style))",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "優先タグのヘルプを開く",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "チェックポイント",
+                "embedding": "埋め込み"
+            },
+            "saveSuccess": "優先タグを更新しました。",
+            "saveError": "優先タグの更新に失敗しました。",
+            "loadingSuggestions": "候補を読み込み中...",
+            "validation": {
+                "missingClosingParen": "エントリ {index} に閉じ括弧がありません。",
+                "missingCanonical": "エントリ {index} には正規タグ名を含める必要があります。",
+                "duplicateCanonical": "正規タグ \"{tag}\" が複数回登場しています。",
+                "unknown": "無効な優先タグ設定です。"
+            }
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "{count} 選択中",
             "selectedSuffix": "選択中",
-            "viewSelected": "選択したアイテムを表示するにはクリック",
-            "sendToWorkflow": "ワークフローに送信",
-            "copyAll": "すべてコピー",
-            "refreshAll": "すべて更新",
-            "moveAll": "すべて移動",
-            "deleteAll": "すべて削除",
-            "clear": "クリア"
+            "viewSelected": "選択中を表示",
+            "addTags": "すべてにタグを追加",
+            "setBaseModel": "すべてにベースモデルを設定",
+            "setContentRating": "すべてのモデルのコンテンツレーティングを設定",
+            "copyAll": "すべての構文をコピー",
+            "refreshAll": "すべてのメタデータを更新",
+            "moveAll": "すべてをフォルダに移動",
+            "autoOrganize": "自動整理を実行",
+            "deleteAll": "すべてのモデルを削除",
+            "clear": "選択をクリア",
+            "autoOrganizeProgress": {
+                "initializing": "自動整理を初期化中...",
+                "starting": "{type}の自動整理を開始中...",
+                "processing": "処理中（{processed}/{total}）- {success} 移動、{skipped} スキップ、{failures} 失敗",
+                "cleaning": "空のディレクトリをクリーンアップ中...",
+                "completed": "完了：{success} 移動、{skipped} スキップ、{failures} 失敗",
+                "complete": "自動整理が完了しました",
+                "error": "エラー：{error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "Civitaiデータを更新",
@@ -445,13 +560,19 @@
         "title": "Embeddingモデル"
     },
     "sidebar": {
-        "modelRoot": "モデルルート",
+        "modelRoot": "ルート",
         "collapseAll": "すべてのフォルダを折りたたむ",
         "pinSidebar": "サイドバーを固定",
         "unpinSidebar": "サイドバーの固定を解除",
         "switchToListView": "リストビューに切り替え",
-        "switchToTreeView": "ツリービューに切り替え",
-        "collapseAllDisabled": "リストビューでは利用できません"
+        "switchToTreeView": "ツリー表示に切り替え",
+        "recursiveOn": "サブフォルダーを検索",
+        "recursiveOff": "現在のフォルダーのみを検索",
+        "recursiveUnavailable": "再帰検索はツリービューでのみ利用できます",
+        "collapseAllDisabled": "リストビューでは利用できません",
+        "dragDrop": {
+            "unableToResolveRoot": "移動先のパスを特定できません。"
+        }
     },
     "statistics": {
         "title": "統計",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "プレビュー画像をダウンロードしました",
                 "downloadingFile": "{type}ファイルをダウンロード中",
                 "finalizing": "ダウンロードを完了中..."
+            },
+            "progress": {
+                "currentFile": "現在のファイル:",
+                "downloading": "ダウンロード中: {name}",
+                "transferred": "ダウンロード済み: {downloaded} / {total}",
+                "transferredSimple": "ダウンロード済み: {downloaded}",
+                "transferredUnknown": "ダウンロード済み: --",
+                "speed": "速度: {speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "コンテンツレーティングを設定",
             "current": "現在",
+            "multiple": "複数の値",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "モデルが完全に削除されます。",
             "action": "すべて削除"
         },
+        "bulkAddTags": {
+            "title": "複数モデルにタグを追加",
+            "description": "タグを追加するモデル：",
+            "models": "モデル",
+            "tagsToAdd": "追加するタグ",
+            "placeholder": "タグを入力してEnterを押してください...",
+            "appendTags": "タグを追加",
+            "replaceTags": "タグを置換",
+            "saveChanges": "変更を保存"
+        },
+        "bulkBaseModel": {
+            "title": "複数モデルのベースモデルを設定",
+            "description": "ベースモデルを設定するモデル：",
+            "models": "モデル",
+            "selectBaseModel": "ベースモデルを選択",
+            "save": "ベースモデルを更新",
+            "cancel": "キャンセル"
+        },
         "exampleAccess": {
             "title": "ローカル例画像",
             "message": "このモデルのローカル例画像が見つかりませんでした。表示オプション：",
@@ -622,7 +770,12 @@
                 "editBaseModel": "ベースモデルを編集",
                 "viewOnCivitai": "Civitaiで表示",
                 "viewOnCivitaiText": "Civitaiで表示",
-                "viewCreatorProfile": "作成者プロフィールを表示"
+                "viewCreatorProfile": "作成者プロフィールを表示",
+                "openFileLocation": "ファイルの場所を開く"
+            },
+            "openFileLocation": {
+                "success": "ファイルの場所を正常に開きました",
+                "failed": "ファイルの場所を開くのに失敗しました"
             },
             "metadata": {
                 "version": "バージョン",
@@ -646,6 +799,7 @@
                 "strengthMin": "強度最小",
                 "strengthMax": "強度最大",
                 "strength": "強度",
+                "clipStrength": "クリップ強度",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "値",
                 "add": "追加"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "{total} LoRAのうち {completed} がダウンロードされました。{accessFailures} はアクセス制限により失敗しました。設定でAPIキーまたはアーリーアクセス状況を確認してください。",
             "pleaseSelectVersion": "バージョンを選択してください",
             "versionExists": "このバージョンは既にライブラリに存在します",
-            "downloadCompleted": "ダウンロードが正常に完了しました"
+            "downloadCompleted": "ダウンロードが正常に完了しました",
+            "autoOrganizeSuccess": "{count} {type} の自動整理が正常に完了しました",
+            "autoOrganizePartialSuccess": "自動整理が完了しました：{total} モデル中 {success} 移動、{failures} 失敗",
+            "autoOrganizeFailed": "自動整理に失敗しました：{error}",
+            "noModelsSelected": "モデルが選択されていません"
         },
         "recipes": {
             "fetchFailed": "レシピの取得に失敗しました：{message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "エラー：{error}",
             "deleteFailedGeneral": "モデルの削除に失敗しました",
             "selectedAdditional": "{count} 追加{type}が選択されました",
+            "marqueeSelectionComplete": "マーキー選択で {count} の{type}が選択されました",
             "refreshMetadataFailed": "メタデータの更新に失敗しました",
             "nameCannotBeEmpty": "モデル名を空にすることはできません",
             "nameUpdatedSuccessfully": "モデル名が正常に更新されました",
             "nameUpdateFailed": "モデル名の更新に失敗しました",
             "baseModelUpdated": "ベースモデルが正常に更新されました",
             "baseModelUpdateFailed": "ベースモデルの更新に失敗しました",
+            "baseModelNotSelected": "ベースモデルを選択してください",
+            "bulkBaseModelUpdating": "{count} モデルのベースモデルを更新中...",
+            "bulkBaseModelUpdateSuccess": "{count} モデルのベースモデルが正常に更新されました",
+            "bulkBaseModelUpdatePartial": "{success} モデルを更新、{failed} モデルは失敗しました",
+            "bulkBaseModelUpdateFailed": "選択したモデルのベースモデルの更新に失敗しました",
+            "bulkContentRatingUpdating": "{count} 件のモデルのコンテンツレーティングを更新中...",
+            "bulkContentRatingSet": "{count} 件のモデルのコンテンツレーティングを {level} に設定しました",
+            "bulkContentRatingPartial": "{success} 件のモデルのコンテンツレーティングを {level} に設定、{failed} 件は失敗しました",
+            "bulkContentRatingFailed": "選択したモデルのコンテンツレーティングを更新できませんでした",
             "invalidCharactersRemoved": "ファイル名から無効な文字が削除されました",
             "filenameCannotBeEmpty": "ファイル名を空にすることはできません",
             "renameFailed": "ファイル名の変更に失敗しました：{message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "このグループは既に検証済みです",
             "verificationCompleteMismatch": "検証完了。{count} ファイルの実際のハッシュが異なります。",
             "verificationCompleteSuccess": "検証完了。すべてのファイルが重複であることが確認されました。",
-            "verificationFailed": "ハッシュの検証に失敗しました：{message}"
+            "verificationFailed": "ハッシュの検証に失敗しました：{message}",
+            "noTagsToAdd": "追加するタグがありません",
+            "tagsAddedSuccessfully": "{count} {type} に {tagCount} 個のタグを追加しました",
+            "tagsReplacedSuccessfully": "{count} {type} のタグを {tagCount} 個に置換しました",
+            "tagsAddFailed": "{count} モデルへのタグ追加に失敗しました",
+            "tagsReplaceFailed": "{count} モデルのタグ置換に失敗しました",
+            "bulkTagsAddFailed": "モデルへのタグ追加に失敗しました",
+            "bulkTagsReplaceFailed": "モデルのタグ置換に失敗しました"
         },
         "search": {
             "atLeastOneOption": "少なくとも1つの検索オプションを選択する必要があります"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "コンパクトモード {state}",
             "settingSaveFailed": "設定の保存に失敗しました：{message}",
             "displayDensitySet": "表示密度が {density} に設定されました",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "言語の変更に失敗しました：{message}",
             "cacheCleared": "キャッシュファイルが正常にクリアされました。次回のアクションでキャッシュが再構築されます。",
             "cacheClearFailed": "キャッシュのクリアに失敗しました：{error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "例画像パスが正常に更新されました",
+            "pathUpdateFailed": "例画像パスの更新に失敗しました：{message}",
             "downloadInProgress": "ダウンロードは既に進行中です",
             "enterLocationFirst": "最初にダウンロード場所を入力してください",
             "downloadStarted": "例画像のダウンロードが開始されました",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "ダウンロードの一時停止に失敗しました：{error}",
             "downloadResumed": "ダウンロードが再開されました",
             "resumeFailed": "ダウンロードの再開に失敗しました：{error}",
+            "downloadStopped": "ダウンロードをキャンセルしました",
+            "stopFailed": "ダウンロードのキャンセルに失敗しました：{error}",
             "deleted": "例画像が削除されました",
             "deleteFailed": "例画像の削除に失敗しました",
             "setPreviewFailed": "プレビュー画像の設定に失敗しました"
@@ -1123,6 +1303,12 @@
             "refreshNow": "今すぐ更新",
             "refreshingIn": "更新まで",
             "seconds": "秒"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/ko.json

@@ -16,7 +16,9 @@
             "loading": "로딩 중...",
             "unknown": "알 수 없음",
             "date": "날짜",
-            "version": "버전"
+            "version": "버전",
+            "enabled": "활성화됨",
+            "disabled": "비활성화됨"
         },
         "language": {
             "select": "언어",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 바이트",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "Civitai에서 이 모델의 원격 예시 이미지를 사용할 수 없습니다"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "예시 이미지 다운로드",
+            "missingPath": "예시 이미지를 다운로드하기 전에 다운로드 위치를 설정하세요.",
+            "unavailable": "예시 이미지 다운로드는 아직 사용할 수 없습니다. 페이지 로딩이 완료된 후 다시 시도하세요."
+        },
+        "cleanupExampleImages": {
+            "label": "예시 이미지 폴더 정리",
+            "success": "{count}개의 폴더가 삭제 폴더로 이동되었습니다",
+            "none": "정리가 필요한 예시 이미지 폴더가 없습니다",
+            "partial": "정리가 완료되었으나 {failures}개의 폴더가 건너뛰어졌습니다",
+            "error": "예시 이미지 폴더 정리에 실패했습니다: {message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA Manager",
         "navigation": {
@@ -171,6 +188,12 @@
         "civitaiApiKey": "Civitai API 키",
         "civitaiApiKeyPlaceholder": "Civitai API 키를 입력하세요",
         "civitaiApiKeyHelp": "Civitai에서 모델을 다운로드할 때 인증에 사용됩니다",
+        "openSettingsFileLocation": {
+            "label": "설정 폴더 열기",
+            "tooltip": "settings.json이 있는 폴더를 엽니다",
+            "success": "settings.json 폴더를 열었습니다",
+            "failed": "settings.json 폴더를 열지 못했습니다"
+        },
         "sections": {
             "contentFiltering": "콘텐츠 필터링",
             "videoSettings": "비디오 설정",
@@ -178,7 +201,10 @@
             "folderSettings": "폴더 설정",
             "downloadPathTemplates": "다운로드 경로 템플릿",
             "exampleImages": "예시 이미지",
-            "misc": "기타"
+            "misc": "기타",
+            "metadataArchive": "메타데이터 아카이브 데이터베이스",
+            "proxySettings": "프록시 설정",
+            "priorityTags": "우선순위 태그"
         },
         "contentFiltering": {
             "blurNsfwContent": "NSFW 콘텐츠 블러 처리",
@@ -194,14 +220,14 @@
             "displayDensity": "표시 밀도",
             "displayDensityOptions": {
                 "default": "기본",
-                "medium": "중간", 
+                "medium": "중간",
                 "compact": "조밀"
             },
             "displayDensityHelp": "한 줄에 표시할 카드 수를 선택하세요:",
             "displayDensityDetails": {
-                "default": "기본: 5개 (1080p), 6개 (2K), 8개 (4K)",
-                "medium": "중간: 6개 (1080p), 7개 (2K), 9개 (4K)",
-                "compact": "조밀: 7개 (1080p), 8개 (2K), 10개 (4K)"
+                "default": "5개 (1080p), 6개 (2K), 8개 (4K)",
+                "medium": "6개 (1080p), 7개 (2K), 9개 (4K)",
+                "compact": "7개 (1080p), 8개 (2K), 10개 (4K)"
             },
             "displayDensityWarning": "경고: 높은 밀도는 리소스가 제한된 시스템에서 성능 문제를 일으킬 수 있습니다.",
             "cardInfoDisplay": "카드 정보 표시",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "모델 정보 및 액션 버튼을 언제 표시할지 선택하세요:",
             "cardInfoDisplayDetails": {
-                "always": "항상 표시: 헤더와 푸터가 항상 보입니다",
-                "hover": "호버 시 표시: 카드에 마우스를 올렸을 때만 헤더와 푸터가 나타납니다"
+                "always": "헤더와 푸터가 항상 보입니다",
+                "hover": "카드에 마우스를 올렸을 때만 헤더와 푸터가 나타납니다"
+            },
+            "modelNameDisplay": "모델명 표시",
+            "modelNameDisplayOptions": {
+                "modelName": "모델명",
+                "fileName": "파일명"
+            },
+            "modelNameDisplayHelp": "모델 카드 하단에 표시할 내용을 선택하세요:",
+            "modelNameDisplayDetails": {
+                "modelName": "모델의 설명적 이름 표시",
+                "fileName": "디스크의 실제 파일명 표시"
             }
         },
         "folderSettings": {
+            "activeLibrary": "활성 라이브러리",
+            "activeLibraryHelp": "구성된 라이브러리를 전환하여 기본 폴더를 업데이트합니다. 선택을 변경하면 페이지가 다시 로드됩니다.",
+            "loadingLibraries": "라이브러리를 불러오는 중...",
+            "noLibraries": "구성된 라이브러리가 없습니다",
             "defaultLoraRoot": "기본 LoRA 루트",
             "defaultLoraRootHelp": "다운로드, 가져오기 및 이동을 위한 기본 LoRA 루트 디렉토리를 설정합니다",
             "defaultCheckpointRoot": "기본 Checkpoint 루트",
@@ -231,17 +271,18 @@
             "templateOptions": {
                 "flatStructure": "플랫 구조",
                 "byBaseModel": "베이스 모델별",
-                "byAuthor": "제작자별", 
+                "byAuthor": "제작자별",
                 "byFirstTag": "첫 번째 태그별",
                 "baseModelFirstTag": "베이스 모델 + 첫 번째 태그",
                 "baseModelAuthor": "베이스 모델 + 제작자",
                 "authorFirstTag": "제작자 + 첫 번째 태그",
+                "baseModelAuthorFirstTag": "베이스 모델 + 제작자 + 첫 번째 태그",
                 "customTemplate": "사용자 정의 템플릿"
             },
             "customTemplatePlaceholder": "사용자 정의 템플릿 입력 (예: {base_model}/{author}/{first_tag})",
             "modelTypes": {
                 "lora": "LoRA",
-                "checkpoint": "Checkpoint", 
+                "checkpoint": "Checkpoint",
                 "embedding": "Embedding"
             },
             "baseModelPathMappings": "베이스 모델 경로 매핑",
@@ -273,6 +314,68 @@
         "misc": {
             "includeTriggerWords": "LoRA 문법에 트리거 단어 포함",
             "includeTriggerWordsHelp": "LoRA 문법을 클립보드에 복사할 때 학습된 트리거 단어를 포함합니다"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "메타데이터 아카이브 데이터베이스 활성화",
+            "enableArchiveDbHelp": "Civitai에서 삭제된 모델의 메타데이터에 접근하기 위해 로컬 데이터베이스를 사용합니다.",
+            "status": "상태",
+            "statusAvailable": "사용 가능",
+            "statusUnavailable": "사용 불가",
+            "enabled": "활성화됨",
+            "management": "데이터베이스 관리",
+            "managementHelp": "메타데이터 아카이브 데이터베이스를 다운로드하거나 제거합니다",
+            "downloadButton": "데이터베이스 다운로드",
+            "downloadingButton": "다운로드 중...",
+            "downloadedButton": "다운로드 완료",
+            "removeButton": "데이터베이스 제거",
+            "removingButton": "제거 중...",
+            "downloadSuccess": "메타데이터 아카이브 데이터베이스가 성공적으로 다운로드되었습니다",
+            "downloadError": "메타데이터 아카이브 데이터베이스 다운로드 실패",
+            "removeSuccess": "메타데이터 아카이브 데이터베이스가 성공적으로 제거되었습니다",
+            "removeError": "메타데이터 아카이브 데이터베이스 제거 실패",
+            "removeConfirm": "메타데이터 아카이브 데이터베이스를 제거하시겠습니까? 이 작업은 로컬 데이터베이스 파일을 삭제하며, 이 기능을 사용하려면 다시 다운로드해야 합니다.",
+            "preparing": "다운로드 준비 중...",
+            "connecting": "다운로드 서버에 연결 중...",
+            "completed": "완료됨",
+            "downloadComplete": "다운로드가 성공적으로 완료되었습니다"
+        },
+        "proxySettings": {
+            "enableProxy": "앱 수준 프록시 활성화",
+            "enableProxyHelp": "이 애플리케이션에 대한 사용자 지정 프록시 설정을 활성화하여 시스템 프록시 설정을 무시합니다",
+            "proxyType": "프록시 유형",
+            "proxyTypeHelp": "프록시 서버 유형을 선택하세요 (HTTP, HTTPS, SOCKS4, SOCKS5)",
+            "proxyHost": "프록시 호스트",
+            "proxyHostPlaceholder": "proxy.example.com",
+            "proxyHostHelp": "프록시 서버의 호스트명 또는 IP 주소",
+            "proxyPort": "프록시 포트",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "프록시 서버의 포트 번호",
+            "proxyUsername": "사용자 이름 (선택사항)",
+            "proxyUsernamePlaceholder": "username",
+            "proxyUsernameHelp": "프록시 인증에 필요한 사용자 이름 (필요한 경우)",
+            "proxyPassword": "비밀번호 (선택사항)",
+            "proxyPasswordPlaceholder": "password",
+            "proxyPasswordHelp": "프록시 인증에 필요한 비밀번호 (필요한 경우)"
+        },
+        "priorityTags": {
+            "title": "우선순위 태그",
+            "description": "모델 유형별 태그 우선순위를 사용자 지정합니다(예: character, concept, style(toon|toon_style)).",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "우선순위 태그 도움말 열기",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "체크포인트",
+                "embedding": "임베딩"
+            },
+            "saveSuccess": "우선순위 태그가 업데이트되었습니다.",
+            "saveError": "우선순위 태그를 업데이트하지 못했습니다.",
+            "loadingSuggestions": "추천을 불러오는 중...",
+            "validation": {
+                "missingClosingParen": "{index}번째 항목에 닫는 괄호가 없습니다.",
+                "missingCanonical": "{index}번째 항목에는 정식 태그 이름이 포함되어야 합니다.",
+                "duplicateCanonical": "정식 태그 \"{tag}\"가 여러 번 나타납니다.",
+                "unknown": "잘못된 우선순위 태그 구성입니다."
+            }
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "{count}개 선택됨",
             "selectedSuffix": "개 선택됨",
-            "viewSelected": "선택된 항목 보기",
-            "sendToWorkflow": "워크플로로 전송",
-            "copyAll": "모두 복사",
-            "refreshAll": "모두 새로고침",
-            "moveAll": "모두 이동",
-            "deleteAll": "모두 삭제",
-            "clear": "지우기"
+            "viewSelected": "선택 항목 보기",
+            "addTags": "모두에 태그 추가",
+            "setBaseModel": "모두에 베이스 모델 설정",
+            "setContentRating": "모든 모델에 콘텐츠 등급 설정",
+            "copyAll": "모든 문법 복사",
+            "refreshAll": "모든 메타데이터 새로고침",
+            "moveAll": "모두 폴더로 이동",
+            "autoOrganize": "자동 정리 선택",
+            "deleteAll": "모든 모델 삭제",
+            "clear": "선택 지우기",
+            "autoOrganizeProgress": {
+                "initializing": "자동 정리 초기화 중...",
+                "starting": "{type}에 대한 자동 정리 시작...",
+                "processing": "처리 중 ({processed}/{total}) - {success}개 이동, {skipped}개 건너뜀, {failures}개 실패",
+                "cleaning": "빈 디렉토리 정리 중...",
+                "completed": "완료: {success}개 이동, {skipped}개 건너뜀, {failures}개 실패",
+                "complete": "자동 정리 완료",
+                "error": "오류: {error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "Civitai 데이터 새로고침",
@@ -445,13 +560,19 @@
         "title": "Embedding 모델"
     },
     "sidebar": {
-        "modelRoot": "모델 루트",
+        "modelRoot": "루트",
         "collapseAll": "모든 폴더 접기",
         "pinSidebar": "사이드바 고정",
         "unpinSidebar": "사이드바 고정 해제",
         "switchToListView": "목록 보기로 전환",
         "switchToTreeView": "트리 보기로 전환",
-        "collapseAllDisabled": "목록 보기에서는 사용할 수 없습니다"
+        "recursiveOn": "하위 폴더 검색",
+        "recursiveOff": "현재 폴더만 검색",
+        "recursiveUnavailable": "재귀 검색은 트리 보기에서만 사용할 수 있습니다",
+        "collapseAllDisabled": "목록 보기에서는 사용할 수 없습니다",
+        "dragDrop": {
+            "unableToResolveRoot": "이동할 대상 경로를 확인할 수 없습니다."
+        }
     },
     "statistics": {
         "title": "통계",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "미리보기 이미지 다운로드됨",
                 "downloadingFile": "{type} 파일 다운로드 중",
                 "finalizing": "다운로드 완료 중..."
+            },
+            "progress": {
+                "currentFile": "현재 파일:",
+                "downloading": "다운로드 중: {name}",
+                "transferred": "다운로드됨: {downloaded} / {total}",
+                "transferredSimple": "다운로드됨: {downloaded}",
+                "transferredUnknown": "다운로드됨: --",
+                "speed": "속도: {speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "콘텐츠 등급 설정",
             "current": "현재",
+            "multiple": "여러 값",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "개의 모델이 영구적으로 삭제됩니다.",
             "action": "모두 삭제"
         },
+        "bulkAddTags": {
+            "title": "여러 모델에 태그 추가",
+            "description": "다음에 태그를 추가합니다:",
+            "models": "모델",
+            "tagsToAdd": "추가할 태그",
+            "placeholder": "태그를 입력하고 Enter를 누르세요...",
+            "appendTags": "태그 추가",
+            "replaceTags": "태그 교체",
+            "saveChanges": "변경사항 저장"
+        },
+        "bulkBaseModel": {
+            "title": "여러 모델의 베이스 모델 설정",
+            "description": "다음 모델의 베이스 모델을 설정합니다:",
+            "models": "모델",
+            "selectBaseModel": "베이스 모델 선택",
+            "save": "베이스 모델 업데이트",
+            "cancel": "취소"
+        },
         "exampleAccess": {
             "title": "로컬 예시 이미지",
             "message": "이 모델의 로컬 예시 이미지를 찾을 수 없습니다. 보기 옵션:",
@@ -622,7 +770,12 @@
                 "editBaseModel": "베이스 모델 편집",
                 "viewOnCivitai": "Civitai에서 보기",
                 "viewOnCivitaiText": "Civitai에서 보기",
-                "viewCreatorProfile": "제작자 프로필 보기"
+                "viewCreatorProfile": "제작자 프로필 보기",
+                "openFileLocation": "파일 위치 열기"
+            },
+            "openFileLocation": {
+                "success": "파일 위치가 성공적으로 열렸습니다",
+                "failed": "파일 위치 열기에 실패했습니다"
             },
             "metadata": {
                 "version": "버전",
@@ -646,6 +799,7 @@
                 "strengthMin": "최소 강도",
                 "strengthMax": "최대 강도",
                 "strength": "강도",
+                "clipStrength": "클립 강도",
                 "clipSkip": "클립 스킵",
                 "valuePlaceholder": "값",
                 "add": "추가"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "{total}개 중 {completed}개 LoRA가 다운로드되었습니다. {accessFailures}개는 액세스 제한으로 실패했습니다. 설정에서 API 키 또는 얼리 액세스 상태를 확인하세요.",
             "pleaseSelectVersion": "버전을 선택해주세요",
             "versionExists": "이 버전은 이미 라이브러리에 있습니다",
-            "downloadCompleted": "다운로드가 성공적으로 완료되었습니다"
+            "downloadCompleted": "다운로드가 성공적으로 완료되었습니다",
+            "autoOrganizeSuccess": "{count}개의 {type}에 대해 자동 정리가 성공적으로 완료되었습니다",
+            "autoOrganizePartialSuccess": "자동 정리 완료: 전체 {total}개 중 {success}개 이동, {failures}개 실패",
+            "autoOrganizeFailed": "자동 정리 실패: {error}",
+            "noModelsSelected": "선택된 모델이 없습니다"
         },
         "recipes": {
             "fetchFailed": "레시피 가져오기 실패: {message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "오류: {error}",
             "deleteFailedGeneral": "모델 삭제에 실패했습니다",
             "selectedAdditional": "추가로 {count}개의 {type}이(가) 선택되었습니다",
+            "marqueeSelectionComplete": "마키 선택으로 {count}개의 {type}이(가) 선택되었습니다",
             "refreshMetadataFailed": "메타데이터 새로고침에 실패했습니다",
             "nameCannotBeEmpty": "모델 이름은 비어있을 수 없습니다",
             "nameUpdatedSuccessfully": "모델 이름이 성공적으로 업데이트되었습니다",
             "nameUpdateFailed": "모델 이름 업데이트에 실패했습니다",
             "baseModelUpdated": "베이스 모델이 성공적으로 업데이트되었습니다",
             "baseModelUpdateFailed": "베이스 모델 업데이트에 실패했습니다",
+            "baseModelNotSelected": "베이스 모델을 선택해주세요",
+            "bulkBaseModelUpdating": "{count}개의 모델에 베이스 모델을 업데이트 중...",
+            "bulkBaseModelUpdateSuccess": "{count}개의 모델에 베이스 모델이 성공적으로 업데이트되었습니다",
+            "bulkBaseModelUpdatePartial": "{success}개의 모델이 업데이트되었고, {failed}개의 모델이 실패했습니다",
+            "bulkBaseModelUpdateFailed": "선택한 모델의 베이스 모델 업데이트에 실패했습니다",
+            "bulkContentRatingUpdating": "{count}개 모델의 콘텐츠 등급을 업데이트하는 중...",
+            "bulkContentRatingSet": "{count}개 모델의 콘텐츠 등급을 {level}(으)로 설정했습니다",
+            "bulkContentRatingPartial": "{success}개 모델의 콘텐츠 등급을 {level}(으)로 설정했고, {failed}개는 실패했습니다",
+            "bulkContentRatingFailed": "선택한 모델의 콘텐츠 등급을 업데이트하지 못했습니다",
             "invalidCharactersRemoved": "파일명에서 잘못된 문자가 제거되었습니다",
             "filenameCannotBeEmpty": "파일 이름은 비어있을 수 없습니다",
             "renameFailed": "파일 이름 변경 실패: {message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "이 그룹은 이미 검증되었습니다",
             "verificationCompleteMismatch": "검증 완료. {count}개 파일의 실제 해시가 다릅니다.",
             "verificationCompleteSuccess": "검증 완료. 모든 파일이 중복임을 확인했습니다.",
-            "verificationFailed": "해시 검증 실패: {message}"
+            "verificationFailed": "해시 검증 실패: {message}",
+            "noTagsToAdd": "추가할 태그가 없습니다",
+            "tagsAddedSuccessfully": "{count}개의 {type}에 {tagCount}개의 태그가 성공적으로 추가되었습니다",
+            "tagsReplacedSuccessfully": "{count}개의 {type}의 태그가 {tagCount}개의 태그로 성공적으로 교체되었습니다",
+            "tagsAddFailed": "{count}개의 모델에 태그 추가에 실패했습니다",
+            "tagsReplaceFailed": "{count}개의 모델의 태그 교체에 실패했습니다",
+            "bulkTagsAddFailed": "모델에 태그 추가에 실패했습니다",
+            "bulkTagsReplaceFailed": "모델의 태그 교체에 실패했습니다"
         },
         "search": {
             "atLeastOneOption": "최소 하나의 검색 옵션을 선택해야 합니다"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "컴팩트 모드 {state}",
             "settingSaveFailed": "설정 저장 실패: {message}",
             "displayDensitySet": "표시 밀도가 {density}로 설정되었습니다",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "언어 변경 실패: {message}",
             "cacheCleared": "캐시 파일이 성공적으로 지워졌습니다. 다음 작업 시 캐시가 재구축됩니다.",
             "cacheClearFailed": "캐시 지우기 실패: {error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "예시 이미지 경로가 성공적으로 업데이트되었습니다",
+            "pathUpdateFailed": "예시 이미지 경로 업데이트 실패: {message}",
             "downloadInProgress": "이미 다운로드가 진행 중입니다",
             "enterLocationFirst": "먼저 다운로드 위치를 입력해주세요",
             "downloadStarted": "예시 이미지 다운로드가 시작되었습니다",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "다운로드 일시정지 실패: {error}",
             "downloadResumed": "다운로드가 재개되었습니다",
             "resumeFailed": "다운로드 재개 실패: {error}",
+            "downloadStopped": "다운로드가 취소되었습니다",
+            "stopFailed": "다운로드 취소 실패: {error}",
             "deleted": "예시 이미지가 삭제되었습니다",
             "deleteFailed": "예시 이미지 삭제 실패",
             "setPreviewFailed": "미리보기 이미지 설정 실패"
@@ -1123,6 +1303,12 @@
             "refreshNow": "지금 새로고침",
             "refreshingIn": "새로고침까지",
             "seconds": "초"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/ru.json

@@ -16,7 +16,9 @@
             "loading": "Загрузка...",
             "unknown": "Неизвестно",
             "date": "Дата",
-            "version": "Версия"
+            "version": "Версия",
+            "enabled": "Включено",
+            "disabled": "Отключено"
         },
         "language": {
             "select": "Язык",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 Байт",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "Нет удаленных примеров изображений для этой модели на Civitai"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "Загрузить примеры изображений",
+            "missingPath": "Укажите место загрузки перед загрузкой примеров изображений.",
+            "unavailable": "Загрузка примеров изображений пока недоступна. Попробуйте снова после полной загрузки страницы."
+        },
+        "cleanupExampleImages": {
+            "label": "Очистить папки с примерами изображений",
+            "success": "Перемещено {count} папок в папку удалённых",
+            "none": "Нет папок с примерами изображений, требующих очистки",
+            "partial": "Очистка завершена, пропущено {failures} папок",
+            "error": "Не удалось очистить папки с примерами изображений: {message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA Manager",
         "navigation": {
@@ -171,6 +188,12 @@
         "civitaiApiKey": "Ключ API Civitai",
         "civitaiApiKeyPlaceholder": "Введите ваш ключ API Civitai",
         "civitaiApiKeyHelp": "Используется для аутентификации при загрузке моделей с Civitai",
+        "openSettingsFileLocation": {
+            "label": "Открыть папку настроек",
+            "tooltip": "Открыть папку, содержащую settings.json",
+            "success": "Папка settings.json открыта",
+            "failed": "Не удалось открыть папку settings.json"
+        },
         "sections": {
             "contentFiltering": "Фильтрация контента",
             "videoSettings": "Настройки видео",
@@ -178,7 +201,10 @@
             "folderSettings": "Настройки папок",
             "downloadPathTemplates": "Шаблоны путей загрузки",
             "exampleImages": "Примеры изображений",
-            "misc": "Разное"
+            "misc": "Разное",
+            "metadataArchive": "Архив метаданных",
+            "proxySettings": "Настройки прокси",
+            "priorityTags": "Приоритетные теги"
         },
         "contentFiltering": {
             "blurNsfwContent": "Размывать NSFW контент",
@@ -194,14 +220,14 @@
             "displayDensity": "Плотность отображения",
             "displayDensityOptions": {
                 "default": "По умолчанию",
-                "medium": "Средняя", 
+                "medium": "Средняя",
                 "compact": "Компактная"
             },
             "displayDensityHelp": "Выберите количество карточек для отображения в ряду:",
             "displayDensityDetails": {
-                "default": "По умолчанию: 5 (1080p), 6 (2K), 8 (4K)",
-                "medium": "Средняя: 6 (1080p), 7 (2K), 9 (4K)",
-                "compact": "Компактная: 7 (1080p), 8 (2K), 10 (4K)"
+                "default": "5 (1080p), 6 (2K), 8 (4K)",
+                "medium": "6 (1080p), 7 (2K), 9 (4K)",
+                "compact": "7 (1080p), 8 (2K), 10 (4K)"
             },
             "displayDensityWarning": "Предупреждение: Высокая плотность может вызвать проблемы с производительностью на системах с ограниченными ресурсами.",
             "cardInfoDisplay": "Отображение информации карточки",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "Выберите когда отображать информацию о модели и кнопки действий:",
             "cardInfoDisplayDetails": {
-                "always": "Всегда видимо: Заголовки и подписи всегда видны",
-                "hover": "Показать при наведении: Заголовки и подписи появляются только при наведении на карточку"
+                "always": "Заголовки и подписи всегда видны",
+                "hover": "Заголовки и подписи появляются только при наведении на карточку"
+            },
+            "modelNameDisplay": "Отображение названия модели",
+            "modelNameDisplayOptions": {
+                "modelName": "Название модели",
+                "fileName": "Имя файла"
+            },
+            "modelNameDisplayHelp": "Выберите, что отображать в нижней части карточки модели:",
+            "modelNameDisplayDetails": {
+                "modelName": "Отображать описательное название модели",
+                "fileName": "Отображать фактическое имя файла на диске"
             }
         },
         "folderSettings": {
+            "activeLibrary": "Активная библиотека",
+            "activeLibraryHelp": "Переключайтесь между настроенными библиотеками, чтобы обновить папки по умолчанию. Изменение выбора перезагружает страницу.",
+            "loadingLibraries": "Загрузка библиотек...",
+            "noLibraries": "Библиотеки не настроены",
             "defaultLoraRoot": "Корневая папка LoRA по умолчанию",
             "defaultLoraRootHelp": "Установить корневую папку LoRA по умолчанию для загрузок, импорта и перемещений",
             "defaultCheckpointRoot": "Корневая папка Checkpoint по умолчанию",
@@ -231,17 +271,18 @@
             "templateOptions": {
                 "flatStructure": "Плоская структура",
                 "byBaseModel": "По базовой модели",
-                "byAuthor": "По автору", 
+                "byAuthor": "По автору",
                 "byFirstTag": "По первому тегу",
                 "baseModelFirstTag": "Базовая модель + Первый тег",
                 "baseModelAuthor": "Базовая модель + Автор",
                 "authorFirstTag": "Автор + Первый тег",
+                "baseModelAuthorFirstTag": "Базовая модель + Автор + Первый тег",
                 "customTemplate": "Пользовательский шаблон"
             },
             "customTemplatePlaceholder": "Введите пользовательский шаблон (например, {base_model}/{author}/{first_tag})",
             "modelTypes": {
                 "lora": "LoRA",
-                "checkpoint": "Checkpoint", 
+                "checkpoint": "Checkpoint",
                 "embedding": "Embedding"
             },
             "baseModelPathMappings": "Сопоставления путей базовых моделей",
@@ -273,6 +314,68 @@
         "misc": {
             "includeTriggerWords": "Включать триггерные слова в синтаксис LoRA",
             "includeTriggerWordsHelp": "Включать обученные триггерные слова при копировании синтаксиса LoRA в буфер обмена"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "Включить архив метаданных",
+            "enableArchiveDbHelp": "Использовать локальную базу данных для доступа к метаданным моделей, удалённых с Civitai.",
+            "status": "Статус",
+            "statusAvailable": "Доступно",
+            "statusUnavailable": "Недоступно",
+            "enabled": "Включено",
+            "management": "Управление базой данных",
+            "managementHelp": "Скачать или удалить базу данных архива метаданных",
+            "downloadButton": "Скачать базу данных",
+            "downloadingButton": "Скачивание...",
+            "downloadedButton": "Скачано",
+            "removeButton": "Удалить базу данных",
+            "removingButton": "Удаление...",
+            "downloadSuccess": "База данных архива метаданных успешно загружена",
+            "downloadError": "Не удалось загрузить базу данных архива метаданных",
+            "removeSuccess": "База данных архива метаданных успешно удалена",
+            "removeError": "Не удалось удалить базу данных архива метаданных",
+            "removeConfirm": "Вы уверены, что хотите удалить базу данных архива метаданных? Это удалит локальный файл базы данных, и для использования этой функции потребуется повторная загрузка.",
+            "preparing": "Подготовка к загрузке...",
+            "connecting": "Подключение к серверу загрузки...",
+            "completed": "Завершено",
+            "downloadComplete": "Загрузка успешно завершена"
+        },
+        "proxySettings": {
+            "enableProxy": "Включить прокси на уровне приложения",
+            "enableProxyHelp": "Включить пользовательские настройки прокси для этого приложения, переопределяя системные настройки прокси",
+            "proxyType": "Тип прокси",
+            "proxyTypeHelp": "Выберите тип прокси-сервера (HTTP, HTTPS, SOCKS4, SOCKS5)",
+            "proxyHost": "Хост прокси",
+            "proxyHostPlaceholder": "proxy.example.com",
+            "proxyHostHelp": "Имя хоста или IP-адрес вашего прокси-сервера",
+            "proxyPort": "Порт прокси",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "Номер порта вашего прокси-сервера",
+            "proxyUsername": "Имя пользователя (необязательно)",
+            "proxyUsernamePlaceholder": "имя пользователя",
+            "proxyUsernameHelp": "Имя пользователя для аутентификации на прокси (если требуется)",
+            "proxyPassword": "Пароль (необязательно)",
+            "proxyPasswordPlaceholder": "пароль",
+            "proxyPasswordHelp": "Пароль для аутентификации на прокси (если требуется)"
+        },
+        "priorityTags": {
+            "title": "Приоритетные теги",
+            "description": "Настройте порядок приоритетов тегов для каждого типа моделей (например, character, concept, style(toon|toon_style)).",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "Открыть справку по приоритетным тегам",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "Чекпойнт",
+                "embedding": "Эмбеддинг"
+            },
+            "saveSuccess": "Приоритетные теги обновлены.",
+            "saveError": "Не удалось обновить приоритетные теги.",
+            "loadingSuggestions": "Загрузка подсказок...",
+            "validation": {
+                "missingClosingParen": "В записи {index} отсутствует закрывающая скобка.",
+                "missingCanonical": "Запись {index} должна содержать каноническое имя тега.",
+                "duplicateCanonical": "Канонический тег \"{tag}\" встречается более одного раза.",
+                "unknown": "Недопустимая конфигурация приоритетных тегов."
+            }
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "Выбрано {count}",
             "selectedSuffix": "выбрано",
-            "viewSelected": "Нажмите для просмотра выбранных элементов",
-            "sendToWorkflow": "Отправить в Workflow",
-            "copyAll": "Копировать все",
-            "refreshAll": "Обновить все",
-            "moveAll": "Переместить все",
-            "deleteAll": "Удалить все",
-            "clear": "Очистить"
+            "viewSelected": "Просмотреть выбранные",
+            "addTags": "Добавить теги ко всем",
+            "setBaseModel": "Установить базовую модель для всех",
+            "setContentRating": "Установить рейтинг контента для всех",
+            "copyAll": "Копировать весь синтаксис",
+            "refreshAll": "Обновить все метаданные",
+            "moveAll": "Переместить все в папку",
+            "autoOrganize": "Автоматически организовать выбранные",
+            "deleteAll": "Удалить все модели",
+            "clear": "Очистить выбор",
+            "autoOrganizeProgress": {
+                "initializing": "Инициализация автоматической организации...",
+                "starting": "Запуск автоматической организации для {type}...",
+                "processing": "Обработка ({processed}/{total}) — {success} перемещено, {skipped} пропущено, {failures} не удалось",
+                "cleaning": "Очистка пустых директорий...",
+                "completed": "Завершено: {success} перемещено, {skipped} пропущено, {failures} не удалось",
+                "complete": "Автоматическая организация завершена",
+                "error": "Ошибка: {error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "Обновить данные Civitai",
@@ -445,13 +560,19 @@
         "title": "Модели Embedding"
     },
     "sidebar": {
-        "modelRoot": "Корень моделей",
+        "modelRoot": "Корень",
         "collapseAll": "Свернуть все папки",
         "pinSidebar": "Закрепить боковую панель",
         "unpinSidebar": "Открепить боковую панель",
         "switchToListView": "Переключить на вид списка",
         "switchToTreeView": "Переключить на древовидный вид",
-        "collapseAllDisabled": "Недоступно в виде списка"
+        "recursiveOn": "Искать во вложенных папках",
+        "recursiveOff": "Искать только в текущей папке",
+        "recursiveUnavailable": "Рекурсивный поиск доступен только в режиме дерева",
+        "collapseAllDisabled": "Недоступно в виде списка",
+        "dragDrop": {
+            "unableToResolveRoot": "Не удалось определить путь назначения для перемещения."
+        }
     },
     "statistics": {
         "title": "Статистика",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "Превью изображение загружено",
                 "downloadingFile": "Загрузка файла {type}",
                 "finalizing": "Завершение загрузки..."
+            },
+            "progress": {
+                "currentFile": "Текущий файл:",
+                "downloading": "Скачивается: {name}",
+                "transferred": "Скачано: {downloaded} / {total}",
+                "transferredSimple": "Скачано: {downloaded}",
+                "transferredUnknown": "Скачано: --",
+                "speed": "Скорость: {speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "Установить рейтинг контента",
             "current": "Текущий",
+            "multiple": "Несколько значений",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "моделей будут удалены навсегда.",
             "action": "Удалить все"
         },
+        "bulkAddTags": {
+            "title": "Добавить теги к нескольким моделям",
+            "description": "Добавить теги к",
+            "models": "моделям",
+            "tagsToAdd": "Теги для добавления",
+            "placeholder": "Введите тег и нажмите Enter...",
+            "appendTags": "Добавить теги",
+            "replaceTags": "Заменить теги",
+            "saveChanges": "Сохранить изменения"
+        },
+        "bulkBaseModel": {
+            "title": "Установить базовую модель для нескольких моделей",
+            "description": "Установить базовую модель для",
+            "models": "моделей",
+            "selectBaseModel": "Выбрать базовую модель",
+            "save": "Обновить базовую модель",
+            "cancel": "Отмена"
+        },
         "exampleAccess": {
             "title": "Локальные примеры изображений",
             "message": "Локальные примеры изображений для этой модели не найдены. Варианты просмотра:",
@@ -622,7 +770,12 @@
                 "editBaseModel": "Редактировать базовую модель",
                 "viewOnCivitai": "Посмотреть на Civitai",
                 "viewOnCivitaiText": "Посмотреть на Civitai",
-                "viewCreatorProfile": "Посмотреть профиль создателя"
+                "viewCreatorProfile": "Посмотреть профиль создателя",
+                "openFileLocation": "Открыть расположение файла"
+            },
+            "openFileLocation": {
+                "success": "Расположение файла успешно открыто",
+                "failed": "Не удалось открыть расположение файла"
             },
             "metadata": {
                 "version": "Версия",
@@ -646,6 +799,7 @@
                 "strengthMin": "Мин. сила",
                 "strengthMax": "Макс. сила",
                 "strength": "Сила",
+                "clipStrength": "Сила клипа",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "Значение",
                 "add": "Добавить"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "Загружено {completed} из {total} LoRAs. {accessFailures} не удалось из-за ограничений доступа. Проверьте ваш API ключ в настройках или статус раннего доступа.",
             "pleaseSelectVersion": "Пожалуйста, выберите версию",
             "versionExists": "Эта версия уже существует в вашей библиотеке",
-            "downloadCompleted": "Загрузка успешно завершена"
+            "downloadCompleted": "Загрузка успешно завершена",
+            "autoOrganizeSuccess": "Автоматическая организация успешно завершена для {count} {type}",
+            "autoOrganizePartialSuccess": "Автоматическая организация завершена: перемещено {success}, не удалось {failures} из {total} моделей",
+            "autoOrganizeFailed": "Ошибка автоматической организации: {error}",
+            "noModelsSelected": "Модели не выбраны"
         },
         "recipes": {
             "fetchFailed": "Не удалось получить рецепты: {message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "Ошибка: {error}",
             "deleteFailedGeneral": "Не удалось удалить модели",
             "selectedAdditional": "Выбрано дополнительно {count} {type}(ей)",
+            "marqueeSelectionComplete": "Выбрано {count} {type} с помощью выделения рамкой",
             "refreshMetadataFailed": "Не удалось обновить метаданные",
             "nameCannotBeEmpty": "Название модели не может быть пустым",
             "nameUpdatedSuccessfully": "Название модели успешно обновлено",
             "nameUpdateFailed": "Не удалось обновить название модели",
             "baseModelUpdated": "Базовая модель успешно обновлена",
             "baseModelUpdateFailed": "Не удалось обновить базовую модель",
+            "baseModelNotSelected": "Пожалуйста, выберите базовую модель",
+            "bulkBaseModelUpdating": "Обновление базовой модели для {count} моделей...",
+            "bulkBaseModelUpdateSuccess": "Базовая модель успешно обновлена для {count} моделей",
+            "bulkBaseModelUpdatePartial": "Обновлено {success} моделей, не удалось обновить {failed} моделей",
+            "bulkBaseModelUpdateFailed": "Не удалось обновить базовую модель для выбранных моделей",
+            "bulkContentRatingUpdating": "Обновление рейтинга контента для {count} модель(ей)...",
+            "bulkContentRatingSet": "Рейтинг контента установлен на {level} для {count} модель(ей)",
+            "bulkContentRatingPartial": "Рейтинг контента {level} установлен для {success} модель(ей), {failed} не удалось",
+            "bulkContentRatingFailed": "Не удалось обновить рейтинг контента для выбранных моделей",
             "invalidCharactersRemoved": "Недопустимые символы удалены из имени файла",
             "filenameCannotBeEmpty": "Имя файла не может быть пустым",
             "renameFailed": "Не удалось переименовать файл: {message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "Эта группа уже была проверена",
             "verificationCompleteMismatch": "Проверка завершена. {count} файл(ов) имеют разные фактические хеши.",
             "verificationCompleteSuccess": "Проверка завершена. Все файлы подтверждены как дубликаты.",
-            "verificationFailed": "Не удалось проверить хеши: {message}"
+            "verificationFailed": "Не удалось проверить хеши: {message}",
+            "noTagsToAdd": "Нет тегов для добавления",
+            "tagsAddedSuccessfully": "Успешно добавлено {tagCount} тег(ов) к {count} {type}(ам)",
+            "tagsReplacedSuccessfully": "Успешно заменены теги для {count} {type}(ов) на {tagCount} тег(ов)",
+            "tagsAddFailed": "Не удалось добавить теги к {count} модель(ям)",
+            "tagsReplaceFailed": "Не удалось заменить теги для {count} модель(ей)",
+            "bulkTagsAddFailed": "Не удалось добавить теги к моделям",
+            "bulkTagsReplaceFailed": "Не удалось заменить теги для моделей"
         },
         "search": {
             "atLeastOneOption": "Должен быть выбран хотя бы один вариант поиска"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "Компактный режим {state}",
             "settingSaveFailed": "Не удалось сохранить настройку: {message}",
             "displayDensitySet": "Плотность отображения установлена на {density}",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "Не удалось изменить язык: {message}",
             "cacheCleared": "Файлы кэша успешно очищены. Кэш будет пересобран при следующем действии.",
             "cacheClearFailed": "Не удалось очистить кэш: {error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "Путь к примерам изображений успешно обновлен",
+            "pathUpdateFailed": "Не удалось обновить путь к примерам изображений: {message}",
             "downloadInProgress": "Загрузка уже в процессе",
             "enterLocationFirst": "Пожалуйста, сначала введите место загрузки",
             "downloadStarted": "Загрузка примеров изображений начата",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "Не удалось приостановить загрузку: {error}",
             "downloadResumed": "Загрузка возобновлена",
             "resumeFailed": "Не удалось возобновить загрузку: {error}",
+            "downloadStopped": "Загрузка отменена",
+            "stopFailed": "Не удалось отменить загрузку: {error}",
             "deleted": "Пример изображения удален",
             "deleteFailed": "Не удалось удалить пример изображения",
             "setPreviewFailed": "Не удалось установить превью изображение"
@@ -1123,6 +1303,12 @@
             "refreshNow": "Обновить сейчас",
             "refreshingIn": "Обновление через",
             "seconds": "секунд"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/zh-CN.json

@@ -16,20 +16,23 @@
             "loading": "加载中...",
             "unknown": "未知",
             "date": "日期",
-            "version": "版本"
+            "version": "版本",
+            "enabled": "已启用",
+            "disabled": "已禁用"
         },
         "language": {
-            "select": "语言",
+            "select": "选择语言",
             "select_help": "选择你喜欢的界面语言",
             "english": "English",
             "chinese_simplified": "中文（简体）",
             "chinese_traditional": "中文（繁体）",
-            "russian": "俄语",
-            "german": "德语",
-            "japanese": "日语",
-            "korean": "韩语",
-            "french": "法语",
-            "spanish": "西班牙语"
+            "russian": "Русский",
+            "german": "Deutsch",
+            "japanese": "日本語",
+            "korean": "한국어",
+            "french": "Français",
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 字节",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "此模型在 Civitai 上没有远程示例图片"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "下载示例图片",
+            "missingPath": "请先设置下载位置后再下载示例图片。",
+            "unavailable": "示例图片下载当前不可用。请在页面加载完成后重试。"
+        },
+        "cleanupExampleImages": {
+            "label": "清理示例图片文件夹",
+            "success": "已将 {count} 个文件夹移动到已删除文件夹",
+            "none": "没有需要清理的示例图片文件夹",
+            "partial": "清理完成，有 {failures} 个文件夹跳过",
+            "error": "清理示例图片文件夹失败：{message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA 管理器",
         "navigation": {
@@ -171,6 +188,12 @@
         "civitaiApiKey": "Civitai API 密钥",
         "civitaiApiKeyPlaceholder": "请输入你的 Civitai API 密钥",
         "civitaiApiKeyHelp": "用于从 Civitai 下载模型时的身份验证",
+        "openSettingsFileLocation": {
+            "label": "打开设置文件夹",
+            "tooltip": "打开包含 settings.json 的文件夹",
+            "success": "已打开 settings.json 文件夹",
+            "failed": "无法打开 settings.json 文件夹"
+        },
         "sections": {
             "contentFiltering": "内容过滤",
             "videoSettings": "视频设置",
@@ -178,7 +201,10 @@
             "folderSettings": "文件夹设置",
             "downloadPathTemplates": "下载路径模板",
             "exampleImages": "示例图片",
-            "misc": "其他"
+            "misc": "其他",
+            "metadataArchive": "元数据归档数据库",
+            "proxySettings": "代理设置",
+            "priorityTags": "优先标签"
         },
         "contentFiltering": {
             "blurNsfwContent": "模糊 NSFW 内容",
@@ -199,9 +225,9 @@
             },
             "displayDensityHelp": "选择每行显示卡片数量：",
             "displayDensityDetails": {
-                "default": "默认：5（1080p），6（2K），8（4K）",
-                "medium": "中等：6（1080p），7（2K），9（4K）",
-                "compact": "紧凑：7（1080p），8（2K），10（4K）"
+                "default": "5（1080p），6（2K），8（4K）",
+                "medium": "6（1080p），7（2K），9（4K）",
+                "compact": "7（1080p），8（2K），10（4K）"
             },
             "displayDensityWarning": "警告：高密度可能导致资源有限的系统性能下降。",
             "cardInfoDisplay": "卡片信息显示",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "选择何时显示模型信息和操作按钮：",
             "cardInfoDisplayDetails": {
-                "always": "始终可见：标题和底部始终显示",
-                "hover": "悬停时显示：仅在悬停卡片时显示标题和底部"
+                "always": "标题和底部始终显示",
+                "hover": "仅在悬停卡片时显示标题和底部"
+            },
+            "modelNameDisplay": "模型名称显示",
+            "modelNameDisplayOptions": {
+                "modelName": "模型名称",
+                "fileName": "文件名"
+            },
+            "modelNameDisplayHelp": "选择在模型卡片底部显示的内容：",
+            "modelNameDisplayDetails": {
+                "modelName": "显示模型的描述性名称",
+                "fileName": "显示磁盘上的实际文件名"
             }
         },
         "folderSettings": {
+            "activeLibrary": "活动库",
+            "activeLibraryHelp": "在已配置的库之间切换以更新默认文件夹。更改选择将重新加载页面。",
+            "loadingLibraries": "正在加载库...",
+            "noLibraries": "尚未配置库",
             "defaultLoraRoot": "默认 LoRA 根目录",
             "defaultLoraRootHelp": "设置下载、导入和移动时的默认 LoRA 根目录",
             "defaultCheckpointRoot": "默认 Checkpoint 根目录",
@@ -236,6 +276,7 @@
                 "baseModelFirstTag": "基础模型 + 首标签",
                 "baseModelAuthor": "基础模型 + 作者",
                 "authorFirstTag": "作者 + 首标签",
+                "baseModelAuthorFirstTag": "基础模型 + 作者 + 首标签",
                 "customTemplate": "自定义模板"
             },
             "customTemplatePlaceholder": "输入自定义模板（如：{base_model}/{author}/{first_tag}）",
@@ -273,6 +314,68 @@
         "misc": {
             "includeTriggerWords": "复制 LoRA 语法时包含触发词",
             "includeTriggerWordsHelp": "复制 LoRA 语法到剪贴板时包含训练触发词"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "启用元数据归档数据库",
+            "enableArchiveDbHelp": "使用本地数据库访问已从 Civitai 删除的模型元数据。",
+            "status": "状态",
+            "statusAvailable": "可用",
+            "statusUnavailable": "不可用",
+            "enabled": "已启用",
+            "management": "数据库管理",
+            "managementHelp": "下载或移除元数据归档数据库",
+            "downloadButton": "下载数据库",
+            "downloadingButton": "正在下载...",
+            "downloadedButton": "已下载",
+            "removeButton": "移除数据库",
+            "removingButton": "正在移除...",
+            "downloadSuccess": "元数据归档数据库下载成功",
+            "downloadError": "元数据归档数据库下载失败",
+            "removeSuccess": "元数据归档数据库移除成功",
+            "removeError": "元数据归档数据库移除失败",
+            "removeConfirm": "你确定要移除元数据归档数据库吗？这将删除本地数据库文件，如需使用此功能需重新下载。",
+            "preparing": "正在准备下载...",
+            "connecting": "正在连接下载服务器...",
+            "completed": "已完成",
+            "downloadComplete": "下载成功完成"
+        },
+        "proxySettings": {
+            "enableProxy": "启用应用级代理",
+            "enableProxyHelp": "为此应用启用自定义代理设置，覆盖系统代理设置",
+            "proxyType": "代理类型",
+            "proxyTypeHelp": "选择代理服务器类型 (HTTP, HTTPS, SOCKS4, SOCKS5)",
+            "proxyHost": "代理主机",
+            "proxyHostPlaceholder": "proxy.example.com",
+            "proxyHostHelp": "代理服务器的主机名或IP地址",
+            "proxyPort": "代理端口",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "代理服务器的端口号",
+            "proxyUsername": "用户名 (可选)",
+            "proxyUsernamePlaceholder": "用户名",
+            "proxyUsernameHelp": "代理认证的用户名 (如果需要)",
+            "proxyPassword": "密码 (可选)",
+            "proxyPasswordPlaceholder": "密码",
+            "proxyPasswordHelp": "代理认证的密码 (如果需要)"
+        },
+        "priorityTags": {
+            "title": "优先标签",
+            "description": "为每种模型类型自定义标签优先级顺序 (例如: character, concept, style(toon|toon_style))",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "打开优先标签帮助",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "Checkpoint",
+                "embedding": "Embedding"
+            },
+            "saveSuccess": "优先标签已更新。",
+            "saveError": "优先标签更新失败。",
+            "loadingSuggestions": "正在加载建议...",
+            "validation": {
+                "missingClosingParen": "条目 {index} 缺少右括号。",
+                "missingCanonical": "条目 {index} 必须包含规范标签名称。",
+                "duplicateCanonical": "规范标签 \"{tag}\" 出现多次。",
+                "unknown": "优先标签配置无效。"
+            }
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "已选中 {count} 项",
             "selectedSuffix": "已选中",
-            "viewSelected": "点击查看已选项目",
-            "sendToWorkflow": "发送到工作流",
-            "copyAll": "全部复制",
-            "refreshAll": "全部刷新",
-            "moveAll": "全部移动",
-            "deleteAll": "全部删除",
-            "clear": "清除"
+            "viewSelected": "查看已选中",
+            "addTags": "为所选中添加标签",
+            "setBaseModel": "为所选中设置基础模型",
+            "setContentRating": "为所选中设置内容评级",
+            "copyAll": "复制所选中语法",
+            "refreshAll": "刷新所选中元数据",
+            "moveAll": "移动所选中到文件夹",
+            "autoOrganize": "自动整理所选模型",
+            "deleteAll": "删除选中模型",
+            "clear": "清除选择",
+            "autoOrganizeProgress": {
+                "initializing": "正在初始化自动整理...",
+                "starting": "正在为 {type} 启动自动整理...",
+                "processing": "处理中（{processed}/{total}）- 已移动 {success} 个，跳过 {skipped} 个，失败 {failures} 个",
+                "cleaning": "正在清理空文件夹...",
+                "completed": "完成：已移动 {success} 个，跳过 {skipped} 个，失败 {failures} 个",
+                "complete": "自动整理已完成",
+                "error": "错误：{error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "刷新 Civitai 数据",
@@ -445,13 +560,19 @@
         "title": "Embedding 模型"
     },
     "sidebar": {
-        "modelRoot": "模型根目录",
+        "modelRoot": "根目录",
         "collapseAll": "折叠所有文件夹",
         "pinSidebar": "固定侧边栏",
         "unpinSidebar": "取消固定侧边栏",
         "switchToListView": "切换到列表视图",
         "switchToTreeView": "切换到树状视图",
-        "collapseAllDisabled": "列表视图下不可用"
+        "recursiveOn": "搜索子文件夹",
+        "recursiveOff": "仅搜索当前文件夹",
+        "recursiveUnavailable": "仅在树形视图中可使用递归搜索",
+        "collapseAllDisabled": "列表视图下不可用",
+        "dragDrop": {
+            "unableToResolveRoot": "无法确定移动的目标路径。"
+        }
     },
     "statistics": {
         "title": "统计",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "预览图片已下载",
                 "downloadingFile": "正在下载 {type} 文件",
                 "finalizing": "正在完成下载..."
+            },
+            "progress": {
+                "currentFile": "当前文件：",
+                "downloading": "下载中：{name}",
+                "transferred": "已下载：{downloaded} / {total}",
+                "transferredSimple": "已下载：{downloaded}",
+                "transferredUnknown": "已下载：--",
+                "speed": "速度：{speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "设置内容评级",
             "current": "当前",
+            "multiple": "多个值",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "模型将被永久删除。",
             "action": "全部删除"
         },
+        "bulkAddTags": {
+            "title": "批量添加标签",
+            "description": "为多个模型添加标签",
+            "models": "个模型",
+            "tagsToAdd": "要添加的标签",
+            "placeholder": "输入标签并按回车...",
+            "appendTags": "追加标签",
+            "replaceTags": "替换标签",
+            "saveChanges": "保存更改"
+        },
+        "bulkBaseModel": {
+            "title": "批量设置基础模型",
+            "description": "为多个模型设置基础模型",
+            "models": "个模型",
+            "selectBaseModel": "选择基础模型",
+            "save": "更新基础模型",
+            "cancel": "取消"
+        },
         "exampleAccess": {
             "title": "本地示例图片",
             "message": "未找到此模型的本地示例图片。可选操作：",
@@ -622,7 +770,12 @@
                 "editBaseModel": "编辑基础模型",
                 "viewOnCivitai": "在 Civitai 查看",
                 "viewOnCivitaiText": "在 Civitai 查看",
-                "viewCreatorProfile": "查看创作者主页"
+                "viewCreatorProfile": "查看创作者主页",
+                "openFileLocation": "打开文件位置"
+            },
+            "openFileLocation": {
+                "success": "文件位置已成功打开",
+                "failed": "打开文件位置失败"
             },
             "metadata": {
                 "version": "版本",
@@ -646,6 +799,7 @@
                 "strengthMin": "最小强度",
                 "strengthMax": "最大强度",
                 "strength": "强度",
+                "clipStrength": "Clip 强度",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "数值",
                 "add": "添加"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "已下载 {completed}/{total} 个 LoRA。{accessFailures} 个因访问限制失败。请检查设置中的 API 密钥或早期访问状态。",
             "pleaseSelectVersion": "请选择版本",
             "versionExists": "该版本已存在于你的库中",
-            "downloadCompleted": "下载成功完成"
+            "downloadCompleted": "下载成功完成",
+            "autoOrganizeSuccess": "自动整理已成功完成，共 {count} 个 {type}",
+            "autoOrganizePartialSuccess": "自动整理完成：已移动 {success} 个，{failures} 个失败，共 {total} 个模型",
+            "autoOrganizeFailed": "自动整理失败：{error}",
+            "noModelsSelected": "未选中模型"
         },
         "recipes": {
             "fetchFailed": "获取配方失败：{message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "错误：{error}",
             "deleteFailedGeneral": "删除模型失败",
             "selectedAdditional": "已选中 {count} 个额外 {type}",
+            "marqueeSelectionComplete": "框选已选中 {count} 个 {type}",
             "refreshMetadataFailed": "刷新元数据失败",
             "nameCannotBeEmpty": "模型名称不能为空",
             "nameUpdatedSuccessfully": "模型名称更新成功",
             "nameUpdateFailed": "模型名称更新失败",
             "baseModelUpdated": "基础模型更新成功",
             "baseModelUpdateFailed": "基础模型更新失败",
+            "baseModelNotSelected": "请选择基础模型",
+            "bulkBaseModelUpdating": "正在为 {count} 个模型更新基础模型...",
+            "bulkBaseModelUpdateSuccess": "成功为 {count} 个模型更新基础模型",
+            "bulkBaseModelUpdatePartial": "更新了 {success} 个模型，{failed} 个失败",
+            "bulkBaseModelUpdateFailed": "为选中模型更新基础模型失败",
+            "bulkContentRatingUpdating": "正在为 {count} 个模型更新内容评级...",
+            "bulkContentRatingSet": "已将 {count} 个模型的内容评级设置为 {level}",
+            "bulkContentRatingPartial": "已将 {success} 个模型的内容评级设置为 {level}，{failed} 个失败",
+            "bulkContentRatingFailed": "未能更新所选模型的内容评级",
             "invalidCharactersRemoved": "文件名中的无效字符已移除",
             "filenameCannotBeEmpty": "文件名不能为空",
             "renameFailed": "重命名文件失败：{message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "此组已验证过",
             "verificationCompleteMismatch": "验证完成。{count} 个文件实际哈希不同。",
             "verificationCompleteSuccess": "验证完成。所有文件均为重复项。",
-            "verificationFailed": "验证哈希失败：{message}"
+            "verificationFailed": "验证哈希失败：{message}",
+            "noTagsToAdd": "没有可添加的标签",
+            "tagsAddedSuccessfully": "已成功为 {count} 个 {type} 添加 {tagCount} 个标签",
+            "tagsReplacedSuccessfully": "已成功为 {count} 个 {type} 替换为 {tagCount} 个标签",
+            "tagsAddFailed": "为 {count} 个模型添加标签失败",
+            "tagsReplaceFailed": "为 {count} 个模型替换标签失败",
+            "bulkTagsAddFailed": "批量添加标签失败",
+            "bulkTagsReplaceFailed": "批量替换标签失败"
         },
         "search": {
             "atLeastOneOption": "至少选择一个搜索选项"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "紧凑模式 {state}",
             "settingSaveFailed": "保存设置失败：{message}",
             "displayDensitySet": "显示密度已设置为 {density}",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "切换语言失败：{message}",
             "cacheCleared": "缓存文件已成功清除。下次操作将重建缓存。",
             "cacheClearFailed": "清除缓存失败：{error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "示例图片路径更新成功",
+            "pathUpdateFailed": "更新示例图片路径失败：{message}",
             "downloadInProgress": "下载已在进行中",
             "enterLocationFirst": "请先输入下载位置",
             "downloadStarted": "示例图片下载已开始",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "暂停下载失败：{error}",
             "downloadResumed": "下载已恢复",
             "resumeFailed": "恢复下载失败：{error}",
+            "downloadStopped": "下载已取消",
+            "stopFailed": "取消下载失败：{error}",
             "deleted": "示例图片已删除",
             "deleteFailed": "删除示例图片失败",
             "setPreviewFailed": "设置预览图片失败"
@@ -1123,6 +1303,12 @@
             "refreshNow": "立即刷新",
             "refreshingIn": "将在",
             "seconds": "秒后刷新"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

locales/zh-TW.json

@@ -16,7 +16,9 @@
             "loading": "載入中...",
             "unknown": "未知",
             "date": "日期",
-            "version": "版本"
+            "version": "版本",
+            "enabled": "已啟用",
+            "disabled": "已停用"
         },
         "language": {
             "select": "語言",
@@ -29,7 +31,8 @@
             "japanese": "日本語",
             "korean": "한국어",
             "french": "Français",
-            "spanish": "Español"
+            "spanish": "Español",
+            "Hebrew": "עברית"
         },
         "fileSize": {
             "zero": "0 位元組",
@@ -120,6 +123,20 @@
             "noRemoteImagesAvailable": "此模型在 Civitai 上無遠端範例圖片"
         }
     },
+    "globalContextMenu": {
+        "downloadExampleImages": {
+            "label": "下載範例圖片",
+            "missingPath": "請先設定下載位置再下載範例圖片。",
+            "unavailable": "範例圖片下載目前尚不可用。請在頁面載入完成後再試一次。"
+        },
+        "cleanupExampleImages": {
+            "label": "清理範例圖片資料夾",
+            "success": "已將 {count} 個資料夾移至已刪除資料夾",
+            "none": "沒有需要清理的範例圖片資料夾",
+            "partial": "清理完成，有 {failures} 個資料夾略過",
+            "error": "清理範例圖片資料夾失敗：{message}"
+        }
+    },
     "header": {
         "appTitle": "LoRA 管理器",
         "navigation": {
@@ -171,6 +188,12 @@
         "civitaiApiKey": "Civitai API 金鑰",
         "civitaiApiKeyPlaceholder": "請輸入您的 Civitai API 金鑰",
         "civitaiApiKeyHelp": "用於從 Civitai 下載模型時的身份驗證",
+        "openSettingsFileLocation": {
+            "label": "開啟設定資料夾",
+            "tooltip": "開啟包含 settings.json 的資料夾",
+            "success": "已開啟 settings.json 資料夾",
+            "failed": "無法開啟 settings.json 資料夾"
+        },
         "sections": {
             "contentFiltering": "內容過濾",
             "videoSettings": "影片設定",
@@ -178,7 +201,10 @@
             "folderSettings": "資料夾設定",
             "downloadPathTemplates": "下載路徑範本",
             "exampleImages": "範例圖片",
-            "misc": "其他"
+            "misc": "其他",
+            "metadataArchive": "中繼資料封存資料庫",
+            "proxySettings": "代理設定",
+            "priorityTags": "優先標籤"
         },
         "contentFiltering": {
             "blurNsfwContent": "模糊 NSFW 內容",
@@ -199,9 +225,9 @@
             },
             "displayDensityHelp": "選擇每行顯示卡片數量：",
             "displayDensityDetails": {
-                "default": "預設：5（1080p）、6（2K）、8（4K）",
-                "medium": "中等：6（1080p）、7（2K）、9（4K）",
-                "compact": "緊湊：7（1080p）、8（2K）、10（4K）"
+                "default": "5（1080p）、6（2K）、8（4K）",
+                "medium": "6（1080p）、7（2K）、9（4K）",
+                "compact": "7（1080p）、8（2K）、10（4K）"
             },
             "displayDensityWarning": "警告：較高密度可能導致資源有限的系統效能下降。",
             "cardInfoDisplay": "卡片資訊顯示",
@@ -211,11 +237,25 @@
             },
             "cardInfoDisplayHelp": "選擇何時顯示模型資訊與操作按鈕：",
             "cardInfoDisplayDetails": {
-                "always": "永遠顯示：標題與頁腳始終可見",
-                "hover": "滑鼠懸停顯示：標題與頁腳僅在滑鼠懸停時顯示"
+                "always": "標題與頁腳始終可見",
+                "hover": "標題與頁腳僅在滑鼠懸停時顯示"
+            },
+            "modelNameDisplay": "模型名稱顯示",
+            "modelNameDisplayOptions": {
+                "modelName": "模型名稱",
+                "fileName": "檔案名稱"
+            },
+            "modelNameDisplayHelp": "選擇在模型卡片底部顯示的內容：",
+            "modelNameDisplayDetails": {
+                "modelName": "顯示模型的描述性名稱",
+                "fileName": "顯示磁碟上的實際檔案名稱"
             }
         },
         "folderSettings": {
+            "activeLibrary": "使用中的資料庫",
+            "activeLibraryHelp": "在已設定的資料庫之間切換以更新預設資料夾。變更選項會重新載入頁面。",
+            "loadingLibraries": "正在載入資料庫...",
+            "noLibraries": "尚未設定任何資料庫",
             "defaultLoraRoot": "預設 LoRA 根目錄",
             "defaultLoraRootHelp": "設定下載、匯入和移動時的預設 LoRA 根目錄",
             "defaultCheckpointRoot": "預設 Checkpoint 根目錄",
@@ -236,6 +276,7 @@
                 "baseModelFirstTag": "基礎模型 + 第一標籤",
                 "baseModelAuthor": "基礎模型 + 作者",
                 "authorFirstTag": "作者 + 第一標籤",
+                "baseModelAuthorFirstTag": "基礎模型 + 作者 + 第一標籤",
                 "customTemplate": "自訂範本"
             },
             "customTemplatePlaceholder": "輸入自訂範本（例如：{base_model}/{author}/{first_tag}）",
@@ -273,6 +314,68 @@
         "misc": {
             "includeTriggerWords": "在 LoRA 語法中包含觸發詞",
             "includeTriggerWordsHelp": "複製 LoRA 語法到剪貼簿時包含訓練觸發詞"
+        },
+        "metadataArchive": {
+            "enableArchiveDb": "啟用中繼資料封存資料庫",
+            "enableArchiveDbHelp": "使用本機資料庫以存取已從 Civitai 刪除模型的中繼資料。",
+            "status": "狀態",
+            "statusAvailable": "可用",
+            "statusUnavailable": "不可用",
+            "enabled": "已啟用",
+            "management": "資料庫管理",
+            "managementHelp": "下載或移除中繼資料封存資料庫",
+            "downloadButton": "下載資料庫",
+            "downloadingButton": "下載中...",
+            "downloadedButton": "已下載",
+            "removeButton": "移除資料庫",
+            "removingButton": "移除中...",
+            "downloadSuccess": "中繼資料封存資料庫下載成功",
+            "downloadError": "下載中繼資料封存資料庫失敗",
+            "removeSuccess": "中繼資料封存資料庫移除成功",
+            "removeError": "移除中繼資料封存資料庫失敗",
+            "removeConfirm": "您確定要移除中繼資料封存資料庫嗎？這將刪除本機資料庫檔案，若要再次使用此功能需重新下載。",
+            "preparing": "準備下載中...",
+            "connecting": "正在連接下載伺服器...",
+            "completed": "已完成",
+            "downloadComplete": "下載成功完成"
+        },
+        "proxySettings": {
+            "enableProxy": "啟用應用程式代理",
+            "enableProxyHelp": "啟用此應用程式的自訂代理設定，將覆蓋系統代理設定",
+            "proxyType": "代理類型",
+            "proxyTypeHelp": "選擇代理伺服器類型（HTTP、HTTPS、SOCKS4、SOCKS5）",
+            "proxyHost": "代理主機",
+            "proxyHostPlaceholder": "proxy.example.com",
+            "proxyHostHelp": "您的代理伺服器主機名稱或 IP 位址",
+            "proxyPort": "代理埠號",
+            "proxyPortPlaceholder": "8080",
+            "proxyPortHelp": "您的代理伺服器埠號",
+            "proxyUsername": "使用者名稱（選填）",
+            "proxyUsernamePlaceholder": "username",
+            "proxyUsernameHelp": "代理驗證所需的使用者名稱（如有需要）",
+            "proxyPassword": "密碼（選填）",
+            "proxyPasswordPlaceholder": "password",
+            "proxyPasswordHelp": "代理驗證所需的密碼（如有需要）"
+        },
+        "priorityTags": {
+            "title": "優先標籤",
+            "description": "為每種模型類型自訂標籤的優先順序 (例如: character, concept, style(toon|toon_style))",
+            "placeholder": "character, concept, style(toon|toon_style)",
+            "helpLinkLabel": "開啟優先標籤說明",
+            "modelTypes": {
+                "lora": "LoRA",
+                "checkpoint": "Checkpoint",
+                "embedding": "Embedding"
+            },
+            "saveSuccess": "優先標籤已更新。",
+            "saveError": "更新優先標籤失敗。",
+            "loadingSuggestions": "正在載入建議...",
+            "validation": {
+                "missingClosingParen": "項目 {index} 缺少右括號。",
+                "missingCanonical": "項目 {index} 必須包含正規標籤名稱。",
+                "duplicateCanonical": "正規標籤 \"{tag}\" 出現多於一次。",
+                "unknown": "優先標籤設定無效。"
+            }
         }
     },
     "loras": {
@@ -318,13 +421,25 @@
         "bulkOperations": {
             "selected": "已選擇 {count} 項",
             "selectedSuffix": "已選擇",
-            "viewSelected": "點擊檢視已選項目",
-            "sendToWorkflow": "傳送到工作流",
-            "copyAll": "全部複製",
-            "refreshAll": "全部刷新",
-            "moveAll": "全部移動",
-            "deleteAll": "全部刪除",
-            "clear": "清除"
+            "viewSelected": "檢視已選取",
+            "addTags": "新增標籤到全部",
+            "setBaseModel": "設定全部基礎模型",
+            "setContentRating": "為全部設定內容分級",
+            "copyAll": "複製全部語法",
+            "refreshAll": "刷新全部 metadata",
+            "moveAll": "全部移動到資料夾",
+            "autoOrganize": "自動整理所選模型",
+            "deleteAll": "刪除全部模型",
+            "clear": "清除選取",
+            "autoOrganizeProgress": {
+                "initializing": "正在初始化自動整理...",
+                "starting": "正在開始自動整理 {type}...",
+                "processing": "處理中（{processed}/{total}）- 已移動 {success}，已略過 {skipped}，失敗 {failures}",
+                "cleaning": "正在清理空資料夾...",
+                "completed": "完成：已移動 {success}，已略過 {skipped}，失敗 {failures}",
+                "complete": "自動整理完成",
+                "error": "錯誤：{error}"
+            }
         },
         "contextMenu": {
             "refreshMetadata": "刷新 Civitai 資料",
@@ -445,13 +560,19 @@
         "title": "Embedding 模型"
     },
     "sidebar": {
-        "modelRoot": "模型根目錄",
+        "modelRoot": "根目錄",
         "collapseAll": "全部摺疊資料夾",
         "pinSidebar": "固定側邊欄",
         "unpinSidebar": "取消固定側邊欄",
         "switchToListView": "切換至列表檢視",
-        "switchToTreeView": "切換至樹狀檢視",
-        "collapseAllDisabled": "列表檢視下不可用"
+        "switchToTreeView": "切換到樹狀檢視",
+        "recursiveOn": "搜尋子資料夾",
+        "recursiveOff": "僅搜尋目前資料夾",
+        "recursiveUnavailable": "遞迴搜尋僅能在樹狀檢視中使用",
+        "collapseAllDisabled": "列表檢視下不可用",
+        "dragDrop": {
+            "unableToResolveRoot": "無法確定移動的目標路徑。"
+        }
     },
     "statistics": {
         "title": "統計",
@@ -526,6 +647,14 @@
                 "downloadedPreview": "已下載預覽圖片",
                 "downloadingFile": "正在下載 {type} 檔案",
                 "finalizing": "完成下載中..."
+            },
+            "progress": {
+                "currentFile": "目前檔案：",
+                "downloading": "下載中：{name}",
+                "transferred": "已下載：{downloaded} / {total}",
+                "transferredSimple": "已下載：{downloaded}",
+                "transferredUnknown": "已下載：--",
+                "speed": "速度：{speed}"
             }
         },
         "move": {
@@ -534,6 +663,7 @@
         "contentRating": {
             "title": "設定內容分級",
             "current": "目前",
+            "multiple": "多個值",
             "levels": {
                 "pg": "PG",
                 "pg13": "PG13",
@@ -572,6 +702,24 @@
             "countMessage": "模型將被永久刪除。",
             "action": "全部刪除"
         },
+        "bulkAddTags": {
+            "title": "新增標籤到多個模型",
+            "description": "新增標籤到",
+            "models": "個模型",
+            "tagsToAdd": "要新增的標籤",
+            "placeholder": "輸入標籤並按 Enter...",
+            "appendTags": "附加標籤",
+            "replaceTags": "取代標籤",
+            "saveChanges": "儲存變更"
+        },
+        "bulkBaseModel": {
+            "title": "設定多個模型的基礎模型",
+            "description": "設定基礎模型給",
+            "models": "個模型",
+            "selectBaseModel": "選擇基礎模型",
+            "save": "更新基礎模型",
+            "cancel": "取消"
+        },
         "exampleAccess": {
             "title": "本機範例圖片",
             "message": "此模型未找到本機範例圖片。可選擇：",
@@ -622,7 +770,12 @@
                 "editBaseModel": "編輯基礎模型",
                 "viewOnCivitai": "在 Civitai 查看",
                 "viewOnCivitaiText": "在 Civitai 查看",
-                "viewCreatorProfile": "查看創作者個人檔案"
+                "viewCreatorProfile": "查看創作者個人檔案",
+                "openFileLocation": "開啟檔案位置"
+            },
+            "openFileLocation": {
+                "success": "檔案位置已成功開啟",
+                "failed": "開啟檔案位置失敗"
             },
             "metadata": {
                 "version": "版本",
@@ -646,6 +799,7 @@
                 "strengthMin": "最小強度",
                 "strengthMax": "最大強度",
                 "strength": "強度",
+                "clipStrength": "Clip 強度",
                 "clipSkip": "Clip Skip",
                 "valuePlaceholder": "數值",
                 "add": "新增"
@@ -923,7 +1077,11 @@
             "downloadPartialWithAccess": "已下載 {completed} 個 LoRA，共 {total} 個。{accessFailures} 個因訪問限制而失敗。請檢查您的 API 密鑰或提前訪問狀態。",
             "pleaseSelectVersion": "請選擇一個版本",
             "versionExists": "此版本已存在於您的庫中",
-            "downloadCompleted": "下載成功完成"
+            "downloadCompleted": "下載成功完成",
+            "autoOrganizeSuccess": "自動整理已成功完成，共 {count} 個 {type} 已整理",
+            "autoOrganizePartialSuccess": "自動整理完成：已移動 {success} 個，{failures} 個失敗，共 {total} 個模型",
+            "autoOrganizeFailed": "自動整理失敗：{error}",
+            "noModelsSelected": "未選擇任何模型"
         },
         "recipes": {
             "fetchFailed": "取得配方失敗：{message}",
@@ -972,12 +1130,22 @@
             "deleteFailed": "錯誤：{error}",
             "deleteFailedGeneral": "刪除模型失敗",
             "selectedAdditional": "已選擇 {count} 個額外 {type}",
+            "marqueeSelectionComplete": "框選已選擇 {count} 個 {type}",
             "refreshMetadataFailed": "刷新 metadata 失敗",
             "nameCannotBeEmpty": "模型名稱不可為空",
             "nameUpdatedSuccessfully": "模型名稱已成功更新",
             "nameUpdateFailed": "更新模型名稱失敗",
             "baseModelUpdated": "基礎模型已成功更新",
             "baseModelUpdateFailed": "更新基礎模型失敗",
+            "baseModelNotSelected": "請選擇基礎模型",
+            "bulkBaseModelUpdating": "正在為 {count} 個模型更新基礎模型...",
+            "bulkBaseModelUpdateSuccess": "已成功為 {count} 個模型更新基礎模型",
+            "bulkBaseModelUpdatePartial": "已更新 {success} 個模型，{failed} 個模型失敗",
+            "bulkBaseModelUpdateFailed": "更新所選模型的基礎模型失敗",
+            "bulkContentRatingUpdating": "正在為 {count} 個模型更新內容分級...",
+            "bulkContentRatingSet": "已將 {count} 個模型的內容分級設定為 {level}",
+            "bulkContentRatingPartial": "已將 {success} 個模型的內容分級設定為 {level}，{failed} 個失敗",
+            "bulkContentRatingFailed": "無法更新所選模型的內容分級",
             "invalidCharactersRemoved": "已移除檔名中的無效字元",
             "filenameCannotBeEmpty": "檔案名稱不可為空",
             "renameFailed": "重新命名檔案失敗：{message}",
@@ -987,7 +1155,14 @@
             "verificationAlreadyDone": "此群組已驗證過",
             "verificationCompleteMismatch": "驗證完成。{count} 個檔案的實際雜湊不同。",
             "verificationCompleteSuccess": "驗證完成。所有檔案均確認為重複項。",
-            "verificationFailed": "驗證雜湊失敗：{message}"
+            "verificationFailed": "驗證雜湊失敗：{message}",
+            "noTagsToAdd": "沒有可新增的標籤",
+            "tagsAddedSuccessfully": "已成功將 {tagCount} 個標籤新增到 {count} 個 {type}",
+            "tagsReplacedSuccessfully": "已成功以 {tagCount} 個標籤取代 {count} 個 {type} 的標籤",
+            "tagsAddFailed": "新增標籤到 {count} 個模型失敗",
+            "tagsReplaceFailed": "取代 {count} 個模型的標籤失敗",
+            "bulkTagsAddFailed": "批量新增標籤到模型失敗",
+            "bulkTagsReplaceFailed": "批量取代模型標籤失敗"
         },
         "search": {
             "atLeastOneOption": "至少需選擇一個搜尋選項"
@@ -1005,6 +1180,8 @@
             "compactModeToggled": "緊湊模式已{state}",
             "settingSaveFailed": "儲存設定失敗：{message}",
             "displayDensitySet": "顯示密度已設為 {density}",
+            "libraryLoadFailed": "Failed to load libraries: {message}",
+            "libraryActivateFailed": "Failed to activate library: {message}",
             "languageChangeFailed": "切換語言失敗：{message}",
             "cacheCleared": "快取檔案已成功清除。快取將於下次操作時重建。",
             "cacheClearFailed": "清除快取失敗：{error}",
@@ -1069,6 +1246,7 @@
         },
         "exampleImages": {
             "pathUpdated": "範例圖片路徑已更新",
+            "pathUpdateFailed": "更新範例圖片路徑失敗：{message}",
             "downloadInProgress": "下載已在進行中",
             "enterLocationFirst": "請先輸入下載位置",
             "downloadStarted": "範例圖片下載已開始",
@@ -1077,6 +1255,8 @@
             "pauseFailed": "暫停下載失敗：{error}",
             "downloadResumed": "下載已恢復",
             "resumeFailed": "恢復下載失敗：{error}",
+            "downloadStopped": "下載已取消",
+            "stopFailed": "取消下載失敗：{error}",
             "deleted": "範例圖片已刪除",
             "deleteFailed": "刪除範例圖片失敗",
             "setPreviewFailed": "設定預覽圖片失敗"
@@ -1123,6 +1303,12 @@
             "refreshNow": "立即重新整理",
             "refreshingIn": "將於",
             "seconds": "秒後重新整理"
+        },
+        "communitySupport": {
+            "title": "Keep LoRA Manager Thriving with Your Support ❤️",
+            "content": "LoRA Manager is a passion project maintained full-time by a solo developer. Your support on Ko-fi helps cover development costs, keeps new updates coming, and unlocks a license key for the LM Civitai Extension as a thank-you gift. Every contribution truly makes a difference.",
+            "supportCta": "Support on Ko-fi",
+            "learnMore": "LM Civitai Extension Tutorial"
         }
     }
 }

package.json

@@ -0,0 +1,15 @@
+{
+  "name": "comfyui-lora-manager-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "node scripts/run_frontend_coverage.js"
+  },
+  "devDependencies": {
+    "jsdom": "^24.0.0",
+    "vitest": "^1.6.0"
+  }
+}

py/__init__.py

@@ -0,0 +1,12 @@
+"""Project namespace package."""
+
+# pytest's internal compatibility layer still imports ``py.path.local`` from the
+# historical ``py`` dependency.  Because this project reuses the ``py`` package
+# name, we expose a minimal shim so ``py.path.local`` resolves to ``pathlib.Path``
+# during test runs without pulling in the external dependency.
+from pathlib import Path
+from types import SimpleNamespace
+
+path = SimpleNamespace(local=Path)
+
+__all__ = ["path"]

py/config.py

@@ -1,17 +1,50 @@
 import os
 import platform
+from pathlib import Path
 import folder_paths # type: ignore
-from typing import List
+from typing import Dict, Iterable, List, Mapping, Set
 import logging
-import sys
 import json
 import urllib.parse
 
-# Check if running in standalone mode
-standalone_mode = 'nodes' not in sys.modules
+from .utils.settings_paths import ensure_settings_file
+
+# Use an environment variable to control standalone mode
+standalone_mode = os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1" or os.environ.get("HF_HUB_DISABLE_TELEMETRY", "0") == "0"
 
 logger = logging.getLogger(__name__)
 
+
+def _normalize_folder_paths_for_comparison(
+    folder_paths: Mapping[str, Iterable[str]]
+) -> Dict[str, Set[str]]:
+    """Normalize folder paths for comparison across libraries."""
+
+    normalized: Dict[str, Set[str]] = {}
+    for key, values in folder_paths.items():
+        if isinstance(values, str):
+            candidate_values: Iterable[str] = [values]
+        else:
+            try:
+                candidate_values = iter(values)
+            except TypeError:
+                continue
+
+        normalized_values: Set[str] = set()
+        for value in candidate_values:
+            if not isinstance(value, str):
+                continue
+            stripped = value.strip()
+            if not stripped:
+                continue
+            normalized_values.add(os.path.normcase(os.path.normpath(stripped)))
+
+        if normalized_values:
+            normalized[key] = normalized_values
+
+    return normalized
+
+
 class Config:
     """Global configuration for LoRA Manager"""
     
@@ -20,9 +53,9 @@ class Config:
         self.static_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'static')
         self.i18n_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'locales')
         # Path mapping dictionary, target to link mapping
-        self._path_mappings = {}
-        # Static route mapping dictionary, target to route mapping
-        self._route_mappings = {}
+        self._path_mappings: Dict[str, str] = {}
+        # Normalized preview root directories used to validate preview access
+        self._preview_root_paths: Set[Path] = set()
         self.loras_roots = self._init_lora_paths()
         self.checkpoints_roots = None
         self.unet_roots = None
@@ -31,45 +64,74 @@ class Config:
         self.embeddings_roots = self._init_embedding_paths()
         # Scan symbolic links during initialization
         self._scan_symbolic_links()
+        self._rebuild_preview_roots()
         
         if not standalone_mode:
             # Save the paths to settings.json when running in ComfyUI mode
             self.save_folder_paths_to_settings()
 
     def save_folder_paths_to_settings(self):
-        """Save folder paths to settings.json for standalone mode to use later"""
+        """Persist ComfyUI-derived folder paths to the multi-library settings."""
         try:
-            # Check if we're running in ComfyUI mode (not standalone)           
-            # Load existing settings
-            settings_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'settings.json')
-            settings = {}
-            if os.path.exists(settings_path):
-                with open(settings_path, 'r', encoding='utf-8') as f:
-                    settings = json.load(f)
-            
-            # Update settings with paths
-            settings['folder_paths'] = {
-                'loras': self.loras_roots,
-                'checkpoints': self.checkpoints_roots,
-                'unet': self.unet_roots,
-                'embeddings': self.embeddings_roots,
-            }
-            
-            # Add default roots if there's only one item and key doesn't exist
-            if len(self.loras_roots) == 1 and "default_lora_root" not in settings:
-                settings["default_lora_root"] = self.loras_roots[0]
-            
-            if self.checkpoints_roots and len(self.checkpoints_roots) == 1 and "default_checkpoint_root" not in settings:
-                settings["default_checkpoint_root"] = self.checkpoints_roots[0]
+            ensure_settings_file(logger)
+            from .services.settings_manager import get_settings_manager
 
-            if self.embeddings_roots and len(self.embeddings_roots) == 1 and "default_embedding_root" not in settings:
-                settings["default_embedding_root"] = self.embeddings_roots[0]
-            
-            # Save settings
-            with open(settings_path, 'w', encoding='utf-8') as f:
-                json.dump(settings, f, indent=2)
-            
-            logger.info("Saved folder paths to settings.json")
+            settings_service = get_settings_manager()
+            libraries = settings_service.get_libraries()
+            comfy_library = libraries.get("comfyui", {})
+            default_library = libraries.get("default", {})
+
+            target_folder_paths = {
+                'loras': list(self.loras_roots),
+                'checkpoints': list(self.checkpoints_roots or []),
+                'unet': list(self.unet_roots or []),
+                'embeddings': list(self.embeddings_roots or []),
+            }
+
+            normalized_target_paths = _normalize_folder_paths_for_comparison(target_folder_paths)
+
+            if (not comfy_library and default_library and normalized_target_paths and
+                    _normalize_folder_paths_for_comparison(default_library.get("folder_paths", {})) ==
+                    normalized_target_paths):
+                try:
+                    settings_service.rename_library("default", "comfyui")
+                    logger.info("Renamed legacy 'default' library to 'comfyui'")
+                    libraries = settings_service.get_libraries()
+                    comfy_library = libraries.get("comfyui", {})
+                except Exception as rename_error:
+                    logger.debug(
+                        "Failed to rename legacy 'default' library: %s", rename_error
+                    )
+
+            default_lora_root = comfy_library.get("default_lora_root", "")
+            if not default_lora_root and len(self.loras_roots) == 1:
+                default_lora_root = self.loras_roots[0]
+
+            default_checkpoint_root = comfy_library.get("default_checkpoint_root", "")
+            if (not default_checkpoint_root and self.checkpoints_roots and
+                    len(self.checkpoints_roots) == 1):
+                default_checkpoint_root = self.checkpoints_roots[0]
+
+            default_embedding_root = comfy_library.get("default_embedding_root", "")
+            if (not default_embedding_root and self.embeddings_roots and
+                    len(self.embeddings_roots) == 1):
+                default_embedding_root = self.embeddings_roots[0]
+
+            metadata = dict(comfy_library.get("metadata", {}))
+            metadata.setdefault("display_name", "ComfyUI")
+            metadata["source"] = "comfyui"
+
+            settings_service.upsert_library(
+                "comfyui",
+                folder_paths=target_folder_paths,
+                default_lora_root=default_lora_root,
+                default_checkpoint_root=default_checkpoint_root,
+                default_embedding_root=default_embedding_root,
+                metadata=metadata,
+                activate=True,
+            )
+
+            logger.info("Updated 'comfyui' library with current folder paths")
         except Exception as e:
             logger.warning(f"Failed to save folder paths: {e}")
 
@@ -126,12 +188,65 @@ class Config:
         # Keep the original mapping: target path -> link path
         self._path_mappings[normalized_target] = normalized_link
         logger.info(f"Added path mapping: {normalized_target} -> {normalized_link}")
+        self._preview_root_paths.update(self._expand_preview_root(normalized_target))
+        self._preview_root_paths.update(self._expand_preview_root(normalized_link))
 
-    def add_route_mapping(self, path: str, route: str):
-        """Add a static route mapping"""
-        normalized_path = os.path.normpath(path).replace(os.sep, '/')
-        self._route_mappings[normalized_path] = route
-        # logger.info(f"Added route mapping: {normalized_path} -> {route}")
+    def _expand_preview_root(self, path: str) -> Set[Path]:
+        """Return normalized ``Path`` objects representing a preview root."""
+
+        roots: Set[Path] = set()
+        if not path:
+            return roots
+
+        try:
+            raw_path = Path(path).expanduser()
+        except Exception:
+            return roots
+
+        if raw_path.is_absolute():
+            roots.add(raw_path)
+
+        try:
+            resolved = raw_path.resolve(strict=False)
+        except RuntimeError:
+            resolved = raw_path.absolute()
+        roots.add(resolved)
+
+        try:
+            real_path = raw_path.resolve()
+        except (FileNotFoundError, RuntimeError):
+            real_path = resolved
+        roots.add(real_path)
+
+        normalized: Set[Path] = set()
+        for candidate in roots:
+            if candidate.is_absolute():
+                normalized.add(candidate)
+            else:
+                try:
+                    normalized.add(candidate.resolve(strict=False))
+                except RuntimeError:
+                    normalized.add(candidate.absolute())
+
+        return normalized
+
+    def _rebuild_preview_roots(self) -> None:
+        """Recompute the cache of directories permitted for previews."""
+
+        preview_roots: Set[Path] = set()
+
+        for root in self.loras_roots or []:
+            preview_roots.update(self._expand_preview_root(root))
+        for root in self.base_models_roots or []:
+            preview_roots.update(self._expand_preview_root(root))
+        for root in self.embeddings_roots or []:
+            preview_roots.update(self._expand_preview_root(root))
+
+        for target, link in self._path_mappings.items():
+            preview_roots.update(self._expand_preview_root(target))
+            preview_roots.update(self._expand_preview_root(link))
+
+        self._preview_root_paths = {path for path in preview_roots if path.is_absolute()}
 
     def map_path_to_link(self, path: str) -> str:
         """Map a target path back to its symbolic link path"""
@@ -155,31 +270,93 @@ class Config:
                 return mapped_path
         return link_path
 
+    def _dedupe_existing_paths(self, raw_paths: Iterable[str]) -> Dict[str, str]:
+        dedup: Dict[str, str] = {}
+        for path in raw_paths:
+            if not isinstance(path, str):
+                continue
+            if not os.path.exists(path):
+                continue
+            real_path = os.path.normpath(os.path.realpath(path)).replace(os.sep, '/')
+            normalized = os.path.normpath(path).replace(os.sep, '/')
+            if real_path not in dedup:
+                dedup[real_path] = normalized
+        return dedup
+
+    def _prepare_lora_paths(self, raw_paths: Iterable[str]) -> List[str]:
+        path_map = self._dedupe_existing_paths(raw_paths)
+        unique_paths = sorted(path_map.values(), key=lambda p: p.lower())
+
+        for original_path in unique_paths:
+            real_path = os.path.normpath(os.path.realpath(original_path)).replace(os.sep, '/')
+            if real_path != original_path:
+                self.add_path_mapping(original_path, real_path)
+
+        return unique_paths
+
+    def _prepare_checkpoint_paths(
+        self, checkpoint_paths: Iterable[str], unet_paths: Iterable[str]
+    ) -> List[str]:
+        checkpoint_map = self._dedupe_existing_paths(checkpoint_paths)
+        unet_map = self._dedupe_existing_paths(unet_paths)
+
+        merged_map: Dict[str, str] = {}
+        for real_path, original in {**checkpoint_map, **unet_map}.items():
+            if real_path not in merged_map:
+                merged_map[real_path] = original
+
+        unique_paths = sorted(merged_map.values(), key=lambda p: p.lower())
+
+        checkpoint_values = set(checkpoint_map.values())
+        unet_values = set(unet_map.values())
+        self.checkpoints_roots = [p for p in unique_paths if p in checkpoint_values]
+        self.unet_roots = [p for p in unique_paths if p in unet_values]
+
+        for original_path in unique_paths:
+            real_path = os.path.normpath(os.path.realpath(original_path)).replace(os.sep, '/')
+            if real_path != original_path:
+                self.add_path_mapping(original_path, real_path)
+
+        return unique_paths
+
+    def _prepare_embedding_paths(self, raw_paths: Iterable[str]) -> List[str]:
+        path_map = self._dedupe_existing_paths(raw_paths)
+        unique_paths = sorted(path_map.values(), key=lambda p: p.lower())
+
+        for original_path in unique_paths:
+            real_path = os.path.normpath(os.path.realpath(original_path)).replace(os.sep, '/')
+            if real_path != original_path:
+                self.add_path_mapping(original_path, real_path)
+
+        return unique_paths
+
+    def _apply_library_paths(self, folder_paths: Mapping[str, Iterable[str]]) -> None:
+        self._path_mappings.clear()
+        self._preview_root_paths = set()
+
+        lora_paths = folder_paths.get('loras', []) or []
+        checkpoint_paths = folder_paths.get('checkpoints', []) or []
+        unet_paths = folder_paths.get('unet', []) or []
+        embedding_paths = folder_paths.get('embeddings', []) or []
+
+        self.loras_roots = self._prepare_lora_paths(lora_paths)
+        self.base_models_roots = self._prepare_checkpoint_paths(checkpoint_paths, unet_paths)
+        self.embeddings_roots = self._prepare_embedding_paths(embedding_paths)
+
+        self._scan_symbolic_links()
+        self._rebuild_preview_roots()
+
     def _init_lora_paths(self) -> List[str]:
         """Initialize and validate LoRA paths from ComfyUI settings"""
         try:
             raw_paths = folder_paths.get_folder_paths("loras")
-            
-            # Normalize and resolve symlinks, store mapping from resolved -> original
-            path_map = {}
-            for path in raw_paths:
-                if os.path.exists(path):
-                    real_path = os.path.normpath(os.path.realpath(path)).replace(os.sep, '/')
-                    path_map[real_path] = path_map.get(real_path, path.replace(os.sep, "/"))  # preserve first seen
-            
-            # Now sort and use only the deduplicated real paths
-            unique_paths = sorted(path_map.values(), key=lambda p: p.lower())
+            unique_paths = self._prepare_lora_paths(raw_paths)
             logger.info("Found LoRA roots:" + ("\n - " + "\n - ".join(unique_paths) if unique_paths else "[]"))
-            
+
             if not unique_paths:
                 logger.warning("No valid loras folders found in ComfyUI configuration")
                 return []
-            
-            for original_path in unique_paths:
-                real_path = os.path.normpath(os.path.realpath(original_path)).replace(os.sep, '/')
-                if real_path != original_path:
-                    self.add_path_mapping(original_path, real_path)
-            
+
             return unique_paths
         except Exception as e:
             logger.warning(f"Error initializing LoRA paths: {e}")
@@ -188,52 +365,17 @@ class Config:
     def _init_checkpoint_paths(self) -> List[str]:
         """Initialize and validate checkpoint paths from ComfyUI settings"""
         try:
-            # Get checkpoint paths from folder_paths
             raw_checkpoint_paths = folder_paths.get_folder_paths("checkpoints")
             raw_unet_paths = folder_paths.get_folder_paths("unet")
-            
-            # Normalize and resolve symlinks for checkpoints, store mapping from resolved -> original
-            checkpoint_map = {}
-            for path in raw_checkpoint_paths:
-                if os.path.exists(path):
-                    real_path = os.path.normpath(os.path.realpath(path)).replace(os.sep, '/')
-                    checkpoint_map[real_path] = checkpoint_map.get(real_path, path.replace(os.sep, "/"))  # preserve first seen
-            
-            # Normalize and resolve symlinks for unet, store mapping from resolved -> original
-            unet_map = {}
-            for path in raw_unet_paths:
-                if os.path.exists(path):
-                    real_path = os.path.normpath(os.path.realpath(path)).replace(os.sep, '/')
-                    unet_map[real_path] = unet_map.get(real_path, path.replace(os.sep, "/"))  # preserve first seen
-            
-            # Merge both maps and deduplicate by real path
-            merged_map = {}
-            for real_path, orig_path in {**checkpoint_map, **unet_map}.items():
-                if real_path not in merged_map:
-                    merged_map[real_path] = orig_path
+            unique_paths = self._prepare_checkpoint_paths(raw_checkpoint_paths, raw_unet_paths)
 
-            # Now sort and use only the deduplicated real paths
-            unique_paths = sorted(merged_map.values(), key=lambda p: p.lower())
-            
-            # Split back into checkpoints and unet roots for class properties
-            self.checkpoints_roots = [p for p in unique_paths if p in checkpoint_map.values()]
-            self.unet_roots = [p for p in unique_paths if p in unet_map.values()]
-            
-            all_paths = unique_paths
-            
-            logger.info("Found checkpoint roots:" + ("\n - " + "\n - ".join(all_paths) if all_paths else "[]"))
-            
-            if not all_paths:
+            logger.info("Found checkpoint roots:" + ("\n - " + "\n - ".join(unique_paths) if unique_paths else "[]"))
+
+            if not unique_paths:
                 logger.warning("No valid checkpoint folders found in ComfyUI configuration")
                 return []
-            
-            # Initialize path mappings
-            for original_path in all_paths:
-                real_path = os.path.normpath(os.path.realpath(original_path)).replace(os.sep, '/')
-                if real_path != original_path:
-                    self.add_path_mapping(original_path, real_path)
-            
-            return all_paths
+
+            return unique_paths
         except Exception as e:
             logger.warning(f"Error initializing checkpoint paths: {e}")
             return []
@@ -242,27 +384,13 @@ class Config:
         """Initialize and validate embedding paths from ComfyUI settings"""
         try:
             raw_paths = folder_paths.get_folder_paths("embeddings")
-            
-            # Normalize and resolve symlinks, store mapping from resolved -> original
-            path_map = {}
-            for path in raw_paths:
-                if os.path.exists(path):
-                    real_path = os.path.normpath(os.path.realpath(path)).replace(os.sep, '/')
-                    path_map[real_path] = path_map.get(real_path, path.replace(os.sep, "/"))  # preserve first seen
-            
-            # Now sort and use only the deduplicated real paths
-            unique_paths = sorted(path_map.values(), key=lambda p: p.lower())
+            unique_paths = self._prepare_embedding_paths(raw_paths)
             logger.info("Found embedding roots:" + ("\n - " + "\n - ".join(unique_paths) if unique_paths else "[]"))
-            
+
             if not unique_paths:
                 logger.warning("No valid embeddings folders found in ComfyUI configuration")
                 return []
-            
-            for original_path in unique_paths:
-                real_path = os.path.normpath(os.path.realpath(original_path)).replace(os.sep, '/')
-                if real_path != original_path:
-                    self.add_path_mapping(original_path, real_path)
-            
+
             return unique_paths
         except Exception as e:
             logger.warning(f"Error initializing embedding paths: {e}")
@@ -271,25 +399,62 @@ class Config:
     def get_preview_static_url(self, preview_path: str) -> str:
         if not preview_path:
             return ""
-        
-        real_path = os.path.realpath(preview_path).replace(os.sep, '/')
-        
-        # Find longest matching path (most specific match)
-        best_match = ""
-        best_route = ""
-        
-        for path, route in self._route_mappings.items():
-            if real_path.startswith(path) and len(path) > len(best_match):
-                best_match = path
-                best_route = route
-        
-        if best_match:
-            relative_path = os.path.relpath(real_path, best_match).replace(os.sep, '/')
-            safe_parts = [urllib.parse.quote(part) for part in relative_path.split('/')]
-            safe_path = '/'.join(safe_parts)
-            return f'{best_route}/{safe_path}'
-        
-        return ""
+
+        normalized = os.path.normpath(preview_path).replace(os.sep, '/')
+        encoded_path = urllib.parse.quote(normalized, safe='')
+        return f'/api/lm/previews?path={encoded_path}'
+
+    def is_preview_path_allowed(self, preview_path: str) -> bool:
+        """Return ``True`` if ``preview_path`` is within an allowed directory."""
+
+        if not preview_path:
+            return False
+
+        try:
+            candidate = Path(preview_path).expanduser().resolve(strict=False)
+        except Exception:
+            return False
+
+        for root in self._preview_root_paths:
+            try:
+                candidate.relative_to(root)
+                return True
+            except ValueError:
+                continue
+
+        return False
+
+    def apply_library_settings(self, library_config: Mapping[str, object]) -> None:
+        """Update runtime paths to match the provided library configuration."""
+        folder_paths = library_config.get('folder_paths') if isinstance(library_config, Mapping) else {}
+        if not isinstance(folder_paths, Mapping):
+            folder_paths = {}
+
+        self._apply_library_paths(folder_paths)
+
+        logger.info(
+            "Applied library settings with %d lora roots, %d checkpoint roots, and %d embedding roots",
+            len(self.loras_roots or []),
+            len(self.base_models_roots or []),
+            len(self.embeddings_roots or []),
+        )
+
+    def get_library_registry_snapshot(self) -> Dict[str, object]:
+        """Return the current library registry and active library name."""
+
+        try:
+            from .services.settings_manager import get_settings_manager
+
+            settings_service = get_settings_manager()
+            libraries = settings_service.get_libraries()
+            active_library = settings_service.get_active_library_name()
+            return {
+                "active_library": active_library,
+                "libraries": libraries,
+            }
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.debug("Failed to collect library registry snapshot: %s", exc)
+            return {"active_library": "", "libraries": {}}
 
 # Global config instance
 config = Config()

py/lora_manager.py

@@ -2,7 +2,6 @@ import asyncio
 import sys
 import os
 import logging
-from pathlib import Path
 from server import PromptServer # type: ignore
 
 from .config import config
@@ -11,17 +10,38 @@ from .routes.recipe_routes import RecipeRoutes
 from .routes.stats_routes import StatsRoutes
 from .routes.update_routes import UpdateRoutes
 from .routes.misc_routes import MiscRoutes
+from .routes.preview_routes import PreviewRoutes
 from .routes.example_images_routes import ExampleImagesRoutes
 from .services.service_registry import ServiceRegistry
-from .services.settings_manager import settings
+from .services.settings_manager import get_settings_manager
 from .utils.example_images_migration import ExampleImagesMigration
 from .services.websocket_manager import ws_manager
+from .services.example_images_cleanup_service import ExampleImagesCleanupService
 
 logger = logging.getLogger(__name__)
 
 # Check if we're in standalone mode
 STANDALONE_MODE = 'nodes' not in sys.modules
 
+
+class _SettingsProxy:
+    def __init__(self):
+        self._manager = None
+
+    def _resolve(self):
+        if self._manager is None:
+            self._manager = get_settings_manager()
+        return self._manager
+
+    def get(self, *args, **kwargs):
+        return self._resolve().get(*args, **kwargs)
+
+    def __getattr__(self, item):
+        return getattr(self._resolve(), item)
+
+
+settings = _SettingsProxy()
+
 class LoraManager:
     """Main entry point for LoRA Manager plugin"""
     
@@ -49,102 +69,12 @@ class LoraManager:
         asyncio_logger = logging.getLogger("asyncio")
         asyncio_logger.addFilter(ConnectionResetFilter())
 
-        added_targets = set()  # Track already added target paths
-        
         # Add static route for example images if the path exists in settings
         example_images_path = settings.get('example_images_path')
         logger.info(f"Example images path: {example_images_path}")
         if example_images_path and os.path.exists(example_images_path):
             app.router.add_static('/example_images_static', example_images_path)
             logger.info(f"Added static route for example images: /example_images_static -> {example_images_path}")
-        
-        # Add static routes for each lora root
-        for idx, root in enumerate(config.loras_roots, start=1):
-            preview_path = f'/loras_static/root{idx}/preview'
-            
-            real_root = root
-            if root in config._path_mappings.values():
-                for target, link in config._path_mappings.items():
-                    if link == root:
-                        real_root = target
-                        break
-            # Add static route for original path
-            app.router.add_static(preview_path, real_root)
-            logger.info(f"Added static route {preview_path} -> {real_root}")
-            
-            # Record route mapping
-            config.add_route_mapping(real_root, preview_path)
-            added_targets.add(real_root)
-        
-        # Add static routes for each checkpoint root
-        for idx, root in enumerate(config.base_models_roots, start=1):
-            preview_path = f'/checkpoints_static/root{idx}/preview'
-            
-            real_root = root
-            if root in config._path_mappings.values():
-                for target, link in config._path_mappings.items():
-                    if link == root:
-                        real_root = target
-                        break
-            # Add static route for original path
-            app.router.add_static(preview_path, real_root)
-            logger.info(f"Added static route {preview_path} -> {real_root}")
-            
-            # Record route mapping
-            config.add_route_mapping(real_root, preview_path)
-            added_targets.add(real_root)
-        
-        # Add static routes for each embedding root
-        for idx, root in enumerate(config.embeddings_roots, start=1):
-            preview_path = f'/embeddings_static/root{idx}/preview'
-            
-            real_root = root
-            if root in config._path_mappings.values():
-                for target, link in config._path_mappings.items():
-                    if link == root:
-                        real_root = target
-                        break
-            # Add static route for original path
-            app.router.add_static(preview_path, real_root)
-            logger.info(f"Added static route {preview_path} -> {real_root}")
-            
-            # Record route mapping
-            config.add_route_mapping(real_root, preview_path)
-            added_targets.add(real_root)
-        
-        # Add static routes for symlink target paths
-        link_idx = {
-            'lora': 1,
-            'checkpoint': 1,
-            'embedding': 1
-        }
-        
-        for target_path, link_path in config._path_mappings.items():
-            if target_path not in added_targets:
-                # Determine if this is a checkpoint, lora, or embedding link based on path
-                is_checkpoint = any(cp_root in link_path for cp_root in config.base_models_roots)
-                is_checkpoint = is_checkpoint or any(cp_root in target_path for cp_root in config.base_models_roots)
-                is_embedding = any(emb_root in link_path for emb_root in config.embeddings_roots)
-                is_embedding = is_embedding or any(emb_root in target_path for emb_root in config.embeddings_roots)
-                
-                if is_checkpoint:
-                    route_path = f'/checkpoints_static/link_{link_idx["checkpoint"]}/preview'
-                    link_idx["checkpoint"] += 1
-                elif is_embedding:
-                    route_path = f'/embeddings_static/link_{link_idx["embedding"]}/preview'
-                    link_idx["embedding"] += 1
-                else:
-                    route_path = f'/loras_static/link_{link_idx["lora"]}/preview'
-                    link_idx["lora"] += 1
-                
-                try:
-                    app.router.add_static(route_path, Path(target_path).resolve(strict=False))
-                    logger.info(f"Added static route for link target {route_path} -> {target_path}")
-                    config.add_route_mapping(target_path, route_path)
-                    added_targets.add(target_path)
-                except Exception as e:
-                    logger.warning(f"Failed to add static route on initialization for {target_path}: {e}")
-                    continue
 
         # Add static route for locales JSON files
         if os.path.exists(config.i18n_path):
@@ -166,7 +96,8 @@ class LoraManager:
         RecipeRoutes.setup_routes(app)
         UpdateRoutes.setup_routes(app)  
         MiscRoutes.setup_routes(app)
-        ExampleImagesRoutes.setup_routes(app)
+        ExampleImagesRoutes.setup_routes(app, ws_manager=ws_manager)
+        PreviewRoutes.setup_routes(app)
         
         # Setup WebSocket routes that are shared across all model types
         app.router.add_get('/ws/fetch-progress', ws_manager.handle_connection)
@@ -190,6 +121,9 @@ class LoraManager:
 
             # Register DownloadManager with ServiceRegistry
             await ServiceRegistry.get_download_manager()
+
+            from .services.metadata_service import initialize_metadata_providers
+            await initialize_metadata_providers()
             
             # Initialize WebSocket manager
             await ServiceRegistry.get_websocket_manager()
@@ -218,7 +152,7 @@ class LoraManager:
                 name='post_init_tasks'
             )
             
-            logger.info("LoRA Manager: All services initialized and background tasks scheduled")
+            logger.debug("LoRA Manager: All services initialized and background tasks scheduled")
                 
         except Exception as e:
             logger.error(f"LoRA Manager: Error initializing services: {e}", exc_info=True)
@@ -346,17 +280,45 @@ class LoraManager:
         
         return deleted_count, size_freed
     
+    @classmethod
+    async def _cleanup_example_images_folders(cls):
+        """Invoke the example images cleanup service for manual execution."""
+        try:
+            service = ExampleImagesCleanupService()
+            result = await service.cleanup_example_image_folders()
+
+            if result.get('success'):
+                logger.debug(
+                    "Manual example images cleanup completed: moved=%s",
+                    result.get('moved_total'),
+                )
+            elif result.get('partial_success'):
+                logger.warning(
+                    "Manual example images cleanup partially succeeded: moved=%s failures=%s",
+                    result.get('moved_total'),
+                    result.get('move_failures'),
+                )
+            else:
+                logger.debug(
+                    "Manual example images cleanup skipped or failed: %s",
+                    result.get('error', 'no changes'),
+                )
+
+            return result
+
+        except Exception as e:  # pragma: no cover - defensive guard
+            logger.error(f"Error during example images cleanup: {e}", exc_info=True)
+            return {
+                'success': False,
+                'error': str(e),
+                'error_code': 'unexpected_error',
+            }
+
     @classmethod
     async def _cleanup(cls, app):
         """Cleanup resources using ServiceRegistry"""
         try:
             logger.info("LoRA Manager: Cleaning up services")
                 
-            # Close CivitaiClient gracefully
-            civitai_client = await ServiceRegistry.get_service("civitai_client")
-            if civitai_client:
-                await civitai_client.close()
-                logger.info("Closed CivitaiClient connection")
-                
         except Exception as e:
             logger.error(f"Error during cleanup: {e}", exc_info=True)

py/metadata_collector/__init__.py

@@ -1,9 +1,7 @@
 import os
-import importlib
-import sys
 
 # Check if running in standalone mode
-standalone_mode = 'nodes' not in sys.modules
+standalone_mode = os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1" or os.environ.get("HF_HUB_DISABLE_TELEMETRY", "0") == "0"
 
 if not standalone_mode:
     from .metadata_hook import MetadataHook

py/metadata_collector/metadata_processor.py

@@ -1,9 +1,9 @@
 import json
-import sys
+import os
 from .constants import IMAGES
 
 # Check if running in standalone mode
-standalone_mode = 'nodes' not in sys.modules
+standalone_mode = os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1" or os.environ.get("HF_HUB_DISABLE_TELEMETRY", "0") == "0"
 
 from .constants import MODELS, PROMPTS, SAMPLING, LORAS, SIZE, IS_SAMPLER
 
@@ -295,7 +295,7 @@ class MetadataProcessor:
             "seed": None,
             "steps": None,
             "cfg_scale": None,
-            "guidance": None,  # Add guidance parameter
+            # "guidance": None,  # Add guidance parameter
             "sampler": None,
             "scheduler": None,
             "checkpoint": None,

py/metadata_collector/node_extractors.py

@@ -666,11 +666,13 @@ NODE_EXTRACTORS = {
     "LoraManagerLoader": LoraLoaderManagerExtractor,
     # Conditioning
     "CLIPTextEncode": CLIPTextEncodeExtractor,
+    "PromptLoraManager": CLIPTextEncodeExtractor,
     "CLIPTextEncodeFlux": CLIPTextEncodeFluxExtractor,  # Add CLIPTextEncodeFlux
     "WAS_Text_to_Conditioning": CLIPTextEncodeExtractor,
     "AdvancedCLIPTextEncode": CLIPTextEncodeExtractor,  # From https://github.com/BlenderNeko/ComfyUI_ADV_CLIP_emb
     "smZ_CLIPTextEncode": CLIPTextEncodeExtractor,  # From https://github.com/shiimizu/ComfyUI_smZNodes
     "CR_ApplyControlNetStack": CR_ApplyControlNetStackExtractor,  # Add CR_ApplyControlNetStack
+    "PCTextEncode": CLIPTextEncodeExtractor,  # From https://github.com/asagi4/comfyui-prompt-control
     # Latent
     "EmptyLatentImage": ImageSizeExtractor,
     # Flux

py/middleware/__init__.py

@@ -0,0 +1 @@
+"""Server middleware modules"""

py/middleware/cache_middleware.py

@@ -0,0 +1,53 @@
+"""Cache control middleware for ComfyUI server"""
+
+from aiohttp import web
+from typing import Callable, Awaitable
+
+# Time in seconds
+ONE_HOUR: int = 3600
+ONE_DAY: int = 86400
+IMG_EXTENSIONS = (
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".ppm",
+    ".bmp",
+    ".pgm",
+    ".tif",
+    ".tiff",
+    ".webp",
+    ".mp4"
+)
+
+
+@web.middleware
+async def cache_control(
+    request: web.Request, handler: Callable[[web.Request], Awaitable[web.Response]]
+) -> web.Response:
+    """Cache control middleware that sets appropriate cache headers based on file type and response status"""
+    response: web.Response = await handler(request)
+
+    if (
+        request.path.endswith(".js")
+        or request.path.endswith(".css")
+        or request.path.endswith("index.json")
+    ):
+        response.headers.setdefault("Cache-Control", "no-cache")
+        return response
+
+    # Early return for non-image files - no cache headers needed
+    if not request.path.lower().endswith(IMG_EXTENSIONS):
+        return response
+
+    # Handle image files
+    if response.status == 404:
+        response.headers.setdefault("Cache-Control", f"public, max-age={ONE_HOUR}")
+    elif response.status in (200, 201, 202, 203, 204, 205, 206, 301, 308):
+        # Success responses and permanent redirects - cache for 1 day
+        response.headers.setdefault("Cache-Control", f"public, max-age={ONE_DAY}")
+    elif response.status in (302, 303, 307):
+        # Temporary redirects - no cache
+        response.headers.setdefault("Cache-Control", "no-cache")
+    # Note: 304 Not Modified falls through - no cache headers set
+
+    return response

py/nodes/lora_loader.py

@@ -1,7 +1,6 @@
 import logging
 import re
 from nodes import LoraLoader
-from comfy.comfy_types import IO # type: ignore
 from ..utils.utils import get_lora_info
 from .utils import FlexibleOptionalInputType, any_type, extract_lora_name, get_loras_list, nunchaku_load_lora
 
@@ -17,7 +16,7 @@ class LoraManagerLoader:
             "required": {
                 "model": ("MODEL",),
                 # "clip": ("CLIP",),
-                "text": (IO.STRING, {
+                "text": ("STRING", {
                     "multiline": True,
                     "pysssss.autocomplete": False, 
                     "dynamicPrompts": True, 
@@ -28,7 +27,7 @@ class LoraManagerLoader:
             "optional": FlexibleOptionalInputType(any_type),
         }
 
-    RETURN_TYPES = ("MODEL", "CLIP", IO.STRING, IO.STRING)
+    RETURN_TYPES = ("MODEL", "CLIP", "STRING", "STRING")
     RETURN_NAMES = ("MODEL", "CLIP", "trigger_words", "loaded_loras")
     FUNCTION = "load_loras"
     
@@ -115,7 +114,7 @@ class LoraManagerLoader:
         formatted_loras = []
         for item in loaded_loras:
             parts = item.split(":")
-            lora_name = parts[0].strip()
+            lora_name = parts[0]
             strength_parts = parts[1].strip().split(",")
             
             if len(strength_parts) > 1:
@@ -141,7 +140,7 @@ class LoraManagerTextLoader:
         return {
             "required": {
                 "model": ("MODEL",),
-                "lora_syntax": (IO.STRING, {
+                "lora_syntax": ("STRING", {
                     "defaultInput": True,
                     "forceInput": True,
                     "tooltip": "Format: <lora:lora_name:strength> separated by spaces or punctuation"
@@ -153,7 +152,7 @@ class LoraManagerTextLoader:
             }
         }
 
-    RETURN_TYPES = ("MODEL", "CLIP", IO.STRING, IO.STRING)
+    RETURN_TYPES = ("MODEL", "CLIP", "STRING", "STRING")
     RETURN_NAMES = ("MODEL", "CLIP", "trigger_words", "loaded_loras")
     FUNCTION = "load_loras_from_text"
     
@@ -165,7 +164,7 @@ class LoraManagerTextLoader:
         
         loras = []
         for match in matches:
-            lora_name = match[0].strip()
+            lora_name = match[0]
             model_strength = float(match[1])
             clip_strength = float(match[2]) if match[2] else model_strength
             

py/nodes/lora_stacker.py

@@ -1,4 +1,3 @@
-from comfy.comfy_types import IO # type: ignore
 import os
 from ..utils.utils import get_lora_info
 from .utils import FlexibleOptionalInputType, any_type, extract_lora_name, get_loras_list
@@ -15,7 +14,7 @@ class LoraStacker:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "text": (IO.STRING, {
+                "text": ("STRING", {
                     "multiline": True, 
                     "pysssss.autocomplete": False, 
                     "dynamicPrompts": True, 
@@ -26,7 +25,7 @@ class LoraStacker:
             "optional": FlexibleOptionalInputType(any_type),
         }
 
-    RETURN_TYPES = ("LORA_STACK", IO.STRING, IO.STRING)
+    RETURN_TYPES = ("LORA_STACK", "STRING", "STRING")
     RETURN_NAMES = ("LORA_STACK", "trigger_words", "active_loras")
     FUNCTION = "stack_loras"
     

py/nodes/prompt.py

@@ -0,0 +1,59 @@
+from typing import Any, Optional
+
+class PromptLoraManager:
+    """Encodes text (and optional trigger words) into CLIP conditioning."""
+
+    NAME = "Prompt (LoraManager)"
+    CATEGORY = "Lora Manager/conditioning"
+    DESCRIPTION = (
+        "Encodes a text prompt using a CLIP model into an embedding that can be used "
+        "to guide the diffusion model towards generating specific images."
+    )
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "text": (
+                    'STRING',
+                    {
+                        "multiline": True,
+                        "pysssss.autocomplete": False, 
+                        "dynamicPrompts": True,
+                        "tooltip": "The text to be encoded.",
+                    },
+                ),
+                "clip": (
+                    'CLIP',
+                    {"tooltip": "The CLIP model used for encoding the text."},
+                ),
+            },
+            "optional": {
+                "trigger_words": (
+                    'STRING',
+                    {
+                        "forceInput": True,
+                        "tooltip": (
+                            "Optional trigger words to prepend to the text before "
+                            "encoding."
+                        )
+                    },
+                )
+            },
+        }
+
+    RETURN_TYPES = ('CONDITIONING', 'STRING',)
+    RETURN_NAMES = ('CONDITIONING', 'PROMPT',)
+    OUTPUT_TOOLTIPS = (
+        "A conditioning containing the embedded text used to guide the diffusion model.",
+    )
+    FUNCTION = "encode"
+
+    def encode(self, text: str, clip: Any, trigger_words: Optional[str] = None):
+        prompt = text
+        if trigger_words:
+            prompt = ", ".join([trigger_words, text])
+
+        from nodes import CLIPTextEncode  # type: ignore
+        conditioning = CLIPTextEncode().encode(clip, prompt)[0]
+        return (conditioning, prompt,)

py/nodes/trigger_word_toggle.py

@@ -1,6 +1,5 @@
 import json
 import re
-from server import PromptServer # type: ignore
 from .utils import FlexibleOptionalInputType, any_type
 import logging
 

py/nodes/wanvideo_lora_select.py

@@ -1,4 +1,3 @@
-from comfy.comfy_types import IO # type: ignore
 import folder_paths # type: ignore
 from ..utils.utils import get_lora_info
 from .utils import FlexibleOptionalInputType, any_type, get_loras_list
@@ -16,7 +15,7 @@ class WanVideoLoraSelect:
             "required": {
                 "low_mem_load": ("BOOLEAN", {"default": False, "tooltip": "Load LORA models with less VRAM usage, slower loading. This affects ALL LoRAs, not just the current ones. No effect if merge_loras is False"}),
                 "merge_loras": ("BOOLEAN", {"default": True, "tooltip": "Merge LoRAs into the model, otherwise they are loaded on the fly. Always disabled for GGUF and scaled fp8 models. This affects ALL LoRAs, not just the current one"}),
-                "text": (IO.STRING, {
+                "text": ("STRING", {
                     "multiline": True, 
                     "pysssss.autocomplete": False, 
                     "dynamicPrompts": True, 
@@ -27,7 +26,7 @@ class WanVideoLoraSelect:
             "optional": FlexibleOptionalInputType(any_type),
         }
 
-    RETURN_TYPES = ("WANVIDLORA", IO.STRING, IO.STRING)
+    RETURN_TYPES = ("WANVIDLORA", "STRING", "STRING")
     RETURN_NAMES = ("lora", "trigger_words", "active_loras")
     FUNCTION = "process_loras"
     

py/nodes/wanvideo_lora_select_from_text.py

@@ -0,0 +1,126 @@
+import folder_paths # type: ignore
+from ..utils.utils import get_lora_info
+from .utils import any_type 
+import logging
+
+# 初始化日志记录器
+logger = logging.getLogger(__name__)
+
+# 定义新节点的类
+class WanVideoLoraSelectFromText:
+    # 节点在UI中显示的名称
+    NAME = "WanVideo Lora Select From Text (LoraManager)"
+    # 节点所属的分类
+    CATEGORY = "Lora Manager/stackers"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "low_mem_load": ("BOOLEAN", {"default": False, "tooltip": "Load LORA models with less VRAM usage, slower loading. This affects ALL LoRAs, not just the current ones. No effect if merge_loras is False"}),
+                "merge_lora": ("BOOLEAN", {"default": True, "tooltip": "Merge LoRAs into the model, otherwise they are loaded on the fly. Always disabled for GGUF and scaled fp8 models. This affects ALL LoRAs, not just the current one"}),
+                "lora_syntax": ("STRING", {
+                    "multiline": True,
+                    "defaultInput": True,
+                    "forceInput": True,
+                    "tooltip": "Connect a TEXT output for LoRA syntax: <lora:name:strength>"
+                }),
+            },
+
+            "optional": {
+                "prev_lora": ("WANVIDLORA",), 
+                "blocks": ("BLOCKS",)        
+            }
+        }
+
+    RETURN_TYPES = ("WANVIDLORA", "STRING", "STRING")
+    RETURN_NAMES = ("lora", "trigger_words", "active_loras")
+
+    FUNCTION = "process_loras_from_syntax"
+    
+    def process_loras_from_syntax(self, lora_syntax, low_mem_load=False, merge_lora=True, **kwargs):
+        text_to_process = lora_syntax
+
+        blocks = kwargs.get('blocks', {})
+        selected_blocks = blocks.get("selected_blocks", {})
+        layer_filter = blocks.get("layer_filter", "")
+
+        loras_list = []
+        all_trigger_words = []
+        active_loras = []
+        
+        prev_lora = kwargs.get('prev_lora', None)
+        if prev_lora is not None:
+            loras_list.extend(prev_lora)
+
+        if not merge_lora:
+            low_mem_load = False
+
+        parts = text_to_process.split('<lora:')
+        for part in parts[1:]:
+            end_index = part.find('>')
+            if end_index == -1:
+                continue
+
+            content = part[:end_index]
+            lora_parts = content.split(':')
+            
+            lora_name_raw = ""
+            model_strength = 1.0
+            clip_strength = 1.0
+
+            if len(lora_parts) == 2:
+                lora_name_raw = lora_parts[0].strip()
+                try:
+                    model_strength = float(lora_parts[1])
+                    clip_strength = model_strength
+                except (ValueError, IndexError):
+                    logger.warning(f"Invalid strength for LoRA '{lora_name_raw}'. Skipping.")
+                    continue
+            elif len(lora_parts) >= 3:
+                lora_name_raw = lora_parts[0].strip()
+                try:
+                    model_strength = float(lora_parts[1])
+                    clip_strength = float(lora_parts[2])
+                except (ValueError, IndexError):
+                    logger.warning(f"Invalid strengths for LoRA '{lora_name_raw}'. Skipping.")
+                    continue
+            else:
+                continue
+
+            lora_path, trigger_words = get_lora_info(lora_name_raw)
+
+            lora_item = {
+                "path": folder_paths.get_full_path("loras", lora_path),
+                "strength": model_strength,
+                "name": lora_path.split(".")[0],
+                "blocks": selected_blocks,
+                "layer_filter": layer_filter,
+                "low_mem_load": low_mem_load,
+                "merge_loras": merge_lora,
+            }
+
+            loras_list.append(lora_item)
+            active_loras.append((lora_name_raw, model_strength, clip_strength))
+            all_trigger_words.extend(trigger_words)
+
+        trigger_words_text = ",, ".join(all_trigger_words) if all_trigger_words else ""
+        
+        formatted_loras = []
+        for name, model_strength, clip_strength in active_loras:
+            if abs(model_strength - clip_strength) > 0.001:
+                formatted_loras.append(f"<lora:{name}:{str(model_strength).strip()}:{str(clip_strength).strip()}>")
+            else:
+                formatted_loras.append(f"<lora:{name}:{str(model_strength).strip()}>")
+                
+        active_loras_text = " ".join(formatted_loras)
+
+        return (loras_list, trigger_words_text, active_loras_text)
+
+NODE_CLASS_MAPPINGS = {
+    "WanVideoLoraSelectFromText": WanVideoLoraSelectFromText
+}
+
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "WanVideoLoraSelectFromText": "WanVideo Lora Select From Text (LoraManager)"
+}

py/recipes/base.py

@@ -55,7 +55,7 @@ class RecipeMetadataParser(ABC):
             # Unpack the tuple to get the actual data
             civitai_info, error_msg = civitai_info_tuple if isinstance(civitai_info_tuple, tuple) else (civitai_info_tuple, None)
             
-            if not civitai_info or civitai_info.get("error") == "Model not found":
+            if not civitai_info or error_msg == "Model not found":
                 # Model not found or deleted
                 lora_entry['isDeleted'] = True
                 lora_entry['thumbnailUrl'] = '/loras_static/images/no-preview.png'

py/recipes/parsers/automatic.py

@@ -6,6 +6,7 @@ import logging
 from typing import Dict, Any
 from ..base import RecipeMetadataParser
 from ..constants import GEN_PARAM_KEYS
+from ...services.metadata_service import get_default_metadata_provider
 
 logger = logging.getLogger(__name__)
 
@@ -30,6 +31,9 @@ class AutomaticMetadataParser(RecipeMetadataParser):
     async def parse_metadata(self, user_comment: str, recipe_scanner=None, civitai_client=None) -> Dict[str, Any]:
         """Parse metadata from Automatic1111 format"""
         try:
+            # Get metadata provider instead of using civitai_client directly
+            metadata_provider = await get_default_metadata_provider()
+            
             # Split on Negative prompt if it exists
             if "Negative prompt:" in user_comment:
                 parts = user_comment.split('Negative prompt:', 1)
@@ -216,9 +220,9 @@ class AutomaticMetadataParser(RecipeMetadataParser):
                         }
                         
                         # Get additional info from Civitai
-                        if civitai_client:
+                        if metadata_provider:
                             try:
-                                civitai_info = await civitai_client.get_model_version_info(resource.get("modelVersionId"))
+                                civitai_info = await metadata_provider.get_model_version_info(resource.get("modelVersionId"))
                                 populated_entry = await self.populate_lora_from_civitai(
                                     lora_entry,
                                     civitai_info,
@@ -271,11 +275,11 @@ class AutomaticMetadataParser(RecipeMetadataParser):
                         }
                         
                         # Try to get info from Civitai
-                        if civitai_client:
+                        if metadata_provider:
                             try:
                                 if lora_hash:
                                     # If we have hash, use it for lookup
-                                    civitai_info = await civitai_client.get_model_by_hash(lora_hash)
+                                    civitai_info = await metadata_provider.get_model_by_hash(lora_hash)
                                 else:
                                     civitai_info = None
                                 

py/recipes/parsers/civitai_image.py

@@ -5,6 +5,7 @@ import logging
 from typing import Dict, Any, Union
 from ..base import RecipeMetadataParser
 from ..constants import GEN_PARAM_KEYS
+from ...services.metadata_service import get_default_metadata_provider
 
 logger = logging.getLogger(__name__)
 
@@ -36,12 +37,15 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
         Args:
             metadata: The metadata from the image (dict)
             recipe_scanner: Optional recipe scanner service
-            civitai_client: Optional Civitai API client
+            civitai_client: Optional Civitai API client (deprecated, use metadata_provider instead)
             
         Returns:
             Dict containing parsed recipe data
         """
         try:
+            # Get metadata provider instead of using civitai_client directly
+            metadata_provider = await get_default_metadata_provider()
+            
             # Initialize result structure
             result = {
                 'base_model': None,
@@ -53,6 +57,14 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
             # Track already added LoRAs to prevent duplicates
             added_loras = {}  # key: model_version_id or hash, value: index in result["loras"]
             
+            # Extract hash information from hashes field for LoRA matching
+            lora_hashes = {}
+            if "hashes" in metadata and isinstance(metadata["hashes"], dict):
+                for key, hash_value in metadata["hashes"].items():
+                    if key.startswith("LORA:"):
+                        lora_name = key.replace("LORA:", "")
+                        lora_hashes[lora_name] = hash_value
+            
             # Extract prompt and negative prompt
             if "prompt" in metadata:
                 result["gen_params"]["prompt"] = metadata["prompt"]
@@ -77,9 +89,9 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
             # Extract base model information - directly if available
             if "baseModel" in metadata:
                 result["base_model"] = metadata["baseModel"]
-            elif "Model hash" in metadata and civitai_client:
+            elif "Model hash" in metadata and metadata_provider:
                 model_hash = metadata["Model hash"]
-                model_info = await civitai_client.get_model_by_hash(model_hash)
+                model_info, error = await metadata_provider.get_model_by_hash(model_hash)
                 if model_info:
                     result["base_model"] = model_info.get("baseModel", "")
             elif "Model" in metadata and isinstance(metadata.get("resources"), list):
@@ -87,8 +99,8 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                 for resource in metadata.get("resources", []):
                     if resource.get("type") == "model" and resource.get("name") == metadata.get("Model"):
                         # This is likely the checkpoint model
-                        if civitai_client and resource.get("hash"):
-                            model_info = await civitai_client.get_model_by_hash(resource.get("hash"))
+                        if metadata_provider and resource.get("hash"):
+                            model_info, error = await metadata_provider.get_model_by_hash(resource.get("hash"))
                             if model_info:
                                 result["base_model"] = model_info.get("baseModel", "")
             
@@ -101,6 +113,10 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                     if resource.get("type", "lora") == "lora":
                         lora_hash = resource.get("hash", "")
                         
+                        # Try to get hash from the hashes field if not present in resource
+                        if not lora_hash and resource.get("name"):
+                            lora_hash = lora_hashes.get(resource["name"], "")
+                        
                         # Skip LoRAs without proper identification (hash or modelVersionId)
                         if not lora_hash and not resource.get("modelVersionId"):
                             logger.debug(f"Skipping LoRA resource '{resource.get('name', 'Unknown')}' - no hash or modelVersionId")
@@ -126,9 +142,9 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                         }
                         
                         # Try to get info from Civitai if hash is available
-                        if lora_entry['hash'] and civitai_client:
+                        if lora_entry['hash'] and metadata_provider:
                             try:
-                                civitai_info = await civitai_client.get_model_by_hash(lora_hash)
+                                civitai_info = await metadata_provider.get_model_by_hash(lora_hash)
                                 
                                 populated_entry = await self.populate_lora_from_civitai(
                                     lora_entry,
@@ -182,14 +198,10 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                     }
                     
                     # Try to get info from Civitai if modelVersionId is available
-                    if version_id and civitai_client:
+                    if version_id and metadata_provider:
                         try:
                             # Use get_model_version_info instead of get_model_version
-                            civitai_info, error = await civitai_client.get_model_version_info(version_id)
-                            
-                            if error:
-                                logger.warning(f"Error getting model version info: {error}")
-                                continue
+                            civitai_info = await metadata_provider.get_model_version_info(version_id)
                             
                             populated_entry = await self.populate_lora_from_civitai(
                                 lora_entry,
@@ -247,35 +259,84 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                         'isDeleted': False
                     }
                     
-                    # If we have a version ID and civitai client, try to get more info
-                    if version_id and civitai_client:
+                    # If we have a version ID and metadata provider, try to get more info
+                    if version_id and metadata_provider:
                         try:
                             # Use get_model_version_info with the version ID
-                            civitai_info, error = await civitai_client.get_model_version_info(version_id)
+                            civitai_info = await metadata_provider.get_model_version_info(version_id)
                             
-                            if error:
-                                logger.warning(f"Error getting model version info: {error}")
-                            else:
-                                populated_entry = await self.populate_lora_from_civitai(
-                                    lora_entry,
-                                    civitai_info,
-                                    recipe_scanner,
-                                    base_model_counts
-                                )
+                            populated_entry = await self.populate_lora_from_civitai(
+                                lora_entry,
+                                civitai_info,
+                                recipe_scanner,
+                                base_model_counts
+                            )
+                            
+                            if populated_entry is None:
+                                continue  # Skip invalid LoRA types
                                 
-                                if populated_entry is None:
-                                    continue  # Skip invalid LoRA types
-                                    
-                                lora_entry = populated_entry
-                                
-                                # Track this LoRA for deduplication
-                                if version_id:
-                                    added_loras[version_id] = len(result["loras"])
+                            lora_entry = populated_entry
+                            
+                            # Track this LoRA for deduplication
+                            if version_id:
+                                added_loras[version_id] = len(result["loras"])
                         except Exception as e:
                             logger.error(f"Error fetching Civitai info for model ID {version_id}: {e}")
                     
                         result["loras"].append(lora_entry)
-            
+
+            # If we found LoRA hashes in the metadata but haven't already
+            # populated entries for them, fall back to creating LoRAs from
+            # the hashes section. Some Civitai image responses only include
+            # LoRA information here without explicit resources entries.
+            for lora_name, lora_hash in lora_hashes.items():
+                if not lora_hash:
+                    continue
+
+                # Skip LoRAs we've already added via resources or other fields
+                if lora_hash in added_loras:
+                    continue
+
+                lora_entry = {
+                    'name': lora_name,
+                    'type': "lora",
+                    'weight': 1.0,
+                    'hash': lora_hash,
+                    'existsLocally': False,
+                    'localPath': None,
+                    'file_name': lora_name,
+                    'thumbnailUrl': '/loras_static/images/no-preview.png',
+                    'baseModel': '',
+                    'size': 0,
+                    'downloadUrl': '',
+                    'isDeleted': False
+                }
+
+                if metadata_provider:
+                    try:
+                        civitai_info = await metadata_provider.get_model_by_hash(lora_hash)
+
+                        populated_entry = await self.populate_lora_from_civitai(
+                            lora_entry,
+                            civitai_info,
+                            recipe_scanner,
+                            base_model_counts,
+                            lora_hash
+                        )
+
+                        if populated_entry is None:
+                            continue
+
+                        lora_entry = populated_entry
+
+                        if 'id' in lora_entry and lora_entry['id']:
+                            added_loras[str(lora_entry['id'])] = len(result["loras"])
+                    except Exception as e:
+                        logger.error(f"Error fetching Civitai info for LoRA hash {lora_hash}: {e}")
+
+                added_loras[lora_hash] = len(result["loras"])
+                result["loras"].append(lora_entry)
+
             # Check for LoRA info in the format "Lora_0 Model hash", "Lora_0 Model name", etc.
             lora_index = 0
             while f"Lora_{lora_index} Model hash" in metadata and f"Lora_{lora_index} Model name" in metadata:
@@ -304,9 +365,9 @@ class CivitaiApiMetadataParser(RecipeMetadataParser):
                 }
                 
                 # Try to get info from Civitai if hash is available
-                if lora_entry['hash'] and civitai_client:
+                if lora_entry['hash'] and metadata_provider:
                     try:
-                        civitai_info = await civitai_client.get_model_by_hash(lora_hash)
+                        civitai_info = await metadata_provider.get_model_by_hash(lora_hash)
                         
                         populated_entry = await self.populate_lora_from_civitai(
                             lora_entry,

py/recipes/parsers/comfy.py

@@ -6,6 +6,7 @@ import logging
 from typing import Dict, Any
 from ..base import RecipeMetadataParser
 from ..constants import GEN_PARAM_KEYS
+from ...services.metadata_service import get_default_metadata_provider
 
 logger = logging.getLogger(__name__)
 
@@ -26,6 +27,9 @@ class ComfyMetadataParser(RecipeMetadataParser):
     async def parse_metadata(self, user_comment: str, recipe_scanner=None, civitai_client=None) -> Dict[str, Any]:
         """Parse metadata from Civitai ComfyUI metadata format"""
         try:
+            # Get metadata provider instead of using civitai_client directly
+            metadata_provider = await get_default_metadata_provider()
+            
             data = json.loads(user_comment)
             loras = []
             
@@ -73,10 +77,10 @@ class ComfyMetadataParser(RecipeMetadataParser):
                     'isDeleted': False
                 }
                 
-                # Get additional info from Civitai if client is available
-                if civitai_client:
+                # Get additional info from Civitai if metadata provider is available
+                if metadata_provider:
                     try:
-                        civitai_info_tuple = await civitai_client.get_model_version_info(model_version_id)
+                        civitai_info_tuple = await metadata_provider.get_model_version_info(model_version_id)
                         # Populate lora entry with Civitai info
                         populated_entry = await self.populate_lora_from_civitai(
                             lora_entry, 
@@ -116,9 +120,9 @@ class ComfyMetadataParser(RecipeMetadataParser):
                         }
                         
                         # Get additional checkpoint info from Civitai
-                        if civitai_client:
+                        if metadata_provider:
                             try:
-                                civitai_info_tuple = await civitai_client.get_model_version_info(checkpoint_version_id)
+                                civitai_info_tuple = await metadata_provider.get_model_version_info(checkpoint_version_id)
                                 civitai_info, _ = civitai_info_tuple if isinstance(civitai_info_tuple, tuple) else (civitai_info_tuple, None)
                                 # Populate checkpoint with Civitai info
                                 checkpoint = await self.populate_checkpoint_from_civitai(checkpoint, civitai_info)

py/recipes/parsers/meta_format.py

@@ -5,6 +5,7 @@ import logging
 from typing import Dict, Any
 from ..base import RecipeMetadataParser
 from ..constants import GEN_PARAM_KEYS
+from ...services.metadata_service import get_default_metadata_provider
 
 logger = logging.getLogger(__name__)
 
@@ -18,8 +19,11 @@ class MetaFormatParser(RecipeMetadataParser):
         return re.search(self.METADATA_MARKER, user_comment, re.IGNORECASE | re.DOTALL) is not None
     
     async def parse_metadata(self, user_comment: str, recipe_scanner=None, civitai_client=None) -> Dict[str, Any]:
-        """Parse metadata from images with meta format metadata"""
+        """Parse metadata from images with meta format metadata (Lora_N Model hash format)"""
         try:
+            # Get metadata provider instead of using civitai_client directly
+            metadata_provider = await get_default_metadata_provider()
+            
             # Extract prompt and negative prompt
             parts = user_comment.split('Negative prompt:', 1)
             prompt = parts[0].strip()
@@ -122,9 +126,9 @@ class MetaFormatParser(RecipeMetadataParser):
                 }
                 
                 # Get info from Civitai by hash if available
-                if civitai_client and hash_value:
+                if metadata_provider and hash_value:
                     try:
-                        civitai_info = await civitai_client.get_model_by_hash(hash_value)
+                        civitai_info = await metadata_provider.get_model_by_hash(hash_value)
                         # Populate lora entry with Civitai info
                         populated_entry = await self.populate_lora_from_civitai(
                             lora_entry, 

py/recipes/parsers/recipe_format.py

@@ -7,6 +7,7 @@ from typing import Dict, Any
 from ...config import config
 from ..base import RecipeMetadataParser
 from ..constants import GEN_PARAM_KEYS
+from ...services.metadata_service import get_default_metadata_provider
 
 logger = logging.getLogger(__name__)
 
@@ -23,6 +24,9 @@ class RecipeFormatParser(RecipeMetadataParser):
     async def parse_metadata(self, user_comment: str, recipe_scanner=None, civitai_client=None) -> Dict[str, Any]:
         """Parse metadata from images with dedicated recipe metadata format"""
         try:
+            # Get metadata provider instead of using civitai_client directly
+            metadata_provider = await get_default_metadata_provider()
+            
             # Extract recipe metadata from user comment
             try:
                 # Look for recipe metadata section
@@ -71,9 +75,9 @@ class RecipeFormatParser(RecipeMetadataParser):
                         lora_entry['localPath'] = None
                         
                         # Try to get additional info from Civitai if we have a model version ID
-                        if lora.get('modelVersionId') and civitai_client:
+                        if lora.get('modelVersionId') and metadata_provider:
                             try:
-                                civitai_info_tuple = await civitai_client.get_model_version_info(lora['modelVersionId'])
+                                civitai_info_tuple = await metadata_provider.get_model_version_info(lora['modelVersionId'])
                                 # Populate lora entry with Civitai info
                                 populated_entry = await self.populate_lora_from_civitai(
                                     lora_entry, 

py/routes/base_recipe_routes.py

@@ -0,0 +1,217 @@
+"""Base infrastructure shared across recipe routes."""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Callable, Mapping
+
+import jinja2
+from aiohttp import web
+
+from ..config import config
+from ..recipes import RecipeParserFactory
+from ..services.downloader import get_downloader
+from ..services.recipes import (
+    RecipeAnalysisService,
+    RecipePersistenceService,
+    RecipeSharingService,
+)
+from ..services.server_i18n import server_i18n
+from ..services.service_registry import ServiceRegistry
+from ..services.settings_manager import get_settings_manager
+from ..utils.constants import CARD_PREVIEW_WIDTH
+from ..utils.exif_utils import ExifUtils
+from .handlers.recipe_handlers import (
+    RecipeAnalysisHandler,
+    RecipeHandlerSet,
+    RecipeListingHandler,
+    RecipeManagementHandler,
+    RecipePageView,
+    RecipeQueryHandler,
+    RecipeSharingHandler,
+)
+from .recipe_route_registrar import ROUTE_DEFINITIONS
+
+logger = logging.getLogger(__name__)
+
+
+class BaseRecipeRoutes:
+    """Common dependency and startup wiring for recipe routes."""
+
+    _HANDLER_NAMES: tuple[str, ...] = tuple(
+        definition.handler_name for definition in ROUTE_DEFINITIONS
+    )
+
+    template_name: str = "recipes.html"
+
+    def __init__(self) -> None:
+        self.recipe_scanner = None
+        self.lora_scanner = None
+        self.civitai_client = None
+        self.settings = get_settings_manager()
+        self.server_i18n = server_i18n
+        self.template_env = jinja2.Environment(
+            loader=jinja2.FileSystemLoader(config.templates_path),
+            autoescape=True,
+        )
+
+        self._i18n_registered = False
+        self._startup_hooks_registered = False
+        self._handler_set: RecipeHandlerSet | None = None
+        self._handler_mapping: dict[str, Callable] | None = None
+
+    async def attach_dependencies(self, app: web.Application | None = None) -> None:
+        """Resolve shared services from the registry."""
+
+        await self._ensure_services()
+        self._ensure_i18n_filter()
+
+    async def ensure_dependencies_ready(self) -> None:
+        """Ensure dependencies are available for request handlers."""
+
+        if self.recipe_scanner is None or self.civitai_client is None:
+            await self.attach_dependencies()
+
+    def register_startup_hooks(self, app: web.Application) -> None:
+        """Register startup hooks once for dependency wiring."""
+
+        if self._startup_hooks_registered:
+            return
+
+        app.on_startup.append(self.attach_dependencies)
+        app.on_startup.append(self.prewarm_cache)
+        self._startup_hooks_registered = True
+
+    async def prewarm_cache(self, app: web.Application | None = None) -> None:
+        """Pre-load recipe and LoRA caches on startup."""
+
+        try:
+            await self.attach_dependencies(app)
+
+            if self.lora_scanner is not None:
+                await self.lora_scanner.get_cached_data()
+                hash_index = getattr(self.lora_scanner, "_hash_index", None)
+                if hash_index is not None and hasattr(hash_index, "_hash_to_path"):
+                    _ = len(hash_index._hash_to_path)
+
+            if self.recipe_scanner is not None:
+                await self.recipe_scanner.get_cached_data(force_refresh=True)
+        except Exception as exc:
+            logger.error("Error pre-warming recipe cache: %s", exc, exc_info=True)
+
+    def to_route_mapping(self) -> Mapping[str, Callable]:
+        """Return a mapping of handler name to coroutine for registrar binding."""
+
+        if self._handler_mapping is None:
+            handler_set = self._create_handler_set()
+            self._handler_set = handler_set
+            self._handler_mapping = handler_set.to_route_mapping()
+        return self._handler_mapping
+
+    # Internal helpers -------------------------------------------------
+
+    async def _ensure_services(self) -> None:
+        if self.recipe_scanner is None:
+            self.recipe_scanner = await ServiceRegistry.get_recipe_scanner()
+            self.lora_scanner = getattr(self.recipe_scanner, "_lora_scanner", None)
+
+        if self.civitai_client is None:
+            self.civitai_client = await ServiceRegistry.get_civitai_client()
+
+    def _ensure_i18n_filter(self) -> None:
+        if not self._i18n_registered:
+            self.template_env.filters["t"] = self.server_i18n.create_template_filter()
+            self._i18n_registered = True
+
+    def get_handler_owner(self):
+        """Return the object supplying bound handler coroutines."""
+
+        if self._handler_set is None:
+            self._handler_set = self._create_handler_set()
+        return self._handler_set
+
+    def _create_handler_set(self) -> RecipeHandlerSet:
+        recipe_scanner_getter = lambda: self.recipe_scanner
+        civitai_client_getter = lambda: self.civitai_client
+
+        standalone_mode = os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1" or os.environ.get("HF_HUB_DISABLE_TELEMETRY", "0") == "0"
+        if not standalone_mode:
+            from ..metadata_collector import get_metadata  # type: ignore[import-not-found]
+            from ..metadata_collector.metadata_processor import (  # type: ignore[import-not-found]
+                MetadataProcessor,
+            )
+            from ..metadata_collector.metadata_registry import (  # type: ignore[import-not-found]
+                MetadataRegistry,
+            )
+        else:  # pragma: no cover - optional dependency path
+            get_metadata = None  # type: ignore[assignment]
+            MetadataProcessor = None  # type: ignore[assignment]
+            MetadataRegistry = None  # type: ignore[assignment]
+
+        analysis_service = RecipeAnalysisService(
+            exif_utils=ExifUtils,
+            recipe_parser_factory=RecipeParserFactory,
+            downloader_factory=get_downloader,
+            metadata_collector=get_metadata,
+            metadata_processor_cls=MetadataProcessor,
+            metadata_registry_cls=MetadataRegistry,
+            standalone_mode=standalone_mode,
+            logger=logger,
+        )
+        persistence_service = RecipePersistenceService(
+            exif_utils=ExifUtils,
+            card_preview_width=CARD_PREVIEW_WIDTH,
+            logger=logger,
+        )
+        sharing_service = RecipeSharingService(logger=logger)
+
+        page_view = RecipePageView(
+            ensure_dependencies_ready=self.ensure_dependencies_ready,
+            settings_service=self.settings,
+            server_i18n=self.server_i18n,
+            template_env=self.template_env,
+            template_name=self.template_name,
+            recipe_scanner_getter=recipe_scanner_getter,
+            logger=logger,
+        )
+        listing = RecipeListingHandler(
+            ensure_dependencies_ready=self.ensure_dependencies_ready,
+            recipe_scanner_getter=recipe_scanner_getter,
+            logger=logger,
+        )
+        query = RecipeQueryHandler(
+            ensure_dependencies_ready=self.ensure_dependencies_ready,
+            recipe_scanner_getter=recipe_scanner_getter,
+            format_recipe_file_url=listing.format_recipe_file_url,
+            logger=logger,
+        )
+        management = RecipeManagementHandler(
+            ensure_dependencies_ready=self.ensure_dependencies_ready,
+            recipe_scanner_getter=recipe_scanner_getter,
+            logger=logger,
+            persistence_service=persistence_service,
+            analysis_service=analysis_service,
+        )
+        analysis = RecipeAnalysisHandler(
+            ensure_dependencies_ready=self.ensure_dependencies_ready,
+            recipe_scanner_getter=recipe_scanner_getter,
+            civitai_client_getter=civitai_client_getter,
+            logger=logger,
+            analysis_service=analysis_service,
+        )
+        sharing = RecipeSharingHandler(
+            ensure_dependencies_ready=self.ensure_dependencies_ready,
+            recipe_scanner_getter=recipe_scanner_getter,
+            logger=logger,
+            sharing_service=sharing_service,
+        )
+
+        return RecipeHandlerSet(
+            page_view=page_view,
+            listing=listing,
+            query=query,
+            management=management,
+            analysis=analysis,
+            sharing=sharing,
+        )
+

py/routes/checkpoint_routes.py

@@ -2,6 +2,7 @@ import logging
 from aiohttp import web
 
 from .base_model_routes import BaseModelRoutes
+from .model_route_registrar import ModelRouteRegistrar
 from ..services.checkpoint_service import CheckpointService
 from ..services.service_registry import ServiceRegistry
 from ..config import config
@@ -13,19 +14,18 @@ class CheckpointRoutes(BaseModelRoutes):
     
     def __init__(self):
         """Initialize Checkpoint routes with Checkpoint service"""
-        # Service will be initialized later via setup_routes
-        self.service = None
-        self.civitai_client = None
+        super().__init__()
         self.template_name = "checkpoints.html"
     
     async def initialize_services(self):
         """Initialize services from ServiceRegistry"""
         checkpoint_scanner = await ServiceRegistry.get_checkpoint_scanner()
-        self.service = CheckpointService(checkpoint_scanner)
-        self.civitai_client = await ServiceRegistry.get_civitai_client()
-        
-        # Initialize parent with the service
-        super().__init__(self.service)
+        update_service = await ServiceRegistry.get_model_update_service()
+        self.service = CheckpointService(checkpoint_scanner, update_service=update_service)
+        self.set_model_update_service(update_service)
+
+        # Attach service dependencies
+        self.attach_service(self.service)
     
     def setup_routes(self, app: web.Application):
         """Setup Checkpoint routes"""
@@ -35,17 +35,22 @@ class CheckpointRoutes(BaseModelRoutes):
         # Setup common routes with 'checkpoints' prefix (includes page route)
         super().setup_routes(app, 'checkpoints')
     
-    def setup_specific_routes(self, app: web.Application, prefix: str):
+    def setup_specific_routes(self, registrar: ModelRouteRegistrar, prefix: str):
         """Setup Checkpoint-specific routes"""
-        # Checkpoint-specific CivitAI integration
-        app.router.add_get(f'/api/{prefix}/civitai/versions/{{model_id}}', self.get_civitai_versions_checkpoint)
-        
         # Checkpoint info by name
-        app.router.add_get(f'/api/{prefix}/info/{{name}}', self.get_checkpoint_info)
-        
+        registrar.add_prefixed_route('GET', '/api/lm/{prefix}/info/{name}', prefix, self.get_checkpoint_info)
+
         # Checkpoint roots and Unet roots
-        app.router.add_get(f'/api/{prefix}/checkpoints_roots', self.get_checkpoints_roots)
-        app.router.add_get(f'/api/{prefix}/unet_roots', self.get_unet_roots)
+        registrar.add_prefixed_route('GET', '/api/lm/{prefix}/checkpoints_roots', prefix, self.get_checkpoints_roots)
+        registrar.add_prefixed_route('GET', '/api/lm/{prefix}/unet_roots', prefix, self.get_unet_roots)
+    
+    def _validate_civitai_model_type(self, model_type: str) -> bool:
+        """Validate CivitAI model type for Checkpoint"""
+        return model_type.lower() == 'checkpoint'
+    
+    def _get_expected_model_types(self) -> str:
+        """Get expected model types string for error messages"""
+        return "Checkpoint"
     
     async def get_checkpoint_info(self, request: web.Request) -> web.Response:
         """Get detailed information for a specific checkpoint by name"""
@@ -62,53 +67,6 @@ class CheckpointRoutes(BaseModelRoutes):
             logger.error(f"Error in get_checkpoint_info: {e}", exc_info=True)
             return web.json_response({"error": str(e)}, status=500)
     
-    async def get_civitai_versions_checkpoint(self, request: web.Request) -> web.Response:
-        """Get available versions for a Civitai checkpoint model with local availability info"""
-        try:
-            model_id = request.match_info['model_id']
-            response = await self.civitai_client.get_model_versions(model_id)
-            if not response or not response.get('modelVersions'):
-                return web.Response(status=404, text="Model not found")
-            
-            versions = response.get('modelVersions', [])
-            model_type = response.get('type', '')
-            
-            # Check model type - should be Checkpoint
-            if model_type.lower() != 'checkpoint':
-                return web.json_response({
-                    'error': f"Model type mismatch. Expected Checkpoint, got {model_type}"
-                }, status=400)
-            
-            # Check local availability for each version
-            for version in versions:
-                # Find the primary model file (type="Model" and primary=true) in the files list
-                model_file = next((file for file in version.get('files', []) 
-                                  if file.get('type') == 'Model' and file.get('primary') == True), None)
-                
-                # If no primary file found, try to find any model file
-                if not model_file:
-                    model_file = next((file for file in version.get('files', []) 
-                                      if file.get('type') == 'Model'), None)
-                
-                if model_file:
-                    sha256 = model_file.get('hashes', {}).get('SHA256')
-                    if sha256:
-                        # Set existsLocally and localPath at the version level
-                        version['existsLocally'] = self.service.has_hash(sha256)
-                        if version['existsLocally']:
-                            version['localPath'] = self.service.get_path_by_hash(sha256)
-                        
-                        # Also set the model file size at the version level for easier access
-                        version['modelSizeKB'] = model_file.get('sizeKB')
-                else:
-                    # No model file found in this version
-                    version['existsLocally'] = False
-                    
-            return web.json_response(versions)
-        except Exception as e:
-            logger.error(f"Error fetching checkpoint model versions: {e}")
-            return web.Response(status=500, text=str(e))
-    
     async def get_checkpoints_roots(self, request: web.Request) -> web.Response:
         """Return the list of checkpoint roots from config"""
         try:
@@ -137,4 +95,4 @@ class CheckpointRoutes(BaseModelRoutes):
             return web.json_response({
                 "success": False,
                 "error": str(e)
-            }, status=500)
+            }, status=500)

py/routes/embedding_routes.py

@@ -2,6 +2,7 @@ import logging
 from aiohttp import web
 
 from .base_model_routes import BaseModelRoutes
+from .model_route_registrar import ModelRouteRegistrar
 from ..services.embedding_service import EmbeddingService
 from ..services.service_registry import ServiceRegistry
 
@@ -12,19 +13,18 @@ class EmbeddingRoutes(BaseModelRoutes):
     
     def __init__(self):
         """Initialize Embedding routes with Embedding service"""
-        # Service will be initialized later via setup_routes
-        self.service = None
-        self.civitai_client = None
+        super().__init__()
         self.template_name = "embeddings.html"
     
     async def initialize_services(self):
         """Initialize services from ServiceRegistry"""
         embedding_scanner = await ServiceRegistry.get_embedding_scanner()
-        self.service = EmbeddingService(embedding_scanner)
-        self.civitai_client = await ServiceRegistry.get_civitai_client()
-        
-        # Initialize parent with the service
-        super().__init__(self.service)
+        update_service = await ServiceRegistry.get_model_update_service()
+        self.service = EmbeddingService(embedding_scanner, update_service=update_service)
+        self.set_model_update_service(update_service)
+
+        # Attach service dependencies
+        self.attach_service(self.service)
     
     def setup_routes(self, app: web.Application):
         """Setup Embedding routes"""
@@ -34,13 +34,18 @@ class EmbeddingRoutes(BaseModelRoutes):
         # Setup common routes with 'embeddings' prefix (includes page route)
         super().setup_routes(app, 'embeddings')
     
-    def setup_specific_routes(self, app: web.Application, prefix: str):
+    def setup_specific_routes(self, registrar: ModelRouteRegistrar, prefix: str):
         """Setup Embedding-specific routes"""
-        # Embedding-specific CivitAI integration
-        app.router.add_get(f'/api/{prefix}/civitai/versions/{{model_id}}', self.get_civitai_versions_embedding)
-        
         # Embedding info by name
-        app.router.add_get(f'/api/{prefix}/info/{{name}}', self.get_embedding_info)
+        registrar.add_prefixed_route('GET', '/api/lm/{prefix}/info/{name}', prefix, self.get_embedding_info)
+    
+    def _validate_civitai_model_type(self, model_type: str) -> bool:
+        """Validate CivitAI model type for Embedding"""
+        return model_type.lower() == 'textualinversion'
+    
+    def _get_expected_model_types(self) -> str:
+        """Get expected model types string for error messages"""
+        return "TextualInversion"
     
     async def get_embedding_info(self, request: web.Request) -> web.Response:
         """Get detailed information for a specific embedding by name"""
@@ -56,50 +61,3 @@ class EmbeddingRoutes(BaseModelRoutes):
         except Exception as e:
             logger.error(f"Error in get_embedding_info: {e}", exc_info=True)
             return web.json_response({"error": str(e)}, status=500)
-    
-    async def get_civitai_versions_embedding(self, request: web.Request) -> web.Response:
-        """Get available versions for a Civitai embedding model with local availability info"""
-        try:
-            model_id = request.match_info['model_id']
-            response = await self.civitai_client.get_model_versions(model_id)
-            if not response or not response.get('modelVersions'):
-                return web.Response(status=404, text="Model not found")
-            
-            versions = response.get('modelVersions', [])
-            model_type = response.get('type', '')
-            
-            # Check model type - should be TextualInversion (Embedding)
-            if model_type.lower() not in ['textualinversion', 'embedding']:
-                return web.json_response({
-                    'error': f"Model type mismatch. Expected TextualInversion/Embedding, got {model_type}"
-                }, status=400)
-            
-            # Check local availability for each version
-            for version in versions:
-                # Find the primary model file (type="Model" and primary=true) in the files list
-                model_file = next((file for file in version.get('files', []) 
-                                  if file.get('type') == 'Model' and file.get('primary') == True), None)
-                
-                # If no primary file found, try to find any model file
-                if not model_file:
-                    model_file = next((file for file in version.get('files', []) 
-                                      if file.get('type') == 'Model'), None)
-                
-                if model_file:
-                    sha256 = model_file.get('hashes', {}).get('SHA256')
-                    if sha256:
-                        # Set existsLocally and localPath at the version level
-                        version['existsLocally'] = self.service.has_hash(sha256)
-                        if version['existsLocally']:
-                            version['localPath'] = self.service.get_path_by_hash(sha256)
-                        
-                        # Also set the model file size at the version level for easier access
-                        version['modelSizeKB'] = model_file.get('sizeKB')
-                else:
-                    # No model file found in this version
-                    version['existsLocally'] = False
-                    
-            return web.json_response(versions)
-        except Exception as e:
-            logger.error(f"Error fetching embedding model versions: {e}")
-            return web.Response(status=500, text=str(e))

py/routes/example_images_route_registrar.py

@@ -0,0 +1,63 @@
+"""Route registrar for example image endpoints."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, Mapping
+
+from aiohttp import web
+
+
+@dataclass(frozen=True)
+class RouteDefinition:
+    """Declarative configuration for a HTTP route."""
+
+    method: str
+    path: str
+    handler_name: str
+
+
+ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
+    RouteDefinition("POST", "/api/lm/download-example-images", "download_example_images"),
+    RouteDefinition("POST", "/api/lm/import-example-images", "import_example_images"),
+    RouteDefinition("GET", "/api/lm/example-images-status", "get_example_images_status"),
+    RouteDefinition("POST", "/api/lm/pause-example-images", "pause_example_images"),
+    RouteDefinition("POST", "/api/lm/resume-example-images", "resume_example_images"),
+    RouteDefinition("POST", "/api/lm/stop-example-images", "stop_example_images"),
+    RouteDefinition("POST", "/api/lm/open-example-images-folder", "open_example_images_folder"),
+    RouteDefinition("GET", "/api/lm/example-image-files", "get_example_image_files"),
+    RouteDefinition("GET", "/api/lm/has-example-images", "has_example_images"),
+    RouteDefinition("POST", "/api/lm/delete-example-image", "delete_example_image"),
+    RouteDefinition("POST", "/api/lm/force-download-example-images", "force_download_example_images"),
+    RouteDefinition("POST", "/api/lm/cleanup-example-image-folders", "cleanup_example_image_folders"),
+)
+
+
+class ExampleImagesRouteRegistrar:
+    """Bind declarative example image routes to an aiohttp router."""
+
+    _METHOD_MAP = {
+        "GET": "add_get",
+        "POST": "add_post",
+        "PUT": "add_put",
+        "DELETE": "add_delete",
+    }
+
+    def __init__(self, app: web.Application) -> None:
+        self._app = app
+
+    def register_routes(
+        self,
+        handler_lookup: Mapping[str, Callable[[web.Request], object]],
+        *,
+        definitions: Iterable[RouteDefinition] = ROUTE_DEFINITIONS,
+    ) -> None:
+        """Register each route definition using the supplied handlers."""
+
+        for definition in definitions:
+            handler = handler_lookup[definition.handler_name]
+            self._bind_route(definition.method, definition.path, handler)
+
+    def _bind_route(self, method: str, path: str, handler: Callable[[web.Request], object]) -> None:
+        add_method_name = self._METHOD_MAP[method.upper()]
+        add_method = getattr(self._app.router, add_method_name)
+        add_method(path, handler)

py/routes/example_images_routes.py

@@ -1,74 +1,88 @@
+from __future__ import annotations
+
 import logging
-from ..utils.example_images_download_manager import DownloadManager
-from ..utils.example_images_processor import ExampleImagesProcessor
+from typing import Callable, Mapping
+
+from aiohttp import web
+
+from .example_images_route_registrar import ExampleImagesRouteRegistrar
+from .handlers.example_images_handlers import (
+    ExampleImagesDownloadHandler,
+    ExampleImagesFileHandler,
+    ExampleImagesHandlerSet,
+    ExampleImagesManagementHandler,
+)
+from ..services.use_cases.example_images import (
+    DownloadExampleImagesUseCase,
+    ImportExampleImagesUseCase,
+)
+from ..utils.example_images_download_manager import (
+    DownloadManager,
+    get_default_download_manager,
+)
 from ..utils.example_images_file_manager import ExampleImagesFileManager
-from ..services.websocket_manager import ws_manager
+from ..utils.example_images_processor import ExampleImagesProcessor
+from ..services.example_images_cleanup_service import ExampleImagesCleanupService
 
 logger = logging.getLogger(__name__)
 
+
 class ExampleImagesRoutes:
-    """Routes for example images related functionality"""
-    
-    @staticmethod
-    def setup_routes(app):
-        """Register example images routes"""
-        app.router.add_post('/api/download-example-images', ExampleImagesRoutes.download_example_images)
-        app.router.add_post('/api/import-example-images', ExampleImagesRoutes.import_example_images)
-        app.router.add_get('/api/example-images-status', ExampleImagesRoutes.get_example_images_status)
-        app.router.add_post('/api/pause-example-images', ExampleImagesRoutes.pause_example_images)
-        app.router.add_post('/api/resume-example-images', ExampleImagesRoutes.resume_example_images)
-        app.router.add_post('/api/open-example-images-folder', ExampleImagesRoutes.open_example_images_folder)
-        app.router.add_get('/api/example-image-files', ExampleImagesRoutes.get_example_image_files)
-        app.router.add_get('/api/has-example-images', ExampleImagesRoutes.has_example_images)
-        app.router.add_post('/api/delete-example-image', ExampleImagesRoutes.delete_example_image)
-        app.router.add_post('/api/force-download-example-images', ExampleImagesRoutes.force_download_example_images)
+    """Route controller for example image endpoints."""
 
-    @staticmethod
-    async def download_example_images(request):
-        """Download example images for models from Civitai"""
-        return await DownloadManager.start_download(request)
+    def __init__(
+        self,
+        *,
+        ws_manager,
+        download_manager: DownloadManager | None = None,
+        processor=ExampleImagesProcessor,
+        file_manager=ExampleImagesFileManager,
+        cleanup_service: ExampleImagesCleanupService | None = None,
+    ) -> None:
+        if ws_manager is None:
+            raise ValueError("ws_manager is required")
+        self._download_manager = download_manager or get_default_download_manager(ws_manager)
+        self._processor = processor
+        self._file_manager = file_manager
+        self._cleanup_service = cleanup_service or ExampleImagesCleanupService()
+        self._handler_set: ExampleImagesHandlerSet | None = None
+        self._handler_mapping: Mapping[str, Callable[[web.Request], web.StreamResponse]] | None = None
 
-    @staticmethod
-    async def get_example_images_status(request):
-        """Get the current status of example images download"""
-        return await DownloadManager.get_status(request)
+    @classmethod
+    def setup_routes(cls, app: web.Application, *, ws_manager) -> None:
+        """Register routes on the given aiohttp application using default wiring."""
 
-    @staticmethod
-    async def pause_example_images(request):
-        """Pause the example images download"""
-        return await DownloadManager.pause_download(request)
+        controller = cls(ws_manager=ws_manager)
+        controller.register(app)
 
-    @staticmethod
-    async def resume_example_images(request):
-        """Resume the example images download"""
-        return await DownloadManager.resume_download(request)
-        
-    @staticmethod
-    async def open_example_images_folder(request):
-        """Open the example images folder for a specific model"""
-        return await ExampleImagesFileManager.open_folder(request)
+    def register(self, app: web.Application) -> None:
+        """Bind the controller's handlers to the aiohttp router."""
 
-    @staticmethod
-    async def get_example_image_files(request):
-        """Get list of example image files for a specific model"""
-        return await ExampleImagesFileManager.get_files(request)
+        registrar = ExampleImagesRouteRegistrar(app)
+        registrar.register_routes(self.to_route_mapping())
 
-    @staticmethod
-    async def import_example_images(request):
-        """Import local example images for a model"""
-        return await ExampleImagesProcessor.import_images(request)
-        
-    @staticmethod
-    async def has_example_images(request):
-        """Check if example images folder exists and is not empty for a model"""
-        return await ExampleImagesFileManager.has_images(request)
+    def to_route_mapping(self) -> Mapping[str, Callable[[web.Request], web.StreamResponse]]:
+        """Return the registrar-compatible mapping of handler names to callables."""
 
-    @staticmethod
-    async def delete_example_image(request):
-        """Delete a custom example image for a model"""
-        return await ExampleImagesProcessor.delete_custom_image(request)
+        if self._handler_mapping is None:
+            handler_set = self._build_handler_set()
+            self._handler_set = handler_set
+            self._handler_mapping = handler_set.to_route_mapping()
+        return self._handler_mapping
 
-    @staticmethod
-    async def force_download_example_images(request):
-        """Force download example images for specific models"""
-        return await DownloadManager.start_force_download(request)
+    def _build_handler_set(self) -> ExampleImagesHandlerSet:
+        logger.debug("Building ExampleImagesHandlerSet with %s, %s, %s", self._download_manager, self._processor, self._file_manager)
+        download_use_case = DownloadExampleImagesUseCase(download_manager=self._download_manager)
+        download_handler = ExampleImagesDownloadHandler(download_use_case, self._download_manager)
+        import_use_case = ImportExampleImagesUseCase(processor=self._processor)
+        management_handler = ExampleImagesManagementHandler(
+            import_use_case,
+            self._processor,
+            self._cleanup_service,
+        )
+        file_handler = ExampleImagesFileHandler(self._file_manager)
+        return ExampleImagesHandlerSet(
+            download=download_handler,
+            management=management_handler,
+            files=file_handler,
+        )

py/routes/handlers/example_images_handlers.py

@@ -0,0 +1,167 @@
+"""Handler set for example image routes."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Mapping
+
+from aiohttp import web
+
+from ...services.use_cases.example_images import (
+    DownloadExampleImagesConfigurationError,
+    DownloadExampleImagesInProgressError,
+    DownloadExampleImagesUseCase,
+    ImportExampleImagesUseCase,
+    ImportExampleImagesValidationError,
+)
+from ...utils.example_images_download_manager import (
+    DownloadConfigurationError,
+    DownloadInProgressError,
+    DownloadNotRunningError,
+    ExampleImagesDownloadError,
+)
+from ...utils.example_images_processor import ExampleImagesImportError
+
+
+class ExampleImagesDownloadHandler:
+    """HTTP adapters for download-related example image endpoints."""
+
+    def __init__(
+        self,
+        download_use_case: DownloadExampleImagesUseCase,
+        download_manager,
+    ) -> None:
+        self._download_use_case = download_use_case
+        self._download_manager = download_manager
+
+    async def download_example_images(self, request: web.Request) -> web.StreamResponse:
+        try:
+            payload = await request.json()
+            result = await self._download_use_case.execute(payload)
+            return web.json_response(result)
+        except DownloadExampleImagesInProgressError as exc:
+            response = {
+                'success': False,
+                'error': str(exc),
+                'status': exc.progress,
+            }
+            return web.json_response(response, status=400)
+        except DownloadExampleImagesConfigurationError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=400)
+        except ExampleImagesDownloadError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=500)
+
+    async def get_example_images_status(self, request: web.Request) -> web.StreamResponse:
+        result = await self._download_manager.get_status(request)
+        return web.json_response(result)
+
+    async def pause_example_images(self, request: web.Request) -> web.StreamResponse:
+        try:
+            result = await self._download_manager.pause_download(request)
+            return web.json_response(result)
+        except DownloadNotRunningError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=400)
+
+    async def resume_example_images(self, request: web.Request) -> web.StreamResponse:
+        try:
+            result = await self._download_manager.resume_download(request)
+            return web.json_response(result)
+        except DownloadNotRunningError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=400)
+
+    async def stop_example_images(self, request: web.Request) -> web.StreamResponse:
+        try:
+            result = await self._download_manager.stop_download(request)
+            return web.json_response(result)
+        except DownloadNotRunningError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=400)
+
+    async def force_download_example_images(self, request: web.Request) -> web.StreamResponse:
+        try:
+            payload = await request.json()
+            result = await self._download_manager.start_force_download(payload)
+            return web.json_response(result)
+        except DownloadInProgressError as exc:
+            response = {
+                'success': False,
+                'error': str(exc),
+                'status': exc.progress_snapshot,
+            }
+            return web.json_response(response, status=400)
+        except DownloadConfigurationError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=400)
+        except ExampleImagesDownloadError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=500)
+
+
+class ExampleImagesManagementHandler:
+    """HTTP adapters for import/delete endpoints."""
+
+    def __init__(self, import_use_case: ImportExampleImagesUseCase, processor, cleanup_service) -> None:
+        self._import_use_case = import_use_case
+        self._processor = processor
+        self._cleanup_service = cleanup_service
+
+    async def import_example_images(self, request: web.Request) -> web.StreamResponse:
+        try:
+            result = await self._import_use_case.execute(request)
+            return web.json_response(result)
+        except ImportExampleImagesValidationError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=400)
+        except ExampleImagesImportError as exc:
+            return web.json_response({'success': False, 'error': str(exc)}, status=500)
+
+    async def delete_example_image(self, request: web.Request) -> web.StreamResponse:
+        return await self._processor.delete_custom_image(request)
+
+    async def cleanup_example_image_folders(self, request: web.Request) -> web.StreamResponse:
+        result = await self._cleanup_service.cleanup_example_image_folders()
+
+        if result.get('success') or result.get('partial_success'):
+            return web.json_response(result, status=200)
+
+        error_code = result.get('error_code')
+        status = 400 if error_code in {'path_not_configured', 'path_not_found'} else 500
+        return web.json_response(result, status=status)
+
+
+class ExampleImagesFileHandler:
+    """HTTP adapters for filesystem-centric endpoints."""
+
+    def __init__(self, file_manager) -> None:
+        self._file_manager = file_manager
+
+    async def open_example_images_folder(self, request: web.Request) -> web.StreamResponse:
+        return await self._file_manager.open_folder(request)
+
+    async def get_example_image_files(self, request: web.Request) -> web.StreamResponse:
+        return await self._file_manager.get_files(request)
+
+    async def has_example_images(self, request: web.Request) -> web.StreamResponse:
+        return await self._file_manager.has_images(request)
+
+
+@dataclass(frozen=True)
+class ExampleImagesHandlerSet:
+    """Aggregate of handlers exposed to the registrar."""
+
+    download: ExampleImagesDownloadHandler
+    management: ExampleImagesManagementHandler
+    files: ExampleImagesFileHandler
+
+    def to_route_mapping(self) -> Mapping[str, Callable[[web.Request], web.StreamResponse]]:
+        """Flatten handler methods into the registrar mapping."""
+
+        return {
+            "download_example_images": self.download.download_example_images,
+            "get_example_images_status": self.download.get_example_images_status,
+            "pause_example_images": self.download.pause_example_images,
+            "resume_example_images": self.download.resume_example_images,
+            "stop_example_images": self.download.stop_example_images,
+            "force_download_example_images": self.download.force_download_example_images,
+            "import_example_images": self.management.import_example_images,
+            "delete_example_image": self.management.delete_example_image,
+            "cleanup_example_image_folders": self.management.cleanup_example_image_folders,
+            "open_example_images_folder": self.files.open_example_images_folder,
+            "get_example_image_files": self.files.get_example_image_files,
+            "has_example_images": self.files.has_example_images,
+        }

py/routes/handlers/misc_handlers.py

@@ -0,0 +1,980 @@
+"""Handlers for miscellaneous routes.
+
+The legacy :mod:`py.routes.misc_routes` module bundled HTTP wiring and
+business logic in a single class.  This module mirrors the model route
+architecture by splitting the responsibilities into dedicated handler
+objects that can be composed by the route controller.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Dict, Mapping, Protocol
+
+from aiohttp import web
+
+from ...config import config
+from ...services.metadata_service import (
+    get_metadata_archive_manager,
+    update_metadata_providers,
+)
+from ...services.service_registry import ServiceRegistry
+from ...services.settings_manager import get_settings_manager
+from ...services.websocket_manager import ws_manager
+from ...services.downloader import get_downloader
+from ...utils.constants import (
+    CIVITAI_USER_MODEL_TYPES,
+    DEFAULT_NODE_COLOR,
+    NODE_TYPES,
+    SUPPORTED_MEDIA_EXTENSIONS,
+    VALID_LORA_TYPES,
+)
+from ...utils.civitai_utils import rewrite_preview_url
+from ...utils.example_images_paths import is_valid_example_images_root
+from ...utils.lora_metadata import extract_trained_words
+from ...utils.usage_stats import UsageStats
+
+logger = logging.getLogger(__name__)
+
+
+class PromptServerProtocol(Protocol):
+    """Subset of PromptServer used by the handlers."""
+
+    instance: "PromptServerProtocol"
+
+    def send_sync(self, event: str, payload: dict) -> None:  # pragma: no cover - protocol
+        ...
+
+
+class DownloaderProtocol(Protocol):
+    async def refresh_session(self) -> None:  # pragma: no cover - protocol
+        ...
+
+
+class UsageStatsFactory(Protocol):
+    def __call__(self) -> UsageStats:  # pragma: no cover - protocol
+        ...
+
+
+class MetadataProviderProtocol(Protocol):
+    async def get_model_versions(self, model_id: int) -> dict | None:  # pragma: no cover - protocol
+        ...
+
+
+class MetadataArchiveManagerProtocol(Protocol):
+    async def download_and_extract_database(
+        self, progress_callback: Callable[[str, str], None]
+    ) -> bool:  # pragma: no cover - protocol
+        ...
+
+    async def remove_database(self) -> bool:  # pragma: no cover - protocol
+        ...
+
+    def is_database_available(self) -> bool:  # pragma: no cover - protocol
+        ...
+
+    def get_database_path(self) -> str | None:  # pragma: no cover - protocol
+        ...
+
+
+class NodeRegistry:
+    """Thread-safe registry for tracking LoRA nodes in active workflows."""
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+        self._nodes: Dict[str, dict] = {}
+        self._registry_updated = asyncio.Event()
+
+    async def register_nodes(self, nodes: list[dict]) -> None:
+        async with self._lock:
+            self._nodes.clear()
+            for node in nodes:
+                node_id = node["node_id"]
+                graph_id = str(node["graph_id"])
+                unique_id = f"{graph_id}:{node_id}"
+                node_type = node.get("type", "")
+                type_id = NODE_TYPES.get(node_type, 0)
+                bgcolor = node.get("bgcolor") or DEFAULT_NODE_COLOR
+                self._nodes[unique_id] = {
+                    "id": node_id,
+                    "graph_id": graph_id,
+                    "graph_name": node.get("graph_name"),
+                    "unique_id": unique_id,
+                    "bgcolor": bgcolor,
+                    "title": node.get("title"),
+                    "type": type_id,
+                    "type_name": node_type,
+                }
+            logger.debug("Registered %s nodes in registry", len(nodes))
+            self._registry_updated.set()
+
+    async def get_registry(self) -> dict:
+        async with self._lock:
+            return {
+                "nodes": dict(self._nodes),
+                "node_count": len(self._nodes),
+            }
+
+    async def wait_for_update(self, timeout: float = 1.0) -> bool:
+        self._registry_updated.clear()
+        try:
+            await asyncio.wait_for(self._registry_updated.wait(), timeout=timeout)
+            return True
+        except asyncio.TimeoutError:
+            return False
+
+
+class HealthCheckHandler:
+    async def health_check(self, request: web.Request) -> web.Response:
+        return web.json_response({"status": "ok"})
+
+
+class SettingsHandler:
+    """Sync settings between backend and frontend."""
+
+    _SYNC_KEYS = (
+        "civitai_api_key",
+        "default_lora_root",
+        "default_checkpoint_root",
+        "default_embedding_root",
+        "base_model_path_mappings",
+        "download_path_templates",
+        "enable_metadata_archive_db",
+        "language",
+        "proxy_enabled",
+        "proxy_type",
+        "proxy_host",
+        "proxy_port",
+        "proxy_username",
+        "proxy_password",
+        "example_images_path",
+        "optimize_example_images",
+        "auto_download_example_images",
+        "blur_mature_content",
+        "autoplay_on_hover",
+        "display_density",
+        "card_info_display",
+        "include_trigger_words",
+        "show_only_sfw",
+        "compact_mode",
+        "priority_tags",
+        "model_name_display",
+    )
+
+    _PROXY_KEYS = {"proxy_enabled", "proxy_host", "proxy_port", "proxy_username", "proxy_password", "proxy_type"}
+
+    def __init__(
+        self,
+        *,
+        settings_service=None,
+        metadata_provider_updater: Callable[[], Awaitable[None]] = update_metadata_providers,
+        downloader_factory: Callable[[], Awaitable[DownloaderProtocol]] = get_downloader,
+    ) -> None:
+        self._settings = settings_service or get_settings_manager()
+        self._metadata_provider_updater = metadata_provider_updater
+        self._downloader_factory = downloader_factory
+
+    async def get_libraries(self, request: web.Request) -> web.Response:
+        """Return the registered libraries and the active selection."""
+
+        try:
+            snapshot = config.get_library_registry_snapshot()
+            libraries = snapshot.get("libraries", {})
+            active_library = snapshot.get("active_library", "")
+            return web.json_response(
+                {
+                    "success": True,
+                    "libraries": libraries,
+                    "active_library": active_library,
+                }
+            )
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error getting library registry: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_settings(self, request: web.Request) -> web.Response:
+        try:
+            response_data = {}
+            for key in self._SYNC_KEYS:
+                value = self._settings.get(key)
+                if value is not None:
+                    response_data[key] = value
+            return web.json_response({"success": True, "settings": response_data})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error getting settings: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_priority_tags(self, request: web.Request) -> web.Response:
+        try:
+            suggestions = self._settings.get_priority_tag_suggestions()
+            return web.json_response({"success": True, "tags": suggestions})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error getting priority tags: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def activate_library(self, request: web.Request) -> web.Response:
+        """Activate the selected library."""
+
+        try:
+            data = await request.json()
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error parsing activate library request: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": "Invalid JSON payload"}, status=400)
+
+        library_name = data.get("library") or data.get("library_name")
+        if not isinstance(library_name, str) or not library_name.strip():
+            return web.json_response(
+                {"success": False, "error": "Library name is required"}, status=400
+            )
+
+        try:
+            normalized_name = library_name.strip()
+            self._settings.activate_library(normalized_name)
+            snapshot = config.get_library_registry_snapshot()
+            libraries = snapshot.get("libraries", {})
+            active_library = snapshot.get("active_library", "")
+            return web.json_response(
+                {
+                    "success": True,
+                    "active_library": active_library,
+                    "libraries": libraries,
+                }
+            )
+        except KeyError as exc:
+            logger.debug("Attempted to activate unknown library '%s'", library_name)
+            return web.json_response({"success": False, "error": str(exc)}, status=404)
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error activating library '%s': %s", library_name, exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def update_settings(self, request: web.Request) -> web.Response:
+        try:
+            data = await request.json()
+            proxy_changed = False
+
+            for key, value in data.items():
+                if value == self._settings.get(key):
+                    continue
+
+                if key == "example_images_path" and value:
+                    validation_error = self._validate_example_images_path(value)
+                    if validation_error:
+                        return web.json_response({"success": False, "error": validation_error})
+
+                if value == "__DELETE__" and key in ("proxy_username", "proxy_password"):
+                    self._settings.delete(key)
+                else:
+                    self._settings.set(key, value)
+
+                if key == "enable_metadata_archive_db":
+                    await self._metadata_provider_updater()
+
+                if key in self._PROXY_KEYS:
+                    proxy_changed = True
+
+            if proxy_changed:
+                downloader = await self._downloader_factory()
+                await downloader.refresh_session()
+
+            return web.json_response({"success": True})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error updating settings: %s", exc, exc_info=True)
+            return web.Response(status=500, text=str(exc))
+
+    def _validate_example_images_path(self, folder_path: str) -> str | None:
+        if not os.path.exists(folder_path):
+            return f"Path does not exist: {folder_path}"
+        if not os.path.isdir(folder_path):
+            return "Please set a dedicated folder for example images."
+        if not self._is_dedicated_example_images_folder(folder_path):
+            return "Please set a dedicated folder for example images."
+        return None
+
+    def _is_dedicated_example_images_folder(self, folder_path: str) -> bool:
+        return is_valid_example_images_root(folder_path)
+
+
+class UsageStatsHandler:
+    def __init__(self, usage_stats_factory: UsageStatsFactory = UsageStats) -> None:
+        self._usage_stats_factory = usage_stats_factory
+
+    async def update_usage_stats(self, request: web.Request) -> web.Response:
+        try:
+            data = await request.json()
+            prompt_id = data.get("prompt_id")
+            if not prompt_id:
+                return web.json_response({"success": False, "error": "Missing prompt_id"}, status=400)
+            usage_stats = self._usage_stats_factory()
+            await usage_stats.process_execution(prompt_id)
+            return web.json_response({"success": True})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to update usage stats: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_usage_stats(self, request: web.Request) -> web.Response:
+        try:
+            usage_stats = self._usage_stats_factory()
+            stats = await usage_stats.get_stats()
+            stats_response = {"success": True, "data": stats, "format_version": 2}
+            return web.json_response(stats_response)
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to get usage stats: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
+class LoraCodeHandler:
+    def __init__(self, prompt_server: type[PromptServerProtocol]) -> None:
+        self._prompt_server = prompt_server
+
+    async def update_lora_code(self, request: web.Request) -> web.Response:
+        try:
+            data = await request.json()
+            node_ids = data.get("node_ids")
+            lora_code = data.get("lora_code", "")
+            mode = data.get("mode", "append")
+
+            if not lora_code:
+                return web.json_response({"success": False, "error": "Missing lora_code parameter"}, status=400)
+
+            results = []
+            if node_ids is None:
+                try:
+                    self._prompt_server.instance.send_sync(
+                        "lora_code_update", {"id": -1, "lora_code": lora_code, "mode": mode}
+                    )
+                    results.append({"node_id": "broadcast", "success": True})
+                except Exception as exc:  # pragma: no cover - defensive logging
+                    logger.error("Error broadcasting lora code: %s", exc)
+                    results.append({"node_id": "broadcast", "success": False, "error": str(exc)})
+            else:
+                for entry in node_ids:
+                    node_identifier = entry
+                    graph_identifier = None
+                    if isinstance(entry, dict):
+                        node_identifier = entry.get("node_id")
+                        graph_identifier = entry.get("graph_id")
+
+                    if node_identifier is None:
+                        results.append(
+                            {
+                                "node_id": node_identifier,
+                                "graph_id": graph_identifier,
+                                "success": False,
+                                "error": "Missing node_id parameter",
+                            }
+                        )
+                        continue
+
+                    try:
+                        parsed_node_id = int(node_identifier)
+                    except (TypeError, ValueError):
+                        parsed_node_id = node_identifier
+
+                    payload = {
+                        "id": parsed_node_id,
+                        "lora_code": lora_code,
+                        "mode": mode,
+                    }
+
+                    if graph_identifier is not None:
+                        payload["graph_id"] = str(graph_identifier)
+
+                    try:
+                        self._prompt_server.instance.send_sync(
+                            "lora_code_update",
+                            payload,
+                        )
+                        results.append(
+                            {
+                                "node_id": parsed_node_id,
+                                "graph_id": payload.get("graph_id"),
+                                "success": True,
+                            }
+                        )
+                    except Exception as exc:  # pragma: no cover - defensive logging
+                        logger.error(
+                            "Error sending lora code to node %s (graph %s): %s",
+                            parsed_node_id,
+                            graph_identifier,
+                            exc,
+                        )
+                        results.append(
+                            {
+                                "node_id": parsed_node_id,
+                                "graph_id": payload.get("graph_id"),
+                                "success": False,
+                                "error": str(exc),
+                            }
+                        )
+
+            return web.json_response({"success": True, "results": results})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to update lora code: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
+class TrainedWordsHandler:
+    async def get_trained_words(self, request: web.Request) -> web.Response:
+        try:
+            file_path = request.query.get("file_path")
+            if not file_path:
+                return web.json_response({"success": False, "error": "Missing file_path parameter"}, status=400)
+            if not os.path.exists(file_path):
+                return web.json_response({"success": False, "error": "File not found"}, status=404)
+            if not file_path.endswith(".safetensors"):
+                return web.json_response({"success": False, "error": "File must be a safetensors file"}, status=400)
+
+            trained_words, class_tokens = await extract_trained_words(file_path)
+            return web.json_response(
+                {
+                    "success": True,
+                    "trained_words": trained_words,
+                    "class_tokens": class_tokens,
+                }
+            )
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to get trained words: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
+class ModelExampleFilesHandler:
+    async def get_model_example_files(self, request: web.Request) -> web.Response:
+        try:
+            model_path = request.query.get("model_path")
+            if not model_path:
+                return web.json_response({"success": False, "error": "Missing model_path parameter"}, status=400)
+            model_dir = os.path.dirname(model_path)
+            if not os.path.exists(model_dir):
+                return web.json_response({"success": False, "error": "Model directory not found"}, status=404)
+
+            base_name = os.path.splitext(os.path.basename(model_path))[0]
+            files = []
+            pattern = f"{base_name}.example."
+            for file in os.listdir(model_dir):
+                if not file.startswith(pattern):
+                    continue
+                file_full_path = os.path.join(model_dir, file)
+                if not os.path.isfile(file_full_path):
+                    continue
+                file_ext = os.path.splitext(file)[1].lower()
+                if file_ext not in SUPPORTED_MEDIA_EXTENSIONS["images"] and file_ext not in SUPPORTED_MEDIA_EXTENSIONS["videos"]:
+                    continue
+                try:
+                    index = int(file[len(pattern) :].split(".")[0])
+                except (ValueError, IndexError):
+                    index = float("inf")
+                static_url = config.get_preview_static_url(file_full_path)
+                files.append(
+                    {
+                        "name": file,
+                        "path": static_url,
+                        "extension": file_ext,
+                        "is_video": file_ext in SUPPORTED_MEDIA_EXTENSIONS["videos"],
+                        "index": index,
+                    }
+                )
+
+            files.sort(key=lambda item: item["index"])
+            for file in files:
+                file.pop("index", None)
+
+            return web.json_response({"success": True, "files": files})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to get model example files: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
+@dataclass
+class ServiceRegistryAdapter:
+    get_lora_scanner: Callable[[], Awaitable]
+    get_checkpoint_scanner: Callable[[], Awaitable]
+    get_embedding_scanner: Callable[[], Awaitable]
+
+
+class ModelLibraryHandler:
+    def __init__(self, service_registry: ServiceRegistryAdapter, metadata_provider_factory: Callable[[], Awaitable[MetadataProviderProtocol | None]]) -> None:
+        self._service_registry = service_registry
+        self._metadata_provider_factory = metadata_provider_factory
+
+    async def check_model_exists(self, request: web.Request) -> web.Response:
+        try:
+            model_id_str = request.query.get("modelId")
+            model_version_id_str = request.query.get("modelVersionId")
+            if not model_id_str:
+                return web.json_response({"success": False, "error": "Missing required parameter: modelId"}, status=400)
+            try:
+                model_id = int(model_id_str)
+            except ValueError:
+                return web.json_response({"success": False, "error": "Parameter modelId must be an integer"}, status=400)
+
+            lora_scanner = await self._service_registry.get_lora_scanner()
+            checkpoint_scanner = await self._service_registry.get_checkpoint_scanner()
+            embedding_scanner = await self._service_registry.get_embedding_scanner()
+
+            if model_version_id_str:
+                try:
+                    model_version_id = int(model_version_id_str)
+                except ValueError:
+                    return web.json_response({"success": False, "error": "Parameter modelVersionId must be an integer"}, status=400)
+
+                exists = False
+                model_type = None
+                if await lora_scanner.check_model_version_exists(model_version_id):
+                    exists = True
+                    model_type = "lora"
+                elif checkpoint_scanner and await checkpoint_scanner.check_model_version_exists(model_version_id):
+                    exists = True
+                    model_type = "checkpoint"
+                elif embedding_scanner and await embedding_scanner.check_model_version_exists(model_version_id):
+                    exists = True
+                    model_type = "embedding"
+
+                return web.json_response({"success": True, "exists": exists, "modelType": model_type if exists else None})
+
+            lora_versions = await lora_scanner.get_model_versions_by_id(model_id)
+            checkpoint_versions = []
+            embedding_versions = []
+            if not lora_versions and checkpoint_scanner:
+                checkpoint_versions = await checkpoint_scanner.get_model_versions_by_id(model_id)
+            if not lora_versions and not checkpoint_versions and embedding_scanner:
+                embedding_versions = await embedding_scanner.get_model_versions_by_id(model_id)
+
+            model_type = None
+            versions = []
+            if lora_versions:
+                model_type = "lora"
+                versions = lora_versions
+            elif checkpoint_versions:
+                model_type = "checkpoint"
+                versions = checkpoint_versions
+            elif embedding_versions:
+                model_type = "embedding"
+                versions = embedding_versions
+
+            return web.json_response({"success": True, "modelType": model_type, "versions": versions})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to check model existence: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_model_versions_status(self, request: web.Request) -> web.Response:
+        try:
+            model_id_str = request.query.get("modelId")
+            if not model_id_str:
+                return web.json_response({"success": False, "error": "Missing required parameter: modelId"}, status=400)
+            try:
+                model_id = int(model_id_str)
+            except ValueError:
+                return web.json_response({"success": False, "error": "Parameter modelId must be an integer"}, status=400)
+
+            metadata_provider = await self._metadata_provider_factory()
+            if not metadata_provider:
+                return web.json_response({"success": False, "error": "Metadata provider not available"}, status=503)
+
+            response = await metadata_provider.get_model_versions(model_id)
+            if not response or not response.get("modelVersions"):
+                return web.json_response({"success": False, "error": "Model not found"}, status=404)
+
+            versions = response.get("modelVersions", [])
+            model_name = response.get("name", "")
+            model_type = response.get("type", "").lower()
+
+            scanner = None
+            normalized_type = None
+            if model_type in {"lora", "locon", "dora"}:
+                scanner = await self._service_registry.get_lora_scanner()
+                normalized_type = "lora"
+            elif model_type == "checkpoint":
+                scanner = await self._service_registry.get_checkpoint_scanner()
+                normalized_type = "checkpoint"
+            elif model_type == "textualinversion":
+                scanner = await self._service_registry.get_embedding_scanner()
+                normalized_type = "embedding"
+            else:
+                return web.json_response({"success": False, "error": f'Model type "{model_type}" is not supported'}, status=400)
+
+            if not scanner:
+                return web.json_response({"success": False, "error": f'Scanner for type "{normalized_type}" is not available'}, status=503)
+
+            local_versions = await scanner.get_model_versions_by_id(model_id)
+            local_version_ids = {version["versionId"] for version in local_versions}
+
+            enriched_versions = []
+            for version in versions:
+                version_id = version.get("id")
+                enriched_versions.append(
+                    {
+                        "id": version_id,
+                        "name": version.get("name", ""),
+                        "thumbnailUrl": version.get("images")[0]["url"] if version.get("images") else None,
+                        "inLibrary": version_id in local_version_ids,
+                    }
+                )
+
+            return web.json_response(
+                {
+                    "success": True,
+                    "modelId": model_id,
+                    "modelName": model_name,
+                    "modelType": model_type,
+                    "versions": enriched_versions,
+                }
+            )
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to get model versions status: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_civitai_user_models(self, request: web.Request) -> web.Response:
+        try:
+            username = request.query.get("username")
+            if not username:
+                return web.json_response({"success": False, "error": "Missing required parameter: username"}, status=400)
+
+            metadata_provider = await self._metadata_provider_factory()
+            if not metadata_provider:
+                return web.json_response({"success": False, "error": "Metadata provider not available"}, status=503)
+
+            try:
+                models = await metadata_provider.get_user_models(username)
+            except NotImplementedError:
+                return web.json_response({"success": False, "error": "Metadata provider does not support user model queries"}, status=501)
+
+            if models is None:
+                return web.json_response({"success": False, "error": "Failed to fetch user models"}, status=502)
+
+            if not isinstance(models, list):
+                models = []
+
+            lora_scanner = await self._service_registry.get_lora_scanner()
+            checkpoint_scanner = await self._service_registry.get_checkpoint_scanner()
+            embedding_scanner = await self._service_registry.get_embedding_scanner()
+
+            normalized_allowed_types = {model_type.lower() for model_type in CIVITAI_USER_MODEL_TYPES}
+            lora_type_aliases = {model_type.lower() for model_type in VALID_LORA_TYPES}
+
+            type_scanner_map: Dict[str, object | None] = {
+                **{alias: lora_scanner for alias in lora_type_aliases},
+                "checkpoint": checkpoint_scanner,
+                "textualinversion": embedding_scanner,
+            }
+
+            versions: list[dict] = []
+            for model in models:
+                if not isinstance(model, dict):
+                    continue
+
+                model_type = str(model.get("type", "")).lower()
+                if model_type not in normalized_allowed_types:
+                    continue
+
+                scanner = type_scanner_map.get(model_type)
+                if scanner is None:
+                    return web.json_response({"success": False, "error": f'Scanner for type "{model_type}" is not available'}, status=503)
+
+                tags_value = model.get("tags")
+                tags = tags_value if isinstance(tags_value, list) else []
+                model_id = model.get("id")
+                try:
+                    model_id_int = int(model_id)
+                except (TypeError, ValueError):
+                    continue
+                model_name = model.get("name", "")
+
+                versions_data = model.get("modelVersions")
+                if not isinstance(versions_data, list):
+                    continue
+
+                for version in versions_data:
+                    if not isinstance(version, dict):
+                        continue
+
+                    version_id = version.get("id")
+                    try:
+                        version_id_int = int(version_id)
+                    except (TypeError, ValueError):
+                        continue
+
+                    images = version.get("images") or []
+                    thumbnail_url = None
+                    if images and isinstance(images, list):
+                        first_image = images[0]
+                        if isinstance(first_image, dict):
+                            raw_url = first_image.get("url")
+                            media_type = first_image.get("type")
+                            rewritten_url, _ = rewrite_preview_url(raw_url, media_type)
+                            thumbnail_url = rewritten_url
+
+                    in_library = await scanner.check_model_version_exists(version_id_int)
+
+                    versions.append(
+                        {
+                            "modelId": model_id_int,
+                            "versionId": version_id_int,
+                            "modelName": model_name,
+                            "versionName": version.get("name", ""),
+                            "type": model.get("type"),
+                            "tags": tags,
+                            "baseModel": version.get("baseModel"),
+                            "thumbnailUrl": thumbnail_url,
+                            "inLibrary": in_library,
+                        }
+                    )
+
+            return web.json_response({"success": True, "username": username, "versions": versions})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to get Civitai user models: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
+class MetadataArchiveHandler:
+    def __init__(
+        self,
+        *,
+        metadata_archive_manager_factory: Callable[[], Awaitable[MetadataArchiveManagerProtocol]] = get_metadata_archive_manager,
+        settings_service=None,
+        metadata_provider_updater: Callable[[], Awaitable[None]] = update_metadata_providers,
+    ) -> None:
+        self._metadata_archive_manager_factory = metadata_archive_manager_factory
+        self._settings = settings_service or get_settings_manager()
+        self._metadata_provider_updater = metadata_provider_updater
+
+    async def download_metadata_archive(self, request: web.Request) -> web.Response:
+        try:
+            archive_manager = await self._metadata_archive_manager_factory()
+            download_id = request.query.get("download_id")
+
+            def progress_callback(stage: str, message: str) -> None:
+                data = {"stage": stage, "message": message, "type": "metadata_archive_download"}
+                if download_id:
+                    asyncio.create_task(ws_manager.broadcast_download_progress(download_id, data))
+                else:
+                    asyncio.create_task(ws_manager.broadcast(data))
+
+            success = await archive_manager.download_and_extract_database(progress_callback)
+            if success:
+                self._settings.set("enable_metadata_archive_db", True)
+                await self._metadata_provider_updater()
+                return web.json_response({"success": True, "message": "Metadata archive database downloaded and extracted successfully"})
+            return web.json_response({"success": False, "error": "Failed to download and extract metadata archive database"}, status=500)
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error downloading metadata archive: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def remove_metadata_archive(self, request: web.Request) -> web.Response:
+        try:
+            archive_manager = await self._metadata_archive_manager_factory()
+            success = await archive_manager.remove_database()
+            if success:
+                self._settings.set("enable_metadata_archive_db", False)
+                await self._metadata_provider_updater()
+                return web.json_response({"success": True, "message": "Metadata archive database removed successfully"})
+            return web.json_response({"success": False, "error": "Failed to remove metadata archive database"}, status=500)
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error removing metadata archive: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_metadata_archive_status(self, request: web.Request) -> web.Response:
+        try:
+            archive_manager = await self._metadata_archive_manager_factory()
+            is_available = archive_manager.is_database_available()
+            is_enabled = self._settings.get("enable_metadata_archive_db", False)
+            db_size = 0
+            if is_available:
+                db_path = archive_manager.get_database_path()
+                if db_path and os.path.exists(db_path):
+                    db_size = os.path.getsize(db_path)
+            return web.json_response(
+                {
+                    "success": True,
+                    "isAvailable": is_available,
+                    "isEnabled": is_enabled,
+                    "databaseSize": db_size,
+                    "databasePath": archive_manager.get_database_path() if is_available else None,
+                }
+            )
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error getting metadata archive status: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
+class FileSystemHandler:
+    async def open_file_location(self, request: web.Request) -> web.Response:
+        try:
+            data = await request.json()
+            file_path = data.get("file_path")
+            if not file_path:
+                return web.json_response({"success": False, "error": "Missing file_path parameter"}, status=400)
+            file_path = os.path.abspath(file_path)
+            if not os.path.isfile(file_path):
+                return web.json_response({"success": False, "error": "File does not exist"}, status=404)
+
+            if os.name == "nt":
+                subprocess.Popen(["explorer", "/select,", file_path])
+            elif os.name == "posix":
+                if sys.platform == "darwin":
+                    subprocess.Popen(["open", "-R", file_path])
+                else:
+                    folder = os.path.dirname(file_path)
+                    subprocess.Popen(["xdg-open", folder])
+
+            return web.json_response({"success": True, "message": f"Opened folder and selected file: {file_path}"})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to open file location: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
+class NodeRegistryHandler:
+    def __init__(
+        self,
+        node_registry: NodeRegistry,
+        prompt_server: type[PromptServerProtocol],
+        *,
+        standalone_mode: bool,
+    ) -> None:
+        self._node_registry = node_registry
+        self._prompt_server = prompt_server
+        self._standalone_mode = standalone_mode
+
+    async def register_nodes(self, request: web.Request) -> web.Response:
+        try:
+            data = await request.json()
+            nodes = data.get("nodes", [])
+            if not isinstance(nodes, list):
+                return web.json_response({"success": False, "error": "nodes must be a list"}, status=400)
+            for index, node in enumerate(nodes):
+                if not isinstance(node, dict):
+                    return web.json_response({"success": False, "error": f"Node {index} must be an object"}, status=400)
+                node_id = node.get("node_id")
+                if node_id is None:
+                    return web.json_response({"success": False, "error": f"Node {index} missing node_id parameter"}, status=400)
+                graph_id = node.get("graph_id")
+                if graph_id is None:
+                    return web.json_response({"success": False, "error": f"Node {index} missing graph_id parameter"}, status=400)
+                graph_name = node.get("graph_name")
+                try:
+                    node["node_id"] = int(node_id)
+                except (TypeError, ValueError):
+                    return web.json_response({"success": False, "error": f"Node {index} node_id must be an integer"}, status=400)
+                node["graph_id"] = str(graph_id)
+                if graph_name is None:
+                    node["graph_name"] = None
+                elif isinstance(graph_name, str):
+                    node["graph_name"] = graph_name
+                else:
+                    node["graph_name"] = str(graph_name)
+
+            await self._node_registry.register_nodes(nodes)
+            return web.json_response({"success": True, "message": f"{len(nodes)} nodes registered successfully"})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to register nodes: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_registry(self, request: web.Request) -> web.Response:
+        try:
+            if self._standalone_mode:
+                logger.warning("Registry refresh not available in standalone mode")
+                return web.json_response(
+                    {
+                        "success": False,
+                        "error": "Standalone Mode Active",
+                        "message": "Cannot interact with ComfyUI in standalone mode.",
+                    },
+                    status=503,
+                )
+
+            try:
+                self._prompt_server.instance.send_sync("lora_registry_refresh", {})
+                logger.debug("Sent registry refresh request to frontend")
+            except Exception as exc:
+                logger.error("Failed to send registry refresh message: %s", exc)
+                return web.json_response(
+                    {
+                        "success": False,
+                        "error": "Communication Error",
+                        "message": f"Failed to communicate with ComfyUI frontend: {exc}",
+                    },
+                    status=500,
+                )
+
+            registry_updated = await self._node_registry.wait_for_update(timeout=1.0)
+            if not registry_updated:
+                logger.warning("Registry refresh timeout after 1 second")
+                return web.json_response(
+                    {
+                        "success": False,
+                        "error": "Timeout Error",
+                        "message": "Registry refresh timeout - ComfyUI frontend may not be responsive",
+                    },
+                    status=408,
+                )
+
+            registry_info = await self._node_registry.get_registry()
+            return web.json_response({"success": True, "data": registry_info})
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Failed to get registry: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": "Internal Error", "message": str(exc)}, status=500)
+
+
+class MiscHandlerSet:
+    """Aggregate handlers into a lookup compatible with the registrar."""
+
+    def __init__(
+        self,
+        *,
+        health: HealthCheckHandler,
+        settings: SettingsHandler,
+        usage_stats: UsageStatsHandler,
+        lora_code: LoraCodeHandler,
+        trained_words: TrainedWordsHandler,
+        model_examples: ModelExampleFilesHandler,
+        node_registry: NodeRegistryHandler,
+        model_library: ModelLibraryHandler,
+        metadata_archive: MetadataArchiveHandler,
+        filesystem: FileSystemHandler,
+    ) -> None:
+        self.health = health
+        self.settings = settings
+        self.usage_stats = usage_stats
+        self.lora_code = lora_code
+        self.trained_words = trained_words
+        self.model_examples = model_examples
+        self.node_registry = node_registry
+        self.model_library = model_library
+        self.metadata_archive = metadata_archive
+        self.filesystem = filesystem
+
+    def to_route_mapping(self) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
+        return {
+            "health_check": self.health.health_check,
+            "get_settings": self.settings.get_settings,
+            "update_settings": self.settings.update_settings,
+            "get_priority_tags": self.settings.get_priority_tags,
+            "get_settings_libraries": self.settings.get_libraries,
+            "activate_library": self.settings.activate_library,
+            "update_usage_stats": self.usage_stats.update_usage_stats,
+            "get_usage_stats": self.usage_stats.get_usage_stats,
+            "update_lora_code": self.lora_code.update_lora_code,
+            "get_trained_words": self.trained_words.get_trained_words,
+            "get_model_example_files": self.model_examples.get_model_example_files,
+            "register_nodes": self.node_registry.register_nodes,
+            "get_registry": self.node_registry.get_registry,
+            "check_model_exists": self.model_library.check_model_exists,
+            "get_civitai_user_models": self.model_library.get_civitai_user_models,
+            "download_metadata_archive": self.metadata_archive.download_metadata_archive,
+            "remove_metadata_archive": self.metadata_archive.remove_metadata_archive,
+            "get_metadata_archive_status": self.metadata_archive.get_metadata_archive_status,
+            "get_model_versions_status": self.model_library.get_model_versions_status,
+            "open_file_location": self.filesystem.open_file_location,
+        }
+
+
+def build_service_registry_adapter() -> ServiceRegistryAdapter:
+    return ServiceRegistryAdapter(
+        get_lora_scanner=ServiceRegistry.get_lora_scanner,
+        get_checkpoint_scanner=ServiceRegistry.get_checkpoint_scanner,
+        get_embedding_scanner=ServiceRegistry.get_embedding_scanner,
+    )

py/routes/handlers/preview_handlers.py

@@ -0,0 +1,56 @@
+"""Handlers responsible for serving preview assets dynamically."""
+
+from __future__ import annotations
+
+import logging
+import urllib.parse
+from pathlib import Path
+
+from aiohttp import web
+
+from ...config import config as global_config
+
+logger = logging.getLogger(__name__)
+
+
+class PreviewHandler:
+    """Serve preview assets for the active library at request time."""
+
+    def __init__(self, *, config=global_config) -> None:
+        self._config = config
+
+    async def serve_preview(self, request: web.Request) -> web.StreamResponse:
+        """Return the preview file referenced by the encoded ``path`` query."""
+
+        raw_path = request.query.get("path", "")
+        if not raw_path:
+            raise web.HTTPBadRequest(text="Missing 'path' query parameter")
+
+        try:
+            decoded_path = urllib.parse.unquote(raw_path)
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.debug("Failed to decode preview path %s: %s", raw_path, exc)
+            raise web.HTTPBadRequest(text="Invalid preview path encoding") from exc
+
+        normalized = decoded_path.replace("\\", "/")
+        candidate = Path(normalized)
+        try:
+            resolved = candidate.expanduser().resolve(strict=False)
+        except Exception as exc:
+            logger.debug("Failed to resolve preview path %s: %s", normalized, exc)
+            raise web.HTTPBadRequest(text="Unable to resolve preview path") from exc
+
+        resolved_str = str(resolved)
+        if not self._config.is_preview_path_allowed(resolved_str):
+            logger.debug("Rejected preview outside allowed roots: %s", resolved_str)
+            raise web.HTTPForbidden(text="Preview path is not within an allowed directory")
+
+        if not resolved.is_file():
+            logger.debug("Preview file not found at %s", resolved_str)
+            raise web.HTTPNotFound(text="Preview file not found")
+
+        # aiohttp's FileResponse handles range requests and content headers for us.
+        return web.FileResponse(path=resolved, chunk_size=256 * 1024)
+
+
+__all__ = ["PreviewHandler"]

py/routes/handlers/recipe_handlers.py

@@ -0,0 +1,723 @@
+"""Dedicated handler objects for recipe-related routes."""
+from __future__ import annotations
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Dict, Mapping, Optional
+
+from aiohttp import web
+
+from ...config import config
+from ...services.server_i18n import server_i18n as default_server_i18n
+from ...services.settings_manager import SettingsManager
+from ...services.recipes import (
+    RecipeAnalysisService,
+    RecipeDownloadError,
+    RecipeNotFoundError,
+    RecipePersistenceService,
+    RecipeSharingService,
+    RecipeValidationError,
+)
+
+Logger = logging.Logger
+EnsureDependenciesCallable = Callable[[], Awaitable[None]]
+RecipeScannerGetter = Callable[[], Any]
+CivitaiClientGetter = Callable[[], Any]
+
+
+@dataclass(frozen=True)
+class RecipeHandlerSet:
+    """Group of handlers providing recipe route implementations."""
+
+    page_view: "RecipePageView"
+    listing: "RecipeListingHandler"
+    query: "RecipeQueryHandler"
+    management: "RecipeManagementHandler"
+    analysis: "RecipeAnalysisHandler"
+    sharing: "RecipeSharingHandler"
+
+    def to_route_mapping(self) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
+        """Expose handler coroutines keyed by registrar handler names."""
+
+        return {
+            "render_page": self.page_view.render_page,
+            "list_recipes": self.listing.list_recipes,
+            "get_recipe": self.listing.get_recipe,
+            "analyze_uploaded_image": self.analysis.analyze_uploaded_image,
+            "analyze_local_image": self.analysis.analyze_local_image,
+            "save_recipe": self.management.save_recipe,
+            "delete_recipe": self.management.delete_recipe,
+            "get_top_tags": self.query.get_top_tags,
+            "get_base_models": self.query.get_base_models,
+            "share_recipe": self.sharing.share_recipe,
+            "download_shared_recipe": self.sharing.download_shared_recipe,
+            "get_recipe_syntax": self.query.get_recipe_syntax,
+            "update_recipe": self.management.update_recipe,
+            "reconnect_lora": self.management.reconnect_lora,
+            "find_duplicates": self.query.find_duplicates,
+            "bulk_delete": self.management.bulk_delete,
+            "save_recipe_from_widget": self.management.save_recipe_from_widget,
+            "get_recipes_for_lora": self.query.get_recipes_for_lora,
+            "scan_recipes": self.query.scan_recipes,
+        }
+
+
+class RecipePageView:
+    """Render the recipe shell page."""
+
+    def __init__(
+        self,
+        *,
+        ensure_dependencies_ready: EnsureDependenciesCallable,
+        settings_service: SettingsManager,
+        server_i18n=default_server_i18n,
+        template_env,
+        template_name: str,
+        recipe_scanner_getter: RecipeScannerGetter,
+        logger: Logger,
+    ) -> None:
+        self._ensure_dependencies_ready = ensure_dependencies_ready
+        self._settings = settings_service
+        self._server_i18n = server_i18n
+        self._template_env = template_env
+        self._template_name = template_name
+        self._recipe_scanner_getter = recipe_scanner_getter
+        self._logger = logger
+
+    async def render_page(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:  # pragma: no cover - defensive guard
+                raise RuntimeError("Recipe scanner not available")
+
+            user_language = self._settings.get("language", "en")
+            self._server_i18n.set_locale(user_language)
+
+            try:
+                await recipe_scanner.get_cached_data(force_refresh=False)
+                rendered = self._template_env.get_template(self._template_name).render(
+                    recipes=[],
+                    is_initializing=False,
+                    settings=self._settings,
+                    request=request,
+                    t=self._server_i18n.get_translation,
+                )
+            except Exception as cache_error:  # pragma: no cover - logging path
+                self._logger.error("Error loading recipe cache data: %s", cache_error)
+                rendered = self._template_env.get_template(self._template_name).render(
+                    is_initializing=True,
+                    settings=self._settings,
+                    request=request,
+                    t=self._server_i18n.get_translation,
+                )
+            return web.Response(text=rendered, content_type="text/html")
+        except Exception as exc:  # pragma: no cover - logging path
+            self._logger.error("Error handling recipes request: %s", exc, exc_info=True)
+            return web.Response(text="Error loading recipes page", status=500)
+
+
+class RecipeListingHandler:
+    """Provide listing and detail APIs for recipes."""
+
+    def __init__(
+        self,
+        *,
+        ensure_dependencies_ready: EnsureDependenciesCallable,
+        recipe_scanner_getter: RecipeScannerGetter,
+        logger: Logger,
+    ) -> None:
+        self._ensure_dependencies_ready = ensure_dependencies_ready
+        self._recipe_scanner_getter = recipe_scanner_getter
+        self._logger = logger
+
+    async def list_recipes(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            page = int(request.query.get("page", "1"))
+            page_size = int(request.query.get("page_size", "20"))
+            sort_by = request.query.get("sort_by", "date")
+            search = request.query.get("search")
+
+            search_options = {
+                "title": request.query.get("search_title", "true").lower() == "true",
+                "tags": request.query.get("search_tags", "true").lower() == "true",
+                "lora_name": request.query.get("search_lora_name", "true").lower() == "true",
+                "lora_model": request.query.get("search_lora_model", "true").lower() == "true",
+            }
+
+            filters: Dict[str, list[str]] = {}
+            base_models = request.query.get("base_models")
+            if base_models:
+                filters["base_model"] = base_models.split(",")
+
+            tags = request.query.get("tags")
+            if tags:
+                filters["tags"] = tags.split(",")
+
+            lora_hash = request.query.get("lora_hash")
+
+            result = await recipe_scanner.get_paginated_data(
+                page=page,
+                page_size=page_size,
+                sort_by=sort_by,
+                search=search,
+                filters=filters,
+                search_options=search_options,
+                lora_hash=lora_hash,
+            )
+
+            for item in result.get("items", []):
+                file_path = item.get("file_path")
+                if file_path:
+                    item["file_url"] = self.format_recipe_file_url(file_path)
+                else:
+                    item.setdefault("file_url", "/loras_static/images/no-preview.png")
+                item.setdefault("loras", [])
+                item.setdefault("base_model", "")
+
+            return web.json_response(result)
+        except Exception as exc:
+            self._logger.error("Error retrieving recipes: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    async def get_recipe(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            recipe_id = request.match_info["recipe_id"]
+            recipe = await recipe_scanner.get_recipe_by_id(recipe_id)
+
+            if not recipe:
+                return web.json_response({"error": "Recipe not found"}, status=404)
+            return web.json_response(recipe)
+        except Exception as exc:
+            self._logger.error("Error retrieving recipe details: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    def format_recipe_file_url(self, file_path: str) -> str:
+        try:
+            normalized_path = os.path.normpath(file_path)
+            static_url = config.get_preview_static_url(normalized_path)
+            if static_url:
+                return static_url
+        except Exception as exc:  # pragma: no cover - logging path
+            self._logger.error("Error formatting recipe file URL: %s", exc, exc_info=True)
+            return "/loras_static/images/no-preview.png"
+
+        return "/loras_static/images/no-preview.png"
+
+
+class RecipeQueryHandler:
+    """Provide read-only insights on recipe data."""
+
+    def __init__(
+        self,
+        *,
+        ensure_dependencies_ready: EnsureDependenciesCallable,
+        recipe_scanner_getter: RecipeScannerGetter,
+        format_recipe_file_url: Callable[[str], str],
+        logger: Logger,
+    ) -> None:
+        self._ensure_dependencies_ready = ensure_dependencies_ready
+        self._recipe_scanner_getter = recipe_scanner_getter
+        self._format_recipe_file_url = format_recipe_file_url
+        self._logger = logger
+
+    async def get_top_tags(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            limit = int(request.query.get("limit", "20"))
+            cache = await recipe_scanner.get_cached_data()
+
+            tag_counts: Dict[str, int] = {}
+            for recipe in getattr(cache, "raw_data", []):
+                for tag in recipe.get("tags", []) or []:
+                    tag_counts[tag] = tag_counts.get(tag, 0) + 1
+
+            sorted_tags = [{"tag": tag, "count": count} for tag, count in tag_counts.items()]
+            sorted_tags.sort(key=lambda entry: entry["count"], reverse=True)
+            return web.json_response({"success": True, "tags": sorted_tags[:limit]})
+        except Exception as exc:
+            self._logger.error("Error retrieving top tags: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_base_models(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            cache = await recipe_scanner.get_cached_data()
+
+            base_model_counts: Dict[str, int] = {}
+            for recipe in getattr(cache, "raw_data", []):
+                base_model = recipe.get("base_model")
+                if base_model:
+                    base_model_counts[base_model] = base_model_counts.get(base_model, 0) + 1
+
+            sorted_models = [{"name": model, "count": count} for model, count in base_model_counts.items()]
+            sorted_models.sort(key=lambda entry: entry["count"], reverse=True)
+            return web.json_response({"success": True, "base_models": sorted_models})
+        except Exception as exc:
+            self._logger.error("Error retrieving base models: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_recipes_for_lora(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            lora_hash = request.query.get("hash")
+            if not lora_hash:
+                return web.json_response({"success": False, "error": "Lora hash is required"}, status=400)
+
+            matching_recipes = await recipe_scanner.get_recipes_for_lora(lora_hash)
+            return web.json_response({"success": True, "recipes": matching_recipes})
+        except Exception as exc:
+            self._logger.error("Error getting recipes for Lora: %s", exc)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def scan_recipes(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            self._logger.info("Manually triggering recipe cache rebuild")
+            await recipe_scanner.get_cached_data(force_refresh=True)
+            return web.json_response({"success": True, "message": "Recipe cache refreshed successfully"})
+        except Exception as exc:
+            self._logger.error("Error refreshing recipe cache: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def find_duplicates(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            duplicate_groups = await recipe_scanner.find_all_duplicate_recipes()
+            response_data = []
+
+            for fingerprint, recipe_ids in duplicate_groups.items():
+                if len(recipe_ids) <= 1:
+                    continue
+
+                recipes = []
+                for recipe_id in recipe_ids:
+                    recipe = await recipe_scanner.get_recipe_by_id(recipe_id)
+                    if recipe:
+                        recipes.append(
+                            {
+                                "id": recipe.get("id"),
+                                "title": recipe.get("title"),
+                                "file_url": recipe.get("file_url")
+                                or self._format_recipe_file_url(recipe.get("file_path", "")),
+                                "modified": recipe.get("modified"),
+                                "created_date": recipe.get("created_date"),
+                                "lora_count": len(recipe.get("loras", [])),
+                            }
+                        )
+
+                if len(recipes) >= 2:
+                    recipes.sort(key=lambda entry: entry.get("modified", 0), reverse=True)
+                    response_data.append(
+                        {
+                            "fingerprint": fingerprint,
+                            "count": len(recipes),
+                            "recipes": recipes,
+                        }
+                    )
+
+            response_data.sort(key=lambda entry: entry["count"], reverse=True)
+            return web.json_response({"success": True, "duplicate_groups": response_data})
+        except Exception as exc:
+            self._logger.error("Error finding duplicate recipes: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def get_recipe_syntax(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            recipe_id = request.match_info["recipe_id"]
+            try:
+                syntax_parts = await recipe_scanner.get_recipe_syntax_tokens(recipe_id)
+            except RecipeNotFoundError:
+                return web.json_response({"error": "Recipe not found"}, status=404)
+
+            if not syntax_parts:
+                return web.json_response({"error": "No LoRAs found in this recipe"}, status=400)
+
+            return web.json_response({"success": True, "syntax": " ".join(syntax_parts)})
+        except Exception as exc:
+            self._logger.error("Error generating recipe syntax: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+
+class RecipeManagementHandler:
+    """Handle create/update/delete style recipe operations."""
+
+    def __init__(
+        self,
+        *,
+        ensure_dependencies_ready: EnsureDependenciesCallable,
+        recipe_scanner_getter: RecipeScannerGetter,
+        logger: Logger,
+        persistence_service: RecipePersistenceService,
+        analysis_service: RecipeAnalysisService,
+    ) -> None:
+        self._ensure_dependencies_ready = ensure_dependencies_ready
+        self._recipe_scanner_getter = recipe_scanner_getter
+        self._logger = logger
+        self._persistence_service = persistence_service
+        self._analysis_service = analysis_service
+
+    async def save_recipe(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            reader = await request.multipart()
+            payload = await self._parse_save_payload(reader)
+
+            result = await self._persistence_service.save_recipe(
+                recipe_scanner=recipe_scanner,
+                image_bytes=payload["image_bytes"],
+                image_base64=payload["image_base64"],
+                name=payload["name"],
+                tags=payload["tags"],
+                metadata=payload["metadata"],
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeValidationError as exc:
+            return web.json_response({"error": str(exc)}, status=400)
+        except Exception as exc:
+            self._logger.error("Error saving recipe: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    async def delete_recipe(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            recipe_id = request.match_info["recipe_id"]
+            result = await self._persistence_service.delete_recipe(
+                recipe_scanner=recipe_scanner, recipe_id=recipe_id
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeNotFoundError as exc:
+            return web.json_response({"error": str(exc)}, status=404)
+        except Exception as exc:
+            self._logger.error("Error deleting recipe: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    async def update_recipe(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            recipe_id = request.match_info["recipe_id"]
+            data = await request.json()
+            result = await self._persistence_service.update_recipe(
+                recipe_scanner=recipe_scanner, recipe_id=recipe_id, updates=data
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeValidationError as exc:
+            return web.json_response({"error": str(exc)}, status=400)
+        except RecipeNotFoundError as exc:
+            return web.json_response({"error": str(exc)}, status=404)
+        except Exception as exc:
+            self._logger.error("Error updating recipe: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    async def reconnect_lora(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            data = await request.json()
+            for field in ("recipe_id", "lora_index", "target_name"):
+                if field not in data:
+                    raise RecipeValidationError(f"Missing required field: {field}")
+
+            result = await self._persistence_service.reconnect_lora(
+                recipe_scanner=recipe_scanner,
+                recipe_id=data["recipe_id"],
+                lora_index=int(data["lora_index"]),
+                target_name=data["target_name"],
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeValidationError as exc:
+            return web.json_response({"error": str(exc)}, status=400)
+        except RecipeNotFoundError as exc:
+            return web.json_response({"error": str(exc)}, status=404)
+        except Exception as exc:
+            self._logger.error("Error reconnecting LoRA: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    async def bulk_delete(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            data = await request.json()
+            recipe_ids = data.get("recipe_ids", [])
+            result = await self._persistence_service.bulk_delete(
+                recipe_scanner=recipe_scanner, recipe_ids=recipe_ids
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeValidationError as exc:
+            return web.json_response({"success": False, "error": str(exc)}, status=400)
+        except RecipeNotFoundError as exc:
+            return web.json_response({"success": False, "error": str(exc)}, status=404)
+        except Exception as exc:
+            self._logger.error("Error performing bulk delete: %s", exc, exc_info=True)
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+    async def save_recipe_from_widget(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            analysis = await self._analysis_service.analyze_widget_metadata(
+                recipe_scanner=recipe_scanner
+            )
+            metadata = analysis.payload.get("metadata")
+            image_bytes = analysis.payload.get("image_bytes")
+            if not metadata or image_bytes is None:
+                raise RecipeValidationError("Unable to extract metadata from widget")
+
+            result = await self._persistence_service.save_recipe_from_widget(
+                recipe_scanner=recipe_scanner,
+                metadata=metadata,
+                image_bytes=image_bytes,
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeValidationError as exc:
+            return web.json_response({"error": str(exc)}, status=400)
+        except Exception as exc:
+            self._logger.error("Error saving recipe from widget: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    async def _parse_save_payload(self, reader) -> dict[str, Any]:
+        image_bytes: Optional[bytes] = None
+        image_base64: Optional[str] = None
+        name: Optional[str] = None
+        tags: list[str] = []
+        metadata: Optional[Dict[str, Any]] = None
+
+        while True:
+            field = await reader.next()
+            if field is None:
+                break
+            if field.name == "image":
+                image_chunks = bytearray()
+                while True:
+                    chunk = await field.read_chunk()
+                    if not chunk:
+                        break
+                    image_chunks.extend(chunk)
+                image_bytes = bytes(image_chunks)
+            elif field.name == "image_base64":
+                image_base64 = await field.text()
+            elif field.name == "name":
+                name = await field.text()
+            elif field.name == "tags":
+                tags_text = await field.text()
+                try:
+                    parsed_tags = json.loads(tags_text)
+                    tags = parsed_tags if isinstance(parsed_tags, list) else []
+                except Exception:
+                    tags = []
+            elif field.name == "metadata":
+                metadata_text = await field.text()
+                try:
+                    metadata = json.loads(metadata_text)
+                except Exception:
+                    metadata = {}
+
+        return {
+            "image_bytes": image_bytes,
+            "image_base64": image_base64,
+            "name": name,
+            "tags": tags,
+            "metadata": metadata,
+        }
+
+
+class RecipeAnalysisHandler:
+    """Analyze images to extract recipe metadata."""
+
+    def __init__(
+        self,
+        *,
+        ensure_dependencies_ready: EnsureDependenciesCallable,
+        recipe_scanner_getter: RecipeScannerGetter,
+        civitai_client_getter: CivitaiClientGetter,
+        logger: Logger,
+        analysis_service: RecipeAnalysisService,
+    ) -> None:
+        self._ensure_dependencies_ready = ensure_dependencies_ready
+        self._recipe_scanner_getter = recipe_scanner_getter
+        self._civitai_client_getter = civitai_client_getter
+        self._logger = logger
+        self._analysis_service = analysis_service
+
+    async def analyze_uploaded_image(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            civitai_client = self._civitai_client_getter()
+            if recipe_scanner is None or civitai_client is None:
+                raise RuntimeError("Required services unavailable")
+
+            content_type = request.headers.get("Content-Type", "")
+            if "multipart/form-data" in content_type:
+                reader = await request.multipart()
+                field = await reader.next()
+                if field is None or field.name != "image":
+                    raise RecipeValidationError("No image field found")
+                image_chunks = bytearray()
+                while True:
+                    chunk = await field.read_chunk()
+                    if not chunk:
+                        break
+                    image_chunks.extend(chunk)
+                result = await self._analysis_service.analyze_uploaded_image(
+                    image_bytes=bytes(image_chunks),
+                    recipe_scanner=recipe_scanner,
+                )
+                return web.json_response(result.payload, status=result.status)
+
+            if "application/json" in content_type:
+                data = await request.json()
+                result = await self._analysis_service.analyze_remote_image(
+                    url=data.get("url"),
+                    recipe_scanner=recipe_scanner,
+                    civitai_client=civitai_client,
+                )
+                return web.json_response(result.payload, status=result.status)
+
+            raise RecipeValidationError("Unsupported content type")
+        except RecipeValidationError as exc:
+            return web.json_response({"error": str(exc), "loras": []}, status=400)
+        except RecipeDownloadError as exc:
+            return web.json_response({"error": str(exc), "loras": []}, status=400)
+        except RecipeNotFoundError as exc:
+            return web.json_response({"error": str(exc), "loras": []}, status=404)
+        except Exception as exc:
+            self._logger.error("Error analyzing recipe image: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc), "loras": []}, status=500)
+
+    async def analyze_local_image(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            data = await request.json()
+            result = await self._analysis_service.analyze_local_image(
+                file_path=data.get("path"),
+                recipe_scanner=recipe_scanner,
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeValidationError as exc:
+            return web.json_response({"error": str(exc), "loras": []}, status=400)
+        except RecipeNotFoundError as exc:
+            return web.json_response({"error": str(exc), "loras": []}, status=404)
+        except Exception as exc:
+            self._logger.error("Error analyzing local image: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc), "loras": []}, status=500)
+
+
+class RecipeSharingHandler:
+    """Serve endpoints related to recipe sharing."""
+
+    def __init__(
+        self,
+        *,
+        ensure_dependencies_ready: EnsureDependenciesCallable,
+        recipe_scanner_getter: RecipeScannerGetter,
+        logger: Logger,
+        sharing_service: RecipeSharingService,
+    ) -> None:
+        self._ensure_dependencies_ready = ensure_dependencies_ready
+        self._recipe_scanner_getter = recipe_scanner_getter
+        self._logger = logger
+        self._sharing_service = sharing_service
+
+    async def share_recipe(self, request: web.Request) -> web.Response:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            recipe_id = request.match_info["recipe_id"]
+            result = await self._sharing_service.share_recipe(
+                recipe_scanner=recipe_scanner, recipe_id=recipe_id
+            )
+            return web.json_response(result.payload, status=result.status)
+        except RecipeNotFoundError as exc:
+            return web.json_response({"error": str(exc)}, status=404)
+        except Exception as exc:
+            self._logger.error("Error sharing recipe: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    async def download_shared_recipe(self, request: web.Request) -> web.StreamResponse:
+        try:
+            await self._ensure_dependencies_ready()
+            recipe_scanner = self._recipe_scanner_getter()
+            if recipe_scanner is None:
+                raise RuntimeError("Recipe scanner unavailable")
+
+            recipe_id = request.match_info["recipe_id"]
+            download_info = await self._sharing_service.prepare_download(
+                recipe_scanner=recipe_scanner, recipe_id=recipe_id
+            )
+            return web.FileResponse(
+                download_info.file_path,
+                headers={
+                    "Content-Disposition": f'attachment; filename="{download_info.download_filename}"'
+                },
+            )
+        except RecipeNotFoundError as exc:
+            return web.json_response({"error": str(exc)}, status=404)
+        except Exception as exc:
+            self._logger.error("Error downloading shared recipe: %s", exc, exc_info=True)
+            return web.json_response({"error": str(exc)}, status=500)

py/routes/lora_routes.py

@@ -5,9 +5,9 @@ from typing import Dict
 from server import PromptServer  # type: ignore
 
 from .base_model_routes import BaseModelRoutes
+from .model_route_registrar import ModelRouteRegistrar
 from ..services.lora_service import LoraService
 from ..services.service_registry import ServiceRegistry
-from ..utils.routes_common import ModelRouteUtils
 from ..utils.utils import get_lora_info
 
 logger = logging.getLogger(__name__)
@@ -17,42 +17,36 @@ class LoraRoutes(BaseModelRoutes):
     
     def __init__(self):
         """Initialize LoRA routes with LoRA service"""
-        # Service will be initialized later via setup_routes
-        self.service = None
-        self.civitai_client = None
+        super().__init__()
         self.template_name = "loras.html"
     
     async def initialize_services(self):
         """Initialize services from ServiceRegistry"""
         lora_scanner = await ServiceRegistry.get_lora_scanner()
-        self.service = LoraService(lora_scanner)
-        self.civitai_client = await ServiceRegistry.get_civitai_client()
-        
-        # Initialize parent with the service
-        super().__init__(self.service)
+        update_service = await ServiceRegistry.get_model_update_service()
+        self.service = LoraService(lora_scanner, update_service=update_service)
+        self.set_model_update_service(update_service)
+
+        # Attach service dependencies
+        self.attach_service(self.service)
     
     def setup_routes(self, app: web.Application):
         """Setup LoRA routes"""
         # Schedule service initialization on app startup
         app.on_startup.append(lambda _: self.initialize_services())
-        
+
         # Setup common routes with 'loras' prefix (includes page route)
         super().setup_routes(app, 'loras')
-    
-    def setup_specific_routes(self, app: web.Application, prefix: str):
+
+    def setup_specific_routes(self, registrar: ModelRouteRegistrar, prefix: str):
         """Setup LoRA-specific routes"""
         # LoRA-specific query routes
-        app.router.add_get(f'/api/{prefix}/letter-counts', self.get_letter_counts)
-        app.router.add_get(f'/api/{prefix}/get-trigger-words', self.get_lora_trigger_words)
-        app.router.add_get(f'/api/{prefix}/usage-tips-by-path', self.get_lora_usage_tips_by_path)
-        
-        # CivitAI integration with LoRA-specific validation
-        app.router.add_get(f'/api/{prefix}/civitai/versions/{{model_id}}', self.get_civitai_versions_lora)
-        app.router.add_get(f'/api/{prefix}/civitai/model/version/{{modelVersionId}}', self.get_civitai_model_by_version)
-        app.router.add_get(f'/api/{prefix}/civitai/model/hash/{{hash}}', self.get_civitai_model_by_hash)
-        
+        registrar.add_prefixed_route('GET', '/api/lm/{prefix}/letter-counts', prefix, self.get_letter_counts)
+        registrar.add_prefixed_route('GET', '/api/lm/{prefix}/get-trigger-words', prefix, self.get_lora_trigger_words)
+        registrar.add_prefixed_route('GET', '/api/lm/{prefix}/usage-tips-by-path', prefix, self.get_lora_usage_tips_by_path)
+
         # ComfyUI integration
-        app.router.add_post(f'/api/{prefix}/get_trigger_words', self.get_trigger_words)
+        registrar.add_prefixed_route('POST', '/api/lm/{prefix}/get_trigger_words', prefix, self.get_trigger_words)
     
     def _parse_specific_params(self, request: web.Request) -> Dict:
         """Parse LoRA-specific parameters"""
@@ -78,6 +72,15 @@ class LoraRoutes(BaseModelRoutes):
         
         return params
     
+    def _validate_civitai_model_type(self, model_type: str) -> bool:
+        """Validate CivitAI model type for LoRA"""
+        from ..utils.constants import VALID_LORA_TYPES
+        return model_type.lower() in VALID_LORA_TYPES
+    
+    def _get_expected_model_types(self) -> str:
+        """Get expected model types string for error messages"""
+        return "LORA, LoCon, or DORA"
+    
     # LoRA-specific route handlers
     async def get_letter_counts(self, request: web.Request) -> web.Response:
         """Get count of LoRAs for each letter of the alphabet"""
@@ -212,91 +215,6 @@ class LoraRoutes(BaseModelRoutes):
                 'error': str(e)
             }, status=500)
     
-    # CivitAI integration methods
-    async def get_civitai_versions_lora(self, request: web.Request) -> web.Response:
-        """Get available versions for a Civitai LoRA model with local availability info"""
-        try:
-            model_id = request.match_info['model_id']
-            response = await self.civitai_client.get_model_versions(model_id)
-            if not response or not response.get('modelVersions'):
-                return web.Response(status=404, text="Model not found")
-            
-            versions = response.get('modelVersions', [])
-            model_type = response.get('type', '')
-            
-            # Check model type - should be LORA, LoCon, or DORA
-            from ..utils.constants import VALID_LORA_TYPES
-            if model_type.lower() not in VALID_LORA_TYPES:
-                return web.json_response({
-                    'error': f"Model type mismatch. Expected LORA or LoCon, got {model_type}"
-                }, status=400)
-            
-            # Check local availability for each version
-            for version in versions:
-                # Find the model file (type="Model") in the files list
-                model_file = next((file for file in version.get('files', []) 
-                                  if file.get('type') == 'Model'), None)
-                
-                if model_file:
-                    sha256 = model_file.get('hashes', {}).get('SHA256')
-                    if sha256:
-                        # Set existsLocally and localPath at the version level
-                        version['existsLocally'] = self.service.has_hash(sha256)
-                        if version['existsLocally']:
-                            version['localPath'] = self.service.get_path_by_hash(sha256)
-                        
-                        # Also set the model file size at the version level for easier access
-                        version['modelSizeKB'] = model_file.get('sizeKB')
-                else:
-                    # No model file found in this version
-                    version['existsLocally'] = False
-                    
-            return web.json_response(versions)
-        except Exception as e:
-            logger.error(f"Error fetching LoRA model versions: {e}")
-            return web.Response(status=500, text=str(e))
-    
-    async def get_civitai_model_by_version(self, request: web.Request) -> web.Response:
-        """Get CivitAI model details by model version ID"""
-        try:
-            model_version_id = request.match_info.get('modelVersionId')
-            
-            # Get model details from Civitai API    
-            model, error_msg = await self.civitai_client.get_model_version_info(model_version_id)
-            
-            if not model:
-                # Log warning for failed model retrieval
-                logger.warning(f"Failed to fetch model version {model_version_id}: {error_msg}")
-                
-                # Determine status code based on error message
-                status_code = 404 if error_msg and "not found" in error_msg.lower() else 500
-                
-                return web.json_response({
-                    "success": False,
-                    "error": error_msg or "Failed to fetch model information"
-                }, status=status_code)
-                
-            return web.json_response(model)
-        except Exception as e:
-            logger.error(f"Error fetching model details: {e}")
-            return web.json_response({
-                "success": False,
-                "error": str(e)
-            }, status=500)
-    
-    async def get_civitai_model_by_hash(self, request: web.Request) -> web.Response:
-        """Get CivitAI model details by hash"""
-        try:
-            hash = request.match_info.get('hash')
-            model = await self.civitai_client.get_model_by_hash(hash)
-            return web.json_response(model)
-        except Exception as e:
-            logger.error(f"Error fetching model details by hash: {e}")
-            return web.json_response({
-                "success": False,
-                "error": str(e)
-            }, status=500)
-    
     async def get_trigger_words(self, request: web.Request) -> web.Response:
         """Get trigger words for specified LoRA models"""
         try:
@@ -313,11 +231,27 @@ class LoraRoutes(BaseModelRoutes):
             trigger_words_text = ",, ".join(all_trigger_words) if all_trigger_words else ""
             
             # Send update to all connected trigger word toggle nodes
-            for node_id in node_ids:
-                PromptServer.instance.send_sync("trigger_word_update", {
-                    "id": node_id,
+            for entry in node_ids:
+                node_identifier = entry
+                graph_identifier = None
+                if isinstance(entry, dict):
+                    node_identifier = entry.get("node_id")
+                    graph_identifier = entry.get("graph_id")
+
+                try:
+                    parsed_node_id = int(node_identifier)
+                except (TypeError, ValueError):
+                    parsed_node_id = node_identifier
+
+                payload = {
+                    "id": parsed_node_id,
                     "message": trigger_words_text
-                })
+                }
+
+                if graph_identifier is not None:
+                    payload["graph_id"] = str(graph_identifier)
+
+                PromptServer.instance.send_sync("trigger_word_update", payload)
             
             return web.json_response({"success": True})
 

py/routes/misc_route_registrar.py

@@ -0,0 +1,71 @@
+"""Route registrar for miscellaneous endpoints.
+
+This module mirrors the model route registrar architecture so that
+miscellaneous endpoints share a consistent registration flow.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, Mapping
+
+from aiohttp import web
+
+
+@dataclass(frozen=True)
+class RouteDefinition:
+    """Declarative definition for a HTTP route."""
+
+    method: str
+    path: str
+    handler_name: str
+
+
+MISC_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
+    RouteDefinition("GET", "/api/lm/settings", "get_settings"),
+    RouteDefinition("POST", "/api/lm/settings", "update_settings"),
+    RouteDefinition("GET", "/api/lm/priority-tags", "get_priority_tags"),
+    RouteDefinition("GET", "/api/lm/settings/libraries", "get_settings_libraries"),
+    RouteDefinition("POST", "/api/lm/settings/libraries/activate", "activate_library"),
+    RouteDefinition("GET", "/api/lm/health-check", "health_check"),
+    RouteDefinition("POST", "/api/lm/open-file-location", "open_file_location"),
+    RouteDefinition("POST", "/api/lm/update-usage-stats", "update_usage_stats"),
+    RouteDefinition("GET", "/api/lm/get-usage-stats", "get_usage_stats"),
+    RouteDefinition("POST", "/api/lm/update-lora-code", "update_lora_code"),
+    RouteDefinition("GET", "/api/lm/trained-words", "get_trained_words"),
+    RouteDefinition("GET", "/api/lm/model-example-files", "get_model_example_files"),
+    RouteDefinition("POST", "/api/lm/register-nodes", "register_nodes"),
+    RouteDefinition("GET", "/api/lm/get-registry", "get_registry"),
+    RouteDefinition("GET", "/api/lm/check-model-exists", "check_model_exists"),
+    RouteDefinition("GET", "/api/lm/civitai/user-models", "get_civitai_user_models"),
+    RouteDefinition("POST", "/api/lm/download-metadata-archive", "download_metadata_archive"),
+    RouteDefinition("POST", "/api/lm/remove-metadata-archive", "remove_metadata_archive"),
+    RouteDefinition("GET", "/api/lm/metadata-archive-status", "get_metadata_archive_status"),
+    RouteDefinition("GET", "/api/lm/model-versions-status", "get_model_versions_status"),
+)
+
+
+class MiscRouteRegistrar:
+    """Bind miscellaneous route definitions to an aiohttp router."""
+
+    _METHOD_MAP = {
+        "GET": "add_get",
+        "POST": "add_post",
+        "PUT": "add_put",
+        "DELETE": "add_delete",
+    }
+
+    def __init__(self, app: web.Application) -> None:
+        self._app = app
+
+    def register_routes(
+        self,
+        handler_lookup: Mapping[str, Callable[[web.Request], object]],
+        *,
+        definitions: Iterable[RouteDefinition] = MISC_ROUTE_DEFINITIONS,
+    ) -> None:
+        for definition in definitions:
+            self._bind(definition.method, definition.path, handler_lookup[definition.handler_name])
+
+    def _bind(self, method: str, path: str, handler: Callable) -> None:
+        add_method_name = self._METHOD_MAP[method.upper()]
+        add_method = getattr(self._app.router, add_method_name)
+        add_method(path, handler)

py/routes/misc_routes.py

@@ -1,699 +1,135 @@
+"""Route controller for miscellaneous endpoints."""
+
+from __future__ import annotations
+
 import logging
 import os
-import sys
-import threading
-import asyncio
-from server import PromptServer # type: ignore
+from typing import Awaitable, Callable, Mapping
+
 from aiohttp import web
-from ..services.settings_manager import settings
+from server import PromptServer  # type: ignore
+
+from ..services.metadata_service import (
+    get_metadata_archive_manager,
+    get_metadata_provider,
+    update_metadata_providers,
+)
+from ..services.settings_manager import get_settings_manager
+from ..services.downloader import get_downloader
 from ..utils.usage_stats import UsageStats
-from ..utils.lora_metadata import extract_trained_words
-from ..config import config
-from ..utils.constants import SUPPORTED_MEDIA_EXTENSIONS, NODE_TYPES, DEFAULT_NODE_COLOR
-from ..services.service_registry import ServiceRegistry
-import re
+from .handlers.misc_handlers import (
+    FileSystemHandler,
+    HealthCheckHandler,
+    LoraCodeHandler,
+    MetadataArchiveHandler,
+    MiscHandlerSet,
+    ModelExampleFilesHandler,
+    ModelLibraryHandler,
+    NodeRegistry,
+    NodeRegistryHandler,
+    SettingsHandler,
+    TrainedWordsHandler,
+    UsageStatsHandler,
+    build_service_registry_adapter,
+)
+from .misc_route_registrar import MiscRouteRegistrar
 
 logger = logging.getLogger(__name__)
 
-standalone_mode = 'nodes' not in sys.modules
+standalone_mode = os.environ.get("LORA_MANAGER_STANDALONE", "0") == "1" or os.environ.get(
+    "HF_HUB_DISABLE_TELEMETRY", "0"
+) == "0"
 
-# Node registry for tracking active workflow nodes
-class NodeRegistry:
-    """Thread-safe registry for tracking Lora nodes in active workflows"""
-    
-    def __init__(self):
-        self._lock = threading.RLock()
-        self._nodes = {}  # node_id -> node_info
-        self._registry_updated = threading.Event()
-    
-    def register_nodes(self, nodes):
-        """Register multiple nodes at once, replacing existing registry"""
-        with self._lock:
-            # Clear existing registry
-            self._nodes.clear()
-            
-            # Register all new nodes
-            for node in nodes:
-                node_id = node['node_id']
-                node_type = node.get('type', '')
-                
-                # Convert node type name to integer
-                type_id = NODE_TYPES.get(node_type, 0)  # 0 for unknown types
-                
-                # Handle null bgcolor with default color
-                bgcolor = node.get('bgcolor')
-                if bgcolor is None:
-                    bgcolor = DEFAULT_NODE_COLOR
-                
-                self._nodes[node_id] = {
-                    'id': node_id,
-                    'bgcolor': bgcolor,
-                    'title': node.get('title'),
-                    'type': type_id,
-                    'type_name': node_type
-                }
-            
-            logger.debug(f"Registered {len(nodes)} nodes in registry")
-            
-            # Signal that registry has been updated
-            self._registry_updated.set()
-    
-    def get_registry(self):
-        """Get current registry information"""
-        with self._lock:
-            return {
-                'nodes': dict(self._nodes),  # Return a copy
-                'node_count': len(self._nodes)
-            }
-    
-    def clear_registry(self):
-        """Clear the entire registry"""
-        with self._lock:
-            self._nodes.clear()
-            logger.info("Node registry cleared")
-    
-    def wait_for_update(self, timeout=1.0):
-        """Wait for registry update with timeout"""
-        self._registry_updated.clear()
-        return self._registry_updated.wait(timeout)
-
-# Global registry instance
-node_registry = NodeRegistry()
 
 class MiscRoutes:
-    """Miscellaneous routes for various utility functions"""
-    
-    @staticmethod
-    def setup_routes(app):
-        """Register miscellaneous routes"""
-        app.router.add_post('/api/settings', MiscRoutes.update_settings)
-        
-        # Add new route for clearing cache
-        app.router.add_post('/api/clear-cache', MiscRoutes.clear_cache)
+    """Route controller that mirrors the model route architecture."""
 
-        app.router.add_get('/api/health-check', lambda request: web.json_response({'status': 'ok'}))
+    def __init__(
+        self,
+        *,
+        settings_service=None,
+        usage_stats_factory: Callable[[], UsageStats] = UsageStats,
+        prompt_server: type[PromptServer] = PromptServer,
+        service_registry_adapter=build_service_registry_adapter(),
+        metadata_provider_factory=get_metadata_provider,
+        metadata_archive_manager_factory=get_metadata_archive_manager,
+        metadata_provider_updater=update_metadata_providers,
+        downloader_factory=get_downloader,
+        registrar_factory=MiscRouteRegistrar,
+        handler_set_factory=MiscHandlerSet,
+        node_registry: NodeRegistry | None = None,
+        standalone_mode_flag: bool = standalone_mode,
+    ) -> None:
+        self._settings = settings_service or get_settings_manager()
+        self._usage_stats_factory = usage_stats_factory
+        self._prompt_server = prompt_server
+        self._service_registry_adapter = service_registry_adapter
+        self._metadata_provider_factory = metadata_provider_factory
+        self._metadata_archive_manager_factory = metadata_archive_manager_factory
+        self._metadata_provider_updater = metadata_provider_updater
+        self._downloader_factory = downloader_factory
+        self._registrar_factory = registrar_factory
+        self._handler_set_factory = handler_set_factory
+        self._node_registry = node_registry or NodeRegistry()
+        self._standalone_mode = standalone_mode_flag
 
-        # Usage stats routes
-        app.router.add_post('/api/update-usage-stats', MiscRoutes.update_usage_stats)
-        app.router.add_get('/api/get-usage-stats', MiscRoutes.get_usage_stats)
-        
-        # Lora code update endpoint
-        app.router.add_post('/api/update-lora-code', MiscRoutes.update_lora_code)
-
-        # Add new route for getting trained words
-        app.router.add_get('/api/trained-words', MiscRoutes.get_trained_words)
-        
-        # Add new route for getting model example files
-        app.router.add_get('/api/model-example-files', MiscRoutes.get_model_example_files)
-        
-        # Node registry endpoints
-        app.router.add_post('/api/register-nodes', MiscRoutes.register_nodes)
-        app.router.add_get('/api/get-registry', MiscRoutes.get_registry)
-        
-        # Add new route for checking if a model exists in the library
-        app.router.add_get('/api/check-model-exists', MiscRoutes.check_model_exists)
+        self._handler_mapping: Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]] | None = None
 
     @staticmethod
-    async def clear_cache(request):
-        """Clear all cache files from the cache folder"""
-        try:
-            # Get the cache folder path (relative to project directory)
-            project_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-            cache_folder = os.path.join(project_dir, 'cache')
-            
-            # Check if cache folder exists
-            if not os.path.exists(cache_folder):
-                logger.info("Cache folder does not exist, nothing to clear")
-                return web.json_response({'success': True, 'message': 'No cache folder found'})
-            
-            # Get list of cache files before deleting for reporting
-            cache_files = [f for f in os.listdir(cache_folder) if os.path.isfile(os.path.join(cache_folder, f))]
-            deleted_files = []
-            
-            # Delete each .msgpack file in the cache folder
-            for filename in cache_files:
-                if filename.endswith('.msgpack'):
-                    file_path = os.path.join(cache_folder, filename)
-                    try:
-                        os.remove(file_path)
-                        deleted_files.append(filename)
-                        logger.info(f"Deleted cache file: {filename}")
-                    except Exception as e:
-                        logger.error(f"Failed to delete {filename}: {e}")
-                        return web.json_response({
-                            'success': False,
-                            'error': f"Failed to delete {filename}: {str(e)}"
-                        }, status=500)
-            
-            return web.json_response({
-                'success': True,
-                'message': f"Successfully cleared {len(deleted_files)} cache files",
-                'deleted_files': deleted_files
-            })
-            
-        except Exception as e:
-            logger.error(f"Error clearing cache files: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
+    def setup_routes(app: web.Application) -> None:
+        """Entry point used by the application bootstrap."""
+        controller = MiscRoutes()
+        controller.bind(app)
 
-    @staticmethod
-    async def update_settings(request):
-        """Update application settings"""
-        try:
-            data = await request.json()
-            
-            # Validate and update settings
-            for key, value in data.items():
-                if value == settings.get(key):
-                    # No change, skip
-                    continue
-                # Special handling for example_images_path - verify path exists
-                if key == 'example_images_path' and value:
-                    if not os.path.exists(value):
-                        return web.json_response({
-                            'success': False,
-                            'error': f"Path does not exist: {value}"
-                        })
-                    
-                    # Path changed - server restart required for new path to take effect
-                    old_path = settings.get('example_images_path')
-                    if old_path != value:
-                        logger.info(f"Example images path changed to {value} - server restart required")
-                
-                # Save to settings
-                settings.set(key, value)
-            
-            return web.json_response({'success': True})
-        except Exception as e:
-            logger.error(f"Error updating settings: {e}", exc_info=True)
-            return web.Response(status=500, text=str(e))
-    
-    @staticmethod
-    async def update_usage_stats(request):
-        """
-        Update usage statistics based on a prompt_id
-        
-        Expects a JSON body with:
-        {
-            "prompt_id": "string"
-        }
-        """
-        try:
-            # Parse the request body
-            data = await request.json()
-            prompt_id = data.get('prompt_id')
-            
-            if not prompt_id:
-                return web.json_response({
-                    'success': False,
-                    'error': 'Missing prompt_id'
-                }, status=400)
-            
-            # Call the UsageStats to process this prompt_id synchronously
-            usage_stats = UsageStats()
-            await usage_stats.process_execution(prompt_id)
-            
-            return web.json_response({
-                'success': True
-            })
-            
-        except Exception as e:
-            logger.error(f"Failed to update usage stats: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
-    
-    @staticmethod
-    async def get_usage_stats(request):
-        """Get current usage statistics"""
-        try:
-            usage_stats = UsageStats()
-            stats = await usage_stats.get_stats()
-            
-            # Add version information to help clients handle format changes
-            stats_response = {
-                'success': True,
-                'data': stats,
-                'format_version': 2  # Indicate this is the new format with history
-            }
-            
-            return web.json_response(stats_response)
-            
-        except Exception as e:
-            logger.error(f"Failed to get usage stats: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
-    
-    @staticmethod
-    async def update_lora_code(request):
-        """
-        Update Lora code in ComfyUI nodes
-        
-        Expects a JSON body with:
-        {
-            "node_ids": [123, 456], # Optional - List of node IDs to update (for browser mode)
-            "lora_code": "<lora:modelname:1.0>", # The Lora code to send
-            "mode": "append" # or "replace" - whether to append or replace existing code
-        }
-        """
-        try:
-            # Parse the request body
-            data = await request.json()
-            node_ids = data.get('node_ids')
-            lora_code = data.get('lora_code', '')
-            mode = data.get('mode', 'append')
-            
-            if not lora_code:
-                return web.json_response({
-                    'success': False,
-                    'error': 'Missing lora_code parameter'
-                }, status=400)
-            
-            results = []
-            
-            # Desktop mode: no specific node_ids provided
-            if node_ids is None:
-                try:
-                    # Send broadcast message with id=-1 to all Lora Loader nodes
-                    PromptServer.instance.send_sync("lora_code_update", {
-                        "id": -1,
-                        "lora_code": lora_code,
-                        "mode": mode
-                    })
-                    results.append({
-                        'node_id': 'broadcast',
-                        'success': True
-                    })
-                except Exception as e:
-                    logger.error(f"Error broadcasting lora code: {e}")
-                    results.append({
-                        'node_id': 'broadcast',
-                        'success': False,
-                        'error': str(e)
-                    })
-            else:
-                # Browser mode: send to specific nodes
-                for node_id in node_ids:
-                    try:
-                        # Send the message to the frontend
-                        PromptServer.instance.send_sync("lora_code_update", {
-                            "id": node_id,
-                            "lora_code": lora_code,
-                            "mode": mode
-                        })
-                        results.append({
-                            'node_id': node_id,
-                            'success': True
-                        })
-                    except Exception as e:
-                        logger.error(f"Error sending lora code to node {node_id}: {e}")
-                        results.append({
-                            'node_id': node_id,
-                            'success': False,
-                            'error': str(e)
-                        })
-            
-            return web.json_response({
-                'success': True,
-                'results': results
-            })
-            
-        except Exception as e:
-            logger.error(f"Failed to update lora code: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
+    def bind(self, app: web.Application) -> None:
+        registrar = self._registrar_factory(app)
+        registrar.register_routes(self._ensure_handler_mapping())
 
-    @staticmethod
-    async def get_trained_words(request):
-        """
-        Get trained words from a safetensors file, sorted by frequency
-        
-        Expects a query parameter:
-        file_path: Path to the safetensors file
-        """
-        try:
-            # Get file path from query parameters
-            file_path = request.query.get('file_path')
-            
-            if not file_path:
-                return web.json_response({
-                    'success': False,
-                    'error': 'Missing file_path parameter'
-                }, status=400)
-            
-            # Check if file exists and is a safetensors file
-            if not os.path.exists(file_path):
-                return web.json_response({
-                    'success': False,
-                    'error': f"File not found: {file_path}"
-                }, status=404)
-                
-            if not file_path.lower().endswith('.safetensors'):
-                return web.json_response({
-                    'success': False,
-                    'error': 'File is not a safetensors file'
-                }, status=400)
-            
-            # Extract trained words and class_tokens
-            trained_words, class_tokens = await extract_trained_words(file_path)
-            
-            # Return result with both trained words and class tokens
-            return web.json_response({
-                'success': True,
-                'trained_words': trained_words,
-                'class_tokens': class_tokens
-            })
-            
-        except Exception as e:
-            logger.error(f"Failed to get trained words: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
+    def _ensure_handler_mapping(self) -> Mapping[str, Callable[[web.Request], Awaitable[web.StreamResponse]]]:
+        if self._handler_mapping is None:
+            handler_set = self._create_handler_set()
+            self._handler_mapping = handler_set.to_route_mapping()
+        return self._handler_mapping
 
-    @staticmethod
-    async def get_model_example_files(request):
-        """
-        Get list of example image files for a specific model based on file path
-        
-        Expects:
-        - file_path in query parameters
-        
-        Returns:
-        - List of image files with their paths as static URLs
-        """
-        try:
-            # Get the model file path from query parameters
-            file_path = request.query.get('file_path')
-            
-            if not file_path:
-                return web.json_response({
-                    'success': False,
-                    'error': 'Missing file_path parameter'
-                }, status=400)
-            
-            # Extract directory and base filename
-            model_dir = os.path.dirname(file_path)
-            model_filename = os.path.basename(file_path)
-            model_name = os.path.splitext(model_filename)[0]
-            
-            # Check if the directory exists
-            if not os.path.exists(model_dir):
-                return web.json_response({
-                    'success': False, 
-                    'error': 'Model directory not found',
-                    'files': []
-                }, status=404)
-            
-            # Look for files matching the pattern modelname.example.<index>.<ext>
-            files = []
-            pattern = f"{model_name}.example."
-            
-            for file in os.listdir(model_dir):
-                file_lower = file.lower()
-                if file_lower.startswith(pattern.lower()):
-                    file_full_path = os.path.join(model_dir, file)
-                    if os.path.isfile(file_full_path):
-                        # Check if the file is a supported media file
-                        file_ext = os.path.splitext(file)[1].lower()
-                        if (file_ext in SUPPORTED_MEDIA_EXTENSIONS['images'] or 
-                            file_ext in SUPPORTED_MEDIA_EXTENSIONS['videos']):
-                            
-                            # Extract the index from the filename
-                            try:
-                                # Extract the part after '.example.' and before file extension
-                                index_part = file[len(pattern):].split('.')[0]
-                                # Try to parse it as an integer
-                                index = int(index_part)
-                            except (ValueError, IndexError):
-                                # If we can't parse the index, use infinity to sort at the end
-                                index = float('inf')
-                            
-                            # Convert file path to static URL
-                            static_url = config.get_preview_static_url(file_full_path)
-                            
-                            files.append({
-                                'name': file,
-                                'path': static_url,
-                                'extension': file_ext,
-                                'is_video': file_ext in SUPPORTED_MEDIA_EXTENSIONS['videos'],
-                                'index': index
-                            })
-            
-            # Sort files by their index for consistent ordering
-            files.sort(key=lambda x: x['index'])
-            # Remove the index field as it's only used for sorting
-            for file in files:
-                file.pop('index', None)
-            
-            return web.json_response({
-                'success': True,
-                'files': files
-            })
-            
-        except Exception as e:
-            logger.error(f"Failed to get model example files: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
+    def _create_handler_set(self) -> MiscHandlerSet:
+        health = HealthCheckHandler()
+        settings_handler = SettingsHandler(
+            settings_service=self._settings,
+            metadata_provider_updater=self._metadata_provider_updater,
+            downloader_factory=self._downloader_factory,
+        )
+        usage_stats = UsageStatsHandler(usage_stats_factory=self._usage_stats_factory)
+        lora_code = LoraCodeHandler(prompt_server=self._prompt_server)
+        trained_words = TrainedWordsHandler()
+        model_examples = ModelExampleFilesHandler()
+        metadata_archive = MetadataArchiveHandler(
+            metadata_archive_manager_factory=self._metadata_archive_manager_factory,
+            settings_service=self._settings,
+            metadata_provider_updater=self._metadata_provider_updater,
+        )
+        filesystem = FileSystemHandler()
+        node_registry_handler = NodeRegistryHandler(
+            node_registry=self._node_registry,
+            prompt_server=self._prompt_server,
+            standalone_mode=self._standalone_mode,
+        )
+        model_library = ModelLibraryHandler(
+            service_registry=self._service_registry_adapter,
+            metadata_provider_factory=self._metadata_provider_factory,
+        )
 
-    @staticmethod
-    async def register_nodes(request):
-        """
-        Register multiple Lora nodes at once
-        
-        Expects a JSON body with:
-        {
-            "nodes": [
-                {
-                    "node_id": 123,
-                    "bgcolor": "#535",
-                    "title": "Lora Loader (LoraManager)"
-                },
-                ...
-            ]
-        }
-        """
-        try:
-            data = await request.json()
-            
-            # Validate required fields
-            nodes = data.get('nodes', [])
-            
-            if not isinstance(nodes, list):
-                return web.json_response({
-                    'success': False,
-                    'error': 'nodes must be a list'
-                }, status=400)
-            
-            # Validate each node
-            for i, node in enumerate(nodes):
-                if not isinstance(node, dict):
-                    return web.json_response({
-                        'success': False,
-                        'error': f'Node {i} must be an object'
-                    }, status=400)
-                
-                node_id = node.get('node_id')
-                if node_id is None:
-                    return web.json_response({
-                        'success': False,
-                        'error': f'Node {i} missing node_id parameter'
-                    }, status=400)
-                
-                # Validate node_id is an integer
-                try:
-                    node['node_id'] = int(node_id)
-                except (ValueError, TypeError):
-                    return web.json_response({
-                        'success': False,
-                        'error': f'Node {i} node_id must be an integer'
-                    }, status=400)
-            
-            # Register all nodes
-            node_registry.register_nodes(nodes)
-            
-            return web.json_response({
-                'success': True,
-                'message': f'{len(nodes)} nodes registered successfully'
-            })
-            
-        except Exception as e:
-            logger.error(f"Failed to register nodes: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
-    
-    @staticmethod
-    async def get_registry(request):
-        """Get current node registry information by refreshing from frontend"""
-        try:
-            # Check if running in standalone mode
-            if standalone_mode:
-                logger.warning("Registry refresh not available in standalone mode")
-                return web.json_response({
-                    'success': False,
-                    'error': 'Standalone Mode Active',
-                    'message': 'Cannot interact with ComfyUI in standalone mode.'
-                }, status=503)
-            
-            # Send message to frontend to refresh registry
-            try:
-                PromptServer.instance.send_sync("lora_registry_refresh", {})
-                logger.debug("Sent registry refresh request to frontend")
-            except Exception as e:
-                logger.error(f"Failed to send registry refresh message: {e}")
-                return web.json_response({
-                    'success': False,
-                    'error': 'Communication Error',
-                    'message': f'Failed to communicate with ComfyUI frontend: {str(e)}'
-                }, status=500)
-            
-            # Wait for registry update with timeout
-            def wait_for_registry():
-                return node_registry.wait_for_update(timeout=1.0)
-            
-            # Run the wait in a thread to avoid blocking the event loop
-            loop = asyncio.get_event_loop()
-            registry_updated = await loop.run_in_executor(None, wait_for_registry)
-            
-            if not registry_updated:
-                logger.warning("Registry refresh timeout after 1 second")
-                return web.json_response({
-                    'success': False,
-                    'error': 'Timeout Error',
-                    'message': 'Registry refresh timeout - ComfyUI frontend may not be responsive'
-                }, status=408)
-            
-            # Get updated registry
-            registry_info = node_registry.get_registry()
-            
-            return web.json_response({
-                'success': True,
-                'data': registry_info
-            })
-            
-        except Exception as e:
-            logger.error(f"Failed to get registry: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': 'Internal Error',
-                'message': str(e)
-            }, status=500)
+        return self._handler_set_factory(
+            health=health,
+            settings=settings_handler,
+            usage_stats=usage_stats,
+            lora_code=lora_code,
+            trained_words=trained_words,
+            model_examples=model_examples,
+            node_registry=node_registry_handler,
+            model_library=model_library,
+            metadata_archive=metadata_archive,
+            filesystem=filesystem,
+        )
 
-    @staticmethod
-    async def check_model_exists(request):
-        """
-        Check if a model with specified modelId and optionally modelVersionId exists in the library
-        
-        Expects query parameters:
-        - modelId: int - Civitai model ID (required)
-        - modelVersionId: int - Civitai model version ID (optional)
-        
-        Returns:
-        - If modelVersionId is provided: JSON with a boolean 'exists' field
-        - If modelVersionId is not provided: JSON with a list of modelVersionIds that exist in the library
-        """
-        try:
-            # Get the modelId and modelVersionId from query parameters
-            model_id_str = request.query.get('modelId')
-            model_version_id_str = request.query.get('modelVersionId')
-            
-            # Validate modelId parameter (required)
-            if not model_id_str:
-                return web.json_response({
-                    'success': False,
-                    'error': 'Missing required parameter: modelId'
-                }, status=400)
-                
-            try:
-                # Convert modelId to integer
-                model_id = int(model_id_str)
-            except ValueError:
-                return web.json_response({
-                    'success': False,
-                    'error': 'Parameter modelId must be an integer'
-                }, status=400)
-            
-            # Get all scanners
-            lora_scanner = await ServiceRegistry.get_lora_scanner()
-            checkpoint_scanner = await ServiceRegistry.get_checkpoint_scanner()
-            embedding_scanner = await ServiceRegistry.get_embedding_scanner()
-            
-            # If modelVersionId is provided, check for specific version
-            if model_version_id_str:
-                try:
-                    model_version_id = int(model_version_id_str)
-                except ValueError:
-                    return web.json_response({
-                        'success': False,
-                        'error': 'Parameter modelVersionId must be an integer'
-                    }, status=400)
-                
-                # Check lora scanner first
-                exists = False
-                model_type = None
 
-                if await lora_scanner.check_model_version_exists(model_version_id):
-                    exists = True
-                    model_type = 'lora'
-                elif checkpoint_scanner and await checkpoint_scanner.check_model_version_exists(model_version_id):
-                    exists = True
-                    model_type = 'checkpoint'
-                elif embedding_scanner and await embedding_scanner.check_model_version_exists(model_version_id):
-                    exists = True
-                    model_type = 'embedding'
-                
-                return web.json_response({
-                    'success': True,
-                    'exists': exists,
-                    'modelType': model_type if exists else None
-                })
-            
-            # If modelVersionId is not provided, return all version IDs for the model
-            else:
-                lora_versions = await lora_scanner.get_model_versions_by_id(model_id)
-                checkpoint_versions = []
-                embedding_versions = []
-
-                # 优先lora，其次checkpoint，最后embedding
-                if not lora_versions:
-                    checkpoint_versions = await checkpoint_scanner.get_model_versions_by_id(model_id)
-                if not lora_versions and not checkpoint_versions:
-                    embedding_versions = await embedding_scanner.get_model_versions_by_id(model_id)
-
-                model_type = None
-                versions = []
-
-                if lora_versions:
-                    model_type = 'lora'
-                    versions = lora_versions
-                elif checkpoint_versions:
-                    model_type = 'checkpoint'
-                    versions = checkpoint_versions
-                elif embedding_versions:
-                    model_type = 'embedding'
-                    versions = embedding_versions
-
-                return web.json_response({
-                    'success': True,
-                    'modelId': model_id,
-                    'modelType': model_type,
-                    'versions': versions
-                })
-            
-        except Exception as e:
-            logger.error(f"Failed to check model existence: {e}", exc_info=True)
-            return web.json_response({
-                'success': False,
-                'error': str(e)
-            }, status=500)
+__all__ = ["MiscRoutes"]

py/routes/model_route_registrar.py

@@ -0,0 +1,104 @@
+"""Route registrar for model endpoints."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, Mapping
+
+from aiohttp import web
+
+
+@dataclass(frozen=True)
+class RouteDefinition:
+    """Declarative definition for a HTTP route."""
+
+    method: str
+    path_template: str
+    handler_name: str
+
+    def build_path(self, prefix: str) -> str:
+        return self.path_template.replace("{prefix}", prefix)
+
+
+COMMON_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
+    RouteDefinition("GET", "/api/lm/{prefix}/list", "get_models"),
+    RouteDefinition("POST", "/api/lm/{prefix}/delete", "delete_model"),
+    RouteDefinition("POST", "/api/lm/{prefix}/exclude", "exclude_model"),
+    RouteDefinition("POST", "/api/lm/{prefix}/fetch-civitai", "fetch_civitai"),
+    RouteDefinition("POST", "/api/lm/{prefix}/fetch-all-civitai", "fetch_all_civitai"),
+    RouteDefinition("POST", "/api/lm/{prefix}/relink-civitai", "relink_civitai"),
+    RouteDefinition("POST", "/api/lm/{prefix}/replace-preview", "replace_preview"),
+    RouteDefinition("POST", "/api/lm/{prefix}/save-metadata", "save_metadata"),
+    RouteDefinition("POST", "/api/lm/{prefix}/add-tags", "add_tags"),
+    RouteDefinition("POST", "/api/lm/{prefix}/rename", "rename_model"),
+    RouteDefinition("POST", "/api/lm/{prefix}/bulk-delete", "bulk_delete_models"),
+    RouteDefinition("POST", "/api/lm/{prefix}/verify-duplicates", "verify_duplicates"),
+    RouteDefinition("POST", "/api/lm/{prefix}/move_model", "move_model"),
+    RouteDefinition("POST", "/api/lm/{prefix}/move_models_bulk", "move_models_bulk"),
+    RouteDefinition("GET", "/api/lm/{prefix}/auto-organize", "auto_organize_models"),
+    RouteDefinition("POST", "/api/lm/{prefix}/auto-organize", "auto_organize_models"),
+    RouteDefinition("GET", "/api/lm/{prefix}/auto-organize-progress", "get_auto_organize_progress"),
+    RouteDefinition("GET", "/api/lm/{prefix}/top-tags", "get_top_tags"),
+    RouteDefinition("GET", "/api/lm/{prefix}/base-models", "get_base_models"),
+    RouteDefinition("GET", "/api/lm/{prefix}/scan", "scan_models"),
+    RouteDefinition("GET", "/api/lm/{prefix}/roots", "get_model_roots"),
+    RouteDefinition("GET", "/api/lm/{prefix}/folders", "get_folders"),
+    RouteDefinition("GET", "/api/lm/{prefix}/folder-tree", "get_folder_tree"),
+    RouteDefinition("GET", "/api/lm/{prefix}/unified-folder-tree", "get_unified_folder_tree"),
+    RouteDefinition("GET", "/api/lm/{prefix}/find-duplicates", "find_duplicate_models"),
+    RouteDefinition("GET", "/api/lm/{prefix}/find-filename-conflicts", "find_filename_conflicts"),
+    RouteDefinition("GET", "/api/lm/{prefix}/get-notes", "get_model_notes"),
+    RouteDefinition("GET", "/api/lm/{prefix}/preview-url", "get_model_preview_url"),
+    RouteDefinition("GET", "/api/lm/{prefix}/civitai-url", "get_model_civitai_url"),
+    RouteDefinition("GET", "/api/lm/{prefix}/metadata", "get_model_metadata"),
+    RouteDefinition("GET", "/api/lm/{prefix}/model-description", "get_model_description"),
+    RouteDefinition("GET", "/api/lm/{prefix}/relative-paths", "get_relative_paths"),
+    RouteDefinition("GET", "/api/lm/{prefix}/civitai/versions/{model_id}", "get_civitai_versions"),
+    RouteDefinition("GET", "/api/lm/{prefix}/civitai/model/version/{modelVersionId}", "get_civitai_model_by_version"),
+    RouteDefinition("GET", "/api/lm/{prefix}/civitai/model/hash/{hash}", "get_civitai_model_by_hash"),
+    RouteDefinition("POST", "/api/lm/{prefix}/updates/refresh", "refresh_model_updates"),
+    RouteDefinition("POST", "/api/lm/{prefix}/updates/ignore", "set_model_update_ignore"),
+    RouteDefinition("GET", "/api/lm/{prefix}/updates/status/{model_id}", "get_model_update_status"),
+    RouteDefinition("POST", "/api/lm/download-model", "download_model"),
+    RouteDefinition("GET", "/api/lm/download-model-get", "download_model_get"),
+    RouteDefinition("GET", "/api/lm/cancel-download-get", "cancel_download_get"),
+    RouteDefinition("GET", "/api/lm/pause-download", "pause_download_get"),
+    RouteDefinition("GET", "/api/lm/resume-download", "resume_download_get"),
+    RouteDefinition("GET", "/api/lm/download-progress/{download_id}", "get_download_progress"),
+    RouteDefinition("GET", "/{prefix}", "handle_models_page"),
+)
+
+
+class ModelRouteRegistrar:
+    """Bind declarative definitions to an aiohttp router."""
+
+    _METHOD_MAP = {
+        "GET": "add_get",
+        "POST": "add_post",
+        "PUT": "add_put",
+        "DELETE": "add_delete",
+    }
+
+    def __init__(self, app: web.Application) -> None:
+        self._app = app
+
+    def register_common_routes(
+        self,
+        prefix: str,
+        handler_lookup: Mapping[str, Callable[[web.Request], object]],
+        *,
+        definitions: Iterable[RouteDefinition] = COMMON_ROUTE_DEFINITIONS,
+    ) -> None:
+        for definition in definitions:
+            self._bind_route(definition.method, definition.build_path(prefix), handler_lookup[definition.handler_name])
+
+    def add_route(self, method: str, path: str, handler: Callable) -> None:
+        self._bind_route(method, path, handler)
+
+    def add_prefixed_route(self, method: str, path_template: str, prefix: str, handler: Callable) -> None:
+        self._bind_route(method, path_template.replace("{prefix}", prefix), handler)
+
+    def _bind_route(self, method: str, path: str, handler: Callable) -> None:
+        add_method_name = self._METHOD_MAP[method.upper()]
+        add_method = getattr(self._app.router, add_method_name)
+        add_method(path, handler)
+

py/routes/preview_routes.py

@@ -0,0 +1,25 @@
+"""Route controller for preview asset delivery."""
+
+from __future__ import annotations
+
+from aiohttp import web
+
+from .handlers.preview_handlers import PreviewHandler
+
+
+class PreviewRoutes:
+    """Register routes that expose preview assets."""
+
+    def __init__(self, *, handler: PreviewHandler | None = None) -> None:
+        self._handler = handler or PreviewHandler()
+
+    @classmethod
+    def setup_routes(cls, app: web.Application) -> None:
+        controller = cls()
+        controller.register(app)
+
+    def register(self, app: web.Application) -> None:
+        app.router.add_get('/api/lm/previews', self._handler.serve_preview)
+
+
+__all__ = ["PreviewRoutes"]

py/routes/recipe_route_registrar.py

@@ -0,0 +1,64 @@
+"""Route registrar for recipe endpoints."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Mapping
+
+from aiohttp import web
+
+
+@dataclass(frozen=True)
+class RouteDefinition:
+    """Declarative definition for a recipe HTTP route."""
+
+    method: str
+    path: str
+    handler_name: str
+
+
+ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
+    RouteDefinition("GET", "/loras/recipes", "render_page"),
+    RouteDefinition("GET", "/api/lm/recipes", "list_recipes"),
+    RouteDefinition("GET", "/api/lm/recipe/{recipe_id}", "get_recipe"),
+    RouteDefinition("POST", "/api/lm/recipes/analyze-image", "analyze_uploaded_image"),
+    RouteDefinition("POST", "/api/lm/recipes/analyze-local-image", "analyze_local_image"),
+    RouteDefinition("POST", "/api/lm/recipes/save", "save_recipe"),
+    RouteDefinition("DELETE", "/api/lm/recipe/{recipe_id}", "delete_recipe"),
+    RouteDefinition("GET", "/api/lm/recipes/top-tags", "get_top_tags"),
+    RouteDefinition("GET", "/api/lm/recipes/base-models", "get_base_models"),
+    RouteDefinition("GET", "/api/lm/recipe/{recipe_id}/share", "share_recipe"),
+    RouteDefinition("GET", "/api/lm/recipe/{recipe_id}/share/download", "download_shared_recipe"),
+    RouteDefinition("GET", "/api/lm/recipe/{recipe_id}/syntax", "get_recipe_syntax"),
+    RouteDefinition("PUT", "/api/lm/recipe/{recipe_id}/update", "update_recipe"),
+    RouteDefinition("POST", "/api/lm/recipe/lora/reconnect", "reconnect_lora"),
+    RouteDefinition("GET", "/api/lm/recipes/find-duplicates", "find_duplicates"),
+    RouteDefinition("POST", "/api/lm/recipes/bulk-delete", "bulk_delete"),
+    RouteDefinition("POST", "/api/lm/recipes/save-from-widget", "save_recipe_from_widget"),
+    RouteDefinition("GET", "/api/lm/recipes/for-lora", "get_recipes_for_lora"),
+    RouteDefinition("GET", "/api/lm/recipes/scan", "scan_recipes"),
+)
+
+
+class RecipeRouteRegistrar:
+    """Bind declarative recipe definitions to an aiohttp router."""
+
+    _METHOD_MAP = {
+        "GET": "add_get",
+        "POST": "add_post",
+        "PUT": "add_put",
+        "DELETE": "add_delete",
+    }
+
+    def __init__(self, app: web.Application) -> None:
+        self._app = app
+
+    def register_routes(self, handler_lookup: Mapping[str, Callable[[web.Request], object]]) -> None:
+        for definition in ROUTE_DEFINITIONS:
+            handler = handler_lookup[definition.handler_name]
+            self._bind_route(definition.method, definition.path, handler)
+
+    def _bind_route(self, method: str, path: str, handler: Callable) -> None:
+        add_method_name = self._METHOD_MAP[method.upper()]
+        add_method = getattr(self._app.router, add_method_name)
+        add_method(path, handler)
+

py/routes/stats_routes.py

@@ -8,13 +8,32 @@ from collections import defaultdict, Counter
 from typing import Dict, List, Any
 
 from ..config import config
-from ..services.settings_manager import settings
+from ..services.settings_manager import get_settings_manager
 from ..services.server_i18n import server_i18n
 from ..services.service_registry import ServiceRegistry
 from ..utils.usage_stats import UsageStats
 
 logger = logging.getLogger(__name__)
 
+
+class _SettingsProxy:
+    def __init__(self):
+        self._manager = None
+
+    def _resolve(self):
+        if self._manager is None:
+            self._manager = get_settings_manager()
+        return self._manager
+
+    def get(self, *args, **kwargs):
+        return self._resolve().get(*args, **kwargs)
+
+    def __getattr__(self, item):
+        return getattr(self._resolve(), item)
+
+
+settings = _SettingsProxy()
+
 class StatsRoutes:
     """Route handlers for Statistics page and API endpoints"""
     
@@ -33,7 +52,13 @@ class StatsRoutes:
         self.lora_scanner = await ServiceRegistry.get_lora_scanner()
         self.checkpoint_scanner = await ServiceRegistry.get_checkpoint_scanner()
         self.embedding_scanner = await ServiceRegistry.get_embedding_scanner()
-        self.usage_stats = UsageStats()
+        
+        # Only initialize usage stats if we have valid paths configured
+        try:
+            self.usage_stats = UsageStats()
+        except RuntimeError as e:
+            logger.warning(f"Could not initialize usage statistics: {e}")
+            self.usage_stats = None
 
     async def handle_stats_page(self, request: web.Request) -> web.Response:
         """Handle GET /statistics request"""
@@ -60,7 +85,9 @@ class StatsRoutes:
             is_initializing = lora_initializing or checkpoint_initializing or embedding_initializing
 
             # 获取用户语言设置
-            user_language = settings.get('language', 'en')
+            settings_object = settings
+            user_language = settings_object.get('language', 'en')
+            settings_manager = settings_object if not isinstance(settings_object, _SettingsProxy) else settings_object._resolve()
             
             # 设置服务端i18n语言
             server_i18n.set_locale(user_language)
@@ -73,7 +100,7 @@ class StatsRoutes:
             template = self.template_env.get_template('statistics.html')
             rendered = template.render(
                 is_initializing=is_initializing,
-                settings=settings,
+                settings=settings_manager,
                 request=request,
                 t=server_i18n.get_translation,
             )
@@ -501,12 +528,12 @@ class StatsRoutes:
         app.router.add_get('/statistics', self.handle_stats_page)
         
         # Register API routes
-        app.router.add_get('/api/stats/collection-overview', self.get_collection_overview)
-        app.router.add_get('/api/stats/usage-analytics', self.get_usage_analytics)
-        app.router.add_get('/api/stats/base-model-distribution', self.get_base_model_distribution)
-        app.router.add_get('/api/stats/tag-analytics', self.get_tag_analytics)
-        app.router.add_get('/api/stats/storage-analytics', self.get_storage_analytics)
-        app.router.add_get('/api/stats/insights', self.get_insights)
+        app.router.add_get('/api/lm/stats/collection-overview', self.get_collection_overview)
+        app.router.add_get('/api/lm/stats/usage-analytics', self.get_usage_analytics)
+        app.router.add_get('/api/lm/stats/base-model-distribution', self.get_base_model_distribution)
+        app.router.add_get('/api/lm/stats/tag-analytics', self.get_tag_analytics)
+        app.router.add_get('/api/lm/stats/storage-analytics', self.get_storage_analytics)
+        app.router.add_get('/api/lm/stats/insights', self.get_insights)
         
     async def _on_startup(self, app):
         """Initialize services when the app starts"""

py/routes/update_routes.py

@@ -1,26 +1,31 @@
 import os
-import aiohttp
 import logging
 import toml
 import git
 import zipfile
 import shutil
 import tempfile
-from aiohttp import web
+import asyncio
+from aiohttp import web, ClientError
 from typing import Dict, List
 
+from ..utils.settings_paths import ensure_settings_file
+from ..services.downloader import get_downloader
 
 logger = logging.getLogger(__name__)
 
+NETWORK_EXCEPTIONS = (ClientError, OSError, asyncio.TimeoutError)
+
+
 class UpdateRoutes:
     """Routes for handling plugin update checks"""
     
     @staticmethod
     def setup_routes(app):
         """Register update check routes"""
-        app.router.add_get('/api/check-updates', UpdateRoutes.check_updates)
-        app.router.add_get('/api/version-info', UpdateRoutes.get_version_info)
-        app.router.add_post('/api/perform-update', UpdateRoutes.perform_update)
+        app.router.add_get('/api/lm/check-updates', UpdateRoutes.check_updates)
+        app.router.add_get('/api/lm/version-info', UpdateRoutes.get_version_info)
+        app.router.add_post('/api/lm/perform-update', UpdateRoutes.perform_update)
     
     @staticmethod
     async def check_updates(request):
@@ -64,6 +69,12 @@ class UpdateRoutes:
                 'nightly': nightly
             })
             
+        except NETWORK_EXCEPTIONS as e:
+            logger.warning("Network unavailable during update check: %s", e)
+            return web.json_response({
+                'success': False,
+                'error': 'Network unavailable for update check'
+            })
         except Exception as e:
             logger.error(f"Failed to check for updates: {e}", exc_info=True)
             return web.json_response({
@@ -112,7 +123,7 @@ class UpdateRoutes:
             current_dir = os.path.dirname(os.path.abspath(__file__))
             plugin_root = os.path.dirname(os.path.dirname(current_dir))
 
-            settings_path = os.path.join(plugin_root, 'settings.json')
+            settings_path = ensure_settings_file(logger)
             settings_backup = None
             if os.path.exists(settings_path):
                 with open(settings_path, 'r', encoding='utf-8') as f:
@@ -155,51 +166,66 @@ class UpdateRoutes:
     async def _download_and_replace_zip(plugin_root: str) -> tuple[bool, str]:
         """
         Download latest release ZIP from GitHub and replace plugin files.
-        Skips settings.json. Writes extracted file list to .tracking.
+        Skips settings.json and civitai folder. Writes extracted file list to .tracking.
         """
         repo_owner = "willmiao"
         repo_name = "ComfyUI-Lora-Manager"
         github_api = f"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest"
 
         try:
-            async with aiohttp.ClientSession() as session:
-                async with session.get(github_api) as resp:
-                    if resp.status != 200:
-                        logger.error(f"Failed to fetch release info: {resp.status}")
-                        return False, ""
-                    data = await resp.json()
-                    zip_url = data.get("zipball_url")
-                    version = data.get("tag_name", "unknown")
+            downloader = await get_downloader()
+            
+            # Get release info
+            success, data = await downloader.make_request(
+                'GET',
+                github_api,
+                use_auth=False
+            )
+            if not success:
+                logger.error(f"Failed to fetch release info: {data}")
+                return False, ""
+            
+            zip_url = data.get("zipball_url")
+            version = data.get("tag_name", "unknown")
 
-                # Download ZIP
-                async with session.get(zip_url) as zip_resp:
-                    if zip_resp.status != 200:
-                        logger.error(f"Failed to download ZIP: {zip_resp.status}")
-                        return False, ""
-                    with tempfile.NamedTemporaryFile(delete=False, suffix=".zip") as tmp_zip:
-                        tmp_zip.write(await zip_resp.read())
-                        zip_path = tmp_zip.name
+            # Download ZIP to temporary file
+            with tempfile.NamedTemporaryFile(delete=False, suffix=".zip") as tmp_zip:
+                tmp_zip_path = tmp_zip.name
+            
+            success, result = await downloader.download_file(
+                url=zip_url,
+                save_path=tmp_zip_path,
+                use_auth=False,
+                allow_resume=False
+            )
+            
+            if not success:
+                logger.error(f"Failed to download ZIP: {result}")
+                return False, ""
 
-                UpdateRoutes._clean_plugin_folder(plugin_root, skip_files=['settings.json'])
+            zip_path = tmp_zip_path
 
-                # Extract ZIP to temp dir
-                with tempfile.TemporaryDirectory() as tmp_dir:
+            # Skip both settings.json and civitai folder
+            UpdateRoutes._clean_plugin_folder(plugin_root, skip_files=['settings.json', 'civitai'])
+
+            # Extract ZIP to temp dir
+            with tempfile.TemporaryDirectory() as tmp_dir:
                     with zipfile.ZipFile(zip_path, 'r') as zip_ref:
                         zip_ref.extractall(tmp_dir)
                     # Find extracted folder (GitHub ZIP contains a root folder)
                     extracted_root = next(os.scandir(tmp_dir)).path
 
-                    # Copy files, skipping settings.json
+                    # Copy files, skipping settings.json and civitai folder
                     for item in os.listdir(extracted_root):
+                        if item == 'settings.json' or item == 'civitai':
+                            continue
                         src = os.path.join(extracted_root, item)
                         dst = os.path.join(plugin_root, item)
                         if os.path.isdir(src):
                             if os.path.exists(dst):
                                 shutil.rmtree(dst)
-                            shutil.copytree(src, dst, ignore=shutil.ignore_patterns('settings.json'))
+                            shutil.copytree(src, dst, ignore=shutil.ignore_patterns('settings.json', 'civitai'))
                         else:
-                            if item == 'settings.json':
-                                continue
                             shutil.copy2(src, dst)
 
                     # Write .tracking file: list all files under extracted_root, relative to extracted_root
@@ -207,15 +233,22 @@ class UpdateRoutes:
                     tracking_info_file = os.path.join(plugin_root, '.tracking')
                     tracking_files = []
                     for root, dirs, files in os.walk(extracted_root):
+                        # Skip civitai folder and its contents
+                        rel_root = os.path.relpath(root, extracted_root)
+                        if rel_root == 'civitai' or rel_root.startswith('civitai' + os.sep):
+                            continue
                         for file in files:
                             rel_path = os.path.relpath(os.path.join(root, file), extracted_root)
+                            # Skip settings.json and any file under civitai
+                            if rel_path == 'settings.json' or rel_path.startswith('civitai' + os.sep):
+                                continue
                             tracking_files.append(rel_path.replace("\\", "/"))
                     with open(tracking_info_file, "w", encoding='utf-8') as file:
                         file.write('\n'.join(tracking_files))
 
-                os.remove(zip_path)
-                logger.info(f"Updated plugin via ZIP to {version}")
-                return True, version
+            os.remove(zip_path)
+            logger.info(f"Updated plugin via ZIP to {version}")
+            return True, version
 
         except Exception as e:
             logger.error(f"ZIP update failed: {e}", exc_info=True)
@@ -244,24 +277,27 @@ class UpdateRoutes:
         github_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/commits/main"
         
         try:
-            async with aiohttp.ClientSession() as session:
-                async with session.get(github_url, headers={'Accept': 'application/vnd.github+json'}) as response:
-                    if response.status != 200:
-                        logger.warning(f"Failed to fetch GitHub commit: {response.status}")
-                        return "main", []
-                    
-                    data = await response.json()
-                    commit_sha = data.get('sha', '')[:7]  # Short hash
-                    commit_message = data.get('commit', {}).get('message', '')
-                    
-                    # Format as "main-{short_hash}"
-                    version = f"main-{commit_sha}"
-                    
-                    # Use commit message as changelog
-                    changelog = [commit_message] if commit_message else []
-                    
-                    return version, changelog
+            downloader = await get_downloader()
+            success, data = await downloader.make_request('GET', github_url, custom_headers={'Accept': 'application/vnd.github+json'})
+            
+            if not success:
+                logger.warning(f"Failed to fetch GitHub commit: {data}")
+                return "main", []
+            
+            commit_sha = data.get('sha', '')[:7]  # Short hash
+            commit_message = data.get('commit', {}).get('message', '')
+            
+            # Format as "main-{short_hash}"
+            version = f"main-{commit_sha}"
+            
+            # Use commit message as changelog
+            changelog = [commit_message] if commit_message else []
+            
+            return version, changelog
         
+        except NETWORK_EXCEPTIONS as e:
+            logger.warning("Unable to reach GitHub for nightly version: %s", e)
+            return "main", []
         except Exception as e:
             logger.error(f"Error fetching nightly version: {e}", exc_info=True)
             return "main", []
@@ -410,23 +446,26 @@ class UpdateRoutes:
         github_url = f"https://api.github.com/repos/{repo_owner}/{repo_name}/releases/latest"
         
         try:
-            async with aiohttp.ClientSession() as session:
-                async with session.get(github_url, headers={'Accept': 'application/vnd.github+json'}) as response:
-                    if response.status != 200:
-                        logger.warning(f"Failed to fetch GitHub release: {response.status}")
-                        return "v0.0.0", []
-                    
-                    data = await response.json()
-                    version = data.get('tag_name', '')
-                    if not version.startswith('v'):
-                        version = f"v{version}"
-                    
-                    # Extract changelog from release notes
-                    body = data.get('body', '')
-                    changelog = UpdateRoutes._parse_changelog(body)
-                    
-                    return version, changelog
+            downloader = await get_downloader()
+            success, data = await downloader.make_request('GET', github_url, custom_headers={'Accept': 'application/vnd.github+json'})
+            
+            if not success:
+                logger.warning(f"Failed to fetch GitHub release: {data}")
+                return "v0.0.0", []
+            
+            version = data.get('tag_name', '')
+            if not version.startswith('v'):
+                version = f"v{version}"
+            
+            # Extract changelog from release notes
+            body = data.get('body', '')
+            changelog = UpdateRoutes._parse_changelog(body)
+            
+            return version, changelog
         
+        except NETWORK_EXCEPTIONS as e:
+            logger.warning("Unable to reach GitHub for release info: %s", e)
+            return "v0.0.0", []
         except Exception as e:
             logger.error(f"Error fetching remote version: {e}", exc_info=True)
             return "v0.0.0", []

py/services/base_model_service.py

@@ -1,102 +1,103 @@
 from abc import ABC, abstractmethod
-from typing import Dict, List, Optional, Type
+import asyncio
+from typing import Dict, List, Optional, Type, TYPE_CHECKING
 import logging
 import os
 
 from ..utils.models import BaseModelMetadata
-from ..utils.routes_common import ModelRouteUtils
-from ..utils.constants import NSFW_LEVELS
-from .settings_manager import settings
-from ..utils.utils import fuzzy_match
+from ..utils.metadata_manager import MetadataManager
+from .model_query import FilterCriteria, ModelCacheRepository, ModelFilterSet, SearchStrategy, SettingsProvider
+from .settings_manager import get_settings_manager
 
 logger = logging.getLogger(__name__)
 
+if TYPE_CHECKING:
+    from .model_update_service import ModelUpdateService
+
 class BaseModelService(ABC):
     """Base service class for all model types"""
     
-    def __init__(self, model_type: str, scanner, metadata_class: Type[BaseModelMetadata]):
-        """Initialize the service
-        
+    def __init__(
+        self,
+        model_type: str,
+        scanner,
+        metadata_class: Type[BaseModelMetadata],
+        *,
+        cache_repository: Optional[ModelCacheRepository] = None,
+        filter_set: Optional[ModelFilterSet] = None,
+        search_strategy: Optional[SearchStrategy] = None,
+        settings_provider: Optional[SettingsProvider] = None,
+        update_service: Optional["ModelUpdateService"] = None,
+    ):
+        """Initialize the service.
+
         Args:
-            model_type: Type of model (lora, checkpoint, etc.)
-            scanner: Model scanner instance
-            metadata_class: Metadata class for this model type
+            model_type: Type of model (lora, checkpoint, etc.).
+            scanner: Model scanner instance.
+            metadata_class: Metadata class for this model type.
+            cache_repository: Custom repository for cache access (primarily for tests).
+            filter_set: Filter component controlling folder/tag/favorites logic.
+            search_strategy: Search component for fuzzy/text matching.
+            settings_provider: Settings object; defaults to the global settings manager.
+            update_service: Service used to determine whether models have remote updates available.
         """
         self.model_type = model_type
         self.scanner = scanner
         self.metadata_class = metadata_class
+        self.settings = settings_provider or get_settings_manager()
+        self.cache_repository = cache_repository or ModelCacheRepository(scanner)
+        self.filter_set = filter_set or ModelFilterSet(self.settings)
+        self.search_strategy = search_strategy or SearchStrategy()
+        self.update_service = update_service
     
-    async def get_paginated_data(self, page: int, page_size: int, sort_by: str = 'name', 
-                               folder: str = None, search: str = None, fuzzy_search: bool = False,
-                               base_models: list = None, tags: list = None,
-                               search_options: dict = None, hash_filters: dict = None,
-                               favorites_only: bool = False, **kwargs) -> Dict:
-        """Get paginated and filtered model data
-        
-        Args:
-            page: Page number (1-based)
-            page_size: Number of items per page
-            sort_by: Sort criteria, e.g. 'name', 'name:asc', 'name:desc', 'date', 'date:asc', 'date:desc'
-            folder: Folder filter
-            search: Search term
-            fuzzy_search: Whether to use fuzzy search
-            base_models: List of base models to filter by
-            tags: List of tags to filter by
-            search_options: Search options dict
-            hash_filters: Hash filtering options
-            favorites_only: Filter for favorites only
-            **kwargs: Additional model-specific filters
-            
-        Returns:
-            Dict containing paginated results
-        """
-        cache = await self.scanner.get_cached_data()
+    async def get_paginated_data(
+        self,
+        page: int,
+        page_size: int,
+        sort_by: str = 'name',
+        folder: str = None,
+        search: str = None,
+        fuzzy_search: bool = False,
+        base_models: list = None,
+        tags: list = None,
+        search_options: dict = None,
+        hash_filters: dict = None,
+        favorites_only: bool = False,
+        has_update: bool = False,
+        **kwargs,
+    ) -> Dict:
+        """Get paginated and filtered model data"""
+        sort_params = self.cache_repository.parse_sort(sort_by)
+        sorted_data = await self.cache_repository.fetch_sorted(sort_params)
 
-        # Parse sort_by into sort_key and order
-        if ':' in sort_by:
-            sort_key, order = sort_by.split(':', 1)
-            sort_key = sort_key.strip()
-            order = order.strip().lower()
-            if order not in ('asc', 'desc'):
-                order = 'asc'
-        else:
-            sort_key = sort_by.strip()
-            order = 'asc'
-
-        # Get default search options if not provided
-        if search_options is None:
-            search_options = {
-                'filename': True,
-                'modelname': True,
-                'tags': False,
-                'recursive': True,
-            }
-
-        # Get the base data set using new sort logic
-        filtered_data = await cache.get_sorted_data(sort_key, order)
-        
-        # Apply hash filtering if provided (highest priority)
         if hash_filters:
-            filtered_data = await self._apply_hash_filters(filtered_data, hash_filters)
-            
-            # Jump to pagination for hash filters
+            filtered_data = await self._apply_hash_filters(sorted_data, hash_filters)
             return self._paginate(filtered_data, page, page_size)
-        
-        # Apply common filters
+
         filtered_data = await self._apply_common_filters(
-            filtered_data, folder, base_models, tags, favorites_only, search_options
+            sorted_data,
+            folder=folder,
+            base_models=base_models,
+            tags=tags,
+            favorites_only=favorites_only,
+            search_options=search_options,
         )
-        
-        # Apply search filtering
+
         if search:
             filtered_data = await self._apply_search_filters(
-                filtered_data, search, fuzzy_search, search_options
+                filtered_data,
+                search,
+                fuzzy_search,
+                search_options,
             )
-        
-        # Apply model-specific filters
+
         filtered_data = await self._apply_specific_filters(filtered_data, **kwargs)
-        
+
+        if has_update:
+            filtered_data = await self._apply_update_filter(filtered_data)
+
         return self._paginate(filtered_data, page, page_size)
+
     
     async def _apply_hash_filters(self, data: List[Dict], hash_filters: Dict) -> List[Dict]:
         """Apply hash-based filtering"""
@@ -120,117 +121,93 @@ class BaseModelService(ABC):
         
         return data
     
-    async def _apply_common_filters(self, data: List[Dict], folder: str = None, 
-                                  base_models: list = None, tags: list = None,
-                                  favorites_only: bool = False, search_options: dict = None) -> List[Dict]:
+    async def _apply_common_filters(
+        self,
+        data: List[Dict],
+        folder: str = None,
+        base_models: list = None,
+        tags: list = None,
+        favorites_only: bool = False,
+        search_options: dict = None,
+    ) -> List[Dict]:
         """Apply common filters that work across all model types"""
-        # Apply SFW filtering if enabled in settings
-        if settings.get('show_only_sfw', False):
-            data = [
-                item for item in data
-                if not item.get('preview_nsfw_level') or item.get('preview_nsfw_level') < NSFW_LEVELS['R']
-            ]
-        
-        # Apply favorites filtering if enabled
-        if favorites_only:
-            data = [
-                item for item in data
-                if item.get('favorite', False) is True
-            ]
-        
-        # Apply folder filtering
-        if folder is not None:
-            if search_options and search_options.get('recursive', True):
-                # Recursive folder filtering - include all subfolders
-                # Ensure we match exact folder or its subfolders by checking path boundaries
-                if folder == "":
-                    # Empty folder means root - include all items
-                    pass  # Don't filter anything
-                else:
-                    # Add trailing slash to ensure we match folder boundaries correctly
-                    folder_with_separator = folder + "/"
-                    data = [
-                        item for item in data
-                        if (item['folder'] == folder or 
-                            item['folder'].startswith(folder_with_separator))
-                    ]
-            else:
-                # Exact folder filtering
-                data = [
-                    item for item in data
-                    if item['folder'] == folder
-                ]
-        
-        # Apply base model filtering
-        if base_models and len(base_models) > 0:
-            data = [
-                item for item in data
-                if item.get('base_model') in base_models
-            ]
-        
-        # Apply tag filtering
-        if tags and len(tags) > 0:
-            data = [
-                item for item in data
-                if any(tag in item.get('tags', []) for tag in tags)
-            ]
-        
-        return data
+        normalized_options = self.search_strategy.normalize_options(search_options)
+        criteria = FilterCriteria(
+            folder=folder,
+            base_models=base_models,
+            tags=tags,
+            favorites_only=favorites_only,
+            search_options=normalized_options,
+        )
+        return self.filter_set.apply(data, criteria)
     
-    async def _apply_search_filters(self, data: List[Dict], search: str, 
-                                  fuzzy_search: bool, search_options: dict) -> List[Dict]:
+    async def _apply_search_filters(
+        self,
+        data: List[Dict],
+        search: str,
+        fuzzy_search: bool,
+        search_options: dict,
+    ) -> List[Dict]:
         """Apply search filtering"""
-        search_results = []
-        
-        for item in data:
-            # Search by file name
-            if search_options.get('filename', True):
-                if fuzzy_search:
-                    if fuzzy_match(item.get('file_name', ''), search):
-                        search_results.append(item)
-                        continue
-                elif search.lower() in item.get('file_name', '').lower():
-                    search_results.append(item)
-                    continue
-            
-            # Search by model name
-            if search_options.get('modelname', True):
-                if fuzzy_search:
-                    if fuzzy_match(item.get('model_name', ''), search):
-                        search_results.append(item)
-                        continue
-                elif search.lower() in item.get('model_name', '').lower():
-                    search_results.append(item)
-                    continue
-            
-            # Search by tags
-            if search_options.get('tags', False) and 'tags' in item:
-                if any((fuzzy_match(tag, search) if fuzzy_search else search.lower() in tag.lower()) 
-                       for tag in item['tags']):
-                    search_results.append(item)
-                    continue
-            
-            # Search by creator
-            civitai = item.get('civitai')
-            creator_username = ''
-            if civitai and isinstance(civitai, dict):
-                creator = civitai.get('creator')
-                if creator and isinstance(creator, dict):
-                    creator_username = creator.get('username', '')
-            if search_options.get('creator', False) and creator_username:
-                if fuzzy_search:
-                    if fuzzy_match(creator_username, search):
-                        search_results.append(item)
-                        continue
-                elif search.lower() in creator_username.lower():
-                    search_results.append(item)
-                    continue
-        
-        return search_results
+        normalized_options = self.search_strategy.normalize_options(search_options)
+        return self.search_strategy.apply(data, search, normalized_options, fuzzy_search)
     
     async def _apply_specific_filters(self, data: List[Dict], **kwargs) -> List[Dict]:
         """Apply model-specific filters - to be overridden by subclasses if needed"""
         return data
+
+    async def _apply_update_filter(self, data: List[Dict]) -> List[Dict]:
+        """Filter models to those with remote updates available when requested."""
+        if not data:
+            return []
+        if self.update_service is None:
+            logger.warning(
+                "Requested has_update filter for %s models but update service is unavailable",
+                self.model_type,
+            )
+            return []
+
+        candidates: List[tuple[Dict, int]] = []
+        for item in data:
+            model_id = self._extract_model_id(item)
+            if model_id is not None:
+                candidates.append((item, model_id))
+
+        if not candidates:
+            return []
+
+        tasks = [
+            self.update_service.has_update(self.model_type, model_id)
+            for _, model_id in candidates
+        ]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        filtered: List[Dict] = []
+        for (item, model_id), result in zip(candidates, results):
+            if isinstance(result, Exception):
+                logger.error(
+                    "Failed to resolve update status for model %s (%s): %s",
+                    model_id,
+                    self.model_type,
+                    result,
+                )
+                continue
+            if result:
+                filtered.append(item)
+        return filtered
+
+    @staticmethod
+    def _extract_model_id(item: Dict) -> Optional[int]:
+        civitai = item.get('civitai') if isinstance(item, dict) else None
+        if not isinstance(civitai, dict):
+            return None
+        try:
+            value = civitai.get('modelId')
+            if value is None:
+                return None
+            return int(value)
+        except (TypeError, ValueError):
+            return None
     
     def _paginate(self, data: List[Dict], page: int, page_size: int) -> Dict:
         """Apply pagination to filtered data"""
@@ -284,6 +261,18 @@ class BaseModelService(ABC):
         """Get model root directories"""
         return self.scanner.get_model_roots()
     
+    def filter_civitai_data(self, data: Dict, minimal: bool = False) -> Dict:
+        """Filter relevant fields from CivitAI data"""
+        if not data:
+            return {}
+
+        fields = ["id", "modelId", "name", "trainedWords"] if minimal else [
+            "id", "modelId", "name", "createdAt", "updatedAt",
+            "publishedAt", "trainedWords", "baseModel", "description",
+            "model", "images", "customImages", "creator"
+        ]
+        return {k: data[k] for k in fields if k in data}
+    
     async def get_folder_tree(self, model_root: str) -> Dict:
         """Get hierarchical folder tree for a specific model root"""
         cache = await self.scanner.get_cached_data()
@@ -363,7 +352,7 @@ class BaseModelService(ABC):
                     from ..config import config
                     return config.get_preview_static_url(preview_url)
         
-        return None
+        return '/loras_static/images/no-preview.png'
     
     async def get_model_civitai_url(self, model_name: str) -> Dict[str, Optional[str]]:
         """Get the Civitai URL for a model file"""
@@ -389,24 +378,24 @@ class BaseModelService(ABC):
         return {'civitai_url': None, 'model_id': None, 'version_id': None}
 
     async def get_model_metadata(self, file_path: str) -> Optional[Dict]:
-        """Get filtered CivitAI metadata for a model by file path"""
-        cache = await self.scanner.get_cached_data()
-        
-        for model in cache.raw_data:
-            if model.get('file_path') == file_path:
-                return ModelRouteUtils.filter_civitai_data(model.get("civitai", {}))
-        
-        return None
+        """Load full metadata for a single model.
+
+        Listing/search endpoints return lightweight cache entries; this method performs
+        a lazy read of the on-disk metadata snapshot when callers need full detail.
+        """
+        metadata, should_skip = await MetadataManager.load_metadata(file_path, self.metadata_class)
+        if should_skip or metadata is None:
+            return None
+        return self.filter_civitai_data(metadata.to_dict().get("civitai", {}))
+
 
     async def get_model_description(self, file_path: str) -> Optional[str]:
-        """Get model description by file path"""
-        cache = await self.scanner.get_cached_data()
-        
-        for model in cache.raw_data:
-            if model.get('file_path') == file_path:
-                return model.get('modelDescription', '')
-        
-        return None
+        """Return the stored modelDescription field for a model."""
+        metadata, should_skip = await MetadataManager.load_metadata(file_path, self.metadata_class)
+        if should_skip or metadata is None:
+            return None
+        return metadata.modelDescription or ''
+
 
     async def search_relative_paths(self, search_term: str, limit: int = 15) -> List[str]:
         """Search model relative file paths for autocomplete functionality"""
@@ -448,4 +437,4 @@ class BaseModelService(ABC):
             x.lower()  # Then alphabetically
         ))
         
-        return matching_paths[:limit]
+        return matching_paths[:limit]

py/services/checkpoint_service.py

@@ -1,24 +1,24 @@
 import os
 import logging
-from typing import Dict, List, Optional
+from typing import Dict
 
 from .base_model_service import BaseModelService
 from ..utils.models import CheckpointMetadata
 from ..config import config
-from ..utils.routes_common import ModelRouteUtils
 
 logger = logging.getLogger(__name__)
 
 class CheckpointService(BaseModelService):
     """Checkpoint-specific service implementation"""
     
-    def __init__(self, scanner):
+    def __init__(self, scanner, update_service=None):
         """Initialize Checkpoint service
         
         Args:
             scanner: Checkpoint scanner instance
+            update_service: Optional service for remote update tracking.
         """
-        super().__init__("checkpoint", scanner, CheckpointMetadata)
+        super().__init__("checkpoint", scanner, CheckpointMetadata, update_service=update_service)
     
     async def format_response(self, checkpoint_data: Dict) -> Dict:
         """Format Checkpoint data for API response"""
@@ -38,7 +38,7 @@ class CheckpointService(BaseModelService):
             "notes": checkpoint_data.get("notes", ""),
             "model_type": checkpoint_data.get("model_type", "checkpoint"),
             "favorite": checkpoint_data.get("favorite", False),
-            "civitai": ModelRouteUtils.filter_civitai_data(checkpoint_data.get("civitai", {}), minimal=True)
+            "civitai": self.filter_civitai_data(checkpoint_data.get("civitai", {}), minimal=True)
         }
     
     def find_duplicate_hashes(self) -> Dict:
@@ -47,4 +47,4 @@ class CheckpointService(BaseModelService):
     
     def find_duplicate_filenames(self) -> Dict:
         """Find Checkpoints with conflicting filenames"""
-        return self.scanner._hash_index.get_duplicate_filenames()
+        return self.scanner._hash_index.get_duplicate_filenames()

py/services/civarchive_client.py

@@ -0,0 +1,554 @@
+import os
+import json
+import logging
+import asyncio
+from copy import deepcopy
+from typing import Optional, Dict, Tuple, List
+from .model_metadata_provider import CivArchiveModelMetadataProvider, ModelMetadataProviderManager
+from .downloader import get_downloader
+from .errors import RateLimitError
+
+try:
+    from bs4 import BeautifulSoup
+except ImportError as exc:
+    BeautifulSoup = None  # type: ignore[assignment]
+    _BS4_IMPORT_ERROR = exc
+else:
+    _BS4_IMPORT_ERROR = None
+
+def _require_beautifulsoup():
+    if BeautifulSoup is None:
+        raise RuntimeError(
+            "BeautifulSoup (bs4) is required for CivArchive client. "
+            "Install it with 'pip install beautifulsoup4'."
+        ) from _BS4_IMPORT_ERROR
+    return BeautifulSoup
+
+logger = logging.getLogger(__name__)
+
+class CivArchiveClient:
+    _instance = None
+    _lock = asyncio.Lock()
+    
+    @classmethod
+    async def get_instance(cls):
+        """Get singleton instance of CivArchiveClient"""
+        async with cls._lock:
+            if cls._instance is None:
+                cls._instance = cls()
+                
+                # Register this client as a metadata provider
+                provider_manager = await ModelMetadataProviderManager.get_instance()
+                provider_manager.register_provider('civarchive', CivArchiveModelMetadataProvider(cls._instance), False)
+                
+            return cls._instance
+
+    def __init__(self):
+        # Check if already initialized for singleton pattern
+        if hasattr(self, '_initialized'):
+            return
+        self._initialized = True
+        
+        self.base_url = "https://civarchive.com/api"
+
+    async def _request_json(
+        self,
+        path: str,
+        params: Optional[Dict[str, str]] = None
+    ) -> Tuple[Optional[Dict], Optional[str]]:
+        """Call CivArchive API and return JSON payload"""
+        success, payload = await self._make_request(path, params=params)
+        if not success:
+            error = payload if isinstance(payload, str) else "Request failed"
+            return None, error
+        if not isinstance(payload, dict):
+            return None, "Invalid response structure"
+        return payload, None
+
+    async def _make_request(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, str]] = None,
+    ) -> Tuple[bool, Dict | str]:
+        """Wrapper around downloader.make_request that surfaces rate limits."""
+
+        downloader = await get_downloader()
+        kwargs: Dict[str, Dict[str, str]] = {}
+        if params:
+            safe_params = {str(key): str(value) for key, value in params.items() if value is not None}
+            if safe_params:
+                kwargs["params"] = safe_params
+
+        success, payload = await downloader.make_request(
+            "GET",
+            f"{self.base_url}{path}",
+            use_auth=False,
+            **kwargs,
+        )
+        if not success and isinstance(payload, RateLimitError):
+            if payload.provider is None:
+                payload.provider = "civarchive_api"
+            raise payload
+        return success, payload
+
+    @staticmethod
+    def _normalize_payload(payload: Dict) -> Dict:
+        """Unwrap CivArchive responses that wrap content under a data key"""
+        if not isinstance(payload, dict):
+            return {}
+        data = payload.get("data")
+        if isinstance(data, dict):
+            return data
+        return payload
+
+    @staticmethod
+    def _split_context(payload: Dict) -> Tuple[Dict, Dict, List[Dict]]:
+        """Separate version payload from surrounding model context"""
+        data = CivArchiveClient._normalize_payload(payload)
+        context: Dict = {}
+        fallback_files: List[Dict] = []
+        version: Dict = {}
+
+        for key, value in data.items():
+            if key in {"version", "model"}:
+                continue
+            context[key] = value
+
+        if isinstance(data.get("version"), dict):
+            version = data["version"]
+
+        model_block = data.get("model")
+        if isinstance(model_block, dict):
+            for key, value in model_block.items():
+                if key == "version":
+                    if not version and isinstance(value, dict):
+                        version = value
+                    continue
+                context.setdefault(key, value)
+            fallback_files = fallback_files or model_block.get("files") or []
+
+        fallback_files = fallback_files or data.get("files") or []
+        return context, version, fallback_files
+
+    @staticmethod
+    def _ensure_list(value) -> List:
+        if isinstance(value, list):
+            return value
+        if value is None:
+            return []
+        return [value]
+
+    @staticmethod
+    def _build_model_info(context: Dict) -> Dict:
+        tags = context.get("tags")
+        if not isinstance(tags, list):
+            tags = list(tags) if isinstance(tags, (set, tuple)) else ([] if tags is None else [tags])
+        return {
+            "name": context.get("name"),
+            "type": context.get("type"),
+            "nsfw": bool(context.get("is_nsfw", context.get("nsfw", False))),
+            "description": context.get("description"),
+            "tags": tags,
+        }
+
+    @staticmethod
+    def _build_creator_info(context: Dict) -> Dict:
+        username = context.get("creator_username") or context.get("username") or ""
+        image = context.get("creator_image") or context.get("creator_avatar") or ""
+        creator: Dict[str, Optional[str]] = {
+            "username": username,
+            "image": image,
+        }
+        if context.get("creator_name"):
+            creator["name"] = context["creator_name"]
+        if context.get("creator_url"):
+            creator["url"] = context["creator_url"]
+        return creator
+
+    @staticmethod
+    def _transform_file_entry(file_data: Dict) -> Dict:
+        mirrors = file_data.get("mirrors") or []
+        if not isinstance(mirrors, list):
+            mirrors = [mirrors]
+        available_mirror = next(
+            (mirror for mirror in mirrors if isinstance(mirror, dict) and mirror.get("deletedAt") is None),
+            None
+        )
+        download_url = file_data.get("downloadUrl")
+        if not download_url and available_mirror:
+            download_url = available_mirror.get("url")
+        name = file_data.get("name")
+        if not name and available_mirror:
+            name = available_mirror.get("filename")
+
+        transformed: Dict = {
+            "id": file_data.get("id"),
+            "sizeKB": file_data.get("sizeKB"),
+            "name": name,
+            "type": file_data.get("type"),
+            "downloadUrl": download_url,
+            "primary": True,
+            # TODO: for some reason is_primary is false in CivArchive response, need to figure this out, 
+            # "primary": bool(file_data.get("is_primary", file_data.get("primary", False))),
+            "mirrors": mirrors,
+        }
+
+        sha256 = file_data.get("sha256")
+        if sha256:
+            transformed["hashes"] = {"SHA256": str(sha256).upper()}
+        elif isinstance(file_data.get("hashes"), dict):
+            transformed["hashes"] = file_data["hashes"]
+
+        if "metadata" in file_data:
+            transformed["metadata"] = file_data["metadata"]
+
+        if file_data.get("modelVersionId") is not None:
+            transformed["modelVersionId"] = file_data.get("modelVersionId")
+        elif file_data.get("model_version_id") is not None:
+            transformed["modelVersionId"] = file_data.get("model_version_id")
+
+        if file_data.get("modelId") is not None:
+            transformed["modelId"] = file_data.get("modelId")
+        elif file_data.get("model_id") is not None:
+            transformed["modelId"] = file_data.get("model_id")
+
+        return transformed
+
+    def _transform_files(
+        self,
+        files: Optional[List[Dict]],
+        fallback_files: Optional[List[Dict]] = None
+    ) -> List[Dict]:
+        candidates: List[Dict] = []
+        if isinstance(files, list) and files:
+            candidates = files
+        elif isinstance(fallback_files, list):
+            candidates = fallback_files
+
+        transformed_files: List[Dict] = []
+        for file_data in candidates:
+            if isinstance(file_data, dict):
+                transformed_files.append(self._transform_file_entry(file_data))
+        return transformed_files
+
+    def _transform_version(
+        self,
+        context: Dict,
+        version: Dict,
+        fallback_files: Optional[List[Dict]] = None
+    ) -> Optional[Dict]:
+        if not version:
+            return None
+
+        version_copy = deepcopy(version)
+        version_copy.pop("model", None)
+        version_copy.pop("creator", None)
+
+        if "trigger" in version_copy:
+            triggers = version_copy.pop("trigger")
+            if isinstance(triggers, list):
+                version_copy["trainedWords"] = triggers
+            elif triggers is None:
+                version_copy["trainedWords"] = []
+            else:
+                version_copy["trainedWords"] = [triggers]
+
+        if "trainedWords" in version_copy and isinstance(version_copy["trainedWords"], str):
+            version_copy["trainedWords"] = [version_copy["trainedWords"]]
+
+        if "nsfw_level" in version_copy:
+            version_copy["nsfwLevel"] = version_copy.pop("nsfw_level")
+        elif "nsfwLevel" not in version_copy and context.get("nsfw_level") is not None:
+            version_copy["nsfwLevel"] = context.get("nsfw_level")
+
+        stats_keys = ["downloadCount", "ratingCount", "rating"]
+        stats = {key: version_copy.pop(key) for key in stats_keys if key in version_copy}
+        if stats:
+            version_copy["stats"] = stats
+
+        version_copy["files"] = self._transform_files(version_copy.get("files"), fallback_files)
+        version_copy["images"] = self._ensure_list(version_copy.get("images"))
+
+        version_copy["model"] = self._build_model_info(context)
+        version_copy["creator"] = self._build_creator_info(context)
+
+        version_copy["source"] = "civarchive"
+        version_copy["is_deleted"] = bool(context.get("deletedAt")) or bool(version.get("deletedAt"))
+
+        return version_copy
+
+    async def _resolve_version_from_files(self, payload: Dict) -> Optional[Dict]:
+        """Fallback to fetch version data when only file metadata is available"""
+        data = self._normalize_payload(payload)
+        files = data.get("files") or payload.get("files") or []
+        if not isinstance(files, list):
+            files = [files]
+        for file_data in files:
+            if not isinstance(file_data, dict):
+                continue
+            model_id = file_data.get("model_id") or file_data.get("modelId")
+            version_id = file_data.get("model_version_id") or file_data.get("modelVersionId")
+            if model_id is None or version_id is None:
+                continue
+            resolved = await self.get_model_version(model_id, version_id)
+            if resolved:
+                return resolved
+        return None
+
+    async def get_model_by_hash(self, model_hash: str) -> Tuple[Optional[Dict], Optional[str]]:
+        """Find model by SHA256 hash value using CivArchive API"""
+        try:
+            payload, error = await self._request_json(f"/sha256/{model_hash.lower()}")
+            if error:
+                if "not found" in error.lower():
+                    return None, "Model not found"
+                return None, error
+
+            context, version_data, fallback_files = self._split_context(payload)
+            transformed = self._transform_version(context, version_data, fallback_files)
+            if transformed:
+                return transformed, None
+
+            resolved = await self._resolve_version_from_files(payload)
+            if resolved:
+                return resolved, None
+
+            logger.error("Error fetching version of CivArchive model by hash %s", model_hash[:10])
+            return None, "No version data found"
+
+        except RateLimitError:
+            raise
+        except Exception as e:
+            logger.error(f"Error fetching CivArchive model by hash {model_hash[:10]}: {e}")
+            return None, str(e)
+
+    async def get_model_versions(self, model_id: str) -> Optional[Dict]:
+        """Get all versions of a model using CivArchive API"""
+        try:
+            payload, error = await self._request_json(f"/models/{model_id}")
+            if error or payload is None:
+                if error and "not found" in error.lower():
+                    return None
+                logger.error(f"Error fetching CivArchive model versions for {model_id}: {error}")
+                return None
+
+            data = self._normalize_payload(payload)
+            context, version_data, fallback_files = self._split_context(payload)
+
+            versions_meta = data.get("versions") or []
+            transformed_versions: List[Dict] = []
+            for meta in versions_meta:
+                if not isinstance(meta, dict):
+                    continue
+                version_id = meta.get("id")
+                if version_id is None:
+                    continue
+                target_model_id = meta.get("modelId") or model_id
+                version = await self.get_model_version(target_model_id, version_id)
+                if version:
+                    transformed_versions.append(version)
+
+            # Ensure the primary version is included even if versions list was empty
+            primary_version = self._transform_version(context, version_data, fallback_files)
+            if primary_version:
+                transformed_versions.insert(0, primary_version)
+
+            ordered_versions: List[Dict] = []
+            seen_ids = set()
+            for version in transformed_versions:
+                version_id = version.get("id")
+                if version_id in seen_ids:
+                    continue
+                seen_ids.add(version_id)
+                ordered_versions.append(version)
+
+            return {
+                "modelVersions": ordered_versions,
+                "type": context.get("type", ""),
+                "name": context.get("name", ""),
+            }
+
+        except RateLimitError:
+            raise
+        except Exception as e:
+            logger.error(f"Error fetching CivArchive model versions for {model_id}: {e}")
+            return None
+
+    async def get_model_version(self, model_id: int = None, version_id: int = None) -> Optional[Dict]:
+        """Get specific model version using CivArchive API
+        
+        Args:
+            model_id: The model ID (required)
+            version_id: Optional specific version ID to filter to
+            
+        Returns:
+            Optional[Dict]: The model version data or None if not found
+        """
+        if model_id is None:
+            return None
+
+        try:
+            params = {"modelVersionId": version_id} if version_id is not None else None
+            payload, error = await self._request_json(f"/models/{model_id}", params=params)
+            if error or payload is None:
+                if error and "not found" in error.lower():
+                    return None
+                logger.error(f"Error fetching CivArchive model version via API {model_id}/{version_id}: {error}")
+                return None
+
+            context, version_data, fallback_files = self._split_context(payload)
+
+            if not version_data:
+                return await self._resolve_version_from_files(payload)
+
+            if version_id is not None:
+                raw_id = version_data.get("id")
+                if raw_id != version_id:
+                    logger.warning(
+                        "Requested version %s doesn't match default version %s for model %s",
+                        version_id,
+                        raw_id,
+                        model_id,
+                    )
+                    return None
+                actual_model_id = version_data.get("modelId")
+                context_model_id = context.get("id")
+                # CivArchive can respond with data for a different model id while already
+                # returning the fully resolved model context. Only follow the redirect when
+                # the context itself still points to the original (wrong) model.
+                if (
+                    actual_model_id is not None
+                    and str(actual_model_id) != str(model_id)
+                    and (context_model_id is None or str(context_model_id) != str(actual_model_id))
+                ):
+                    return await self.get_model_version(actual_model_id, version_id)
+
+            return self._transform_version(context, version_data, fallback_files)
+
+        except RateLimitError:
+            raise
+        except Exception as e:
+            logger.error(f"Error fetching CivArchive model version via API {model_id}/{version_id}: {e}")
+            return None
+
+    async def get_model_version_info(self, version_id: str) -> Tuple[Optional[Dict], Optional[str]]:
+        """ Fetch model version metadata using a known bogus model lookup        
+        CivArchive lacks a direct version lookup API, this uses a workaround (which we handle in the main model request now)
+        
+        Args:
+            version_id: The model version ID
+            
+        Returns:
+            Tuple[Optional[Dict], Optional[str]]: (version_data, error_message)
+        """
+        version = await self.get_model_version(1, version_id)
+        if version is None:
+            return None, "Model not found"
+        return version, None
+
+    async def get_model_by_url(self, url) -> Optional[Dict]:
+        """Get specific model version by parsing CivArchive HTML page (legacy method)
+        
+        This is the original HTML scraping implementation, kept for reference and new sites added not in api.
+        The primary get_model_version() now uses the API instead.
+        """
+
+        try:
+            # Construct CivArchive URL
+            url = f"https://civarchive.com/{url}"
+            downloader = await get_downloader()
+            session = await downloader.session
+            async with session.get(url) as response:
+                if response.status != 200:
+                    return None
+                
+                html_content = await response.text()
+                
+            # Parse HTML to extract JSON data
+            soup_parser = _require_beautifulsoup()
+            soup = soup_parser(html_content, 'html.parser')
+            script_tag = soup.find('script', {'id': '__NEXT_DATA__', 'type': 'application/json'})
+            
+            if not script_tag:
+                return None
+                
+            # Parse JSON content
+            json_data = json.loads(script_tag.string)
+            model_data = json_data.get('props', {}).get('pageProps', {}).get('model')
+            
+            if not model_data or 'version' not in model_data:
+                return None
+            
+            # Extract version data as base
+            version = model_data['version'].copy()
+            
+            # Restructure stats
+            if 'downloadCount' in version and 'ratingCount' in version and 'rating' in version:
+                version['stats'] = {
+                    'downloadCount': version.pop('downloadCount'),
+                    'ratingCount': version.pop('ratingCount'),
+                    'rating': version.pop('rating')
+                }
+            
+            # Rename trigger to trainedWords
+            if 'trigger' in version:
+                version['trainedWords'] = version.pop('trigger')
+            
+            # Transform files data to expected format
+            if 'files' in version:
+                transformed_files = []
+                for file_data in version['files']:
+                    # Find first available mirror (deletedAt is null)
+                    available_mirror = None
+                    for mirror in file_data.get('mirrors', []):
+                        if mirror.get('deletedAt') is None:
+                            available_mirror = mirror
+                            break
+                    
+                    # Create transformed file entry
+                    transformed_file = {
+                        'id': file_data.get('id'),
+                        'sizeKB': file_data.get('sizeKB'),
+                        'name': available_mirror.get('filename', file_data.get('name')) if available_mirror else file_data.get('name'),
+                        'type': file_data.get('type'),
+                        'downloadUrl': available_mirror.get('url') if available_mirror else None,
+                        'primary': file_data.get('is_primary', False),
+                        'mirrors': file_data.get('mirrors', [])
+                    }
+                    
+                    # Transform hash format
+                    if 'sha256' in file_data:
+                        transformed_file['hashes'] = {
+                            'SHA256': file_data['sha256'].upper()
+                        }
+                    
+                    transformed_files.append(transformed_file)
+                
+                version['files'] = transformed_files
+            
+            # Add model information
+            version['model'] = {
+                'name': model_data.get('name'),
+                'type': model_data.get('type'),
+                'nsfw': model_data.get('is_nsfw', False),
+                'description': model_data.get('description'),
+                'tags': model_data.get('tags', [])
+            }
+
+            version['creator'] = {
+                'username': model_data.get('username'),
+                'image': ''
+            }
+            
+            # Add source identifier
+            version['source'] = 'civarchive'
+            version['is_deleted'] = json_data.get('query', {}).get('is_deleted', False)
+            
+            return version
+            
+        except RateLimitError:
+            raise
+        except Exception as e:
+            logger.error(f"Error fetching CivArchive model version (scraping) {url}: {e}")
+            return None

py/services/civitai_client.py

@@ -1,11 +1,11 @@
-from datetime import datetime
-import aiohttp
-import os
-import logging
 import asyncio
-from email.parser import Parser
+import copy
+import logging
+import os
 from typing import Optional, Dict, Tuple, List
-from urllib.parse import unquote
+from .model_metadata_provider import CivitaiModelMetadataProvider, ModelMetadataProviderManager
+from .downloader import get_downloader
+from .errors import RateLimitError
 
 logger = logging.getLogger(__name__)
 
@@ -19,6 +19,11 @@ class CivitaiClient:
         async with cls._lock:
             if cls._instance is None:
                 cls._instance = cls()
+                
+                # Register this client as a metadata provider
+                provider_manager = await ModelMetadataProviderManager.get_instance()
+                provider_manager.register_provider('civitai', CivitaiModelMetadataProvider(cls._instance), True)
+                
             return cls._instance
 
     def __init__(self):
@@ -28,80 +33,49 @@ class CivitaiClient:
         self._initialized = True
         
         self.base_url = "https://civitai.com/api/v1"
-        self.headers = {
-            'User-Agent': 'ComfyUI-LoRA-Manager/1.0'
-        }
-        self._session = None
-        self._session_created_at = None
-        # Adjust chunk size based on storage type - consider making this configurable
-        self.chunk_size = 4 * 1024 * 1024   # 4MB chunks for better HDD throughput
+
+    async def _make_request(
+        self,
+        method: str,
+        url: str,
+        *,
+        use_auth: bool = False,
+        **kwargs,
+    ) -> Tuple[bool, Dict | str]:
+        """Wrapper around downloader.make_request that surfaces rate limits."""
+
+        downloader = await get_downloader()
+        success, result = await downloader.make_request(
+            method,
+            url,
+            use_auth=use_auth,
+            **kwargs,
+        )
+        if not success and isinstance(result, RateLimitError):
+            if result.provider is None:
+                result.provider = "civitai_api"
+            raise result
+        return success, result
+
+    @staticmethod
+    def _remove_comfy_metadata(model_version: Optional[Dict]) -> None:
+        """Remove Comfy-specific metadata from model version images."""
+        if not isinstance(model_version, dict):
+            return
+
+        images = model_version.get("images")
+        if not isinstance(images, list):
+            return
+
+        for image in images:
+            if not isinstance(image, dict):
+                continue
+
+            meta = image.get("meta")
+            if isinstance(meta, dict) and "comfy" in meta:
+                meta.pop("comfy", None)
     
-    @property
-    async def session(self) -> aiohttp.ClientSession:
-        """Lazy initialize the session"""
-        if self._session is None:
-            # Optimize TCP connection parameters
-            connector = aiohttp.TCPConnector(
-                ssl=True,
-                limit=8,  # Increase from 3 to 8 for better parallelism
-                ttl_dns_cache=300,  # Enable DNS caching with reasonable timeout
-                force_close=False,  # Keep connections for reuse
-                enable_cleanup_closed=True
-            )
-            trust_env = True  # Allow using system environment proxy settings
-            # Configure timeout parameters - increase read timeout for large files and remove sock_read timeout
-            timeout = aiohttp.ClientTimeout(total=None, connect=60, sock_read=None)
-            self._session = aiohttp.ClientSession(
-                connector=connector, 
-                trust_env=trust_env,
-                timeout=timeout
-            )
-            self._session_created_at = datetime.now()
-        return self._session
-    
-    async def _ensure_fresh_session(self):
-        """Refresh session if it's been open too long"""
-        if self._session is not None:
-            if not hasattr(self, '_session_created_at') or \
-               (datetime.now() - self._session_created_at).total_seconds() > 300:  # 5 minutes
-                await self.close()
-                self._session = None
-        
-        return await self.session
-
-    def _parse_content_disposition(self, header: str) -> str:
-        """Parse filename from content-disposition header"""
-        if not header:
-            return None
-        
-        # Handle quoted filenames
-        if 'filename="' in header:
-            start = header.index('filename="') + 10
-            end = header.index('"', start)
-            return unquote(header[start:end])
-        
-        # Fallback to original parsing
-        disposition = Parser().parsestr(f'Content-Disposition: {header}')
-        filename = disposition.get_param('filename')
-        if filename:
-            return unquote(filename)
-        return None
-
-    def _get_request_headers(self) -> dict:
-        """Get request headers with optional API key"""
-        headers = {
-            'User-Agent': 'ComfyUI-LoRA-Manager/1.0',
-            'Content-Type': 'application/json'
-        }
-        
-        from .settings_manager import settings
-        api_key = settings.get('civitai_api_key')
-        if (api_key):
-            headers['Authorization'] = f'Bearer {api_key}'
-            
-        return headers
-
-    async def _download_file(self, url: str, save_dir: str, default_filename: str, progress_callback=None) -> Tuple[bool, str]:
+    async def download_file(self, url: str, save_dir: str, default_filename: str, progress_callback=None) -> Tuple[bool, str]:
         """Download file with resumable downloads and retry mechanism
 
         Args:
@@ -113,302 +87,256 @@ class CivitaiClient:
         Returns:
             Tuple[bool, str]: (success, save_path or error message)
         """
-        max_retries = 5
-        retry_count = 0
-        base_delay = 2.0  # Base delay for exponential backoff
-        
-        # Initial setup
-        session = await self._ensure_fresh_session()
+        downloader = await get_downloader()
         save_path = os.path.join(save_dir, default_filename)
-        part_path = save_path + '.part'
         
-        # Get existing file size for resume
-        resume_offset = 0
-        if os.path.exists(part_path):
-            resume_offset = os.path.getsize(part_path)
-            logger.info(f"Resuming download from offset {resume_offset} bytes")
+        # Use unified downloader with CivitAI authentication
+        success, result = await downloader.download_file(
+            url=url,
+            save_path=save_path,
+            progress_callback=progress_callback,
+            use_auth=True,  # Enable CivitAI authentication
+            allow_resume=True
+        )
         
-        total_size = 0
-        filename = default_filename
-        
-        while retry_count <= max_retries:
-            try:
-                headers = self._get_request_headers()
-                
-                # Add Range header for resume if we have partial data
-                if resume_offset > 0:
-                    headers['Range'] = f'bytes={resume_offset}-'
-                
-                # Add Range header to allow resumable downloads
-                headers['Accept-Encoding'] = 'identity'  # Disable compression for better chunked downloads
-                
-                logger.debug(f"Download attempt {retry_count + 1}/{max_retries + 1} from: {url}")
-                if resume_offset > 0:
-                    logger.debug(f"Requesting range from byte {resume_offset}")
-                
-                async with session.get(url, headers=headers, allow_redirects=True) as response:
-                    # Handle different response codes
-                    if response.status == 200:
-                        # Full content response
-                        if resume_offset > 0:
-                            # Server doesn't support ranges, restart from beginning
-                            logger.warning("Server doesn't support range requests, restarting download")
-                            resume_offset = 0
-                            if os.path.exists(part_path):
-                                os.remove(part_path)
-                    elif response.status == 206:
-                        # Partial content response (resume successful)
-                        content_range = response.headers.get('Content-Range')
-                        if content_range:
-                            # Parse total size from Content-Range header (e.g., "bytes 1024-2047/2048")
-                            range_parts = content_range.split('/')
-                            if len(range_parts) == 2:
-                                total_size = int(range_parts[1])
-                        logger.info(f"Successfully resumed download from byte {resume_offset}")
-                    elif response.status == 416:
-                        # Range not satisfiable - file might be complete or corrupted
-                        if os.path.exists(part_path):
-                            part_size = os.path.getsize(part_path)
-                            logger.warning(f"Range not satisfiable. Part file size: {part_size}")
-                            # Try to get actual file size
-                            head_response = await session.head(url, headers=self._get_request_headers())
-                            if head_response.status == 200:
-                                actual_size = int(head_response.headers.get('content-length', 0))
-                                if part_size == actual_size:
-                                    # File is complete, just rename it
-                                    os.rename(part_path, save_path)
-                                    if progress_callback:
-                                        await progress_callback(100)
-                                    return True, save_path
-                            # Remove corrupted part file and restart
-                            os.remove(part_path)
-                            resume_offset = 0
-                            continue
-                    elif response.status == 401:
-                        logger.warning(f"Unauthorized access to resource: {url} (Status 401)")
-                        return False, "Invalid or missing CivitAI API key, or early access restriction."
-                    elif response.status == 403:
-                        logger.warning(f"Forbidden access to resource: {url} (Status 403)")
-                        return False, "Access forbidden: You don't have permission to download this file."
-                    else:
-                        logger.error(f"Download failed for {url} with status {response.status}")
-                        return False, f"Download failed with status {response.status}"
-                    
-                    # Get total file size for progress calculation (if not set from Content-Range)
-                    if total_size == 0:
-                        total_size = int(response.headers.get('content-length', 0))
-                        if response.status == 206:
-                            # For partial content, add the offset to get total file size
-                            total_size += resume_offset
+        return success, result
 
-                    current_size = resume_offset
-                    last_progress_report_time = datetime.now()
-
-                    # Stream download to file with progress updates using larger buffer
-                    loop = asyncio.get_running_loop()
-                    mode = 'ab' if resume_offset > 0 else 'wb'
-                    with open(part_path, mode) as f:
-                        async for chunk in response.content.iter_chunked(self.chunk_size):
-                            if chunk:
-                                # Run blocking file write in executor
-                                await loop.run_in_executor(None, f.write, chunk)
-                                current_size += len(chunk)
-                                
-                                # Limit progress update frequency to reduce overhead
-                                now = datetime.now()
-                                time_diff = (now - last_progress_report_time).total_seconds()
-                                
-                                if progress_callback and total_size and time_diff >= 1.0:
-                                    progress = (current_size / total_size) * 100
-                                    await progress_callback(progress)
-                                    last_progress_report_time = now
-                    
-                    # Download completed successfully
-                    # Verify file size if total_size was provided
-                    final_size = os.path.getsize(part_path)
-                    if total_size > 0 and final_size != total_size:
-                        logger.warning(f"File size mismatch. Expected: {total_size}, Got: {final_size}")
-                        # Don't treat this as fatal error, rename anyway
-                    
-                    # Atomically rename .part to final file with retries
-                    max_rename_attempts = 5
-                    rename_attempt = 0
-                    rename_success = False
-                    
-                    while rename_attempt < max_rename_attempts and not rename_success:
-                        try:
-                            os.rename(part_path, save_path)
-                            rename_success = True
-                        except PermissionError as e:
-                            rename_attempt += 1
-                            if rename_attempt < max_rename_attempts:
-                                logger.info(f"File still in use, retrying rename in 2 seconds (attempt {rename_attempt}/{max_rename_attempts})")
-                                await asyncio.sleep(2)  # Wait before retrying
-                            else:
-                                logger.error(f"Failed to rename file after {max_rename_attempts} attempts: {e}")
-                                return False, f"Failed to finalize download: {str(e)}"
-                    
-                    # Ensure 100% progress is reported
-                    if progress_callback:
-                        await progress_callback(100)
-                        
-                    return True, save_path
-                    
-            except (aiohttp.ClientError, aiohttp.ClientPayloadError, 
-                    aiohttp.ServerDisconnectedError, asyncio.TimeoutError) as e:
-                retry_count += 1
-                logger.warning(f"Network error during download (attempt {retry_count}/{max_retries + 1}): {e}")
-                
-                if retry_count <= max_retries:
-                    # Calculate delay with exponential backoff
-                    delay = base_delay * (2 ** (retry_count - 1))
-                    logger.info(f"Retrying in {delay} seconds...")
-                    await asyncio.sleep(delay)
-                    
-                    # Update resume offset for next attempt
-                    if os.path.exists(part_path):
-                        resume_offset = os.path.getsize(part_path)
-                        logger.info(f"Will resume from byte {resume_offset}")
-                    
-                    # Refresh session to get new connection
-                    await self.close()
-                    session = await self._ensure_fresh_session()
-                    continue
-                else:
-                    logger.error(f"Max retries exceeded for download: {e}")
-                    return False, f"Network error after {max_retries + 1} attempts: {str(e)}"
-                    
-            except Exception as e:
-                logger.error(f"Unexpected download error: {e}")
-                return False, str(e)
-        
-        return False, f"Download failed after {max_retries + 1} attempts"
-
-    async def get_model_by_hash(self, model_hash: str) -> Optional[Dict]:
+    async def get_model_by_hash(self, model_hash: str) -> Tuple[Optional[Dict], Optional[str]]:
         try:
-            session = await self._ensure_fresh_session()
-            async with session.get(f"{self.base_url}/model-versions/by-hash/{model_hash}") as response:
-                if response.status == 200:
-                    return await response.json()
-                return None
+            success, result = await self._make_request(
+                'GET',
+                f"{self.base_url}/model-versions/by-hash/{model_hash}",
+                use_auth=True
+            )
+            if success:
+                # Get model ID from version data
+                model_id = result.get('modelId')
+                if model_id:
+                    # Fetch additional model metadata
+                    success_model, data = await self._make_request(
+                        'GET',
+                        f"{self.base_url}/models/{model_id}",
+                        use_auth=True
+                    )
+                    if success_model:
+                        # Enrich version_info with model data
+                        result['model']['description'] = data.get("description")
+                        result['model']['tags'] = data.get("tags", [])
+
+                        # Add creator from model data
+                        result['creator'] = data.get("creator")
+
+                self._remove_comfy_metadata(result)
+                return result, None
+            
+            # Handle specific error cases
+            if "not found" in str(result):
+                return None, "Model not found"
+            
+            # Other error cases
+            logger.error(f"Failed to fetch model info for {model_hash[:10]}: {result}")
+            return None, str(result)
+        except RateLimitError:
+            raise
         except Exception as e:
             logger.error(f"API Error: {str(e)}")
-            return None
+            return None, str(e)
 
     async def download_preview_image(self, image_url: str, save_path: str):
         try:
-            session = await self._ensure_fresh_session()
-            async with session.get(image_url) as response:
-                if response.status == 200:
-                    content = await response.read()
-                    with open(save_path, 'wb') as f:
-                        f.write(content)
-                    return True
-                return False
+            downloader = await get_downloader()
+            success, content, headers = await downloader.download_to_memory(
+                image_url,
+                use_auth=False  # Preview images don't need auth
+            )
+            if success:
+                # Ensure directory exists
+                os.makedirs(os.path.dirname(save_path), exist_ok=True)
+                with open(save_path, 'wb') as f:
+                    f.write(content)
+                return True
+            return False
         except Exception as e:
-            print(f"Download Error: {str(e)}")
+            logger.error(f"Download Error: {str(e)}")
             return False
             
     async def get_model_versions(self, model_id: str) -> List[Dict]:
         """Get all versions of a model with local availability info"""
         try:
-            session = await self._ensure_fresh_session()  # Use fresh session
-            async with session.get(f"{self.base_url}/models/{model_id}") as response:
-                if response.status != 200:
-                    return None
-                data = await response.json()
+            success, result = await self._make_request(
+                'GET',
+                f"{self.base_url}/models/{model_id}",
+                use_auth=True
+            )
+            if success:
                 # Also return model type along with versions
                 return {
-                    'modelVersions': data.get('modelVersions', []),
-                    'type': data.get('type', '')
+                    'modelVersions': result.get('modelVersions', []),
+                    'type': result.get('type', ''),
+                    'name': result.get('name', '')
                 }
+            return None
+        except RateLimitError:
+            raise
         except Exception as e:
             logger.error(f"Error fetching model versions: {e}")
             return None
             
     async def get_model_version(self, model_id: int = None, version_id: int = None) -> Optional[Dict]:
-        """Get specific model version with additional metadata
-        
-        Args:
-            model_id: The Civitai model ID (optional if version_id is provided)
-            version_id: Optional specific version ID to retrieve
-            
-        Returns:
-            Optional[Dict]: The model version data with additional fields or None if not found
-        """
+        """Get specific model version with additional metadata."""
         try:
-            session = await self._ensure_fresh_session()
-            headers = self._get_request_headers()
-            
-            # Case 1: Only version_id is provided
             if model_id is None and version_id is not None:
-                # First get the version info to extract model_id
-                async with session.get(f"{self.base_url}/model-versions/{version_id}", headers=headers) as response:
-                    if response.status != 200:
-                        return None
-                    
-                    version = await response.json()
-                    model_id = version.get('modelId')
-                    
-                    if not model_id:
-                        logger.error(f"No modelId found in version {version_id}")
-                        return None
-                
-                # Now get the model data for additional metadata
-                async with session.get(f"{self.base_url}/models/{model_id}") as response:
-                    if response.status != 200:
-                        return version  # Return version without additional metadata
-                    
-                    model_data = await response.json()
-                    
-                    # Enrich version with model data
-                    version['model']['description'] = model_data.get("description")
-                    version['model']['tags'] = model_data.get("tags", [])
-                    version['creator'] = model_data.get("creator")
-                    
-                    return version
-            
-            # Case 2: model_id is provided (with or without version_id)
-            elif model_id is not None:
-                # Step 1: Get model data to find version_id if not provided and get additional metadata
-                async with session.get(f"{self.base_url}/models/{model_id}") as response:
-                    if response.status != 200:
-                        return None
-                        
-                    data = await response.json()
-                    model_versions = data.get('modelVersions', [])
-                    
-                    # Step 2: Determine the version_id to use
-                    target_version_id = version_id
-                    if target_version_id is None:
-                        target_version_id = model_versions[0].get('id')
-                
-                # Step 3: Get detailed version info using the version_id
-                async with session.get(f"{self.base_url}/model-versions/{target_version_id}", headers=headers) as response:
-                    if response.status != 200:
-                        return None
-                    
-                    version = await response.json()
-                    
-                    # Step 4: Enrich version_info with model data
-                    # Add description and tags from model data
-                    version['model']['description'] = data.get("description")
-                    version['model']['tags'] = data.get("tags", [])
-                    
-                    # Add creator from model data
-                    version['creator'] = data.get("creator")
-                    
-                    return version
-            
-            # Case 3: Neither model_id nor version_id provided
-            else:
-                logger.error("Either model_id or version_id must be provided")
-                return None
-                
+                return await self._get_version_by_id_only(version_id)
+
+            if model_id is not None:
+                return await self._get_version_with_model_id(model_id, version_id)
+
+            logger.error("Either model_id or version_id must be provided")
+            return None
+
+        except RateLimitError:
+            raise
         except Exception as e:
             logger.error(f"Error fetching model version: {e}")
             return None
 
+    async def _get_version_by_id_only(self, version_id: int) -> Optional[Dict]:
+        version = await self._fetch_version_by_id(version_id)
+        if version is None:
+            return None
+
+        model_id = version.get('modelId')
+        if not model_id:
+            logger.error(f"No modelId found in version {version_id}")
+            return None
+
+        model_data = await self._fetch_model_data(model_id)
+        if model_data:
+            self._enrich_version_with_model_data(version, model_data)
+
+        self._remove_comfy_metadata(version)
+        return version
+
+    async def _get_version_with_model_id(self, model_id: int, version_id: Optional[int]) -> Optional[Dict]:
+        model_data = await self._fetch_model_data(model_id)
+        if not model_data:
+            return None
+
+        target_version = self._select_target_version(model_data, model_id, version_id)
+        if target_version is None:
+            return None
+
+        target_version_id = target_version.get('id')
+        version = await self._fetch_version_by_id(target_version_id) if target_version_id else None
+
+        if version is None:
+            model_hash = self._extract_primary_model_hash(target_version)
+            if model_hash:
+                version = await self._fetch_version_by_hash(model_hash)
+            else:
+                logger.warning(
+                    f"No primary model hash found for model {model_id} version {target_version_id}"
+                )
+
+        if version is None:
+            version = self._build_version_from_model_data(target_version, model_id, model_data)
+
+        self._enrich_version_with_model_data(version, model_data)
+        self._remove_comfy_metadata(version)
+        return version
+
+    async def _fetch_model_data(self, model_id: int) -> Optional[Dict]:
+        success, data = await self._make_request(
+            'GET',
+            f"{self.base_url}/models/{model_id}",
+            use_auth=True
+        )
+        if success:
+            return data
+        logger.warning(f"Failed to fetch model data for model {model_id}")
+        return None
+
+    async def _fetch_version_by_id(self, version_id: Optional[int]) -> Optional[Dict]:
+        if version_id is None:
+            return None
+
+        success, version = await self._make_request(
+            'GET',
+            f"{self.base_url}/model-versions/{version_id}",
+            use_auth=True
+        )
+        if success:
+            return version
+
+        logger.warning(f"Failed to fetch version by id {version_id}")
+        return None
+
+    async def _fetch_version_by_hash(self, model_hash: Optional[str]) -> Optional[Dict]:
+        if not model_hash:
+            return None
+
+        success, version = await self._make_request(
+            'GET',
+            f"{self.base_url}/model-versions/by-hash/{model_hash}",
+            use_auth=True
+        )
+        if success:
+            return version
+
+        logger.warning(f"Failed to fetch version by hash {model_hash}")
+        return None
+
+    def _select_target_version(self, model_data: Dict, model_id: int, version_id: Optional[int]) -> Optional[Dict]:
+        model_versions = model_data.get('modelVersions', [])
+        if not model_versions:
+            logger.warning(f"No model versions found for model {model_id}")
+            return None
+
+        if version_id is not None:
+            target_version = next(
+                (item for item in model_versions if item.get('id') == version_id),
+                None
+            )
+            if target_version is None:
+                logger.warning(
+                    f"Version {version_id} not found for model {model_id}, defaulting to first version"
+                )
+                return model_versions[0]
+            return target_version
+
+        return model_versions[0]
+
+    def _extract_primary_model_hash(self, version_entry: Dict) -> Optional[str]:
+        for file_info in version_entry.get('files', []):
+            if file_info.get('type') == 'Model' and file_info.get('primary'):
+                hashes = file_info.get('hashes', {})
+                model_hash = hashes.get('SHA256')
+                if model_hash:
+                    return model_hash
+        return None
+
+    def _build_version_from_model_data(self, version_entry: Dict, model_id: int, model_data: Dict) -> Dict:
+        version = copy.deepcopy(version_entry)
+        version.pop('index', None)
+        version['modelId'] = model_id
+        version['model'] = {
+            'name': model_data.get('name'),
+            'type': model_data.get('type'),
+            'nsfw': model_data.get('nsfw'),
+            'poi': model_data.get('poi')
+        }
+        return version
+
+    def _enrich_version_with_model_data(self, version: Dict, model_data: Dict) -> None:
+        model_info = version.get('model')
+        if not isinstance(model_info, dict):
+            model_info = {}
+            version['model'] = model_info
+
+        model_info['description'] = model_data.get("description")
+        model_info['tags'] = model_data.get("tags", [])
+        version['creator'] = model_data.get("creator")
+
     async def get_model_version_info(self, version_id: str) -> Tuple[Optional[Dict], Optional[str]]:
         """Fetch model version metadata from Civitai
         
@@ -421,119 +349,39 @@ class CivitaiClient:
                 - An error message if there was an error, or None on success
         """
         try:
-            session = await self._ensure_fresh_session()
             url = f"{self.base_url}/model-versions/{version_id}"
-            headers = self._get_request_headers()
             
             logger.debug(f"Resolving DNS for model version info: {url}")
-            async with session.get(url, headers=headers) as response:
-                if response.status == 200:
-                    logger.debug(f"Successfully fetched model version info for: {version_id}")
-                    return await response.json(), None
-                
-                # Handle specific error cases
-                if response.status == 404:
-                    # Try to parse the error message
-                    try:
-                        error_data = await response.json()
-                        error_msg = error_data.get('error', f"Model not found (status 404)")
-                        logger.warning(f"Model version not found: {version_id} - {error_msg}")
-                        return None, error_msg
-                    except:
-                        return None, "Model not found (status 404)"
-                
-                # Other error cases
-                logger.error(f"Failed to fetch model info for {version_id} (status {response.status})")
-                return None, f"Failed to fetch model info (status {response.status})"
+            success, result = await self._make_request(
+                'GET',
+                url,
+                use_auth=True
+            )
+            
+            if success:
+                logger.debug(f"Successfully fetched model version info for: {version_id}")
+                self._remove_comfy_metadata(result)
+                return result, None
+            
+            # Handle specific error cases
+            if "not found" in str(result):
+                error_msg = f"Model not found"
+                logger.warning(f"Model version not found: {version_id} - {error_msg}")
+                return None, error_msg
+            
+            # Other error cases
+            logger.error(f"Failed to fetch model info for {version_id}: {result}")
+            return None, str(result)
+        except RateLimitError:
+            raise
         except Exception as e:
             error_msg = f"Error fetching model version info: {e}"
             logger.error(error_msg)
             return None, error_msg
 
-    async def get_model_metadata(self, model_id: str) -> Tuple[Optional[Dict], int]:
-        """Fetch model metadata (description, tags, and creator info) from Civitai API
-        
-        Args:
-            model_id: The Civitai model ID
-            
-        Returns:
-            Tuple[Optional[Dict], int]: A tuple containing:
-                - A dictionary with model metadata or None if not found
-                - The HTTP status code from the request
-        """
-        try:
-            session = await self._ensure_fresh_session()
-            headers = self._get_request_headers()
-            url = f"{self.base_url}/models/{model_id}"
-            
-            async with session.get(url, headers=headers) as response:
-                status_code = response.status
-                
-                if status_code != 200:
-                    logger.warning(f"Failed to fetch model metadata: Status {status_code}")
-                    return None, status_code
-                
-                data = await response.json()
-                
-                # Extract relevant metadata
-                metadata = {
-                    "description": data.get("description") or "No model description available",
-                    "tags": data.get("tags", []),
-                    "creator": {
-                        "username": data.get("creator", {}).get("username"),
-                        "image": data.get("creator", {}).get("image")
-                    }
-                }
-                
-                if metadata["description"] or metadata["tags"] or metadata["creator"]["username"]:
-                    return metadata, status_code
-                else:
-                    logger.warning(f"No metadata found for model {model_id}")
-                    return None, status_code
-                
-        except Exception as e:
-            logger.error(f"Error fetching model metadata: {e}", exc_info=True)
-            return None, 0
-
-    # Keep old method for backward compatibility, delegating to the new one
-    async def get_model_description(self, model_id: str) -> Optional[str]:
-        """Fetch the model description from Civitai API (Legacy method)"""
-        metadata, _ = await self.get_model_metadata(model_id)
-        return metadata.get("description") if metadata else None
-
-    async def close(self):
-        """Close the session if it exists"""
-        if self._session is not None:
-            await self._session.close()
-            self._session = None
-
-    async def _get_hash_from_civitai(self, model_version_id: str) -> Optional[str]:
-        """Get hash from Civitai API"""
-        try:
-            session = await self._ensure_fresh_session()
-            if not session:
-                return None
-            
-            version_info = await session.get(f"{self.base_url}/model-versions/{model_version_id}")
-            
-            if not version_info or not version_info.json().get('files'):
-                return None
-            
-            # Get hash from the first file
-            for file_info in version_info.json().get('files', []):
-                if file_info.get('hashes', {}).get('SHA256'):
-                    # Convert hash to lowercase to standardize
-                    hash_value = file_info['hashes']['SHA256'].lower()
-                    return hash_value
-                
-            return None
-        except Exception as e:
-            logger.error(f"Error getting hash from Civitai: {e}")
-            return None
-
     async def get_image_info(self, image_id: str) -> Optional[Dict]:
         """Fetch image information from Civitai API
-        
+
         Args:
             image_id: The Civitai image ID
             
@@ -541,23 +389,62 @@ class CivitaiClient:
             Optional[Dict]: The image data or None if not found
         """
         try:
-            session = await self._ensure_fresh_session()
-            headers = self._get_request_headers()
             url = f"{self.base_url}/images?imageId={image_id}&nsfw=X"
             
             logger.debug(f"Fetching image info for ID: {image_id}")
-            async with session.get(url, headers=headers) as response:
-                if response.status == 200:
-                    data = await response.json()
-                    if data and "items" in data and len(data["items"]) > 0:
-                        logger.debug(f"Successfully fetched image info for ID: {image_id}")
-                        return data["items"][0]
-                    logger.warning(f"No image found with ID: {image_id}")
-                    return None
-                
-                logger.error(f"Failed to fetch image info for ID: {image_id} (status {response.status})")
+            success, result = await self._make_request(
+                'GET',
+                url,
+                use_auth=True
+            )
+            
+            if success:
+                if result and "items" in result and len(result["items"]) > 0:
+                    logger.debug(f"Successfully fetched image info for ID: {image_id}")
+                    return result["items"][0]
+                logger.warning(f"No image found with ID: {image_id}")
                 return None
+            
+            logger.error(f"Failed to fetch image info for ID: {image_id}: {result}")
+            return None
+        except RateLimitError:
+            raise
         except Exception as e:
             error_msg = f"Error fetching image info: {e}"
             logger.error(error_msg)
             return None
+
+    async def get_user_models(self, username: str) -> Optional[List[Dict]]:
+        """Fetch all models for a specific Civitai user."""
+        if not username:
+            return None
+
+        try:
+            url = f"{self.base_url}/models?username={username}"
+            success, result = await self._make_request(
+                'GET',
+                url,
+                use_auth=True
+            )
+
+            if not success:
+                logger.error("Failed to fetch models for %s: %s", username, result)
+                return None
+
+            items = result.get("items") if isinstance(result, dict) else None
+            if not isinstance(items, list):
+                return []
+
+            for model in items:
+                versions = model.get("modelVersions")
+                if not isinstance(versions, list):
+                    continue
+                for version in versions:
+                    self._remove_comfy_metadata(version)
+
+            return items
+        except RateLimitError:
+            raise
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error fetching models for %s: %s", username, exc)
+            return None

py/services/download_coordinator.py

@@ -0,0 +1,178 @@
+"""Service wrapper for coordinating download lifecycle events."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from .downloader import DownloadProgress
+
+
+logger = logging.getLogger(__name__)
+
+
+class DownloadCoordinator:
+    """Manage download scheduling, cancellation and introspection."""
+
+    def __init__(
+        self,
+        *,
+        ws_manager,
+        download_manager_factory: Callable[[], Awaitable],
+    ) -> None:
+        self._ws_manager = ws_manager
+        self._download_manager_factory = download_manager_factory
+
+    async def schedule_download(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Schedule a download using the provided payload."""
+
+        download_manager = await self._download_manager_factory()
+
+        download_id = payload.get("download_id") or self._ws_manager.generate_download_id()
+        payload.setdefault("download_id", download_id)
+
+        async def progress_callback(progress: Any, snapshot: Optional[DownloadProgress] = None) -> None:
+            percent = 0.0
+            metrics: Optional[DownloadProgress] = None
+
+            if isinstance(progress, DownloadProgress):
+                metrics = progress
+                percent = progress.percent_complete
+            elif isinstance(snapshot, DownloadProgress):
+                metrics = snapshot
+                percent = snapshot.percent_complete
+            else:
+                try:
+                    percent = float(progress)
+                except (TypeError, ValueError):
+                    percent = 0.0
+
+            payload: Dict[str, Any] = {
+                "status": "progress",
+                "progress": round(percent),
+                "download_id": download_id,
+            }
+
+            if metrics is not None:
+                payload.update(
+                    {
+                        "bytes_downloaded": metrics.bytes_downloaded,
+                        "total_bytes": metrics.total_bytes,
+                        "bytes_per_second": metrics.bytes_per_second,
+                    }
+                )
+
+            await self._ws_manager.broadcast_download_progress(
+                download_id,
+                payload,
+            )
+
+        model_id = self._parse_optional_int(payload.get("model_id"), "model_id")
+        model_version_id = self._parse_optional_int(
+            payload.get("model_version_id"), "model_version_id"
+        )
+
+        if model_id is None and model_version_id is None:
+            raise ValueError(
+                "Missing required parameter: Please provide either 'model_id' or 'model_version_id'"
+            )
+
+        result = await download_manager.download_from_civitai(
+            model_id=model_id,
+            model_version_id=model_version_id,
+            save_dir=payload.get("model_root"),
+            relative_path=payload.get("relative_path", ""),
+            use_default_paths=payload.get("use_default_paths", False),
+            progress_callback=progress_callback,
+            download_id=download_id,
+            source=payload.get("source"),
+        )
+
+        result["download_id"] = download_id
+        return result
+
+    async def cancel_download(self, download_id: str) -> Dict[str, Any]:
+        """Cancel an active download and emit a broadcast event."""
+
+        download_manager = await self._download_manager_factory()
+        result = await download_manager.cancel_download(download_id)
+
+        await self._ws_manager.broadcast_download_progress(
+            download_id,
+            {
+                "status": "cancelled",
+                "progress": 0,
+                "download_id": download_id,
+                "message": "Download cancelled by user",
+            },
+        )
+
+        return result
+
+    async def pause_download(self, download_id: str) -> Dict[str, Any]:
+        """Pause an active download and notify listeners."""
+
+        download_manager = await self._download_manager_factory()
+        result = await download_manager.pause_download(download_id)
+
+        if result.get("success"):
+            cached_progress = self._ws_manager.get_download_progress(download_id) or {}
+            payload: Dict[str, Any] = {
+                "status": "paused",
+                "progress": cached_progress.get("progress", 0),
+                "download_id": download_id,
+                "message": "Download paused by user",
+            }
+
+            for field in ("bytes_downloaded", "total_bytes", "bytes_per_second"):
+                if field in cached_progress:
+                    payload[field] = cached_progress[field]
+
+            payload["bytes_per_second"] = 0.0
+
+            await self._ws_manager.broadcast_download_progress(download_id, payload)
+
+        return result
+
+    async def resume_download(self, download_id: str) -> Dict[str, Any]:
+        """Resume a paused download and notify listeners."""
+
+        download_manager = await self._download_manager_factory()
+        result = await download_manager.resume_download(download_id)
+
+        if result.get("success"):
+            cached_progress = self._ws_manager.get_download_progress(download_id) or {}
+            payload: Dict[str, Any] = {
+                "status": "downloading",
+                "progress": cached_progress.get("progress", 0),
+                "download_id": download_id,
+                "message": "Download resumed by user",
+            }
+
+            for field in ("bytes_downloaded", "total_bytes"):
+                if field in cached_progress:
+                    payload[field] = cached_progress[field]
+
+            payload["bytes_per_second"] = cached_progress.get("bytes_per_second", 0.0)
+
+            await self._ws_manager.broadcast_download_progress(download_id, payload)
+
+        return result
+
+    async def list_active_downloads(self) -> Dict[str, Any]:
+        """Return the active download map from the underlying manager."""
+
+        download_manager = await self._download_manager_factory()
+        return await download_manager.get_active_downloads()
+
+    def _parse_optional_int(self, value: Any, field: str) -> Optional[int]:
+        """Parse an optional integer from user input."""
+
+        if value is None or value == "":
+            return None
+
+        try:
+            return int(value)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"Invalid {field}: Must be an integer") from exc
+

py/services/download_manager.py

@@ -1,15 +1,20 @@
 import logging
 import os
 import asyncio
+import inspect
 from collections import OrderedDict
 import uuid
-from typing import Dict
+from typing import Dict, List, Optional, Tuple
+from urllib.parse import urlparse
 from ..utils.models import LoraMetadata, CheckpointMetadata, EmbeddingMetadata
-from ..utils.constants import CARD_PREVIEW_WIDTH, VALID_LORA_TYPES, CIVITAI_MODEL_TAGS
+from ..utils.constants import CARD_PREVIEW_WIDTH, VALID_LORA_TYPES
+from ..utils.civitai_utils import rewrite_preview_url
 from ..utils.exif_utils import ExifUtils
 from ..utils.metadata_manager import MetadataManager
 from .service_registry import ServiceRegistry
-from .settings_manager import settings
+from .settings_manager import get_settings_manager
+from .metadata_service import get_default_metadata_provider
+from .downloader import get_downloader, DownloadProgress
 
 # Download to temporary file first
 import tempfile
@@ -34,17 +39,11 @@ class DownloadManager:
             return
         self._initialized = True
         
-        self._civitai_client = None  # Will be lazily initialized
         # Add download management
         self._active_downloads = OrderedDict()  # download_id -> download_info
         self._download_semaphore = asyncio.Semaphore(5)  # Limit concurrent downloads
         self._download_tasks = {}  # download_id -> asyncio.Task
-
-    async def _get_civitai_client(self):
-        """Lazily initialize CivitaiClient from registry"""
-        if self._civitai_client is None:
-            self._civitai_client = await ServiceRegistry.get_civitai_client()
-        return self._civitai_client
+        self._pause_events: Dict[str, asyncio.Event] = {}
     
     async def _get_lora_scanner(self):
         """Get the lora scanner from registry"""
@@ -57,7 +56,7 @@ class DownloadManager:
     async def download_from_civitai(self, model_id: int = None, model_version_id: int = None, 
                                   save_dir: str = None, relative_path: str = '', 
                                   progress_callback=None, use_default_paths: bool = False,
-                                  download_id: str = None) -> Dict:
+                                  download_id: str = None, source: str = None) -> Dict:
         """Download model from Civitai with task tracking and concurrency control
         
         Args:
@@ -68,6 +67,7 @@ class DownloadManager:
             progress_callback: Callback function for progress updates
             use_default_paths: Flag to use default paths
             download_id: Unique identifier for this download task
+            source: Optional source parameter to specify metadata provider
             
         Returns:
             Dict with download result
@@ -84,14 +84,21 @@ class DownloadManager:
             'model_id': model_id,
             'model_version_id': model_version_id,
             'progress': 0,
-            'status': 'queued'
+            'status': 'queued',
+            'bytes_downloaded': 0,
+            'total_bytes': None,
+            'bytes_per_second': 0.0,
         }
+
+        pause_event = asyncio.Event()
+        pause_event.set()
+        self._pause_events[task_id] = pause_event
         
         # Create tracking task
         download_task = asyncio.create_task(
             self._download_with_semaphore(
-                task_id, model_id, model_version_id, save_dir, 
-                relative_path, progress_callback, use_default_paths
+                task_id, model_id, model_version_id, save_dir,
+                relative_path, progress_callback, use_default_paths, source
             )
         )
         
@@ -109,10 +116,12 @@ class DownloadManager:
             # Clean up task reference
             if task_id in self._download_tasks:
                 del self._download_tasks[task_id]
+            self._pause_events.pop(task_id, None)
 
     async def _download_with_semaphore(self, task_id: str, model_id: int, model_version_id: int,
-                                     save_dir: str, relative_path: str, 
-                                     progress_callback=None, use_default_paths: bool = False):
+                                     save_dir: str, relative_path: str,
+                                     progress_callback=None, use_default_paths: bool = False,
+                                     source: str = None):
         """Execute download with semaphore to limit concurrency"""
         # Update status to waiting
         if task_id in self._active_downloads:
@@ -120,15 +129,30 @@ class DownloadManager:
         
         # Wrap progress callback to track progress in active_downloads
         original_callback = progress_callback
-        async def tracking_callback(progress):
+        async def tracking_callback(progress, metrics=None):
+            progress_value, snapshot = self._normalize_progress(progress, metrics)
+
             if task_id in self._active_downloads:
-                self._active_downloads[task_id]['progress'] = progress
+                info = self._active_downloads[task_id]
+                info['progress'] = round(progress_value)
+                if snapshot is not None:
+                    info['bytes_downloaded'] = snapshot.bytes_downloaded
+                    info['total_bytes'] = snapshot.total_bytes
+                    info['bytes_per_second'] = snapshot.bytes_per_second
+
             if original_callback:
-                await original_callback(progress)
+                await self._dispatch_progress(original_callback, snapshot, progress_value)
         
         # Acquire semaphore to limit concurrent downloads
         try:
             async with self._download_semaphore:
+                pause_event = self._pause_events.get(task_id)
+                if pause_event is not None and not pause_event.is_set():
+                    if task_id in self._active_downloads:
+                        self._active_downloads[task_id]['status'] = 'paused'
+                        self._active_downloads[task_id]['bytes_per_second'] = 0.0
+                    await pause_event.wait()
+
                 # Update status to downloading
                 if task_id in self._active_downloads:
                     self._active_downloads[task_id]['status'] = 'downloading'
@@ -142,7 +166,7 @@ class DownloadManager:
                     result = await self._execute_original_download(
                         model_id, model_version_id, save_dir,
                         relative_path, tracking_callback, use_default_paths,
-                        task_id
+                        task_id, source
                     )
                     
                     # Update status based on result
@@ -150,12 +174,14 @@ class DownloadManager:
                         self._active_downloads[task_id]['status'] = 'completed' if result['success'] else 'failed'
                         if not result['success']:
                             self._active_downloads[task_id]['error'] = result.get('error', 'Unknown error')
+                        self._active_downloads[task_id]['bytes_per_second'] = 0.0
                     
                     return result
                 except asyncio.CancelledError:
                     # Handle cancellation
                     if task_id in self._active_downloads:
                         self._active_downloads[task_id]['status'] = 'cancelled'
+                        self._active_downloads[task_id]['bytes_per_second'] = 0.0
                     logger.info(f"Download cancelled for task {task_id}")
                     raise
                 except Exception as e:
@@ -164,6 +190,7 @@ class DownloadManager:
                     if task_id in self._active_downloads:
                         self._active_downloads[task_id]['status'] = 'failed'
                         self._active_downloads[task_id]['error'] = str(e)
+                        self._active_downloads[task_id]['bytes_per_second'] = 0.0
                     return {'success': False, 'error': str(e)}
         finally:
             # Schedule cleanup of download record after delay
@@ -175,9 +202,17 @@ class DownloadManager:
         if task_id in self._active_downloads:
             del self._active_downloads[task_id]
 
-    async def _execute_original_download(self, model_id, model_version_id, save_dir, 
-                                     relative_path, progress_callback, use_default_paths,
-                                     download_id=None):
+    async def _execute_original_download(
+        self,
+        model_id,
+        model_version_id,
+        save_dir,
+        relative_path,
+        progress_callback,
+        use_default_paths,
+        download_id=None,
+        source=None,
+    ):
         """Wrapper for original download_from_civitai implementation"""
         try:
             # Check if model version already exists in library
@@ -198,12 +233,11 @@ class DownloadManager:
                 # Check embedding scanner
                 if await embedding_scanner.check_model_version_exists(model_version_id):
                     return {'success': False, 'error': 'Model version already exists in embedding library'}
-
-            # Get civitai client
-            civitai_client = await self._get_civitai_client()
+          
+            metadata_provider = await get_default_metadata_provider()
 
             # Get version info based on the provided identifier
-            version_info = await civitai_client.get_model_version(model_id, model_version_id)
+            version_info = await metadata_provider.get_model_version(model_id, model_version_id)
             
             if not version_info:
                 return {'success': False, 'error': 'Failed to fetch model metadata'}
@@ -240,23 +274,24 @@ class DownloadManager:
             
             # Handle use_default_paths
             if use_default_paths:
+                settings_manager = get_settings_manager()
                 # Set save_dir based on model type
                 if model_type == 'checkpoint':
-                    default_path = settings.get('default_checkpoint_root')
+                    default_path = settings_manager.get('default_checkpoint_root')
                     if not default_path:
                         return {'success': False, 'error': 'Default checkpoint root path not set in settings'}
                     save_dir = default_path
                 elif model_type == 'lora':
-                    default_path = settings.get('default_lora_root')
+                    default_path = settings_manager.get('default_lora_root')
                     if not default_path:
                         return {'success': False, 'error': 'Default lora root path not set in settings'}
                     save_dir = default_path
                 elif model_type == 'embedding':
-                    default_path = settings.get('default_embedding_root')
+                    default_path = settings_manager.get('default_embedding_root')
                     if not default_path:
                         return {'success': False, 'error': 'Default embedding root path not set in settings'}
                     save_dir = default_path
-                    
+
                 # Calculate relative path using template
                 relative_path = self._calculate_relative_path(version_info, model_type)
 
@@ -290,9 +325,22 @@ class DownloadManager:
                 await progress_callback(0)
 
             # 2. Get file information
-            file_info = next((f for f in version_info.get('files', []) if f.get('primary')), None)
+            file_info = next((f for f in version_info.get('files', []) if f.get('primary') and f.get('type') == 'Model'), None)
             if not file_info:
                 return {'success': False, 'error': 'No primary file found in metadata'}
+            mirrors = file_info.get('mirrors') or []
+            download_urls = []
+            if mirrors:
+                for mirror in mirrors:
+                    if mirror.get('deletedAt') is None and mirror.get('url'):
+                        download_urls.append(mirror['url'])
+            else:
+                download_url = file_info.get('downloadUrl')
+                if download_url:
+                    download_urls.append(download_url)
+
+            if not download_urls:
+                return {'success': False, 'error': 'No mirror URL found'}
 
             # 3. Prepare download
             file_name = file_info['name']
@@ -311,14 +359,14 @@ class DownloadManager:
             
             # 6. Start download process
             result = await self._execute_download(
-                download_url=file_info.get('downloadUrl', ''),
+                download_urls=download_urls,
                 save_dir=save_dir,
                 metadata=metadata,
                 version_info=version_info,
                 relative_path=relative_path,
                 progress_callback=progress_callback,
                 model_type=model_type,
-                download_id=download_id
+                download_id=download_id,
             )
 
             # If early_access_msg exists and download failed, replace error message
@@ -346,7 +394,8 @@ class DownloadManager:
             Relative path string
         """
         # Get path template from settings for specific model type
-        path_template = settings.get_download_path_template(model_type)
+        settings_manager = get_settings_manager()
+        path_template = settings_manager.get_download_path_template(model_type)
         
         # If template is empty, return empty path (flat structure)
         if not path_template:
@@ -363,39 +412,38 @@ class DownloadManager:
             author = 'Anonymous'
         
         # Apply mapping if available
-        base_model_mappings = settings.get('base_model_path_mappings', {})
+        base_model_mappings = settings_manager.get('base_model_path_mappings', {})
         mapped_base_model = base_model_mappings.get(base_model, base_model)
         
         # Get model tags
         model_tags = version_info.get('model', {}).get('tags', [])
-        
-        # Find the first Civitai model tag that exists in model_tags
-        first_tag = ''
-        for civitai_tag in CIVITAI_MODEL_TAGS:
-            if civitai_tag in model_tags:
-                first_tag = civitai_tag
-                break
-        
-        # If no Civitai model tag found, fallback to first tag
-        if not first_tag and model_tags:
-            first_tag = model_tags[0]
-        
+
+        first_tag = settings_manager.resolve_priority_tag_for_model(model_tags, model_type)
+
         # Format the template with available data
         formatted_path = path_template
         formatted_path = formatted_path.replace('{base_model}', mapped_base_model)
         formatted_path = formatted_path.replace('{first_tag}', first_tag)
         formatted_path = formatted_path.replace('{author}', author)
-        
+
+        if model_type == 'embedding':
+            formatted_path = formatted_path.replace(' ', '_')
+
         return formatted_path
 
-    async def _execute_download(self, download_url: str, save_dir: str, 
-                          metadata, version_info: Dict, 
-                          relative_path: str, progress_callback=None,
-                          model_type: str = "lora", download_id: str = None) -> Dict:
+    async def _execute_download(
+        self,
+        download_urls: List[str],
+        save_dir: str,
+        metadata,
+        version_info: Dict,
+        relative_path: str,
+        progress_callback=None,
+        model_type: str = "lora",
+        download_id: str = None,
+    ) -> Dict:
         """Execute the actual download process including preview images and model files"""
         try:
-            civitai_client = await self._get_civitai_client()
-            
             # Extract original filename details
             original_filename = os.path.basename(metadata.file_path)
             base_name, extension = os.path.splitext(original_filename)
@@ -424,6 +472,8 @@ class DownloadManager:
                 
             part_path = save_path + '.part'
             metadata_path = os.path.splitext(save_path)[0] + '.metadata.json'
+
+            pause_event = self._pause_events.get(download_id) if download_id else None
             
             # Store file paths in active_downloads for potential cleanup
             if download_id and download_id in self._active_downloads:
@@ -433,85 +483,157 @@ class DownloadManager:
             # Download preview image if available
             images = version_info.get('images', [])
             if images:
-                # Report preview download progress
                 if progress_callback:
                     await progress_callback(1)  # 1% progress for starting preview download
 
-                # Check if it's a video or an image
-                is_video = images[0].get('type') == 'video'
-                
-                if (is_video):
-                    # For videos, use .mp4 extension
-                    preview_ext = '.mp4'
-                    preview_path = os.path.splitext(save_path)[0] + preview_ext
-                    
-                    # Download video directly
-                    if await civitai_client.download_preview_image(images[0]['url'], preview_path):
-                        metadata.preview_url = preview_path.replace(os.sep, '/')
-                        metadata.preview_nsfw_level = images[0].get('nsfwLevel', 0)
-                else:
-                    # For images, use WebP format for better performance
-                    with tempfile.NamedTemporaryFile(suffix='.png', delete=False) as temp_file:
-                        temp_path = temp_file.name
-                    
-                    # Download the original image to temp path
-                    if await civitai_client.download_preview_image(images[0]['url'], temp_path):
-                        # Optimize and convert to WebP
-                        preview_path = os.path.splitext(save_path)[0] + '.webp'
-                        
-                        # Use ExifUtils to optimize and convert the image
-                        optimized_data, _ = ExifUtils.optimize_image(
-                            image_data=temp_path,
-                            target_width=CARD_PREVIEW_WIDTH,
-                            format='webp',
-                            quality=85,
-                            preserve_metadata=False
-                        )
-                        
-                        # Save the optimized image
-                        with open(preview_path, 'wb') as f:
-                            f.write(optimized_data)
-                            
-                        # Update metadata
-                        metadata.preview_url = preview_path.replace(os.sep, '/')
-                        metadata.preview_nsfw_level = images[0].get('nsfwLevel', 0)
-                        
-                        # Remove temporary file
-                        try:
-                            os.unlink(temp_path)
-                        except Exception as e:
-                            logger.warning(f"Failed to delete temp file: {e}")
+                first_image = images[0] if isinstance(images[0], dict) else None
+                preview_url = first_image.get('url') if first_image else None
+                media_type = (first_image.get('type') or '').lower() if first_image else ''
+                nsfw_level = first_image.get('nsfwLevel', 0) if first_image else 0
+
+                def _extension_from_url(url: str, fallback: str) -> str:
+                    try:
+                        parsed = urlparse(url)
+                    except ValueError:
+                        return fallback
+                    ext = os.path.splitext(parsed.path)[1]
+                    return ext or fallback
+
+                preview_downloaded = False
+                preview_path = None
+
+                if preview_url:
+                    downloader = await get_downloader()
+
+                    if media_type == 'video':
+                        preview_ext = _extension_from_url(preview_url, '.mp4')
+                        preview_path = os.path.splitext(save_path)[0] + preview_ext
+                        rewritten_url, rewritten = rewrite_preview_url(preview_url, media_type='video')
+                        attempt_urls: List[str] = []
+                        if rewritten:
+                            attempt_urls.append(rewritten_url)
+                        attempt_urls.append(preview_url)
+
+                        seen_attempts = set()
+                        for attempt in attempt_urls:
+                            if not attempt or attempt in seen_attempts:
+                                continue
+                            seen_attempts.add(attempt)
+                            success, _ = await downloader.download_file(
+                                attempt,
+                                preview_path,
+                                use_auth=False
+                            )
+                            if success:
+                                preview_downloaded = True
+                                break
+                    else:
+                        rewritten_url, rewritten = rewrite_preview_url(preview_url, media_type='image')
+                        if rewritten:
+                            preview_ext = _extension_from_url(preview_url, '.png')
+                            preview_path = os.path.splitext(save_path)[0] + preview_ext
+                            success, _ = await downloader.download_file(
+                                rewritten_url,
+                                preview_path,
+                                use_auth=False
+                            )
+                            if success:
+                                preview_downloaded = True
+
+                        if not preview_downloaded:
+                            temp_path: str | None = None
+                            try:
+                                with tempfile.NamedTemporaryFile(suffix='.png', delete=False) as temp_file:
+                                    temp_path = temp_file.name
+
+                                success, content, _ = await downloader.download_to_memory(
+                                    preview_url,
+                                    use_auth=False
+                                )
+                                if success:
+                                    with open(temp_path, 'wb') as temp_file_handle:
+                                        temp_file_handle.write(content)
+                                    preview_path = os.path.splitext(save_path)[0] + '.webp'
+
+                                    optimized_data, _ = ExifUtils.optimize_image(
+                                        image_data=temp_path,
+                                        target_width=CARD_PREVIEW_WIDTH,
+                                        format='webp',
+                                        quality=85,
+                                        preserve_metadata=False
+                                    )
+
+                                    with open(preview_path, 'wb') as preview_file:
+                                        preview_file.write(optimized_data)
+
+                                    preview_downloaded = True
+                            finally:
+                                if temp_path and os.path.exists(temp_path):
+                                    try:
+                                        os.unlink(temp_path)
+                                    except Exception as e:
+                                        logger.warning(f"Failed to delete temp file: {e}")
+
+                if preview_downloaded and preview_path:
+                    metadata.preview_url = preview_path.replace(os.sep, '/')
+                    metadata.preview_nsfw_level = nsfw_level
+                    if download_id and download_id in self._active_downloads:
+                        self._active_downloads[download_id]['preview_path'] = preview_path
 
-                # Report preview download completion
                 if progress_callback:
                     await progress_callback(3)  # 3% progress after preview download
 
-            # Download model file with progress tracking
-            success, result = await civitai_client._download_file(
-                download_url, 
-                save_dir,
-                os.path.basename(save_path),
-                progress_callback=lambda p: self._handle_download_progress(p, progress_callback)
-            )
+            # Download model file with progress tracking using downloader
+            downloader = await get_downloader()
+            last_error = None
+            for download_url in download_urls:
+                use_auth = download_url.startswith("https://civitai.com/api/download/")
+                download_kwargs = {
+                    "progress_callback": lambda progress, snapshot=None: self._handle_download_progress(
+                        progress,
+                        progress_callback,
+                        snapshot,
+                    ),
+                    "use_auth": use_auth,  # Only use authentication for Civitai downloads
+                }
 
-            if not success:
+                if pause_event is not None:
+                    download_kwargs["pause_event"] = pause_event
+
+                success, result = await downloader.download_file(
+                    download_url,
+                    save_path,  # Use full path instead of separate dir and filename
+                    **download_kwargs,
+                )
+
+                if success:
+                    break
+
+                last_error = result
+                if os.path.exists(save_path):
+                    try:
+                        os.remove(save_path)
+                    except Exception as e:
+                        logger.warning(f"Failed to remove incomplete file {save_path}: {e}")
+            else:
                 # Clean up files on failure, but preserve .part file for resume
                 cleanup_files = [metadata_path]
-                if metadata.preview_url and os.path.exists(metadata.preview_url):
-                    cleanup_files.append(metadata.preview_url)
-                
+                preview_path_value = getattr(metadata, 'preview_url', None)
+                if preview_path_value and os.path.exists(preview_path_value):
+                    cleanup_files.append(preview_path_value)
+
                 for path in cleanup_files:
                     if path and os.path.exists(path):
                         try:
                             os.remove(path)
                         except Exception as e:
                             logger.warning(f"Failed to cleanup file {path}: {e}")
-                
+
                 # Log but don't remove .part file to allow resume
                 if os.path.exists(part_path):
                     logger.info(f"Preserving partial download for resume: {part_path}")
-                
-                return {'success': False, 'error': result}
+
+                return {'success': False, 'error': last_error or 'Failed to download file'}
 
             # 4. Update file information (size and modified time)
             metadata.update_file_info(save_path)
@@ -560,21 +682,37 @@ class DownloadManager:
             
             return {'success': False, 'error': str(e)}
 
-    async def _handle_download_progress(self, file_progress: float, progress_callback):
-        """Convert file download progress to overall progress
-        
-        Args:
-            file_progress: Progress of file download (0-100)
-            progress_callback: Callback function for progress updates
-        """
-        if progress_callback:
-            # Scale file progress to 3-100 range (after preview download)
-            overall_progress = 3 + (file_progress * 0.97)  # 97% of progress for file download
-            await progress_callback(round(overall_progress))
+    async def _handle_download_progress(
+        self,
+        progress_update,
+        progress_callback,
+        snapshot=None,
+    ):
+        """Convert file download progress to overall progress."""
+
+        if not progress_callback:
+            return
+
+        file_progress, original_snapshot = self._normalize_progress(progress_update, snapshot)
+        overall_progress = 3 + (file_progress * 0.97)
+        overall_progress = max(0.0, min(overall_progress, 100.0))
+        rounded_progress = round(overall_progress)
+
+        normalized_snapshot: Optional[DownloadProgress] = None
+        if original_snapshot is not None:
+            normalized_snapshot = DownloadProgress(
+                percent_complete=overall_progress,
+                bytes_downloaded=original_snapshot.bytes_downloaded,
+                total_bytes=original_snapshot.total_bytes,
+                bytes_per_second=original_snapshot.bytes_per_second,
+                timestamp=original_snapshot.timestamp,
+            )
+
+        await self._dispatch_progress(progress_callback, normalized_snapshot, rounded_progress)
             
     async def cancel_download(self, download_id: str) -> Dict:
         """Cancel an active download by download_id
-        
+
         Args:
             download_id: The unique identifier of the download task
             
@@ -588,10 +726,15 @@ class DownloadManager:
             # Get the task and cancel it
             task = self._download_tasks[download_id]
             task.cancel()
-            
+
+            pause_event = self._pause_events.get(download_id)
+            if pause_event is not None:
+                pause_event.set()
+
             # Update status in active downloads
             if download_id in self._active_downloads:
                 self._active_downloads[download_id]['status'] = 'cancelling'
+                self._active_downloads[download_id]['bytes_per_second'] = 0.0
             
             # Wait briefly for the task to acknowledge cancellation
             try:
@@ -632,7 +775,15 @@ class DownloadManager:
                         except Exception as e:
                             logger.error(f"Error deleting metadata file: {e}")
 
-                    # Delete preview file if exists (.webp or .mp4)
+                    preview_path_value = download_info.get('preview_path')
+                    if preview_path_value and os.path.exists(preview_path_value):
+                        try:
+                            os.unlink(preview_path_value)
+                            logger.debug(f"Deleted preview file: {preview_path_value}")
+                        except Exception as e:
+                            logger.error(f"Error deleting preview file: {e}")
+
+                    # Delete preview file if exists (.webp or .mp4) for legacy paths
                     for preview_ext in ['.webp', '.mp4']:
                         preview_path = os.path.splitext(file_path)[0] + preview_ext
                         if os.path.exists(preview_path):
@@ -646,7 +797,99 @@ class DownloadManager:
         except Exception as e:
             logger.error(f"Error cancelling download: {e}", exc_info=True)
             return {'success': False, 'error': str(e)}
-    
+        finally:
+            self._pause_events.pop(download_id, None)
+
+    async def pause_download(self, download_id: str) -> Dict:
+        """Pause an active download without losing progress."""
+
+        if download_id not in self._download_tasks:
+            return {'success': False, 'error': 'Download task not found'}
+
+        pause_event = self._pause_events.get(download_id)
+        if pause_event is None:
+            pause_event = asyncio.Event()
+            pause_event.set()
+            self._pause_events[download_id] = pause_event
+
+        if not pause_event.is_set():
+            return {'success': False, 'error': 'Download is already paused'}
+
+        pause_event.clear()
+
+        download_info = self._active_downloads.get(download_id)
+        if download_info is not None:
+            download_info['status'] = 'paused'
+            download_info['bytes_per_second'] = 0.0
+
+        return {'success': True, 'message': 'Download paused successfully'}
+
+    async def resume_download(self, download_id: str) -> Dict:
+        """Resume a previously paused download."""
+
+        pause_event = self._pause_events.get(download_id)
+        if pause_event is None:
+            return {'success': False, 'error': 'Download task not found'}
+
+        if pause_event.is_set():
+            return {'success': False, 'error': 'Download is not paused'}
+
+        pause_event.set()
+
+        download_info = self._active_downloads.get(download_id)
+        if download_info is not None:
+            if download_info.get('status') == 'paused':
+                download_info['status'] = 'downloading'
+            download_info.setdefault('bytes_per_second', 0.0)
+
+        return {'success': True, 'message': 'Download resumed successfully'}
+
+    @staticmethod
+    def _coerce_progress_value(progress) -> float:
+        try:
+            return float(progress)
+        except (TypeError, ValueError):
+            return 0.0
+
+    @classmethod
+    def _normalize_progress(
+        cls,
+        progress,
+        snapshot: Optional[DownloadProgress] = None,
+    ) -> Tuple[float, Optional[DownloadProgress]]:
+        if isinstance(progress, DownloadProgress):
+            return progress.percent_complete, progress
+
+        if isinstance(snapshot, DownloadProgress):
+            return snapshot.percent_complete, snapshot
+
+        if isinstance(progress, dict):
+            if 'percent_complete' in progress:
+                return cls._coerce_progress_value(progress['percent_complete']), snapshot
+            if 'progress' in progress:
+                return cls._coerce_progress_value(progress['progress']), snapshot
+
+        return cls._coerce_progress_value(progress), None
+
+    async def _dispatch_progress(
+        self,
+        callback,
+        snapshot: Optional[DownloadProgress],
+        progress_value: float,
+    ) -> None:
+        try:
+            if snapshot is not None:
+                result = callback(snapshot, snapshot)
+            else:
+                result = callback(progress_value)
+        except TypeError:
+            result = callback(progress_value)
+
+        if inspect.isawaitable(result):
+            await result
+        elif asyncio.iscoroutine(result):
+            await result
+
     async def get_active_downloads(self) -> Dict:
         """Get information about all active downloads
         
@@ -661,8 +904,11 @@ class DownloadManager:
                     'model_version_id': info.get('model_version_id'),
                     'progress': info.get('progress', 0),
                     'status': info.get('status', 'unknown'),
-                    'error': info.get('error', None)
+                    'error': info.get('error', None),
+                    'bytes_downloaded': info.get('bytes_downloaded', 0),
+                    'total_bytes': info.get('total_bytes'),
+                    'bytes_per_second': info.get('bytes_per_second', 0.0),
                 }
                 for task_id, info in self._active_downloads.items()
             ]
-        }
+        }

py/services/downloader.py

@@ -0,0 +1,662 @@
+"""
+Unified download manager for all HTTP/HTTPS downloads in the application.
+
+This module provides a centralized download service with:
+- Singleton pattern for global session management
+- Support for authenticated downloads (e.g., CivitAI API key)
+- Resumable downloads with automatic retry
+- Progress tracking and callbacks
+- Optimized connection pooling and timeouts
+- Unified error handling and logging
+"""
+
+import os
+import logging
+import asyncio
+import aiohttp
+from collections import deque
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from email.utils import parsedate_to_datetime
+from typing import Optional, Dict, Tuple, Callable, Union, Awaitable
+from ..services.settings_manager import get_settings_manager
+from .errors import RateLimitError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class DownloadProgress:
+    """Snapshot of a download transfer at a moment in time."""
+
+    percent_complete: float
+    bytes_downloaded: int
+    total_bytes: Optional[int]
+    bytes_per_second: float
+    timestamp: float
+
+
+class Downloader:
+    """Unified downloader for all HTTP/HTTPS downloads in the application."""
+    
+    _instance = None
+    _lock = asyncio.Lock()
+    
+    @classmethod
+    async def get_instance(cls):
+        """Get singleton instance of Downloader"""
+        async with cls._lock:
+            if cls._instance is None:
+                cls._instance = cls()
+            return cls._instance
+    
+    def __init__(self):
+        """Initialize the downloader with optimal settings"""
+        # Check if already initialized for singleton pattern
+        if hasattr(self, '_initialized'):
+            return
+        self._initialized = True
+        
+        # Session management
+        self._session = None
+        self._session_created_at = None
+        self._proxy_url = None  # Store proxy URL for current session
+        
+        # Configuration
+        self.chunk_size = 4 * 1024 * 1024  # 4MB chunks for better throughput
+        self.max_retries = 5
+        self.base_delay = 2.0  # Base delay for exponential backoff
+        self.session_timeout = 300  # 5 minutes
+        
+        # Default headers
+        self.default_headers = {
+            'User-Agent': 'ComfyUI-LoRA-Manager/1.0'
+        }
+    
+    @property
+    async def session(self) -> aiohttp.ClientSession:
+        """Get or create the global aiohttp session with optimized settings"""
+        if self._session is None or self._should_refresh_session():
+            await self._create_session()
+        return self._session
+    
+    @property
+    def proxy_url(self) -> Optional[str]:
+        """Get the current proxy URL (initialize if needed)"""
+        if not hasattr(self, '_proxy_url'):
+            self._proxy_url = None
+        return self._proxy_url
+    
+    def _should_refresh_session(self) -> bool:
+        """Check if session should be refreshed"""
+        if self._session is None:
+            return True
+        
+        if not hasattr(self, '_session_created_at') or self._session_created_at is None:
+            return True
+        
+        # Refresh if session is older than timeout
+        if (datetime.now() - self._session_created_at).total_seconds() > self.session_timeout:
+            return True
+        
+        return False
+    
+    async def _create_session(self):
+        """Create a new aiohttp session with optimized settings"""
+        # Close existing session if any
+        if self._session is not None:
+            await self._session.close()
+        
+        # Check for app-level proxy settings
+        proxy_url = None
+        settings_manager = get_settings_manager()
+        if settings_manager.get('proxy_enabled', False):
+            proxy_host = settings_manager.get('proxy_host', '').strip()
+            proxy_port = settings_manager.get('proxy_port', '').strip()
+            proxy_type = settings_manager.get('proxy_type', 'http').lower()
+            proxy_username = settings_manager.get('proxy_username', '').strip()
+            proxy_password = settings_manager.get('proxy_password', '').strip()
+            
+            if proxy_host and proxy_port:
+                # Build proxy URL
+                if proxy_username and proxy_password:
+                    proxy_url = f"{proxy_type}://{proxy_username}:{proxy_password}@{proxy_host}:{proxy_port}"
+                else:
+                    proxy_url = f"{proxy_type}://{proxy_host}:{proxy_port}"
+                
+                logger.debug(f"Using app-level proxy: {proxy_type}://{proxy_host}:{proxy_port}")
+                logger.debug("Proxy mode: app-level proxy is active.")
+        else:
+            logger.debug("Proxy mode: system-level proxy (trust_env) will be used if configured in environment.")
+        # Optimize TCP connection parameters
+        connector = aiohttp.TCPConnector(
+            ssl=True,
+            limit=8,  # Concurrent connections
+            ttl_dns_cache=300,  # DNS cache timeout
+            force_close=False,  # Keep connections for reuse
+            enable_cleanup_closed=True
+        )
+        
+        # Configure timeout parameters
+        timeout = aiohttp.ClientTimeout(
+            total=None,  # No total timeout for large downloads
+            connect=60,  # Connection timeout
+            sock_read=300  # 5 minute socket read timeout
+        )
+        
+        self._session = aiohttp.ClientSession(
+            connector=connector,
+            trust_env=proxy_url is None,  # Only use system proxy if no app-level proxy is set
+            timeout=timeout
+        )
+        
+        # Store proxy URL for use in requests
+        self._proxy_url = proxy_url
+        self._session_created_at = datetime.now()
+        
+        logger.debug("Created new HTTP session with proxy settings. App-level proxy: %s, System-level proxy (trust_env): %s", bool(proxy_url), proxy_url is None)
+    
+    def _get_auth_headers(self, use_auth: bool = False) -> Dict[str, str]:
+        """Get headers with optional authentication"""
+        headers = self.default_headers.copy()
+        
+        if use_auth:
+            # Add CivitAI API key if available
+            settings_manager = get_settings_manager()
+            api_key = settings_manager.get('civitai_api_key')
+            if api_key:
+                headers['Authorization'] = f'Bearer {api_key}'
+                headers['Content-Type'] = 'application/json'
+        
+        return headers
+    
+    async def download_file(
+        self,
+        url: str,
+        save_path: str,
+        progress_callback: Optional[Callable[..., Awaitable[None]]] = None,
+        use_auth: bool = False,
+        custom_headers: Optional[Dict[str, str]] = None,
+        allow_resume: bool = True,
+        pause_event: Optional[asyncio.Event] = None,
+    ) -> Tuple[bool, str]:
+        """
+        Download a file with resumable downloads and retry mechanism
+        
+        Args:
+            url: Download URL
+            save_path: Full path where the file should be saved
+            progress_callback: Optional callback for progress updates (0-100)
+            use_auth: Whether to include authentication headers (e.g., CivitAI API key)
+            custom_headers: Additional headers to include in request
+            allow_resume: Whether to support resumable downloads
+            pause_event: Optional event that, when cleared, will pause streaming until set again
+            
+        Returns:
+            Tuple[bool, str]: (success, save_path or error message)
+        """
+        retry_count = 0
+        part_path = save_path + '.part' if allow_resume else save_path
+        
+        # Prepare headers
+        headers = self._get_auth_headers(use_auth)
+        if custom_headers:
+            headers.update(custom_headers)
+        
+        # Get existing file size for resume
+        resume_offset = 0
+        if allow_resume and os.path.exists(part_path):
+            resume_offset = os.path.getsize(part_path)
+            logger.info(f"Resuming download from offset {resume_offset} bytes")
+        
+        total_size = 0
+        
+        while retry_count <= self.max_retries:
+            try:
+                session = await self.session
+                # Debug log for proxy mode at request time
+                if self.proxy_url:
+                    logger.debug(f"[download_file] Using app-level proxy: {self.proxy_url}")
+                else:
+                    logger.debug("[download_file] Using system-level proxy (trust_env) if configured.")
+                
+                # Add Range header for resume if we have partial data
+                request_headers = headers.copy()
+                if allow_resume and resume_offset > 0:
+                    request_headers['Range'] = f'bytes={resume_offset}-'
+                
+                # Disable compression for better chunked downloads
+                request_headers['Accept-Encoding'] = 'identity'
+                
+                logger.debug(f"Download attempt {retry_count + 1}/{self.max_retries + 1} from: {url}")
+                if resume_offset > 0:
+                    logger.debug(f"Requesting range from byte {resume_offset}")
+                
+                async with session.get(url, headers=request_headers, allow_redirects=True, proxy=self.proxy_url) as response:
+                    # Handle different response codes
+                    if response.status == 200:
+                        # Full content response
+                        if resume_offset > 0:
+                            # Server doesn't support ranges, restart from beginning
+                            logger.warning("Server doesn't support range requests, restarting download")
+                            resume_offset = 0
+                            if os.path.exists(part_path):
+                                os.remove(part_path)
+                    elif response.status == 206:
+                        # Partial content response (resume successful)
+                        content_range = response.headers.get('Content-Range')
+                        if content_range:
+                            # Parse total size from Content-Range header (e.g., "bytes 1024-2047/2048")
+                            range_parts = content_range.split('/')
+                            if len(range_parts) == 2:
+                                total_size = int(range_parts[1])
+                        logger.info(f"Successfully resumed download from byte {resume_offset}")
+                    elif response.status == 416:
+                        # Range not satisfiable - file might be complete or corrupted
+                        if allow_resume and os.path.exists(part_path):
+                            part_size = os.path.getsize(part_path)
+                            logger.warning(f"Range not satisfiable. Part file size: {part_size}")
+                            # Try to get actual file size
+                            head_response = await session.head(url, headers=headers, proxy=self.proxy_url)
+                            if head_response.status == 200:
+                                actual_size = int(head_response.headers.get('content-length', 0))
+                                if part_size == actual_size:
+                                    # File is complete, just rename it
+                                    if allow_resume:
+                                        os.rename(part_path, save_path)
+                                    if progress_callback:
+                                        await self._dispatch_progress_callback(
+                                            progress_callback,
+                                            DownloadProgress(
+                                                percent_complete=100.0,
+                                                bytes_downloaded=part_size,
+                                                total_bytes=actual_size,
+                                                bytes_per_second=0.0,
+                                                timestamp=datetime.now().timestamp(),
+                                            ),
+                                        )
+                                    return True, save_path
+                            # Remove corrupted part file and restart
+                            os.remove(part_path)
+                            resume_offset = 0
+                            continue
+                    elif response.status == 401:
+                        logger.warning(f"Unauthorized access to resource: {url} (Status 401)")
+                        return False, "Invalid or missing API key, or early access restriction."
+                    elif response.status == 403:
+                        logger.warning(f"Forbidden access to resource: {url} (Status 403)")
+                        return False, "Access forbidden: You don't have permission to download this file."
+                    elif response.status == 404:
+                        logger.warning(f"Resource not found: {url} (Status 404)")
+                        return False, "File not found - the download link may be invalid or expired."
+                    else:
+                        logger.error(f"Download failed for {url} with status {response.status}")
+                        return False, f"Download failed with status {response.status}"
+                    
+                    # Get total file size for progress calculation (if not set from Content-Range)
+                    if total_size == 0:
+                        total_size = int(response.headers.get('content-length', 0))
+                        if response.status == 206:
+                            # For partial content, add the offset to get total file size
+                            total_size += resume_offset
+                    
+                    current_size = resume_offset
+                    last_progress_report_time = datetime.now()
+                    progress_samples: deque[tuple[datetime, int]] = deque()
+                    progress_samples.append((last_progress_report_time, current_size))
+                    
+                    # Ensure directory exists
+                    os.makedirs(os.path.dirname(save_path), exist_ok=True)
+                    
+                    # Stream download to file with progress updates
+                    loop = asyncio.get_running_loop()
+                    mode = 'ab' if (allow_resume and resume_offset > 0) else 'wb'
+                    with open(part_path, mode) as f:
+                        async for chunk in response.content.iter_chunked(self.chunk_size):
+                            if pause_event is not None and not pause_event.is_set():
+                                await pause_event.wait()
+                            if chunk:
+                                # Run blocking file write in executor
+                                await loop.run_in_executor(None, f.write, chunk)
+                                current_size += len(chunk)
+
+                                # Limit progress update frequency to reduce overhead
+                                now = datetime.now()
+                                time_diff = (now - last_progress_report_time).total_seconds()
+
+                                if progress_callback and time_diff >= 1.0:
+                                    progress_samples.append((now, current_size))
+                                    cutoff = now - timedelta(seconds=5)
+                                    while progress_samples and progress_samples[0][0] < cutoff:
+                                        progress_samples.popleft()
+
+                                    percent = (current_size / total_size) * 100 if total_size else 0.0
+                                    bytes_per_second = 0.0
+                                    if len(progress_samples) >= 2:
+                                        first_time, first_bytes = progress_samples[0]
+                                        last_time, last_bytes = progress_samples[-1]
+                                        elapsed = (last_time - first_time).total_seconds()
+                                        if elapsed > 0:
+                                            bytes_per_second = (last_bytes - first_bytes) / elapsed
+
+                                    progress_snapshot = DownloadProgress(
+                                        percent_complete=percent,
+                                        bytes_downloaded=current_size,
+                                        total_bytes=total_size or None,
+                                        bytes_per_second=bytes_per_second,
+                                        timestamp=now.timestamp(),
+                                    )
+
+                                    await self._dispatch_progress_callback(progress_callback, progress_snapshot)
+                                    last_progress_report_time = now
+                    
+                    # Download completed successfully
+                    # Verify file size if total_size was provided
+                    final_size = os.path.getsize(part_path)
+                    if total_size > 0 and final_size != total_size:
+                        logger.warning(f"File size mismatch. Expected: {total_size}, Got: {final_size}")
+                        # Don't treat this as fatal error, continue anyway
+                    
+                    # Atomically rename .part to final file (only if using resume)
+                    if allow_resume and part_path != save_path:
+                        max_rename_attempts = 5
+                        rename_attempt = 0
+                        rename_success = False
+                        
+                        while rename_attempt < max_rename_attempts and not rename_success:
+                            try:
+                                # If the destination file exists, remove it first (Windows safe)
+                                if os.path.exists(save_path):
+                                    os.remove(save_path)
+
+                                os.rename(part_path, save_path)
+                                rename_success = True
+                            except PermissionError as e:
+                                rename_attempt += 1
+                                if rename_attempt < max_rename_attempts:
+                                    logger.info(f"File still in use, retrying rename in 2 seconds (attempt {rename_attempt}/{max_rename_attempts})")
+                                    await asyncio.sleep(2)
+                                else:
+                                    logger.error(f"Failed to rename file after {max_rename_attempts} attempts: {e}")
+                                    return False, f"Failed to finalize download: {str(e)}"
+                    
+                    # Ensure 100% progress is reported
+                    if progress_callback:
+                        final_snapshot = DownloadProgress(
+                            percent_complete=100.0,
+                            bytes_downloaded=final_size,
+                            total_bytes=total_size or final_size,
+                            bytes_per_second=0.0,
+                            timestamp=datetime.now().timestamp(),
+                        )
+                        await self._dispatch_progress_callback(progress_callback, final_snapshot)
+
+                    
+                    return True, save_path
+                    
+            except (aiohttp.ClientError, aiohttp.ClientPayloadError,
+                    aiohttp.ServerDisconnectedError, asyncio.TimeoutError) as e:
+                retry_count += 1
+                logger.warning(f"Network error during download (attempt {retry_count}/{self.max_retries + 1}): {e}")
+                
+                if retry_count <= self.max_retries:
+                    # Calculate delay with exponential backoff
+                    delay = self.base_delay * (2 ** (retry_count - 1))
+                    logger.info(f"Retrying in {delay} seconds...")
+                    await asyncio.sleep(delay)
+                    
+                    # Update resume offset for next attempt
+                    if allow_resume and os.path.exists(part_path):
+                        resume_offset = os.path.getsize(part_path)
+                        logger.info(f"Will resume from byte {resume_offset}")
+                    
+                    # Refresh session to get new connection
+                    await self._create_session()
+                    continue
+                else:
+                    logger.error(f"Max retries exceeded for download: {e}")
+                    return False, f"Network error after {self.max_retries + 1} attempts: {str(e)}"
+                    
+            except Exception as e:
+                logger.error(f"Unexpected download error: {e}")
+                return False, str(e)
+        
+        return False, f"Download failed after {self.max_retries + 1} attempts"
+
+    async def _dispatch_progress_callback(
+        self,
+        progress_callback: Callable[..., Awaitable[None]],
+        snapshot: DownloadProgress,
+    ) -> None:
+        """Invoke a progress callback while preserving backward compatibility."""
+
+        try:
+            result = progress_callback(snapshot, snapshot)
+        except TypeError:
+            result = progress_callback(snapshot.percent_complete)
+
+        if asyncio.iscoroutine(result):
+            await result
+        elif hasattr(result, "__await__"):
+            await result
+
+    async def download_to_memory(
+        self,
+        url: str,
+        use_auth: bool = False,
+        custom_headers: Optional[Dict[str, str]] = None,
+        return_headers: bool = False
+    ) -> Tuple[bool, Union[bytes, str], Optional[Dict]]:
+        """
+        Download a file to memory (for small files like preview images)
+        
+        Args:
+            url: Download URL
+            use_auth: Whether to include authentication headers
+            custom_headers: Additional headers to include in request
+            return_headers: Whether to return response headers along with content
+            
+        Returns:
+            Tuple[bool, Union[bytes, str], Optional[Dict]]: (success, content or error message, response headers if requested)
+        """
+        try:
+            session = await self.session
+            # Debug log for proxy mode at request time
+            if self.proxy_url:
+                logger.debug(f"[download_to_memory] Using app-level proxy: {self.proxy_url}")
+            else:
+                logger.debug("[download_to_memory] Using system-level proxy (trust_env) if configured.")
+            
+            # Prepare headers
+            headers = self._get_auth_headers(use_auth)
+            if custom_headers:
+                headers.update(custom_headers)
+            
+            async with session.get(url, headers=headers, proxy=self.proxy_url) as response:
+                if response.status == 200:
+                    content = await response.read()
+                    if return_headers:
+                        return True, content, dict(response.headers)
+                    else:
+                        return True, content, None
+                elif response.status == 401:
+                    error_msg = "Unauthorized access - invalid or missing API key"
+                    return False, error_msg, None
+                elif response.status == 403:
+                    error_msg = "Access forbidden"
+                    return False, error_msg, None
+                elif response.status == 404:
+                    error_msg = "File not found"
+                    return False, error_msg, None
+                else:
+                    error_msg = f"Download failed with status {response.status}"
+                    return False, error_msg, None
+                    
+        except Exception as e:
+            logger.error(f"Error downloading to memory from {url}: {e}")
+            return False, str(e), None
+    
+    async def get_response_headers(
+        self,
+        url: str,
+        use_auth: bool = False,
+        custom_headers: Optional[Dict[str, str]] = None
+    ) -> Tuple[bool, Union[Dict, str]]:
+        """
+        Get response headers without downloading the full content
+        
+        Args:
+            url: URL to check
+            use_auth: Whether to include authentication headers
+            custom_headers: Additional headers to include in request
+            
+        Returns:
+            Tuple[bool, Union[Dict, str]]: (success, headers dict or error message)
+        """
+        try:
+            session = await self.session
+            # Debug log for proxy mode at request time
+            if self.proxy_url:
+                logger.debug(f"[get_response_headers] Using app-level proxy: {self.proxy_url}")
+            else:
+                logger.debug("[get_response_headers] Using system-level proxy (trust_env) if configured.")
+            
+            # Prepare headers
+            headers = self._get_auth_headers(use_auth)
+            if custom_headers:
+                headers.update(custom_headers)
+            
+            async with session.head(url, headers=headers, proxy=self.proxy_url) as response:
+                if response.status == 200:
+                    return True, dict(response.headers)
+                else:
+                    return False, f"Head request failed with status {response.status}"
+                    
+        except Exception as e:
+            logger.error(f"Error getting headers from {url}: {e}")
+            return False, str(e)
+    
+    async def make_request(
+        self,
+        method: str,
+        url: str,
+        use_auth: bool = False,
+        custom_headers: Optional[Dict[str, str]] = None,
+        **kwargs
+    ) -> Tuple[bool, Union[Dict, str]]:
+        """
+        Make a generic HTTP request and return JSON response
+        
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            url: Request URL
+            use_auth: Whether to include authentication headers
+            custom_headers: Additional headers to include in request
+            **kwargs: Additional arguments for aiohttp request
+            
+        Returns:
+            Tuple[bool, Union[Dict, str]]: (success, response data or error message)
+        """
+        try:
+            session = await self.session
+            # Debug log for proxy mode at request time
+            if self.proxy_url:
+                logger.debug(f"[make_request] Using app-level proxy: {self.proxy_url}")
+            else:
+                logger.debug("[make_request] Using system-level proxy (trust_env) if configured.")
+            
+            # Prepare headers
+            headers = self._get_auth_headers(use_auth)
+            if custom_headers:
+                headers.update(custom_headers)
+            
+            # Add proxy to kwargs if not already present
+            if 'proxy' not in kwargs:
+                kwargs['proxy'] = self.proxy_url
+            
+            async with session.request(method, url, headers=headers, **kwargs) as response:
+                if response.status == 200:
+                    # Try to parse as JSON, fall back to text
+                    try:
+                        data = await response.json()
+                        return True, data
+                    except:
+                        text = await response.text()
+                        return True, text
+                elif response.status == 401:
+                    return False, "Unauthorized access - invalid or missing API key"
+                elif response.status == 403:
+                    return False, "Access forbidden"
+                elif response.status == 404:
+                    return False, "Resource not found"
+                elif response.status == 429:
+                    retry_after = self._extract_retry_after(response.headers)
+                    error_msg = "Request rate limited"
+                    logger.warning(
+                        "Rate limit encountered for %s %s; retry_after=%s",
+                        method,
+                        url,
+                        retry_after,
+                    )
+                    return False, RateLimitError(
+                        error_msg,
+                        retry_after=retry_after,
+                    )
+                else:
+                    return False, f"Request failed with status {response.status}"
+                    
+        except Exception as e:
+            logger.error(f"Error making {method} request to {url}: {e}")
+            return False, str(e)
+    
+    async def close(self):
+        """Close the HTTP session"""
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+            self._session_created_at = None
+            self._proxy_url = None
+            logger.debug("Closed HTTP session")
+    
+    async def refresh_session(self):
+        """Force refresh the HTTP session (useful when proxy settings change)"""
+        await self._create_session()
+        logger.info("HTTP session refreshed due to settings change")
+
+    @staticmethod
+    def _extract_retry_after(headers) -> Optional[float]:
+        """Parse the Retry-After header into seconds."""
+        if not headers:
+            return None
+
+        header_value = headers.get("Retry-After")
+        if not header_value:
+            return None
+
+        header_value = header_value.strip()
+        if not header_value:
+            return None
+
+        if header_value.isdigit():
+            try:
+                seconds = float(header_value)
+            except ValueError:
+                return None
+            return max(0.0, seconds)
+
+        try:
+            retry_datetime = parsedate_to_datetime(header_value)
+        except (TypeError, ValueError):
+            return None
+
+        if retry_datetime.tzinfo is None:
+            return None
+
+        delta = retry_datetime - datetime.now(tz=retry_datetime.tzinfo)
+        return max(0.0, delta.total_seconds())
+
+
+# Global instance accessor
+async def get_downloader() -> Downloader:
+    """Get the global downloader instance"""
+    return await Downloader.get_instance()

py/services/embedding_service.py

@@ -1,24 +1,24 @@
 import os
 import logging
-from typing import Dict, List, Optional
+from typing import Dict
 
 from .base_model_service import BaseModelService
 from ..utils.models import EmbeddingMetadata
 from ..config import config
-from ..utils.routes_common import ModelRouteUtils
 
 logger = logging.getLogger(__name__)
 
 class EmbeddingService(BaseModelService):
     """Embedding-specific service implementation"""
     
-    def __init__(self, scanner):
+    def __init__(self, scanner, update_service=None):
         """Initialize Embedding service
         
         Args:
             scanner: Embedding scanner instance
+            update_service: Optional service for remote update tracking.
         """
-        super().__init__("embedding", scanner, EmbeddingMetadata)
+        super().__init__("embedding", scanner, EmbeddingMetadata, update_service=update_service)
     
     async def format_response(self, embedding_data: Dict) -> Dict:
         """Format Embedding data for API response"""
@@ -38,7 +38,7 @@ class EmbeddingService(BaseModelService):
             "notes": embedding_data.get("notes", ""),
             "model_type": embedding_data.get("model_type", "embedding"),
             "favorite": embedding_data.get("favorite", False),
-            "civitai": ModelRouteUtils.filter_civitai_data(embedding_data.get("civitai", {}), minimal=True)
+            "civitai": self.filter_civitai_data(embedding_data.get("civitai", {}), minimal=True)
         }
     
     def find_duplicate_hashes(self) -> Dict:

py/services/errors.py

@@ -0,0 +1,21 @@
+"""Common service-level exception types."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class RateLimitError(RuntimeError):
+    """Raised when a remote provider rejects a request due to rate limiting."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: Optional[float] = None,
+        provider: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+        self.provider = provider
+

py/services/example_images_cleanup_service.py

@@ -0,0 +1,297 @@
+"""Service for cleaning up example image folders."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from .service_registry import ServiceRegistry
+from .settings_manager import get_settings_manager
+from ..utils.example_images_paths import iter_library_roots
+
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class CleanupResult:
+    """Structured result returned from cleanup operations."""
+
+    success: bool
+    checked_folders: int
+    moved_empty_folders: int
+    moved_orphaned_folders: int
+    skipped_non_hash: int
+    move_failures: int
+    errors: List[str]
+    deleted_root: str | None
+    partial_success: bool
+
+    def to_dict(self) -> Dict[str, object]:
+        """Convert the dataclass to a serialisable dictionary."""
+
+        data = {
+            "success": self.success,
+            "checked_folders": self.checked_folders,
+            "moved_empty_folders": self.moved_empty_folders,
+            "moved_orphaned_folders": self.moved_orphaned_folders,
+            "moved_total": self.moved_empty_folders + self.moved_orphaned_folders,
+            "skipped_non_hash": self.skipped_non_hash,
+            "move_failures": self.move_failures,
+            "errors": self.errors,
+            "deleted_root": self.deleted_root,
+            "partial_success": self.partial_success,
+        }
+
+        return data
+
+
+class ExampleImagesCleanupService:
+    """Encapsulates logic for cleaning example image folders."""
+
+    DELETED_FOLDER_NAME = "_deleted"
+
+    def __init__(self, deleted_folder_name: str | None = None) -> None:
+        self._deleted_folder_name = deleted_folder_name or self.DELETED_FOLDER_NAME
+
+    async def cleanup_example_image_folders(self) -> Dict[str, object]:
+        """Clean empty or orphaned example image folders by moving them under a deleted bucket."""
+
+        settings_manager = get_settings_manager()
+        example_images_path = settings_manager.get("example_images_path")
+        if not example_images_path:
+            logger.debug("Cleanup skipped: example images path not configured")
+            return {
+                "success": False,
+                "error": "Example images path is not configured.",
+                "error_code": "path_not_configured",
+            }
+
+        base_root = Path(example_images_path)
+        if not base_root.exists():
+            logger.debug("Cleanup skipped: example images path missing -> %s", base_root)
+            return {
+                "success": False,
+                "error": "Example images path does not exist.",
+                "error_code": "path_not_found",
+            }
+
+        try:
+            lora_scanner = await ServiceRegistry.get_lora_scanner()
+            checkpoint_scanner = await ServiceRegistry.get_checkpoint_scanner()
+            embedding_scanner = await ServiceRegistry.get_embedding_scanner()
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.error("Failed to acquire scanners for cleanup: %s", exc, exc_info=True)
+            return {
+                "success": False,
+                "error": f"Failed to load model scanners: {exc}",
+                "error_code": "scanner_initialization_failed",
+            }
+
+        checked_folders = 0
+        moved_empty = 0
+        moved_orphaned = 0
+        skipped_non_hash = 0
+        move_failures = 0
+        errors: List[str] = []
+
+        resolved_base = base_root.resolve()
+        library_paths: List[Tuple[str, Path]] = []
+        processed_paths = {resolved_base}
+
+        for library_name, library_path in iter_library_roots():
+            if not library_path:
+                continue
+            library_root = Path(library_path)
+            try:
+                resolved = library_root.resolve()
+            except FileNotFoundError:
+                continue
+            if resolved in processed_paths:
+                continue
+            if not library_root.exists():
+                logger.debug(
+                    "Skipping cleanup for library '%s': folder missing (%s)",
+                    library_name,
+                    library_root,
+                )
+                continue
+            processed_paths.add(resolved)
+            library_paths.append((library_name, library_root))
+
+        deleted_roots: List[Path] = []
+
+        # Build list of (label, root) pairs including the base root for legacy layouts
+        cleanup_targets: List[Tuple[str, Path]] = [("__base__", base_root)] + library_paths
+
+        library_root_set = {root.resolve() for _, root in library_paths}
+
+        for label, root_path in cleanup_targets:
+            deleted_bucket = root_path / self._deleted_folder_name
+            deleted_bucket.mkdir(exist_ok=True)
+            deleted_roots.append(deleted_bucket)
+
+            for entry in os.scandir(root_path):
+                if not entry.is_dir(follow_symlinks=False):
+                    continue
+
+                if entry.name == self._deleted_folder_name:
+                    continue
+
+                entry_path = Path(entry.path)
+
+                if label == "__base__":
+                    try:
+                        resolved_entry = entry_path.resolve()
+                    except FileNotFoundError:
+                        continue
+                    if resolved_entry in library_root_set:
+                        # Skip library-specific folders tracked separately
+                        continue
+
+                checked_folders += 1
+
+                try:
+                    if self._is_folder_empty(entry_path):
+                        if await self._remove_empty_folder(entry_path):
+                            moved_empty += 1
+                        else:
+                            move_failures += 1
+                        continue
+
+                    if not self._is_hash_folder(entry.name):
+                        skipped_non_hash += 1
+                        continue
+
+                    hash_exists = (
+                        lora_scanner.has_hash(entry.name)
+                        or checkpoint_scanner.has_hash(entry.name)
+                        or embedding_scanner.has_hash(entry.name)
+                    )
+
+                    if not hash_exists:
+                        if await self._move_folder(entry_path, deleted_bucket):
+                            moved_orphaned += 1
+                        else:
+                            move_failures += 1
+
+                except Exception as exc:  # pragma: no cover - filesystem guard
+                    move_failures += 1
+                    error_message = f"{entry.name}: {exc}"
+                    errors.append(error_message)
+                    logger.error(
+                        "Error processing example images folder %s: %s",
+                        entry_path,
+                        exc,
+                        exc_info=True,
+                    )
+
+        partial_success = move_failures > 0 and (moved_empty > 0 or moved_orphaned > 0)
+        success = move_failures == 0 and not errors
+
+        result = CleanupResult(
+            success=success,
+            checked_folders=checked_folders,
+            moved_empty_folders=moved_empty,
+            moved_orphaned_folders=moved_orphaned,
+            skipped_non_hash=skipped_non_hash,
+            move_failures=move_failures,
+            errors=errors,
+            deleted_root=str(deleted_roots[0]) if deleted_roots else None,
+            partial_success=partial_success,
+        )
+
+        summary = result.to_dict()
+        summary["deleted_roots"] = [str(path) for path in deleted_roots]
+        if success:
+            logger.info(
+                "Example images cleanup complete: checked=%s, moved_empty=%s, moved_orphaned=%s",
+                checked_folders,
+                moved_empty,
+                moved_orphaned,
+            )
+        elif partial_success:
+            logger.warning(
+                "Example images cleanup partially complete: moved=%s, failures=%s",
+                summary["moved_total"],
+                move_failures,
+            )
+        else:
+            logger.error(
+                "Example images cleanup failed: move_failures=%s, errors=%s",
+                move_failures,
+                errors,
+            )
+
+        return summary
+
+    @staticmethod
+    def _is_folder_empty(folder_path: Path) -> bool:
+        try:
+            with os.scandir(folder_path) as iterator:
+                return not any(iterator)
+        except FileNotFoundError:
+            return True
+        except OSError as exc:  # pragma: no cover - defensive guard
+            logger.debug("Failed to inspect folder %s: %s", folder_path, exc)
+            return False
+
+    @staticmethod
+    def _is_hash_folder(name: str) -> bool:
+        if len(name) != 64:
+            return False
+        hex_chars = set("0123456789abcdefABCDEF")
+        return all(char in hex_chars for char in name)
+
+    async def _remove_empty_folder(self, folder_path: Path) -> bool:
+        loop = asyncio.get_running_loop()
+
+        try:
+            await loop.run_in_executor(
+                None,
+                shutil.rmtree,
+                str(folder_path),
+            )
+            logger.debug("Removed empty example images folder %s", folder_path)
+            return True
+        except Exception as exc:  # pragma: no cover - filesystem guard
+            logger.error("Failed to remove empty example images folder %s: %s", folder_path, exc, exc_info=True)
+            return False
+
+    async def _move_folder(self, folder_path: Path, deleted_bucket: Path) -> bool:
+        destination = self._build_destination(folder_path.name, deleted_bucket)
+        loop = asyncio.get_running_loop()
+
+        try:
+            await loop.run_in_executor(
+                None,
+                shutil.move,
+                str(folder_path),
+                str(destination),
+            )
+            logger.debug("Moved example images folder %s -> %s", folder_path, destination)
+            return True
+        except Exception as exc:  # pragma: no cover - filesystem guard
+            logger.error(
+                "Failed to move example images folder %s to %s: %s",
+                folder_path,
+                destination,
+                exc,
+                exc_info=True,
+            )
+            return False
+
+    def _build_destination(self, folder_name: str, deleted_bucket: Path) -> Path:
+        destination = deleted_bucket / folder_name
+        suffix = 1
+
+        while destination.exists():
+            destination = deleted_bucket / f"{folder_name}_{suffix}"
+            suffix += 1
+
+        return destination

py/services/lora_service.py

@@ -5,20 +5,20 @@ from typing import Dict, List, Optional
 from .base_model_service import BaseModelService
 from ..utils.models import LoraMetadata
 from ..config import config
-from ..utils.routes_common import ModelRouteUtils
 
 logger = logging.getLogger(__name__)
 
 class LoraService(BaseModelService):
     """LoRA-specific service implementation"""
     
-    def __init__(self, scanner):
+    def __init__(self, scanner, update_service=None):
         """Initialize LoRA service
         
         Args:
             scanner: LoRA scanner instance
+            update_service: Optional service for remote update tracking.
         """
-        super().__init__("lora", scanner, LoraMetadata)
+        super().__init__("lora", scanner, LoraMetadata, update_service=update_service)
     
     async def format_response(self, lora_data: Dict) -> Dict:
         """Format LoRA data for API response"""
@@ -38,7 +38,7 @@ class LoraService(BaseModelService):
             "usage_tips": lora_data.get("usage_tips", ""),
             "notes": lora_data.get("notes", ""),
             "favorite": lora_data.get("favorite", False),
-            "civitai": ModelRouteUtils.filter_civitai_data(lora_data.get("civitai", {}), minimal=True)
+            "civitai": self.filter_civitai_data(lora_data.get("civitai", {}), minimal=True)
         }
     
     async def _apply_specific_filters(self, data: List[Dict], **kwargs) -> List[Dict]:
@@ -179,4 +179,4 @@ class LoraService(BaseModelService):
     
     def find_duplicate_filenames(self) -> Dict:
         """Find LoRAs with conflicting filenames"""
-        return self.scanner._hash_index.get_duplicate_filenames()
+        return self.scanner._hash_index.get_duplicate_filenames()

py/services/metadata_archive_manager.py

@@ -0,0 +1,157 @@
+import zipfile
+import logging
+import asyncio
+from pathlib import Path
+from typing import Optional
+from .downloader import get_downloader, DownloadProgress
+
+logger = logging.getLogger(__name__)
+
+class MetadataArchiveManager:
+    """Manages downloading and extracting Civitai metadata archive database"""
+    
+    DOWNLOAD_URLS = [
+        "https://github.com/willmiao/civitai-metadata-archive-db/releases/download/db-2025-08-08/civitai.zip",
+        "https://huggingface.co/datasets/willmiao/civitai-metadata-archive-db/blob/main/civitai.zip"
+    ]
+    
+    def __init__(self, base_path: str):
+        """Initialize with base path where files will be stored"""
+        self.base_path = Path(base_path)
+        self.civitai_folder = self.base_path / "civitai"
+        self.archive_path = self.base_path / "civitai.zip"
+        self.db_path = self.civitai_folder / "civitai.sqlite"
+        
+    def is_database_available(self) -> bool:
+        """Check if the SQLite database is available and valid"""
+        return self.db_path.exists() and self.db_path.stat().st_size > 0
+        
+    def get_database_path(self) -> Optional[str]:
+        """Get the path to the SQLite database if available"""
+        if self.is_database_available():
+            return str(self.db_path)
+        return None
+        
+    async def download_and_extract_database(self, progress_callback=None) -> bool:
+        """Download and extract the metadata archive database
+        
+        Args:
+            progress_callback: Optional callback function to report progress
+            
+        Returns:
+            bool: True if successful, False otherwise
+        """
+        try:
+            # Create directories if they don't exist
+            self.base_path.mkdir(parents=True, exist_ok=True)
+            self.civitai_folder.mkdir(parents=True, exist_ok=True)
+            
+            # Download the archive
+            if not await self._download_archive(progress_callback):
+                return False
+                
+            # Extract the archive
+            if not await self._extract_archive(progress_callback):
+                return False
+                
+            # Clean up the archive file
+            if self.archive_path.exists():
+                self.archive_path.unlink()
+                
+            logger.info(f"Successfully downloaded and extracted metadata database to {self.db_path}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error downloading and extracting metadata database: {e}", exc_info=True)
+            return False
+            
+    async def _download_archive(self, progress_callback=None) -> bool:
+        """Download the zip archive from one of the available URLs"""
+        downloader = await get_downloader()
+        
+        for url in self.DOWNLOAD_URLS:
+            try:
+                logger.info(f"Attempting to download from {url}")
+                
+                if progress_callback:
+                    progress_callback("download", f"Downloading from {url}")
+                
+                # Custom progress callback to report download progress
+                async def download_progress(progress, snapshot=None):
+                    if progress_callback:
+                        if isinstance(progress, DownloadProgress):
+                            percent = progress.percent_complete
+                        elif isinstance(snapshot, DownloadProgress):
+                            percent = snapshot.percent_complete
+                        else:
+                            percent = float(progress or 0)
+                        progress_callback("download", f"Downloading archive... {percent:.1f}%")
+                
+                success, result = await downloader.download_file(
+                    url=url,
+                    save_path=str(self.archive_path),
+                    progress_callback=download_progress,
+                    use_auth=False,  # Public download, no auth needed
+                    allow_resume=True
+                )
+                
+                if success:
+                    logger.info(f"Successfully downloaded archive from {url}")
+                    return True
+                else:
+                    logger.warning(f"Failed to download from {url}: {result}")
+                    continue
+                            
+            except Exception as e:
+                logger.warning(f"Error downloading from {url}: {e}")
+                continue
+                
+        logger.error("Failed to download archive from any URL")
+        return False
+        
+    async def _extract_archive(self, progress_callback=None) -> bool:
+        """Extract the zip archive to the civitai folder"""
+        try:
+            if progress_callback:
+                progress_callback("extract", "Extracting archive...")
+                
+            # Run extraction in thread pool to avoid blocking
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, self._extract_zip_sync)
+            
+            if progress_callback:
+                progress_callback("extract", "Extraction completed")
+                
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error extracting archive: {e}", exc_info=True)
+            return False
+            
+    def _extract_zip_sync(self):
+        """Synchronous zip extraction (runs in thread pool)"""
+        with zipfile.ZipFile(self.archive_path, 'r') as archive:
+            archive.extractall(path=self.base_path)
+            
+    async def remove_database(self) -> bool:
+        """Remove the metadata database and folder"""
+        try:
+            if self.civitai_folder.exists():
+                # Remove all files in the civitai folder
+                for file_path in self.civitai_folder.iterdir():
+                    if file_path.is_file():
+                        file_path.unlink()
+                        
+                # Remove the folder itself
+                self.civitai_folder.rmdir()
+                
+            # Also remove the archive file if it exists
+            if self.archive_path.exists():
+                self.archive_path.unlink()
+                
+            logger.info("Successfully removed metadata database")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error removing metadata database: {e}", exc_info=True)
+            return False

py/services/metadata_service.py

@@ -0,0 +1,122 @@
+import os
+import logging
+from .model_metadata_provider import (
+    ModelMetadataProvider,
+    ModelMetadataProviderManager, 
+    SQLiteModelMetadataProvider,
+    CivitaiModelMetadataProvider,
+    CivArchiveModelMetadataProvider,
+    FallbackMetadataProvider
+)
+from .settings_manager import get_settings_manager
+from .metadata_archive_manager import MetadataArchiveManager
+from .service_registry import ServiceRegistry
+
+logger = logging.getLogger(__name__)
+
+async def initialize_metadata_providers():
+    """Initialize and configure all metadata providers based on settings"""
+    provider_manager = await ModelMetadataProviderManager.get_instance()
+    
+    # Clear existing providers to allow reinitialization
+    provider_manager.providers.clear()
+    provider_manager.default_provider = None
+    
+    # Get settings
+    settings_manager = get_settings_manager()
+    enable_archive_db = settings_manager.get('enable_metadata_archive_db', False)
+    
+    providers = []
+    
+    # Initialize archive database provider if enabled
+    if enable_archive_db:
+        try:
+            # Initialize archive manager
+            base_path = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+            archive_manager = MetadataArchiveManager(base_path)
+            
+            db_path = archive_manager.get_database_path()
+            if db_path and os.path.exists(db_path):
+                sqlite_provider = SQLiteModelMetadataProvider(db_path)
+                provider_manager.register_provider('sqlite', sqlite_provider)
+                providers.append(('sqlite', sqlite_provider))
+                logger.debug(f"SQLite metadata provider registered with database: {db_path}")
+            else:
+                logger.warning("Metadata archive database is enabled but database file not found")
+        except Exception as e:
+            logger.error(f"Failed to initialize SQLite metadata provider: {e}")
+    
+    # Initialize Civitai API provider (always available as fallback)
+    try:
+        civitai_client = await ServiceRegistry.get_civitai_client()
+        civitai_provider = CivitaiModelMetadataProvider(civitai_client)
+        provider_manager.register_provider('civitai_api', civitai_provider)
+        providers.append(('civitai_api', civitai_provider))
+        logger.debug("Civitai API metadata provider registered")
+    except Exception as e:
+        logger.error(f"Failed to initialize Civitai API metadata provider: {e}")
+
+    # Register CivArchive provider, and all add to fallback providers
+    try:
+        civarchive_client = await ServiceRegistry.get_civarchive_client()
+        civarchive_provider = CivArchiveModelMetadataProvider(civarchive_client)
+        provider_manager.register_provider('civarchive_api', civarchive_provider)
+        providers.append(('civarchive_api', civarchive_provider))
+        logger.debug("CivArchive metadata provider registered (also included in fallback)")
+    except Exception as e:
+        logger.error(f"Failed to initialize CivArchive metadata provider: {e}")
+
+    # Set up fallback provider based on available providers
+    if len(providers) > 1:
+        # Always use Civitai API (it has better metadata), then CivArchive API, then Archive DB
+        ordered_providers: list[tuple[str, ModelMetadataProvider]] = []
+        ordered_providers.extend([p for p in providers if p[0] == 'civitai_api'])
+        ordered_providers.extend([p for p in providers if p[0] == 'civarchive_api'])
+        ordered_providers.extend([p for p in providers if p[0] == 'sqlite'])
+        
+        if ordered_providers:
+            fallback_provider = FallbackMetadataProvider(ordered_providers)
+            provider_manager.register_provider('fallback', fallback_provider, is_default=True)
+    elif len(providers) == 1:
+        # Only one provider available, set it as default
+        provider_name, provider = providers[0]
+        provider_manager.register_provider(provider_name, provider, is_default=True)
+        logger.debug(f"Single metadata provider registered as default: {provider_name}")
+    else:
+        logger.warning("No metadata providers available - this may cause metadata lookup failures")
+    
+    return provider_manager
+
+async def update_metadata_providers():
+    """Update metadata providers based on current settings"""
+    try:
+        # Get current settings
+        settings_manager = get_settings_manager()
+        enable_archive_db = settings_manager.get('enable_metadata_archive_db', False)
+        
+        # Reinitialize all providers with new settings
+        provider_manager = await initialize_metadata_providers()
+        
+        logger.info(f"Updated metadata providers, archive_db enabled: {enable_archive_db}")
+        return provider_manager
+    except Exception as e:
+        logger.error(f"Failed to update metadata providers: {e}")
+        return await ModelMetadataProviderManager.get_instance()
+
+async def get_metadata_archive_manager():
+    """Get metadata archive manager instance"""
+    base_path = os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
+    return MetadataArchiveManager(base_path)
+
+async def get_metadata_provider(provider_name: str = None):
+    """Get a specific metadata provider or default provider"""
+    provider_manager = await ModelMetadataProviderManager.get_instance()
+    
+    if provider_name:
+        return provider_manager._get_provider(provider_name)
+    
+    return provider_manager._get_provider()
+
+async def get_default_metadata_provider():
+    """Get the default metadata provider (fallback or single provider)"""
+    return await get_metadata_provider()

py/services/metadata_sync_service.py

@@ -0,0 +1,448 @@
+"""Services for synchronising metadata with remote providers."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import datetime
+from typing import Any, Awaitable, Callable, Dict, Iterable, Optional
+
+from ..services.settings_manager import SettingsManager
+from ..utils.model_utils import determine_base_model
+from .errors import RateLimitError
+
+logger = logging.getLogger(__name__)
+
+
+class MetadataProviderProtocol:
+    """Subset of metadata provider interface consumed by the sync service."""
+
+    async def get_model_by_hash(self, sha256: str) -> tuple[Optional[Dict[str, Any]], Optional[str]]:
+        ...
+
+    async def get_model_version(
+        self, model_id: int, model_version_id: Optional[int]
+    ) -> Optional[Dict[str, Any]]:
+        ...
+
+
+class MetadataSyncService:
+    """High level orchestration for metadata synchronisation flows."""
+
+    def __init__(
+        self,
+        *,
+        metadata_manager,
+        preview_service,
+        settings: SettingsManager,
+        default_metadata_provider_factory: Callable[[], Awaitable[MetadataProviderProtocol]],
+        metadata_provider_selector: Callable[[str], Awaitable[MetadataProviderProtocol]],
+    ) -> None:
+        self._metadata_manager = metadata_manager
+        self._preview_service = preview_service
+        self._settings = settings
+        self._get_default_provider = default_metadata_provider_factory
+        self._get_provider = metadata_provider_selector
+
+    async def load_local_metadata(self, metadata_path: str) -> Dict[str, Any]:
+        """Load metadata JSON from disk, returning an empty structure when missing."""
+
+        if not os.path.exists(metadata_path):
+            return {}
+
+        try:
+            with open(metadata_path, "r", encoding="utf-8") as handle:
+                return json.load(handle)
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.error("Error loading metadata from %s: %s", metadata_path, exc)
+            return {}
+
+    async def mark_not_found_on_civitai(
+        self, metadata_path: str, local_metadata: Dict[str, Any]
+    ) -> None:
+        """Persist the not-found flag for a metadata payload."""
+
+        local_metadata["from_civitai"] = False
+        await self._metadata_manager.save_metadata(metadata_path, local_metadata)
+
+    @staticmethod
+    def is_civitai_api_metadata(meta: Dict[str, Any]) -> bool:
+        """Determine if the metadata originated from the CivitAI public API."""
+
+        if not isinstance(meta, dict):
+            return False
+        files = meta.get("files")
+        images = meta.get("images")
+        source = meta.get("source")
+        return bool(files) and bool(images) and source != "archive_db"
+
+    async def update_model_metadata(
+        self,
+        metadata_path: str,
+        local_metadata: Dict[str, Any],
+        civitai_metadata: Dict[str, Any],
+        metadata_provider: Optional[MetadataProviderProtocol] = None,
+    ) -> Dict[str, Any]:
+        """Merge remote metadata into the local record and persist the result."""
+
+        existing_civitai = local_metadata.get("civitai") or {}
+
+        if (
+            civitai_metadata.get("source") == "archive_db"
+            and self.is_civitai_api_metadata(existing_civitai)
+        ):
+            logger.info(
+                "Skip civitai update for %s (%s)",
+                local_metadata.get("model_name", ""),
+                existing_civitai.get("name", ""),
+            )
+        else:
+            merged_civitai = existing_civitai.copy()
+            merged_civitai.update(civitai_metadata)
+
+            if civitai_metadata.get("source") == "archive_db":
+                model_name = civitai_metadata.get("model", {}).get("name", "")
+                version_name = civitai_metadata.get("name", "")
+                logger.info(
+                    "Recovered metadata from archive_db for deleted model: %s (%s)",
+                    model_name,
+                    version_name,
+                )
+
+            if "trainedWords" in existing_civitai:
+                existing_trained = existing_civitai.get("trainedWords", [])
+                new_trained = civitai_metadata.get("trainedWords", [])
+                merged_trained = list(set(existing_trained + new_trained))
+                merged_civitai["trainedWords"] = merged_trained
+
+            local_metadata["civitai"] = merged_civitai
+
+        if "model" in civitai_metadata and civitai_metadata["model"]:
+            model_data = civitai_metadata["model"]
+
+            if model_data.get("name"):
+                local_metadata["model_name"] = model_data["name"]
+
+            if not local_metadata.get("modelDescription") and model_data.get("description"):
+                local_metadata["modelDescription"] = model_data["description"]
+
+            if not local_metadata.get("tags") and model_data.get("tags"):
+                local_metadata["tags"] = model_data["tags"]
+
+            if model_data.get("creator") and not local_metadata.get("civitai", {}).get(
+                "creator"
+            ):
+                local_metadata.setdefault("civitai", {})["creator"] = model_data["creator"]
+
+        local_metadata["base_model"] = determine_base_model(
+            civitai_metadata.get("baseModel")
+        )
+
+        await self._preview_service.ensure_preview_for_metadata(
+            metadata_path, local_metadata, civitai_metadata.get("images", [])
+        )
+
+        await self._metadata_manager.save_metadata(metadata_path, local_metadata)
+        return local_metadata
+
+    async def fetch_and_update_model(
+        self,
+        *,
+        sha256: str,
+        file_path: str,
+        model_data: Dict[str, Any],
+        update_cache_func: Callable[[str, str, Dict[str, Any]], Awaitable[bool]],
+    ) -> tuple[bool, Optional[str]]:
+        """Fetch metadata for a model and update both disk and cache state.
+
+        Callers should hydrate ``model_data`` via ``MetadataManager.hydrate_model_data``
+        before invoking this method so that the persisted payload retains all known
+        metadata fields.
+        """
+
+        if not isinstance(model_data, dict):
+            error = f"Invalid model_data type: {type(model_data)}"
+            logger.error(error)
+            return False, error
+
+        metadata_path = os.path.splitext(file_path)[0] + ".metadata.json"
+        enable_archive = self._settings.get("enable_metadata_archive_db", False)
+        previous_source = model_data.get("metadata_source") or (model_data.get("civitai") or {}).get("source")
+
+        try:
+            provider_attempts: list[tuple[Optional[str], MetadataProviderProtocol]] = []
+            sqlite_attempted = False
+
+            if model_data.get("civitai_deleted") is True:
+                if previous_source in (None, "civarchive"):
+                    try:
+                        provider_attempts.append(("civarchive_api", await self._get_provider("civarchive_api")))
+                    except Exception as exc:  # pragma: no cover - provider resolution fault
+                        logger.debug("Unable to resolve civarchive provider: %s", exc)
+
+                if enable_archive and model_data.get("db_checked") is not True:
+                    try:
+                        provider_attempts.append(("sqlite", await self._get_provider("sqlite")))
+                    except Exception as exc:  # pragma: no cover - provider resolution fault
+                        logger.debug("Unable to resolve sqlite provider: %s", exc)
+
+                if not provider_attempts:
+                    if not enable_archive:
+                        error_msg = "CivitAI model is deleted and metadata archive DB is not enabled"
+                    elif model_data.get("db_checked") is True:
+                        error_msg = "CivitAI model is deleted and not found in metadata archive DB"
+                    else:
+                        error_msg = "CivitAI model is deleted and no archive provider is available"
+                    return False, error_msg
+            else:
+                provider_attempts.append((None, await self._get_default_provider()))
+
+            civitai_metadata: Optional[Dict[str, Any]] = None
+            metadata_provider: Optional[MetadataProviderProtocol] = None
+            provider_used: Optional[str] = None
+            last_error: Optional[str] = None
+
+            for provider_name, provider in provider_attempts:
+                try:
+                    civitai_metadata_candidate, error = await provider.get_model_by_hash(sha256)
+                except RateLimitError as exc:
+                    exc.provider = exc.provider or (provider_name or provider.__class__.__name__)
+                    raise
+                except Exception as exc:  # pragma: no cover - defensive logging
+                    logger.error("Provider %s failed for hash %s: %s", provider_name, sha256, exc)
+                    civitai_metadata_candidate, error = None, str(exc)
+
+                if provider_name == "sqlite":
+                    sqlite_attempted = True
+
+                if civitai_metadata_candidate:
+                    civitai_metadata = civitai_metadata_candidate
+                    metadata_provider = provider
+                    provider_used = provider_name
+                    break
+
+                last_error = error or last_error
+
+            if civitai_metadata is None or metadata_provider is None:
+                if sqlite_attempted:
+                    model_data["db_checked"] = True
+
+                if last_error == "Model not found":
+                    model_data["from_civitai"] = False
+                    model_data["civitai_deleted"] = True
+                    model_data["db_checked"] = sqlite_attempted or (enable_archive and model_data.get("db_checked", False))
+                    model_data["last_checked_at"] = datetime.now().timestamp()
+
+                    data_to_save = model_data.copy()
+                    data_to_save.pop("folder", None)
+                    await self._metadata_manager.save_metadata(file_path, data_to_save)
+
+                default_error = (
+                    "CivitAI model is deleted and metadata archive DB is not enabled"
+                    if model_data.get("civitai_deleted") and not enable_archive
+                    else "CivitAI model is deleted and not found in metadata archive DB"
+                    if model_data.get("civitai_deleted") and (model_data.get("db_checked") is True or sqlite_attempted)
+                    else "No provider returned metadata"
+                )
+
+                error_msg = (
+                    f"Error fetching metadata: {last_error or default_error} "
+                    f"(model_name={model_data.get('model_name', '')})"
+                )
+                logger.error(error_msg)
+                return False, error_msg
+
+            model_data["from_civitai"] = True
+            model_data["civitai_deleted"] = civitai_metadata.get("source") == "archive_db" or civitai_metadata.get("source") == "civarchive"
+            model_data["db_checked"] = enable_archive and (
+                civitai_metadata.get("source") == "archive_db" or sqlite_attempted
+            )
+            source = civitai_metadata.get("source") or "civitai_api"
+            if source == "api":
+                source = "civitai_api"
+            elif provider_used == "civarchive_api" and source != "civarchive":
+                source = "civarchive"
+            elif provider_used == "sqlite":
+                source = "archive_db"
+            model_data["metadata_source"] = source
+            model_data["last_checked_at"] = datetime.now().timestamp()
+
+            readable_source = {
+                "civitai_api": "CivitAI API",
+                "civarchive": "CivArchive API",
+                "archive_db": "Archive Database",
+            }.get(source, source)
+
+            logger.info(
+                "Fetched metadata for %s via %s",
+                model_data.get("model_name", ""),
+                readable_source,
+            )
+
+            local_metadata = model_data.copy()
+            local_metadata.pop("folder", None)
+
+            await self.update_model_metadata(
+                metadata_path,
+                local_metadata,
+                civitai_metadata,
+                metadata_provider,
+            )
+
+            update_payload = {
+                "model_name": local_metadata.get("model_name"),
+                "preview_url": local_metadata.get("preview_url"),
+                "civitai": local_metadata.get("civitai"),
+            }
+            model_data.update(update_payload)
+
+            await update_cache_func(file_path, file_path, local_metadata)
+            return True, None
+        except KeyError as exc:
+            error_msg = f"Error fetching metadata - Missing key: {exc} in model_data={model_data}"
+            logger.error(error_msg)
+            return False, error_msg
+        except RateLimitError as exc:
+            provider_label = exc.provider or "metadata provider"
+            wait_hint = (
+                f"; retry after approximately {int(exc.retry_after)}s"
+                if exc.retry_after and exc.retry_after > 0
+                else ""
+            )
+            error_msg = f"Rate limited by {provider_label}{wait_hint}"
+            logger.warning(error_msg)
+            return False, error_msg
+        except Exception as exc:  # pragma: no cover - error path
+            error_msg = f"Error fetching metadata: {exc}"
+            logger.error(error_msg, exc_info=True)
+            return False, error_msg
+
+    async def fetch_metadata_by_sha(
+        self, sha256: str, metadata_provider: Optional[MetadataProviderProtocol] = None
+    ) -> tuple[Optional[Dict[str, Any]], Optional[str]]:
+        """Fetch metadata for a SHA256 hash from the configured provider."""
+
+        provider = metadata_provider or await self._get_default_provider()
+        return await provider.get_model_by_hash(sha256)
+
+    async def relink_metadata(
+        self,
+        *,
+        file_path: str,
+        metadata: Dict[str, Any],
+        model_id: int,
+        model_version_id: Optional[int],
+    ) -> Dict[str, Any]:
+        """Relink a local metadata record to a specific CivitAI model version."""
+
+        provider = await self._get_default_provider()
+        civitai_metadata = await provider.get_model_version(model_id, model_version_id)
+        if not civitai_metadata:
+            raise ValueError(
+                f"Model version not found on CivitAI for ID: {model_id}"
+                + (f" with version: {model_version_id}" if model_version_id else "")
+            )
+
+        primary_model_file: Optional[Dict[str, Any]] = None
+        for file_info in civitai_metadata.get("files", []):
+            if file_info.get("primary", False) and file_info.get("type") == "Model":
+                primary_model_file = file_info
+                break
+
+        if primary_model_file and primary_model_file.get("hashes", {}).get("SHA256"):
+            metadata["sha256"] = primary_model_file["hashes"]["SHA256"].lower()
+
+        metadata_path = os.path.splitext(file_path)[0] + ".metadata.json"
+        await self.update_model_metadata(
+            metadata_path,
+            metadata,
+            civitai_metadata,
+            provider,
+        )
+
+        return metadata
+
+    async def save_metadata_updates(
+        self,
+        *,
+        file_path: str,
+        updates: Dict[str, Any],
+        metadata_loader: Callable[[str], Awaitable[Dict[str, Any]]],
+        update_cache: Callable[[str, str, Dict[str, Any]], Awaitable[bool]],
+    ) -> Dict[str, Any]:
+        """Apply metadata updates and persist to disk and cache."""
+
+        metadata_path = os.path.splitext(file_path)[0] + ".metadata.json"
+        metadata = await metadata_loader(metadata_path)
+
+        for key, value in updates.items():
+            if isinstance(value, dict) and isinstance(metadata.get(key), dict):
+                metadata[key].update(value)
+            else:
+                metadata[key] = value
+
+        await self._metadata_manager.save_metadata(file_path, metadata)
+        await update_cache(file_path, file_path, metadata)
+
+        if "model_name" in updates:
+            logger.debug("Metadata update touched model_name; cache resort required")
+
+        return metadata
+
+    async def verify_duplicate_hashes(
+        self,
+        *,
+        file_paths: Iterable[str],
+        metadata_loader: Callable[[str], Awaitable[Dict[str, Any]]],
+        hash_calculator: Callable[[str], Awaitable[str]],
+        update_cache: Callable[[str, str, Dict[str, Any]], Awaitable[bool]],
+    ) -> Dict[str, Any]:
+        """Verify a collection of files share the same SHA256 hash."""
+
+        file_paths = list(file_paths)
+        if not file_paths:
+            raise ValueError("No file paths provided for verification")
+
+        results = {
+            "verified_as_duplicates": True,
+            "mismatched_files": [],
+            "new_hash_map": {},
+        }
+
+        expected_hash: Optional[str] = None
+        first_metadata_path = os.path.splitext(file_paths[0])[0] + ".metadata.json"
+        first_metadata = await metadata_loader(first_metadata_path)
+        if first_metadata and "sha256" in first_metadata:
+            expected_hash = first_metadata["sha256"].lower()
+
+        for path in file_paths:
+            if not os.path.exists(path):
+                continue
+
+            try:
+                actual_hash = await hash_calculator(path)
+                metadata_path = os.path.splitext(path)[0] + ".metadata.json"
+                metadata = await metadata_loader(metadata_path)
+                stored_hash = metadata.get("sha256", "").lower()
+
+                if not expected_hash:
+                    expected_hash = stored_hash
+
+                if actual_hash != expected_hash:
+                    results["verified_as_duplicates"] = False
+                    results["mismatched_files"].append(path)
+                    results["new_hash_map"][path] = actual_hash
+
+                if actual_hash != stored_hash:
+                    metadata["sha256"] = actual_hash
+                    await self._metadata_manager.save_metadata(path, metadata)
+                    await update_cache(path, path, metadata)
+            except Exception as exc:  # pragma: no cover - defensive path
+                logger.error("Error verifying hash for %s: %s", path, exc)
+                results["mismatched_files"].append(path)
+                results["new_hash_map"][path] = "error_calculating_hash"
+                results["verified_as_duplicates"] = False
+
+        return results
+

py/services/model_cache.py

@@ -1,6 +1,6 @@
 import asyncio
-from typing import List, Dict, Tuple
-from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Tuple
+from dataclasses import dataclass, field
 from operator import itemgetter
 from natsort import natsorted
 
@@ -17,10 +17,12 @@ SUPPORTED_SORT_MODES = [
 
 @dataclass
 class ModelCache:
-    """Cache structure for model data with extensible sorting"""
+    """Cache structure for model data with extensible sorting."""
+
     raw_data: List[Dict]
     folders: List[str]
-    
+    version_index: Dict[int, Dict] = field(default_factory=dict)
+
     def __post_init__(self):
         self._lock = asyncio.Lock()
         # Cache for last sort: (sort_key, order) -> sorted list
@@ -28,6 +30,58 @@ class ModelCache:
         self._last_sorted_data: List[Dict] = []
         # Default sort on init
         asyncio.create_task(self.resort())
+        self.rebuild_version_index()
+
+    @staticmethod
+    def _normalize_version_id(value: Any) -> Optional[int]:
+        """Normalize a potential version identifier into an integer."""
+
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str):
+            try:
+                return int(value)
+            except ValueError:
+                return None
+        return None
+
+    def rebuild_version_index(self) -> None:
+        """Rebuild the version index from the current raw data."""
+
+        self.version_index = {}
+        for item in self.raw_data:
+            self.add_to_version_index(item)
+
+    def add_to_version_index(self, item: Dict) -> None:
+        """Register a cache item in the version index if possible."""
+
+        civitai_data = item.get('civitai') if isinstance(item, dict) else None
+        if not isinstance(civitai_data, dict):
+            return
+
+        version_id = self._normalize_version_id(civitai_data.get('id'))
+        if version_id is None:
+            return
+
+        self.version_index[version_id] = item
+
+    def remove_from_version_index(self, item: Dict) -> None:
+        """Remove a cache item from the version index if present."""
+
+        civitai_data = item.get('civitai') if isinstance(item, dict) else None
+        if not isinstance(civitai_data, dict):
+            return
+
+        version_id = self._normalize_version_id(civitai_data.get('id'))
+        if version_id is None:
+            return
+
+        existing = self.version_index.get(version_id)
+        if existing is item or (
+            isinstance(existing, dict)
+            and existing.get('file_path') == item.get('file_path')
+        ):
+            self.version_index.pop(version_id, None)
 
     async def resort(self):
         """Resort cached data according to last sort mode if set"""
@@ -41,6 +95,7 @@ class ModelCache:
 
             all_folders = set(l['folder'] for l in self.raw_data)
             self.folders = sorted(list(all_folders), key=lambda x: x.lower())
+            self.rebuild_version_index()
 
     def _sort_data(self, data: List[Dict], sort_key: str, order: str) -> List[Dict]:
         """Sort data by sort_key and order"""

py/services/model_file_service.py

@@ -0,0 +1,464 @@
+import asyncio
+import os
+import logging
+from typing import List, Dict, Optional, Any, Set
+from abc import ABC, abstractmethod
+
+from ..utils.utils import calculate_relative_path_for_model, remove_empty_dirs
+from ..utils.constants import AUTO_ORGANIZE_BATCH_SIZE
+from ..services.settings_manager import get_settings_manager
+
+logger = logging.getLogger(__name__)
+
+
+class ProgressCallback(ABC):
+    """Abstract callback interface for progress reporting"""
+    
+    @abstractmethod
+    async def on_progress(self, progress_data: Dict[str, Any]) -> None:
+        """Called when progress is updated"""
+        pass
+
+
+class AutoOrganizeResult:
+    """Result object for auto-organize operations"""
+    
+    def __init__(self):
+        self.total: int = 0
+        self.processed: int = 0
+        self.success_count: int = 0
+        self.failure_count: int = 0
+        self.skipped_count: int = 0
+        self.operation_type: str = 'unknown'
+        self.cleanup_counts: Dict[str, int] = {}
+        self.results: List[Dict[str, Any]] = []
+        self.results_truncated: bool = False
+        self.sample_results: List[Dict[str, Any]] = []
+        self.is_flat_structure: bool = False
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary"""
+        result = {
+            'success': True,
+            'message': f'Auto-organize {self.operation_type} completed: {self.success_count} moved, {self.skipped_count} skipped, {self.failure_count} failed out of {self.total} total',
+            'summary': {
+                'total': self.total,
+                'success': self.success_count,
+                'skipped': self.skipped_count,
+                'failures': self.failure_count,
+                'organization_type': 'flat' if self.is_flat_structure else 'structured',
+                'cleaned_dirs': self.cleanup_counts,
+                'operation_type': self.operation_type
+            }
+        }
+        
+        if self.results_truncated:
+            result['results_truncated'] = True
+            result['sample_results'] = self.sample_results
+        else:
+            result['results'] = self.results
+        
+        return result
+
+
+class ModelFileService:
+    """Service for handling model file operations and organization"""
+    
+    def __init__(self, scanner, model_type: str):
+        """Initialize the service
+        
+        Args:
+            scanner: Model scanner instance
+            model_type: Type of model (e.g., 'lora', 'checkpoint')
+        """
+        self.scanner = scanner
+        self.model_type = model_type
+    
+    def get_model_roots(self) -> List[str]:
+        """Get model root directories"""
+        return self.scanner.get_model_roots()
+    
+    async def auto_organize_models(
+        self, 
+        file_paths: Optional[List[str]] = None,
+        progress_callback: Optional[ProgressCallback] = None
+    ) -> AutoOrganizeResult:
+        """Auto-organize models based on current settings
+        
+        Args:
+            file_paths: Optional list of specific file paths to organize. 
+                       If None, organizes all models.
+            progress_callback: Optional callback for progress updates
+            
+        Returns:
+            AutoOrganizeResult object with operation results
+        """
+        result = AutoOrganizeResult()
+        source_directories: Set[str] = set()
+        
+        try:
+            # Get all models from cache
+            cache = await self.scanner.get_cached_data()
+            all_models = cache.raw_data
+            
+            # Filter models if specific file paths are provided
+            if file_paths:
+                all_models = [model for model in all_models if model.get('file_path') in file_paths]
+                result.operation_type = 'bulk'
+            else:
+                result.operation_type = 'all'
+            
+            # Get model roots for this scanner
+            model_roots = self.get_model_roots()
+            if not model_roots:
+                raise ValueError('No model roots configured')
+            
+            # Check if flat structure is configured for this model type
+            settings_manager = get_settings_manager()
+            path_template = settings_manager.get_download_path_template(self.model_type)
+            result.is_flat_structure = not path_template
+            
+            # Initialize tracking
+            result.total = len(all_models)
+            
+            # Send initial progress
+            if progress_callback:
+                await progress_callback.on_progress({
+                    'type': 'auto_organize_progress',
+                    'status': 'started',
+                    'total': result.total,
+                    'processed': 0,
+                    'success': 0,
+                    'failures': 0,
+                    'skipped': 0,
+                    'operation_type': result.operation_type
+                })
+            
+            # Process models in batches
+            await self._process_models_in_batches(
+                all_models, 
+                model_roots, 
+                result, 
+                progress_callback,
+                source_directories  # Pass the set to track source directories
+            )
+            
+            # Send cleanup progress
+            if progress_callback:
+                await progress_callback.on_progress({
+                    'type': 'auto_organize_progress',
+                    'status': 'cleaning',
+                    'total': result.total,
+                    'processed': result.processed,
+                    'success': result.success_count,
+                    'failures': result.failure_count,
+                    'skipped': result.skipped_count,
+                    'message': 'Cleaning up empty directories...',
+                    'operation_type': result.operation_type
+                })
+            
+            # Clean up empty directories - only in affected directories for bulk operations
+            cleanup_paths = list(source_directories) if result.operation_type == 'bulk' else model_roots
+            result.cleanup_counts = await self._cleanup_empty_directories(cleanup_paths)
+            
+            # Send completion message
+            if progress_callback:
+                await progress_callback.on_progress({
+                    'type': 'auto_organize_progress',
+                    'status': 'completed',
+                    'total': result.total,
+                    'processed': result.processed,
+                    'success': result.success_count,
+                    'failures': result.failure_count,
+                    'skipped': result.skipped_count,
+                    'cleanup': result.cleanup_counts,
+                    'operation_type': result.operation_type
+                })
+            
+            return result
+            
+        except Exception as e:
+            logger.error(f"Error in auto_organize_models: {e}", exc_info=True)
+            
+            # Send error message
+            if progress_callback:
+                await progress_callback.on_progress({
+                    'type': 'auto_organize_progress',
+                    'status': 'error',
+                    'error': str(e),
+                    'operation_type': result.operation_type
+                })
+            
+            raise e
+    
+    async def _process_models_in_batches(
+        self, 
+        all_models: List[Dict[str, Any]], 
+        model_roots: List[str], 
+        result: AutoOrganizeResult,
+        progress_callback: Optional[ProgressCallback],
+        source_directories: Optional[Set[str]] = None
+    ) -> None:
+        """Process models in batches to avoid overwhelming the system"""
+        
+        for i in range(0, result.total, AUTO_ORGANIZE_BATCH_SIZE):
+            batch = all_models[i:i + AUTO_ORGANIZE_BATCH_SIZE]
+            
+            for model in batch:
+                await self._process_single_model(model, model_roots, result, source_directories)
+                result.processed += 1
+            
+            # Send progress update after each batch
+            if progress_callback:
+                await progress_callback.on_progress({
+                    'type': 'auto_organize_progress',
+                    'status': 'processing',
+                    'total': result.total,
+                    'processed': result.processed,
+                    'success': result.success_count,
+                    'failures': result.failure_count,
+                    'skipped': result.skipped_count,
+                    'operation_type': result.operation_type
+                })
+            
+            # Small delay between batches
+            await asyncio.sleep(0.1)
+    
+    async def _process_single_model(
+        self, 
+        model: Dict[str, Any], 
+        model_roots: List[str], 
+        result: AutoOrganizeResult,
+        source_directories: Optional[Set[str]] = None
+    ) -> None:
+        """Process a single model for organization"""
+        try:
+            file_path = model.get('file_path')
+            model_name = model.get('model_name', 'Unknown')
+            
+            if not file_path:
+                self._add_result(result, model_name, False, "No file path found")
+                result.failure_count += 1
+                return
+            
+            # Find which model root this file belongs to
+            current_root = self._find_model_root(file_path, model_roots)
+            if not current_root:
+                self._add_result(result, model_name, False, 
+                               "Model file not found in any configured root directory")
+                result.failure_count += 1
+                return
+            
+            # Determine target directory
+            target_dir = await self._calculate_target_directory(
+                model, current_root, result.is_flat_structure
+            )
+            
+            if target_dir is None:
+                self._add_result(result, model_name, False, 
+                               "Skipped - insufficient metadata for organization")
+                result.skipped_count += 1
+                return
+            
+            current_dir = os.path.dirname(file_path)
+            
+            # Skip if already in correct location
+            if current_dir.replace(os.sep, '/') == target_dir.replace(os.sep, '/'):
+                result.skipped_count += 1
+                return
+            
+            # Check for conflicts
+            file_name = os.path.basename(file_path)
+            target_file_path = os.path.join(target_dir, file_name)
+            
+            if os.path.exists(target_file_path):
+                self._add_result(result, model_name, False, 
+                               f"Target file already exists: {target_file_path}")
+                result.failure_count += 1
+                return
+            
+            # Store the source directory for potential cleanup
+            if source_directories is not None:
+                source_directories.add(current_dir)
+            
+            # Perform the move
+            success = await self.scanner.move_model(file_path, target_dir)
+            
+            if success:
+                result.success_count += 1
+            else:
+                self._add_result(result, model_name, False, "Failed to move model")
+                result.failure_count += 1
+            
+        except Exception as e:
+            logger.error(f"Error processing model {model.get('model_name', 'Unknown')}: {e}", exc_info=True)
+            self._add_result(result, model.get('model_name', 'Unknown'), False, f"Error: {str(e)}")
+            result.failure_count += 1
+    
+    def _find_model_root(self, file_path: str, model_roots: List[str]) -> Optional[str]:
+        """Find which model root the file belongs to"""
+        for root in model_roots:
+            # Normalize paths for comparison
+            normalized_root = os.path.normpath(root).replace(os.sep, '/')
+            normalized_file = os.path.normpath(file_path).replace(os.sep, '/')
+            
+            if normalized_file.startswith(normalized_root):
+                return root
+        return None
+    
+    async def _calculate_target_directory(
+        self, 
+        model: Dict[str, Any], 
+        current_root: str, 
+        is_flat_structure: bool
+    ) -> Optional[str]:
+        """Calculate the target directory for a model"""
+        if is_flat_structure:
+            file_path = model.get('file_path')
+            current_dir = os.path.dirname(file_path)
+            
+            # Check if already in root directory
+            if os.path.normpath(current_dir) == os.path.normpath(current_root):
+                return None  # Signal to skip
+            
+            return current_root
+        else:
+            # Calculate new relative path based on settings
+            new_relative_path = calculate_relative_path_for_model(model, self.model_type)
+            
+            if not new_relative_path:
+                return None  # Signal to skip
+            
+            return os.path.join(current_root, new_relative_path).replace(os.sep, '/')
+    
+    def _add_result(
+        self, 
+        result: AutoOrganizeResult, 
+        model_name: str, 
+        success: bool, 
+        message: str
+    ) -> None:
+        """Add a result entry if under the limit"""
+        if len(result.results) < 100:  # Limit detailed results
+            result.results.append({
+                "model": model_name,
+                "success": success,
+                "message": message
+            })
+        elif len(result.results) == 100:
+            # Mark as truncated and save sample
+            result.results_truncated = True
+            result.sample_results = result.results[:50]
+    
+    async def _cleanup_empty_directories(self, paths: List[str]) -> Dict[str, int]:
+        """Clean up empty directories after organizing
+        
+        Args:
+            paths: List of paths to check for empty directories
+            
+        Returns:
+            Dictionary with counts of removed directories by root path
+        """
+        cleanup_counts = {}
+        for path in paths:
+            removed = remove_empty_dirs(path)
+            cleanup_counts[path] = removed
+        return cleanup_counts
+
+
+class ModelMoveService:
+    """Service for handling individual model moves"""
+    
+    def __init__(self, scanner):
+        """Initialize the service
+        
+        Args:
+            scanner: Model scanner instance
+        """
+        self.scanner = scanner
+    
+    async def move_model(self, file_path: str, target_path: str) -> Dict[str, Any]:
+        """Move a single model file
+        
+        Args:
+            file_path: Source file path
+            target_path: Target directory path
+            
+        Returns:
+            Dictionary with move result
+        """
+        try:
+            source_dir = os.path.dirname(file_path)
+            if os.path.normpath(source_dir) == os.path.normpath(target_path):
+                logger.info(f"Source and target directories are the same: {source_dir}")
+                return {
+                    'success': True, 
+                    'message': 'Source and target directories are the same',
+                    'original_file_path': file_path,
+                    'new_file_path': file_path
+                }
+
+            new_file_path = await self.scanner.move_model(file_path, target_path)
+            if new_file_path:
+                return {
+                    'success': True, 
+                    'original_file_path': file_path,
+                    'new_file_path': new_file_path
+                }
+            else:
+                return {
+                    'success': False,
+                    'error': 'Failed to move model',
+                    'original_file_path': file_path,
+                    'new_file_path': None
+                }
+        except Exception as e:
+            logger.error(f"Error moving model: {e}", exc_info=True)
+            return {
+                'success': False,
+                'error': str(e),
+                'original_file_path': file_path,
+                'new_file_path': None
+            }
+    
+    async def move_models_bulk(self, file_paths: List[str], target_path: str) -> Dict[str, Any]:
+        """Move multiple model files
+        
+        Args:
+            file_paths: List of source file paths
+            target_path: Target directory path
+            
+        Returns:
+            Dictionary with bulk move results
+        """
+        try:
+            results = []
+            
+            for file_path in file_paths:
+                result = await self.move_model(file_path, target_path)
+                results.append({
+                    "original_file_path": file_path,
+                    "new_file_path": result.get('new_file_path'),
+                    "success": result['success'],
+                    "message": result.get('message', result.get('error', 'Unknown'))
+                })
+            
+            success_count = sum(1 for r in results if r["success"])
+            failure_count = len(results) - success_count
+            
+            return {
+                'success': True,
+                'message': f'Moved {success_count} of {len(file_paths)} models',
+                'results': results,
+                'success_count': success_count,
+                'failure_count': failure_count
+            }
+        except Exception as e:
+            logger.error(f"Error moving models in bulk: {e}", exc_info=True)
+            return {
+                'success': False,
+                'error': str(e),
+                'results': [],
+                'success_count': 0,
+                'failure_count': len(file_paths)
+            }

py/services/model_lifecycle_service.py

@@ -0,0 +1,245 @@
+"""Service routines for model lifecycle mutations."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Awaitable, Callable, Dict, Iterable, List, Optional
+
+from ..services.service_registry import ServiceRegistry
+from ..utils.constants import PREVIEW_EXTENSIONS
+
+logger = logging.getLogger(__name__)
+
+
+async def delete_model_artifacts(target_dir: str, file_name: str) -> List[str]:
+    """Delete the primary model artefacts within ``target_dir``."""
+
+    patterns = [
+        f"{file_name}.safetensors",
+        f"{file_name}.metadata.json",
+    ]
+    for ext in PREVIEW_EXTENSIONS:
+        patterns.append(f"{file_name}{ext}")
+
+    deleted: List[str] = []
+    main_file = patterns[0]
+    main_path = os.path.join(target_dir, main_file).replace(os.sep, "/")
+
+    if os.path.exists(main_path):
+        os.remove(main_path)
+        deleted.append(main_path)
+    else:
+        logger.warning("Model file not found: %s", main_file)
+
+    for pattern in patterns[1:]:
+        path = os.path.join(target_dir, pattern)
+        if os.path.exists(path):
+            try:
+                os.remove(path)
+                deleted.append(pattern)
+            except Exception as exc:  # pragma: no cover - defensive path
+                logger.warning("Failed to delete %s: %s", pattern, exc)
+
+    return deleted
+
+
+class ModelLifecycleService:
+    """Co-ordinate destructive and mutating model operations."""
+
+    def __init__(
+        self,
+        *,
+        scanner,
+        metadata_manager,
+        metadata_loader: Callable[[str], Awaitable[Dict[str, object]]],
+        recipe_scanner_factory: Callable[[], Awaitable] | None = None,
+    ) -> None:
+        self._scanner = scanner
+        self._metadata_manager = metadata_manager
+        self._metadata_loader = metadata_loader
+        self._recipe_scanner_factory = (
+            recipe_scanner_factory or ServiceRegistry.get_recipe_scanner
+        )
+
+    async def delete_model(self, file_path: str) -> Dict[str, object]:
+        """Delete a model file and associated artefacts."""
+
+        if not file_path:
+            raise ValueError("Model path is required")
+
+        target_dir = os.path.dirname(file_path)
+        file_name = os.path.splitext(os.path.basename(file_path))[0]
+
+        deleted_files = await delete_model_artifacts(target_dir, file_name)
+
+        cache = await self._scanner.get_cached_data()
+        cache.raw_data = [item for item in cache.raw_data if item["file_path"] != file_path]
+        await cache.resort()
+
+        if hasattr(self._scanner, "_hash_index") and self._scanner._hash_index:
+            self._scanner._hash_index.remove_by_path(file_path)
+
+        return {"success": True, "deleted_files": deleted_files}
+
+    async def exclude_model(self, file_path: str) -> Dict[str, object]:
+        """Mark a model as excluded and prune cache references."""
+
+        if not file_path:
+            raise ValueError("Model path is required")
+
+        metadata_path = os.path.splitext(file_path)[0] + ".metadata.json"
+        metadata = await self._metadata_loader(metadata_path)
+        metadata["exclude"] = True
+
+        await self._metadata_manager.save_metadata(file_path, metadata)
+
+        cache = await self._scanner.get_cached_data()
+        model_to_remove = next(
+            (item for item in cache.raw_data if item["file_path"] == file_path),
+            None,
+        )
+
+        if model_to_remove:
+            for tag in model_to_remove.get("tags", []):
+                if tag in getattr(self._scanner, "_tags_count", {}):
+                    self._scanner._tags_count[tag] = max(
+                        0, self._scanner._tags_count[tag] - 1
+                    )
+                    if self._scanner._tags_count[tag] == 0:
+                        del self._scanner._tags_count[tag]
+
+            if hasattr(self._scanner, "_hash_index") and self._scanner._hash_index:
+                self._scanner._hash_index.remove_by_path(file_path)
+
+            cache.raw_data = [
+                item for item in cache.raw_data if item["file_path"] != file_path
+            ]
+            await cache.resort()
+
+        excluded = getattr(self._scanner, "_excluded_models", None)
+        if isinstance(excluded, list):
+            excluded.append(file_path)
+
+        message = f"Model {os.path.basename(file_path)} excluded"
+        return {"success": True, "message": message}
+
+    async def bulk_delete_models(self, file_paths: Iterable[str]) -> Dict[str, object]:
+        """Delete a collection of models via the scanner bulk operation."""
+
+        file_paths = list(file_paths)
+        if not file_paths:
+            raise ValueError("No file paths provided for deletion")
+
+        return await self._scanner.bulk_delete_models(file_paths)
+
+    async def rename_model(
+        self, *, file_path: str, new_file_name: str
+    ) -> Dict[str, object]:
+        """Rename a model and its companion artefacts."""
+
+        if not file_path or not new_file_name:
+            raise ValueError("File path and new file name are required")
+
+        invalid_chars = {"/", "\\", ":", "*", "?", '"', "<", ">", "|"}
+        if any(char in new_file_name for char in invalid_chars):
+            raise ValueError("Invalid characters in file name")
+
+        target_dir = os.path.dirname(file_path)
+        old_file_name = os.path.splitext(os.path.basename(file_path))[0]
+        new_file_path = os.path.join(target_dir, f"{new_file_name}.safetensors").replace(
+            os.sep, "/"
+        )
+
+        if os.path.exists(new_file_path):
+            raise ValueError("A file with this name already exists")
+
+        patterns = [
+            f"{old_file_name}.safetensors",
+            f"{old_file_name}.metadata.json",
+            f"{old_file_name}.metadata.json.bak",
+        ]
+        for ext in PREVIEW_EXTENSIONS:
+            patterns.append(f"{old_file_name}{ext}")
+
+        existing_files: List[tuple[str, str]] = []
+        for pattern in patterns:
+            path = os.path.join(target_dir, pattern)
+            if os.path.exists(path):
+                existing_files.append((path, pattern))
+
+        metadata_path = os.path.join(target_dir, f"{old_file_name}.metadata.json")
+        metadata: Optional[Dict[str, object]] = None
+        hash_value: Optional[str] = None
+
+        if os.path.exists(metadata_path):
+            metadata = await self._metadata_loader(metadata_path)
+            hash_value = metadata.get("sha256") if isinstance(metadata, dict) else None
+
+        renamed_files: List[str] = []
+        new_metadata_path: Optional[str] = None
+        new_preview: Optional[str] = None
+
+        for old_path, pattern in existing_files:
+            ext = self._get_multipart_ext(pattern)
+            new_path = os.path.join(target_dir, f"{new_file_name}{ext}").replace(
+                os.sep, "/"
+            )
+            os.rename(old_path, new_path)
+            renamed_files.append(new_path)
+
+            if ext == ".metadata.json":
+                new_metadata_path = new_path
+
+        if metadata and new_metadata_path:
+            metadata["file_name"] = new_file_name
+            metadata["file_path"] = new_file_path
+
+            if metadata.get("preview_url"):
+                old_preview = str(metadata["preview_url"])
+                ext = self._get_multipart_ext(old_preview)
+                new_preview = os.path.join(target_dir, f"{new_file_name}{ext}").replace(
+                    os.sep, "/"
+                )
+                metadata["preview_url"] = new_preview
+
+            await self._metadata_manager.save_metadata(new_file_path, metadata)
+
+        if metadata:
+            await self._scanner.update_single_model_cache(
+                file_path, new_file_path, metadata
+            )
+
+            if hash_value and getattr(self._scanner, "model_type", "") == "lora":
+                recipe_scanner = await self._recipe_scanner_factory()
+                if recipe_scanner:
+                    try:
+                        await recipe_scanner.update_lora_filename_by_hash(
+                            hash_value, new_file_name
+                        )
+                    except Exception as exc:  # pragma: no cover - defensive logging
+                        logger.error(
+                            "Error updating recipe references for %s: %s",
+                            file_path,
+                            exc,
+                        )
+
+        return {
+            "success": True,
+            "new_file_path": new_file_path,
+            "new_preview_path": new_preview,
+            "renamed_files": renamed_files,
+            "reload_required": False,
+        }
+
+    @staticmethod
+    def _get_multipart_ext(filename: str) -> str:
+        """Return the extension for files with compound suffixes."""
+
+        parts = filename.split(".")
+        if len(parts) == 3:
+            return "." + ".".join(parts[-2:])
+        if len(parts) >= 4:
+            return "." + ".".join(parts[-3:])
+        return os.path.splitext(filename)[1]
+

py/services/model_metadata_provider.py

@@ -0,0 +1,571 @@
+from abc import ABC, abstractmethod
+import asyncio
+import json
+import logging
+import random
+from typing import Optional, Dict, Tuple, Any, List, Sequence
+from .downloader import get_downloader
+from .errors import RateLimitError
+
+try:
+    from bs4 import BeautifulSoup
+except ImportError as exc:
+    BeautifulSoup = None  # type: ignore[assignment]
+    _BS4_IMPORT_ERROR = exc
+else:
+    _BS4_IMPORT_ERROR = None
+
+try:
+    import aiosqlite
+except ImportError as exc:
+    aiosqlite = None  # type: ignore[assignment]
+    _AIOSQLITE_IMPORT_ERROR = exc
+else:
+    _AIOSQLITE_IMPORT_ERROR = None
+
+def _require_beautifulsoup() -> Any:
+    if BeautifulSoup is None:
+        raise RuntimeError(
+            "BeautifulSoup (bs4) is required for CivArchiveModelMetadataProvider. "
+            "Install it with 'pip install beautifulsoup4'."
+        ) from _BS4_IMPORT_ERROR
+    return BeautifulSoup
+
+def _require_aiosqlite() -> Any:
+    if aiosqlite is None:
+        raise RuntimeError(
+            "aiosqlite is required for SQLiteModelMetadataProvider. "
+            "Install it with 'pip install aiosqlite'."
+        ) from _AIOSQLITE_IMPORT_ERROR
+    return aiosqlite
+
+logger = logging.getLogger(__name__)
+
+class ModelMetadataProvider(ABC):
+    """Base abstract class for all model metadata providers"""
+    
+    @abstractmethod
+    async def get_model_by_hash(self, model_hash: str) -> Tuple[Optional[Dict], Optional[str]]:
+        """Find model by hash value"""
+        pass
+        
+    @abstractmethod
+    async def get_model_versions(self, model_id: str) -> Optional[Dict]:
+        """Get all versions of a model with their details"""
+        pass
+        
+    @abstractmethod
+    async def get_model_version(self, model_id: int = None, version_id: int = None) -> Optional[Dict]:
+        """Get specific model version with additional metadata"""
+        pass
+        
+    @abstractmethod
+    async def get_model_version_info(self, version_id: str) -> Tuple[Optional[Dict], Optional[str]]:
+        """Fetch model version metadata"""
+        pass
+
+    @abstractmethod
+    async def get_user_models(self, username: str) -> Optional[List[Dict]]:
+        """Fetch models owned by the specified user"""
+        pass
+
+class CivitaiModelMetadataProvider(ModelMetadataProvider):
+    """Provider that uses Civitai API for metadata"""
+    
+    def __init__(self, civitai_client):
+        self.client = civitai_client
+        
+    async def get_model_by_hash(self, model_hash: str) -> Tuple[Optional[Dict], Optional[str]]:
+        return await self.client.get_model_by_hash(model_hash)
+        
+    async def get_model_versions(self, model_id: str) -> Optional[Dict]:
+        return await self.client.get_model_versions(model_id)
+        
+    async def get_model_version(self, model_id: int = None, version_id: int = None) -> Optional[Dict]:
+        return await self.client.get_model_version(model_id, version_id)
+        
+    async def get_model_version_info(self, version_id: str) -> Tuple[Optional[Dict], Optional[str]]:
+        return await self.client.get_model_version_info(version_id)
+
+    async def get_user_models(self, username: str) -> Optional[List[Dict]]:
+        return await self.client.get_user_models(username)
+
+class CivArchiveModelMetadataProvider(ModelMetadataProvider):
+    """Provider that uses CivArchive API for metadata"""
+    
+    def __init__(self, civarchive_client):
+        self.client = civarchive_client
+        
+    async def get_model_by_hash(self, model_hash: str) -> Tuple[Optional[Dict], Optional[str]]:
+        return await self.client.get_model_by_hash(model_hash)
+        
+    async def get_model_versions(self, model_id: str) -> Optional[Dict]:
+        return await self.client.get_model_versions(model_id)
+        
+    async def get_model_version(self, model_id: int = None, version_id: int = None) -> Optional[Dict]:
+        return await self.client.get_model_version(model_id, version_id)
+        
+    async def get_model_version_info(self, version_id: str) -> Tuple[Optional[Dict], Optional[str]]:
+        return await self.client.get_model_version_info(version_id)
+
+    async def get_user_models(self, username: str) -> Optional[List[Dict]]:
+        """Not supported by CivArchive provider"""
+        return None
+
+class SQLiteModelMetadataProvider(ModelMetadataProvider):
+    """Provider that uses SQLite database for metadata"""
+    
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self._aiosqlite = _require_aiosqlite()
+        
+    async def get_model_by_hash(self, model_hash: str) -> Tuple[Optional[Dict], Optional[str]]:
+        """Find model by hash value from SQLite database"""
+        async with self._aiosqlite.connect(self.db_path) as db:
+            # Look up in model_files table to get model_id and version_id
+            query = """
+                SELECT model_id, version_id 
+                FROM model_files 
+                WHERE sha256 = ? 
+                LIMIT 1
+            """
+            db.row_factory = self._aiosqlite.Row
+            cursor = await db.execute(query, (model_hash.upper(),))
+            file_row = await cursor.fetchone()
+            
+            if not file_row:
+                return None, "Model not found"
+                
+            # Get version details
+            model_id = file_row['model_id']
+            version_id = file_row['version_id']
+            
+            # Build response in the same format as Civitai API
+            result = await self._get_version_with_model_data(db, model_id, version_id)
+            return result, None if result else "Error retrieving model data"
+            
+    async def get_model_versions(self, model_id: str) -> Optional[Dict]:
+        """Get all versions of a model from SQLite database"""
+        async with self._aiosqlite.connect(self.db_path) as db:
+            db.row_factory = self._aiosqlite.Row
+            
+            # First check if model exists
+            model_query = "SELECT * FROM models WHERE id = ?"
+            cursor = await db.execute(model_query, (model_id,))
+            model_row = await cursor.fetchone()
+            
+            if not model_row:
+                return None
+                
+            model_data = json.loads(model_row['data'])
+            model_type = model_row['type']
+            model_name = model_row['name']
+            
+            # Get all versions for this model
+            versions_query = """
+                SELECT id, name, base_model, data, position, published_at
+                FROM model_versions
+                WHERE model_id = ?
+                ORDER BY position ASC
+            """
+            cursor = await db.execute(versions_query, (model_id,))
+            version_rows = await cursor.fetchall()
+            
+            if not version_rows:
+                return {'modelVersions': [], 'type': model_type}
+                
+            # Format versions similar to Civitai API
+            model_versions = []
+            for row in version_rows:
+                version_data = json.loads(row['data'])
+                # Add fields from the row to ensure we have the basic fields
+                version_entry = {
+                    'id': row['id'],
+                    'modelId': int(model_id),
+                    'name': row['name'],
+                    'baseModel': row['base_model'],
+                    'model': {
+                        'name': model_row['name'],
+                        'type': model_type,
+                    },
+                    'source': 'archive_db'
+                }
+                # Update with any additional data
+                version_entry.update(version_data)
+                model_versions.append(version_entry)
+                
+            return {
+                'modelVersions': model_versions,
+                'type': model_type,
+                'name': model_name
+            }
+    
+    async def get_model_version(self, model_id: int = None, version_id: int = None) -> Optional[Dict]:
+        """Get specific model version with additional metadata from SQLite database"""
+        if not model_id and not version_id:
+            return None
+            
+        async with self._aiosqlite.connect(self.db_path) as db:
+            db.row_factory = self._aiosqlite.Row
+            
+            # Case 1: Only version_id is provided
+            if model_id is None and version_id is not None:
+                # First get the version info to extract model_id
+                version_query = "SELECT model_id FROM model_versions WHERE id = ?"
+                cursor = await db.execute(version_query, (version_id,))
+                version_row = await cursor.fetchone()
+                
+                if not version_row:
+                    return None
+                    
+                model_id = version_row['model_id']
+            
+            # Case 2: model_id is provided but version_id is not
+            elif model_id is not None and version_id is None:
+                # Find the latest version
+                version_query = """
+                    SELECT id FROM model_versions 
+                    WHERE model_id = ? 
+                    ORDER BY position ASC
+                    LIMIT 1
+                """
+                cursor = await db.execute(version_query, (model_id,))
+                version_row = await cursor.fetchone()
+                
+                if not version_row:
+                    return None
+                    
+                version_id = version_row['id']
+            
+            # Now we have both model_id and version_id, get the full data
+            return await self._get_version_with_model_data(db, model_id, version_id)
+    
+    async def get_model_version_info(self, version_id: str) -> Tuple[Optional[Dict], Optional[str]]:
+        """Fetch model version metadata from SQLite database"""
+        async with self._aiosqlite.connect(self.db_path) as db:
+            db.row_factory = self._aiosqlite.Row
+
+            # Get version details
+            version_query = "SELECT model_id FROM model_versions WHERE id = ?"
+            cursor = await db.execute(version_query, (version_id,))
+            version_row = await cursor.fetchone()
+
+            if not version_row:
+                return None, "Model version not found"
+
+            model_id = version_row['model_id']
+
+            # Build complete version data with model info
+            version_data = await self._get_version_with_model_data(db, model_id, version_id)
+            return version_data, None
+
+    async def get_user_models(self, username: str) -> Optional[List[Dict]]:
+        """Listing models by username is not supported for archive database"""
+        return None
+    
+    async def _get_version_with_model_data(self, db, model_id, version_id) -> Optional[Dict]:
+        """Helper to build version data with model information"""
+        # Get version details
+        version_query = "SELECT name, base_model, data FROM model_versions WHERE id = ? AND model_id = ?"
+        cursor = await db.execute(version_query, (version_id, model_id))
+        version_row = await cursor.fetchone()
+        
+        if not version_row:
+            return None
+            
+        # Get model details
+        model_query = "SELECT name, type, data, username FROM models WHERE id = ?"
+        cursor = await db.execute(model_query, (model_id,))
+        model_row = await cursor.fetchone()
+        
+        if not model_row:
+            return None
+            
+        # Parse JSON data
+        try:
+            version_data = json.loads(version_row['data'])
+            model_data = json.loads(model_row['data'])
+            
+            # Build response
+            result = {
+                "id": int(version_id),
+                "modelId": int(model_id),
+                "name": version_row['name'],
+                "baseModel": version_row['base_model'],
+                "model": {
+                    "name": model_row['name'],
+                    "description": model_data.get("description"),
+                    "type": model_row['type'],
+                    "tags": model_data.get("tags", [])
+                },
+                "creator": {
+                    "username": model_row['username'] or model_data.get("creator", {}).get("username"),
+                    "image": model_data.get("creator", {}).get("image")
+                },
+                "source": "archive_db"
+            }
+            
+            # Add any additional fields from version data
+            result.update(version_data)
+            
+            # Attach files associated with this version from model_files table
+            files_query = """
+                SELECT data
+                FROM model_files
+                WHERE version_id = ? AND type = 'Model'
+                ORDER BY id ASC
+            """
+            cursor = await db.execute(files_query, (version_id,))
+            file_rows = await cursor.fetchall()
+            
+            files = []
+            for file_row in file_rows:
+                try:
+                    file_data = json.loads(file_row['data'])
+                except json.JSONDecodeError:
+                    logger.warning(
+                        "Skipping model_files entry with invalid JSON for version_id %s", version_id
+                    )
+                    continue
+                # Remove 'modelId' and 'modelVersionId' fields if present
+                file_data.pop('modelId', None)
+                file_data.pop('modelVersionId', None)
+                files.append(file_data)
+            
+            if 'files' in result:
+                existing_files = result['files']
+                if isinstance(existing_files, list):
+                    existing_files.extend(files)
+                    result['files'] = existing_files
+                else:
+                    merged_files = files.copy()
+                    if existing_files:
+                        merged_files.insert(0, existing_files)
+                    result['files'] = merged_files
+            elif files:
+                result['files'] = files
+            else:
+                result['files'] = []
+            
+            return result
+        except json.JSONDecodeError:
+            return None
+        
+class FallbackMetadataProvider(ModelMetadataProvider):
+    """Try providers in order, return first successful result."""
+
+    def __init__(
+        self,
+        providers: Sequence[ModelMetadataProvider | Tuple[str, ModelMetadataProvider]],
+        *,
+        rate_limit_retry_limit: int = 3,
+        rate_limit_base_delay: float = 1.5,
+        rate_limit_max_delay: float = 30.0,
+        rate_limit_jitter_ratio: float = 0.2,
+    ) -> None:
+        self.providers: List[ModelMetadataProvider] = []
+        self._provider_labels: List[str] = []
+
+        for entry in providers:
+            if isinstance(entry, tuple) and len(entry) == 2:
+                name, provider = entry
+            else:
+                provider = entry
+                name = provider.__class__.__name__
+            self.providers.append(provider)
+            self._provider_labels.append(str(name))
+
+        self._rate_limit_retry_limit = max(1, rate_limit_retry_limit)
+        self._rate_limit_base_delay = rate_limit_base_delay
+        self._rate_limit_max_delay = rate_limit_max_delay
+        self._rate_limit_jitter_ratio = max(0.0, rate_limit_jitter_ratio)
+
+    async def get_model_by_hash(self, model_hash: str) -> Tuple[Optional[Dict], Optional[str]]:
+        for provider, label in self._iter_providers():
+            try:
+                result, error = await self._call_with_rate_limit(
+                    label,
+                    provider.get_model_by_hash,
+                    model_hash,
+                )
+                if result:
+                    return result, error
+            except RateLimitError as exc:
+                exc.provider = exc.provider or label
+                raise exc
+            except Exception as e:
+                logger.debug("Provider %s failed for get_model_by_hash: %s", label, e)
+                continue
+        return None, "Model not found"
+
+    async def get_model_versions(self, model_id: str) -> Optional[Dict]:
+        for provider, label in self._iter_providers():
+            try:
+                result = await self._call_with_rate_limit(
+                    label,
+                    provider.get_model_versions,
+                    model_id,
+                )
+                if result:
+                    return result
+            except RateLimitError as exc:
+                exc.provider = exc.provider or label
+                raise exc
+            except Exception as e:
+                logger.debug("Provider %s failed for get_model_versions: %s", label, e)
+                continue
+        return None
+
+    async def get_model_version(self, model_id: int = None, version_id: int = None) -> Optional[Dict]:
+        for provider, label in self._iter_providers():
+            try:
+                result = await self._call_with_rate_limit(
+                    label,
+                    provider.get_model_version,
+                    model_id,
+                    version_id,
+                )
+                if result:
+                    return result
+            except RateLimitError as exc:
+                exc.provider = exc.provider or label
+                raise exc
+            except Exception as e:
+                logger.debug("Provider %s failed for get_model_version: %s", label, e)
+                continue
+        return None
+
+    async def get_model_version_info(self, version_id: str) -> Tuple[Optional[Dict], Optional[str]]:
+        for provider, label in self._iter_providers():
+            try:
+                result, error = await self._call_with_rate_limit(
+                    label,
+                    provider.get_model_version_info,
+                    version_id,
+                )
+                if result:
+                    return result, error
+            except RateLimitError as exc:
+                exc.provider = exc.provider or label
+                raise exc
+            except Exception as e:
+                logger.debug("Provider %s failed for get_model_version_info: %s", label, e)
+                continue
+        return None, "No provider could retrieve the data"
+
+    async def get_user_models(self, username: str) -> Optional[List[Dict]]:
+        for provider, label in self._iter_providers():
+            try:
+                result = await self._call_with_rate_limit(
+                    label,
+                    provider.get_user_models,
+                    username,
+                )
+                if result is not None:
+                    return result
+            except RateLimitError as exc:
+                exc.provider = exc.provider or label
+                raise exc
+            except Exception as e:
+                logger.debug("Provider %s failed for get_user_models: %s", label, e)
+                continue
+        return None
+
+    def _iter_providers(self):
+        return zip(self.providers, self._provider_labels)
+
+    async def _call_with_rate_limit(
+        self,
+        label: str,
+        func,
+        *args,
+        **kwargs,
+    ):
+        attempt = 0
+        while True:
+            try:
+                return await func(*args, **kwargs)
+            except RateLimitError as exc:
+                attempt += 1
+                if attempt >= self._rate_limit_retry_limit:
+                    exc.provider = exc.provider or label
+                    raise exc
+                delay = self._calculate_rate_limit_delay(exc.retry_after, attempt)
+                logger.warning(
+                    "Provider %s rate limited request; retrying in %.2fs (attempt %s/%s)",
+                    label,
+                    delay,
+                    attempt,
+                    self._rate_limit_retry_limit,
+                )
+                await asyncio.sleep(delay)
+            except Exception:
+                raise
+
+    def _calculate_rate_limit_delay(self, retry_after: Optional[float], attempt: int) -> float:
+        if retry_after is not None:
+            return min(self._rate_limit_max_delay, max(0.0, retry_after))
+
+        base_delay = self._rate_limit_base_delay * (2 ** max(0, attempt - 1))
+        jitter_span = base_delay * self._rate_limit_jitter_ratio
+        if jitter_span > 0:
+            base_delay += random.uniform(-jitter_span, jitter_span)
+
+        return min(self._rate_limit_max_delay, max(0.0, base_delay))
+
+class ModelMetadataProviderManager:
+    """Manager for selecting and using model metadata providers"""
+    
+    _instance = None
+    
+    @classmethod
+    async def get_instance(cls):
+        """Get singleton instance of ModelMetadataProviderManager"""
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+    
+    def __init__(self):
+        self.providers = {}
+        self.default_provider = None
+        
+    def register_provider(self, name: str, provider: ModelMetadataProvider, is_default: bool = False):
+        """Register a metadata provider"""
+        self.providers[name] = provider
+        if is_default or self.default_provider is None:
+            self.default_provider = name
+            
+    async def get_model_by_hash(self, model_hash: str, provider_name: str = None) -> Tuple[Optional[Dict], Optional[str]]:
+        """Find model by hash using specified or default provider"""
+        provider = self._get_provider(provider_name)
+        return await provider.get_model_by_hash(model_hash)
+        
+    async def get_model_versions(self, model_id: str, provider_name: str = None) -> Optional[Dict]:
+        """Get model versions using specified or default provider"""
+        provider = self._get_provider(provider_name)
+        return await provider.get_model_versions(model_id)
+        
+    async def get_model_version(self, model_id: int = None, version_id: int = None, provider_name: str = None) -> Optional[Dict]:
+        """Get specific model version using specified or default provider"""
+        provider = self._get_provider(provider_name)
+        return await provider.get_model_version(model_id, version_id)
+        
+    async def get_model_version_info(self, version_id: str, provider_name: str = None) -> Tuple[Optional[Dict], Optional[str]]:
+        """Fetch model version info using specified or default provider"""
+        provider = self._get_provider(provider_name)
+        return await provider.get_model_version_info(version_id)
+
+    async def get_user_models(self, username: str, provider_name: str = None) -> Optional[List[Dict]]:
+        """Fetch models owned by the specified user"""
+        provider = self._get_provider(provider_name)
+        return await provider.get_user_models(username)
+        
+    def _get_provider(self, provider_name: str = None) -> ModelMetadataProvider:
+        """Get provider by name or default provider"""
+        if provider_name and provider_name in self.providers:
+            return self.providers[provider_name]
+        
+        if self.default_provider is None:
+            raise ValueError("No default provider set and no valid provider specified")
+            
+        return self.providers[self.default_provider]

py/services/model_query.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Protocol, Callable
+
+from ..utils.constants import NSFW_LEVELS
+from ..utils.utils import fuzzy_match as default_fuzzy_match
+
+
+class SettingsProvider(Protocol):
+    """Protocol describing the SettingsManager contract used by query helpers."""
+
+    def get(self, key: str, default: Any = None) -> Any:
+        ...
+
+
+@dataclass(frozen=True)
+class SortParams:
+    """Normalized representation of sorting instructions."""
+
+    key: str
+    order: str
+
+
+@dataclass(frozen=True)
+class FilterCriteria:
+    """Container for model list filtering options."""
+
+    folder: Optional[str] = None
+    base_models: Optional[Sequence[str]] = None
+    tags: Optional[Sequence[str]] = None
+    favorites_only: bool = False
+    search_options: Optional[Dict[str, Any]] = None
+
+
+class ModelCacheRepository:
+    """Adapter around scanner cache access and sort normalisation."""
+
+    def __init__(self, scanner) -> None:
+        self._scanner = scanner
+
+    async def get_cache(self):
+        """Return the underlying cache instance from the scanner."""
+        return await self._scanner.get_cached_data()
+
+    async def fetch_sorted(self, params: SortParams) -> List[Dict[str, Any]]:
+        """Fetch cached data pre-sorted according to ``params``."""
+        cache = await self.get_cache()
+        return await cache.get_sorted_data(params.key, params.order)
+
+    @staticmethod
+    def parse_sort(sort_by: str) -> SortParams:
+        """Parse an incoming sort string into key/order primitives."""
+        if not sort_by:
+            return SortParams(key="name", order="asc")
+
+        if ":" in sort_by:
+            raw_key, raw_order = sort_by.split(":", 1)
+            sort_key = raw_key.strip().lower() or "name"
+            order = raw_order.strip().lower()
+        else:
+            sort_key = sort_by.strip().lower() or "name"
+            order = "asc"
+
+        if order not in ("asc", "desc"):
+            order = "asc"
+
+        return SortParams(key=sort_key, order=order)
+
+
+class ModelFilterSet:
+    """Applies common filtering rules to the model collection."""
+
+    def __init__(self, settings: SettingsProvider, nsfw_levels: Optional[Dict[str, int]] = None) -> None:
+        self._settings = settings
+        self._nsfw_levels = nsfw_levels or NSFW_LEVELS
+
+    def apply(self, data: Iterable[Dict[str, Any]], criteria: FilterCriteria) -> List[Dict[str, Any]]:
+        """Return items that satisfy the provided criteria."""
+        items = list(data)
+
+        if self._settings.get("show_only_sfw", False):
+            threshold = self._nsfw_levels.get("R", 0)
+            items = [
+                item for item in items
+                if not item.get("preview_nsfw_level") or item.get("preview_nsfw_level") < threshold
+            ]
+
+        if criteria.favorites_only:
+            items = [item for item in items if item.get("favorite", False)]
+
+        folder = criteria.folder
+        options = criteria.search_options or {}
+        recursive = bool(options.get("recursive", True))
+        if folder is not None:
+            if recursive:
+                if folder:
+                    folder_with_sep = f"{folder}/"
+                    items = [
+                        item for item in items
+                        if item.get("folder") == folder or item.get("folder", "").startswith(folder_with_sep)
+                    ]
+            else:
+                items = [item for item in items if item.get("folder") == folder]
+
+        base_models = criteria.base_models or []
+        if base_models:
+            base_model_set = set(base_models)
+            items = [item for item in items if item.get("base_model") in base_model_set]
+
+        tags = criteria.tags or []
+        if tags:
+            tag_set = set(tags)
+            items = [
+                item for item in items
+                if any(tag in tag_set for tag in item.get("tags", []))
+            ]
+
+        return items
+
+
+class SearchStrategy:
+    """Encapsulates text and fuzzy matching behaviour for model queries."""
+
+    DEFAULT_OPTIONS: Dict[str, Any] = {
+        "filename": True,
+        "modelname": True,
+        "tags": False,
+        "recursive": True,
+        "creator": False,
+    }
+
+    def __init__(self, fuzzy_matcher: Optional[Callable[[str, str], bool]] = None) -> None:
+        self._fuzzy_match = fuzzy_matcher or default_fuzzy_match
+
+    def normalize_options(self, options: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """Merge provided options with defaults without mutating input."""
+        normalized = dict(self.DEFAULT_OPTIONS)
+        if options:
+            normalized.update(options)
+        return normalized
+
+    def apply(
+        self,
+        data: Iterable[Dict[str, Any]],
+        search_term: str,
+        options: Dict[str, Any],
+        fuzzy: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """Return items matching the search term using the configured strategy."""
+        if not search_term:
+            return list(data)
+
+        search_lower = search_term.lower()
+        results: List[Dict[str, Any]] = []
+
+        for item in data:
+            if options.get("filename", True):
+                candidate = item.get("file_name", "")
+                if self._matches(candidate, search_term, search_lower, fuzzy):
+                    results.append(item)
+                    continue
+
+            if options.get("modelname", True):
+                candidate = item.get("model_name", "")
+                if self._matches(candidate, search_term, search_lower, fuzzy):
+                    results.append(item)
+                    continue
+
+            if options.get("tags", False):
+                tags = item.get("tags", []) or []
+                if any(self._matches(tag, search_term, search_lower, fuzzy) for tag in tags):
+                    results.append(item)
+                    continue
+
+            if options.get("creator", False):
+                creator_username = ""
+                civitai = item.get("civitai")
+                if isinstance(civitai, dict):
+                    creator = civitai.get("creator")
+                    if isinstance(creator, dict):
+                        creator_username = creator.get("username", "")
+                if creator_username and self._matches(creator_username, search_term, search_lower, fuzzy):
+                    results.append(item)
+                    continue
+
+        return results
+
+    def _matches(self, candidate: str, search_term: str, search_lower: str, fuzzy: bool) -> bool:
+        if not candidate:
+            return False
+
+        candidate_lower = candidate.lower()
+        if fuzzy:
+            return self._fuzzy_match(candidate, search_term)
+        return search_lower in candidate_lower

py/services/model_update_service.py

@@ -0,0 +1,411 @@
+"""Service for tracking remote model version updates."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import sqlite3
+import time
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Mapping, Optional, Sequence
+
+from .errors import RateLimitError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ModelUpdateRecord:
+    """Representation of a persisted update record."""
+
+    model_type: str
+    model_id: int
+    largest_version_id: Optional[int]
+    version_ids: List[int]
+    in_library_version_ids: List[int]
+    last_checked_at: Optional[float]
+    should_ignore: bool
+
+    def has_update(self) -> bool:
+        """Return True when remote versions exceed the local library."""
+
+        if self.should_ignore or not self.version_ids:
+            return False
+        local_versions = set(self.in_library_version_ids)
+        return any(version_id not in local_versions for version_id in self.version_ids)
+
+
+class ModelUpdateService:
+    """Persist and query remote model version metadata."""
+
+    _SCHEMA = """
+        CREATE TABLE IF NOT EXISTS model_update_status (
+            model_type TEXT NOT NULL,
+            model_id INTEGER NOT NULL,
+            largest_version_id INTEGER,
+            version_ids TEXT,
+            in_library_version_ids TEXT,
+            last_checked_at REAL,
+            should_ignore INTEGER DEFAULT 0,
+            PRIMARY KEY (model_type, model_id)
+        )
+    """
+
+    def __init__(self, db_path: str, *, ttl_seconds: int = 24 * 60 * 60) -> None:
+        self._db_path = db_path
+        self._ttl_seconds = ttl_seconds
+        self._lock = asyncio.Lock()
+        self._schema_initialized = False
+        self._ensure_directory()
+        self._initialize_schema()
+
+    def _ensure_directory(self) -> None:
+        directory = os.path.dirname(self._db_path)
+        if directory:
+            os.makedirs(directory, exist_ok=True)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self._db_path, check_same_thread=False)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _initialize_schema(self) -> None:
+        if self._schema_initialized:
+            return
+        try:
+            with self._connect() as conn:
+                conn.execute("PRAGMA journal_mode=WAL")
+                conn.execute("PRAGMA foreign_keys = ON")
+                conn.executescript(self._SCHEMA)
+            self._schema_initialized = True
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.error("Failed to initialize update schema: %s", exc, exc_info=True)
+            raise
+
+    async def refresh_for_model_type(
+        self,
+        model_type: str,
+        scanner,
+        metadata_provider,
+        *,
+        force_refresh: bool = False,
+    ) -> Dict[int, ModelUpdateRecord]:
+        """Refresh update information for every model present in the cache."""
+
+        local_versions = await self._collect_local_versions(scanner)
+        results: Dict[int, ModelUpdateRecord] = {}
+        for model_id, version_ids in local_versions.items():
+            record = await self._refresh_single_model(
+                model_type,
+                model_id,
+                version_ids,
+                metadata_provider,
+                force_refresh=force_refresh,
+            )
+            if record:
+                results[model_id] = record
+        return results
+
+    async def refresh_single_model(
+        self,
+        model_type: str,
+        model_id: int,
+        scanner,
+        metadata_provider,
+        *,
+        force_refresh: bool = False,
+    ) -> Optional[ModelUpdateRecord]:
+        """Refresh update information for a specific model id."""
+
+        local_versions = await self._collect_local_versions(scanner)
+        version_ids = local_versions.get(model_id, [])
+        return await self._refresh_single_model(
+            model_type,
+            model_id,
+            version_ids,
+            metadata_provider,
+            force_refresh=force_refresh,
+        )
+
+    async def update_in_library_versions(
+        self,
+        model_type: str,
+        model_id: int,
+        version_ids: Sequence[int],
+    ) -> ModelUpdateRecord:
+        """Persist a new set of in-library version identifiers."""
+
+        normalized_versions = self._normalize_sequence(version_ids)
+        async with self._lock:
+            existing = self._get_record(model_type, model_id)
+            record = ModelUpdateRecord(
+                model_type=model_type,
+                model_id=model_id,
+                largest_version_id=existing.largest_version_id if existing else None,
+                version_ids=list(existing.version_ids) if existing else [],
+                in_library_version_ids=normalized_versions,
+                last_checked_at=existing.last_checked_at if existing else None,
+                should_ignore=existing.should_ignore if existing else False,
+            )
+            self._upsert_record(record)
+            return record
+
+    async def set_should_ignore(
+        self, model_type: str, model_id: int, should_ignore: bool
+    ) -> ModelUpdateRecord:
+        """Toggle the ignore flag for a model."""
+
+        async with self._lock:
+            existing = self._get_record(model_type, model_id)
+            if existing:
+                record = ModelUpdateRecord(
+                    model_type=model_type,
+                    model_id=model_id,
+                    largest_version_id=existing.largest_version_id,
+                    version_ids=list(existing.version_ids),
+                    in_library_version_ids=list(existing.in_library_version_ids),
+                    last_checked_at=existing.last_checked_at,
+                    should_ignore=should_ignore,
+                )
+            else:
+                record = ModelUpdateRecord(
+                    model_type=model_type,
+                    model_id=model_id,
+                    largest_version_id=None,
+                    version_ids=[],
+                    in_library_version_ids=[],
+                    last_checked_at=None,
+                    should_ignore=should_ignore,
+                )
+            self._upsert_record(record)
+            return record
+
+    async def get_record(self, model_type: str, model_id: int) -> Optional[ModelUpdateRecord]:
+        """Return a cached record without triggering remote fetches."""
+
+        async with self._lock:
+            return self._get_record(model_type, model_id)
+
+    async def has_update(self, model_type: str, model_id: int) -> bool:
+        """Determine if a model has updates pending."""
+
+        record = await self.get_record(model_type, model_id)
+        return record.has_update() if record else False
+
+    async def _refresh_single_model(
+        self,
+        model_type: str,
+        model_id: int,
+        local_versions: Sequence[int],
+        metadata_provider,
+        *,
+        force_refresh: bool = False,
+    ) -> Optional[ModelUpdateRecord]:
+        normalized_local = self._normalize_sequence(local_versions)
+        now = time.time()
+        async with self._lock:
+            existing = self._get_record(model_type, model_id)
+            if existing and existing.should_ignore and not force_refresh:
+                record = ModelUpdateRecord(
+                    model_type=model_type,
+                    model_id=model_id,
+                    largest_version_id=existing.largest_version_id,
+                    version_ids=list(existing.version_ids),
+                    in_library_version_ids=normalized_local,
+                    last_checked_at=existing.last_checked_at,
+                    should_ignore=True,
+                )
+                self._upsert_record(record)
+                return record
+
+            should_fetch = force_refresh or not existing or self._is_stale(existing, now)
+        # release lock during network request
+        fetched_versions: List[int] | None = None
+        refresh_succeeded = False
+        if metadata_provider and should_fetch:
+            try:
+                response = await metadata_provider.get_model_versions(model_id)
+            except RateLimitError:
+                raise
+            except Exception as exc:  # pragma: no cover - defensive log
+                logger.error(
+                    "Failed to fetch versions for model %s (%s): %s",
+                    model_id,
+                    model_type,
+                    exc,
+                    exc_info=True,
+                )
+            else:
+                if response is not None:
+                    extracted = self._extract_version_ids(response)
+                    if extracted is not None:
+                        fetched_versions = extracted
+                        refresh_succeeded = True
+
+        async with self._lock:
+            existing = self._get_record(model_type, model_id)
+            if existing and existing.should_ignore and not force_refresh:
+                # Ignore state could have flipped while awaiting provider
+                record = ModelUpdateRecord(
+                    model_type=model_type,
+                    model_id=model_id,
+                    largest_version_id=existing.largest_version_id,
+                    version_ids=list(existing.version_ids),
+                    in_library_version_ids=normalized_local,
+                    last_checked_at=existing.last_checked_at,
+                    should_ignore=True,
+                )
+                self._upsert_record(record)
+                return record
+
+            version_ids = (
+                fetched_versions
+                if refresh_succeeded
+                else (list(existing.version_ids) if existing else [])
+            )
+            largest = max(version_ids) if version_ids else None
+            last_checked = now if refresh_succeeded else (
+                existing.last_checked_at if existing else None
+            )
+            record = ModelUpdateRecord(
+                model_type=model_type,
+                model_id=model_id,
+                largest_version_id=largest,
+                version_ids=version_ids,
+                in_library_version_ids=normalized_local,
+                last_checked_at=last_checked,
+                should_ignore=existing.should_ignore if existing else False,
+            )
+            self._upsert_record(record)
+            return record
+
+    async def _collect_local_versions(self, scanner) -> Dict[int, List[int]]:
+        cache = await scanner.get_cached_data()
+        mapping: Dict[int, set[int]] = {}
+        if not cache or not getattr(cache, "raw_data", None):
+            return {}
+
+        for item in cache.raw_data:
+            civitai = item.get("civitai") if isinstance(item, dict) else None
+            if not isinstance(civitai, dict):
+                continue
+            model_id = self._normalize_int(civitai.get("modelId"))
+            version_id = self._normalize_int(civitai.get("id"))
+            if model_id is None or version_id is None:
+                continue
+            mapping.setdefault(model_id, set()).add(version_id)
+
+        return {model_id: sorted(ids) for model_id, ids in mapping.items()}
+
+    def _is_stale(self, record: ModelUpdateRecord, now: float) -> bool:
+        if record.last_checked_at is None:
+            return True
+        return (now - record.last_checked_at) >= self._ttl_seconds
+
+    @staticmethod
+    def _normalize_int(value) -> Optional[int]:
+        try:
+            if value is None:
+                return None
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    def _normalize_sequence(self, values: Sequence[int]) -> List[int]:
+        normalized = [
+            item
+            for item in (self._normalize_int(value) for value in values)
+            if item is not None
+        ]
+        return sorted(dict.fromkeys(normalized))
+
+    def _extract_version_ids(self, response) -> Optional[List[int]]:
+        if not isinstance(response, Mapping):
+            return None
+        versions = response.get("modelVersions")
+        if versions is None:
+            return []
+        if not isinstance(versions, Iterable):
+            return None
+        normalized = []
+        for entry in versions:
+            if isinstance(entry, Mapping):
+                normalized_id = self._normalize_int(entry.get("id"))
+            else:
+                normalized_id = self._normalize_int(entry)
+            if normalized_id is not None:
+                normalized.append(normalized_id)
+        return sorted(dict.fromkeys(normalized))
+
+    def _get_record(self, model_type: str, model_id: int) -> Optional[ModelUpdateRecord]:
+        with self._connect() as conn:
+            row = conn.execute(
+                """
+                SELECT model_type, model_id, largest_version_id, version_ids,
+                       in_library_version_ids, last_checked_at, should_ignore
+                FROM model_update_status
+                WHERE model_type = ? AND model_id = ?
+                """,
+                (model_type, model_id),
+            ).fetchone()
+        if not row:
+            return None
+        return ModelUpdateRecord(
+            model_type=row["model_type"],
+            model_id=int(row["model_id"]),
+            largest_version_id=self._normalize_int(row["largest_version_id"]),
+            version_ids=self._deserialize_json_array(row["version_ids"]),
+            in_library_version_ids=self._deserialize_json_array(
+                row["in_library_version_ids"]
+            ),
+            last_checked_at=row["last_checked_at"],
+            should_ignore=bool(row["should_ignore"]),
+        )
+
+    def _upsert_record(self, record: ModelUpdateRecord) -> None:
+        payload = (
+            record.model_type,
+            record.model_id,
+            record.largest_version_id,
+            json.dumps(record.version_ids),
+            json.dumps(record.in_library_version_ids),
+            record.last_checked_at,
+            1 if record.should_ignore else 0,
+        )
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO model_update_status (
+                    model_type, model_id, largest_version_id, version_ids,
+                    in_library_version_ids, last_checked_at, should_ignore
+                ) VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(model_type, model_id) DO UPDATE SET
+                    largest_version_id = excluded.largest_version_id,
+                    version_ids = excluded.version_ids,
+                    in_library_version_ids = excluded.in_library_version_ids,
+                    last_checked_at = excluded.last_checked_at,
+                    should_ignore = excluded.should_ignore
+                """,
+                payload,
+            )
+            conn.commit()
+
+    @staticmethod
+    def _deserialize_json_array(value) -> List[int]:
+        if not value:
+            return []
+        try:
+            data = json.loads(value)
+        except (TypeError, json.JSONDecodeError):
+            return []
+        if isinstance(data, list):
+            normalized = []
+            for entry in data:
+                try:
+                    normalized.append(int(entry))
+                except (TypeError, ValueError):
+                    continue
+            return sorted(dict.fromkeys(normalized))
+        return []
+

py/services/persistent_model_cache.py

@@ -0,0 +1,569 @@
+import json
+import logging
+import os
+import re
+import sqlite3
+import threading
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from ..utils.settings_paths import get_settings_dir
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PersistedCacheData:
+    """Lightweight structure returned by the persistent cache."""
+
+    raw_data: List[Dict]
+    hash_rows: List[Tuple[str, str]]
+    excluded_models: List[str]
+
+
+class PersistentModelCache:
+    """Persist core model metadata and hash index data in SQLite."""
+
+    _DEFAULT_FILENAME = "model_cache.sqlite"
+    _MODEL_COLUMNS: Tuple[str, ...] = (
+        "model_type",
+        "file_path",
+        "file_name",
+        "model_name",
+        "folder",
+        "size",
+        "modified",
+        "sha256",
+        "base_model",
+        "preview_url",
+        "preview_nsfw_level",
+        "from_civitai",
+        "favorite",
+        "notes",
+        "usage_tips",
+        "metadata_source",
+        "civitai_id",
+        "civitai_model_id",
+        "civitai_name",
+        "civitai_creator_username",
+        "trained_words",
+        "civitai_deleted",
+        "exclude",
+        "db_checked",
+        "last_checked_at",
+    )
+    _MODEL_UPDATE_COLUMNS: Tuple[str, ...] = _MODEL_COLUMNS[2:]
+    _instances: Dict[str, "PersistentModelCache"] = {}
+    _instance_lock = threading.Lock()
+
+    def __init__(self, library_name: str = "default", db_path: Optional[str] = None) -> None:
+        self._library_name = library_name or "default"
+        self._db_path = db_path or self._resolve_default_path(self._library_name)
+        self._db_lock = threading.Lock()
+        self._schema_initialized = False
+        try:
+            directory = os.path.dirname(self._db_path)
+            if directory:
+                os.makedirs(directory, exist_ok=True)
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.warning("Could not create cache directory %s: %s", directory, exc)
+        if self.is_enabled():
+            self._initialize_schema()
+
+    @classmethod
+    def get_default(cls, library_name: Optional[str] = None) -> "PersistentModelCache":
+        name = (library_name or "default")
+        with cls._instance_lock:
+            if name not in cls._instances:
+                cls._instances[name] = cls(name)
+            return cls._instances[name]
+
+    def is_enabled(self) -> bool:
+        return os.environ.get("LORA_MANAGER_DISABLE_PERSISTENT_CACHE", "0") != "1"
+
+    def get_database_path(self) -> str:
+        """Expose the resolved SQLite database path."""
+
+        return self._db_path
+
+    def load_cache(self, model_type: str) -> Optional[PersistedCacheData]:
+        if not self.is_enabled():
+            return None
+        if not self._schema_initialized:
+            self._initialize_schema()
+        if not self._schema_initialized:
+            return None
+        try:
+            with self._db_lock:
+                conn = self._connect(readonly=True)
+                try:
+                    model_columns_sql = ", ".join(self._MODEL_COLUMNS[1:])
+                    rows = conn.execute(
+                        f"SELECT {model_columns_sql} FROM models WHERE model_type = ?",
+                        (model_type,),
+                    ).fetchall()
+
+                    if not rows:
+                        return None
+
+                    tags = self._load_tags(conn, model_type)
+                    hash_rows = conn.execute(
+                        "SELECT sha256, file_path FROM hash_index WHERE model_type = ?",
+                        (model_type,),
+                    ).fetchall()
+                    excluded = conn.execute(
+                        "SELECT file_path FROM excluded_models WHERE model_type = ?",
+                        (model_type,),
+                    ).fetchall()
+                finally:
+                    conn.close()
+        except Exception as exc:
+            logger.warning("Failed to load persisted cache for %s: %s", model_type, exc)
+            return None
+
+        raw_data: List[Dict] = []
+        for row in rows:
+            file_path: str = row["file_path"]
+            trained_words = []
+            if row["trained_words"]:
+                try:
+                    trained_words = json.loads(row["trained_words"])
+                except json.JSONDecodeError:
+                    trained_words = []
+
+            creator_username = row["civitai_creator_username"]
+            civitai: Optional[Dict] = None
+            civitai_has_data = any(
+                row[col] is not None for col in ("civitai_id", "civitai_model_id", "civitai_name")
+            ) or trained_words or creator_username
+            if civitai_has_data:
+                civitai = {}
+                if row["civitai_id"] is not None:
+                    civitai["id"] = row["civitai_id"]
+                if row["civitai_model_id"] is not None:
+                    civitai["modelId"] = row["civitai_model_id"]
+                if row["civitai_name"]:
+                    civitai["name"] = row["civitai_name"]
+                if trained_words:
+                    civitai["trainedWords"] = trained_words
+                if creator_username:
+                    civitai.setdefault("creator", {})["username"] = creator_username
+
+            item = {
+                "file_path": file_path,
+                "file_name": row["file_name"],
+                "model_name": row["model_name"],
+                "folder": row["folder"] or "",
+                "size": row["size"] or 0,
+                "modified": row["modified"] or 0.0,
+                "sha256": row["sha256"] or "",
+                "base_model": row["base_model"] or "",
+                "preview_url": row["preview_url"] or "",
+                "preview_nsfw_level": row["preview_nsfw_level"] or 0,
+                "from_civitai": bool(row["from_civitai"]),
+                "favorite": bool(row["favorite"]),
+                "notes": row["notes"] or "",
+                "usage_tips": row["usage_tips"] or "",
+                "metadata_source": row["metadata_source"] or None,
+                "exclude": bool(row["exclude"]),
+                "db_checked": bool(row["db_checked"]),
+                "last_checked_at": row["last_checked_at"] or 0.0,
+                "tags": tags.get(file_path, []),
+                "civitai": civitai,
+                "civitai_deleted": bool(row["civitai_deleted"]),
+            }
+            raw_data.append(item)
+
+        hash_pairs = [(entry["sha256"].lower(), entry["file_path"]) for entry in hash_rows if entry["sha256"]]
+        if not hash_pairs:
+            # Fall back to hashes stored on the model rows
+            for item in raw_data:
+                sha_value = item.get("sha256")
+                if sha_value:
+                    hash_pairs.append((sha_value.lower(), item["file_path"]))
+
+        excluded_paths = [row["file_path"] for row in excluded]
+        return PersistedCacheData(raw_data=raw_data, hash_rows=hash_pairs, excluded_models=excluded_paths)
+
+    def save_cache(self, model_type: str, raw_data: Sequence[Dict], hash_index: Dict[str, List[str]], excluded_models: Sequence[str]) -> None:
+        if not self.is_enabled():
+            return
+        if not self._schema_initialized:
+            self._initialize_schema()
+        if not self._schema_initialized:
+            return
+        try:
+            with self._db_lock:
+                conn = self._connect()
+                try:
+                    conn.execute("PRAGMA foreign_keys = ON")
+                    conn.execute("BEGIN")
+
+                    model_rows = [self._prepare_model_row(model_type, item) for item in raw_data]
+                    model_map: Dict[str, Tuple] = {
+                        row[1]: row for row in model_rows if row[1]  # row[1] is file_path
+                    }
+
+                    existing_models = conn.execute(
+                        "SELECT "
+                        + ", ".join(self._MODEL_COLUMNS[1:])
+                        + " FROM models WHERE model_type = ?",
+                        (model_type,),
+                    ).fetchall()
+                    existing_model_map: Dict[str, sqlite3.Row] = {
+                        row["file_path"]: row for row in existing_models
+                    }
+
+                    to_remove_models = [
+                        (model_type, path)
+                        for path in existing_model_map.keys()
+                        if path not in model_map
+                    ]
+                    if to_remove_models:
+                        conn.executemany(
+                            "DELETE FROM models WHERE model_type = ? AND file_path = ?",
+                            to_remove_models,
+                        )
+                        conn.executemany(
+                            "DELETE FROM model_tags WHERE model_type = ? AND file_path = ?",
+                            to_remove_models,
+                        )
+                        conn.executemany(
+                            "DELETE FROM hash_index WHERE model_type = ? AND file_path = ?",
+                            to_remove_models,
+                        )
+                        conn.executemany(
+                            "DELETE FROM excluded_models WHERE model_type = ? AND file_path = ?",
+                            to_remove_models,
+                        )
+
+                    insert_rows: List[Tuple] = []
+                    update_rows: List[Tuple] = []
+
+                    for file_path, row in model_map.items():
+                        existing = existing_model_map.get(file_path)
+                        if existing is None:
+                            insert_rows.append(row)
+                            continue
+
+                        existing_values = tuple(
+                            existing[column] for column in self._MODEL_COLUMNS[1:]
+                        )
+                        current_values = row[1:]
+                        if existing_values != current_values:
+                            update_rows.append(row[2:] + (model_type, file_path))
+
+                    if insert_rows:
+                        conn.executemany(self._insert_model_sql(), insert_rows)
+
+                    if update_rows:
+                        set_clause = ", ".join(
+                            f"{column} = ?"
+                            for column in self._MODEL_UPDATE_COLUMNS
+                        )
+                        update_sql = (
+                            f"UPDATE models SET {set_clause} WHERE model_type = ? AND file_path = ?"
+                        )
+                        conn.executemany(update_sql, update_rows)
+
+                    existing_tags_rows = conn.execute(
+                        "SELECT file_path, tag FROM model_tags WHERE model_type = ?",
+                        (model_type,),
+                    ).fetchall()
+                    existing_tags: Dict[str, set] = {}
+                    for row in existing_tags_rows:
+                        existing_tags.setdefault(row["file_path"], set()).add(row["tag"])
+
+                    new_tags: Dict[str, set] = {}
+                    for item in raw_data:
+                        file_path = item.get("file_path")
+                        if not file_path:
+                            continue
+                        tags = set(item.get("tags") or [])
+                        if tags:
+                            new_tags[file_path] = tags
+
+                    tag_inserts: List[Tuple[str, str, str]] = []
+                    tag_deletes: List[Tuple[str, str, str]] = []
+
+                    all_tag_paths = set(existing_tags.keys()) | set(new_tags.keys())
+                    for path in all_tag_paths:
+                        existing_set = existing_tags.get(path, set())
+                        new_set = new_tags.get(path, set())
+                        to_add = new_set - existing_set
+                        to_remove = existing_set - new_set
+
+                        for tag in to_add:
+                            tag_inserts.append((model_type, path, tag))
+                        for tag in to_remove:
+                            tag_deletes.append((model_type, path, tag))
+
+                    if tag_deletes:
+                        conn.executemany(
+                            "DELETE FROM model_tags WHERE model_type = ? AND file_path = ? AND tag = ?",
+                            tag_deletes,
+                        )
+                    if tag_inserts:
+                        conn.executemany(
+                            "INSERT INTO model_tags (model_type, file_path, tag) VALUES (?, ?, ?)",
+                            tag_inserts,
+                        )
+
+                    existing_hash_rows = conn.execute(
+                        "SELECT sha256, file_path FROM hash_index WHERE model_type = ?",
+                        (model_type,),
+                    ).fetchall()
+                    existing_hash_map: Dict[str, set] = {}
+                    for row in existing_hash_rows:
+                        sha_value = (row["sha256"] or "").lower()
+                        if not sha_value:
+                            continue
+                        existing_hash_map.setdefault(sha_value, set()).add(row["file_path"])
+
+                    new_hash_map: Dict[str, set] = {}
+                    for sha_value, paths in hash_index.items():
+                        normalized_sha = (sha_value or "").lower()
+                        if not normalized_sha:
+                            continue
+                        bucket = new_hash_map.setdefault(normalized_sha, set())
+                        for path in paths:
+                            if path:
+                                bucket.add(path)
+
+                    hash_inserts: List[Tuple[str, str, str]] = []
+                    hash_deletes: List[Tuple[str, str, str]] = []
+
+                    all_shas = set(existing_hash_map.keys()) | set(new_hash_map.keys())
+                    for sha_value in all_shas:
+                        existing_paths = existing_hash_map.get(sha_value, set())
+                        new_paths = new_hash_map.get(sha_value, set())
+
+                        for path in existing_paths - new_paths:
+                            hash_deletes.append((model_type, sha_value, path))
+                        for path in new_paths - existing_paths:
+                            hash_inserts.append((model_type, sha_value, path))
+
+                    if hash_deletes:
+                        conn.executemany(
+                            "DELETE FROM hash_index WHERE model_type = ? AND sha256 = ? AND file_path = ?",
+                            hash_deletes,
+                        )
+                    if hash_inserts:
+                        conn.executemany(
+                            "INSERT OR IGNORE INTO hash_index (model_type, sha256, file_path) VALUES (?, ?, ?)",
+                            hash_inserts,
+                        )
+
+                    existing_excluded_rows = conn.execute(
+                        "SELECT file_path FROM excluded_models WHERE model_type = ?",
+                        (model_type,),
+                    ).fetchall()
+                    existing_excluded = {row["file_path"] for row in existing_excluded_rows}
+                    new_excluded = {path for path in excluded_models if path}
+
+                    excluded_deletes = [
+                        (model_type, path)
+                        for path in existing_excluded - new_excluded
+                    ]
+                    excluded_inserts = [
+                        (model_type, path)
+                        for path in new_excluded - existing_excluded
+                    ]
+
+                    if excluded_deletes:
+                        conn.executemany(
+                            "DELETE FROM excluded_models WHERE model_type = ? AND file_path = ?",
+                            excluded_deletes,
+                        )
+                    if excluded_inserts:
+                        conn.executemany(
+                            "INSERT OR IGNORE INTO excluded_models (model_type, file_path) VALUES (?, ?)",
+                            excluded_inserts,
+                        )
+
+                    conn.commit()
+                finally:
+                    conn.close()
+        except Exception as exc:
+            logger.warning("Failed to persist cache for %s: %s", model_type, exc)
+
+    # Internal helpers -------------------------------------------------
+
+    def _resolve_default_path(self, library_name: str) -> str:
+        override = os.environ.get("LORA_MANAGER_CACHE_DB")
+        if override:
+            return override
+        try:
+            settings_dir = get_settings_dir(create=True)
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.warning("Falling back to project directory for cache: %s", exc)
+            settings_dir = os.path.dirname(os.path.dirname(self._db_path)) if hasattr(self, "_db_path") else os.getcwd()
+        safe_name = re.sub(r"[^A-Za-z0-9_.-]", "_", library_name or "default")
+        if safe_name.lower() in ("default", ""):
+            legacy_path = os.path.join(settings_dir, self._DEFAULT_FILENAME)
+            if os.path.exists(legacy_path):
+                return legacy_path
+        return os.path.join(settings_dir, "model_cache", f"{safe_name}.sqlite")
+
+    def _initialize_schema(self) -> None:
+        with self._db_lock:
+            if self._schema_initialized:
+                return
+            try:
+                with self._connect() as conn:
+                    conn.execute("PRAGMA journal_mode=WAL")
+                    conn.execute("PRAGMA foreign_keys = ON")
+                    conn.executescript(
+                        """
+                        CREATE TABLE IF NOT EXISTS models (
+                            model_type TEXT NOT NULL,
+                            file_path TEXT NOT NULL,
+                            file_name TEXT,
+                            model_name TEXT,
+                            folder TEXT,
+                            size INTEGER,
+                            modified REAL,
+                            sha256 TEXT,
+                            base_model TEXT,
+                            preview_url TEXT,
+                            preview_nsfw_level INTEGER,
+                            from_civitai INTEGER,
+                            favorite INTEGER,
+                            notes TEXT,
+                            usage_tips TEXT,
+                            metadata_source TEXT,
+                            civitai_id INTEGER,
+                            civitai_model_id INTEGER,
+                            civitai_name TEXT,
+                            civitai_creator_username TEXT,
+                            trained_words TEXT,
+                            civitai_deleted INTEGER,
+                            exclude INTEGER,
+                            db_checked INTEGER,
+                            last_checked_at REAL,
+                            PRIMARY KEY (model_type, file_path)
+                        );
+
+                        CREATE TABLE IF NOT EXISTS model_tags (
+                            model_type TEXT NOT NULL,
+                            file_path TEXT NOT NULL,
+                            tag TEXT NOT NULL,
+                            PRIMARY KEY (model_type, file_path, tag)
+                        );
+
+                        CREATE TABLE IF NOT EXISTS hash_index (
+                            model_type TEXT NOT NULL,
+                            sha256 TEXT NOT NULL,
+                            file_path TEXT NOT NULL,
+                            PRIMARY KEY (model_type, sha256, file_path)
+                        );
+
+                        CREATE TABLE IF NOT EXISTS excluded_models (
+                            model_type TEXT NOT NULL,
+                            file_path TEXT NOT NULL,
+                            PRIMARY KEY (model_type, file_path)
+                        );
+                        """
+                    )
+                    self._ensure_additional_model_columns(conn)
+                    conn.commit()
+                self._schema_initialized = True
+            except Exception as exc:  # pragma: no cover - defensive guard
+                logger.warning("Failed to initialize persistent cache schema: %s", exc)
+
+    def _ensure_additional_model_columns(self, conn: sqlite3.Connection) -> None:
+        try:
+            existing_columns = {
+                row["name"]
+                for row in conn.execute("PRAGMA table_info(models)").fetchall()
+            }
+        except Exception:  # pragma: no cover - defensive guard
+            return
+
+        required_columns = {
+            "metadata_source": "TEXT",
+            "civitai_creator_username": "TEXT",
+            "civitai_deleted": "INTEGER DEFAULT 0",
+        }
+
+        for column, definition in required_columns.items():
+            if column not in existing_columns:
+                conn.execute(f"ALTER TABLE models ADD COLUMN {column} {definition}")
+
+    def _connect(self, readonly: bool = False) -> sqlite3.Connection:
+        uri = False
+        path = self._db_path
+        if readonly:
+            if not os.path.exists(path):
+                raise FileNotFoundError(path)
+            path = f"file:{path}?mode=ro"
+            uri = True
+        conn = sqlite3.connect(path, check_same_thread=False, uri=uri, detect_types=sqlite3.PARSE_DECLTYPES)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _prepare_model_row(self, model_type: str, item: Dict) -> Tuple:
+        civitai = item.get("civitai") or {}
+        trained_words = civitai.get("trainedWords")
+        if isinstance(trained_words, str):
+            trained_words_json = trained_words
+        elif trained_words is None:
+            trained_words_json = None
+        else:
+            trained_words_json = json.dumps(trained_words)
+
+        metadata_source = item.get("metadata_source") or None
+        creator_username = None
+        creator_data = civitai.get("creator") if isinstance(civitai, dict) else None
+        if isinstance(creator_data, dict):
+            creator_username = creator_data.get("username") or None
+
+        return (
+            model_type,
+            item.get("file_path"),
+            item.get("file_name"),
+            item.get("model_name"),
+            item.get("folder"),
+            int(item.get("size") or 0),
+            float(item.get("modified") or 0.0),
+            (item.get("sha256") or "").lower() or None,
+            item.get("base_model"),
+            item.get("preview_url"),
+            int(item.get("preview_nsfw_level") or 0),
+            1 if item.get("from_civitai", True) else 0,
+            1 if item.get("favorite") else 0,
+            item.get("notes"),
+            item.get("usage_tips"),
+            metadata_source,
+            civitai.get("id"),
+            civitai.get("modelId"),
+            civitai.get("name"),
+            creator_username,
+            trained_words_json,
+            1 if item.get("civitai_deleted") else 0,
+            1 if item.get("exclude") else 0,
+            1 if item.get("db_checked") else 0,
+            float(item.get("last_checked_at") or 0.0),
+        )
+
+    def _insert_model_sql(self) -> str:
+        columns = ", ".join(self._MODEL_COLUMNS)
+        placeholders = ", ".join(["?"] * len(self._MODEL_COLUMNS))
+        return f"INSERT INTO models ({columns}) VALUES ({placeholders})"
+
+    def _load_tags(self, conn: sqlite3.Connection, model_type: str) -> Dict[str, List[str]]:
+        tag_rows = conn.execute(
+            "SELECT file_path, tag FROM model_tags WHERE model_type = ?",
+            (model_type,),
+        ).fetchall()
+        result: Dict[str, List[str]] = {}
+        for row in tag_rows:
+            result.setdefault(row["file_path"], []).append(row["tag"])
+        return result
+
+
+def get_persistent_cache() -> PersistentModelCache:
+    from .settings_manager import get_settings_manager  # Local import to avoid cycles
+
+    library_name = get_settings_manager().get_active_library_name()
+    return PersistentModelCache.get_default(library_name)

py/services/preview_asset_service.py

@@ -0,0 +1,206 @@
+"""Service for processing preview assets for models."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Awaitable, Callable, Dict, Optional, Sequence
+from urllib.parse import urlparse
+
+from ..utils.constants import CARD_PREVIEW_WIDTH, PREVIEW_EXTENSIONS
+from ..utils.civitai_utils import rewrite_preview_url
+
+logger = logging.getLogger(__name__)
+
+
+class PreviewAssetService:
+    """Manage fetching and persisting preview assets."""
+
+    def __init__(
+        self,
+        *,
+        metadata_manager,
+        downloader_factory: Callable[[], Awaitable],
+        exif_utils,
+    ) -> None:
+        self._metadata_manager = metadata_manager
+        self._downloader_factory = downloader_factory
+        self._exif_utils = exif_utils
+
+    async def ensure_preview_for_metadata(
+        self,
+        metadata_path: str,
+        local_metadata: Dict[str, object],
+        images: Sequence[Dict[str, object]] | None,
+    ) -> None:
+        """Ensure preview assets exist for the supplied metadata entry."""
+
+        if local_metadata.get("preview_url") and os.path.exists(
+            str(local_metadata["preview_url"])
+        ):
+            return
+
+        if not images:
+            return
+
+        first_preview = images[0]
+        base_name = os.path.splitext(os.path.splitext(os.path.basename(metadata_path))[0])[0]
+        preview_dir = os.path.dirname(metadata_path)
+        is_video = first_preview.get("type") == "video"
+        preview_url = first_preview.get("url")
+
+        if not preview_url:
+            return
+
+        def extension_from_url(url: str, fallback: str) -> str:
+            try:
+                parsed = urlparse(url)
+            except ValueError:
+                return fallback
+            ext = os.path.splitext(parsed.path)[1]
+            return ext or fallback
+
+        downloader = await self._downloader_factory()
+
+        if is_video:
+            extension = extension_from_url(preview_url, ".mp4")
+            preview_path = os.path.join(preview_dir, base_name + extension)
+            rewritten_url, rewritten = rewrite_preview_url(preview_url, media_type="video")
+
+            attempt_urls = []
+            if rewritten:
+                attempt_urls.append(rewritten_url)
+            attempt_urls.append(preview_url)
+
+            seen: set[str] = set()
+            for candidate in attempt_urls:
+                if not candidate or candidate in seen:
+                    continue
+                seen.add(candidate)
+
+                success, _ = await downloader.download_file(candidate, preview_path, use_auth=False)
+                if success:
+                    local_metadata["preview_url"] = preview_path.replace(os.sep, "/")
+                    local_metadata["preview_nsfw_level"] = first_preview.get("nsfwLevel", 0)
+                    return
+        else:
+            rewritten_url, rewritten = rewrite_preview_url(preview_url, media_type="image")
+            if rewritten:
+                extension = extension_from_url(preview_url, ".png")
+                preview_path = os.path.join(preview_dir, base_name + extension)
+                success, _ = await downloader.download_file(
+                    rewritten_url, preview_path, use_auth=False
+                )
+                if success:
+                    local_metadata["preview_url"] = preview_path.replace(os.sep, "/")
+                    local_metadata["preview_nsfw_level"] = first_preview.get("nsfwLevel", 0)
+                    return
+
+            extension = ".webp"
+            preview_path = os.path.join(preview_dir, base_name + extension)
+            success, content, _headers = await downloader.download_to_memory(
+                preview_url, use_auth=False
+            )
+            if not success:
+                return
+
+            try:
+                optimized_data, _ = self._exif_utils.optimize_image(
+                    image_data=content,
+                    target_width=CARD_PREVIEW_WIDTH,
+                    format="webp",
+                    quality=85,
+                    preserve_metadata=False,
+                )
+                with open(preview_path, "wb") as handle:
+                    handle.write(optimized_data)
+            except Exception as exc:  # pragma: no cover - defensive path
+                logger.error("Error optimizing preview image: %s", exc)
+                try:
+                    with open(preview_path, "wb") as handle:
+                        handle.write(content)
+                except Exception as save_exc:
+                    logger.error("Error saving preview image: %s", save_exc)
+                    return
+
+            local_metadata["preview_url"] = preview_path.replace(os.sep, "/")
+            local_metadata["preview_nsfw_level"] = first_preview.get("nsfwLevel", 0)
+
+    async def replace_preview(
+        self,
+        *,
+        model_path: str,
+        preview_data: bytes,
+        content_type: str,
+        original_filename: Optional[str],
+        nsfw_level: int,
+        update_preview_in_cache: Callable[[str, str, int], Awaitable[bool]],
+        metadata_loader: Callable[[str], Awaitable[Dict[str, object]]],
+    ) -> Dict[str, object]:
+        """Replace an existing preview asset for a model."""
+
+        base_name = os.path.splitext(os.path.basename(model_path))[0]
+        folder = os.path.dirname(model_path)
+
+        extension, optimized_data = await self._convert_preview(
+            preview_data, content_type, original_filename
+        )
+
+        for ext in PREVIEW_EXTENSIONS:
+            existing_preview = os.path.join(folder, base_name + ext)
+            if os.path.exists(existing_preview):
+                try:
+                    os.remove(existing_preview)
+                except Exception as exc:  # pragma: no cover - defensive path
+                    logger.warning(
+                        "Failed to delete existing preview %s: %s", existing_preview, exc
+                    )
+
+        preview_path = os.path.join(folder, base_name + extension).replace(os.sep, "/")
+        with open(preview_path, "wb") as handle:
+            handle.write(optimized_data)
+
+        metadata_path = os.path.splitext(model_path)[0] + ".metadata.json"
+        metadata = await metadata_loader(metadata_path)
+        metadata["preview_url"] = preview_path
+        metadata["preview_nsfw_level"] = nsfw_level
+        await self._metadata_manager.save_metadata(model_path, metadata)
+
+        await update_preview_in_cache(model_path, preview_path, nsfw_level)
+
+        return {"preview_path": preview_path, "preview_nsfw_level": nsfw_level}
+
+    async def _convert_preview(
+        self, data: bytes, content_type: str, original_filename: Optional[str]
+    ) -> tuple[str, bytes]:
+        """Convert preview bytes to the persisted representation."""
+
+        if content_type.startswith("video/"):
+            extension = self._resolve_video_extension(content_type, original_filename)
+            return extension, data
+
+        original_ext = (original_filename or "").lower()
+        if original_ext.endswith(".gif") or content_type.lower() == "image/gif":
+            return ".gif", data
+
+        optimized_data, _ = self._exif_utils.optimize_image(
+            image_data=data,
+            target_width=CARD_PREVIEW_WIDTH,
+            format="webp",
+            quality=85,
+            preserve_metadata=False,
+        )
+        return ".webp", optimized_data
+
+    def _resolve_video_extension(self, content_type: str, original_filename: Optional[str]) -> str:
+        """Infer the best extension for a video preview."""
+
+        if original_filename:
+            extension = os.path.splitext(original_filename)[1].lower()
+            if extension in {".mp4", ".webm", ".mov", ".avi"}:
+                return extension
+
+        if "webm" in content_type:
+            return ".webm"
+        return ".mp4"
+

py/services/recipe_cache.py

@@ -1,5 +1,5 @@
 import asyncio
-from typing import List, Dict
+from typing import Iterable, List, Dict, Optional
 from dataclasses import dataclass
 from operator import itemgetter
 from natsort import natsorted
@@ -10,77 +10,115 @@ class RecipeCache:
     raw_data: List[Dict]
     sorted_by_name: List[Dict]
     sorted_by_date: List[Dict]
-    
+
     def __post_init__(self):
         self._lock = asyncio.Lock()
 
     async def resort(self, name_only: bool = False):
         """Resort all cached data views"""
         async with self._lock:
-            self.sorted_by_name = natsorted(
-                self.raw_data, 
-                key=lambda x: x.get('title', '').lower()  # Case-insensitive sort
-            )
-            if not name_only:
-                self.sorted_by_date = sorted(
-                    self.raw_data, 
-                    key=itemgetter('created_date', 'file_path'), 
-                    reverse=True
-                )
-    
-    async def update_recipe_metadata(self, recipe_id: str, metadata: Dict) -> bool:
+            self._resort_locked(name_only=name_only)
+
+    async def update_recipe_metadata(self, recipe_id: str, metadata: Dict, *, resort: bool = True) -> bool:
         """Update metadata for a specific recipe in all cached data
-        
+
         Args:
             recipe_id: The ID of the recipe to update
             metadata: The new metadata
-            
+
         Returns:
             bool: True if the update was successful, False if the recipe wasn't found
         """
+        async with self._lock:
+            for item in self.raw_data:
+                if str(item.get('id')) == str(recipe_id):
+                    item.update(metadata)
+                    if resort:
+                        self._resort_locked()
+                    return True
+        return False  # Recipe not found
+
+    async def add_recipe(self, recipe_data: Dict, *, resort: bool = False) -> None:
+        """Add a new recipe to the cache."""
 
-        # Update in raw_data
-        for item in self.raw_data:
-            if item.get('id') == recipe_id:
-                item.update(metadata)
-                break
-        else:
-            return False  # Recipe not found
-            
-        # Resort to reflect changes
-        await self.resort()
-        return True
-            
-    async def add_recipe(self, recipe_data: Dict) -> None:
-        """Add a new recipe to the cache
-        
-        Args:
-            recipe_data: The recipe data to add
-        """
         async with self._lock:
             self.raw_data.append(recipe_data)
-            await self.resort() 
+            if resort:
+                self._resort_locked()
+
+    async def remove_recipe(self, recipe_id: str, *, resort: bool = False) -> Optional[Dict]:
+        """Remove a recipe from the cache by ID.
 
-    async def remove_recipe(self, recipe_id: str) -> bool:
-        """Remove a recipe from the cache by ID
-        
         Args:
             recipe_id: The ID of the recipe to remove
-            
+
         Returns:
-            bool: True if the recipe was found and removed, False otherwise
+            The removed recipe data if found, otherwise ``None``.
         """
-        # Find the recipe in raw_data
-        recipe_index = next((i for i, recipe in enumerate(self.raw_data) 
-                             if recipe.get('id') == recipe_id), None)
-        
-        if recipe_index is None:
-            return False
-        
-        # Remove from raw_data
-        self.raw_data.pop(recipe_index)
-        
-        # Resort to update sorted lists
-        await self.resort()
-        
-        return True 
+
+        async with self._lock:
+            for index, recipe in enumerate(self.raw_data):
+                if str(recipe.get('id')) == str(recipe_id):
+                    removed = self.raw_data.pop(index)
+                    if resort:
+                        self._resort_locked()
+                    return removed
+        return None
+
+    async def bulk_remove(self, recipe_ids: Iterable[str], *, resort: bool = False) -> List[Dict]:
+        """Remove multiple recipes from the cache."""
+
+        id_set = {str(recipe_id) for recipe_id in recipe_ids}
+        if not id_set:
+            return []
+
+        async with self._lock:
+            removed = [item for item in self.raw_data if str(item.get('id')) in id_set]
+            if not removed:
+                return []
+
+            self.raw_data = [item for item in self.raw_data if str(item.get('id')) not in id_set]
+            if resort:
+                self._resort_locked()
+            return removed
+
+    async def replace_recipe(self, recipe_id: str, new_data: Dict, *, resort: bool = False) -> bool:
+        """Replace cached data for a recipe."""
+
+        async with self._lock:
+            for index, recipe in enumerate(self.raw_data):
+                if str(recipe.get('id')) == str(recipe_id):
+                    self.raw_data[index] = new_data
+                    if resort:
+                        self._resort_locked()
+                    return True
+        return False
+
+    async def get_recipe(self, recipe_id: str) -> Optional[Dict]:
+        """Return a shallow copy of a cached recipe."""
+
+        async with self._lock:
+            for recipe in self.raw_data:
+                if str(recipe.get('id')) == str(recipe_id):
+                    return dict(recipe)
+        return None
+
+    async def snapshot(self) -> List[Dict]:
+        """Return a copy of all cached recipes."""
+
+        async with self._lock:
+            return [dict(item) for item in self.raw_data]
+
+    def _resort_locked(self, *, name_only: bool = False) -> None:
+        """Sort cached views. Caller must hold ``_lock``."""
+
+        self.sorted_by_name = natsorted(
+            self.raw_data,
+            key=lambda x: x.get('title', '').lower()
+        )
+        if not name_only:
+            self.sorted_by_date = sorted(
+                self.raw_data,
+                key=itemgetter('created_date', 'file_path'),
+                reverse=True
+            )

py/services/recipe_scanner.py

@@ -3,12 +3,14 @@ import logging
 import asyncio
 import json
 import time
-from typing import List, Dict, Optional, Any, Tuple
+from typing import Any, Dict, Iterable, List, Optional, Set, Tuple
 from ..config import config
 from .recipe_cache import RecipeCache
 from .service_registry import ServiceRegistry
 from .lora_scanner import LoraScanner
-from ..utils.utils import fuzzy_match
+from .metadata_service import get_default_metadata_provider
+from .recipes.errors import RecipeNotFoundError
+from ..utils.utils import calculate_recipe_fingerprint, fuzzy_match
 from natsort import natsorted
 import sys
 
@@ -45,9 +47,36 @@ class RecipeScanner:
             self._initialization_lock = asyncio.Lock()
             self._initialization_task: Optional[asyncio.Task] = None
             self._is_initializing = False
+            self._mutation_lock = asyncio.Lock()
+            self._resort_tasks: Set[asyncio.Task] = set()
             if lora_scanner:
                 self._lora_scanner = lora_scanner
             self._initialized = True
+
+    def on_library_changed(self) -> None:
+        """Reset cached state when the active library changes."""
+
+        # Cancel any in-flight initialization or resorting work so the next
+        # access rebuilds the cache for the new library.
+        if self._initialization_task and not self._initialization_task.done():
+            self._initialization_task.cancel()
+
+        for task in list(self._resort_tasks):
+            if not task.done():
+                task.cancel()
+        self._resort_tasks.clear()
+
+        self._cache = None
+        self._initialization_task = None
+        self._is_initializing = False
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop and not loop.is_closed():
+            loop.create_task(self.initialize_in_background())
     
     async def _get_civitai_client(self):
         """Lazily initialize CivitaiClient from registry"""
@@ -190,6 +219,22 @@ class RecipeScanner:
             # Clean up the event loop
             loop.close()
 
+    def _schedule_resort(self, *, name_only: bool = False) -> None:
+        """Schedule a background resort of the recipe cache."""
+
+        if not self._cache:
+            return
+
+        async def _resort_wrapper() -> None:
+            try:
+                await self._cache.resort(name_only=name_only)
+            except Exception as exc:  # pragma: no cover - defensive logging
+                logger.error("Recipe Scanner: error resorting cache: %s", exc, exc_info=True)
+
+        task = asyncio.create_task(_resort_wrapper())
+        self._resort_tasks.add(task)
+        task.add_done_callback(lambda finished: self._resort_tasks.discard(finished))
+
     @property
     def recipes_dir(self) -> str:
         """Get path to recipes directory"""
@@ -254,7 +299,45 @@ class RecipeScanner:
         
         # Return the cache (may be empty or partially initialized)
         return self._cache or RecipeCache(raw_data=[], sorted_by_name=[], sorted_by_date=[])
-    
+
+    async def refresh_cache(self, force: bool = False) -> RecipeCache:
+        """Public helper to refresh or return the recipe cache."""
+
+        return await self.get_cached_data(force_refresh=force)
+
+    async def add_recipe(self, recipe_data: Dict[str, Any]) -> None:
+        """Add a recipe to the in-memory cache."""
+
+        if not recipe_data:
+            return
+
+        cache = await self.get_cached_data()
+        await cache.add_recipe(recipe_data, resort=False)
+        self._schedule_resort()
+
+    async def remove_recipe(self, recipe_id: str) -> bool:
+        """Remove a recipe from the cache by ID."""
+
+        if not recipe_id:
+            return False
+
+        cache = await self.get_cached_data()
+        removed = await cache.remove_recipe(recipe_id, resort=False)
+        if removed is None:
+            return False
+
+        self._schedule_resort()
+        return True
+
+    async def bulk_remove(self, recipe_ids: Iterable[str]) -> int:
+        """Remove multiple recipes from the cache."""
+
+        cache = await self.get_cached_data()
+        removed = await cache.bulk_remove(recipe_ids, resort=False)
+        if removed:
+            self._schedule_resort()
+        return len(removed)
+
     async def scan_all_recipes(self) -> List[Dict]:
         """Scan all recipe JSON files and return metadata"""
         recipes = []
@@ -325,7 +408,6 @@ class RecipeScanner:
 
             # Calculate and update fingerprint if missing
             if 'loras' in recipe_data and 'fingerprint' not in recipe_data:
-                from ..utils.utils import calculate_recipe_fingerprint
                 fingerprint = calculate_recipe_fingerprint(recipe_data['loras'])
                 recipe_data['fingerprint'] = fingerprint
                 
@@ -367,27 +449,29 @@ class RecipeScanner:
             # If has modelVersionId but no hash, look in lora cache first, then fetch from Civitai
             if 'modelVersionId' in lora and not lora.get('hash'):
                 model_version_id = lora['modelVersionId']
+                # Check if model_version_id is an integer and > 0
+                if isinstance(model_version_id, int) and model_version_id > 0:
 
-                # Try to find in lora cache first
-                hash_from_cache = await self._find_hash_in_lora_cache(model_version_id)
-                if hash_from_cache:
-                    lora['hash'] = hash_from_cache
-                    metadata_updated = True
-                else:
-                    # If not in cache, fetch from Civitai
-                    result = await self._get_hash_from_civitai(model_version_id)
-                    if isinstance(result, tuple):
-                        hash_from_civitai, is_deleted = result
-                        if hash_from_civitai:
-                            lora['hash'] = hash_from_civitai
-                            metadata_updated = True
-                        elif is_deleted:
-                            # Mark the lora as deleted if it was not found on Civitai
-                            lora['isDeleted'] = True
-                            logger.warning(f"Marked lora with modelVersionId {model_version_id} as deleted")
-                            metadata_updated = True
+                    # Try to find in lora cache first
+                    hash_from_cache = await self._find_hash_in_lora_cache(model_version_id)
+                    if hash_from_cache:
+                        lora['hash'] = hash_from_cache
+                        metadata_updated = True
                     else:
-                        logger.debug(f"Could not get hash for modelVersionId {model_version_id}")
+                        # If not in cache, fetch from Civitai
+                        result = await self._get_hash_from_civitai(model_version_id)
+                        if isinstance(result, tuple):
+                            hash_from_civitai, is_deleted = result
+                            if hash_from_civitai:
+                                lora['hash'] = hash_from_civitai
+                                metadata_updated = True
+                            elif is_deleted:
+                                # Mark the lora as deleted if it was not found on Civitai
+                                lora['isDeleted'] = True
+                                logger.warning(f"Marked lora with modelVersionId {model_version_id} as deleted")
+                                metadata_updated = True
+                        else:
+                            logger.debug(f"Could not get hash for modelVersionId {model_version_id}")
             
             # If has hash but no file_name, look up in lora library
             if 'hash' in lora and (not lora.get('file_name') or not lora['file_name']):
@@ -431,13 +515,13 @@ class RecipeScanner:
     async def _get_hash_from_civitai(self, model_version_id: str) -> Optional[str]:
         """Get hash from Civitai API"""
         try:
-            # Get CivitaiClient from ServiceRegistry
-            civitai_client = await self._get_civitai_client()
-            if not civitai_client:
-                logger.error("Failed to get CivitaiClient from ServiceRegistry")
+            # Get metadata provider instead of civitai client directly
+            metadata_provider = await get_default_metadata_provider()
+            if not metadata_provider:
+                logger.error("Failed to get metadata provider")
                 return None
                 
-            version_info, error_msg = await civitai_client.get_model_version_info(model_version_id)
+            version_info, error_msg = await metadata_provider.get_model_version_info(model_version_id)
             
             if not version_info:
                 if error_msg and "model not found" in error_msg.lower():
@@ -496,9 +580,36 @@ class RecipeScanner:
             logger.error(f"Error getting base model for lora: {e}")
             return None
 
+    def _enrich_lora_entry(self, lora: Dict[str, Any]) -> Dict[str, Any]:
+        """Populate convenience fields for a LoRA entry."""
+
+        if not lora or not self._lora_scanner:
+            return lora
+
+        hash_value = (lora.get('hash') or '').lower()
+        if not hash_value:
+            return lora
+
+        try:
+            lora['inLibrary'] = self._lora_scanner.has_hash(hash_value)
+            lora['preview_url'] = self._lora_scanner.get_preview_url_by_hash(hash_value)
+            lora['localPath'] = self._lora_scanner.get_path_by_hash(hash_value)
+        except Exception as exc:  # pragma: no cover - defensive logging
+            logger.debug("Error enriching lora entry %s: %s", hash_value, exc)
+
+        return lora
+
+    async def get_local_lora(self, name: str) -> Optional[Dict[str, Any]]:
+        """Lookup a local LoRA model by name."""
+
+        if not self._lora_scanner or not name:
+            return None
+
+        return await self._lora_scanner.get_model_info_by_name(name)
+
     async def get_paginated_data(self, page: int, page_size: int, sort_by: str = 'date', search: str = None, filters: dict = None, search_options: dict = None, lora_hash: str = None, bypass_filters: bool = True):
         """Get paginated and filtered recipe data
-        
+
         Args:
             page: Current page number (1-based)
             page_size: Number of items per page
@@ -597,16 +708,12 @@ class RecipeScanner:
         
         # Get paginated items
         paginated_items = filtered_data[start_idx:end_idx]
-        
+
         # Add inLibrary information for each lora
         for item in paginated_items:
             if 'loras' in item:
-                for lora in item['loras']:
-                    if 'hash' in lora and lora['hash']:
-                        lora['inLibrary'] = self._lora_scanner.has_hash(lora['hash'].lower())
-                        lora['preview_url'] = self._lora_scanner.get_preview_url_by_hash(lora['hash'].lower())
-                        lora['localPath'] = self._lora_scanner.get_path_by_hash(lora['hash'].lower())
-        
+                item['loras'] = [self._enrich_lora_entry(dict(lora)) for lora in item['loras']]
+
         result = {
             'items': paginated_items,
             'total': total_items,
@@ -652,33 +759,25 @@ class RecipeScanner:
                 
         # Add lora metadata
         if 'loras' in formatted_recipe:
-            for lora in formatted_recipe['loras']:
-                if 'hash' in lora and lora['hash']:
-                    lora_hash = lora['hash'].lower()
-                    lora['inLibrary'] = self._lora_scanner.has_hash(lora_hash)
-                    lora['preview_url'] = self._lora_scanner.get_preview_url_by_hash(lora_hash)
-                    lora['localPath'] = self._lora_scanner.get_path_by_hash(lora_hash)
-                    
+            formatted_recipe['loras'] = [self._enrich_lora_entry(dict(lora)) for lora in formatted_recipe['loras']]
+
         return formatted_recipe
         
     def _format_file_url(self, file_path: str) -> str:
         """Format file path as URL for serving in web UI"""
         if not file_path:
             return '/loras_static/images/no-preview.png'
-            
+
         try:
-            # Format file path as a URL that will work with static file serving
-            recipes_dir = os.path.join(config.loras_roots[0], "recipes").replace(os.sep, '/')
-            if file_path.replace(os.sep, '/').startswith(recipes_dir):
-                relative_path = os.path.relpath(file_path, config.loras_roots[0]).replace(os.sep, '/')
-                return f"/loras_static/root1/preview/{relative_path}"
-                
-            # If not in recipes dir, try to create a valid URL from the file name
-            file_name = os.path.basename(file_path)
-            return f"/loras_static/root1/preview/recipes/{file_name}"
+            normalized_path = os.path.normpath(file_path)
+            static_url = config.get_preview_static_url(normalized_path)
+            if static_url:
+                return static_url
         except Exception as e:
             logger.error(f"Error formatting file URL: {e}")
             return '/loras_static/images/no-preview.png'
+
+        return '/loras_static/images/no-preview.png'
     
     def _format_timestamp(self, timestamp: float) -> str:
         """Format timestamp for display"""
@@ -716,26 +815,159 @@ class RecipeScanner:
             # Save updated recipe
             with open(recipe_json_path, 'w', encoding='utf-8') as f:
                 json.dump(recipe_data, f, indent=4, ensure_ascii=False)
-                
+
             # Update the cache if it exists
             if self._cache is not None:
-                await self._cache.update_recipe_metadata(recipe_id, metadata)
-                
+                await self._cache.update_recipe_metadata(recipe_id, metadata, resort=False)
+                self._schedule_resort()
+
             # If the recipe has an image, update its EXIF metadata
             from ..utils.exif_utils import ExifUtils
             image_path = recipe_data.get('file_path')
             if image_path and os.path.exists(image_path):
                 ExifUtils.append_recipe_metadata(image_path, recipe_data)
-                
+
             return True
         except Exception as e:
             import logging
             logging.getLogger(__name__).error(f"Error updating recipe metadata: {e}", exc_info=True)
             return False
 
+    async def update_lora_entry(
+        self,
+        recipe_id: str,
+        lora_index: int,
+        *,
+        target_name: str,
+        target_lora: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        """Update a specific LoRA entry within a recipe.
+
+        Returns the updated recipe data and the refreshed LoRA metadata.
+        """
+
+        if target_name is None:
+            raise ValueError("target_name must be provided")
+
+        recipe_json_path = os.path.join(self.recipes_dir, f"{recipe_id}.recipe.json")
+        if not os.path.exists(recipe_json_path):
+            raise RecipeNotFoundError("Recipe not found")
+
+        async with self._mutation_lock:
+            with open(recipe_json_path, 'r', encoding='utf-8') as file_obj:
+                recipe_data = json.load(file_obj)
+
+            loras = recipe_data.get('loras', [])
+            if lora_index >= len(loras):
+                raise RecipeNotFoundError("LoRA index out of range in recipe")
+
+            lora_entry = loras[lora_index]
+            lora_entry['isDeleted'] = False
+            lora_entry['exclude'] = False
+            lora_entry['file_name'] = target_name
+
+            if target_lora is not None:
+                sha_value = target_lora.get('sha256') or target_lora.get('sha')
+                if sha_value:
+                    lora_entry['hash'] = sha_value.lower()
+
+                civitai_info = target_lora.get('civitai') or {}
+                if civitai_info:
+                    lora_entry['modelName'] = civitai_info.get('model', {}).get('name', '')
+                    lora_entry['modelVersionName'] = civitai_info.get('name', '')
+                    lora_entry['modelVersionId'] = civitai_info.get('id')
+
+            recipe_data['fingerprint'] = calculate_recipe_fingerprint(recipe_data.get('loras', []))
+            recipe_data['modified'] = time.time()
+
+            with open(recipe_json_path, 'w', encoding='utf-8') as file_obj:
+                json.dump(recipe_data, file_obj, indent=4, ensure_ascii=False)
+
+        cache = await self.get_cached_data()
+        replaced = await cache.replace_recipe(recipe_id, recipe_data, resort=False)
+        if not replaced:
+            await cache.add_recipe(recipe_data, resort=False)
+        self._schedule_resort()
+
+        updated_lora = dict(lora_entry)
+        if target_lora is not None:
+            preview_url = target_lora.get('preview_url')
+            if preview_url:
+                updated_lora['preview_url'] = config.get_preview_static_url(preview_url)
+            if target_lora.get('file_path'):
+                updated_lora['localPath'] = target_lora['file_path']
+
+        updated_lora = self._enrich_lora_entry(updated_lora)
+        return recipe_data, updated_lora
+
+    async def get_recipes_for_lora(self, lora_hash: str) -> List[Dict[str, Any]]:
+        """Return recipes that reference a given LoRA hash."""
+
+        if not lora_hash:
+            return []
+
+        normalized_hash = lora_hash.lower()
+        cache = await self.get_cached_data()
+        matching_recipes: List[Dict[str, Any]] = []
+
+        for recipe in cache.raw_data:
+            loras = recipe.get('loras', [])
+            if any((entry.get('hash') or '').lower() == normalized_hash for entry in loras):
+                recipe_copy = {**recipe}
+                recipe_copy['loras'] = [self._enrich_lora_entry(dict(entry)) for entry in loras]
+                recipe_copy['file_url'] = self._format_file_url(recipe.get('file_path'))
+                matching_recipes.append(recipe_copy)
+
+        return matching_recipes
+
+    async def get_recipe_syntax_tokens(self, recipe_id: str) -> List[str]:
+        """Build LoRA syntax tokens for a recipe."""
+
+        cache = await self.get_cached_data()
+        recipe = await cache.get_recipe(recipe_id)
+        if recipe is None:
+            raise RecipeNotFoundError("Recipe not found")
+
+        loras = recipe.get('loras', [])
+        if not loras:
+            return []
+
+        lora_cache = None
+        if self._lora_scanner is not None:
+            lora_cache = await self._lora_scanner.get_cached_data()
+
+        syntax_parts: List[str] = []
+        for lora in loras:
+            if lora.get('isDeleted', False):
+                continue
+
+            file_name = None
+            hash_value = (lora.get('hash') or '').lower()
+            if hash_value and self._lora_scanner is not None and hasattr(self._lora_scanner, '_hash_index'):
+                file_path = self._lora_scanner._hash_index.get_path(hash_value)
+                if file_path:
+                    file_name = os.path.splitext(os.path.basename(file_path))[0]
+
+            if not file_name and lora.get('modelVersionId') and lora_cache is not None:
+                for cached_lora in getattr(lora_cache, 'raw_data', []):
+                    civitai_info = cached_lora.get('civitai')
+                    if civitai_info and civitai_info.get('id') == lora.get('modelVersionId'):
+                        cached_path = cached_lora.get('path') or cached_lora.get('file_path')
+                        if cached_path:
+                            file_name = os.path.splitext(os.path.basename(cached_path))[0]
+                        break
+
+            if not file_name:
+                file_name = lora.get('file_name', 'unknown-lora')
+
+            strength = lora.get('strength', 1.0)
+            syntax_parts.append(f"<lora:{file_name}:{strength}>")
+
+        return syntax_parts
+
     async def update_lora_filename_by_hash(self, hash_value: str, new_file_name: str) -> Tuple[int, int]:
         """Update file_name in all recipes that contain a LoRA with the specified hash.
-        
+
         Args:
             hash_value: The SHA256 hash value of the LoRA
             new_file_name: The new file_name to set

py/services/recipes/__init__.py

@@ -0,0 +1,23 @@
+"""Recipe service layer implementations."""
+
+from .analysis_service import RecipeAnalysisService
+from .persistence_service import RecipePersistenceService
+from .sharing_service import RecipeSharingService
+from .errors import (
+    RecipeServiceError,
+    RecipeValidationError,
+    RecipeNotFoundError,
+    RecipeDownloadError,
+    RecipeConflictError,
+)
+
+__all__ = [
+    "RecipeAnalysisService",
+    "RecipePersistenceService",
+    "RecipeSharingService",
+    "RecipeServiceError",
+    "RecipeValidationError",
+    "RecipeNotFoundError",
+    "RecipeDownloadError",
+    "RecipeConflictError",
+]

py/services/recipes/analysis_service.py

@@ -0,0 +1,289 @@
+"""Services responsible for recipe metadata analysis."""
+from __future__ import annotations
+
+import base64
+import io
+import os
+import re
+import tempfile
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+import numpy as np
+from PIL import Image
+
+from ...utils.utils import calculate_recipe_fingerprint
+from .errors import (
+    RecipeDownloadError,
+    RecipeNotFoundError,
+    RecipeServiceError,
+    RecipeValidationError,
+)
+
+
+@dataclass(frozen=True)
+class AnalysisResult:
+    """Return payload from analysis operations."""
+
+    payload: dict[str, Any]
+    status: int = 200
+
+
+class RecipeAnalysisService:
+    """Extract recipe metadata from various image sources."""
+
+    def __init__(
+        self,
+        *,
+        exif_utils,
+        recipe_parser_factory,
+        downloader_factory: Callable[[], Any],
+        metadata_collector: Optional[Callable[[], Any]] = None,
+        metadata_processor_cls: Optional[type] = None,
+        metadata_registry_cls: Optional[type] = None,
+        standalone_mode: bool = False,
+        logger,
+    ) -> None:
+        self._exif_utils = exif_utils
+        self._recipe_parser_factory = recipe_parser_factory
+        self._downloader_factory = downloader_factory
+        self._metadata_collector = metadata_collector
+        self._metadata_processor_cls = metadata_processor_cls
+        self._metadata_registry_cls = metadata_registry_cls
+        self._standalone_mode = standalone_mode
+        self._logger = logger
+
+    async def analyze_uploaded_image(
+        self,
+        *,
+        image_bytes: bytes | None,
+        recipe_scanner,
+    ) -> AnalysisResult:
+        """Analyze an uploaded image payload."""
+
+        if not image_bytes:
+            raise RecipeValidationError("No image data provided")
+
+        temp_path = self._write_temp_file(image_bytes)
+        try:
+            metadata = self._exif_utils.extract_image_metadata(temp_path)
+            if not metadata:
+                return AnalysisResult({"error": "No metadata found in this image", "loras": []})
+
+            return await self._parse_metadata(
+                metadata,
+                recipe_scanner=recipe_scanner,
+                image_path=None,
+                include_image_base64=False,
+            )
+        finally:
+            self._safe_cleanup(temp_path)
+
+    async def analyze_remote_image(
+        self,
+        *,
+        url: str | None,
+        recipe_scanner,
+        civitai_client,
+    ) -> AnalysisResult:
+        """Analyze an image accessible via URL, including Civitai integration."""
+
+        if not url:
+            raise RecipeValidationError("No URL provided")
+
+        if civitai_client is None:
+            raise RecipeServiceError("Civitai client unavailable")
+
+        temp_path = self._create_temp_path()
+        metadata: Optional[dict[str, Any]] = None
+        try:
+            civitai_match = re.match(r"https://civitai\.com/images/(\d+)", url)
+            if civitai_match:
+                image_info = await civitai_client.get_image_info(civitai_match.group(1))
+                if not image_info:
+                    raise RecipeDownloadError("Failed to fetch image information from Civitai")
+                image_url = image_info.get("url")
+                if not image_url:
+                    raise RecipeDownloadError("No image URL found in Civitai response")
+                await self._download_image(image_url, temp_path)
+                metadata = image_info.get("meta") if "meta" in image_info else None
+            else:
+                await self._download_image(url, temp_path)
+
+            if metadata is None:
+                metadata = self._exif_utils.extract_image_metadata(temp_path)
+
+            if not metadata:
+                return self._metadata_not_found_response(temp_path)
+
+            return await self._parse_metadata(
+                metadata,
+                recipe_scanner=recipe_scanner,
+                image_path=temp_path,
+                include_image_base64=True,
+            )
+        finally:
+            self._safe_cleanup(temp_path)
+
+    async def analyze_local_image(
+        self,
+        *,
+        file_path: str | None,
+        recipe_scanner,
+    ) -> AnalysisResult:
+        """Analyze a file already present on disk."""
+
+        if not file_path:
+            raise RecipeValidationError("No file path provided")
+
+        normalized_path = os.path.normpath(file_path.strip('"').strip("'"))
+        if not os.path.isfile(normalized_path):
+            raise RecipeNotFoundError("File not found")
+
+        metadata = self._exif_utils.extract_image_metadata(normalized_path)
+        if not metadata:
+            return self._metadata_not_found_response(normalized_path)
+
+        return await self._parse_metadata(
+            metadata,
+            recipe_scanner=recipe_scanner,
+            image_path=normalized_path,
+            include_image_base64=True,
+        )
+
+    async def analyze_widget_metadata(self, *, recipe_scanner) -> AnalysisResult:
+        """Analyse the most recent generation metadata for widget saves."""
+
+        if self._metadata_collector is None or self._metadata_processor_cls is None:
+            raise RecipeValidationError("Metadata collection not available")
+
+        raw_metadata = self._metadata_collector()
+        metadata_dict = self._metadata_processor_cls.to_dict(raw_metadata)
+        if not metadata_dict:
+            raise RecipeValidationError("No generation metadata found")
+
+        latest_image = None
+        if not self._standalone_mode and self._metadata_registry_cls is not None:
+            metadata_registry = self._metadata_registry_cls()
+            latest_image = metadata_registry.get_first_decoded_image()
+
+        if latest_image is None:
+            raise RecipeValidationError(
+                "No recent images found to use for recipe. Try generating an image first."
+            )
+
+        image_bytes = self._convert_tensor_to_png_bytes(latest_image)
+        if image_bytes is None:
+            raise RecipeValidationError("Cannot handle this data shape from metadata registry")
+
+        return AnalysisResult(
+            {
+                "metadata": metadata_dict,
+                "image_bytes": image_bytes,
+            }
+        )
+
+    # Internal helpers -------------------------------------------------
+
+    async def _parse_metadata(
+        self,
+        metadata: dict[str, Any],
+        *,
+        recipe_scanner,
+        image_path: Optional[str],
+        include_image_base64: bool,
+    ) -> AnalysisResult:
+        parser = self._recipe_parser_factory.create_parser(metadata)
+        if parser is None:
+            payload = {"error": "No parser found for this image", "loras": []}
+            if include_image_base64 and image_path:
+                payload["image_base64"] = self._encode_file(image_path)
+            return AnalysisResult(payload)
+
+        result = await parser.parse_metadata(metadata, recipe_scanner=recipe_scanner)
+
+        if include_image_base64 and image_path:
+            result["image_base64"] = self._encode_file(image_path)
+
+        if "error" in result and not result.get("loras"):
+            return AnalysisResult(result)
+
+        fingerprint = calculate_recipe_fingerprint(result.get("loras", []))
+        result["fingerprint"] = fingerprint
+
+        matching_recipes: list[str] = []
+        if fingerprint:
+            matching_recipes = await recipe_scanner.find_recipes_by_fingerprint(fingerprint)
+        result["matching_recipes"] = matching_recipes
+
+        return AnalysisResult(result)
+
+    async def _download_image(self, url: str, temp_path: str) -> None:
+        downloader = await self._downloader_factory()
+        success, result = await downloader.download_file(url, temp_path, use_auth=False)
+        if not success:
+            raise RecipeDownloadError(f"Failed to download image from URL: {result}")
+
+    def _metadata_not_found_response(self, path: str) -> AnalysisResult:
+        payload: dict[str, Any] = {"error": "No metadata found in this image", "loras": []}
+        if os.path.exists(path):
+            payload["image_base64"] = self._encode_file(path)
+        return AnalysisResult(payload)
+
+    def _write_temp_file(self, data: bytes) -> str:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".jpg") as temp_file:
+            temp_file.write(data)
+            return temp_file.name
+
+    def _create_temp_path(self) -> str:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".jpg") as temp_file:
+            return temp_file.name
+
+    def _safe_cleanup(self, path: Optional[str]) -> None:
+        if path and os.path.exists(path):
+            try:
+                os.unlink(path)
+            except Exception as exc:  # pragma: no cover - defensive logging
+                self._logger.error("Error deleting temporary file: %s", exc)
+
+    def _encode_file(self, path: str) -> str:
+        with open(path, "rb") as image_file:
+            return base64.b64encode(image_file.read()).decode("utf-8")
+
+    def _convert_tensor_to_png_bytes(self, latest_image: Any) -> Optional[bytes]:
+        try:
+            if isinstance(latest_image, tuple):
+                tensor_image = latest_image[0] if latest_image else None
+                if tensor_image is None:
+                    return None
+            else:
+                tensor_image = latest_image
+
+            if hasattr(tensor_image, "shape"):
+                self._logger.debug(
+                    "Tensor shape: %s, dtype: %s", tensor_image.shape, getattr(tensor_image, "dtype", None)
+                )
+
+            import torch  # type: ignore[import-not-found]
+
+            if isinstance(tensor_image, torch.Tensor):
+                image_np = tensor_image.cpu().numpy()
+            else:
+                image_np = np.array(tensor_image)
+
+            while len(image_np.shape) > 3:
+                image_np = image_np[0]
+
+            if image_np.dtype in (np.float32, np.float64) and image_np.max() <= 1.0:
+                image_np = (image_np * 255).astype(np.uint8)
+
+            if len(image_np.shape) == 3 and image_np.shape[2] == 3:
+                pil_image = Image.fromarray(image_np)
+                img_byte_arr = io.BytesIO()
+                pil_image.save(img_byte_arr, format="PNG")
+                return img_byte_arr.getvalue()
+        except Exception as exc:  # pragma: no cover - defensive logging path
+            self._logger.error("Error processing image data: %s", exc, exc_info=True)
+            return None
+
+        return None

py/services/recipes/errors.py

@@ -0,0 +1,22 @@
+"""Shared exceptions for recipe services."""
+from __future__ import annotations
+
+
+class RecipeServiceError(Exception):
+    """Base exception for recipe service failures."""
+
+
+class RecipeValidationError(RecipeServiceError):
+    """Raised when a request payload fails validation."""
+
+
+class RecipeNotFoundError(RecipeServiceError):
+    """Raised when a recipe resource cannot be located."""
+
+
+class RecipeDownloadError(RecipeServiceError):
+    """Raised when remote recipe assets cannot be downloaded."""
+
+
+class RecipeConflictError(RecipeServiceError):
+    """Raised when a conflicting recipe state is detected."""