fix(ai_admin): optimize model timeout failover and expand free artwork providers with Cinemeta, TVmaze, and TMDb images

ai_admin/config.py

@@ -10,12 +10,10 @@ logger = logging.getLogger("AIAdmin.Config")
 
 DEFAULT_WORKING_MODELS: List[str] = [
     "oc/gemini-3.5-flash-lite",
-    "oc/gemini-3.5-flash",
+    "oc/gemini-3.7-flash",
     "oc/gemini-3.6-flash",
-    "oc/claude-sonnet-4-6",
-    "oc/grok-4.5",
-    "oc/glm-5.3-flash",
     "oc/kimi-k3",
+    "oc/glm-5.3-flash",
 ]
 
 
@@ -62,6 +60,7 @@ class AIAdminConfig:
     ai_model: str = "oc/gemini-3.5-flash-lite"
     ai_models: List[str] = field(default_factory=list)
     ai_max_tokens: int = 1024
+    omniroute_timeout_seconds: int = 18
 
     # Storage and Lifetimes
     data_dir: str = "/data/ai_admin"
@@ -126,6 +125,12 @@ class AIAdminConfig:
         except ValueError:
             max_tokens = 1024
 
+        try:
+            timeout_env = int(os.environ.get("OMNIROUTE_TIMEOUT_SECONDS", "18"))
+            omniroute_timeout = max(5, min(timeout_env, 60))
+        except ValueError:
+            omniroute_timeout = 18
+
         data_dir = os.environ.get("AI_DATA_DIR") or "/data/ai_admin"
 
         try:
@@ -164,6 +169,7 @@ class AIAdminConfig:
             ai_model=primary_model,
             ai_models=ai_models,
             ai_max_tokens=max_tokens,
+            omniroute_timeout_seconds=omniroute_timeout,
             data_dir=data_dir,
             confirm_ttl_seconds=confirm_ttl,
             context_ttl_seconds=context_ttl,

ai_admin/handler.py

@@ -145,14 +145,15 @@ class AIAdminHandler:
             "You are an intelligent, friendly, and expert Jellyfin Media Server AI Assistant.\n"
             "You have direct control to inspect and manage the Jellyfin library and query metadata/artwork providers:\n"
             "• Search Jellyfin library for movies, series, episodes (`jellyfin_search`, `jellyfin_get_item`, `jellyfin_get_media_info`).\n"
-            "• Query TMDb (themoviedb) for official posters, backdrops, and metadata (`tmdb_search`, `tmdb_get_details`).\n"
-            "• Query Fanart.tv for high-resolution posters, clearart, and backgrounds (`fanart_get_images`).\n"
+            "• Search artwork & posters across providers (`artwork_search` for multi-provider search, `tmdb_get_images`, `cinemeta_search`, `cinemeta_get_meta`, `tvmaze_search`, `fanart_get_images`).\n"
+            "• Free providers like Cinemeta (IMDb catalog) and TVmaze require zero API keys and find authentic posters/thumbnails for movies and series.\n"
+            "• Query TMDb (themoviedb) for official details and images (`tmdb_search`, `tmdb_get_details`, `tmdb_get_images`).\n"
             "• Search subtitles on OpenSubtitles (`opensubtitles_search`).\n\n"
             "Workflow Guidelines:\n"
             "1. When the user asks to find a movie/series and check or fix its poster/thumbnail:\n"
-            "   a) FIRST search Jellyfin to locate the item and check its metadata.\n"
-            "   b) THEN search TMDb or Fanart using the movie name or TMDb ID to discover the best authentic posters and artwork.\n"
-            "   c) PRESENT the results conversationally with titles, years, current status, and direct preview links for the best posters found.\n"
+            "   a) FIRST search Jellyfin (`jellyfin_search`) to locate the item, its ID, current metadata, and existing artwork.\n"
+            "   b) THEN search artwork via `artwork_search` or `cinemeta_search` / `tmdb_get_images` using the title or IMDb/TMDb ID.\n"
+            "   c) PRESENT the results conversationally with titles, years, current status, and direct preview links for the best authentic posters found.\n"
             "   d) Offer to apply the selected poster.\n"
             "2. If the user is just chatting or asking a question that doesn't need tools, reply warmly, concisely, and conversationally.\n"
             "3. Format all responses using Telegram markdown (*bold*, `code`, [link](url)). Never output raw JSON unless specifically requested."
@@ -171,6 +172,7 @@ class AIAdminHandler:
             planned_ok, tool_calls, reply_or_err = await self.omniroute.chat_or_plan(
                 messages=messages,
                 tool_schemas=schemas,
+                timeout_seconds=self.config.omniroute_timeout_seconds,
             )
 
             if not planned_ok:

ai_admin/net_guard.py

@@ -17,6 +17,12 @@ APPROVED_PROVIDER_HOSTS: Set[str] = {
     "opensubtitles-v3.strem.io",
     "webservice.fanart.tv",
     "assets.fanart.tv",
+    "v3-cinemeta.strem.io",
+    "images.metahub.space",
+    "m.media-amazon.com",
+    "ia.media-imdb.com",
+    "api.tvmaze.com",
+    "static.tvmaze.com",
 }
 
 

ai_admin/omniroute_adapter.py

@@ -93,7 +93,7 @@ class OmniRouteAdapter:
         context_history: Optional[List[Dict[str, str]]] = None,
         tool_schemas: Optional[List[Dict[str, Any]]] = None,
         messages: Optional[List[Dict[str, Any]]] = None,
-        timeout_seconds: int = 30,
+        timeout_seconds: Optional[int] = None,
     ) -> Tuple[bool, List[Dict[str, Any]], str]:
         """Send instruction or pre-built messages to OmniRoute.
         Returns:
@@ -105,10 +105,12 @@ class OmniRouteAdapter:
         if not (self.config.omniroute_api_url and self.config.omniroute_api_key):
             return False, [], "OmniRoute configuration is missing (OMNIROUTE_API_KEY / OMNIROUTE_API_URL)."
 
+        effective_timeout = timeout_seconds or getattr(self.config, "omniroute_timeout_seconds", 18)
+
         if messages is None:
             system_prompt = (
                 "You are an intelligent, helpful, and friendly Jellyfin Media Server AI Assistant.\n"
-                "You have access to tools to inspect and manage the Jellyfin library and query metadata/artwork providers (TMDB, Fanart.tv, OpenSubtitles).\n"
+                "You have access to tools to inspect and manage the Jellyfin library and query metadata/artwork providers (TMDb, Cinemeta, TVmaze, Fanart.tv, OpenSubtitles).\n"
                 "If the user asks to find, check, compare, or fix posters, thumbnails, subtitles, or metadata, use the appropriate tools.\n"
                 "If the user greets you or asks general questions that do not require tool operations, answer conversationally and helpfully.\n"
                 "Format your answers with clean Telegram markdown (*bold*, `code`, [link](url))."
@@ -134,8 +136,8 @@ class OmniRouteAdapter:
             if tool_schemas:
                 payload["tools"] = tool_schemas
 
-            logger.info(f"[OMNIROUTE-CHAT] Attempting model '{model}'...")
-            status, data, err_msg = await self._send_request(payload, timeout_seconds=timeout_seconds)
+            logger.info(f"[OMNIROUTE-CHAT] Attempting model '{model}' with {effective_timeout}s timeout...")
+            status, data, err_msg = await self._send_request(payload, timeout_seconds=effective_timeout)
 
             if status in (401, 403):
                 return False, [], err_msg
@@ -169,19 +171,24 @@ class OmniRouteAdapter:
             content = (msg.get("content") or "").strip()
             return True, parsed_calls, content
 
-        return False, [], last_err or "All configured AI models failed to respond."
+        return False, [], (
+            f"All configured AI models timed out or failed to respond ({last_err})."
+            if last_err else "All configured AI models failed to respond."
+        )
 
     async def synthesize_response(
         self,
         instruction: str,
         context_history: List[Dict[str, str]],
         tool_results: List[Dict[str, Any]],
-        timeout_seconds: int = 25,
+        timeout_seconds: Optional[int] = None,
     ) -> Tuple[bool, str]:
         """Synthesize tool execution results into a natural, conversational response."""
         if not (self.config.omniroute_api_url and self.config.omniroute_api_key):
             return False, ""
 
+        effective_timeout = timeout_seconds or getattr(self.config, "omniroute_timeout_seconds", 18)
+
         system_prompt = (
             "You are an intelligent, friendly Jellyfin Media Server AI Assistant.\n"
             "Explain the results of the operations conversationally to the user.\n"
@@ -214,7 +221,7 @@ class OmniRouteAdapter:
                 "messages": messages,
             }
             try:
-                status, data, err_msg = await self._send_request(payload, timeout_seconds=timeout_seconds)
+                status, data, err_msg = await self._send_request(payload, timeout_seconds=effective_timeout)
                 if status == 200 and isinstance(data, dict):
                     choices = data.get("choices") or []
                     if choices:
@@ -291,7 +298,8 @@ class OmniRouteAdapter:
                     return 500, None, f"Malformed JSON from OmniRoute: {json_err}"
 
         except asyncio.TimeoutError:
-            return 504, None, f"OmniRoute request timed out after {timeout_seconds} seconds."
+            model_name = payload.get("model", "unknown")
+            return 504, None, f"OmniRoute request for '{model_name}' timed out after {timeout_seconds} seconds."
         except Exception as e:
             return 500, None, f"Network error contacting OmniRoute: {type(e).__name__}"
         finally:

ai_admin/providers_client.py

@@ -184,9 +184,11 @@ class ProvidersClient:
         year: Optional[int] = None,
         language: Optional[str] = None,
         limit: int = 10,
+        user_id: Optional[int] = None,
+        chat_id: Optional[int] = None,
         session: Optional[aiohttp.ClientSession] = None,
     ) -> List[Dict[str, Any]]:
-        """Search TMDb for movie or TV titles with bounded output."""
+        """Search TMDb for movie or TV titles with bounded output and candidate artwork handles."""
         clean_query = (query or "").strip()
         if not clean_query:
             return []
@@ -221,6 +223,25 @@ class ProvidersClient:
             release_date = hit.get("release_date") or hit.get("first_air_date") or ""
             parsed_year = int(release_date[:4]) if len(release_date) >= 4 and release_date[:4].isdigit() else None
             overview = (hit.get("overview") or "").strip()
+            poster_path = hit.get("poster_path")
+            backdrop_path = hit.get("backdrop_path")
+
+            poster_url = f"https://image.tmdb.org/t/p/w500{poster_path}" if poster_path else None
+            backdrop_url = f"https://image.tmdb.org/t/p/w1280{backdrop_path}" if backdrop_path else None
+
+            poster_cand = None
+            if poster_url:
+                poster_cand = self.candidate_cache.register_candidate(
+                    {
+                        "provider": "themoviedb.org",
+                        "raw_url": poster_url,
+                        "image_type": "poster",
+                        "target_id": str(hit.get("id")),
+                    },
+                    user_id=user_id,
+                    chat_id=chat_id,
+                    operation="image_artwork",
+                )
 
             results.append({
                 "tmdb_id": hit.get("id"),
@@ -231,8 +252,11 @@ class ProvidersClient:
                 "overview": overview[:200] + ("..." if len(overview) > 200 else ""),
                 "original_language": hit.get("original_language"),
                 "vote_average": hit.get("vote_average"),
-                "has_poster": bool(hit.get("poster_path")),
-                "has_backdrop": bool(hit.get("backdrop_path")),
+                "has_poster": bool(poster_path),
+                "poster_url": poster_url,
+                "poster_candidate_id": poster_cand,
+                "has_backdrop": bool(backdrop_path),
+                "backdrop_url": backdrop_url,
             })
         return results
 
@@ -280,8 +304,414 @@ class ProvidersClient:
             "has_backdrop": bool(data.get("backdrop_path")),
         }
 
+    async def tmdb_get_images(
+        self,
+        tmdb_id: int,
+        media_type: str = "movie",
+        limit: int = 20,
+        user_id: Optional[int] = None,
+        chat_id: Optional[int] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> List[Dict[str, Any]]:
+        """Fetch all official posters, backdrops, and logos from TMDb."""
+        if not isinstance(tmdb_id, int) or tmdb_id <= 0:
+            raise ValueError(f"Invalid tmdb_id: {tmdb_id}")
+
+        if not self.tmdb_key:
+            raise ProviderAuthError("TMDb API key not configured (TMDB_API_KEY).")
+
+        clean_type = "tv" if str(media_type).lower() in ("tv", "series") else "movie"
+        url = f"https://api.themoviedb.org/3/{clean_type}/{tmdb_id}/images"
+        params = {"api_key": self.tmdb_key}
+
+        data = await self._safe_get(url, params=params, session=session)
+        bounded_limit = max(1, min(limit, 40))
+        candidates = []
+
+        categories = [
+            ("posters", "poster"),
+            ("backdrops", "backdrop"),
+            ("logos", "clearlogo"),
+        ]
+
+        for cat_key, canonical_type in categories:
+            items = data.get(cat_key) or []
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                file_path = item.get("file_path")
+                if not file_path:
+                    continue
+                raw_url = f"https://image.tmdb.org/t/p/original{file_path}"
+                preview_url = f"https://image.tmdb.org/t/p/w500{file_path}"
+                cand_id = self.candidate_cache.register_candidate(
+                    {
+                        "provider": "themoviedb.org",
+                        "raw_url": raw_url,
+                        "image_type": canonical_type,
+                        "target_id": str(tmdb_id),
+                    },
+                    user_id=user_id,
+                    chat_id=chat_id,
+                    operation="image_artwork",
+                )
+                candidates.append({
+                    "candidate_id": cand_id,
+                    "image_type": canonical_type,
+                    "preview_url": preview_url,
+                    "full_url": raw_url,
+                    "width": item.get("width"),
+                    "height": item.get("height"),
+                    "vote_average": item.get("vote_average"),
+                    "provider": "themoviedb.org",
+                })
+                if len(candidates) >= bounded_limit:
+                    break
+            if len(candidates) >= bounded_limit:
+                break
+
+        return candidates
+
+    # ==========================================================================
+    # 2. Free Stremio Cinemeta (No API Key Required)
+    # ==========================================================================
+
+    async def cinemeta_search(
+        self,
+        query: str,
+        media_type: str = "movie",
+        limit: int = 10,
+        user_id: Optional[int] = None,
+        chat_id: Optional[int] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> List[Dict[str, Any]]:
+        """Search Stremio Cinemeta catalog (free, no API key required). Returns IMDb items with posters."""
+        clean_query = (query or "").strip()
+        if not clean_query:
+            return []
+
+        clean_type = "series" if str(media_type).lower() in ("tv", "series") else "movie"
+        encoded_query = urllib.parse.quote(clean_query)
+        url = f"https://v3-cinemeta.strem.io/catalog/{clean_type}/top/search={encoded_query}.json"
+
+        data = await self._safe_get(url, session=session)
+        metas = data.get("metas") or []
+        bounded_limit = max(1, min(limit, 20))
+        results = []
+
+        for m in metas[:bounded_limit]:
+            imdb_id = m.get("imdb_id") or m.get("id") or ""
+            name = m.get("name") or "Unknown"
+            year = m.get("year")
+            poster_url = m.get("poster")
+            cand_id = None
+            if poster_url:
+                cand_id = self.candidate_cache.register_candidate(
+                    {
+                        "provider": "cinemeta",
+                        "raw_url": poster_url,
+                        "image_type": "poster",
+                        "target_id": imdb_id or name,
+                    },
+                    user_id=user_id,
+                    chat_id=chat_id,
+                    operation="image_artwork",
+                )
+
+            results.append({
+                "imdb_id": imdb_id,
+                "title": name,
+                "year": year,
+                "media_type": clean_type,
+                "poster_url": poster_url,
+                "candidate_id": cand_id,
+                "description": (m.get("description") or "")[:200],
+                "provider": "cinemeta (IMDb)",
+            })
+        return results
+
+    async def cinemeta_get_meta(
+        self,
+        imdb_id: str,
+        media_type: str = "movie",
+        user_id: Optional[int] = None,
+        chat_id: Optional[int] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> Dict[str, Any]:
+        """Fetch detailed metadata and high-res artwork from Cinemeta (free, no API key)."""
+        clean_id = (imdb_id or "").strip()
+        if not clean_id or not clean_id.startswith("tt"):
+            raise ValueError(f"Invalid IMDb ID: {imdb_id}. Must start with 'tt'.")
+
+        clean_type = "series" if str(media_type).lower() in ("tv", "series") else "movie"
+        url = f"https://v3-cinemeta.strem.io/meta/{clean_type}/{clean_id}.json"
+
+        data = await self._safe_get(url, session=session)
+        meta = data.get("meta") or {}
+
+        poster_url = meta.get("poster")
+        background_url = meta.get("background")
+        logo_url = meta.get("logo")
+
+        poster_cand = None
+        if poster_url:
+            poster_cand = self.candidate_cache.register_candidate(
+                {"provider": "cinemeta", "raw_url": poster_url, "image_type": "poster", "target_id": clean_id},
+                user_id=user_id,
+                chat_id=chat_id,
+                operation="image_artwork",
+            )
+
+        backdrop_cand = None
+        if background_url:
+            backdrop_cand = self.candidate_cache.register_candidate(
+                {"provider": "cinemeta", "raw_url": background_url, "image_type": "backdrop", "target_id": clean_id},
+                user_id=user_id,
+                chat_id=chat_id,
+                operation="image_artwork",
+            )
+
+        return {
+            "imdb_id": clean_id,
+            "title": meta.get("name") or "Unknown",
+            "year": meta.get("year"),
+            "media_type": clean_type,
+            "description": meta.get("description"),
+            "genres": meta.get("genres") or [],
+            "imdb_rating": meta.get("imdbRating"),
+            "poster_url": poster_url,
+            "poster_candidate_id": poster_cand,
+            "background_url": background_url,
+            "background_candidate_id": backdrop_cand,
+            "logo_url": logo_url,
+            "provider": "cinemeta (IMDb)",
+        }
+
+    # ==========================================================================
+    # 3. Free TVmaze (No API Key Required)
+    # ==========================================================================
+
+    async def tvmaze_search(
+        self,
+        query: str,
+        limit: int = 10,
+        user_id: Optional[int] = None,
+        chat_id: Optional[int] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> List[Dict[str, Any]]:
+        """Search TVmaze for TV shows and official artwork (free, no API key)."""
+        clean_query = (query or "").strip()
+        if not clean_query:
+            return []
+
+        encoded_query = urllib.parse.quote(clean_query)
+        url = f"https://api.tvmaze.com/search/shows?q={encoded_query}"
+
+        data = await self._safe_get(url, session=session)
+        bounded_limit = max(1, min(limit, 20))
+        results = []
+
+        if isinstance(data, list):
+            for item in data[:bounded_limit]:
+                show = item.get("show") or {}
+                image = show.get("image") or {}
+                poster_url = image.get("original") or image.get("medium")
+                cand_id = None
+                if poster_url:
+                    cand_id = self.candidate_cache.register_candidate(
+                        {
+                            "provider": "tvmaze",
+                            "raw_url": poster_url,
+                            "image_type": "poster",
+                            "target_id": str(show.get("id")),
+                        },
+                        user_id=user_id,
+                        chat_id=chat_id,
+                        operation="image_artwork",
+                    )
+
+                results.append({
+                    "show_id": show.get("id"),
+                    "title": show.get("name") or "Unknown",
+                    "premiered": show.get("premiered"),
+                    "genres": show.get("genres") or [],
+                    "rating": (show.get("rating") or {}).get("average"),
+                    "poster_url": poster_url,
+                    "candidate_id": cand_id,
+                    "summary": (show.get("summary") or "")[:200],
+                    "provider": "tvmaze",
+                })
+        return results
+
+    # ==========================================================================
+    # 4. Unified Artwork Search (Multi-Provider Fallback)
+    # ==========================================================================
+
+    async def artwork_search(
+        self,
+        query: Optional[str] = None,
+        imdb_id: Optional[str] = None,
+        tmdb_id: Optional[int] = None,
+        media_type: str = "movie",
+        limit: int = 15,
+        user_id: Optional[int] = None,
+        chat_id: Optional[int] = None,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> List[Dict[str, Any]]:
+        """Multi-provider artwork search across TMDb, Cinemeta, TVmaze, and Fanart.tv.
+        Guarantees posters & backdrops are found even if an API key is missing.
+        """
+        candidates: List[Dict[str, Any]] = []
+        bounded_limit = max(1, min(limit, 30))
+
+        # 1. Try TMDb images if tmdb_id or query is available and tmdb_key is configured
+        if self.tmdb_key:
+            target_tmdb_id = tmdb_id
+            if not target_tmdb_id and query:
+                try:
+                    hits = await self.tmdb_search(
+                        query=query,
+                        media_type=media_type,
+                        limit=3,
+                        user_id=user_id,
+                        chat_id=chat_id,
+                        session=session,
+                    )
+                    if hits:
+                        target_tmdb_id = hits[0].get("tmdb_id")
+                        if hits[0].get("poster_url"):
+                            candidates.append({
+                                "candidate_id": hits[0].get("poster_candidate_id"),
+                                "image_type": "poster",
+                                "preview_url": hits[0].get("poster_url"),
+                                "title": hits[0].get("title"),
+                                "provider": "themoviedb.org",
+                            })
+                except Exception as e:
+                    logger.debug(f"[ARTWORK-SEARCH] TMDb search skipped: {e}")
+
+            if target_tmdb_id:
+                try:
+                    tmdb_imgs = await self.tmdb_get_images(
+                        tmdb_id=target_tmdb_id,
+                        media_type=media_type,
+                        limit=bounded_limit,
+                        user_id=user_id,
+                        chat_id=chat_id,
+                        session=session,
+                    )
+                    candidates.extend(tmdb_imgs)
+                except Exception as e:
+                    logger.debug(f"[ARTWORK-SEARCH] TMDb get_images skipped: {e}")
+
+        # 2. Try Cinemeta (Free, no key needed) if IMDb ID or query is available
+        if len(candidates) < bounded_limit:
+            if imdb_id and imdb_id.startswith("tt"):
+                try:
+                    meta = await self.cinemeta_get_meta(
+                        imdb_id=imdb_id,
+                        media_type=media_type,
+                        user_id=user_id,
+                        chat_id=chat_id,
+                        session=session,
+                    )
+                    if meta.get("poster_url"):
+                        candidates.append({
+                            "candidate_id": meta.get("poster_candidate_id"),
+                            "image_type": "poster",
+                            "preview_url": meta.get("poster_url"),
+                            "title": meta.get("title"),
+                            "provider": "cinemeta (IMDb)",
+                        })
+                    if meta.get("background_url"):
+                        candidates.append({
+                            "candidate_id": meta.get("background_candidate_id"),
+                            "image_type": "backdrop",
+                            "preview_url": meta.get("background_url"),
+                            "title": meta.get("title"),
+                            "provider": "cinemeta (IMDb)",
+                        })
+                except Exception as e:
+                    logger.debug(f"[ARTWORK-SEARCH] Cinemeta get_meta skipped: {e}")
+
+            if len(candidates) < bounded_limit and query:
+                try:
+                    c_hits = await self.cinemeta_search(
+                        query=query,
+                        media_type=media_type,
+                        limit=5,
+                        user_id=user_id,
+                        chat_id=chat_id,
+                        session=session,
+                    )
+                    for ch in c_hits:
+                        if ch.get("poster_url"):
+                            candidates.append({
+                                "candidate_id": ch.get("candidate_id"),
+                                "image_type": "poster",
+                                "preview_url": ch.get("poster_url"),
+                                "title": ch.get("title"),
+                                "provider": "cinemeta (IMDb)",
+                            })
+                except Exception as e:
+                    logger.debug(f"[ARTWORK-SEARCH] Cinemeta search skipped: {e}")
+
+        # 3. Try TVmaze if TV series and query is provided (Free, no key needed)
+        if len(candidates) < bounded_limit and media_type in ("tv", "series") and query:
+            try:
+                tv_hits = await self.tvmaze_search(
+                    query=query,
+                    limit=5,
+                    user_id=user_id,
+                    chat_id=chat_id,
+                    session=session,
+                )
+                for th in tv_hits:
+                    if th.get("poster_url"):
+                        candidates.append({
+                            "candidate_id": th.get("candidate_id"),
+                            "image_type": "poster",
+                            "preview_url": th.get("poster_url"),
+                            "title": th.get("title"),
+                            "provider": "tvmaze",
+                        })
+            except Exception as e:
+                logger.debug(f"[ARTWORK-SEARCH] TVmaze search skipped: {e}")
+
+        # 4. Try Fanart.tv if fanart_key is configured
+        if len(candidates) < bounded_limit and self.fanart_key:
+            lookup_id = imdb_id or (str(tmdb_id) if tmdb_id else None)
+            if lookup_id:
+                try:
+                    f_imgs = await self.fanart_get_images(
+                        id_str=lookup_id,
+                        media_type=media_type,
+                        limit=bounded_limit,
+                        user_id=user_id,
+                        chat_id=chat_id,
+                        session=session,
+                    )
+                    candidates.extend(f_imgs)
+                except Exception as e:
+                    logger.debug(f"[ARTWORK-SEARCH] Fanart lookup skipped: {e}")
+
+        # Deduplicate candidates by preview_url
+        seen_urls = set()
+        deduped = []
+        for cand in candidates:
+            url = cand.get("preview_url") or cand.get("full_url")
+            if url and url in seen_urls:
+                continue
+            if url:
+                seen_urls.add(url)
+            deduped.append(cand)
+            if len(deduped) >= bounded_limit:
+                break
+
+        return deduped
+
     # ==========================================================================
-    # 2. Fanart.tv
+    # 5. Fanart.tv
     # ==========================================================================
 
     async def fanart_get_images(

ai_admin/tools_providers.py

@@ -93,6 +93,98 @@ def make_opensubtitles_search_handler(client: ProvidersClient):
     return handler
 
 
+def make_tmdb_get_images_handler(client: ProvidersClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        tmdb_id = params.get("tmdb_id")
+        media_type = params.get("media_type", "movie")
+        limit = params.get("limit", 20)
+        candidates = await client.tmdb_get_images(
+            tmdb_id=tmdb_id,
+            media_type=media_type,
+            limit=limit,
+        )
+        return {
+            "tmdb_id": tmdb_id,
+            "media_type": media_type,
+            "count": len(candidates),
+            "candidates": candidates,
+        }
+    return handler
+
+
+def make_cinemeta_search_handler(client: ProvidersClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        query = params.get("query", "")
+        media_type = params.get("media_type", "movie")
+        limit = params.get("limit", 10)
+        results = await client.cinemeta_search(
+            query=query,
+            media_type=media_type,
+            limit=limit,
+        )
+        return {
+            "query": query,
+            "media_type": media_type,
+            "count": len(results),
+            "results": results,
+            "provider": "cinemeta (IMDb)",
+        }
+    return handler
+
+
+def make_cinemeta_get_meta_handler(client: ProvidersClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        imdb_id = params.get("imdb_id", "")
+        media_type = params.get("media_type", "movie")
+        details = await client.cinemeta_get_meta(
+            imdb_id=imdb_id,
+            media_type=media_type,
+        )
+        return details
+    return handler
+
+
+def make_tvmaze_search_handler(client: ProvidersClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        query = params.get("query", "")
+        limit = params.get("limit", 10)
+        results = await client.tvmaze_search(
+            query=query,
+            limit=limit,
+        )
+        return {
+            "query": query,
+            "count": len(results),
+            "results": results,
+            "provider": "tvmaze",
+        }
+    return handler
+
+
+def make_artwork_search_handler(client: ProvidersClient):
+    async def handler(params: Dict[str, Any]) -> Dict[str, Any]:
+        query = params.get("query")
+        imdb_id = params.get("imdb_id")
+        tmdb_id = params.get("tmdb_id")
+        media_type = params.get("media_type", "movie")
+        limit = params.get("limit", 15)
+        candidates = await client.artwork_search(
+            query=query,
+            imdb_id=imdb_id,
+            tmdb_id=tmdb_id,
+            media_type=media_type,
+            limit=limit,
+        )
+        return {
+            "query": query,
+            "imdb_id": imdb_id,
+            "tmdb_id": tmdb_id,
+            "count": len(candidates),
+            "candidates": candidates,
+        }
+    return handler
+
+
 # ==============================================================================
 # Tool Definitions
 # ==============================================================================
@@ -145,6 +237,115 @@ def get_provider_read_tool_definitions(client: ProvidersClient) -> List[ToolDefi
             max_output_chars=4000,
             handler=make_tmdb_get_details_handler(client),
         ),
+        ToolDefinition(
+            name="tmdb_get_images",
+            purpose="Fetch all official posters, backdrops, and logos from TMDb by tmdb_id.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "tmdb_id": {"type": "integer"},
+                    "media_type": {"type": "string", "maxLength": 10},
+                    "limit": {"type": "integer"},
+                },
+                "required": ["tmdb_id"],
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=15,
+            max_output_chars=4000,
+            handler=make_tmdb_get_images_handler(client),
+        ),
+        ToolDefinition(
+            name="cinemeta_search",
+            purpose="Search Stremio Cinemeta catalog (free, no API key required) for movies or series to get IMDb posters.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "maxLength": 100},
+                    "media_type": {"type": "string", "maxLength": 10},
+                    "limit": {"type": "integer"},
+                },
+                "required": ["query"],
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=15,
+            max_output_chars=4000,
+            handler=make_cinemeta_search_handler(client),
+        ),
+        ToolDefinition(
+            name="cinemeta_get_meta",
+            purpose="Fetch high-resolution poster and background from Cinemeta (free, no API key required) by IMDb ID.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "imdb_id": {"type": "string", "maxLength": 20},
+                    "media_type": {"type": "string", "maxLength": 10},
+                },
+                "required": ["imdb_id"],
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=15,
+            max_output_chars=4000,
+            handler=make_cinemeta_get_meta_handler(client),
+        ),
+        ToolDefinition(
+            name="tvmaze_search",
+            purpose="Search TVmaze for TV shows and official artwork (free, no API key required).",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "maxLength": 100},
+                    "limit": {"type": "integer"},
+                },
+                "required": ["query"],
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=15,
+            max_output_chars=4000,
+            handler=make_tvmaze_search_handler(client),
+        ),
+        ToolDefinition(
+            name="artwork_search",
+            purpose="Search posters and backdrops across multiple free and configured providers (TMDb, Cinemeta, TVmaze, Fanart.tv) with automatic fallback.",
+            json_schema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "maxLength": 100},
+                    "imdb_id": {"type": "string", "maxLength": 20},
+                    "tmdb_id": {"type": "integer"},
+                    "media_type": {"type": "string", "maxLength": 10},
+                    "limit": {"type": "integer"},
+                },
+                "additionalProperties": False,
+            },
+            read_only=True,
+            mutates=False,
+            risk="low",
+            requires_confirmation="never",
+            permission="read",
+            timeout_seconds=15,
+            max_output_chars=4000,
+            handler=make_artwork_search_handler(client),
+        ),
         ToolDefinition(
             name="fanart_get_images",
             purpose="Query Fanart.tv for high-resolution posters, clearlogos, banners, and backdrops.",

tests/ai_admin/test_provider_tools.py

@@ -463,3 +463,86 @@ def test_candidate_cache_expired_handle_fails_closed():
     # Entry must be pruned from cache
     assert cand_id not in short_cache._cache
 
+
+@pytest.mark.asyncio
+async def test_tmdb_get_images_mocked(mock_providers_client):
+    """Test TMDb images lookup returns candidates and covers posters and backdrops."""
+    mock_payload = {
+        "posters": [
+            {"file_path": "/poster1.jpg", "width": 1000, "height": 1500, "vote_average": 8.5},
+        ],
+        "backdrops": [
+            {"file_path": "/backdrop1.jpg", "width": 1920, "height": 1080, "vote_average": 9.0},
+        ],
+    }
+    with patch.object(mock_providers_client, "_safe_get", new=AsyncMock(return_value=mock_payload)):
+        images = await mock_providers_client.tmdb_get_images(tmdb_id=550, media_type="movie", user_id=1, chat_id=1)
+        assert len(images) == 2
+        assert images[0]["image_type"] == "poster"
+        assert "poster1.jpg" in images[0]["preview_url"]
+        assert images[0]["candidate_id"].startswith("cand_")
+
+
+@pytest.mark.asyncio
+async def test_cinemeta_search_and_get_meta(mock_providers_client):
+    """Test free Cinemeta provider search and metadata lookup."""
+    search_payload = {
+        "metas": [
+            {"id": "tt22797990", "name": "Khalifa", "year": "2023", "poster": "https://m.media-amazon.com/poster.jpg", "description": "Thriller"},
+        ]
+    }
+    with patch.object(mock_providers_client, "_safe_get", new=AsyncMock(return_value=search_payload)):
+        results = await mock_providers_client.cinemeta_search(query="khalifa", user_id=1, chat_id=1)
+        assert len(results) == 1
+        assert results[0]["title"] == "Khalifa"
+        assert results[0]["imdb_id"] == "tt22797990"
+        assert results[0]["candidate_id"] is not None
+
+    meta_payload = {
+        "meta": {
+            "name": "Khalifa",
+            "year": "2023",
+            "poster": "https://m.media-amazon.com/poster.jpg",
+            "background": "https://images.metahub.space/bg.jpg",
+            "genres": ["Action", "Thriller"],
+        }
+    }
+    with patch.object(mock_providers_client, "_safe_get", new=AsyncMock(return_value=meta_payload)):
+        details = await mock_providers_client.cinemeta_get_meta(imdb_id="tt22797990", user_id=1, chat_id=1)
+        assert details["title"] == "Khalifa"
+        assert details["poster_candidate_id"] is not None
+        assert details["background_candidate_id"] is not None
+
+
+@pytest.mark.asyncio
+async def test_tvmaze_search(mock_providers_client):
+    """Test free TVmaze provider search."""
+    tvmaze_payload = [
+        {
+            "show": {
+                "id": 169,
+                "name": "Breaking Bad",
+                "premiered": "2008-01-20",
+                "image": {"original": "https://static.tvmaze.com/bb.jpg"},
+            }
+        }
+    ]
+    with patch.object(mock_providers_client, "_safe_get", new=AsyncMock(return_value=tvmaze_payload)):
+        shows = await mock_providers_client.tvmaze_search(query="breaking bad", user_id=1, chat_id=1)
+        assert len(shows) == 1
+        assert shows[0]["title"] == "Breaking Bad"
+        assert shows[0]["candidate_id"] is not None
+
+
+@pytest.mark.asyncio
+async def test_artwork_search_fallback(mock_providers_client):
+    """Test unified artwork search combines TMDb and Cinemeta."""
+    with patch.object(mock_providers_client, "tmdb_search", new=AsyncMock(return_value=[])):
+        with patch.object(mock_providers_client, "cinemeta_search", new=AsyncMock(return_value=[
+            {"title": "Khalifa", "poster_url": "https://m.media-amazon.com/poster.jpg", "candidate_id": "cand_123"}
+        ])):
+            candidates = await mock_providers_client.artwork_search(query="khalifa", user_id=1, chat_id=1)
+            assert len(candidates) >= 1
+            assert candidates[0]["title"] == "Khalifa"
+            assert candidates[0]["provider"] == "cinemeta (IMDb)"
+

tests/ai_admin/test_stage6_e2e_integration.py

@@ -120,8 +120,8 @@ def test_stage6_exact_tool_count_and_absence_of_mutations(monkeypatch, tmp_path)
     registry = router.handler.registry
     registered_tools = registry.list_tools()
 
-    # Must contain exactly 8 tools
-    assert len(registered_tools) == 8, f"Expected 8 tools, got {len(registered_tools)}: {[t.name for t in registered_tools]}"
+    # Must contain exactly 13 read-only tools
+    assert len(registered_tools) == 13, f"Expected 13 tools, got {len(registered_tools)}: {[t.name for t in registered_tools]}"
 
     expected_tool_names = {
         "jellyfin_search",
@@ -130,13 +130,18 @@ def test_stage6_exact_tool_count_and_absence_of_mutations(monkeypatch, tmp_path)
         "jellyfin_get_media_info",
         "tmdb_search",
         "tmdb_get_details",
+        "tmdb_get_images",
+        "cinemeta_search",
+        "cinemeta_get_meta",
+        "tvmaze_search",
+        "artwork_search",
         "fanart_get_images",
         "opensubtitles_search",
     }
     actual_tool_names = {t.name for t in registered_tools}
     assert actual_tool_names == expected_tool_names
 
-    # All 8 tools must be strictly read-only
+    # All tools must be strictly read-only
     for tool in registered_tools:
         assert tool.read_only is True
         assert tool.mutates is False