real API examples, plug-and-play quickstart

SETUP.md

@@ -1,183 +1,269 @@
-# Running Marquee on your own server
+# Marquee
 
-**Marquee-4B v1.0**
+Recommendation rows for a media server.
 
-Complete setup, start to finish. Roughly an hour, most of it unattended.
-
-## What you are building
+## Install
 
+```bash
+pip install marquee-ai
 ```
-  your media server
-        |  exports {id, tmdb_id, media_type}
-        v
-   marquee ingest ------> library index (titles, cast, crew, embeddings)
-        |
-        v
-   marquee serve  <-----> Ollama (the model)
-        |  HTTP
-        v
-  your media server UI
+
+You also need [Ollama](https://ollama.com) to run the model.
+
+## Download
+
+```bash
+hf download KernelMedia/marquee-ai --local-dir marquee
+cd marquee
+ollama create marquee -f Modelfile
 ```
 
-The model decides which rows to show and names them. The **retriever** — the index —
-decides what goes in them. Both matter; the model on its own is not useful.
+~2.8 GB: the model, plus a catalog of ~122,000 films and shows with full cast and crew.
 
-## 1. Install
+## Run
 
 ```bash
-pip install marquee-ai
-curl -fsSL https://ollama.com/install.sh | sh      # if you do not have it
+marquee serve --library catalog.jsonl --port 8080
 ```
 
-## 2. Get the model
+Loads in about 15 seconds.
+
+## Use it
 
 ```bash
-huggingface-cli download KernelMedia/marquee-ai --local-dir marquee-model
-cd marquee-model && ollama create marquee -f Modelfile && cd ..
+curl -X POST localhost:8080/recommend \
+  -H 'Content-Type: application/json' \
+  -d '{"title": "The Sopranos", "row_size": 20}'
 ```
 
-Do not edit the `Modelfile`'s `TEMPLATE` block or raise `temperature`. Both are
-load-bearing — see Troubleshooting.
+```
+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
+```
 
-## 3. Get a TMDB key
+Or from the command line:
 
-Free, two minutes: https://www.themoviedb.org/settings/api — choose Developer,
-non-commercial.
+```bash
+marquee recommend --library catalog.jsonl --seed "Blade Runner 2049" --row-size 20
+marquee person  --library catalog.jsonl --name "Roger Deakins"
+```
+
+Set `MARQUEE_LIBRARY` once and drop the flag:
 
 ```bash
-echo 'TMDB_API_KEY=your_key' >> .env
+export MARQUEE_LIBRARY=$PWD/catalog.jsonl
+export MARQUEE_MODEL=marquee
+marquee recommend --seed "Dune (2021)"
 ```
 
-TMDB is free for non-commercial use and requires attribution. **Commercial use needs a
-written agreement with TMDB** — if you charge for access to this, talk to them first.
+## API
 
-## 4. Harvest metadata
+### `POST /recommend`
 
 ```bash
-marquee harvest --out tmdb_full.jsonl
+curl -X POST localhost:8080/recommend -H 'Content-Type: application/json' \
+  -d '{"title": "The Sopranos", "row_size": 20}'
 ```
 
-~55 minutes, ~120,000 titles, ~210 MB. It caches every response, so re-runs are free
-and an interrupted run resumes.
-
-This keeps titles with 10+ votes (plus all anime regardless, which skews to low vote
-counts). That drops TMDB's 1.4M entries to ~120k by removing shorts, unreleased stubs
-and uploads with no credits — none of which can form a recommendation row anyway.
+```json
+{
+  "seed": {"id": "tmdb:tv:1398", "title": "The Sopranos", "year": 1999,
+           "media_type": "tv", "rating": 8.7, "owned": true},
+  "rows": [
+    {"type": "thematic", "title": "Shows like The Sopranos",
+     "items": [
+       {"id": "tmdb:tv:31050", "title": "The Last Don", "year": 1997,
+        "media_type": "tv", "rating": 7.1, "owned": true},
+       {"id": "tmdb:tv:12822", "title": "The Octopus", "year": 1984,
+        "media_type": "tv", "rating": 7.8, "owned": true}
+     ]},
+    {"type": "director", "title": "More from Tim Van Patten",
+     "items": [
+       {"id": "tmdb:tv:1399", "title": "Game of Thrones", "year": 2011,
+        "media_type": "tv", "rating": 8.5, "owned": true},
+       {"id": "tmdb:tv:1438", "title": "The Wire", "year": 2002,
+        "media_type": "tv", "rating": 8.6, "owned": true}
+     ]}
+  ]
+}
+```
 
-`--min-votes 0` takes everything: 1.4M titles, ~10 hours, ~108 GB of cache, and about
-27 GB of RAM to load. Not advised.
+Body fields: `seed_id` **or** `title`, plus optional `year`, `media_type`, `row_size`
+(items per row), `owned_only`, `semantic_k`.
 
-## 5. Export your library
+Rows arrive in a fixed order — thematic, franchise, director, cast, crew — so a UI can
+render them top to bottom without sorting.
 
-One JSON object per line. Only `tmdb_id` and `media_type` are required:
+An ambiguous title returns **409** with the candidates rather than guessing:
 
 ```json
-{"id": "myserver-04471", "tmdb_id": 335984, "media_type": "movie"}
-{"id": "myserver-04472", "tmdb_id": 1396, "media_type": "tv"}
+{"error": "5 items match 'Godzilla'; pass seed_id, or narrow with year/media_type",
+ "matches": [
+   {"id": "tmdb:movie:124905", "title": "Godzilla", "year": 2014, "media_type": "movie"},
+   {"id": "tmdb:movie:929",    "title": "Godzilla", "year": 1998, "media_type": "movie"},
+   {"id": "tmdb:movie:1678",   "title": "Godzilla", "year": 1954, "media_type": "movie"}
+ ]}
 ```
 
-Include `id` and recommendations come back keyed the way your server already refers to
-things, so you need no lookup table.
+`{"title": "Godzilla", "year": 2014}` or `{"title": "Godzilla (2014)"}` resolves it.
 
-**Jellyfin**: `/Items?Recursive=true&Fields=ProviderIds` gives `ProviderIds.Tmdb`.
-**Plex**: `/library/sections/{id}/all` — the `guid` field carries the TMDB id on
-recent agents.
+### `GET /search?q=`
 
-## 6. Build the library index
+Matches titles **and** people, because "Scorsese" is not a title but has 109 credits.
 
 ```bash
-marquee ingest --server library.jsonl --catalog tmdb_full.jsonl \
-                --out lib.jsonl --mode requestable
+curl 'localhost:8080/search?q=Scorsese&limit=3'
 ```
 
-| mode | contents |
-|---|---|
-| `owned` | only what is on your server — every recommendation is playable |
-| `requestable` | your items **plus** unowned titles flagged `owned: false`, so the UI can offer a Request button |
+```json
+{
+  "query": "Scorsese",
+  "titles": [
+    {"id": "tmdb:tv:292130", "title": "Mr. Scorsese", "year": 2025,
+     "media_type": "tv", "rating": 8.1, "owned": true}
+  ],
+  "people": [
+    {"key": "tmdb:person:1032", "name": "Martin Scorsese",
+     "roles": {"director": 47, "actor": 50, "writer": 12}, "credits": 109}
+  ],
+  "count": 6
+}
+```
 
-`requestable` plus `owned_only` at query time is the flexible setup: one index serves
-both, and you can flip per user.
+`kind=title` or `kind=person` narrows it. Names are matched loosely: `samuel l jackson`,
+`Jackson Samuel` and `Inarritu` all resolve.
 
-Anything whose `tmdb_id` is not in the harvest is fetched from TMDB on the spot, so
-coverage is complete however you filtered. `--no-fetch` disables that.
+### `GET /person?name=`
 
-## 7. Serve
+Everything someone is credited on, films and shows in one list, best first.
 
 ```bash
-marquee serve --library lib.jsonl --model marquee --port 8080
+curl 'localhost:8080/person?name=Roger%20Deakins&limit=3'
+```
+
+```json
+{
+  "person": "Roger Deakins",
+  "count": 3,
+  "credits": [
+    {"id": "tmdb:movie:278", "title": "The Shawshank Redemption", "year": 1994,
+     "media_type": "movie", "rating": 8.7, "score": 8.66, "votes": 31061,
+     "owned": true, "roles": ["cinematographer"]},
+    {"id": "tmdb:movie:146233", "title": "Prisoners", "year": 2013,
+     "media_type": "movie", "rating": 8.1, "score": 8.04, "votes": 13352,
+     "owned": true, "roles": ["cinematographer"]}
+  ]
+}
 ```
 
-First start builds embeddings (~3 min for 120k titles) and caches them next to the
-library. Later starts take ~15 s.
+`score` is what the ranking uses: the raw rating damped toward the catalog mean by vote
+count, so an 8.2 from 600 votes sits below a 7.6 from 4,300. Someone who both directed
+and wrote a title appears once with both roles.
 
-Watch for the startup line:
+Options: `media_type`, `owned_only`, `limit`, `by_role=true` for per-role shelves.
 
-```
-[marquee] contract v1 self-test: PASS - contract v1 OK (3/3 clean)
+### `GET /health`
+
+```json
+{
+  "status": "ok",
+  "contract_version": 1,
+  "model_self_test": {"passed": true, "detail": "contract v1 OK (3/3 clean)"},
+  "cache": {"entries": 0, "hits": 0, "misses": 0, "max": 2048},
+  "library_items": 121727,
+  "owned": 121727,
+  "requestable": 0,
+  "model": "marquee",
+  "backend": "http://localhost:11434/v1"
+}
 ```
 
-FAIL means the model and the package disagree, or the chat template is wrong. It will
-say which.
+`status` is `degraded` if the self-test fails — the model and package disagree, or the
+chat template is wrong.
 
-## API
+### `DELETE /cache`
+
+Responses are cached per seed. Call this after a library rescan or you will serve rows
+referring to items you no longer have.
+
+`/search` and `/person` are index lookups with no model call, so they are instant. Only
+`/recommend` uses the GPU.
+
+## Restricting results to your own library (optional)
+
+By default it recommends from the whole 122k catalog, whether or not you own the title.
+
+To mark what is actually on your server -- so a UI can show a Request button on the rest
+-- export your library and join it:
 
 ```bash
-curl -X POST localhost:8080/recommend \
-  -H 'Content-Type: application/json' \
-  -d '{"seed_id": "myserver-04471", "row_size": 20}'
+marquee ingest --server library.jsonl --catalog catalog.jsonl \
+               --out lib.jsonl --mode requestable
+marquee serve --library lib.jsonl
+```
+
+Your export needs one JSON object per line; `tmdb_id` and `media_type` are enough:
 
-curl 'localhost:8080/search?q=Scorsese'         # titles and people
-curl 'localhost:8080/person?name=Roger+Deakins'
-curl localhost:8080/health
-curl -X DELETE localhost:8080/cache             # after a library rescan
+```json
+{"id": "myserver-04471", "tmdb_id": 335984, "media_type": "movie"}
 ```
 
-`/recommend` takes `seed_id` (exact) or `title`. 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.
+Every item then carries `"owned": true|false`. Pass `"owned_only": true` on a request to
+drop the ones you do not have:
 
-`/search` and `/person` are index lookups with no model call, so they are instant. Only
-`/recommend` uses the GPU.
+```bash
+curl -X POST localhost:8080/recommend -H 'Content-Type: application/json' \
+  -d '{"seed_id": "myserver-04471", "row_size": 20, "owned_only": true}'
+```
+
+`/health` reports the split:
 
-### Caching
+```json
+{"library_items": 121727, "owned": 1670, "requestable": 120057}
+```
 
-Recommendations for an item are stable until the library changes, so they are cached.
-`/health` reports hits and misses. **Call `DELETE /cache` after a rescan** or you will
-serve rows referring to items you no longer have.
+**Jellyfin**: `/Items?Recursive=true&Fields=ProviderIds` gives `ProviderIds.Tmdb`.
+**Plex**: `/library/sections/{id}/all` -- the `guid` carries the TMDB id on recent agents.
 
-## Hardware
+## Requirements
 
 | | |
 |---|---|
-| VRAM | ~3.5 GB. A 4 GB card is fine. CPU works but is slow — cache matters more there. |
-| RAM | ~2.2 GB for a 120k catalog |
-| Disk | 2.4 GB model, ~210 MB catalog, ~190 MB embeddings, ~2.6 GB API cache |
+| VRAM | ~3.5 GB. A 4 GB card is fine; CPU works but is slower. |
+| RAM | ~2.2 GB for the 122k catalog |
+| Disk | ~2.8 GB |
+| Latency | ~1 s per request on an RTX 3060; cached responses are instant |
 
 ## Troubleshooting
 
 **Every row comes back typed `director`, titles look like item names.**
-The chat template is missing. Ollama ignores the Jinja template inside GGUF and falls
-back to a raw passthrough, so the model never sees the `<|im_start|>` markers it was
-trained on. Confirm your Modelfile has the `TEMPLATE` block:
+The chat template is missing. Ollama ignores the template inside GGUF metadata and falls
+back to a raw passthrough, so the model never sees the tokens it was trained on:
 ```bash
 ollama show --template marquee     # must NOT be just "{{ .Prompt }}"
 ```
+Recreate from the supplied `Modelfile`, and do not remove its `TEMPLATE` block.
 
 **Output is valid sometimes and not others.**
 `temperature` is too high. Structured output needs near-greedy decoding: 0.1 gave 8/8
-clean in testing, 0.3 gave 5/8.
+clean in testing, 0.3 gave 5/8. The Modelfile ships 0.1.
 
 **Self-test fails at startup.**
-Model and package are on different contract versions. Both must be contract v1.
+The model and the package are built against different contract versions. Both must be
+contract v1.
+
+**A title I own is missing.**
+The catalog covers ~122k titles with 10+ TMDB votes, plus all anime. Genuinely obscure
+releases may not be there. `marquee harvest --min-votes 0` rebuilds a wider catalog with
+your own free TMDB key.
 
-**Server items are being dropped at ingest.**
-They have no TMDB id, or the id is wrong. The ingest reports the count and samples. On-
-demand fetch handles anything merely missing from the harvest.
+## Data
 
-**Rows are thin, or missing entirely.**
-The library is small. A director with one other credit present gets no row — that is
-deliberate, the model is trained not to pad. Harvest more, or use `requestable` mode.
+Catalog metadata is from TMDB. This product uses the TMDB API but is not endorsed or
+certified by TMDB.
 
-## Attribution
+## Licence
 
-This product uses the TMDB API but is not endorsed or certified by TMDB.
+Apache-2.0.