cine-rec-engine 0.4.0__py3-none-any.whl

cine_rec_engine/__init__.py

@@ -0,0 +1,6 @@
+"""cine-rec-engine — content-based movie & series recommendations from your own PostgreSQL."""
+
+from .service import RecommendationService
+
+__version__ = "0.4.0"
+__all__ = ["RecommendationService", "__version__"]

cine_rec_engine/cache.py

@@ -0,0 +1,115 @@
+"""Cache layer for the engine: Redis when available, in-process TTL otherwise.
+
+The engine touches the cache through a tiny async surface —
+``get / set / set_nx / exists / delete / is_connected`` — so any client
+implementing it plugs in (we ship one below). If a Redis URL is
+configured via ``CINE_REC_REDIS_URL`` we lazily connect with ``redis``
+(asyncio); otherwise a per-process TTL dict keeps everything working
+with zero infrastructure.
+
+Every cache call in the engine is wrapped in ``try/except`` and degrades
+on failure — a cache outage must never break a recommendation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from typing import Any, Optional
+
+_client: Any = None
+_client_checked = False
+_fallback: Optional["_TTLCache"] = None
+
+
+class _TTLCache:
+    """Minimal async cache with TTL + NX semantics (single-process)."""
+
+    def __init__(self) -> None:
+        self._data: dict = {}
+        self._lock = asyncio.Lock()
+
+    def is_connected(self) -> bool:
+        return True
+
+    async def get(self, key: str) -> Any:
+        async with self._lock:
+            item = self._data.get(key)
+            if item is None:
+                return None
+            value, expires = item
+            if expires is not None and expires < time.monotonic():
+                del self._data[key]
+                return None
+            # JSON round-trip so callers see the same shape as Redis gives
+            try:
+                return json.loads(value)
+            except (TypeError, ValueError):
+                return value
+
+    async def set(self, key: str, value: Any, ttl: Optional[int] = None) -> Any:
+        async with self._lock:
+            serialized = json.dumps(value, default=str)
+            self._data[key] = (serialized, time.monotonic() + ttl if ttl is not None else None)
+            return True
+
+    async def set_nx(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
+        async with self._lock:
+            item = self._data.get(key)
+            if item is not None:
+                expires = item[1]
+                if expires is None or expires >= time.monotonic():
+                    return False
+                del self._data[key]
+            self._data[key] = (json.dumps(value, default=str),
+                               time.monotonic() + ttl if ttl is not None else None)
+            return True
+
+    async def exists(self, key: str) -> bool:
+        return await self.get(key) is not None
+
+    async def delete(self, key: str) -> None:
+        async with self._lock:
+            self._data.pop(key, None)
+
+
+async def get_cache() -> Any:
+    """Return a cache client, or None if nothing is available.
+
+    Priority: Redis (``CINE_REC_REDIS_URL``) → in-process TTL cache.
+    Redis is probed once per process; afterwards the decision sticks
+    unless a live connection errors out.
+    """
+    global _client, _client_checked, _fallback
+
+    if not _client_checked:
+        _client_checked = True
+        url = os.getenv("CINE_REC_REDIS_URL")
+        if url:
+            try:
+                import redis.asyncio as aioredis  # type: ignore
+
+                _client = aioredis.from_url(
+                    url, decode_responses=True, socket_timeout=2,
+                    socket_connect_timeout=2,
+                )
+                await _client.ping()
+            except Exception:
+                _client = None
+
+    if _client is not None:
+        try:
+            if await _client.ping():
+                return _client
+        except Exception:
+            _client = None  # Redis died mid-flight — fall through to local
+    elif _fallback is not None:
+        # Redis was already ruled out this process; stay local without
+        # re-probing on every call (a recommendation path must not ping).
+        return _fallback
+
+    if _fallback is None:
+        _fallback = _TTLCache()
+    return _fallback

cine_rec_engine/config.py

@@ -0,0 +1,221 @@
+"""Scoring configuration for the recommendation engine.
+
+Tuned feature weights for the similarity scorer (see weights.json provenance).
+"""
+
+# Scoring weights for recommendation components
+COMPANY_SIMILARITY_WEIGHT: float = 0.75  # Production company overlap — a weak taste signal
+# (Warner Bros produced half the action catalog; at 3.0 it drowned semantics)
+COLLECTION_MATCH_BONUS: float = 2.0  # Same franchise/collection (flat +2)
+NETWORK_MATCH_BONUS: float = 2.0  # Shared TV network (flat +2, TV only)
+# Director DNA — person-id match from tmdb_crew (name-string match kept as
+# fallback for rows the crew backfill hasn't reached yet). The channel bonus
+# rides on top for candidates the director channel recalled: by construction
+# they share the seed's director person_id, the strongest auteur signal the
+# overview vectors cannot see (Coen brothers never match by name string).
+DIRECTOR_MATCH_BONUS: float = 3.0
+# Modest on purpose: writer/cast/behavioral signals carry the rest of the
+# auteur signal, so the channel bonus only nudges.
+DIRECTOR_CHANNEL_BONUS: float = 3.0
+# Writer DNA — a shared screenwriter links taste clusters the director
+# signal can't see (Taylor Sheridan's Sicario / Hell or High Water / Wind
+# River are different directors, one voice). Weaker than an auteur stamp,
+# so it starts lower and applies once per pair (match or channel recall).
+WRITER_BONUS: float = 3.5
+# Behavioral signal — a title TMDB's own users ranked in the seed's top
+# recommendations ("people also watched"). Today it only escapes the
+# genre gate; this gives the rank-1-3 recalls real points.
+TMDB_REC_BONUS: float = 3.5
+# Auteur diversification — geometric decay per additional same-director
+# title in the final list (first keeps full score). (1.0, 1.0, 1.0) = off;
+# diversification is handled by MMR instead.
+AUTEUR_DECAY_FACTORS: tuple = (1.0, 1.0, 1.0)
+# Genre-conditional auteur decay (7c): the second-plus same-director title
+# whose genres share NOTHING with the seed decays by this factor — Sicario
+# (Crime) under Arrival (Sci-Fi/Drama) is director brand without a thematic
+# bridge, while Dune (Sci-Fi) keeps its full auteur score.
+GENRE_MISMATCH_AUTEUR_FACTOR: float = 0.5
+# --- MMR selection (step 7d) ------------------------------------------
+# Greedy Maximal Marginal Relevance over the ranked list before the final
+# limit: score(c) = λ·relevance_norm − (1−λ)·max_sim(c, selected).
+# Relevance is min-max normalized per list so both terms live in [0,1]
+# and λ has true 70/30 meaning. Similarity is graded: same collection 1.0
+# (sequel pile-up), shared director 0.85 (a second masterpiece can still
+# surface), genre Jaccard capped at 0.5 (genre overlap must not erase
+# good picks). Replaces the point-penalty decays as THE diversifier.
+MMR_ENABLED: bool = True
+MMR_LAMBDA: float = 0.8  # tuned for a 70/30 relevance/diversity balance
+# Pop-action leak damper — mega-vote titles (>10k votes) whose semantic
+# similarity to the seed is below the floor lose POP_ACTION_PENALTY:
+# Transformers has genre/company connectivity with Arrival but zero
+# thematic overlap, and the light −1.0 popularity damping never stopped it.
+POP_ACTION_SIM_FLOOR: float = 0.30
+# 0.0 — off; the similarity floor above does the gating.
+POP_ACTION_PENALTY: float = 0.0
+
+# Genre priority weights — uniform 1.0 for most genres, with selective
+# boosts for strong secondary-genre signals.
+# - Music 1.5: when someone searches for a musical (telenovela, teen pop),
+#   other musicals should outrank non-musical matches in the same tone
+#   (a teen musical should steer toward other teen musicals).
+# - Soap 1.3: telenovela format is a strong affinity signal.
+# The old values (Mystery=1.6 vs Family=0.7) actively suppressed light
+# content: a user searching for a teen musical got dark fantasy because
+# dark genres "scored more" per match. Genre matching should reflect
+# similarity, not prestige. Only truly niche formats get < 1.0.
+GENRE_PRIORITY: dict[str, float] = {
+    "Mystery": 1.0,
+    "Psychological": 1.0,
+    "Science Fiction": 1.0,
+    "Horror": 1.0,
+    "Thriller": 1.0,
+    "Crime": 1.0,
+    "Fantasy": 1.0,
+    "Action": 1.0,
+    "War": 1.0,
+    "History": 1.0,
+    "Western": 1.0,
+    "Adventure": 1.0,
+    "Drama": 1.0,
+    "Comedy": 1.0,
+    "Romance": 1.0,
+    "Animation": 1.0,
+    "Family": 1.0,
+    "Music": 1.5,
+    "Soap": 1.3,
+    "Documentary": 0.5,
+}
+
+# Keyword → style mapping for style matching (+3 points)
+KEYWORDS_STYLE: dict[str, set[str]] = {
+    "mind-bending": {
+        "dream",
+        "subconscious",
+        "lucid dream",
+        "virtual reality",
+        "simulation",
+        "manipulation",
+        "memory loss",
+        "amnesia",
+        "alternate reality",
+        "hallucination",
+        "unreliable narrator",
+        "mind game",
+        "twist ending",
+        "psychological thriller",
+    },
+    "cyberpunk/dystopian": {
+        "cyberpunk",
+        "dystopia",
+        "artificial intelligence",
+        "android",
+        "transhumanism",
+        "megacorporation",
+        "post-apocalyptic",
+    },
+    "time-travel": {
+        "time travel",
+        "time loop",
+        "temporal paradox",
+        "parallel timeline",
+        "multiverse",
+    },
+    "noir": {
+        "neo-noir",
+        "femme fatale",
+        "cynical detective",
+        "dark city",
+        "gritty",
+        "conspiracy",
+    },
+    "buddy cop": {"buddy cop", "bromance", "police partners"},
+    "parody": {"parody", "satire", "spoof"},
+    "slapstick": {"absurd", "slapstick", "over-the-top"},
+}
+
+# Semantic (pgvector KNN) candidate recall: top-N nearest overview
+# embeddings fetched per seed IN ADDITION to the genre+popularity candidates.
+# Surfaces titles that are close in spirit but would never pass the
+# genre-overlap + popularity ordering of the classic recall path.
+KNN_CANDIDATES_PER_SEED: int = 60
+
+# Local catalog stores Hebrew genre labels ('מותחן', 'מסתורין') while the
+# scoring tables (GENRE_PRIORITY, style matching) use canonical English.
+# Map every label found in tmdb_genres so priority weighting actually fires.
+GENRE_LABELS_EN: dict[str, str] = {
+    "אימה": "Horror",
+    "אנימציה": "Animation",
+    "אקשן": "Action",
+    "אקשן והרפתקאות": "Action",
+    "דוקומנטרי": "Documentary",
+    "דיבורים": "Talk Show",
+    "דרמה": "Drama",
+    "הסטוריה": "History",
+    "הרפתקאות": "Adventure",
+    "חדשות": "News",
+    "ילדים": "Family",
+    "מדע בדיוני": "Science Fiction",
+    "מדע בדיוני ופנטזיה": "Science Fiction",
+    "מוסיקה": "Music",
+    "מותחן": "Thriller",
+    "מלחמה": "War",
+    "מלחמה ופוליטיקה": "War",
+    "מסתורין": "Mystery",
+    "מערבון": "Western",
+    "משפחה": "Family",
+    "סבון": "Soap",
+    "סרט טלויזיה": "TV Movie",
+    "פנטזיה": "Fantasy",
+    "פשע": "Crime",
+    "קומדיה": "Comedy",
+    "רומנטי": "Romance",
+    "ריאליטי": "Reality",
+}
+
+# Candidates below this many TMDB votes are dropped during pre-filtering —
+# thin-voted oddities (old/niche titles with a lucky 6.5) should not crowd
+# proven classics out of the shortlist.
+MIN_VOTE_COUNT: int = 500
+
+# Media-type-aware vote floors (channels AND the pre-filter). Measured on
+# a lower TV floor (100/200) widens series recall
+# but nets -0.2 (noise outweighs hits), so both stay 500 for now — the
+# plumbing remains so the split can be revisited with better tv embeddings.
+VOTE_FLOOR_MOVIE: int = 500
+VOTE_FLOOR_TV: int = 500
+
+
+# ----------------------------------------------------------------------------
+# Embedding space — "original" (384-dim MiniLM, column `embedding`) or
+# "v4b" (768-dim fine-tuned bge, column `embedding_v4`). All engine reads
+# (both KNN channels + the cosine feature) follow this switch; embeddings
+# are written by scripts/eval/embed_catalog_v4.py with the canonical text.
+# ----------------------------------------------------------------------------
+import os
+
+REC_EMBEDDING_SPACE = os.getenv("CINE_REC_EMBEDDING", os.getenv("REC_EMBEDDING", "original"))
+# Bake-off spaces map to their embedding_<name> columns; "v4b" keeps its
+# historical name and "original" the legacy 384-dim column.
+EMBEDDING_COLUMN = {
+    "v4b": "embedding_v4",
+    "original": "embedding",
+}.get(REC_EMBEDDING_SPACE, f"embedding_{REC_EMBEDDING_SPACE}")
+
+
+# Optional cosine blend across several embedding columns:
+#   REC_COSINE_BLEND="embedding_mpnetae:32.0,embedding_e5e:8.0,embedding_mpnetan:4.0"
+# The final-score cosine becomes sum(w_i/sum(w) * cos_i) * cosine_sim_weight.
+# Retrieval (KNN) stays on EMBEDDING_COLUMN — the blend rescores candidates.
+def _parse_cosine_blend(raw: str) -> dict:
+    blend = {}
+    for part in (raw or "").split(","):
+        if ":" in part:
+            col, w = part.rsplit(":", 1)
+            try:
+                blend[col.strip()] = float(w)
+            except ValueError:
+                continue
+    return {c: w for c, w in blend.items() if w > 0}
+
+
+COSINE_BLEND: dict = _parse_cosine_blend(os.getenv("CINE_REC_COSINE_BLEND", os.getenv("REC_COSINE_BLEND", "")))

cine_rec_engine/model_spaces.py

@@ -0,0 +1,61 @@
+"""Embedding space registry — the seam between engine and models.
+
+The engine's KNN recall channel and cosine-blend feature read OVERVIEW
+EMBEDDINGS from columns on ``tmdb_media``. Which column(s) exist is a
+property of YOUR database: you generate embeddings with whichever
+sentence-encoder you like (see ``models/README.md``), store them as
+``vector`` columns, and register them here.
+
+Each entry names:
+- ``column``: the tmdb_media column holding the vectors (None = the
+  tuned multi-model ensemble driven by config.COSINE_BLEND).
+- ``cosine_weight``: the cosine_sim feature weight to use when this
+  space is selected solo (overrides the tuned default).
+
+The published ``weights.json`` was tuned on the ensemble space; solo
+weights below are safe defaults, not fitted constants.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+REC_MODELS: dict = {
+    "ensemble": {
+        "column": None,
+        "cosine_weight": None,
+    },
+    "e5e": {
+        "column": "embedding_e5e",
+        "cosine_weight": 26.0,
+    },
+    "mpnetae": {
+        "column": "embedding_mpnetae",
+        "cosine_weight": 26.0,
+    },
+    "mpnetan": {
+        "column": "embedding_mpnetan",
+        "cosine_weight": 26.0,
+    },
+    "v4": {
+        "column": "embedding_v4",
+        "cosine_weight": 10.0,
+    },
+}
+
+
+def normalize_model(name: Optional[str]) -> Optional[str]:
+    """Case-insensitive match against REC_MODELS, or None."""
+    if not name:
+        return None
+    low = name.strip().lower()
+    for key in REC_MODELS:
+        if key.lower() == low:
+            return key
+    return None
+
+
+def is_solo(model_key: str) -> bool:
+    """True when the key selects a single embedding column."""
+    spec = REC_MODELS.get(model_key)
+    return bool(spec and spec["column"])