feat(metadata): add CivArchive API toggle and provider fallback order settings

- Add enable_civarchive_api toggle (default on) to allow disabling CivArchive to avoid its rate-limit windows entirely - Add metadata_provider_order dropdown with two presets: CivitAI → CivArchive → Archive DB (default) and CivitAI → Archive DB → CivArchive - Wire both settings through backend (metadata_service, settings_manager, misc_handlers) and frontend (SettingsManager, state, settings modal) - Reorder Metadata section in settings modal: toggles → status/management → fallback order, for natural top-down workflow - Make update_metadata_providers() log the effective provider chain using actually-registered providers rather than settings assumptions - Add 5 test cases covering all provider-combination paths - Complete i18n translations for 6 new keys across all 9 non-English locales
2026-08-06 22:10:14 -03:00 · 2026-07-19 17:51:50 +08:00
parent c27e4d1bfc
commit a8d742b031
17 changed files with 20055 additions and 19776 deletions
--- a/locales/de.json
+++ b/locales/de.json
@@ -640,7 +640,13 @@
      "preparing": "Download wird vorbereitet...",
      "connecting": "Verbindung zum Download-Server wird hergestellt...",
      "completed": "Abgeschlossen",
-            "downloadComplete": "Download erfolgreich abgeschlossen"
+      "downloadComplete": "Download erfolgreich abgeschlossen",
+      "enableCivarchiveApi": "CivArchive API als Metadaten-Anbieter aktivieren",
+      "enableCivarchiveApiHelp": "Wenn aktiviert, wird die CivArchive API als alternative Quelle für Modell-Metadaten verwendet (z. B. für von CivitAI gelöschte Modelle). Deaktivieren, um die Ratenbegrenzungen von CivArchive vollständig zu vermeiden.",
+      "providerOrder": "Reihenfolge der Metadaten-Anbieter",
+      "providerOrderHelp": "Die CivitAI API wird immer zuerst versucht. Wählen Sie die Reihenfolge der übrigen Anbieter bei der Metadatensuche.",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "App-Proxy aktivieren",
--- a/locales/en.json
+++ b/locales/en.json
@@ -640,7 +640,13 @@
      "preparing": "Preparing download...",
      "connecting": "Connecting to download server...",
      "completed": "Completed",
-      "downloadComplete": "Download completed successfully"
+      "downloadComplete": "Download completed successfully",
+      "enableCivarchiveApi": "Enable CivArchive API as metadata provider",
+      "enableCivarchiveApiHelp": "When on, CivArchive API is used as a fallback source for model metadata (e.g. for models deleted from CivitAI). Turn off to avoid CivArchive rate limits entirely.",
+      "providerOrder": "Metadata provider fallback order",
+      "providerOrderHelp": "CivitAI API is always tried first. Choose the order of the remaining providers when looking up metadata.",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "Enable App-level Proxy",
--- a/locales/es.json
+++ b/locales/es.json
@@ -640,7 +640,13 @@
      "preparing": "Preparando descarga...",
      "connecting": "Conectando al servidor de descarga...",
      "completed": "Completado",
-            "downloadComplete": "Descarga completada exitosamente"
+      "downloadComplete": "Descarga completada exitosamente",
+      "enableCivarchiveApi": "Habilitar CivArchive API como proveedor de metadatos",
+      "enableCivarchiveApiHelp": "Al activarlo, la API de CivArchive se usa como fuente alternativa de metadatos de modelos (p. ej. para modelos eliminados de CivitAI). Desactívelo para evitar por completo los límites de velocidad de CivArchive.",
+      "providerOrder": "Orden de proveedores de metadatos de respaldo",
+      "providerOrderHelp": "La API de CivitAI siempre se intenta primero. Elija el orden de los demás proveedores al buscar metadatos.",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "Habilitar proxy a nivel de aplicación",
--- a/locales/fr.json
+++ b/locales/fr.json
@@ -640,7 +640,13 @@
      "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"
+      "downloadComplete": "Téléchargement terminé avec succès",
+      "enableCivarchiveApi": "Activer l'API CivArchive comme fournisseur de métadonnées",
+      "enableCivarchiveApiHelp": "Lorsqu'elle est activée, l'API CivArchive est utilisée comme source de secours pour les métadonnées des modèles (par ex. pour les modèles supprimés de CivitAI). Désactivez pour éviter entièrement les limites de débit de CivArchive.",
+      "providerOrder": "Ordre de secours des fournisseurs de métadonnées",
+      "providerOrderHelp": "L'API CivitAI est toujours essayée en premier. Choisissez l'ordre des autres fournisseurs lors de la recherche de métadonnées.",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "Activer le proxy au niveau de l'application",
--- a/locales/he.json
+++ b/locales/he.json
@@ -640,7 +640,13 @@
      "preparing": "מכין הורדה...",
      "connecting": "מתחבר לשרת ההורדות...",
      "completed": "הושלם",
-            "downloadComplete": "ההורדה הושלמה בהצלחה"
+      "downloadComplete": "ההורדה הושלמה בהצלחה",
+      "enableCivarchiveApi": "הפעל את CivArchive API כספק מטא-נתונים",
+      "enableCivarchiveApiHelp": "כאשר מופעל, CivArchive API משמש כמקור גיבוי למטא-נתונים של מודלים (למשל עבור מודלים שנמחקו מ-CivitAI). כבה כדי להימנע לחלוטין ממגבלות הקצב של CivArchive.",
+      "providerOrder": "סדר ספקי מטא-נתונים לגיבוי",
+      "providerOrderHelp": "CivitAI API תמיד מנוסה ראשון. בחר את סדר הספקים הנותרים בעת חיפוש מטא-נתונים.",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "הפעל פרוקסי ברמת האפליקציה",
--- a/locales/ja.json
+++ b/locales/ja.json
@@ -640,7 +640,13 @@
      "preparing": "ダウンロードを準備中...",
      "connecting": "ダウンロードサーバーに接続中...",
      "completed": "完了",
-            "downloadComplete": "ダウンロードが正常に完了しました"
+      "downloadComplete": "ダウンロードが正常に完了しました",
+      "enableCivarchiveApi": "CivArchive API をメタデータプロバイダーとして有効化",
+      "enableCivarchiveApiHelp": "有効にすると、CivArchive API がモデルメタデータの代替ソースとして使用されます（例：CivitAI から削除されたモデルの場合）。オフにすると、CivArchive のレート制限を完全に回避できます。",
+      "providerOrder": "メタデータプロバイダーのフォールバック順序",
+      "providerOrderHelp": "CivitAI API が常に最初に試行されます。メタデータ検索時の残りのプロバイダーの順序を選択してください。",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "アプリレベルのプロキシを有効化",
--- a/locales/ko.json
+++ b/locales/ko.json
@@ -640,7 +640,13 @@
      "preparing": "다운로드 준비 중...",
      "connecting": "다운로드 서버에 연결 중...",
      "completed": "완료됨",
-            "downloadComplete": "다운로드가 성공적으로 완료되었습니다"
+      "downloadComplete": "다운로드가 성공적으로 완료되었습니다",
+      "enableCivarchiveApi": "CivArchive API를 메타데이터 제공자로 활성화",
+      "enableCivarchiveApiHelp": "활성화하면 CivArchive API가 모델 메타데이터의 대체 소스로 사용됩니다 (예: CivitAI에서 삭제된 모델의 경우). 비활성화하면 CivArchive의 속도 제한을 완전히 피할 수 있습니다.",
+      "providerOrder": "메타데이터 제공자 폴백 순서",
+      "providerOrderHelp": "CivitAI API가 항상 먼저 시도됩니다. 메타데이터 조회 시 나머지 제공자의 순서를 선택하세요.",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "앱 수준 프록시 활성화",
--- a/locales/ru.json
+++ b/locales/ru.json
@@ -640,7 +640,13 @@
      "preparing": "Подготовка к загрузке...",
      "connecting": "Подключение к серверу загрузки...",
      "completed": "Завершено",
-            "downloadComplete": "Загрузка успешно завершена"
+      "downloadComplete": "Загрузка успешно завершена",
+      "enableCivarchiveApi": "Включить CivArchive API как источник метаданных",
+      "enableCivarchiveApiHelp": "При включении CivArchive API используется как резервный источник метаданных моделей (например, для моделей, удалённых с CivitAI). Отключите, чтобы полностью избежать ограничений скорости CivArchive.",
+      "providerOrder": "Порядок резервных источников метаданных",
+      "providerOrderHelp": "CivitAI API всегда проверяется первым. Выберите порядок остальных источников при поиске метаданных.",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "Включить прокси на уровне приложения",
--- a/locales/zh-CN.json
+++ b/locales/zh-CN.json
@@ -640,7 +640,13 @@
      "preparing": "正在准备下载...",
      "connecting": "正在连接下载服务器...",
      "completed": "已完成",
-            "downloadComplete": "下载成功完成"
+      "downloadComplete": "下载成功完成",
+      "enableCivarchiveApi": "启用 CivArchive API 作为元数据提供者",
+      "enableCivarchiveApiHelp": "开启后，CivArchive API 将作为模型元数据的备用来源（例如用于已从 CivitAI 删除的模型）。关闭可完全避免 CivArchive 的速率限制。",
+      "providerOrder": "元数据提供者回退顺序",
+      "providerOrderHelp": "CivitAI API 始终优先尝试。选择查找元数据时其余提供者的顺序。",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "启用应用级代理",
--- a/locales/zh-TW.json
+++ b/locales/zh-TW.json
@@ -640,7 +640,13 @@
      "preparing": "準備下載中...",
      "connecting": "正在連接下載伺服器...",
      "completed": "已完成",
-            "downloadComplete": "下載成功完成"
+      "downloadComplete": "下載成功完成",
+      "enableCivarchiveApi": "啟用 CivArchive API 作為中繼資料提供者",
+      "enableCivarchiveApiHelp": "開啟後，CivArchive API 將作為模型中繼資料的備用來源（例如用於已從 CivitAI 刪除的模型）。關閉可完全避免 CivArchive 的速率限制。",
+      "providerOrder": "中繼資料提供者回退順序",
+      "providerOrderHelp": "CivitAI API 始終優先嘗試。選擇查詢中繼資料時其餘提供者的順序。",
+      "providerOrderCivitaiArchiveSqlite": "CivitAI → CivArchive → Archive DB",
+      "providerOrderCivitaiSqliteArchive": "CivitAI → Archive DB → CivArchive"
    },
    "proxySettings": {
      "enableProxy": "啟用應用程式代理",
--- a/py/routes/handlers/misc_handlers.py
+++ b/py/routes/handlers/misc_handlers.py
@@ -1570,7 +1570,11 @@ class SettingsHandler:
                else:
                    self._settings.set(key, value)

-                if key == "enable_metadata_archive_db":
+                if key in (
+                    "enable_metadata_archive_db",
+                    "enable_civarchive_api",
+                    "metadata_provider_order",
+                ):
                    await self._metadata_provider_updater()

                if key in self._PROXY_KEYS:
--- a/py/services/metadata_service.py
+++ b/py/services/metadata_service.py
@@ -15,6 +15,17 @@ from .service_registry import ServiceRegistry

 logger = logging.getLogger(__name__)

+_PROVIDER_DISPLAY_NAMES = {
+    "civitai_api": "CivitAI",
+    "civarchive_api": "CivArchive",
+    "sqlite": "Archive DB",
+}
+
+_PRESET_PROVIDER_ORDERS = {
+    "civitai_archive_sqlite": ["civitai_api", "civarchive_api", "sqlite"],
+    "civitai_sqlite_archive": ["civitai_api", "sqlite", "civarchive_api"],
+}
+
 async def initialize_metadata_providers():
    """Initialize and configure all metadata providers based on settings"""
    provider_manager = await ModelMetadataProviderManager.get_instance()
@@ -26,6 +37,8 @@ async def initialize_metadata_providers():
    # Get settings
    settings_manager = get_settings_manager()
    enable_archive_db = settings_manager.get('enable_metadata_archive_db', False)
+    enable_civarchive_api = settings_manager.get('enable_civarchive_api', True)
+    provider_order = settings_manager.get('metadata_provider_order', 'civitai_archive_sqlite')

    providers = []
    
@@ -59,7 +72,11 @@ async def initialize_metadata_providers():
    except Exception as e:
        logger.error(f"Failed to initialize Civitai API metadata provider: {e}")

-    # Register CivArchive provider, and all add to fallback providers
+    # Register CivArchive provider when enabled. Civitai API is always
+    # preferred (better metadata); CivArchive mainly recovers metadata for
+    # models deleted from Civitai, so it can be turned off to avoid its long
+    # rate-limit windows entirely.
+    if enable_civarchive_api:
        try:
            civarchive_client = await ServiceRegistry.get_civarchive_client()
            civarchive_provider = CivArchiveModelMetadataProvider(civarchive_client)
@@ -68,18 +85,35 @@ async def initialize_metadata_providers():
            logger.debug("CivArchive metadata provider registered (also included in fallback)")
        except Exception as e:
            logger.error(f"Failed to initialize CivArchive metadata provider: {e}")
+    else:
+        logger.debug("CivArchive metadata provider disabled by setting 'enable_civarchive_api'")
+
+    # Preset fallback orderings (see module-level _PRESET_PROVIDER_ORDERS).
+    # civitai_api is always first (better metadata); the remaining providers
+    # are arranged by the configured preset.  Providers that are not
+    # registered (disabled/unavailable) are simply skipped, so each preset
+    # degrades gracefully.
+    desired_order = _PRESET_PROVIDER_ORDERS.get(
+        provider_order, _PRESET_PROVIDER_ORDERS["civitai_archive_sqlite"]
+    )

    # 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'])
+        for name in desired_order:
+            ordered_providers.extend([p for p in providers if p[0] == name])
+        # Include any provider not covered by the preset (defensive) at the end
+        for p in providers:
+            if p not in ordered_providers:
+                ordered_providers.append(p)

        if ordered_providers:
            fallback_provider = FallbackMetadataProvider(ordered_providers)
            provider_manager.register_provider('fallback', fallback_provider, is_default=True)
+            logger.debug(
+                "Metadata fallback provider order: %s",
+                ", ".join(name for name, _ in ordered_providers),
+            )
    elif len(providers) == 1:
        # Only one provider available, set it as default
        provider_name, provider = providers[0]
@@ -96,11 +130,30 @@ async def update_metadata_providers():
        # Get current settings
        settings_manager = get_settings_manager()
        enable_archive_db = settings_manager.get('enable_metadata_archive_db', False)
+        enable_civarchive_api = settings_manager.get('enable_civarchive_api', True)
+        provider_order = settings_manager.get('metadata_provider_order', 'civitai_archive_sqlite')
        
        # Reinitialize all providers with new settings
        provider_manager = await initialize_metadata_providers()
        
-        logger.info(f"Updated metadata providers, archive_db enabled: {enable_archive_db}")
+        # Build effective provider chain for logging (use actually-registered
+        # providers, not just settings, so a failed init is reflected correctly)
+        registered = set(provider_manager.providers.keys())
+        desired = _PRESET_PROVIDER_ORDERS.get(
+            provider_order, _PRESET_PROVIDER_ORDERS["civitai_archive_sqlite"]
+        )
+        chain = " → ".join(
+            _PROVIDER_DISPLAY_NAMES[p]
+            for p in desired
+            if p in registered and p in _PROVIDER_DISPLAY_NAMES
+        )
+        
+        logger.info(
+            "Updated metadata providers: archive_db=%s, civarchive_api=%s, chain=%s",
+            enable_archive_db,
+            enable_civarchive_api,
+            chain,
+        )
        return provider_manager
    except Exception as e:
        logger.error(f"Failed to update metadata providers: {e}")
--- a/py/services/settings_manager.py
+++ b/py/services/settings_manager.py
@@ -65,6 +65,8 @@ DEFAULT_SETTINGS: Dict[str, Any] = {
    "onboarding_completed": False,
    "dismissed_banners": [],
    "enable_metadata_archive_db": False,
+    "enable_civarchive_api": True,
+    "metadata_provider_order": "civitai_archive_sqlite",
    "proxy_enabled": False,
    "proxy_host": "",
    "proxy_port": "",
--- a/static/js/managers/SettingsManager.js
+++ b/static/js/managers/SettingsManager.js
@@ -2346,6 +2346,16 @@ export class SettingsManager {
                enableMetadataArchiveCheckbox.checked = state.global.settings.enable_metadata_archive_db || false;
            }

+            const enableCivarchiveApiCheckbox = document.getElementById('enableCivarchiveApi');
+            if (enableCivarchiveApiCheckbox) {
+                enableCivarchiveApiCheckbox.checked = state.global.settings.enable_civarchive_api ?? true;
+            }
+
+            const metadataProviderOrderSelect = document.getElementById('metadataProviderOrder');
+            if (metadataProviderOrderSelect) {
+                metadataProviderOrderSelect.value = state.global.settings.metadata_provider_order || 'civitai_archive_sqlite';
+            }
+
            // Load status
            await this.updateMetadataArchiveStatus();
        } catch (error) {
--- a/static/js/state/index.js
+++ b/static/js/state/index.js
@@ -13,6 +13,8 @@ const DEFAULT_SETTINGS_BASE = Object.freeze({
    language: 'en',
    show_only_sfw: false,
    enable_metadata_archive_db: false,
+    enable_civarchive_api: true,
+    metadata_provider_order: 'civitai_archive_sqlite',
    proxy_enabled: false,
    proxy_type: 'http',
    proxy_host: '',
--- a/templates/components/modals/settings_modal.html
+++ b/templates/components/modals/settings_modal.html
@@ -1401,7 +1401,26 @@
                                <div class="settings-input-error-message" id="metadataRefreshSkipPathsError"></div>
                            </div>
                            
-                            <!-- Metadata Archive -->
+                            <!-- CivArchive API provider toggle -->
+                            <div class="setting-item">
+                                <div class="setting-row">
+                                    <div class="setting-info">
+                                        <label for="enableCivarchiveApi">
+                                            {{ t('settings.metadataArchive.enableCivarchiveApi') }}
+                                            <i class="fas fa-info-circle info-icon" data-tooltip="{{ t('settings.metadataArchive.enableCivarchiveApiHelp') }}"></i>
+                                        </label>
+                                    </div>
+                                    <div class="setting-control">
+                                        <label class="toggle-switch">
+                                            <input type="checkbox" id="enableCivarchiveApi"
+                                                   onchange="settingsManager.saveToggleSetting('enableCivarchiveApi', 'enable_civarchive_api')">
+                                            <span class="toggle-slider"></span>
+                                        </label>
+                                    </div>
+                                </div>
+                            </div>
+
+                            <!-- Metadata Archive DB -->
                            <div class="setting-item">
                                <div class="setting-row">
                                    <div class="setting-info">
@@ -1444,6 +1463,24 @@
                                    </div>
                                </div>
                            </div>
+
+                            <!-- Metadata provider fallback order -->
+                            <div class="setting-item">
+                                <div class="setting-row">
+                                    <div class="setting-info">
+                                        <label for="metadataProviderOrder">
+                                            {{ t('settings.metadataArchive.providerOrder') }}
+                                            <i class="fas fa-info-circle info-icon" data-tooltip="{{ t('settings.metadataArchive.providerOrderHelp') }}"></i>
+                                        </label>
+                                    </div>
+                                    <div class="setting-control select-control">
+                                        <select id="metadataProviderOrder" onchange="settingsManager.saveSelectSetting('metadataProviderOrder', 'metadata_provider_order')">
+                                            <option value="civitai_archive_sqlite">{{ t('settings.metadataArchive.providerOrderCivitaiArchiveSqlite') }}</option>
+                                            <option value="civitai_sqlite_archive">{{ t('settings.metadataArchive.providerOrderCivitaiSqliteArchive') }}</option>
+                                        </select>
+                                    </div>
+                                </div>
+                            </div>
                        </div>
                    </div>
                </div>
--- a/tests/services/test_metadata_service.py
+++ b/tests/services/test_metadata_service.py
@@ -60,3 +60,114 @@ async def test_get_metadata_provider_returns_fallback_as_is(monkeypatch):
    provider = await metadata_service.get_metadata_provider()

    assert provider is fallback
+
+
+# ---------------------------------------------------------------------------
+# initialize_metadata_providers — provider gating + fallback ordering
+# ---------------------------------------------------------------------------
+
+
+def _stub_settings(**overrides):
+    """Minimal settings stub returning configured values."""
+    base = {
+        "enable_metadata_archive_db": False,
+        "enable_civarchive_api": True,
+        "metadata_provider_order": "civitai_archive_sqlite",
+    }
+    base.update(overrides)
+    return SimpleNamespace(get=lambda key, default=None: base.get(key, default))
+
+
+async def _run_initialize(monkeypatch, settings):
+    # Fresh provider manager for each test
+    monkeypatch.setattr(
+        metadata_service.ModelMetadataProviderManager,
+        "get_instance",
+        AsyncMock(return_value=metadata_service.ModelMetadataProviderManager()),
+    )
+    monkeypatch.setattr(
+        metadata_service, "get_settings_manager", lambda: settings
+    )
+    monkeypatch.setattr(
+        metadata_service.ServiceRegistry,
+        "get_civitai_client",
+        AsyncMock(return_value=object()),
+    )
+    monkeypatch.setattr(
+        metadata_service.ServiceRegistry,
+        "get_civarchive_client",
+        AsyncMock(return_value=object()),
+    )
+
+    # Make MetadataArchiveManager report a usable db path when enabled
+    fake_archive = SimpleNamespace(get_database_path=lambda: "/tmp/fake.db")
+    monkeypatch.setattr(
+        metadata_service, "MetadataArchiveManager", lambda _base: fake_archive
+    )
+    # Pretend the db file exists
+    monkeypatch.setattr(metadata_service.os.path, "exists", lambda _p: True)
+
+    manager = await metadata_service.initialize_metadata_providers()
+    return manager
+
+
+def _fallback_provider_order(manager):
+    """Return the ordered list of provider labels inside the fallback provider."""
+    fallback = manager.providers.get("fallback")
+    assert isinstance(fallback, FallbackMetadataProvider), "expected a fallback provider"
+    return list(fallback._provider_labels)
+
+
+@pytest.mark.asyncio
+async def test_initialize_providers_default_order(monkeypatch):
+    settings = _stub_settings(enable_metadata_archive_db=True)
+    manager = await _run_initialize(monkeypatch, settings)
+    assert _fallback_provider_order(manager) == ["civitai_api", "civarchive_api", "sqlite"]
+
+
+@pytest.mark.asyncio
+async def test_initialize_providers_prefer_sqlite_order(monkeypatch):
+    settings = _stub_settings(
+        enable_metadata_archive_db=True,
+        metadata_provider_order="civitai_sqlite_archive",
+    )
+    manager = await _run_initialize(monkeypatch, settings)
+    assert _fallback_provider_order(manager) == ["civitai_api", "sqlite", "civarchive_api"]
+
+
+@pytest.mark.asyncio
+async def test_initialize_providers_disables_civarchive(monkeypatch):
+    settings = _stub_settings(
+        enable_metadata_archive_db=True,
+        enable_civarchive_api=False,
+    )
+    manager = await _run_initialize(monkeypatch, settings)
+    # civarchive_api must not be registered at all
+    assert "civarchive_api" not in manager.providers
+    assert _fallback_provider_order(manager) == ["civitai_api", "sqlite"]
+
+
+@pytest.mark.asyncio
+async def test_initialize_providers_skips_unavailable_sqlite_in_preset(monkeypatch):
+    # Preset wants sqlite before civarchive, but archive db is disabled ->
+    # sqlite is unavailable and must be skipped, civarchive stays.
+    settings = _stub_settings(
+        enable_metadata_archive_db=False,
+        metadata_provider_order="civitai_sqlite_archive",
+    )
+    manager = await _run_initialize(monkeypatch, settings)
+    assert _fallback_provider_order(manager) == ["civitai_api", "civarchive_api"]
+
+
+@pytest.mark.asyncio
+async def test_initialize_providers_single_provider_when_only_civitai(monkeypatch):
+    # Both archive db and civarchive disabled -> only civitai_api remains,
+    # which takes the single-provider path (registered as default, no fallback).
+    settings = _stub_settings(
+        enable_metadata_archive_db=False,
+        enable_civarchive_api=False,
+    )
+    manager = await _run_initialize(monkeypatch, settings)
+    assert "fallback" not in manager.providers
+    assert manager.default_provider == "civitai_api"
+