feat(settings): filename templates for download and bulk rename (#1071)

Add per-model-type filename templates ({model_name}, {version_name},
{base_model}, {author}, {first_tag}, {hash_short}, {original_name}) so
downloaded files get informative names instead of e.g. V1.safetensors.
Empty template keeps the current filename (opt-in, off by default).

- apply template automatically after downloads; rename conflicts keep
  the original name and never fail the download
- record original_file_name in metadata on rename for traceability
- bulk apply via GET|POST /api/lm/{prefix}/apply-filename-template with
  WebSocket progress, sharing the auto-organize lock
- settings UI lives in the new Organization tab with validation, live
  preview, and per-type 'apply to library' actions

py/routes/base_model_routes.py

@@ -24,9 +24,11 @@ from ..services.use_cases import (
     AutoOrganizeUseCase,
     BulkMetadataRefreshUseCase,
     DownloadModelUseCase,
+    FilenameTemplateUseCase,
 )
 from ..services.websocket_progress_callback import (
     WebSocketBroadcastCallback,
+    WebSocketFilenameTemplateProgressCallback,
     WebSocketProgressCallback,
 )
 from ..utils.exif_utils import ExifUtils
@@ -37,6 +39,7 @@ from .handlers.model_handlers import (
     ModelAutoOrganizeHandler,
     ModelCivitaiHandler,
     ModelDownloadHandler,
+    ModelFilenameTemplateHandler,
     ModelHandlerSet,
     ModelListingHandler,
     ModelManagementHandler,
@@ -83,6 +86,9 @@ class BaseModelRoutes(ABC):
         self.model_lifecycle_service: ModelLifecycleService | None = None
         self.websocket_progress_callback = WebSocketProgressCallback()
         self.metadata_progress_callback = WebSocketBroadcastCallback()
+        self.filename_template_progress_callback = (
+            WebSocketFilenameTemplateProgressCallback()
+        )
 
         self._handler_set: ModelHandlerSet | None = None
         self._handler_mapping: Dict[str, Callable[[web.Request], Awaitable[web.Response]]] | None = None
@@ -202,6 +208,17 @@ class BaseModelRoutes(ABC):
             ws_manager=self._ws_manager,
             logger=logger,
         )
+        filename_template_use_case = FilenameTemplateUseCase(
+            scanner=service.scanner,
+            lifecycle_service=self._ensure_lifecycle_service(),
+            lock_provider=self._ws_manager,
+            model_type=service.model_type,
+        )
+        filename_template = ModelFilenameTemplateHandler(
+            use_case=filename_template_use_case,
+            progress_callback=self.filename_template_progress_callback,
+            logger=logger,
+        )
         updates = ModelUpdateHandler(
             service=service,
             update_service=update_service,
@@ -218,6 +235,7 @@ class BaseModelRoutes(ABC):
             civitai=civitai,
             move=move,
             auto_organize=auto_organize,
+            filename_template=filename_template,
             updates=updates,
         )
 

py/routes/handlers/model_handlers.py

@@ -37,10 +37,14 @@ from ...services.use_cases import (
     DownloadModelEarlyAccessError,
     DownloadModelUseCase,
     DownloadModelValidationError,
+    FilenameTemplateUseCase,
     MetadataRefreshProgressReporter,
 )
 from ...services.websocket_manager import WebSocketManager
-from ...services.websocket_progress_callback import WebSocketProgressCallback
+from ...services.websocket_progress_callback import (
+    WebSocketFilenameTemplateProgressCallback,
+    WebSocketProgressCallback,
+)
 from ...services.download_queue_service import DownloadQueueService
 from ...services.errors import RateLimitError, ResourceNotFoundError
 from ...utils.civitai_utils import resolve_license_payload
@@ -2692,6 +2696,71 @@ class ModelAutoOrganizeHandler:
             return web.json_response({"success": False, "error": str(exc)}, status=500)
 
 
+class ModelFilenameTemplateHandler:
+    """Apply the configured filename template to existing library models."""
+
+    def __init__(
+        self,
+        *,
+        use_case: FilenameTemplateUseCase,
+        progress_callback: WebSocketFilenameTemplateProgressCallback,
+        logger: logging.Logger,
+    ) -> None:
+        self._use_case = use_case
+        self._progress_callback = progress_callback
+        self._logger = logger
+
+    async def apply_filename_template(self, request: web.Request) -> web.Response:
+        try:
+            file_paths = None
+            if request.method == "POST":
+                try:
+                    data = await request.json()
+                    file_paths = data.get("file_paths")
+                except Exception:  # pragma: no cover - permissive path
+                    pass
+            else:
+                # GET variant (browser extension is GET-only): comma-separated
+                # file_paths query parameter.
+                raw_file_paths = request.query.get("file_paths")
+                if raw_file_paths:
+                    file_paths = [
+                        path.strip()
+                        for path in raw_file_paths.split(",")
+                        if path.strip()
+                    ]
+
+            result = await self._use_case.execute(
+                file_paths=file_paths,
+                progress_callback=self._progress_callback,
+            )
+            _broadcast_models_changed()
+            return web.json_response(result.to_dict())
+        except AutoOrganizeInProgressError:
+            return web.json_response(
+                {
+                    "success": False,
+                    "error": "Another library operation is already running. Please wait for it to complete.",
+                },
+                status=409,
+            )
+        except Exception as exc:
+            self._logger.error(
+                "Error in apply_filename_template: %s", exc, exc_info=True
+            )
+            try:
+                await self._progress_callback.on_progress(
+                    {
+                        "type": "filename_template_progress",
+                        "status": "error",
+                        "error": str(exc),
+                    }
+                )
+            except Exception:  # pragma: no cover - defensive reporting
+                pass
+            return web.json_response({"success": False, "error": str(exc)}, status=500)
+
+
 class ModelUpdateHandler:
     """Handle update tracking requests."""
 
@@ -3459,6 +3528,7 @@ class ModelHandlerSet:
     civitai: ModelCivitaiHandler
     move: ModelMoveHandler
     auto_organize: ModelAutoOrganizeHandler
+    filename_template: ModelFilenameTemplateHandler
     updates: ModelUpdateHandler
 
     def to_route_mapping(
@@ -3523,6 +3593,7 @@ class ModelHandlerSet:
             "rename_folder": self.move.rename_folder,
             "auto_organize_models": self.auto_organize.auto_organize_models,
             "get_auto_organize_progress": self.auto_organize.get_auto_organize_progress,
+            "apply_filename_template": self.filename_template.apply_filename_template,
             "get_model_notes": self.query.get_model_notes,
             "get_model_preview_url": self.query.get_model_preview_url,
             "get_model_civitai_url": self.query.get_model_civitai_url,

py/routes/model_route_registrar.py

@@ -48,6 +48,12 @@ COMMON_ROUTE_DEFINITIONS: tuple[RouteDefinition, ...] = (
     RouteDefinition(
         "GET", "/api/lm/{prefix}/auto-organize-progress", "get_auto_organize_progress"
     ),
+    RouteDefinition(
+        "GET", "/api/lm/{prefix}/apply-filename-template", "apply_filename_template"
+    ),
+    RouteDefinition(
+        "POST", "/api/lm/{prefix}/apply-filename-template", "apply_filename_template"
+    ),
     RouteDefinition("GET", "/api/lm/{prefix}/top-tags", "get_top_tags"),
     RouteDefinition("GET", "/api/lm/{prefix}/search-tags", "search_tags"),
     RouteDefinition("GET", "/api/lm/{prefix}/base-models", "get_base_models"),

py/services/download_manager.py

@@ -33,7 +33,7 @@ from ..utils.constants import (
 from ..utils.civitai_utils import normalize_civitai_download_url, rewrite_preview_url
 from ..utils.file_utils import calculate_sha256, calculate_autov3
 from ..utils.preview_selection import resolve_mature_threshold, select_preview_media
-from ..utils.utils import sanitize_folder_name
+from ..utils.utils import calculate_filename_for_model, sanitize_folder_name
 from ..utils.exif_utils import ExifUtils
 from ..utils.metadata_manager import MetadataManager
 from .service_registry import ServiceRegistry
@@ -45,6 +45,7 @@ from .errors import RateLimitError
 from .aria2_downloader import Aria2Error, get_aria2_downloader
 from .aria2_transfer_state import Aria2TransferStateStore
 from .download_queue_service import DownloadQueueService
+from .model_lifecycle_service import ModelLifecycleService, load_local_metadata
 
 # Download to temporary file first
 import tempfile
@@ -2746,6 +2747,7 @@ class DownloadManager:
                 else None
             )
 
+            downloaded_metadata: List[Dict[str, Any]] = []
             for index, entry in enumerate(metadata_entries):
                 file_path_for_adjust = getattr(
                     entry, "file_path", actual_file_paths[index]
@@ -2788,6 +2790,15 @@ class DownloadManager:
                 if scanner is not None:
                     await scanner.add_model_to_cache(metadata_dict, relative_path)
 
+                downloaded_metadata.append(metadata_dict)
+
+            await self._apply_download_filename_template(
+                scanner=scanner,
+                model_type=model_type,
+                downloaded_metadata=downloaded_metadata,
+                download_id=download_id,
+            )
+
             if transfer_backend == "aria2" and download_id:
                 await self._aria2_state_store.remove(download_id)
 
@@ -2827,6 +2838,83 @@ class DownloadManager:
 
             return {"success": False, "error": str(e)}
 
+    async def _apply_download_filename_template(
+        self,
+        *,
+        scanner,
+        model_type: str,
+        downloaded_metadata: List[Dict[str, Any]],
+        download_id: Optional[str],
+    ) -> None:
+        """Rename freshly downloaded models according to the filename template.
+
+        Best-effort post-download step: any failure (including name conflicts)
+        is logged and skipped so a successful download is never turned into a
+        failure by a rename problem.
+        """
+        try:
+            if scanner is None or not downloaded_metadata:
+                return
+
+            template = get_settings_manager().get_download_filename_template(
+                model_type
+            )
+            if not template:
+                return
+
+            lifecycle_service = ModelLifecycleService(
+                scanner=scanner,
+                metadata_manager=MetadataManager,
+                metadata_loader=load_local_metadata,
+                recipe_scanner_factory=ServiceRegistry.get_recipe_scanner,
+            )
+
+            for metadata_dict in downloaded_metadata:
+                file_path = metadata_dict.get("file_path")
+                if not isinstance(file_path, str) or not file_path:
+                    continue
+
+                new_stem = calculate_filename_for_model(metadata_dict, model_type)
+                if not new_stem:
+                    continue
+
+                current_stem = os.path.splitext(os.path.basename(file_path))[0]
+                if new_stem == current_stem or os.path.normcase(
+                    new_stem
+                ) == os.path.normcase(current_stem):
+                    continue
+
+                try:
+                    result = await lifecycle_service.rename_model(
+                        file_path=file_path, new_file_name=new_stem
+                    )
+                except ValueError as exc:
+                    logger.warning(
+                        "Keeping original filename for %s: %s", file_path, exc
+                    )
+                    continue
+
+                new_file_path = result.get("new_file_path")
+                if download_id and isinstance(new_file_path, str):
+                    info = self._active_downloads.get(download_id)
+                    if info is None:
+                        continue
+                    if info.get("file_path") == file_path:
+                        info["file_path"] = new_file_path
+                    extracted = info.get("extracted_paths")
+                    if isinstance(extracted, list):
+                        info["extracted_paths"] = [
+                            new_file_path if path == file_path else path
+                            for path in extracted
+                        ]
+        except Exception as exc:  # Rename phase must never fail the download
+            logger.warning(
+                "Filename template rename failed for %s download: %s",
+                model_type,
+                exc,
+                exc_info=True,
+            )
+
     def _get_supported_extensions_for_type(self, model_type: str) -> Set[str]:
         if model_type in ("checkpoint", "other"):
             return {

py/services/model_file_service.py

@@ -43,10 +43,22 @@ class AutoOrganizeResult:
     
     def to_dict(self) -> Dict[str, Any]:
         """Convert result to dictionary"""
+        if self.operation_type == 'filename_template':
+            message = (
+                f'Filename template applied: {self.success_count} renamed, '
+                f'{self.skipped_count} skipped, {self.failure_count} failed '
+                f'out of {self.total} total'
+            )
+        else:
+            message = (
+                f'Auto-organize {self.operation_type} completed: '
+                f'{self.success_count} moved, {self.skipped_count} skipped, '
+                f'{self.failure_count} failed out of {self.total} total'
+            )
         result: Dict[str, Any] = {
             'success': self.status != 'error',
             'status': self.status,
-            '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',
+            'message': message,
             'summary': {
                 'total': self.total,
                 'success': self.success_count,

py/services/model_lifecycle_service.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import logging
 import os
 from typing import Any, Awaitable, Callable, Dict, Iterable, List, Mapping, Optional, TYPE_CHECKING, cast
@@ -17,6 +18,26 @@ if TYPE_CHECKING:
     from ..services.model_update_service import ModelUpdateService
 
 
+async def load_local_metadata(metadata_path: str) -> Dict[str, Any]:
+    """Load a metadata sidecar JSON, returning an empty dict when missing.
+
+    Thin equivalent of ``MetadataSyncService.load_local_metadata`` for callers
+    (download manager, use cases) that do not hold a sync-service instance.
+    """
+
+    if not os.path.exists(metadata_path):
+        return {}
+
+    try:
+        with open(metadata_path, "r", encoding="utf-8") as handle:
+            payload = json.load(handle)
+    except Exception as exc:
+        logger.warning("Failed to load metadata from %s: %s", metadata_path, exc)
+        return {}
+
+    return payload if isinstance(payload, dict) else {}
+
+
 async def delete_model_artifacts(
     target_dir: str, file_name: str, main_extension: str | None = None
 ) -> List[str]:
@@ -404,6 +425,9 @@ class ModelLifecycleService:
         if metadata and new_metadata_path:
             metadata["file_name"] = new_file_name
             metadata["file_path"] = new_file_path
+            # Preserve the pre-rename stem so the original download filename
+            # stays recoverable after template-driven renames.
+            metadata.setdefault("original_file_name", old_file_name)
 
             if metadata.get("preview_url"):
                 old_preview = str(metadata["preview_url"])

py/services/settings_manager.py

@@ -98,6 +98,7 @@ DEFAULT_SETTINGS: Dict[str, Any] = {
     "recipes_path": "",
     "base_model_path_mappings": {},
     "download_path_templates": {},
+    "download_filename_templates": {},
     "folder_paths": {},
     "extra_folder_paths": {},
     "example_images_path": "",
@@ -1276,6 +1277,7 @@ class SettingsManager:
         defaults = copy.deepcopy(DEFAULT_SETTINGS)
         defaults["base_model_path_mappings"] = {}
         defaults["download_path_templates"] = {}
+        defaults["download_filename_templates"] = {}
         defaults["priority_tags"] = DEFAULT_PRIORITY_TAG_CONFIG.copy()
         defaults.setdefault("folder_paths", {})
         defaults.setdefault("extra_folder_paths", {})
@@ -2424,6 +2426,49 @@ class SettingsManager:
             model_type, DEFAULT_DOWNLOAD_PATH_TEMPLATES.get(model_type, "")
         )
 
+    def get_download_filename_template(self, model_type: str) -> str:
+        """Get the download filename template for a specific model type.
+
+        Args:
+            model_type: The type of model ('lora', 'checkpoint', 'embedding',
+                'other')
+
+        Returns:
+            Template string for the model type. Empty string (the default for
+            every model type) means downloaded files keep their original
+            filename.
+        """
+        templates = self.settings.get("download_filename_templates", {})
+
+        # Handle edge case where templates might be stored as JSON string
+        if isinstance(templates, str):
+            try:
+                parsed_templates = json.loads(templates)
+                if isinstance(parsed_templates, dict):
+                    self.settings["download_filename_templates"] = parsed_templates
+                    self._save_settings()
+                    templates = parsed_templates
+                    logger.info(
+                        "Successfully parsed download_filename_templates from JSON string"
+                    )
+                else:
+                    raise ValueError("Parsed JSON is not a dictionary")
+            except (json.JSONDecodeError, ValueError) as e:
+                logger.warning(
+                    f"Failed to parse download_filename_templates JSON string: {e}. Resetting to empty templates."
+                )
+                templates = {}
+                self.settings["download_filename_templates"] = templates
+                self._save_settings()
+
+        if not isinstance(templates, dict):
+            templates = {}
+            self.settings["download_filename_templates"] = templates
+            self._save_settings()
+
+        template = templates.get(model_type, "")
+        return template if isinstance(template, str) else ""
+
 
 _SETTINGS_MANAGER: Optional["SettingsManager"] = None
 _SETTINGS_MANAGER_LOCK = Lock()

py/services/use_cases/__init__.py

@@ -20,6 +20,7 @@ from .example_images import (
     ImportExampleImagesUseCase,
     ImportExampleImagesValidationError,
 )
+from .filename_template_use_case import FilenameTemplateUseCase
 
 __all__ = [
     "AutoOrganizeInProgressError",
@@ -34,4 +35,5 @@ __all__ = [
     "DownloadExampleImagesUseCase",
     "ImportExampleImagesUseCase",
     "ImportExampleImagesValidationError",
+    "FilenameTemplateUseCase",
 ]

py/services/use_cases/filename_template_use_case.py

@@ -0,0 +1,222 @@
+"""Filename template use case: bulk-rename library models per the configured template."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Any, Dict, List, Optional, Sequence
+
+from ...utils.constants import AUTO_ORGANIZE_BATCH_SIZE
+from ...utils.utils import calculate_filename_for_model
+from ..model_file_service import AutoOrganizeResult, ProgressCallback
+from ..model_lifecycle_service import ModelLifecycleService
+from ..settings_manager import get_settings_manager
+from .auto_organize_use_case import (
+    AutoOrganizeInProgressError,
+    AutoOrganizeLockProvider,
+)
+
+logger = logging.getLogger(__name__)
+
+_PROGRESS_TYPE = "filename_template_progress"
+
+
+class FilenameTemplateUseCase:
+    """Apply the download filename template to existing library models.
+
+    Shares the auto-organize lock (and its in-progress error) so a bulk
+    rename never runs concurrently with an auto-organize operation.
+    """
+
+    def __init__(
+        self,
+        *,
+        scanner,
+        lifecycle_service: ModelLifecycleService,
+        lock_provider: AutoOrganizeLockProvider,
+        model_type: str,
+    ) -> None:
+        self._scanner = scanner
+        self._lifecycle_service = lifecycle_service
+        self._lock_provider = lock_provider
+        self._model_type = model_type
+
+    async def execute(
+        self,
+        *,
+        file_paths: Optional[Sequence[str]] = None,
+        progress_callback: Optional[ProgressCallback] = None,
+    ) -> AutoOrganizeResult:
+        """Run the bulk rename guarded by the shared library-operation lock."""
+
+        is_running = getattr(self._lock_provider, "is_filename_template_running", None)
+        if callable(is_running) and is_running():
+            raise AutoOrganizeInProgressError(
+                "A filename template operation is already running"
+            )
+        if self._lock_provider.is_auto_organize_running():
+            raise AutoOrganizeInProgressError("Auto-organize is already running")
+
+        lock = await self._lock_provider.get_auto_organize_lock()
+        if lock.locked():
+            raise AutoOrganizeInProgressError(
+                "Another library operation is already running"
+            )
+
+        async with lock:
+            return await self._run(
+                file_paths=file_paths, progress_callback=progress_callback
+            )
+
+    async def _run(
+        self,
+        *,
+        file_paths: Optional[Sequence[str]],
+        progress_callback: Optional[ProgressCallback],
+    ) -> AutoOrganizeResult:
+        result = AutoOrganizeResult()
+        result.operation_type = "filename_template"
+
+        self._scanner.reset_cancellation()
+
+        try:
+            template = get_settings_manager().get_download_filename_template(
+                self._model_type
+            )
+
+            cache = await self._scanner.get_cached_data()
+            models = list(cache.raw_data)
+            if file_paths:
+                wanted = set(file_paths)
+                models = [
+                    model for model in models if model.get("file_path") in wanted
+                ]
+
+            result.total = len(models)
+
+            await self._emit_progress(progress_callback, result, "started")
+
+            for index in range(0, result.total, AUTO_ORGANIZE_BATCH_SIZE):
+                if self._scanner.is_cancelled():
+                    logger.info(
+                        "Filename template apply cancelled for %s", self._model_type
+                    )
+                    break
+
+                batch = models[index : index + AUTO_ORGANIZE_BATCH_SIZE]
+                for model in batch:
+                    if self._scanner.is_cancelled():
+                        break
+                    await self._process_model(model, template, result)
+                    result.processed += 1
+
+                await self._emit_progress(progress_callback, result, "processing")
+                # Yield between batches so the server stays responsive.
+                await asyncio.sleep(0.1)
+
+            if self._scanner.is_cancelled():
+                result.status = "cancelled"
+                await self._emit_progress(progress_callback, result, "cancelled")
+                return result
+
+            await self._emit_progress(progress_callback, result, "completed")
+            return result
+
+        except Exception as exc:
+            logger.error("Error in filename template apply: %s", exc, exc_info=True)
+            if progress_callback:
+                await progress_callback.on_progress(
+                    {
+                        "type": _PROGRESS_TYPE,
+                        "status": "error",
+                        "error": str(exc),
+                        "operation_type": result.operation_type,
+                    }
+                )
+            raise
+
+    async def _process_model(
+        self,
+        model: Dict[str, Any],
+        template: str,
+        result: AutoOrganizeResult,
+    ) -> None:
+        model_name = model.get("model_name", "Unknown")
+        try:
+            file_path = model.get("file_path")
+            if not file_path:
+                self._add_result(result, model_name, False, "No file path found")
+                result.failure_count += 1
+                return
+
+            if not template:
+                result.skipped_count += 1
+                return
+
+            new_stem = calculate_filename_for_model(model, self._model_type)
+            if not new_stem:
+                result.skipped_count += 1
+                return
+
+            current_stem = os.path.splitext(os.path.basename(file_path))[0]
+            if new_stem == current_stem or os.path.normcase(
+                new_stem
+            ) == os.path.normcase(current_stem):
+                result.skipped_count += 1
+                return
+
+            await self._lifecycle_service.rename_model(
+                file_path=file_path, new_file_name=new_stem
+            )
+            result.success_count += 1
+
+        except ValueError as exc:
+            # Conflicts (e.g. target name already exists) count as failures
+            # without aborting the batch.
+            self._add_result(result, model_name, False, str(exc))
+            result.failure_count += 1
+        except Exception as exc:
+            logger.error(
+                "Error applying filename template to %s: %s", model_name, exc,
+                exc_info=True,
+            )
+            self._add_result(result, model_name, False, f"Error: {exc}")
+            result.failure_count += 1
+
+    async def _emit_progress(
+        self,
+        progress_callback: Optional[ProgressCallback],
+        result: AutoOrganizeResult,
+        status: str,
+    ) -> None:
+        if not progress_callback:
+            return
+        await progress_callback.on_progress(
+            {
+                "type": _PROGRESS_TYPE,
+                "status": status,
+                "total": result.total,
+                "processed": result.processed,
+                "success": result.success_count,
+                "failures": result.failure_count,
+                "skipped": result.skipped_count,
+                "operation_type": result.operation_type,
+            }
+        )
+
+    @staticmethod
+    def _add_result(
+        result: AutoOrganizeResult,
+        model_name: str,
+        success: bool,
+        message: str,
+    ) -> None:
+        """Add a result entry if under the limit (mirrors ModelFileService)."""
+        if len(result.results) < 100:
+            result.results.append(
+                {"model": model_name, "success": success, "message": message}
+            )
+        elif len(result.results) == 100:
+            result.results_truncated = True
+            result.sample_results = result.results[:50]

py/services/websocket_manager.py

@@ -20,6 +20,8 @@ class WebSocketManager:
         self._last_init_progress: Dict[str, Dict[str, Any]] = {}
         # Add auto-organize progress tracking
         self._auto_organize_progress: Optional[Dict[str, Any]] = None
+        # Add filename template progress tracking
+        self._filename_template_progress: Optional[Dict[str, Any]] = None
         # Add recipe rematch progress tracking
         self._recipe_rematch_progress: Optional[Dict[str, Any]] = None
         self._auto_organize_lock = asyncio.Lock()
@@ -205,6 +207,26 @@ class WebSocketManager:
     def cleanup_auto_organize_progress(self):
         """Clear auto-organize progress data"""
         self._auto_organize_progress = None
+
+    async def broadcast_filename_template_progress(self, data: Dict[str, Any]):
+        """Broadcast filename template progress to connected clients"""
+        self._filename_template_progress = data
+        await self.broadcast(data)
+
+    def get_filename_template_progress(self) -> Optional[Dict[str, Any]]:
+        """Get current filename template progress"""
+        return self._filename_template_progress
+
+    def cleanup_filename_template_progress(self):
+        """Clear filename template progress data"""
+        self._filename_template_progress = None
+
+    def is_filename_template_running(self) -> bool:
+        """Check if a filename template operation is currently running"""
+        if not self._filename_template_progress:
+            return False
+        status = self._filename_template_progress.get('status')
+        return status in ['started', 'processing']
     
     async def broadcast_recipe_rematch_progress(self, data: Dict[str, Any]):
         """Broadcast recipe rematch progress to connected clients"""

py/services/websocket_progress_callback.py

@@ -21,6 +21,14 @@ class WebSocketProgressCallback(ProgressCallback):
         await ws_manager.broadcast_auto_organize_progress(progress_data)
 
 
+class WebSocketFilenameTemplateProgressCallback(ProgressCallback):
+    """WebSocket progress callback for filename template operations."""
+
+    async def on_progress(self, progress_data: Dict[str, Any]) -> None:
+        """Send filename template progress via WebSocket."""
+        await ws_manager.broadcast_filename_template_progress(progress_data)
+
+
 class WebSocketBroadcastCallback:
     """Generic WebSocket progress callback broadcasting to all clients."""
 

py/utils/utils.py

@@ -1,4 +1,5 @@
 from difflib import SequenceMatcher
+import logging
 import os
 import re
 from typing import Any, Dict, List, Optional
@@ -7,6 +8,8 @@ from ..config import config
 from ..services.settings_manager import get_settings_manager
 import asyncio
 
+logger = logging.getLogger(__name__)
+
 
 def get_lora_info(lora_name):
     """Get the lora path and trigger words from cache"""
@@ -598,6 +601,107 @@ def calculate_relative_path_for_model(
     return formatted_path
 
 
+def calculate_filename_for_model(
+    model_data: Dict[str, Any], model_type: str = "lora"
+) -> str:
+    """Calculate the filename stem for a model using the filename template.
+
+    Mirrors the data extraction of :func:`calculate_relative_path_for_model`
+    but renders a single filename (no path segments). Missing values resolve
+    to empty segments instead of the path-oriented defaults ("Anonymous" /
+    "no tags") so templates degrade gracefully.
+
+    Args:
+        model_data: Model data from scanner cache
+        model_type: Type of model ('lora', 'checkpoint', 'embedding')
+
+    Returns:
+        Sanitized filename stem without extension, or an empty string when no
+        template is configured, the template is invalid, or the rendered name
+        is empty.
+    """
+    settings_manager = get_settings_manager()
+    template = settings_manager.get_download_filename_template(model_type)
+
+    if not template:
+        return ""
+
+    # A filename template must render a single name, never folder segments.
+    if "/" in template or "\\" in template:
+        logger.warning(
+            "Filename template for %s contains a path separator and is ignored: %r",
+            model_type,
+            template,
+        )
+        return ""
+
+    civitai_data = model_data.get("civitai", {})
+
+    author = ""
+    if isinstance(civitai_data, dict) and civitai_data.get("id") is not None:
+        creator_info = civitai_data.get("creator") or {}
+        author = creator_info.get("username") or ""
+
+    base_model = model_data.get("base_model", "")
+    base_model_mappings = settings_manager.get("base_model_path_mappings", {})
+    mapped_base_model = base_model_mappings.get(base_model, base_model)
+
+    lowercase_tags = [
+        tag.lower() for tag in model_data.get("tags", []) if isinstance(tag, str)
+    ]
+    first_tag = settings_manager.resolve_priority_tag_for_model(
+        lowercase_tags, model_type
+    )
+
+    model_name = model_data.get("model_name", "")
+    version_name = ""
+    if isinstance(civitai_data, dict):
+        version_name = civitai_data.get("name") or ""
+
+    sha256 = model_data.get("sha256") or ""
+    hash_short = sha256[:10].lower() if isinstance(sha256, str) else ""
+
+    file_path = model_data.get("file_path") or ""
+    if isinstance(file_path, str) and file_path:
+        original_name = os.path.splitext(os.path.basename(file_path))[0]
+    else:
+        original_name = os.path.splitext(str(model_data.get("file_name", "")))[0]
+
+    def _sanitize_value(value: Any) -> str:
+        # sanitize_folder_name falls back to "unnamed" for empty input; for
+        # templates an empty value must stay empty so segments collapse.
+        text = str(value) if value else ""
+        return sanitize_folder_name(text) if text else ""
+
+    replacements = {
+        "{model_name}": _sanitize_value(model_name),
+        "{version_name}": _sanitize_value(version_name),
+        "{base_model}": _sanitize_value(mapped_base_model),
+        "{author}": _sanitize_value(author),
+        "{first_tag}": _sanitize_value(first_tag),
+        "{hash_short}": hash_short,
+        "{original_name}": _sanitize_value(original_name),
+    }
+
+    result = template
+    for placeholder, value in replacements.items():
+        result = result.replace(placeholder, value)
+
+    if model_type == "embedding":
+        result = result.replace(" ", "_")
+
+    # Strip characters that are illegal in filenames on common filesystems.
+    result = re.sub(r'[:*?"<>|]', "", result)
+    # Collapse runs of identical separators introduced by empty substitutions.
+    result = re.sub(r"([-_. ])\1+", r"\1", result)
+    # Drop separators left dangling next to each other ("- -" -> "-").
+    result = re.sub(r" ?([-_.]) (?=[-_.])", r"\1", result)
+    # A stem must not start or end with separators, spaces or dots.
+    result = result.strip("-_. ")
+
+    return result
+
+
 def remove_empty_dirs(path):
     """Recursively remove empty directories starting from the given path.