from __future__ import annotations import json import time from collections.abc import Iterable 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]) -> None: if not documents: return self._check(self.session.post( f"{self.url}/indexes/{self.index}/documents", params={"primaryKey": "id"}, json=documents, )) def wait_for_task(self, task_uid: int, *, timeout_seconds: float = 120) -> dict: deadline = time.monotonic() + timeout_seconds while True: task = self._check( self.session.get(f"{self.url}/tasks/{task_uid}") ).json() 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 time.monotonic() >= deadline: raise RuntimeError( f"Timed out waiting for Meilisearch task {task_uid}" ) time.sleep(0.1) def update_documents( self, documents: list[dict], *, wait: bool = False, ) -> None: """Partially update existing documents without replacing omitted fields.""" if not documents: return self.ensure_index() response = self._check( self.session.post( 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_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()