find_similar
Read-only
Find archived scenes that look like the acquisition at url.
This is the one search that lives in the pixels, not the metadata: where
``search_catalog`` filters by date/bbox/task-name, this renders the query
item's quicklook, embeds it, and ranks the pre-embedded scene index by visual
(cosine) similarity — "find scenes that look like this flooded field / crowded
berth / runway". The query item is excluded from its own results.
Requires a scene-embedding index built ahead of time with ``umbra embed
build`` (a sidecar ``catalog.embed.db`` beside the catalog index) and a
user-supplied multimodal embedding key (``OPENAI_API_KEY``, optionally
``OPENAI_BASE_URL`` / ``UMBRA_SCENE_EMBED_MODEL``) — the only model call is
turning the query image into a vector; ranking is deterministic. ``asset``
picks which product's quicklook to embed (default ``GEC``; match how the index
was built); ``model`` must match the index's embedding model. Returns the
ranked matches as compact records (each with the acquisition's ``href``, so
hand it to ``get_item`` / ``quicklook`` / ``change_composite`` next) plus the
attribution line.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| asset | No | GEC | |
| model | No | ||
| top_k | No | ||
| min_score | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||