feat: implement new recommendation services and profile system (#82)

* chore: upgrade Python version to 3.12 and update dependencies

* feat: implement new recommendation services and profile system

* refactor: streamline catalog fetching by integrating CatalogService and simplifying endpoint logic

* refactor: enhance recommendation services by consolidating utility functions and improving filtering logic

* feat: add default item limits and concurrency settings for recommendations

* feat: add minimum rating thresholds for theme-based recommendations and streamline creator recommendation logic

* feat: implement final score calculation for recommendations, enhancing scoring logic with quality adjustments

Author: TimilsinaBimal

.gitignore

@@ -47,3 +47,4 @@ logs/
 */ipynb_checkpoints/
 *.ipynb
 .vercel
+migration.py

.python-version

@@ -1 +1 @@
-3.10
+3.12

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
 
 WORKDIR /app
 

app/api/endpoints/catalogs.py

@@ -1,24 +1,14 @@
-import re
-
 from fastapi import APIRouter, HTTPException, Response
 from loguru import logger
 
-from app.api.endpoints.manifest import get_config_id
-from app.core.config import settings
 from app.core.security import redact_token
-from app.core.settings import UserSettings, get_default_settings
-from app.services.catalog_updater import catalog_updater
-from app.services.recommendation.engine import RecommendationEngine
-from app.services.stremio.service import StremioBundle
-from app.services.token_store import token_store
-
-MAX_RESULTS = 50
-DEFAULT_MIN_ITEMS = 20
-DEFAULT_MAX_ITEMS = 32
-SOURCE_ITEMS_LIMIT = 10
+from app.services.recommendation.catalog_service import CatalogService
 
 router = APIRouter()
 
+# Initialize catalog service (singleton)
+_catalog_service = CatalogService()
+
 
 def _clean_meta(meta: dict) -> dict:
     """Return a sanitized Stremio meta object without internal fields.
@@ -49,164 +39,27 @@ def _clean_meta(meta: dict) -> dict:
 
 @router.get("/{token}/catalog/{type}/{id}.json")
 async def get_catalog(type: str, id: str, response: Response, token: str):
-    if not token:
-        raise HTTPException(
-            status_code=400,
-            detail="Missing credentials token. Please open Watchly from a configured manifest URL.",
-        )
-
-    if type not in ["movie", "series"]:
-        logger.warning(f"Invalid type: {type}")
-        raise HTTPException(status_code=400, detail="Invalid type. Use 'movie' or 'series'")
-
-    # Supported IDs now include dynamic themes and item-based rows
-    if id != "watchly.rec" and not any(
-        id.startswith(p)
-        for p in (
-            "tt",
-            "watchly.theme.",
-            "watchly.item.",
-            "watchly.loved.",
-            "watchly.watched.",
-        )
-    ):
-        logger.warning(f"Invalid id: {id}")
-        raise HTTPException(
-            status_code=400,
-            detail=(  #
-                "Invalid id. Supported: 'watchly.rec', 'watchly.theme.<params>', 'watchly.item.<id>', or"
-                " specific item IDs."
-            ),
-        )
-
-    logger.info(f"[{redact_token(token)}] Fetching catalog for {type} with id {id}")
-
-    credentials = await token_store.get_user_data(token)
-    if not credentials:
-        raise HTTPException(status_code=401, detail="Invalid or expired token. Please reconfigure the addon.")
-
-    # Trigger lazy update if needed
-    if settings.AUTO_UPDATE_CATALOGS:
-        await catalog_updater.trigger_update(token, credentials)
+    """
+    Get catalog recommendations.
 
-    bundle = StremioBundle()
+    This endpoint delegates all logic to CatalogService facade.
+    """
     try:
-        # 1. Resolve Auth Key (with potential fallback to login)
-        auth_key = credentials.get("authKey")
-        email = credentials.get("email")
-        password = credentials.get("password")
-
-        is_valid = False
-        if auth_key:
-            try:
-                await bundle.auth.get_user_info(auth_key)
-                is_valid = True
-            except Exception:
-                pass
+        # Delegate to catalog service facade
+        recommendations, headers = await _catalog_service.get_catalog(token, type, id)
 
-        if not is_valid and email and password:
-            try:
-                auth_key = await bundle.auth.login(email, password)
-                credentials["authKey"] = auth_key
-                await token_store.update_user_data(token, credentials)
-            except Exception as e:
-                logger.error(f"Failed to refresh auth key during catalog fetch: {e}")
+        # Set response headers
+        for key, value in headers.items():
+            response.headers[key] = value
 
-        if not auth_key:
-            raise HTTPException(status_code=401, detail="Stremio session expired. Please reconfigure.")
-
-        # 2. Extract settings from credentials
-        settings_dict = credentials.get("settings", {})
-        user_settings = UserSettings(**settings_dict) if settings_dict else get_default_settings()
-        language = user_settings.language if user_settings else "en-US"
-
-        # 3. Fetch library once per request and reuse across recommendation paths
-        library_items = await bundle.library.get_library_items(auth_key)
-        engine = RecommendationEngine(
-            stremio_service=bundle,
-            language=language,
-            user_settings=user_settings,
-            token=token,
-            library_data=library_items,
-        )
-
-        # Resolve per-catalog limits (min/max)
-        def _get_limits() -> tuple[int, int]:
-            try:
-                cfg_id = get_config_id({"id": id})
-            except Exception:
-                cfg_id = id
-            try:
-                cfg = next((c for c in user_settings.catalogs if c.id == cfg_id), None)
-                if cfg and hasattr(cfg, "min_items") and hasattr(cfg, "max_items"):
-                    return int(cfg.min_items or DEFAULT_MIN_ITEMS), int(cfg.max_items or DEFAULT_MAX_ITEMS)
-            except Exception:
-                pass
-            return DEFAULT_MIN_ITEMS, DEFAULT_MAX_ITEMS
-
-        min_items, max_items = _get_limits()
-        # Enforce caps: min_items <= 20, max_items <= 32 and max >= min
-        try:
-            min_items = max(1, min(DEFAULT_MIN_ITEMS, int(min_items)))
-            max_items = max(min_items, min(DEFAULT_MAX_ITEMS, int(max_items)))
-        except (ValueError, TypeError):
-            logger.warning(
-                "Invalid min/max items values. Falling back to defaults. "
-                f"min_items={min_items}, max_items={max_items}"
-            )
-            min_items, max_items = DEFAULT_MIN_ITEMS, DEFAULT_MAX_ITEMS
-
-        # Handle item-based recommendations
-        if id.startswith("tt"):
-            engine.per_item_limit = max_items
-            recommendations = await engine.get_recommendations_for_item(item_id=id, media_type=type)
-            if len(recommendations) < min_items:
-                recommendations = await engine.pad_to_min(type, recommendations, min_items)
-            logger.info(f"Found {len(recommendations)} recommendations for {id}")
-
-        elif any(
-            id.startswith(p)
-            for p in (
-                "watchly.item.",
-                "watchly.loved.",
-                "watchly.watched.",
-            )
-        ):
-            # Extract actual item ID (tt... or tmdb:...)
-            item_id = re.sub(r"^watchly\.(item|loved|watched)\.", "", id)
-            engine.per_item_limit = max_items
-            recommendations = await engine.get_recommendations_for_item(item_id=item_id, media_type=type)
-            if len(recommendations) < min_items:
-                recommendations = await engine.pad_to_min(type, recommendations, min_items)
-            logger.info(f"Found {len(recommendations)} recommendations for item {item_id}")
-
-        elif id.startswith("watchly.theme."):
-            recommendations = await engine.get_recommendations_for_theme(
-                theme_id=id, content_type=type, limit=max_items
-            )
-            if len(recommendations) < min_items:
-                recommendations = await engine.pad_to_min(type, recommendations, min_items)
-            logger.info(f"Found {len(recommendations)} recommendations for theme {id}")
-
-        else:
-            recommendations = await engine.get_recommendations(
-                content_type=type, source_items_limit=SOURCE_ITEMS_LIMIT, max_results=max_items
-            )
-            if len(recommendations) < min_items:
-                recommendations = await engine.pad_to_min(type, recommendations, min_items)
-            logger.info(f"Found {len(recommendations)} recommendations for {type}")
-
-        logger.info(f"Returning {len(recommendations)} items for {type}")
-        response.headers["Cache-Control"] = "public, max-age=21600"  # 6 hours
+        # Clean and format metadata
         cleaned = [_clean_meta(m) for m in recommendations]
-        # remove none values
         cleaned = [m for m in cleaned if m is not None]
+
         return {"metas": cleaned}
 
     except HTTPException:
         raise
     except Exception as e:
         logger.exception(f"[{redact_token(token)}] Error fetching catalog for {type}/{id}: {e}")
         raise HTTPException(status_code=500, detail=str(e))
-    finally:
-        await bundle.close()

app/api/endpoints/manifest.py

@@ -14,57 +14,52 @@
 router = APIRouter()
 
 
+def get_catalogs_from_config(
+    user_settings: UserSettings, cat_id: str, default_name: str, default_movie: bool, default_series: bool
+):
+    catalogs = []
+    config = next((c for c in user_settings.catalogs if c.id == cat_id), None)
+    if not config or config.enabled:
+        name = config.name if config and config.name else default_name
+        enabled_movie = getattr(config, "enabled_movie", default_movie) if config else default_movie
+        enabled_series = getattr(config, "enabled_series", default_series) if config else default_series
+
+        if enabled_movie:
+            catalogs.append({"type": "movie", "id": cat_id, "name": name, "extra": []})
+        if enabled_series:
+            catalogs.append({"type": "series", "id": cat_id, "name": name, "extra": []})
+    return catalogs
+
+
 def get_base_manifest(user_settings: UserSettings | None = None):
-    # Default catalog config
-    rec_config = None
-    if user_settings:
-        # Find config for 'recommended'
-        rec_config = next((c for c in user_settings.catalogs if c.id == "watchly.rec"), None)
+    catalogs = []
 
-    # If disabled explicitly, don't include it.
-    # If not configured (None), default to enabled.
-    if rec_config and not rec_config.enabled:
-        catalogs = []
+    if user_settings:
+        catalogs.extend(get_catalogs_from_config(user_settings, "watchly.rec", "Top Picks for You", True, True))
+        catalogs.extend(
+            get_catalogs_from_config(user_settings, "watchly.creators", "From your favourite Creators", False, False)
+        )
     else:
-        name = rec_config.name if rec_config and rec_config.name else "Top Picks for You"
-        enabled_movie = getattr(rec_config, "enabled_movie", True) if rec_config else True
-        enabled_series = getattr(rec_config, "enabled_series", True) if rec_config else True
-
+        # Default: empty catalogs
         catalogs = []
-        if enabled_movie:
-            catalogs.append(
-                {
-                    "type": "movie",
-                    "id": "watchly.rec",
-                    "name": name,
-                    "extra": [],
-                }
-            )
-        if enabled_series:
-            catalogs.append(
-                {
-                    "type": "series",
-                    "id": "watchly.rec",
-                    "name": name,
-                    "extra": [],
-                }
-            )
 
     return {
         "id": settings.ADDON_ID,
         "version": __version__,
         "name": settings.ADDON_NAME,
         "description": "Movie and series recommendations based on your Stremio library",
         "logo": "https://raw.githubusercontent.com/TimilsinaBimal/Watchly/refs/heads/main/app/static/logo.png",
-        "background": "https://raw.githubusercontent.com/TimilsinaBimal/Watchly/refs/heads/main/app/static/cover.png",
+        "background": ("https://raw.githubusercontent.com/TimilsinaBimal/Watchly/refs/heads/main/app/static/cover.png"),
         "resources": ["catalog"],
         "types": ["movie", "series"],
         "idPrefixes": ["tt"],
         "catalogs": catalogs,
         "behaviorHints": {"configurable": True, "configurationRequired": False},
         "stremioAddonsConfig": {
             "issuer": "https://stremio-addons.net",
-            "signature": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..ycLGL5WUjggv7PxKPqMLYQ.Y_cD-8wqoXqENdXbFmR1-Si39NtqBlsxEDdrEO0deciilBsWWAlPIglx85XFE4ScSfSqzNxrCZUjHjWWIb2LdcFuvE1RVBrFsUBXgbs5eQknnEL617pFtCWNh0bi37Xv.zYhJ87ZqcYZMRfxLY0bSGQ",  # noqa
+            "signature": (
+                "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..WSrhzzlj1TuDycD6QoVLuA.Dzmxzr4y83uqQF15r4tC1bB9-vtZRh1Rvy4BqgDYxu91c2esiJuov9KnnI_cboQCgZS7hjwnIqRSlQ-jEyGwXHHRerh9QklyfdxpXqNUyBgTWFzDOVdVvDYJeM_tGMmR.sezAChlWGV7lNS-t9HWB6A"  # noqa
+            ),
         },
     }
 
@@ -79,8 +74,7 @@ async def build_dynamic_catalogs(bundle: StremioBundle, auth_key: str, user_sett
 
 
 async def _manifest_handler(response: Response, token: str):
-    response.headers["Cache-Control"] = "public, max-age=300"  # 5 minutes
-
+    # response.headers["Cache-Control"] = "public, max-age=300"  # 5 minutes
     if not token:
         raise HTTPException(status_code=401, detail="Missing token. Please reconfigure the addon.")
 

app/core/constants.py

@@ -1 +1,9 @@
 RECOMMENDATIONS_CATALOG_NAME: str = "Top Picks For You"
+DEFAULT_MIN_ITEMS: int = 20
+DEFAULT_MAX_ITEMS: int = 32
+
+DEFAULT_CONCURRENCY_LIMIT: int = 30
+
+
+DEFAULT_MINIMUM_RATING_FOR_THEME_BASED_MOVIE: float = 7.2
+DEFAULT_MINIMUM_RATING_FOR_THEME_BASED_TV: float = 6.8

app/core/settings.py

@@ -37,6 +37,13 @@ def get_default_settings() -> UserSettings:
                 enabled_movie=True,
                 enabled_series=True,
             ),
+            CatalogConfig(
+                id="watchly.creators",
+                name="From your favourite Creators",
+                enabled=True,
+                enabled_movie=True,
+                enabled_series=True,
+            ),
         ],
     )
 

app/core/version.py

@@ -1 +1 @@
-__version__ = "1.4.3"
+__version__ = "1.4.4"