Update SETUP.md: Q6_K specs, quantization-sensitivity troubleshooting note

SETUP.md

@@ -18,7 +18,7 @@ cd marquee
 ollama create marquee -f Modelfile
 ```
 
-~2.8 GB: the model, plus a catalog of ~122,000 films and shows with full cast and crew.
+~3 GB: the model, plus a catalog of ~195,000 films and shows with full cast and crew.
 
 ## Run
 
@@ -28,36 +28,6 @@ marquee serve --library catalog.jsonl --port 8080
 
 Loads in about 15 seconds.
 
-## Use it
-
-```bash
-curl -X POST localhost:8080/recommend \
-  -H 'Content-Type: application/json' \
-  -d '{"title": "The Sopranos", "row_size": 20}'
-```
-
-```
-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
-```
-
-Or from the command line:
-
-```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
-export MARQUEE_LIBRARY=$PWD/catalog.jsonl
-export MARQUEE_MODEL=marquee
-marquee recommend --seed "Dune (2021)"
-```
-
 ## API
 
 ### `POST /recommend`
@@ -69,131 +39,110 @@ curl -X POST localhost:8080/recommend -H 'Content-Type: application/json' \
 
 ```json
 {
-  "seed": {"id": "tmdb:tv:1398", "title": "The Sopranos", "year": 1999,
-           "media_type": "tv", "rating": 8.7, "owned": true},
+  "seed": {"id": "wd:Q23628", "title": "The Sopranos", "year": 1999,
+           "media_type": "tv", "rating": 0.0, "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}
+       {"id": "wd:Q...", "title": "Gomorrah", "year": 2014,
+        "media_type": "tv", "owned": true},
+       {"id": "wd:Q...", "title": "Boardwalk Empire", "year": 2010,
+        "media_type": "tv", "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}
+       {"id": "wd:Q...", "title": "Game of Thrones", "year": 2011,
+        "media_type": "tv", "owned": true}
      ]}
   ]
 }
 ```
 
-Body fields: `seed_id` **or** `title`, plus optional `year`, `media_type`, `row_size`
-(items per row), `owned_only`, `semantic_k`.
-
-Rows arrive in a fixed order — thematic, franchise, director, cast, crew — so a UI can
-render them top to bottom without sorting.
+Body: `seed_id` **or** `title`, plus optional `year`, `media_type`, `row_size`,
+`owned_only`, `semantic_k`. Rows arrive in a fixed order -- thematic, franchise,
+director, cast, crew.
 
-An ambiguous title returns **409** with the candidates rather than guessing:
+An ambiguous title returns **409** with the candidates rather than guessing. A catalog
+this size holds many remakes sharing a bare title:
 
 ```json
-{"error": "5 items match 'Godzilla'; pass seed_id, or narrow with year/media_type",
+{"error": "22 items match 'Macbeth'; 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"}
+   {"id": "wd:Q15934383", "title": "Macbeth", "year": 2015, "media_type": "movie"},
+   {"id": "wd:Q2573008",  "title": "Macbeth", "year": 1951, "media_type": "movie"}
  ]}
 ```
 
-`{"title": "Godzilla", "year": 2014}` or `{"title": "Godzilla (2014)"}` resolves it.
+`{"title": "Macbeth", "year": 2015}` or `{"title": "Macbeth (2015)"}` resolves it.
 
-### `GET /search?q=`
+### `GET /metadata` and `POST /metadata/batch`
 
-Matches titles **and** people, because "Scorsese" is not a title but has 109 credits.
+Full catalog record for one item, or up to 500 in one call. Pure index lookups -- no
+model, no GPU. Look up by `id`, `tmdb_id`, `imdb_id` (all exact), or `title` (fuzzy,
+can be ambiguous like `/recommend`).
 
 ```bash
-curl 'localhost:8080/search?q=Scorsese&limit=3'
+curl 'localhost:8080/metadata?tmdb_id=335984'
 ```
 
 ```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
+  "id": "wd:Q21500755", "title": "Blade Runner 2049", "media_type": "movie",
+  "year": 2017, "genres": ["cyberpunk", "dystopian film", "neo-noir"],
+  "people": [{"name": "Denis Villeneuve", "role": "director"},
+             {"name": "Roger Deakins", "role": "cinematographer"}],
+  "summary": "Blade Runner 2049 is a 2017 American science fiction film...",
+  "franchise": "Blade Runner", "runtime_min": 164,
+  "country": "United Kingdom", "language": "English",
+  "external": {"wikidata": "Q21500755", "tmdb": "335984", "imdb": "tt1856101"}
 }
 ```
 
-`kind=title` or `kind=person` narrows it. Names are matched loosely: `samuel l jackson`,
-`Jackson Samuel` and `Inarritu` all resolve.
+```bash
+curl -X POST localhost:8080/metadata/batch -H 'Content-Type: application/json' -d '{
+  "queries": [{"tmdb_id": 335984}, {"imdb_id": "tt0141842"}]
+}'
+```
+
+Every query gets a result in the order sent -- found, ambiguous with candidates, or
+not found -- so you can zip the response against your input.
 
-### `GET /person?name=`
+### `GET /search?q=` and `GET /person?name=`
 
-Everything someone is credited on, films and shows in one list, best first.
+`/search` matches titles **and** people in one call -- "Scorsese" isn't a title but has
+109 credits. `/person` returns everything someone worked on, films and shows together,
+ranked by a popularity-weighted score, deduplicated across roles. Both are index
+lookups, no model call.
 
 ```bash
 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"]}
-  ]
-}
+{"person": "Roger Deakins", "count": 3, "credits": [
+  {"id": "wd:...", "title": "The Shawshank Redemption", "year": 1994,
+   "score": 8.66, "roles": ["cinematographer"]}
+]}
 ```
 
-`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.
+`score` is what ranking actually uses -- popularity-weighted, so a well-known film
+outranks an obscure one even without a raw rating to sort by.
 
-Options: `media_type`, `owned_only`, `limit`, `by_role=true` for per-role shelves.
-
-### `GET /health`
+### `GET /health` and `DELETE /cache`
 
 ```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"
-}
+{"status": "ok", "contract_version": 1,
+ "model_self_test": {"passed": true, "detail": "contract v1 OK (3/3 clean)"},
+ "library_items": 194509, "owned": 194509, "requestable": 0}
 ```
 
-`status` is `degraded` if the self-test fails — the model and package disagree, or the
-chat template is wrong.
-
-### `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.
+`status` is `degraded` if the self-test fails -- model and package disagree, or the
+chat template is wrong. Recommendations are cached per seed; call `DELETE /cache`
+after a library rescan or you'll serve rows referring to items you no longer have.
 
 ## Restricting results to your own library (optional)
 
-By default it recommends from the whole 122k catalog, whether or not you own the title.
+By default it recommends from the whole 195k-title catalog, whether or not you own it.
 
 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:
@@ -221,7 +170,7 @@ curl -X POST localhost:8080/recommend -H 'Content-Type: application/json' \
 `/health` reports the split:
 
 ```json
-{"library_items": 121727, "owned": 1670, "requestable": 120057}
+{"library_items": 194509, "owned": 1670, "requestable": 192839}
 ```
 
 **Jellyfin**: `/Items?Recursive=true&Fields=ProviderIds` gives `ProviderIds.Tmdb`.
@@ -231,9 +180,9 @@ curl -X POST localhost:8080/recommend -H 'Content-Type: application/json' \
 
 | | |
 |---|---|
-| 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 |
+| VRAM | ~4.7 GB (Q6_K at 6144 context). A 6 GB card is fine; CPU works but is slower. |
+| RAM | ~2.5 GB for the 195k-title catalog |
+| Disk | ~3.6 GB |
 | Latency | ~1 s per request on an RTX 3060; cached responses are instant |
 
 ## Troubleshooting
@@ -247,22 +196,30 @@ 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. The Modelfile ships 0.1.
+Two independent causes, both already fixed in the shipped model/Modelfile:
+- `temperature` too high -- structured output needs near-greedy decoding. 0.1 gave 8/8
+  clean in testing, 0.3 gave 5/8. The Modelfile ships 0.1.
+- Quantizing below Q6_K measurably hurts this model: on 20 held-out seeds through real
+  Ollama serving, Q4_K_M gave 1/20 clean vs Q6_K's 19/20, same weights, same decoding --
+  llama.cpp's 4-bit rounding alone is enough to collapse it into repeating
+  `<tool_call>` tokens instead of JSON. Don't requantize to Q4_K_M to save disk space.
 
 **Self-test fails at startup.**
 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.
+The catalog covers ~195k titles from Wikidata. Genuinely obscure releases may not be
+there. `marquee harvest-wikidata --min-votes 0` (if rebuilding) widens coverage.
 
 ## Data
 
-Catalog metadata is from TMDB. This product uses the TMDB API but is not endorsed or
-certified by TMDB.
+The catalog is built from Wikidata (CC0) and Wikipedia (summaries, embedded then
+discarded -- never redistributed as text). No TMDB data is shipped.
+
+No poster/image URLs are included -- text and structured facts only. Pull artwork
+from your media server, or from TMDB/Fanart yourself using the `external.tmdb`/
+`external.imdb` ids returned by `/metadata`.
 
 ## Licence