marquee-ai 1.0.0__tar.gz

marquee_ai-1.0.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: marquee-ai
+Version: 1.0.0
+Summary: Marquee -- Plex-style recommendation rows for a media server library
+Author: KernelMedia
+License: Apache-2.0
+Project-URL: Homepage, https://huggingface.co/KernelMedia
+Keywords: recommendations,media-server,plex,jellyfin,llm
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: requests>=2.31
+Requires-Dist: sentence-transformers>=3.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: uvicorn>=0.27; extra == "api"
+Requires-Dist: pydantic>=2.6; extra == "api"
+Provides-Extra: harvest
+Requires-Dist: tqdm>=4.66; extra == "harvest"
+
+# Marquee
+
+Turns one item in a media library into Plex-style rows of other items in **that same
+library**. Built for self-hosted media servers.
+
+```
+IN:  "The Sopranos"
+
+OUT:
+  Shows like The Sopranos      Gomorrah, Boardwalk Empire, The Wire, ZeroZeroZero
+  More from Tim Van Patten     Game of Thrones, Black Mirror, Boardwalk Empire
+  More with Edie Falco         Nurse Jackie, Oz
+  Shot by Alik Sakharov        Game of Thrones, House of Cards
+```
+
+## Two halves, both required
+
+A **retriever** decides what goes in the rows, by joining your library on shared cast,
+crew and franchise and by embedding similarity. A small fine-tuned **model** decides
+which rows are worth showing, their order, and what to call them.
+
+The model never sees item ids — it answers with index references into candidates it was
+handed, so it cannot invent a title that isn't in your library.
+
+```bash
+pip install marquee-ai
+```
+
+Model weights: [KernelMedia/marquee-ai](https://huggingface.co/KernelMedia/marquee-ai)
+
+## Quickstart
+
+```bash
+# the model (needs ollama)
+ollama create marquee-4b -f Modelfile
+
+# metadata -- free TMDB key from themoviedb.org/settings/api
+echo 'TMDB_API_KEY=your_key' >> .env
+marquee harvest --out tmdb_full.jsonl        # ~55 min, ~120k titles
+
+# join it to your server's library
+marquee ingest --server library.jsonl --catalog tmdb_full.jsonl \
+               --out lib.jsonl --mode requestable
+
+# serve
+marquee serve --library lib.jsonl --model marquee-4b --port 8080
+```
+
+Your server exports one JSON object per line — only `tmdb_id` and `media_type` are
+required:
+
+```json
+{"id": "myserver-04471", "tmdb_id": 335984, "media_type": "movie"}
+```
+
+Anything missing from the harvest is fetched from TMDB on demand at ingest, so coverage
+is complete however you filtered.
+
+## API
+
+```bash
+POST /recommend   {"seed_id": "myserver-04471", "row_size": 20}
+GET  /search?q=Scorsese          # matches titles AND people
+GET  /person?name=Roger%20Deakins
+GET  /health
+DELETE /cache                    # after a library rescan
+```
+
+`/search` and `/person` are pure index lookups — no model call, effectively instant.
+Only `/recommend` uses the GPU.
+
+Items carry an `owned` flag, so a UI can offer a Request button on anything not on the
+server. Ambiguous titles return **409 with the candidates** rather than guessing —
+`Godzilla` matches three films. Narrow with `year` and `media_type`, or write
+`"Top Gun (1986)"` directly.
+
+## Use it as a library
+
+The HTTP API is optional. If your server is Python, skip it:
+
+```python
+from marquee import Library
+from marquee.contract import messages, parse, repair, expand_rows
+
+lib = Library.load("lib.jsonl")
+lib.build_embeddings(cache=Path("lib.emb.npz"))     # once at startup
+
+request = lib.build_request(seed_id, semantic_k=14, row_size=20)
+raw = call_your_llm(messages(request))              # any OpenAI-compatible endpoint
+rows = expand_rows(repair(parse(raw), request), request, 20)
+```
+
+## Requirements
+
+| | |
+|---|---|
+| VRAM | ~3.5 GB (Q4_K_M). Runs on a 4 GB card, or CPU. |
+| RAM | ~2.2 GB for a 120k-title catalog |
+| Latency | ~1 s per request on an RTX 3060; cached responses are instant |
+
+Full setup and troubleshooting: [SETUP.md](https://huggingface.co/KernelMedia/marquee-ai/blob/main/SETUP.md)
+
+## Data
+
+You harvest TMDB yourself with your own free key; no catalog is distributed. TMDB is
+free for non-commercial use and requires attribution — commercial use needs a written
+agreement with them.
+
+This product uses the TMDB API but is not endorsed or certified by TMDB.
+
+## Licence
+
+Apache-2.0.

marquee_ai-1.0.0/README.md

@@ -0,0 +1,113 @@
+# Marquee
+
+Turns one item in a media library into Plex-style rows of other items in **that same
+library**. Built for self-hosted media servers.
+
+```
+IN:  "The Sopranos"
+
+OUT:
+  Shows like The Sopranos      Gomorrah, Boardwalk Empire, The Wire, ZeroZeroZero
+  More from Tim Van Patten     Game of Thrones, Black Mirror, Boardwalk Empire
+  More with Edie Falco         Nurse Jackie, Oz
+  Shot by Alik Sakharov        Game of Thrones, House of Cards
+```
+
+## Two halves, both required
+
+A **retriever** decides what goes in the rows, by joining your library on shared cast,
+crew and franchise and by embedding similarity. A small fine-tuned **model** decides
+which rows are worth showing, their order, and what to call them.
+
+The model never sees item ids — it answers with index references into candidates it was
+handed, so it cannot invent a title that isn't in your library.
+
+```bash
+pip install marquee-ai
+```
+
+Model weights: [KernelMedia/marquee-ai](https://huggingface.co/KernelMedia/marquee-ai)
+
+## Quickstart
+
+```bash
+# the model (needs ollama)
+ollama create marquee-4b -f Modelfile
+
+# metadata -- free TMDB key from themoviedb.org/settings/api
+echo 'TMDB_API_KEY=your_key' >> .env
+marquee harvest --out tmdb_full.jsonl        # ~55 min, ~120k titles
+
+# join it to your server's library
+marquee ingest --server library.jsonl --catalog tmdb_full.jsonl \
+               --out lib.jsonl --mode requestable
+
+# serve
+marquee serve --library lib.jsonl --model marquee-4b --port 8080
+```
+
+Your server exports one JSON object per line — only `tmdb_id` and `media_type` are
+required:
+
+```json
+{"id": "myserver-04471", "tmdb_id": 335984, "media_type": "movie"}
+```
+
+Anything missing from the harvest is fetched from TMDB on demand at ingest, so coverage
+is complete however you filtered.
+
+## API
+
+```bash
+POST /recommend   {"seed_id": "myserver-04471", "row_size": 20}
+GET  /search?q=Scorsese          # matches titles AND people
+GET  /person?name=Roger%20Deakins
+GET  /health
+DELETE /cache                    # after a library rescan
+```
+
+`/search` and `/person` are pure index lookups — no model call, effectively instant.
+Only `/recommend` uses the GPU.
+
+Items carry an `owned` flag, so a UI can offer a Request button on anything not on the
+server. Ambiguous titles return **409 with the candidates** rather than guessing —
+`Godzilla` matches three films. Narrow with `year` and `media_type`, or write
+`"Top Gun (1986)"` directly.
+
+## Use it as a library
+
+The HTTP API is optional. If your server is Python, skip it:
+
+```python
+from marquee import Library
+from marquee.contract import messages, parse, repair, expand_rows
+
+lib = Library.load("lib.jsonl")
+lib.build_embeddings(cache=Path("lib.emb.npz"))     # once at startup
+
+request = lib.build_request(seed_id, semantic_k=14, row_size=20)
+raw = call_your_llm(messages(request))              # any OpenAI-compatible endpoint
+rows = expand_rows(repair(parse(raw), request), request, 20)
+```
+
+## Requirements
+
+| | |
+|---|---|
+| VRAM | ~3.5 GB (Q4_K_M). Runs on a 4 GB card, or CPU. |
+| RAM | ~2.2 GB for a 120k-title catalog |
+| Latency | ~1 s per request on an RTX 3060; cached responses are instant |
+
+Full setup and troubleshooting: [SETUP.md](https://huggingface.co/KernelMedia/marquee-ai/blob/main/SETUP.md)
+
+## Data
+
+You harvest TMDB yourself with your own free key; no catalog is distributed. TMDB is
+free for non-commercial use and requires attribution — commercial use needs a written
+agreement with them.
+
+This product uses the TMDB API but is not endorsed or certified by TMDB.
+
+## Licence
+
+Apache-2.0.

marquee_ai-1.0.0/marquee/__init__.py

@@ -0,0 +1,51 @@
+"""Marquee -- Plex-style recommendation rows for a media server library.
+
+The model is only half of this. It decides which rows to show and what to call them;
+the retriever decides what goes in them. Ship them together or neither works.
+
+    from marquee import Library, build_rows
+"""
+
+from .contract import (
+    CONTRACT_VERSION,
+    MAX_ROW_ITEMS,
+    MAX_ROWS,
+    ROW_ORDER,
+    SYSTEM_PROMPT,
+    expand_rows,
+    messages,
+    parse,
+    render_human,
+    repair,
+    response_format,
+    to_compact,
+    validate,
+    verify_model,
+)
+from .retriever import Library
+from .schema import MediaItem, Person, read_jsonl, write_jsonl
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "CONTRACT_VERSION",
+    "verify_model",
+    "to_compact",
+    "Library",
+    "MediaItem",
+    "Person",
+    "read_jsonl",
+    "write_jsonl",
+    "SYSTEM_PROMPT",
+    "ROW_ORDER",
+    "MAX_ROWS",
+    "MAX_ROW_ITEMS",
+    "messages",
+    "parse",
+    "repair",
+    "validate",
+    "expand_rows",
+    "render_human",
+    "response_format",
+    "__version__",
+]

marquee_ai-1.0.0/marquee/api.py

@@ -0,0 +1,386 @@
+"""Marquee HTTP API.
+
+What a media server actually talks to. Wraps the retriever, the prompt contract and
+the model behind one endpoint:
+
+    POST /recommend  {"seed_id": "myserver-04471", "row_size": 20}
+    -> {"rows": [{"type", "title", "items": [{"id", "title", "owned", ...}]}]}
+
+The model runs behind any OpenAI-compatible endpoint -- Ollama is the expected one
+for self-hosters:
+
+    ollama serve
+    uvicorn serve.api:app --host 0.0.0.0 --port 8080
+
+Config via environment:
+    MARQUEE_LIBRARY   path to the library JSONL from data/ingest.py   (required)
+    MARQUEE_MODEL     model name                    (default curator-4b)
+    MARQUEE_BASE_URL  OpenAI-compatible endpoint    (default http://localhost:11434/v1)
+    MARQUEE_EMB_CACHE embedding cache path          (default alongside the library)
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections import OrderedDict
+from pathlib import Path
+
+import requests
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+
+from .retriever import Library
+from .contract import (
+    CONTRACT_VERSION,
+    ValidationError,
+    expand_rows,
+    messages,
+    parse,
+    repair,
+    response_format,
+    verify_model,
+)
+
+# Recommendations for an item are stable until the library changes, so serving the
+# same seed twice should never cost a second model call. This is the single biggest
+# latency win available without retraining.
+CACHE_SIZE = int(os.environ.get("MARQUEE_CACHE_SIZE", "2048"))
+
+LIBRARY_PATH = os.environ.get("MARQUEE_LIBRARY", "")
+MODEL = os.environ.get("MARQUEE_MODEL", "marquee-4b")
+BASE_URL = os.environ.get("MARQUEE_BASE_URL", "http://localhost:11434/v1")
+
+app = FastAPI(title="Marquee", version="1.0")
+_lib: Library | None = None
+_cache: "OrderedDict[tuple, dict]" = OrderedDict()
+_hits = _misses = 0
+_verified: tuple[bool, str] | None = None
+
+
+def _raw_call(msgs: list[dict]) -> str:
+    """Model call with NO grammar, used by the self-test."""
+    resp = requests.post(
+        BASE_URL.rstrip("/") + "/chat/completions",
+        json={"model": MODEL, "messages": msgs, "temperature": 0.1, "max_tokens": 1700},
+        timeout=180,
+    )
+    resp.raise_for_status()
+    return resp.json()["choices"][0]["message"]["content"]
+
+
+@app.on_event("startup")
+def _startup_selftest() -> None:
+    """Fail loudly at boot rather than serving quietly wrong rows.
+
+    Uses a real item from the loaded library: a synthetic probe is far enough out of
+    distribution that a healthy model can fail it.
+    """
+    global _verified
+    try:
+        lib = library()
+        seed = max(lib.items, key=lambda i: i.popularity)
+        probe = lib.build_request(seed.id, semantic_k=10)
+    except Exception as exc:  # noqa: BLE001
+        _verified = (False, f"could not build a probe request: {exc}")
+    else:
+        _verified = verify_model(_raw_call, probe)
+    ok, msg = _verified
+    print(f"[marquee] contract v{CONTRACT_VERSION} self-test: "
+          f"{'PASS' if ok else 'FAIL'} - {msg}")
+
+
+class RecommendRequest(BaseModel):
+    seed_id: str | None = Field(None, description="library id -- always unambiguous, prefer this")
+    title: str | None = Field(None, description="fallback lookup when you have no id")
+    year: int | None = Field(None, description="disambiguates remakes when matching by title")
+    media_type: str | None = Field(None, description="movie | tv, to narrow a title match")
+    row_size: int = Field(0, ge=0, le=50, description="top rows up to N items; 0 = model's own")
+    owned_only: bool = Field(False, description="hide items not on this server")
+    semantic_k: int = Field(14, ge=4, le=40)
+
+
+class Item(BaseModel):
+    id: str
+    title: str
+    owned: bool = True
+    media_type: str = ""
+    year: int | None = None
+    rating: float = 0.0
+
+
+class Row(BaseModel):
+    type: str
+    title: str
+    items: list[Item]
+
+
+class RecommendResponse(BaseModel):
+    seed: Item
+    rows: list[Row]
+
+
+def library() -> Library:
+    global _lib
+    if _lib is None:
+        if not LIBRARY_PATH:
+            raise HTTPException(500, "MARQUEE_LIBRARY is not set")
+        path = Path(LIBRARY_PATH)
+        if not path.exists():
+            raise HTTPException(500, f"library not found: {path}")
+        lib = Library.load(path)
+        cache = Path(os.environ.get("MARQUEE_EMB_CACHE", path.with_suffix(".emb.npz")))
+        lib.build_embeddings(cache=cache)
+        _lib = lib
+    return _lib
+
+
+def _call_model(msgs: list[dict]) -> str:
+    resp = requests.post(
+        BASE_URL.rstrip("/") + "/chat/completions",
+        json={
+            "model": MODEL,
+            "messages": msgs,
+            "temperature": 0.1,
+            "max_tokens": 1700,
+            "response_format": response_format(),
+        },
+        timeout=180,
+    )
+    if not resp.ok:
+        raise HTTPException(502, f"model backend {resp.status_code}: {resp.text[:200]}")
+    return resp.json()["choices"][0]["message"]["content"]
+
+
+@app.get("/health")
+def health() -> dict:
+    lib = library()
+    owned = sum(1 for i in lib.items if i.owned)
+    ok, msg = _verified or (None, "not run")
+    return {
+        "status": "ok" if ok else "degraded",
+        "contract_version": CONTRACT_VERSION,
+        "model_self_test": {"passed": ok, "detail": msg},
+        "cache": {"entries": len(_cache), "hits": _hits, "misses": _misses,
+                  "max": CACHE_SIZE},
+        "library_items": len(lib.items),
+        "owned": owned,
+        "requestable": len(lib.items) - owned,
+        "model": MODEL,
+        "backend": BASE_URL,
+    }
+
+
+def split_title_year(text: str) -> tuple[str, int | None]:
+    """Accept "Top Gun (1986)" as well as a bare title.
+
+    Writing the year in parentheses is how people habitually disambiguate remakes,
+    so treat it as the year filter rather than as part of the title to match.
+    """
+    m = re.search(r"^(.*?)\s*\((\d{4})\)\s*$", text.strip())
+    if m:
+        return m.group(1).strip(), int(m.group(2))
+    return text.strip(), None
+
+
+def _find(lib: Library, title: str, year: int | None, media_type: str | None) -> list:
+    """Title lookup, narrowed by year and media type when given.
+
+    Exact title matches win outright: searching "Dune" should not also return
+    "Dune: Part Two" when an exact "Dune" exists.
+    """
+    title_text, inline_year = split_title_year(title)
+    year = year if year is not None else inline_year
+    q = title_text.lower()
+    pool = [i for i in lib.items if q in i.title.lower()]
+    exact = [i for i in pool if i.title.lower() == q]
+    if exact:
+        pool = exact
+    if year is not None:
+        pool = [i for i in pool if i.year == year]
+    if media_type:
+        pool = [i for i in pool if i.media_type == media_type]
+    return sorted(pool, key=lambda i: -i.popularity)
+
+
+@app.get("/search")
+def search(
+    q: str,
+    media_type: str | None = None,
+    kind: str = "all",
+    limit: int = 20,
+) -> dict:
+    """Search titles and people.
+
+    `kind` is "title", "person" or "all". A query like "Scorsese" matches no title but
+    plenty of credits, so searching both by default is what a user actually expects.
+    """
+    lib = library()
+    out: dict = {"query": q, "titles": [], "people": []}
+
+    if kind in ("title", "all"):
+        out["titles"] = [
+            {"id": i.id, "title": i.title, "year": i.year, "media_type": i.media_type,
+             "rating": round(i.rating, 1), "owned": i.owned}
+            for i in _find(lib, q, None, media_type)[:limit]
+        ]
+    if kind in ("person", "all"):
+        out["people"] = lib.find_people(q, limit=limit)
+
+    out["count"] = len(out["titles"]) + len(out["people"])
+    return out
+
+
+@app.get("/person")
+def person(
+    key: str | None = None,
+    name: str | None = None,
+    media_type: str | None = None,
+    owned_only: bool = False,
+    limit: int = 40,
+    by_role: bool = False,
+) -> dict:
+    """Everything a person is credited on.
+
+    Films and shows in one rating-ranked list by default, deduplicated across roles.
+    `by_role=true` splits it into per-role shelves instead.
+
+    No model call: this is a pure index lookup, so it is effectively instant.
+    """
+    lib = library()
+    if not key:
+        if not name:
+            raise HTTPException(400, "provide key or name")
+        hits = lib.find_people(name, limit=5)
+        if not hits:
+            raise HTTPException(404, f"no person matching {name!r}")
+        if len(hits) > 1 and hits[0]["name"].lower() != name.strip().lower():
+            raise HTTPException(409, {"error": "ambiguous name", "matches": hits})
+        key = hits[0]["key"]
+
+    if not by_role:
+        credits = lib.person_credits(key, limit=limit, media_type=media_type,
+                                     owned_only=owned_only)
+        if not credits:
+            raise HTTPException(404, f"no credits for {key!r}")
+        return {
+            "person": lib.person_names.get(key, key),
+            "count": len(credits),
+            "credits": credits,
+        }
+
+    rows = lib.person_rows(key, max_per_row=limit, media_type=media_type,
+                           owned_only=owned_only)
+    if not rows:
+        raise HTTPException(404, f"no credits for {key!r}")
+
+    titles = {
+        "director": "Directed by {name}", "author": "Written by {name}",
+        "actor": "Starring {name}", "writer": "Written by {name}",
+        "cinematographer": "Shot by {name}", "composer": "Scored by {name}",
+        "narrator": "Narrated by {name}",
+    }
+    return {
+        "person": lib.person_names.get(key, key),
+        "rows": [
+            {
+                "role": r["role"],
+                "title": titles.get(r["role"], "{name}").format(name=r["anchor"]),
+                "items": [
+                    {"id": i, "title": lib.by_id[i].title, "year": lib.by_id[i].year,
+                     "media_type": lib.by_id[i].media_type,
+                     "rating": round(lib.by_id[i].rating, 1),
+                     "owned": lib.by_id[i].owned}
+                    for i in r["items"]
+                ],
+            }
+            for r in rows
+        ],
+    }
+
+
+@app.delete("/cache")
+def clear_cache() -> dict:
+    """Call this after a library rescan -- cached rows go stale when items change."""
+    n = len(_cache)
+    _cache.clear()
+    return {"cleared": n}
+
+
+@app.post("/recommend", response_model=RecommendResponse)
+def recommend(req: RecommendRequest) -> RecommendResponse:
+    global _hits, _misses
+    lib = library()
+
+    if req.seed_id:
+        if req.seed_id not in lib.by_id:
+            raise HTTPException(404, f"no library item with id {req.seed_id!r}")
+        seed = lib.by_id[req.seed_id]
+    elif req.title:
+        matches = _find(lib, req.title, req.year, req.media_type)
+        if not matches:
+            raise HTTPException(404, f"no library item matching {req.title!r}")
+        # 2.2% of titles collide (remakes, and occasional duplicate catalog entries).
+        # Guessing by popularity silently returns the wrong film, so say so instead
+        # and let the caller pick -- /search exists for exactly this.
+        if len(matches) > 1:
+            raise HTTPException(
+                409,
+                {
+                    "error": f"{len(matches)} items match {req.title!r}; pass seed_id, "
+                             "or narrow with year/media_type",
+                    "matches": [
+                        {"id": m.id, "title": m.title, "year": m.year,
+                         "media_type": m.media_type}
+                        for m in matches[:10]
+                    ],
+                },
+            )
+        seed = matches[0]
+    else:
+        raise HTTPException(400, "provide seed_id or title")
+
+    key = (seed.id, req.row_size, req.owned_only, req.semantic_k)
+    if key in _cache:
+        _cache.move_to_end(key)
+        _hits += 1
+        return RecommendResponse(**_cache[key])
+    _misses += 1
+
+    request = lib.build_request(
+        seed.id,
+        semantic_k=req.semantic_k,
+        row_size=req.row_size,
+        owned_only=req.owned_only,
+    )
+
+    try:
+        response = parse(_call_model(messages(request)))
+    except ValidationError as exc:
+        raise HTTPException(502, f"model returned unusable output: {exc}") from exc
+
+    # Repair before serving: the same normalisation used to build the training data,
+    # so a stray row never reaches the client.
+    response = repair(response, request)
+    if req.row_size:
+        response = expand_rows(response, request, req.row_size)
+
+    def as_item(item_id: str) -> Item:
+        it = lib.by_id[item_id]
+        return Item(
+            id=it.id, title=it.title, owned=it.owned,
+            media_type=it.media_type, year=it.year, rating=round(it.rating, 1),
+        )
+
+    result = RecommendResponse(
+        seed=as_item(seed.id),
+        rows=[
+            Row(type=r["type"], title=r["title"], items=[as_item(i) for i in r["items"]])
+            for r in response.get("rows", [])
+        ],
+    )
+
+    _cache[key] = result.model_dump()
+    while len(_cache) > CACHE_SIZE:
+        _cache.popitem(last=False)
+    return result