from __future__ import annotations import json import time from collections.abc import Iterable from typing import Callable import requests class Meili: def __init__(self, url: str, master_key: str, index: str) -> None: self.url = url.rstrip("/") self.index = index self.session = requests.Session() if master_key: self.session.headers.update({"Authorization": f"Bearer {master_key}"}) self.session.headers.update({"Content-Type": "application/json"}) def _check(self, response: requests.Response) -> requests.Response: if not response.ok: raise RuntimeError(f"Meilisearch {response.status_code}: {response.text}") return response @staticmethod def _json_vector(vector: Iterable[float]) -> list[float]: """Convert NumPy/PyTorch scalar values into JSON-native floats.""" return [float(value) for value in vector] def ensure_index(self) -> None: r = self.session.get(f"{self.url}/indexes/{self.index}") if r.status_code == 404: self._check(self.session.post( f"{self.url}/indexes", json={"uid": self.index, "primaryKey": "id"}, )) else: self._check(r) def configure_user_vectors(self, dimensions: int) -> None: self.ensure_index() self._check(self.session.patch( f"{self.url}/indexes/{self.index}/settings/embedders", json={"siglip2": {"source": "userProvided", "dimensions": dimensions}}, )) self._check(self.session.put( f"{self.url}/indexes/{self.index}/settings/filterable-attributes", json=[ "media_id", "title", "caption_model", "caption_route", "route_model", "source_kind", "jellyfin_item_id", "jellyfin_library_id", "jellyfin_item_type", "jellyfin_tags", ], )) self._check(self.session.put( f"{self.url}/indexes/{self.index}/settings/searchable-attributes", json=["title", "caption", "jellyfin_tags"], )) def clear_documents(self) -> None: self.ensure_index() self._check(self.session.delete( f"{self.url}/indexes/{self.index}/documents", )) def add_documents( self, documents: list[dict], *, wait: bool = False, ) -> int | None: """Replace complete documents (used for indexing and targeted repairs).""" if not documents: return response = self._check(self.session.post( f"{self.url}/indexes/{self.index}/documents", params={"primaryKey": "id"}, json=documents, )) task_uid = response.json().get("taskUid") if task_uid is None: if wait: raise RuntimeError("Meilisearch replacement did not return a taskUid") return None task_uid = int(task_uid) if wait: self.wait_for_task(task_uid) return task_uid def get_task(self, task_uid: int) -> dict: """Read the durable status of an asynchronous Meilisearch task.""" return self._check( self.session.get(f"{self.url}/tasks/{task_uid}", timeout=15) ).json() def wait_for_task( self, task_uid: int, *, timeout_seconds: float | None = 120, poll_seconds: float = 2.0, on_poll: Callable[[dict], None] | None = None, ) -> dict: """Wait for a task. None timeout permits an intentionally long repair.""" deadline = ( time.monotonic() + timeout_seconds if timeout_seconds is not None else None ) while True: task = self.get_task(task_uid) status = str(task.get("status") or "") if status == "succeeded": return task if status in {"failed", "canceled"}: error = task.get("error") or {} message = error.get("message") if isinstance(error, dict) else error raise RuntimeError( f"Meilisearch task {task_uid} {status}: " f"{message or task}" ) if on_poll is not None: on_poll(task) if deadline is not None and time.monotonic() >= deadline: raise RuntimeError( f"Timed out waiting for Meilisearch task {task_uid} " f"(last status: {status or 'unknown'})" ) time.sleep(max(0.1, poll_seconds)) def update_documents( self, documents: list[dict], *, wait: bool = False, ) -> None: """Update only supplied caption fields, preserving identities and vectors. POST replaces an entire Meilisearch document; PUT is the partial-update endpoint. Using POST here previously deleted titles, Jellyfin item IDs, and SigLIP vectors whenever a caption was synchronised. """ if not documents: return self.ensure_index() response = self._check( self.session.put( f"{self.url}/indexes/{self.index}/documents", params={"primaryKey": "id"}, json=documents, ) ) if wait: task_uid = response.json().get("taskUid") if task_uid is None: raise RuntimeError( "Meilisearch update did not return a taskUid" ) self.wait_for_task(int(task_uid)) def delete_jellyfin_libraries(self, library_ids: list[str]) -> None: if not library_ids: return self.ensure_index() filter_expression = ( "jellyfin_library_id IN " + json.dumps(library_ids) ) self._check( self.session.post( f"{self.url}/indexes/{self.index}/documents/delete", json={"filter": filter_expression}, ) ) def stats(self) -> dict: self.ensure_index() return self._check( self.session.get(f"{self.url}/indexes/{self.index}/stats") ).json() def search_caption_text( self, query: str, limit: int = 20, filter_expression: str | None = None, ) -> dict: """Find literal caption matches without visual-vector dilution. The field restriction prevents title and tag matches from masquerading as caption hits. Requiring all terms avoids loose one-word matches displacing ordinary Jellyfin search results. """ payload = { "q": query, "limit": limit, "attributesToSearchOn": ["caption"], "matchingStrategy": "all", "showRankingScore": True, } if filter_expression: payload["filter"] = filter_expression return self._check(self.session.post( f"{self.url}/indexes/{self.index}/search", json=payload, )).json() def search_vector( self, vector: Iterable[float], query: str, limit: int = 10, semantic_ratio: float = 0.8, filter_expression: str | None = None, ) -> dict: payload = { "q": query, "vector": self._json_vector(vector), "hybrid": { "embedder": "siglip2", "semanticRatio": semantic_ratio, }, "limit": limit, "showRankingScore": True, } if filter_expression: payload["filter"] = filter_expression return self._check(self.session.post( f"{self.url}/indexes/{self.index}/search", json=payload, )).json()