Make Catalog v2 as simple to use as Catalog v1

[hanclintoclaw-pixel]

Goal

Catalog v2 should preserve what is great about Catalog v1:

• choose a game rather than an artifact;
• receive a ready-to-search catalog and its matching embedder;
• use the same embedder.embed(...) then catalog.search(...) loop;
• download once and reuse the cache;
• support offline use;
• keep manifests, releases, and deltas out of normal application code.

Constructing a Python catalog may download it. The resulting object is ready to
search.

Python

from PIL import Image
import collector_vision as cv

catalog = cv.CatalogV2("mtg")

with Image.open("card.jpg") as image:
    embedding = catalog.embedder.embed(image.convert("RGB"))

score, card_id = catalog.search(embedding, top_k=1)[0]

Load optional names, sets, languages, finishes, and peer identifiers:

catalog = cv.CatalogV2("mtg", include_metadata=True)
match = catalog.search_records(embedding, top_k=1)[0]

Open the latest locally installed feed version without network access:

catalog = cv.CatalogV2("mtg", offline=True)

Strings and Game values are accepted. Familiar v1 attributes remain available
where meaningful: embeddings, card_ids, oracle_ids, source, algo_key,
and embedder.

Browser

import {
  BrowserCatalogV2,
} from "https://hanclinto.github.io/CollectorVision/lib/collectorvision-catalog-v2.mjs";

const catalog = await BrowserCatalogV2.forGame("mtg", {
  includeMetadata: true,
});

const [[score, cardId]] = catalog.search(queryEmbedding, 1);

Update model

Normal clients read a small catalog-feed-v2.json. For each catalog it names:

• one complete base manifest;
• up to four ordered exact-base delta manifests.

The next changed release becomes a fresh base after four deltas. Every release
still contains a complete snapshot, so explicit versions and recovery never
depend on a permanent delta chain.

Current status

• CatalogV2("mtg") installs or reopens the default Scryfall catalog.
• include_metadata=True enables rich records without changing search().
• offline=True reopens the latest locally installed feed version.
• Feed, manifest, index, and asset checksums are verified.
• Exact-base deltas and full-snapshot fallback are automatic.
• V1-compatible catalog attributes are exposed.
• The browser has the same game-first API and optional IndexedDB cache.
• Catalog v1 remains unchanged and usable in parallel.

Remaining migration work

• Connect the standalone browser catalog to the existing scanner inference pipeline.
• Add optional pre-ranking filters without complicating construction.
• Add multi-game construction only if real usage requires it.

CatalogV2.load(...), CatalogV2Downloader, and CatalogV2BrowserClient
remain available for explicit local artifacts, versions, mirrors, and cache
control.